From 907d96641c0b7f155f47d5857cd6d49b4161ac6d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Jan 2026 16:40:36 +0000 Subject: [PATCH 1/2] feat: add media generation subagents for content creation Add four Claude Code command agents for coordinating media content: - media.coordinate: Coordinator that delegates to specialist agents - media.content: Blog posts, LinkedIn summaries, voice/tone guidance - media.site: Jekyll site structure, templates, publishing - media.technical: Architecture diagrams, specs, READMEs, API docs Also add supporting templates: - blog-post-planning-template.md: For announcing upcoming features - blog-post-completed-template.md: For showcasing shipped work - technical-decision-record-template.md: For documenting decisions --- .claude/commands/media.content.md | 208 +++++++++++ .claude/commands/media.coordinate.md | 157 +++++++++ .claude/commands/media.site.md | 220 ++++++++++++ .claude/commands/media.technical.md | 331 ++++++++++++++++++ .../templates/blog-post-completed-template.md | 56 +++ .../templates/blog-post-planning-template.md | 41 +++ .../technical-decision-record-template.md | 93 +++++ 7 files changed, 1106 insertions(+) create mode 100644 .claude/commands/media.content.md create mode 100644 .claude/commands/media.coordinate.md create mode 100644 .claude/commands/media.site.md create mode 100644 .claude/commands/media.technical.md create mode 100644 .specify/templates/blog-post-completed-template.md create mode 100644 .specify/templates/blog-post-planning-template.md create mode 100644 .specify/templates/technical-decision-record-template.md diff --git a/.claude/commands/media.content.md b/.claude/commands/media.content.md new file mode 100644 index 00000000..5587aa78 --- /dev/null +++ b/.claude/commands/media.content.md @@ -0,0 +1,208 @@ +--- +description: Generate blog posts, LinkedIn summaries, and other content with consistent voice and tone. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Overview + +The Content Specialist creates written content for external communications: +- Blog posts (planning announcements, shipped features) +- LinkedIn summaries +- Release notes +- Newsletter content + +## Voice Guidelines + +Maintain a tone that is: + +- **Confident but not arrogant**: Share achievements without overstating +- **Technical but accessible**: Balance depth for developers with clarity for stakeholders +- **Engaging but professional**: Use hooks without clickbait +- **Concise but complete**: Every word should earn its place + +### Audience + +Primary audiences to consider: +- Technical users and developers +- Project stakeholders +- Open-source community members +- Potential contributors + +## Blog Post Types + +### Planning Posts (Announcing Upcoming Work) + +Use for Monday-style announcements of upcoming features. + +**Structure**: + +```markdown +# [Feature Name]: What We're Building Next + +## What We're Building + +[2-3 paragraphs explaining the feature in accessible terms] +- Key capability 1 +- Key capability 2 +- Key capability 3 + +## How It Fits + +[1-2 paragraphs on how this connects to the broader project vision] + +## Key Decisions We're Making + +- **[Decision area 1]**: [Brief explanation of the choice and why] +- **[Decision area 2]**: [Brief explanation of the choice and why] +- **[Decision area 3]**: [Brief explanation of the choice and why] + +## We Want Your Feedback + +We're particularly interested in hearing about: +- [Specific feedback area 1] +- [Specific feedback area 2] + +[Join the discussion on GitHub →](link-to-discussion) +``` + +### Completed Posts (Showcasing Delivered Work) + +Use for Friday-style announcements of shipped features. + +**Structure**: + +```markdown +# [Feature Name]: Now Available + +## What We Built + +[2-3 paragraphs explaining what was delivered and why it matters] + +## See It In Action + +[Include 2-4 annotated screenshots or code examples] + +![Screenshot description](path/to/image.png) +*Caption explaining what the screenshot shows* + +## Lessons Learned + +During development, we discovered: + +1. **[Lesson 1]**: [Brief insight] +2. **[Lesson 2]**: [Brief insight] +3. **[Lesson 3]**: [Brief insight] + +## What's Next + +[1 paragraph pointing to upcoming work or related features] + +[Read the full documentation →](link-to-docs) +``` + +## LinkedIn Summaries + +For social media sharing: + +**Constraints**: +- 150-200 words maximum +- Open with engaging hook (not "Announcing..." or "We're excited...") +- 2-3 hashtags maximum +- Include call-to-action + +**Structure**: + +``` +[Hook - question, surprising fact, or bold statement] + +[2-3 sentences summarizing the key value] + +[1-2 sentences on impact or results] + +[Call to action with link] + +#Tag1 #Tag2 +``` + +**Example Hooks** (adapt to content): +- "What if [problem] could be solved in [fraction of time]?" +- "We spent [X weeks] on a feature that saves [Y hours]." +- "[Surprising statistic or insight from the work]" + +## Content Generation Workflow + +### Step 1: Gather Context + +Before writing, collect: + +1. **Feature information**: What was built/is being built +2. **Technical details**: Key implementation choices +3. **User value**: Why this matters to users +4. **Visuals available**: Screenshots, diagrams, demos + +### Step 2: Draft Content + +1. Choose appropriate template (planning vs completed) +2. Fill in sections with gathered context +3. Apply voice guidelines throughout +4. Keep paragraphs short (3-4 sentences max) + +### Step 3: Create Supporting Assets + +If needed: +- Suggest screenshot opportunities +- Identify diagram needs (delegate to Technical Specialist) +- Draft alt-text for images + +### Step 4: Review Checklist + +Before finalizing: + +- [ ] Hook engages without clickbait +- [ ] Technical terms are explained or linked +- [ ] All claims are accurate and verifiable +- [ ] Call-to-action is clear +- [ ] Length is appropriate for format +- [ ] Images have descriptive alt-text + +## Output Format + +```markdown +## Content Generated + +### [Content Type]: [Title] + +**Target**: [Blog/LinkedIn/Newsletter] +**Word Count**: [X words] +**Reading Time**: [X min] + +--- + +[Full content here] + +--- + +### Assets Needed +- [ ] [Screenshot/image description] +- [ ] [Diagram type if needed] + +### Suggested Tags/Categories +- Category: [planning|shipped|tutorial|announcement] +- Tags: [tag1], [tag2], [tag3] +``` + +## Quick Reference + +| Content Type | Length | Key Element | +|--------------|--------|-------------| +| Planning Post | 400-600 words | Feedback request | +| Completed Post | 500-800 words | Screenshots/demos | +| LinkedIn | 150-200 words | Hook + CTA | +| Release Notes | 200-400 words | Changelog format | diff --git a/.claude/commands/media.coordinate.md b/.claude/commands/media.coordinate.md new file mode 100644 index 00000000..117316ba --- /dev/null +++ b/.claude/commands/media.coordinate.md @@ -0,0 +1,157 @@ +--- +description: Coordinate media content generation across specialist agents for blog posts, site updates, and technical documentation. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Overview + +This coordinator manages three specialist agents for media content generation: + +1. **Content Specialist** (`/media.content`) - Blog posts, LinkedIn summaries, voice/tone +2. **Site Specialist** (`/media.site`) - Jekyll site structure, templates, styling +3. **Technical Specialist** (`/media.technical`) - Specs, architecture docs, READMEs, diagrams + +## Delegation Framework + +When receiving a request, analyze it and delegate to the appropriate specialist(s). + +### Task Classification + +| Request Type | Primary Specialist | Supporting Specialist | +|--------------|-------------------|----------------------| +| "Write a blog post about..." | Content | Technical (context) | +| "Update the site layout..." | Site | - | +| "Create architecture diagram..." | Technical | - | +| "Announce feature X..." | Content | Technical (context) → Site (publish) | +| "Document the API..." | Technical | - | +| "Add new page to site..." | Site | Content (copy) | + +## Coordination Workflow + +### Step 1: Parse Request + +Analyze the user input to determine: + +1. **Primary task type**: content, site, or technical +2. **Required specialists**: which agents needed +3. **Dependencies**: what order to execute +4. **Deliverables**: expected outputs + +### Step 2: Gather Context + +Before delegating: + +1. Check for existing related content in: + - `docs/` - existing documentation + - `specs/` - feature specifications + - `_posts/` or blog directories - existing posts + - `README.md` - project overview + +2. Extract relevant context for specialists: + - Feature names and descriptions + - Technical details needed + - Existing voice/tone from prior content + +### Step 3: Delegate Tasks + +Execute in dependency order: + +``` +Complex Request Flow: +┌─────────────────┐ +│ User Request │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Coordinator │──► Parse & classify +└────────┬────────┘ + │ + ┌────┴────┐ + │ │ + ▼ ▼ +┌───────┐ ┌───────┐ +│ Tech │ │Content│ +│Spec. │ │ Spec. │ +└───┬───┘ └───┬───┘ + │ │ + └────┬────┘ + │ + ▼ +┌─────────────────┐ +│ Site Spec. │──► Publish/integrate +└─────────────────┘ +``` + +### Step 4: Assemble Output + +Combine specialist outputs into cohesive deliverable: + +1. Verify consistency across outputs +2. Resolve any conflicts +3. Present final artifacts to user + +## Request Handling + +### For Blog Post Requests + +**Planning Posts** (announcing upcoming work): + +1. Delegate to Technical Specialist for feature context +2. Delegate to Content Specialist with context + template type "planning" +3. Optionally delegate to Site Specialist for publishing + +**Completed Posts** (showcasing delivered work): + +1. Delegate to Technical Specialist for implementation summary +2. Delegate to Content Specialist with context + template type "completed" +3. Optionally delegate to Site Specialist for publishing + +### For Documentation Requests + +1. Delegate directly to Technical Specialist +2. If user-facing docs needed, also delegate to Content Specialist for review + +### For Site Updates + +1. Delegate directly to Site Specialist +2. If content needed, first delegate to Content Specialist + +## Output Format + +After coordination, report: + +```markdown +## Media Generation Complete + +### Tasks Executed +- [x] Task 1: [description] → [specialist] +- [x] Task 2: [description] → [specialist] + +### Deliverables Created +1. **[File/artifact name]**: [brief description] + - Location: `path/to/file` + +2. **[File/artifact name]**: [brief description] + - Location: `path/to/file` + +### Next Steps (if any) +- [ ] [Action needed] +``` + +## Quick Commands + +For simple single-specialist tasks, you may invoke directly: + +- `/media.content [description]` - Content creation only +- `/media.site [description]` - Site updates only +- `/media.technical [description]` - Technical docs only + +Use this coordinator (`/media.coordinate`) for complex multi-specialist tasks. diff --git a/.claude/commands/media.site.md b/.claude/commands/media.site.md new file mode 100644 index 00000000..2246bc56 --- /dev/null +++ b/.claude/commands/media.site.md @@ -0,0 +1,220 @@ +--- +description: Manage Jekyll site structure, templates, styling, and content publishing. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Overview + +The Site Specialist manages static site infrastructure: +- Jekyll site structure and configuration +- Page templates and layouts +- Styling and theming +- Content publishing and organization +- Asset management + +## Site Architecture + +### Standard Jekyll Directory Structure + +``` +├── _config.yml # Site configuration +├── _posts/ # Blog content (YYYY-MM-DD-title.md) +├── _drafts/ # Unpublished posts +├── _layouts/ # Page templates +│ ├── default.html # Base layout +│ ├── post.html # Blog post layout +│ └── page.html # Static page layout +├── _includes/ # Reusable components +│ ├── header.html +│ ├── footer.html +│ └── nav.html +├── _sass/ # Stylesheets +│ ├── _base.scss +│ ├── _layout.scss +│ └── _components.scss +├── assets/ +│ ├── css/ +│ ├── images/ +│ └── js/ +├── _data/ # Data files (YAML, JSON) +└── pages/ # Static pages +``` + +## Content Front Matter + +### Blog Posts + +Required front matter for posts: + +```yaml +--- +layout: post +title: "Post Title Here" +date: YYYY-MM-DD HH:MM:SS +0000 +author: Author Name +category: planning|shipped|tutorial|announcement +tags: [tag1, tag2, tag3] +excerpt: "Brief description for listings and social sharing" +image: /assets/images/post-hero.png # Optional hero image +discussion_url: https://github.com/org/repo/discussions/123 # Optional +--- +``` + +### Static Pages + +```yaml +--- +layout: page +title: "Page Title" +permalink: /page-slug/ +nav_order: 1 # For navigation ordering +--- +``` + +## Site Tasks + +### Creating a New Blog Post + +1. **Generate filename**: `_posts/YYYY-MM-DD-slug-title.md` +2. **Add front matter** with all required fields +3. **Write content** using provided copy +4. **Add images** to `assets/images/posts/YYYY-MM/` +5. **Verify** markdown renders correctly + +### Adding a New Page + +1. **Create file** in `pages/` or root directory +2. **Set permalink** in front matter +3. **Update navigation** in `_data/navigation.yml` if needed +4. **Add to sitemap** if not auto-generated + +### Updating Site Styling + +1. **Locate** appropriate SCSS file in `_sass/` +2. **Make changes** following existing conventions +3. **Test** across breakpoints (mobile, tablet, desktop) +4. **Verify** no regressions in existing pages + +### Managing Assets + +**Images**: +- Store in `assets/images/` with organized subdirectories +- Use descriptive filenames: `feature-name-screenshot-01.png` +- Optimize for web (compress, appropriate dimensions) +- Always include alt text in markdown + +**Downloads**: +- Store in `assets/downloads/` +- Version files when appropriate + +## Publishing Workflow + +### Draft to Published + +1. Create post in `_drafts/` (no date prefix needed) +2. Preview with `bundle exec jekyll serve --drafts` +3. When ready, move to `_posts/` with date prefix +4. Commit and push + +### Scheduling Posts + +For future-dated posts: +1. Set `date` in front matter to future date +2. Build with `--future` flag for preview +3. Post will appear when date arrives (with proper CI/CD) + +## Configuration Reference + +### Key `_config.yml` Settings + +```yaml +title: Site Title +description: Site description for SEO +url: https://example.github.io +baseurl: /repo-name # If hosted at subdirectory + +# Build settings +markdown: kramdown +highlighter: rouge + +# Collections (if using) +collections: + docs: + output: true + permalink: /docs/:path/ + +# Defaults +defaults: + - scope: + path: "_posts" + type: posts + values: + layout: post + author: Default Author +``` + +## Output Format + +### For New Content + +```markdown +## Site Update Complete + +### Files Created/Modified + +| File | Action | Description | +|------|--------|-------------| +| `_posts/2024-01-15-feature-name.md` | Created | New blog post | +| `assets/images/posts/2024-01/hero.png` | Added | Post hero image | + +### Front Matter Used + +\`\`\`yaml +--- +layout: post +title: "..." +date: ... +--- +\`\`\` + +### Verification Steps +- [ ] Preview locally with `bundle exec jekyll serve` +- [ ] Check responsive layout +- [ ] Verify images load correctly +- [ ] Test internal links +``` + +### For Site Updates + +```markdown +## Site Structure Update + +### Changes Made +1. **[Component/file]**: [What changed] +2. **[Component/file]**: [What changed] + +### Files Modified +- `path/to/file.html` +- `path/to/style.scss` + +### Testing Required +- [ ] [Specific page/feature to test] +- [ ] [Browser/device to verify] +``` + +## Quick Reference + +| Task | Primary File | Related Files | +|------|--------------|---------------| +| New blog post | `_posts/` | `assets/images/` | +| New page | `pages/` | `_data/navigation.yml` | +| Update header | `_includes/header.html` | `_sass/_components.scss` | +| Change colors | `_sass/_variables.scss` | - | +| Add navigation | `_data/navigation.yml` | `_includes/nav.html` | diff --git a/.claude/commands/media.technical.md b/.claude/commands/media.technical.md new file mode 100644 index 00000000..90590c80 --- /dev/null +++ b/.claude/commands/media.technical.md @@ -0,0 +1,331 @@ +--- +description: Generate technical documentation including specs, architecture diagrams, READMEs, and API docs. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Overview + +The Technical Specialist creates and maintains technical documentation: +- Architecture diagrams (Mermaid syntax) +- Component/feature specifications +- README documentation +- API documentation +- Technical decision records + +## Documentation Types + +### Architecture Diagrams + +Use Mermaid syntax for GitHub-native rendering. + +**Principles**: +- One concept per diagram (don't overcrowd) +- Use consistent naming conventions +- Include legend when using custom styling +- Keep text concise in nodes + +**Common Diagram Types**: + +#### Flowcharts +```mermaid +flowchart TD + A[Start] --> B{Decision} + B -->|Yes| C[Action 1] + B -->|No| D[Action 2] + C --> E[End] + D --> E +``` + +#### Sequence Diagrams +```mermaid +sequenceDiagram + participant U as User + participant C as Component + participant S as Service + + U->>C: User action + C->>S: Service call + S-->>C: Response + C-->>U: Update UI +``` + +#### Component Diagrams +```mermaid +graph LR + subgraph Frontend + A[Component A] + B[Component B] + end + subgraph Backend + C[Service] + D[Database] + end + A --> C + B --> C + C --> D +``` + +#### State Diagrams +```mermaid +stateDiagram-v2 + [*] --> Idle + Idle --> Loading: fetch() + Loading --> Success: data received + Loading --> Error: request failed + Success --> Idle: reset + Error --> Loading: retry +``` + +### Feature Specifications + +Follow SpecKit format (see existing `specs/` directory): + +```markdown +# Feature: [Name] + +## Goal +[1-2 sentences on what this achieves] + +## Context +[Background and why this is needed] + +## Deliverables +- [ ] Deliverable 1 +- [ ] Deliverable 2 + +## Approach +[High-level implementation strategy] + +## Open Questions +- [ ] Question 1 +- [ ] Question 2 + +## Exit Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 +``` + +### Component READMEs + +Structure for component documentation: + +```markdown +# Component Name + +Brief description of what this component does. + +## Installation + +\`\`\`bash +npm install component-name +\`\`\` + +## Usage + +\`\`\`typescript +import { Component } from 'component-name'; + +// Basic usage example +const instance = new Component(); +\`\`\` + +## API + +### `methodName(param: Type): ReturnType` + +Description of what the method does. + +**Parameters**: +- `param` - Description of parameter + +**Returns**: Description of return value + +**Example**: +\`\`\`typescript +component.methodName('value'); +\`\`\` + +## Configuration + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `option1` | `string` | `'default'` | What it does | +| `option2` | `boolean` | `false` | What it does | + +## Development + +\`\`\`bash +# Run tests +npm test + +# Build +npm run build +\`\`\` + +## Contributing + +[Link to contribution guidelines] +``` + +### API Documentation + +For REST APIs: + +```markdown +# API Reference + +## Base URL + +\`https://api.example.com/v1\` + +## Authentication + +All requests require Bearer token in Authorization header. + +## Endpoints + +### GET /resource + +Retrieves a list of resources. + +**Query Parameters**: +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `limit` | integer | No | Max items (default: 20) | +| `offset` | integer | No | Pagination offset | + +**Response**: +\`\`\`json +{ + "data": [...], + "meta": { + "total": 100, + "limit": 20, + "offset": 0 + } +} +\`\`\` + +**Status Codes**: +- `200` - Success +- `401` - Unauthorized +- `500` - Server error +``` + +### Technical Decision Records (TDRs) + +```markdown +# TDR-001: [Decision Title] + +**Status**: Proposed | Accepted | Deprecated | Superseded +**Date**: YYYY-MM-DD +**Deciders**: [Names] + +## Context + +[What is the issue or situation that requires a decision?] + +## Decision + +[What is the change that we're proposing and/or doing?] + +## Consequences + +### Positive +- [Benefit 1] +- [Benefit 2] + +### Negative +- [Drawback 1] +- [Drawback 2] + +### Neutral +- [Side effect 1] + +## Alternatives Considered + +### Option A: [Name] +[Description and why not chosen] + +### Option B: [Name] +[Description and why not chosen] +``` + +## Generation Workflow + +### Step 1: Understand Context + +1. **Identify scope**: What needs documentation +2. **Find existing docs**: Check `docs/`, `specs/`, README files +3. **Gather technical details**: Code structure, APIs, data flow + +### Step 2: Choose Format + +| Content Need | Recommended Format | +|--------------|-------------------| +| System overview | Architecture diagram | +| Data flow | Sequence diagram | +| Component states | State diagram | +| New feature | Feature spec | +| Library/package | Component README | +| HTTP endpoints | API documentation | +| Major decision | TDR | + +### Step 3: Draft Documentation + +1. Start with outline/structure +2. Fill in details systematically +3. Add diagrams where they clarify +4. Include examples for APIs/code + +### Step 4: Review Checklist + +- [ ] Accurate and up-to-date +- [ ] Consistent terminology with codebase +- [ ] Diagrams render correctly (test Mermaid) +- [ ] Code examples are tested/valid +- [ ] Links are functional +- [ ] Follows existing documentation patterns + +## Output Format + +```markdown +## Technical Documentation Generated + +### Document Type +[Diagram | Spec | README | API Doc | TDR] + +### Location +`path/to/document.md` + +### Preview + +--- + +[Full document content here] + +--- + +### Related Files +- [List any related documents that may need updates] + +### Diagrams Included +- [List any Mermaid diagrams with brief description] +``` + +## Quick Reference + +| Task | Template | Location | +|------|----------|----------| +| New architecture diagram | Mermaid flowchart/sequence | `docs/architecture/` | +| Feature spec | SpecKit format | `specs/NNN-feature/` | +| Component docs | README template | Component directory | +| API reference | OpenAPI/Markdown | `docs/api/` | +| Decision record | TDR template | `docs/decisions/` | diff --git a/.specify/templates/blog-post-completed-template.md b/.specify/templates/blog-post-completed-template.md new file mode 100644 index 00000000..f302fab2 --- /dev/null +++ b/.specify/templates/blog-post-completed-template.md @@ -0,0 +1,56 @@ +# [Feature Name]: Now Available + + + +## What We Built + +[2-3 paragraphs explaining what was delivered and why it matters. Focus on the problem solved and value delivered.] + +Highlights: +- [Key feature/improvement 1] +- [Key feature/improvement 2] +- [Key feature/improvement 3] + +## See It In Action + +[Include 2-4 annotated screenshots, GIFs, or code examples that demonstrate the feature] + +![Screenshot 1: Description of what's shown](path/to/screenshot-1.png) +*Caption: [Explain what the user is seeing and why it matters]* + +![Screenshot 2: Description of what's shown](path/to/screenshot-2.png) +*Caption: [Explain what the user is seeing and why it matters]* + +### Quick Demo + +```typescript +// Example code showing how to use the feature +import { NewFeature } from 'package'; + +const feature = new NewFeature(); +feature.doSomethingUseful(); +``` + +## Lessons Learned + +During development, we discovered: + +1. **[Lesson 1 title]**: [Brief insight - what we learned and how it shaped the solution] + +2. **[Lesson 2 title]**: [Brief insight - what we learned and how it shaped the solution] + +3. **[Lesson 3 title]**: [Brief insight - what we learned and how it shaped the solution] + +## What's Next + +[1 paragraph pointing to upcoming work, related features, or how users can build on this] + +**[Read the full documentation →](link-to-docs)** + +--- + +*Thanks to [contributors] for their work on this feature. Questions or feedback? [Let us know](link-to-feedback).* diff --git a/.specify/templates/blog-post-planning-template.md b/.specify/templates/blog-post-planning-template.md new file mode 100644 index 00000000..a49f0880 --- /dev/null +++ b/.specify/templates/blog-post-planning-template.md @@ -0,0 +1,41 @@ +# [Feature Name]: What We're Building Next + + + +## What We're Building + +[2-3 paragraphs explaining the feature in accessible terms. Focus on user value, not implementation details.] + +Key capabilities: +- [Capability 1 - what users will be able to do] +- [Capability 2 - what users will be able to do] +- [Capability 3 - what users will be able to do] + +## How It Fits + +[1-2 paragraphs explaining how this connects to the broader project vision. Help readers understand the bigger picture.] + +## Key Decisions We're Making + +We're currently evaluating several approaches: + +- **[Decision area 1]**: [Brief explanation of the choice and trade-offs] +- **[Decision area 2]**: [Brief explanation of the choice and trade-offs] +- **[Decision area 3]**: [Brief explanation of the choice and trade-offs] + +## We Want Your Feedback + +We're particularly interested in hearing about: +- [Specific feedback area 1 - e.g., "Your experience with similar features"] +- [Specific feedback area 2 - e.g., "Use cases we might have missed"] +- [Specific feedback area 3 - e.g., "Concerns about the proposed approach"] + +**[Join the discussion on GitHub →](link-to-discussion)** + +--- + +*Have questions? Drop a comment below or reach out on [platform].* diff --git a/.specify/templates/technical-decision-record-template.md b/.specify/templates/technical-decision-record-template.md new file mode 100644 index 00000000..c75b5315 --- /dev/null +++ b/.specify/templates/technical-decision-record-template.md @@ -0,0 +1,93 @@ +# TDR-[NNN]: [Decision Title] + + + +**Status**: Proposed | Accepted | Deprecated | Superseded by [TDR-XXX] +**Date**: YYYY-MM-DD +**Deciders**: [List of people involved in the decision] +**Technical Story**: [Link to issue/ticket if applicable] + +## Context + +[Describe the situation that requires a decision. What problem are we solving? What constraints exist? What forces are at play?] + +Key considerations: +- [Consideration 1] +- [Consideration 2] +- [Consideration 3] + +## Decision + +[State the decision clearly and concisely. What change are we making?] + +We will [do X] because [primary reason]. + +### Implementation Details + +[If helpful, include high-level implementation notes] + +``` +[Diagram or code example if applicable] +``` + +## Consequences + +### Positive + +- [Benefit 1 - what improves] +- [Benefit 2 - what becomes easier] +- [Benefit 3 - what risks are mitigated] + +### Negative + +- [Drawback 1 - what becomes harder] +- [Drawback 2 - what technical debt is introduced] +- [Drawback 3 - what limitations are accepted] + +### Neutral + +- [Side effect 1 - changes that aren't clearly good or bad] +- [Side effect 2 - things that are just different] + +## Alternatives Considered + +### Option A: [Alternative Name] + +[Description of the alternative] + +**Pros**: +- [Advantage 1] +- [Advantage 2] + +**Cons**: +- [Disadvantage 1] +- [Disadvantage 2] + +**Why not chosen**: [Brief explanation] + +### Option B: [Alternative Name] + +[Description of the alternative] + +**Pros**: +- [Advantage 1] + +**Cons**: +- [Disadvantage 1] + +**Why not chosen**: [Brief explanation] + +## Related Decisions + +- [TDR-XXX: Related decision title](link) +- [TDR-YYY: Related decision title](link) + +## References + +- [Link to relevant documentation] +- [Link to research or prior art] +- [Link to discussion thread] From d39d7e60b6c59b8600a1d1cc255c94bec31ae15a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Jan 2026 16:53:49 +0000 Subject: [PATCH 2/2] feat: integrate media generation into speckit workflow Update speckit commands to include media generation as part of the feature development workflow: - speckit.tasks.md: Add Media & Communications phase with task examples for documentation, blog posts, and site updates - speckit.implement.md: Add step 10 for media generation after implementation completion - tasks-template.md: Add Phase N (Media & Communications) with structured tasks for technical docs, content creation, and site updates This ensures that documentation and announcements are generated as part of the standard feature development workflow. --- .claude/commands/speckit.implement.md | 9 ++++++++ .claude/commands/speckit.tasks.md | 29 ++++++++++++++++++++++++- .specify/templates/tasks-template.md | 31 +++++++++++++++++++++++++-- 3 files changed, 66 insertions(+), 3 deletions(-) diff --git a/.claude/commands/speckit.implement.md b/.claude/commands/speckit.implement.md index 9646a2d8..194946e8 100644 --- a/.claude/commands/speckit.implement.md +++ b/.claude/commands/speckit.implement.md @@ -131,4 +131,13 @@ You **MUST** consider the user input before proceeding (if not empty). - Confirm the implementation follows the technical plan - Report final status with summary of completed work +10. **Media & Communications** (after implementation complete): + - If tasks.md includes a Media & Communications phase, execute those tasks + - Use the media generation commands to create documentation and announcements: + - `/media.technical` - Architecture diagrams, README updates, API docs + - `/media.content` - Blog posts, LinkedIn summaries, release notes + - `/media.site` - Site documentation updates (if applicable) + - Alternatively, run `/media.coordinate` with a summary of the feature for coordinated content generation + - Report generated media artifacts in final summary + Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list. diff --git a/.claude/commands/speckit.tasks.md b/.claude/commands/speckit.tasks.md index 3b89c8ec..5900142b 100644 --- a/.claude/commands/speckit.tasks.md +++ b/.claude/commands/speckit.tasks.md @@ -125,4 +125,31 @@ Every task MUST strictly follow this format: - **Phase 3+**: User Stories in priority order (P1, P2, P3...) - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration - Each phase should be a complete, independently testable increment -- **Final Phase**: Polish & Cross-Cutting Concerns +- **Phase N-1**: Polish & Cross-Cutting Concerns +- **Phase N**: Media & Communications (documentation, blog posts, announcements) + +### Media & Communications Tasks + +The final phase should include tasks for communicating the feature: + +1. **Technical Documentation** (via `/media.technical`): + - Architecture diagrams (Mermaid) for new components + - README updates for new features + - API documentation for new endpoints + +2. **Content Creation** (via `/media.content`): + - Blog post draft (planning or completed style) + - LinkedIn summary for social sharing + - Release notes entry + +3. **Site Updates** (via `/media.site`) - if applicable: + - Documentation page updates + - Changelog entry + +**Task Examples**: +``` +- [ ] TXXX [P] Create architecture diagram for [feature] using /media.technical +- [ ] TXXX [P] Update README with [feature] usage examples +- [ ] TXXX [P] Draft blog post for [feature] using /media.content +- [ ] TXXX [P] Create LinkedIn summary for [feature] announcement +``` diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index 60f9be45..5ce0fc0a 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -146,7 +146,7 @@ Examples of foundational tasks (adjust based on your project): --- -## Phase N: Polish & Cross-Cutting Concerns +## Phase N-1: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories @@ -159,6 +159,32 @@ Examples of foundational tasks (adjust based on your project): --- +## Phase N: Media & Communications + +**Purpose**: Document and communicate the feature for users and stakeholders + +### Technical Documentation (via `/media.technical`) + +- [ ] TXXX [P] Create architecture diagram for [feature] in docs/architecture/ +- [ ] TXXX [P] Update README.md with [feature] usage and examples +- [ ] TXXX [P] Generate API documentation for new endpoints (if applicable) +- [ ] TXXX [P] Create or update component documentation + +### Content Creation (via `/media.content`) + +- [ ] TXXX [P] Draft blog post announcing [feature] (planning or completed style) +- [ ] TXXX [P] Create LinkedIn summary (150-200 words) for social sharing +- [ ] TXXX [P] Write release notes entry for CHANGELOG.md + +### Site Updates (via `/media.site`) - if applicable + +- [ ] TXXX [P] Add/update documentation page on project site +- [ ] TXXX [P] Update site navigation if new pages added + +**Checkpoint**: Feature is documented, announced, and ready for users + +--- + ## Dependencies & Execution Order ### Phase Dependencies @@ -168,7 +194,8 @@ Examples of foundational tasks (adjust based on your project): - **User Stories (Phase 3+)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3) -- **Polish (Final Phase)**: Depends on all desired user stories being complete +- **Polish (Phase N-1)**: Depends on all desired user stories being complete +- **Media & Communications (Phase N)**: Depends on Polish - can start once feature is stable ### User Story Dependencies