Workflow Overview#

Goal: Create focused technical specification for small projects

Phase: 2 - Planning

Agent: Product Manager

Inputs: Product brief (if available), requirements discussion

Output: .bmad/tech-spec-{project-name}-{date}.md

Duration: 20-40 minutes

Best for: Level 0-1 projects (≤10 stories)

Pre-Flight#

1. Load context per helpers.md#Combined-Config-Load
2. Check status per helpers.md#Load-Workflow-Status
3. Load product brief if exists (read .bmad/product-brief-*.md)
4. Load template per helpers.md#Load-Template (tech-spec.md)

Streamlined Requirements Process#

Use TodoWrite to track: Pre-flight → Requirements → Technical → Plan → Generate → Validate → Update

Approach: Pragmatic and efficient for smaller scope.

Section 1: Problem & Solution#

If product brief exists, extract:

• Problem statement
• Proposed solution

If NO brief: Ask:

"In 2-3 sentences:

1. What problem are you solving?
2. What's your solution?"

Store as: {{problem_statement}}, {{proposed_solution}}

Section 2: Requirements List#

Explain:

"For small projects, we'll keep requirements simple and actionable."

Ask: "What needs to be built? List the key features or capabilities."

Format as bulleted list:

- Feature 1: Description with acceptance criteria
- Feature 2: Description with acceptance criteria
- Feature 3: Description with acceptance criteria

Typical count: 3-8 requirements

Also ask: "What is explicitly OUT of scope?"

Store as: {{requirements_list}}, {{out_of_scope}}

Section 3: Technical Approach#

Technology Stack: Ask: "What technologies will you use?"

• Language/framework
• Database
• Hosting/deployment
• Key libraries

Format:

- **Language/Framework:** Python 3.11 + FastAPI
- **Database:** PostgreSQL 15
- **Hosting:** AWS (ECS + RDS)
- **Key Libraries:** SQLAlchemy, Pydantic, pytest

Store as: {{tech_stack}}

Architecture Overview: Ask: "At a high level, how does the system work?"

Encourage: Simple description or diagram text

• Main components
• Data flow
• Key interactions

Store as: {{architecture_overview}}

Data Model (if applicable): If data-heavy: Ask: "What are the main data entities and their relationships?"

Format as simple list or markdown table.

Store as: {{data_model}}

API Design (if applicable): If API project: Ask: "What are the key API endpoints?"

Format:

- GET /api/users - List users
- POST /api/users - Create user
- GET /api/users/{id} - Get user by ID

Store as: {{api_design}}

Section 4: Implementation Plan#

Stories: Ask: "Let's break this into implementable pieces. What are the 1-10 stories?"

For Level 0 (single story):

• Just one story that encompasses everything

For Level 1 (1-10 stories):

• Break into logical chunks
• Each story should be 1-3 days of work

Format:

1. **Story Name** - What it delivers
2. **Story Name** - What it delivers
...

Store as: {{stories_list}}

Development Phases (optional for Level 1): If multiple stories, ask about order:

"What's the logical implementation order?"

Store as: {{development_phases}}

Section 5: Acceptance Criteria#

Ask: "How will you know it's complete? What must work?"

Format as checklist:

- [ ] Feature X works as described
- [ ] All tests pass
- [ ] Deployed to [environment]
- [ ] User can successfully [key action]

Store as: {{acceptance_criteria}}

Section 6: Non-Functional Requirements (Brief)#

Ask concisely:

Performance:

"Any performance requirements? (e.g., response time, load handling)"

Security:

"Any security requirements? (e.g., authentication, data protection)"

Other:

"Anything else? (accessibility, browser support, etc.)"

Store as: {{performance_requirements}}, {{security_requirements}}, {{other_nfr}}

Section 7: Dependencies, Risks, Timeline#

Dependencies: Ask: "What does this depend on?" Store as: {{dependencies}}

Risks: Ask: "What could go wrong? How to mitigate?" Format:

- **Risk:** Description
  - **Mitigation:** Strategy

Store as: {{risks}}

Timeline: Ask: "When do you want this done?" Ask: "Any key milestones?" Store as: {{target_completion}}, {{milestones}}

Generate Document#

1. Load template from ${CLAUDE_PLUGIN_ROOT}/references/templates/tech-spec.md
2. Substitute variables per helpers.md#Apply-Variables-to-Template
3. Determine output path: {output_folder}/tech-spec-{project-name}-{date}.md
4. Write document using Write tool
5. Display summary:

       ✓ Tech Spec Created!
   
   Summary:
   - Requirements: {count}
   - Stories: {count}
   - Tech Stack: {stack}
   - Target: {completion_date}
   

Validation#

✓ Checklist:
- [ ] Problem and solution are clear
- [ ] Requirements are specific and testable
- [ ] Tech stack is defined
- [ ] Stories are broken down (if Level 1)
- [ ] Acceptance criteria are clear
- [ ] Out of scope is stated

Ask user: "Please review the tech spec. Is it complete?"

Update Status#

Per helpers.md#Update-Workflow-Status:

1. Update tech-spec status to file path
2. Save

Recommend Next Steps#

Level 0:

✓ Tech Spec complete!

Next: Create your story
Run /create-story to create the single story for implementation.

Then: /dev-story to implement it.

Level 1:

✓ Tech Spec complete!

Next: Sprint Planning
Run /sprint-planning to organize your stories and plan implementation.

Note: Level 1 projects can skip architecture and go straight to implementation.

Helper References#

• Load config: helpers.md#Combined-Config-Load
• Load status: helpers.md#Load-Workflow-Status
• Load template: helpers.md#Load-Template
• Apply variables: helpers.md#Apply-Variables-to-Template
• Save document: helpers.md#Save-Output-Document
• Update status: helpers.md#Update-Workflow-Status
• Recommend next: helpers.md#Determine-Next-Workflow

Tips for Tech Specs#

Keep it lightweight:

• Don't over-plan for small projects
• Focus on what's essential
• Get to implementation faster

But be clear:

• Requirements should still be testable
• Tech decisions should be documented
• Success criteria should be explicit

Right-size:

• Level 0: 1 page is fine
• Level 1: 2-3 pages maximum
• If you need more, consider using /prd instead

Notes for LLMs#

• Maintain a pragmatic persona for small projects
• Move faster than PRD - less ceremony
• Still ensure clarity and testability
• Don't skip critical elements (requirements, acceptance criteria)
• For Level 0, keep it very simple (single story focus)
• For Level 1, provide just enough structure

Remember: Tech specs are for speed on small projects. Don't over-engineer the planning process.