diff --git a/README.md b/README.md index 8ada2d50..108f3072 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,59 @@ BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies ## Table of Contents -- [Quick Start](#quick-start) -- [What is BMad-CORE?](#what-is-bmad-core) -- [Modules](#modules) - - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development) - - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions) - - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity) -- [Installation](#installation) -- [Key Features](#key-features) -- [Documentation](#documentation) -- [Community & Support](#community--support) +- [BMad CORE + BMad Method](#bmad-core--bmad-method) + - [Universal Human-AI Collaboration Platform](#universal-human-ai-collaboration-platform) + - [Table of Contents](#table-of-contents) + - [Quick Start](#quick-start) + - [⚡ NEW: Quick Spec Flow for Rapid Development](#-new-quick-spec-flow-for-rapid-development) + - [What is BMad-CORE?](#what-is-bmad-core) + - [v6 Core Enhancements](#v6-core-enhancements) + - [C.O.R.E. Philosophy](#core-philosophy) + - [Modules](#modules) + - [BMad Method (BMM) - Agile AI Development](#bmad-method-bmm---agile-ai-development) + - [v6 Highlights](#v6-highlights) + - [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions) + - [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity) + - [Installation](#installation) + - [Project Structure](#project-structure) + - [Getting Started](#getting-started) + - [Key Features](#key-features) + - [🎨 Update-Safe Customization](#-update-safe-customization) + - [🚀 Intelligent Installation](#-intelligent-installation) + - [📁 Unified Architecture](#-unified-architecture) + - [📄 Document Sharding](#-document-sharding) + - [Documentation](#documentation) + - [Community \& Support](#community--support) + - [Contributing](#contributing) + - [License](#license) ## Quick Start - **New to v6?** [→ BMad Method V6 Quick Start Guide](./docs/BMad-Method-V6-Quick-Start.md) +- **Need a quick bug fix or small feature?** ⚡ [→ BMad Quick Spec Flow](./docs/quick-spec-flow.md) - Go from idea to implementation in minutes! - **Upgrading?** [→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md) +### ⚡ NEW: Quick Spec Flow for Rapid Development + +**Perfect for:** Bug fixes, small features, rapid prototyping + +Skip the full planning docs and go **straight to implementation** with auto-detected stack, brownfield analysis, and context-rich technical specs. Ideal for Level 0-1 projects that don't need Product Briefs or PRDs. + +📚 **Learn about project levels:** [BMad Method Scale Adaptive System](./docs/scale-adaptive-system.md) - Automatically adapts from Level 0 (bug fixes) to Level 4 (enterprise systems) + +**When to use Quick Spec Flow:** + +- 🐛 **Bug fixes** - Single file changes, isolated improvements +- ✨ **Small features** - 2-3 related changes, coherent functionality +- 🚀 **Rapid prototyping** - Quick experiments and validation +- 🔧 **Brownfield enhancements** - Adding to existing codebases + +**Not sure which flow to use?** Run `workflow-init` - it will analyze your project goal and recommend either Quick Spec Flow (Level 0-1) or Full BMM Flow (Level 2-4). + +[**→ Read the complete Quick Spec Flow guide**](./docs/quick-spec-flow.md) + +--- + ## What is BMad-CORE? Foundation framework powering all BMad modules: diff --git a/docs/quick-spec-flow.md b/docs/quick-spec-flow.md new file mode 100644 index 00000000..840882d9 --- /dev/null +++ b/docs/quick-spec-flow.md @@ -0,0 +1,645 @@ +# BMad Quick Spec Flow + +**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements + +**Time to implementation:** Minutes, not hours + +--- + +## What is Quick Spec Flow? + +Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Level 0-1 projects. Instead of going through Product Brief → PRD → Architecture, you go **straight to a context-aware technical specification** and start coding. + +### When to Use Quick Spec Flow + +✅ **Use Quick Spec Flow (Level 0-1) when:** + +- Single bug fix or small enhancement (Level 0) +- Small feature with 2-3 related changes (Level 1) +- Rapid prototyping or experimentation +- Adding to existing brownfield codebase +- You know exactly what you want to build + +❌ **Use Full BMM Flow (Level 2-4) when:** + +- Building new products or major features (Level 2-4) +- Need stakeholder alignment +- Complex multi-team coordination +- Requires extensive planning and architecture + +💡 **Not sure?** Run `workflow-init` to get a recommendation based on your project's size and complexity! + +--- + +## Quick Spec Flow Overview + +``` +┌─────────────────────────────────────────────────────────────┐ +│ QUICK SPEC FLOW │ +│ (Level 0-1 Projects) │ +└─────────────────────────────────────────────────────────────┘ + +Step 1: Run Tech-Spec Workflow + │ + ├─► Detects your project stack (package.json, requirements.txt, etc.) + ├─► Analyzes brownfield codebase (if exists) + ├─► Detects test frameworks and conventions + ├─► Confirms conventions with you + ├─► Generates context-rich tech-spec + └─► Creates ready-to-implement stories + +Step 2: Optional - Generate Story Context (SM Agent) + │ + └─► For complex scenarios only + +Step 3: Implement (DEV Agent) + │ + └─► Code, test, commit + +DONE! 🚀 +``` + +--- + +## Level 0: Single Atomic Change + +**Best for:** Bug fixes, single file changes, isolated improvements + +### What You Get + +1. **tech-spec.md** - Comprehensive technical specification with: + - Problem statement and solution + - Detected framework versions and dependencies + - Brownfield code patterns (if applicable) + - Existing test patterns to follow + - Specific file paths to modify + - Complete implementation guidance + +2. **story-[slug].md** - Single user story ready for development + +### Quick Spec Flow Commands + +```bash +# Start Quick Spec Flow (no workflow-init needed!) +# Load PM agent and run tech-spec + +# When complete, implement directly: +# Load DEV agent and run dev-story +``` + +### What Makes It Quick + +- ✅ No Product Brief needed +- ✅ No PRD needed +- ✅ No Architecture doc needed +- ✅ Auto-detects your stack +- ✅ Auto-analyzes brownfield code +- ✅ Auto-validates quality +- ✅ Story context optional (tech-spec is comprehensive!) + +### Example Level 0 Scenarios + +- "Fix the login validation bug" +- "Add email field to user registration form" +- "Update API endpoint to return additional field" +- "Improve error handling in payment processing" + +--- + +## Level 1: Coherent Small Feature + +**Best for:** Small features with 2-3 related user stories + +### What You Get + +1. **tech-spec.md** - Same comprehensive spec as Level 0 +2. **epics.md** - Epic organization with story breakdown +3. **story-[epic-slug]-1.md** - First story +4. **story-[epic-slug]-2.md** - Second story +5. **story-[epic-slug]-3.md** - Third story (if needed) + +### Quick Spec Flow Commands + +```bash +# Start Quick Spec Flow +# Load PM agent and run tech-spec + +# Optional: Organize stories as a sprint +# Load SM agent and run sprint-planning + +# Implement story-by-story: +# Load DEV agent and run dev-story for each story +``` + +### Story Sequencing + +Stories are **automatically validated** to ensure proper sequence: + +- ✅ No forward dependencies (Story 2 can't depend on Story 3) +- ✅ Clear dependency documentation +- ✅ Infrastructure → Features → Polish order +- ✅ Backend → Frontend flow + +### Example Level 1 Scenarios + +- "Add OAuth social login (Google, GitHub, Twitter)" +- "Build user profile page with avatar upload" +- "Implement basic search with filters" +- "Add dark mode toggle to application" + +--- + +## Smart Context Discovery + +Quick Spec Flow automatically discovers and uses: + +### 1. Existing Documentation + +- Product briefs (if they exist) +- Research documents +- `document-project` output (brownfield codebase map) + +### 2. Project Stack + +- **Node.js:** package.json → frameworks, dependencies, scripts, test framework +- **Python:** requirements.txt, pyproject.toml → packages, tools +- **Ruby:** Gemfile → gems and versions +- **Java:** pom.xml, build.gradle → Maven/Gradle dependencies +- **Go:** go.mod → modules +- **Rust:** Cargo.toml → crates +- **PHP:** composer.json → packages + +### 3. Brownfield Code Patterns + +- Directory structure and organization +- Existing code patterns (class-based, functional, MVC) +- Naming conventions (camelCase, snake_case, PascalCase) +- Test frameworks and patterns +- Code style (semicolons, quotes, indentation) +- Linter/formatter configs +- Error handling patterns +- Logging conventions +- Documentation style + +### 4. Convention Confirmation + +**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**: + +``` +I've detected these conventions in your codebase: + +Code Style: +- ESLint with Airbnb config +- Prettier with single quotes, 2-space indent +- No semicolons + +Test Patterns: +- Jest test framework +- .test.js file naming +- expect() assertion style + +Should I follow these existing conventions? (yes/no) +``` + +**You decide:** Conform to existing patterns or establish new standards! + +--- + +## Modern Best Practices via WebSearch + +Quick Spec Flow stays current by using WebSearch when appropriate: + +### For Greenfield Projects + +- Searches for latest framework versions +- Recommends official starter templates +- Suggests modern best practices + +### For Outdated Dependencies + +- Detects if your dependencies are >2 years old +- Searches for migration guides +- Notes upgrade complexity + +### Starter Template Recommendations + +For greenfield projects, Quick Spec Flow recommends: + +**React:** + +- Vite (modern, fast) +- Next.js (full-stack) + +**Python:** + +- cookiecutter templates +- FastAPI starter + +**Node.js:** + +- NestJS CLI +- express-generator + +**Benefits:** + +- ✅ Modern best practices baked in +- ✅ Proper project structure +- ✅ Build tooling configured +- ✅ Testing framework set up +- ✅ Faster time to first feature + +--- + +## UX/UI Considerations + +For user-facing changes, Quick Spec Flow captures: + +- UI components affected (create vs modify) +- UX flow changes (current vs new) +- Responsive design needs (mobile, tablet, desktop) +- Accessibility requirements: + - Keyboard navigation + - Screen reader compatibility + - ARIA labels + - Color contrast standards +- User feedback patterns: + - Loading states + - Error messages + - Success confirmations + - Progress indicators + +--- + +## Auto-Validation & Quality Assurance + +Quick Spec Flow **automatically validates** everything: + +### Tech-Spec Validation (Always Runs) + +Checks: + +- ✅ Context gathering completeness +- ✅ Definitiveness (no "use X or Y" statements) +- ✅ Brownfield integration quality +- ✅ Stack alignment +- ✅ Implementation readiness + +Generates scores: + +``` +✅ Validation Passed! +- Context Gathering: Comprehensive +- Definitiveness: All definitive +- Brownfield Integration: Excellent +- Stack Alignment: Perfect +- Implementation Readiness: ✅ Ready +``` + +### Story Validation (Level 1 Only) + +Checks: + +- ✅ Story sequence (no forward dependencies!) +- ✅ Acceptance criteria quality (specific, testable) +- ✅ Completeness (all tech spec tasks covered) +- ✅ Clear dependency documentation + +**Auto-fixes issues if found!** + +--- + +## Complete User Journey + +### Scenario 1: Bug Fix (Level 0) + +**Goal:** Fix login validation bug + +**Steps:** + +1. **Start:** Load PM agent, say "I want to fix the login validation bug" +2. **PM runs tech-spec workflow:** + - Asks: "What problem are you solving?" + - You explain the validation issue + - Detects your Node.js stack (Express 4.18.2, Jest for testing) + - Analyzes existing UserService code patterns + - Asks: "Should I follow your existing conventions?" → You say yes + - Generates tech-spec.md with specific file paths and patterns + - Creates story-login-fix.md +3. **Implement:** Load DEV agent, run `dev-story` + - DEV reads tech-spec (has all context!) + - Implements fix following existing patterns + - Runs tests (following existing Jest patterns) + - Done! + +**Total time:** 15-30 minutes (mostly implementation) + +--- + +### Scenario 2: Small Feature (Level 1) + +**Goal:** Add OAuth social login (Google, GitHub) + +**Steps:** + +1. **Start:** Load PM agent, say "I want to add OAuth social login" +2. **PM runs tech-spec workflow:** + - Asks about the feature scope + - You specify: Google and GitHub OAuth + - Detects your stack (Next.js 13.4, NextAuth.js already installed!) + - Analyzes existing auth patterns + - Confirms conventions with you + - Generates: + - tech-spec.md (comprehensive implementation guide) + - epics.md (OAuth Integration epic) + - story-oauth-1.md (Backend OAuth setup) + - story-oauth-2.md (Frontend login buttons) +3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning` +4. **Implement Story 1:** + - Load DEV agent, run `dev-story` for story 1 + - DEV implements backend OAuth +5. **Implement Story 2:** + - DEV agent, run `dev-story` for story 2 + - DEV implements frontend + - Done! + +**Total time:** 1-3 hours (mostly implementation) + +--- + +## Integration with Phase 4 Workflows + +Quick Spec Flow works seamlessly with all Phase 4 implementation workflows: + +### story-context (SM Agent) + +- ✅ Recognizes tech-spec.md as authoritative source +- ✅ Extracts context from tech-spec (replaces PRD) +- ✅ Generates XML context for complex scenarios + +### create-story (SM Agent) + +- ✅ Can work with tech-spec.md instead of PRD +- ✅ Uses epics.md from tech-spec workflow +- ✅ Creates additional stories if needed + +### sprint-planning (SM Agent) + +- ✅ Works with epics.md from tech-spec +- ✅ Organizes Level 1 stories for coordinated implementation +- ✅ Tracks progress through sprint-status.yaml + +### dev-story (DEV Agent) + +- ✅ Reads stories generated by tech-spec +- ✅ Uses tech-spec.md as comprehensive context +- ✅ Implements following detected conventions + +--- + +## Comparison: Quick Spec vs Full BMM + +| Aspect | Quick Spec Flow (Level 0-1) | Full BMM Flow (Level 2-4) | +| --------------------- | ---------------------------- | ---------------------------------- | +| **Setup** | None (standalone) | workflow-init recommended | +| **Planning Docs** | tech-spec.md only | Product Brief → PRD → Architecture | +| **Time to Code** | Minutes | Hours to days | +| **Best For** | Bug fixes, small features | New products, major features | +| **Context Discovery** | Automatic | Manual + guided | +| **Story Context** | Optional (tech-spec is rich) | Required (generated from PRD) | +| **Validation** | Auto-validates everything | Manual validation steps | +| **Brownfield** | Auto-analyzes and conforms | Manual documentation required | +| **Conventions** | Auto-detects and confirms | Document in PRD/Architecture | + +--- + +## When to Graduate from Quick Spec to Full BMM + +Start with Quick Spec, but switch to Full BMM when: + +- ❌ Project grows beyond 3-5 stories +- ❌ Multiple teams need coordination +- ❌ Stakeholders need formal documentation +- ❌ Product vision is unclear +- ❌ Architectural decisions need deep analysis +- ❌ Compliance/regulatory requirements exist + +💡 **Tip:** You can always run `workflow-init` later to transition from Quick Spec to Full BMM! + +--- + +## Quick Spec Flow - Key Benefits + +### 🚀 **Speed** + +- No Product Brief +- No PRD +- No Architecture doc +- Straight to implementation + +### 🧠 **Intelligence** + +- Auto-detects stack +- Auto-analyzes brownfield +- Auto-validates quality +- WebSearch for current info + +### 📐 **Respect for Existing Code** + +- Detects conventions +- Asks for confirmation +- Follows patterns +- Adapts vs. changes + +### ✅ **Quality** + +- Auto-validation +- Definitive decisions (no "or" statements) +- Comprehensive context +- Clear acceptance criteria + +### 🎯 **Focus** + +- Level 0: Single atomic change +- Level 1: Coherent small feature +- No scope creep +- Fast iteration + +--- + +## Getting Started + +### Prerequisites + +- BMad Method installed (`npx bmad-method install`) +- Project directory with code (or empty for greenfield) + +### Quick Start Commands + +```bash +# For a quick bug fix or small change: +# 1. Load PM agent +# 2. Say: "I want to [describe your change]" +# 3. PM will ask if you want to run tech-spec +# 4. Answer questions about your change +# 5. Get tech-spec + story +# 6. Load DEV agent and implement! + +# For a small feature with multiple stories: +# Same as above, but get epic + 2-3 stories +# Optionally use SM sprint-planning to organize +``` + +### No workflow-init Required! + +Quick Spec Flow is **fully standalone**: + +- Detects if you're Level 0 or Level 1 +- Asks for greenfield vs brownfield +- Works without status file tracking +- Perfect for rapid prototyping + +--- + +## FAQ + +### Q: Can I use Quick Spec Flow on an existing project? + +**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them. + +### Q: What if I don't have a package.json or requirements.txt? + +**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices. + +### Q: Do I need to run workflow-init first? + +**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help. + +### Q: Can I use this for frontend changes? + +**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements. + +### Q: What if my Level 0 project grows? + +**A:** No problem! You can always transition to Full BMM by running workflow-init and create-prd. Your tech-spec becomes input for the PRD. + +### Q: Do I need story-context for every story? + +**A:** Usually no! Tech-spec is comprehensive enough for most Level 0-1 projects. Only use story-context for complex edge cases. + +### Q: Can I skip validation? + +**A:** No, validation always runs automatically. But it's fast and catches issues early! + +### Q: Will it work with my team's code style? + +**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones. + +--- + +## Tips & Best Practices + +### 1. **Be Specific in Discovery** + +When describing your change, provide specifics: + +- ✅ "Fix email validation in UserService to allow plus-addressing" +- ❌ "Fix validation bug" + +### 2. **Trust the Convention Detection** + +If it detects your patterns correctly, say yes! It's faster than establishing new conventions. + +### 3. **Use WebSearch Recommendations for Greenfield** + +Starter templates save hours of setup time. Let Quick Spec Flow find the best ones. + +### 4. **Review the Auto-Validation** + +When validation runs, read the scores. They tell you if your spec is production-ready. + +### 5. **Story Context is Optional** + +For Level 0, try going directly to dev-story first. Only add story-context if you hit complexity. + +### 6. **Keep Level 0 Truly Atomic** + +If your "single change" needs 3+ files, it might be Level 1. Let the workflow guide you. + +### 7. **Validate Story Sequence for Level 1** + +When you get multiple stories, check the dependency validation output. Proper sequence matters! + +--- + +## Real-World Examples + +### Example 1: Adding Logging (Level 0) + +**Input:** "Add structured logging to payment processing" + +**Tech-Spec Output:** + +- Detected: winston 3.8.2 already in package.json +- Analyzed: Existing services use winston with JSON format +- Confirmed: Follow existing logging patterns +- Generated: Specific file paths, log levels, format example +- Story: Ready to implement in 1-2 hours + +**Result:** Consistent logging added, following team patterns, no research needed. + +--- + +### Example 2: Search Feature (Level 1) + +**Input:** "Add search to product catalog with filters" + +**Tech-Spec Output:** + +- Detected: React 18.2.0, MUI component library, Express backend +- Analyzed: Existing ProductList component patterns +- Confirmed: Follow existing API and component structure +- Generated: + - Epic: Product Search Functionality + - Story 1: Backend search API with filters + - Story 2: Frontend search UI component +- Auto-validated: Story 1 → Story 2 sequence correct + +**Result:** Search feature implemented in 4-6 hours with proper architecture. + +--- + +## Summary + +Quick Spec Flow is your **fast path from idea to implementation** for: + +- 🐛 Bug fixes +- ✨ Small features +- 🚀 Rapid prototyping +- 🔧 Quick enhancements + +**Key Features:** + +- Auto-detects your stack +- Auto-analyzes brownfield code +- Auto-validates quality +- Respects existing conventions +- Uses WebSearch for modern practices +- Generates comprehensive tech-specs +- Creates implementation-ready stories + +**Time to code:** Minutes, not hours. + +**Ready to try it?** Load the PM agent and say what you want to build! 🚀 + +--- + +## Next Steps + +- **Try it now:** Load PM agent and describe a small change +- **Learn more:** See `src/modules/bmm/workflows/README.md` for full BMM workflow guide +- **Need help deciding?** Run `workflow-init` to get a recommendation +- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj + +--- + +_Quick Spec Flow - Because not every change needs a Product Brief._ diff --git a/docs/scale-adaptive-system.md b/docs/scale-adaptive-system.md new file mode 100644 index 00000000..d90b656c --- /dev/null +++ b/docs/scale-adaptive-system.md @@ -0,0 +1,1045 @@ +# BMad Method Scale Adaptive System + +**Automatically adapts workflows to project complexity - from bug fixes to enterprise systems** + +--- + +## Overview + +The **Scale Adaptive System** is BMad Method's intelligent workflow orchestration that automatically adjusts planning depth, documentation requirements, and implementation processes based on project size and complexity. + +### The Problem It Solves + +Traditional methodologies apply the same process to every project: + +- ❌ **Overkill:** Bug fix requires full design docs +- ❌ **Insufficient:** Enterprise system built with minimal planning +- ❌ **One-Size-Fits-None:** Same process for 1 story and 100 stories + +### The Solution + +BMad Method **adapts workflows to match project scale**: + +- ✅ **Level 0 (1 story):** Tech-spec only, implement immediately +- ✅ **Level 2 (10 stories):** PRD + Architecture, structured approach +- ✅ **Level 4 (100+ stories):** Full enterprise planning, comprehensive docs + +**Result:** Right amount of planning for every project - no more, no less. + +--- + +## Key Terminology + +### Analysis Phase + +**What it is:** Discovery and research phase that informs planning decisions. + +**Activities:** + +- **Brainstorming:** Ideation and creative exploration +- **Research:** Market analysis, technical investigation, user research +- **Product Brief:** High-level vision and requirements capture + +**When used:** + +- Optional for Level 0-1 (quick changes) +- Recommended for Level 2 (provides context) +- Required for Level 3-4 (critical for complex systems) + +--- + +### Tech-Spec (Technical Specification) + +**What it is:** Comprehensive technical plan for implementing changes or features. Serves as the **primary planning document** for Level 0-1 projects. + +**Contents:** + +- Problem statement and solution approach +- Source tree changes (specific files) +- Technical implementation details +- Detected stack and conventions (brownfield) +- UX/UI considerations (if user-facing) +- Testing strategy +- Developer resources + +**When used:** + +- **Level 0:** Single story technical plan +- **Level 1:** Feature technical plan with epic +- **Level 2-4:** Not used (PRD + Architecture instead) + +**Replacement at Level 2+:** Tech-spec is **replaced by PRD + Architecture** for proper product and system planning. + +--- + +### Epic-Tech-Spec (Epic Technical Specification) + +**What it is:** Detailed technical planning document created **during implementation** for each epic in Level 2-4 projects. + +**Difference from Tech-Spec:** + +- **Tech-spec (Level 0-1):** Created upfront, serves as primary planning doc +- **Epic-tech-spec (Level 2-4):** Created just-before-implementation per epic, supplements PRD + Architecture + +**Contents:** + +- Epic-specific technical details +- Detailed implementation approach for this epic +- Code-level design decisions +- Epic-scoped testing strategy +- Integration points with other epics + +**When used:** + +- **Recommended** for Level 2-4 during implementation phase +- Created as each epic is worked on +- Particularly important for: + - Complex epics with many stories + - Novel technical approaches + - Integration-heavy epics + - Performance-critical features + +--- + +### Architecture Document + +**What it is:** System-wide design document that defines structure, components, and interactions. + +**Scale-Adaptive:** + +- **Level 0-1:** Not used +- **Level 2:** Optional - lightweight architecture if needed +- **Level 3:** Required - comprehensive system architecture +- **Level 4:** Required - enterprise-grade architecture + +**Contents:** + +- System components and their responsibilities +- Data models and schemas +- Integration patterns +- Security architecture +- Performance considerations +- Deployment architecture +- **Scales in complexity** with project level + +**Note:** Architecture document takes the place of tech-spec for system-level planning in Level 2-4 projects. + +--- + +### Document-Project Workflow + +**What it is:** Brownfield codebase analysis workflow that creates comprehensive documentation of existing code. + +**Output:** `docs/index.md` with sharded sections covering: + +- Project structure +- Key modules and services +- Existing patterns +- Dependencies +- Configuration + +**Critical for Brownfield:** +🚨 **Run document-project BEFORE starting any brownfield project (Level 0-4)** + +**Why it matters:** + +- Tech-spec workflow uses this for brownfield analysis +- PRD workflow references it for context +- Architecture workflow builds on existing structure +- Epic-tech-specs reference existing code + +**When to run:** + +- Before workflow-init for brownfield projects +- When joining an existing codebase +- After major refactors (to update docs) + +--- + +## The Five Levels + +### Level 0: Single Atomic Change + +**Examples:** Bug fixes, typos, single-file changes + +| Aspect | Details | +| ------------------- | ------------------------------------------------ | +| **Stories** | 1 story | +| **Planning Docs** | Tech-spec only | +| **Architecture** | None | +| **Best For** | Bug fixes, small patches, quick updates | +| **Brownfield Prep** | Run document-project first (if not already done) | + +**Workflow:** + +``` +(Brownfield: document-project first) +↓ +Analysis (optional) → Tech-Spec → Implement +``` + +**Keywords:** fix, bug, typo, small change, quick update, patch + +--- + +### Level 1: Small Feature + +**Examples:** OAuth login, search feature, user profile page + +| Aspect | Details | +| ------------------- | --------------------------------------------------- | +| **Stories** | 1-10 stories (typically 2-3) | +| **Planning Docs** | Tech-spec with epic | +| **Architecture** | None | +| **UX Design** | Optional - can be included in tech-spec or separate | +| **Best For** | Small coherent features, rapid prototyping | +| **Brownfield Prep** | Run document-project first (if not already done) | + +**Workflow:** + +``` +(Brownfield: document-project first) +↓ +Analysis (optional) → Tech-Spec + Epic → (Optional UX Design) → Implement +``` + +**UX Note:** Level 1 tech-spec can include UX/UI considerations inline, or you can optionally run separate UX Design workflow if the UI is complex. + +**Keywords:** simple, basic, small feature, add, minor + +--- + +### Level 2: Medium Project + +**Examples:** Admin dashboard, customer portal, reporting system + +| Aspect | Details | +| ------------------- | ----------------------------------------------------------- | +| **Stories** | 5-15 stories across multiple epics | +| **Planning Docs** | PRD + Epics | +| **Architecture** | Optional - lightweight architecture if system design needed | +| **UX Design** | Optional - recommended for UI-heavy projects | +| **Epic-Tech-Specs** | Recommended during implementation per epic | +| **Best For** | Multiple related features, focused products | +| **Brownfield Prep** | Run document-project first (if not already done) | + +**Workflow:** + +``` +(Brownfield: document-project first) +↓ +Analysis (recommended) → PRD + Epics → (Optional) UX Design → (Optional) Architecture → Implement + ↓ + Epic-Tech-Spec per epic (recommended) + ↓ + Retrospective after each epic (if >1 epic) +``` + +**Architecture Note:** Level 2 uses optional **Architecture document** (not tech-spec) if system design is needed. For projects that don't need architecture, PRD + Epics are sufficient. + +**Epic-Tech-Specs:** As you implement each epic, create epic-tech-spec for detailed technical guidance. If you have 3 epics, you'll create 3 epic-tech-specs during implementation. + +**Retrospectives:** After completing each epic (when there are multiple), run retrospective to capture learnings before starting the next epic. + +**Keywords:** dashboard, several features, admin panel, medium + +--- + +### Level 3: Complex System + +**Examples:** E-commerce platform, SaaS product, multi-module system + +| Aspect | Details | +| ------------------- | -------------------------------------------------- | +| **Stories** | 12-40 stories with subsystems | +| **Planning Docs** | PRD + Epics + System Architecture | +| **Architecture** | Required - comprehensive system design | +| **UX Design** | Recommended for user-facing systems | +| **Epic-Tech-Specs** | Recommended during implementation per epic | +| **Gate Checks** | Required - validate cohesion before implementation | +| **Best For** | Complex integrations, multi-subsystem products | +| **Brownfield Prep** | Run document-project first (if not already done) | + +**Workflow:** + +``` +(Brownfield: document-project first) +↓ +Analysis + Research → PRD + Epics → (Recommended) UX Design → Architecture (required) → Gate Check → Implement + ↓ + Epic-Tech-Spec per epic (recommended) + ↓ + Retrospective after each epic +``` + +**Gate Check:** Validates PRD + UX + Architecture cohesion before starting implementation. Prevents costly rework. + +**Epic-Tech-Specs:** For complex epics, create detailed epic-tech-spec before implementation. These provide code-level design decisions that Architecture doesn't cover. + +**Additional Detail Docs:** For very novel or complex subsystems, you may create additional technical design documents beyond epic-tech-specs. These are created as-needed, not upfront. + +**Keywords:** platform, integration, complex, system, architecture + +--- + +### Level 4: Enterprise Scale + +**Examples:** Multi-product suite, enterprise ecosystem, platform with multiple apps + +| Aspect | Details | +| ------------------- | -------------------------------------------------------------- | +| **Stories** | 40+ stories across products | +| **Planning Docs** | Comprehensive PRD + Epics + Enterprise Architecture | +| **Architecture** | Required - enterprise-grade system design | +| **UX Design** | Recommended - design system and patterns | +| **Epic-Tech-Specs** | Recommended during implementation per epic | +| **Gate Checks** | Required - multiple validation gates | +| **Best For** | Multi-tenant systems, product ecosystems, enterprise platforms | +| **Brownfield Prep** | Run document-project first (if not already done) | + +**Workflow:** + +``` +(Brownfield: document-project first) +↓ +Analysis + Research → PRD + Epics → UX Design → Enterprise Architecture → Gate Check → Implement + ↓ + Epic-Tech-Spec per epic (recommended) + ↓ + Additional design docs for complex subsystems + ↓ + Retrospective after each epic +``` + +**Enterprise Architecture:** More comprehensive than Level 3, includes: + +- Multi-tenancy design +- Security architecture +- Scalability planning +- Integration architecture +- Data architecture +- Deployment architecture + +**Additional Design Documents:** For enterprise complexity, you may need supplementary technical documents: + +- Detailed subsystem designs +- Integration specifications +- Performance optimization plans +- Security implementation guides + +These are created **during implementation** as needed, not all upfront. + +**Keywords:** enterprise, multi-tenant, multiple products, ecosystem, scale + +--- + +## Workflow Comparison + +| Level | Analysis | Planning | Architecture | Epic-Tech-Specs | Stories | Retrospectives | +| ----- | ----------- | ---------------- | ------------ | ----------------- | ------- | ----------------------- | +| **0** | Optional | Tech-spec | None | N/A (no epics) | 1 | N/A | +| **1** | Optional | Tech-spec + Epic | None | N/A (single epic) | 2-3 | N/A | +| **2** | Recommended | PRD | Optional | Recommended | 5-15 | After each epic (if >1) | +| **3** | Required | PRD | Required | Recommended | 12-40 | After each epic | +| **4** | Required | PRD | Required | Recommended | 40+ | After each epic | + +--- + +## Documentation Progression + +### Level 0-1: Tech-Spec as Primary Doc + +**Why tech-spec for Level 0-1?** + +- Changes are focused and atomic +- Context is specific to implementation +- Speed is priority +- Full product planning is overkill + +**Tech-spec contents:** + +- Technical approach +- File-level changes +- Implementation guide +- Testing strategy +- **Includes UX considerations** if user-facing + +**Created:** Upfront, serves as complete planning doc + +--- + +### Level 2: PRD + Optional Architecture + +**Why PRD instead of tech-spec?** + +- Multiple features need coordination +- Product vision and requirements matter +- Stakeholder alignment needed +- Feature interdependencies exist + +**PRD contents:** + +- Product vision and goals +- Feature requirements +- Epics and story breakdown +- Success criteria +- User experience considerations + +**Architecture (optional):** + +- Only if system design needed +- Lightweight architectural decisions +- Component interactions +- Data models + +**Epic-tech-specs (recommended during implementation):** + +- Created as each epic is worked on +- Detailed technical guidance per epic +- Supplements PRD with implementation details + +**Created:** PRD upfront, epic-tech-specs during implementation + +--- + +### Level 3-4: PRD + Architecture + Epic-Tech-Specs + +**Why comprehensive planning?** + +- Complex integrations +- Multiple subsystems +- Long-term maintainability +- Risk management +- Team coordination + +**PRD contents:** + +- Comprehensive product vision +- Detailed requirements +- Business objectives +- Market considerations +- Complete epic breakdown + +**Architecture (required):** + +- System design +- Component architecture +- Data models +- Integration patterns +- Security design +- Performance requirements +- **Scales with complexity** (Level 3 vs Level 4) + +**Epic-tech-specs (recommended during implementation):** + +- Created before implementing each epic +- Code-level design decisions +- Epic-specific implementation approach +- Detailed testing strategy + +**Additional design docs (as-needed):** + +- For novel or complex subsystems +- Created during implementation +- Not all created upfront +- Examples: detailed integration specs, performance optimization plans + +**Created:** PRD + Architecture upfront, epic-tech-specs and detail docs during implementation + +--- + +## Brownfield Projects: Document-Project First + +### Critical Workflow Step + +🚨 **For ALL brownfield projects (Level 0-4):** + +**BEFORE running any workflow:** + +1. Run `document-project` workflow +2. This analyzes your codebase and creates `docs/index.md` +3. Output includes sharded documentation of: + - Project structure + - Key modules + - Existing patterns + - Dependencies + - Configuration + +**Why it's critical:** + +- **Tech-spec workflow** (Level 0-1) uses this for auto-detection +- **PRD workflow** (Level 2-4) references existing code +- **Architecture workflow** (Level 3-4) builds on existing structure +- **Epic-tech-specs** reference existing implementations + +### Brownfield Workflow Pattern + +``` +Step 1: document-project (FIRST!) + ↓ + Creates docs/index.md with codebase analysis + ↓ +Step 2: workflow-init OR tech-spec directly + ↓ + Uses docs/index.md for context + ↓ +Step 3: Continue with level-appropriate workflows +``` + +**Without document-project:** + +- Workflows can't detect existing patterns +- Convention analysis won't work +- Integration planning is incomplete +- You'll miss existing code to reuse + +--- + +## Tech-Spec vs Epic-Tech-Spec + +### When to Use Each + +| Document | Level | Created When | Purpose | +| ------------------ | ----- | ------------------------ | ----------------------------------------------- | +| **Tech-Spec** | 0-1 | Upfront (Planning Phase) | Primary planning doc for small changes/features | +| **Epic-Tech-Spec** | 2-4 | During Implementation | Detailed technical guidance per epic | + +### Tech-Spec (Level 0-1) + +**Characteristics:** + +- Created in Planning Phase +- Serves as primary/only planning document +- Comprehensive for the entire change/feature +- Includes all context needed for implementation +- Can include UX considerations inline + +**Workflow context:** + +``` +Planning Phase: Tech-Spec created here + ↓ +Implementation Phase: Stories implemented using tech-spec +``` + +### Epic-Tech-Spec (Level 2-4) + +**Characteristics:** + +- Created in Implementation Phase +- Supplements PRD + Architecture +- Focused on single epic +- Detailed code-level design +- References architecture decisions + +**Workflow context:** + +``` +Planning Phase: PRD + Architecture created here + ↓ +Implementation Phase: + - Epic 1 starts + - Create epic-tech-spec-1 (just-before-implementation) + - Implement stories for epic 1 + - Retrospective + - Epic 2 starts + - Create epic-tech-spec-2 + - Implement stories for epic 2 + - Retrospective + - ... +``` + +**Why not created upfront?** + +- Implementation learnings inform later epic-tech-specs +- Avoids over-planning details that may change +- Keeps specs fresh and relevant +- Retrospectives provide input for next epic-tech-spec + +--- + +## Level 2 Architecture vs Tech-Spec + +### The Question + +"What takes the place of architecture with Level 2 since there is no tech-spec?" + +### The Answer + +Level 2 uses **Architecture document (optional)** instead of tech-spec for system-level planning. + +**Comparison:** + +| Aspect | Tech-Spec (Level 0-1) | Architecture (Level 2) | +| ------------ | ------------------------------------ | ---------------------------------- | +| **Purpose** | Implementation plan for small change | System design for medium project | +| **Scope** | Single change or small feature | Multiple epics and features | +| **Focus** | Code-level details | System-level design | +| **When** | Replaces need for PRD+Arch | Supplements PRD | +| **Required** | Yes (primary doc) | Optional (if system design needed) | + +**Level 2 Documentation Options:** + +**Option A: PRD Only (no architecture)** + +- For projects that don't need system design +- Features are independent +- No complex integrations +- Example: Admin dashboard with CRUD screens + +**Option B: PRD + Architecture** + +- For projects needing system design +- Components interact +- Integrations exist +- Example: Customer portal with notifications, webhooks, reporting + +**Plus Epic-Tech-Specs (recommended):** + +- Created during implementation +- One per epic +- Detailed technical guidance +- References Architecture decisions (if architecture exists) + +--- + +## Retrospectives in Multi-Epic Projects + +### When to Run Retrospectives + +**Trigger:** After completing each epic in Level 2-4 projects **when there are multiple epics** + +**Example:** + +- Level 2 project with 3 epics +- Complete Epic 1 → Retrospective +- Complete Epic 2 → Retrospective +- Complete Epic 3 → Final retrospective + +**Purpose:** + +- Capture learnings from completed epic +- Identify improvements for next epic +- Adjust approach based on what worked/didn't +- Feed insights into next epic-tech-spec + +### Retrospective Contents + +- What went well? +- What could be improved? +- Technical insights gained +- Process adjustments needed +- Input for next epic planning + +**Output feeds into:** + +- Next epic-tech-spec +- Architecture refinements +- Team process improvements + +--- + +## How Level Detection Works + +### Automatic Detection (workflow-init) + +When you run `workflow-init`, it analyzes your project description using: + +#### 1. **Keyword Analysis** + +Scans for level-specific keywords: + +**Level 0 Keywords:** + +- fix, bug, typo, small change, quick update, patch + +**Level 1 Keywords:** + +- simple, basic, small feature, add, minor + +**Level 2 Keywords:** + +- dashboard, several features, admin panel, medium + +**Level 3 Keywords:** + +- platform, integration, complex, system, architecture + +**Level 4 Keywords:** + +- enterprise, multi-tenant, multiple products, ecosystem, scale + +#### 2. **Story Count Estimation** + +Asks about expected scope: + +| Level | Story Range | +| ------- | ------------- | +| Level 0 | 1 story | +| Level 1 | 1-10 stories | +| Level 2 | 5-15 stories | +| Level 3 | 12-40 stories | +| Level 4 | 40+ stories | + +#### 3. **Complexity Indicators** + +- Multiple teams involved? +- External integrations? +- Compliance requirements? +- Multi-tenant needs? +- Existing system modifications? (triggers brownfield) + +### Manual Override + +You can always override the detected level if workflow-init gets it wrong. The system is a guide, not a constraint. + +--- + +## Field Types: Greenfield vs Brownfield + +Each level has **two workflow paths**: + +### Greenfield (New Project) + +- Starting from scratch +- No existing codebase +- Establishing new patterns +- Freedom to choose stack + +**Special Features:** + +- Starter template recommendations +- Modern best practices via WebSearch +- Convention establishment + +**Workflow:** + +``` +workflow-init → Level detection → Greenfield path +``` + +### Brownfield (Existing Project) + +- Adding to existing code +- Working with established patterns +- Integration with current systems +- Stack already chosen + +**Special Features:** + +- Auto-detects existing conventions +- Analyzes current patterns +- Confirms before deviating +- Respects established standards + +**Workflow:** + +``` +document-project (FIRST!) → workflow-init → Level detection → Brownfield path +``` + +**Critical difference:** Brownfield requires document-project BEFORE any other workflow. + +--- + +## Common Scenarios + +### Scenario 1: Bug Fix (Level 0) + +**Input:** "Fix email validation bug in login form" + +**Detection:** + +- Keywords: "fix", "bug" +- Estimated stories: 1 + +**Result:** Level 0 → Greenfield-level-0.yaml + +**Workflow:** + +1. (Optional) Brief analysis +2. Tech-spec with single story +3. Implement immediately + +--- + +### Scenario 2: Small Feature (Level 1) + +**Input:** "Add OAuth social login (Google, GitHub, Facebook)" + +**Detection:** + +- Keywords: "add", "feature" +- Estimated stories: 2-3 + +**Result:** Level 1 → Greenfield-level-1.yaml + +**Workflow:** + +1. (Optional) Research OAuth providers +2. Tech-spec with epic + 3 stories +3. (Optional) UX Design if UI is complex +4. Implement story-by-story + +--- + +### Scenario 3: Customer Portal (Level 2) + +**Input:** "Build customer portal with dashboard, tickets, billing" + +**Detection:** + +- Keywords: "portal", "dashboard" +- Estimated stories: 10-12 + +**Result:** Level 2 → Greenfield-level-2.yaml + +**Workflow:** + +1. Product Brief (recommended) +2. PRD with epics +3. (Optional) UX Design +4. (Optional) Architecture if system design needed +5. Implement with sprint planning +6. Create epic-tech-spec for each epic as you implement +7. Run retrospective after each epic + +--- + +### Scenario 4: E-commerce Platform (Level 3) + +**Input:** "Build full e-commerce platform with products, cart, checkout, admin, analytics" + +**Detection:** + +- Keywords: "platform", "full" +- Estimated stories: 30-35 + +**Result:** Level 3 → Greenfield-level-3.yaml + +**Workflow:** + +1. Research + Product Brief +2. Comprehensive PRD +3. UX Design (recommended) +4. System Architecture (required) +5. Gate check +6. Implement with phased approach +7. Create epic-tech-spec per epic before implementing +8. Run retrospective after each epic +9. Create additional design docs as needed for complex subsystems + +--- + +### Scenario 5: Adding Feature to Existing App (Brownfield) + +**Input:** "Add search functionality to existing product catalog" + +**Detection:** + +- Keywords: "add", "existing" +- Estimated stories: 3-4 +- Field type: Brownfield + +**Result:** Level 1 → Brownfield-level-1.yaml + +**Critical First Step:** + +1. **Run document-project** to analyze existing codebase + +**Then Workflow:** 2. Tech-spec (uses document-project output for analysis) 3. Auto-detects existing patterns 4. Confirms conventions 5. Implement following existing patterns + +--- + +## Workflow Paths Configuration + +BMad Method stores workflow paths in YAML configuration files: + +### Path File Structure + +``` +src/modules/bmm/workflows/workflow-status/paths/ +├── greenfield-level-0.yaml +├── greenfield-level-1.yaml +├── greenfield-level-2.yaml +├── greenfield-level-3.yaml +├── greenfield-level-4.yaml +├── brownfield-level-0.yaml +├── brownfield-level-1.yaml +├── brownfield-level-2.yaml +├── brownfield-level-3.yaml +├── brownfield-level-4.yaml +├── game-design.yaml +└── project-levels.yaml (source of truth) +``` + +### Path File Format + +Each path file defines: + +```yaml +project_type: 'software' +level: 2 +field_type: 'greenfield' +description: 'Medium project - multiple epics' + +phases: + - phase: 1 + name: 'Analysis' + optional: true + workflows: + - id: 'brainstorm-project' + optional: true + agent: 'analyst' + command: 'brainstorm-project' + + - phase: 2 + name: 'Planning' + required: true + workflows: + - id: 'prd' + required: true + agent: 'pm' + command: 'prd' + output: 'Creates PRD with epics and stories' +``` + +### Phase Structure + +Each level defines **4 phases**: + +1. **Analysis Phase** + - Brainstorming + - Research + - Product Brief + - Complexity: Increases with level + +2. **Planning Phase** + - Level 0-1: Tech-spec + - Level 2-4: PRD + (optional/required) Architecture + +3. **Solutioning Phase** + - Level 0-2: Skipped or optional architecture + - Level 3-4: Required architecture + gate checks + +4. **Implementation Phase** + - Sprint planning + - Story-by-story development + - Epic-tech-specs created per epic (Level 2-4) + - Retrospectives after each epic (Level 2-4) + +--- + +## Best Practices + +### 1. **Document-Project First for Brownfield** + +Always run document-project before starting any brownfield workflow. This is critical for context. + +### 2. **Trust the Detection** + +If workflow-init suggests Level 2, there's probably complexity you haven't considered. Review before overriding. + +### 3. **Start Small, Upgrade Later** + +Uncertain between Level 1 and 2? Start with Level 1. You can always run PRD creation later if needed. + +### 4. **Don't Skip Gate Checks** + +For Level 3-4, gate checks prevent costly mistakes. Invest the time upfront. + +### 5. **Create Epic-Tech-Specs Just-Before-Implementation** + +For Level 2-4, create epic-tech-spec right before implementing each epic. Don't create all upfront. + +### 6. **Run Retrospectives Between Epics** + +Capture learnings after each epic. Feed insights into next epic-tech-spec. + +### 7. **Optional UX for Level 1** + +If your Level 1 feature has complex UI, run separate UX Design. Otherwise, include UX notes in tech-spec. + +### 8. **Architecture Scales** + +Level 2 architecture is lighter than Level 3, which is lighter than Level 4. Don't over-architect. + +--- + +## FAQ + +### Q: What's the difference between tech-spec and epic-tech-spec? + +**A:** + +- **Tech-spec (Level 0-1):** Created upfront in Planning Phase, serves as primary planning doc +- **Epic-tech-spec (Level 2-4):** Created during Implementation Phase per epic, supplements PRD + Architecture + +### Q: Why no tech-spec at Level 2+? + +**A:** At Level 2+, you need product-level planning (PRD) and optionally system-level design (Architecture). Tech-spec is too narrow. Instead, use epic-tech-specs during implementation for detailed technical guidance per epic. + +### Q: Do I always need Architecture at Level 2? + +**A:** No, it's optional. Only create Architecture if you need system-level design. Many Level 2 projects can work with just PRD + epic-tech-specs. + +### Q: What if I forget to run document-project on brownfield? + +**A:** Workflows will lack context about existing code. Run document-project and restart your workflow to get proper brownfield analysis. + +### Q: Can Level 1 include UX Design? + +**A:** Yes! You can either: + +- Include UX considerations in the tech-spec (simpler) +- Run separate UX Design workflow (complex UI) + +### Q: When do I create additional design documents? + +**A:** Create them during implementation as-needed for: + +- Very novel technical approaches +- Complex subsystems needing detailed design +- Integration specifications +- Performance optimization plans + +Don't create them all upfront - create just-before-needed. + +### Q: Can I change levels mid-project? + +**A:** Yes! If you started at Level 1 but realize it's Level 2, you can run `create-prd` to add proper planning docs. The system is flexible. + +--- + +## Summary + +The Scale Adaptive System ensures: + +✅ **Level 0-1:** Fast, lean, tech-spec only → Quick Spec Flow +✅ **Level 2:** Structured, PRD-driven, optional architecture, epic-tech-specs during implementation +✅ **Level 3-4:** Comprehensive, PRD + Architecture required, epic-tech-specs per epic, gate checks + +**Key Principles:** + +- Match planning depth to project complexity +- Tech-spec for Level 0-1, PRD + Architecture for Level 2-4 +- Epic-tech-specs supplement Level 2-4 during implementation +- Document-project FIRST for all brownfield projects +- Create detailed docs just-before-needed, not all upfront + +**Result:** Right amount of ceremony for every project, maximum efficiency at every scale. + +--- + +## Learn More + +- **Quick Spec Flow (Level 0-1):** [docs/quick-spec-flow.md](./quick-spec-flow.md) +- **Full BMM Workflows (Level 2-4):** [src/modules/bmm/workflows/README.md](../src/modules/bmm/workflows/README.md) +- **Document-Project Workflow:** Ask SM agent to run document-project +- **Run workflow-init:** Load PM agent and ask to run workflow-init +- **Path Configuration:** `src/modules/bmm/workflows/workflow-status/paths/` +- **Level Definitions:** `src/modules/bmm/workflows/workflow-status/project-levels.yaml` + +--- + +_Scale Adaptive System - Because one size doesn't fit all._ diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md index cb93baaa..13af9f99 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md @@ -1,11 +1,13 @@ # Tech-Spec Workflow Validation Checklist -**Purpose**: Validate tech-spec workflow outputs are definitive, complete, and implementation-ready. +**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready. **Scope**: Levels 0-1 software projects **Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1) +**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects + --- ## 1. Output Files Exist @@ -14,38 +16,107 @@ - [ ] Story file(s) created in dev_story_location - Level 0: 1 story file (story-{slug}.md) - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md) -- [ ] bmm-workflow-status.md updated to Phase 4 -- [ ] No unfilled {{template_variables}} +- [ ] bmm-workflow-status.yaml updated (if not standalone mode) +- [ ] No unfilled {{template_variables}} in any files --- -## 2. Tech-Spec Definitiveness (CRITICAL) +## 2. Context Gathering (NEW - CRITICAL) + +### Document Discovery + +- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist) +- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map) +- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized +- [ ] **Context summary**: loaded_documents_summary lists all sources used + +### Project Stack Detection + +- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed +- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2") +- [ ] **Dependencies extracted**: All production dependencies with specific versions +- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions +- [ ] **Scripts documented**: Available npm/pip/etc scripts identified +- [ ] **Stack summary**: project_stack_summary is complete and accurate + +### Brownfield Analysis (if applicable) + +- [ ] **Directory structure**: Main code directories identified and documented +- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.) +- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.) +- [ ] **Key modules**: Important existing modules/services identified +- [ ] **Testing patterns**: Test framework and patterns documented +- [ ] **Structure summary**: existing_structure_summary is comprehensive + +--- + +## 3. Tech-Spec Definitiveness (CRITICAL) ### No Ambiguity Allowed - [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include" - [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions - - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2" + - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)" - ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston" - [ ] **Definitive decisions**: Every technical choice is final, not a proposal +- [ ] **Stack-aligned**: Decisions reference detected project stack ### Implementation Clarity -- [ ] Source tree shows EXACT file paths (not "somewhere in src/") -- [ ] Each file marked as create/modify/delete -- [ ] Technical approach describes SPECIFIC implementation -- [ ] Implementation stack has complete toolchain with versions +- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions + - ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method" + - ❌ BAD: "Update some files in the services folder" +- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack +- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable) +- [ ] **Integration points**: Specific modules, APIs, services identified --- -## 3. Story Quality +## 4. Context-Rich Content (NEW) + +### Context Section + +- [ ] **Available Documents**: Lists all loaded documents +- [ ] **Project Stack**: Complete framework and dependency information +- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation + +### The Change Section + +- [ ] **Problem Statement**: Clear, specific problem definition +- [ ] **Proposed Solution**: Concrete solution approach +- [ ] **Scope In/Out**: Clear boundaries defined + +### Development Context Section + +- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield) +- [ ] **Framework Dependencies**: Complete list with exact versions from project +- [ ] **Internal Dependencies**: Internal modules listed +- [ ] **Configuration Changes**: Specific config file updates identified + +### Developer Resources Section + +- [ ] **File Paths Reference**: Complete list of all files involved +- [ ] **Key Code Locations**: Functions, classes, modules with file:line references +- [ ] **Testing Locations**: Specific test directories and patterns +- [ ] **Documentation Updates**: Docs that need updating identified + +--- + +## 5. Story Quality ### Story Format - [ ] All stories use "As a [role], I want [capability], so that [benefit]" format - [ ] Each story has numbered acceptance criteria - [ ] Tasks reference AC numbers: (AC: #1), (AC: #2) -- [ ] Dev Notes section links back to tech-spec.md +- [ ] Dev Notes section links to tech-spec.md + +### Story Context Integration (NEW) + +- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context +- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.) +- [ ] **Test Results section**: Placeholder ready for dev execution +- [ ] **Review Notes section**: Placeholder ready for code review ### Story Sequencing (If Level 1) @@ -56,38 +127,66 @@ ### Coverage -- [ ] Story acceptance criteria derived from tech-spec testing section +- [ ] Story acceptance criteria derived from tech-spec - [ ] Story tasks map to tech-spec implementation guide - [ ] Files in stories match tech-spec source tree +- [ ] Key code references align with tech-spec Developer Resources --- -## 4. Workflow Status Integration +## 6. Epic Quality (Level 1 Only) -- [ ] bmm-workflow-status.md shows current_phase = "4-Implementation" -- [ ] Phase 2 ("2-Plan") marked complete -- [ ] First story in TODO section, others in BACKLOG (if Level 1) -- [ ] Next action clear (review story, run story-ready) +- [ ] **Epic title**: User-focused outcome (not implementation detail) +- [ ] **Epic slug**: Clean kebab-case slug (2-3 words) +- [ ] **Epic goal**: Clear purpose and value statement +- [ ] **Epic scope**: Boundaries clearly defined +- [ ] **Success criteria**: Measurable outcomes +- [ ] **Story map**: Visual representation of epic → stories +- [ ] **Implementation sequence**: Logical story ordering with dependencies +- [ ] **Tech-spec reference**: Links back to tech-spec.md --- -## 5. Readiness for Implementation +## 7. Workflow Status Integration -- [ ] Developer can start coding from tech-spec alone -- [ ] All technical questions answered definitively -- [ ] Testing approach clear and verifiable -- [ ] Deployment strategy documented +- [ ] bmm-workflow-status.yaml updated (if exists) +- [ ] Current phase reflects tech-spec completion +- [ ] Progress percentage updated appropriately +- [ ] Next workflow clearly identified --- -## 6. Critical Failures (Auto-Fail) +## 8. Implementation Readiness (NEW - ENHANCED) + +### Can Developer Start Immediately? + +- [ ] **All context available**: Brownfield analysis + stack details + existing patterns +- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns +- [ ] **Specific file paths**: Developer knows exactly which files to create/modify +- [ ] **Code references**: Can find similar code to reference (brownfield) +- [ ] **Testing clear**: Knows what to test and how +- [ ] **Deployment documented**: Knows how to deploy and rollback + +### Tech-Spec Replaces Story-Context? + +- [ ] **Comprehensive enough**: Contains all info typically in story-context XML +- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance +- [ ] **Framework specifics**: Exact versions and usage patterns +- [ ] **Pattern guidance**: Shows examples of existing patterns to follow + +--- + +## 9. Critical Failures (Auto-Fail) - [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices) - [ ] ❌ **Missing versions** (framework/library without specific version) -- [ ] ❌ **Stories don't match template** (incompatible with story-context/dev-story workflows) -- [ ] ❌ **Missing tech-spec sections** (required section missing from tech-spec.md) +- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.) +- [ ] ❌ **Stack mismatch** (decisions don't align with detected project stack) +- [ ] ❌ **Stories don't match template** (missing Dev Agent Record sections) +- [ ] ❌ **Missing tech-spec sections** (required section missing from enhanced template) - [ ] ❌ **Stories have forward dependencies** (would break sequential implementation) -- [ ] ❌ **Vague source tree** (file changes not specific) +- [ ] ❌ **Vague source tree** (file changes not specific with actions) +- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used) --- @@ -95,13 +194,21 @@ **Document any findings:** -- Definitiveness score: [All definitive / Some ambiguity / Significant ambiguity] -- Strengths: -- Issues to address: -- Recommended actions: +- **Context Gathering Score**: [Comprehensive / Partial / Insufficient] +- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity] +- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing] +- **Stack Alignment**: [Perfect / Good / Partial / None] + +## **Strengths:** + +## **Issues to address:** + +## **Recommended actions:** **Ready for implementation?** [Yes / No - explain] +**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A] + --- -_Adapt based on Level 0 vs Level 1. Focus on definitiveness above all else._ +_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._ diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md index 1c11e888..0047785f 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md @@ -1,11 +1,58 @@ # {{project_name}} - Epic Breakdown -## Epic Overview - -{{epic_overview}} +**Date:** {{date}} +**Project Level:** {{project_level}} --- -## Epic Details +## Epic: {{epic_title}} -{{epic_details}} +**Slug:** {{epic_slug}} + +### Goal + +{{epic_goal}} + +### Scope + +{{epic_scope}} + +### Success Criteria + +{{epic_success_criteria}} + +### Dependencies + +{{epic_dependencies}} + +--- + +## Story Map + +{{story_map}} + +--- + +## Story Summaries + +{{story_summaries}} + +--- + +## Implementation Timeline + +**Total Story Points:** {{total_points}} + +**Estimated Timeline:** {{estimated_timeline}} + +--- + +## Implementation Sequence + +{{implementation_sequence}} + +--- + +## Tech-Spec Reference + +See [tech-spec.md](../tech-spec.md) for complete technical implementation details. diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md index 636986e0..49d2e65f 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md @@ -10,12 +10,23 @@ Read the completed tech-spec.md file from {output_folder}/tech-spec.md -Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md +Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists) Extract dev_story_location from config (where stories are stored) -Extract the problem statement from "Technical Approach" section -Extract the scope from "Source Tree Structure" section -Extract time estimate from "Implementation Guide" or technical details -Extract acceptance criteria from "Testing Approach" section + +Extract from the ENHANCED tech-spec structure: + +- Problem statement from "The Change → Problem Statement" section +- Solution overview from "The Change → Proposed Solution" section +- Scope from "The Change → Scope" section +- Source tree from "Implementation Details → Source Tree Changes" section +- Time estimate from "Implementation Guide → Implementation Steps" section +- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section +- Framework dependencies from "Development Context → Framework/Libraries" section +- Existing code references from "Development Context → Relevant Existing Code" section +- File paths from "Developer Resources → File Paths Reference" section +- Key code locations from "Developer Resources → Key Code Locations" section +- Testing locations from "Developer Resources → Testing Locations" section + @@ -76,9 +87,18 @@ **Dev Notes:** - Extract technical constraints from tech-spec -- Include file paths from "Source Tree Structure" +- Include file paths from "Developer Resources → File Paths Reference" +- Include existing code references from "Development Context → Relevant Existing Code" - Reference architecture patterns if applicable - Cite tech-spec sections for implementation details +- Note dependencies (internal and external) + +**NEW: Comprehensive Context** + +Since tech-spec is now context-rich, populate all new template fields: + +- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points" +- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations" Initialize story file using user_story_template @@ -94,6 +114,8 @@ test_locations story_points time_estimate +dependencies +existing_code_references architecture_references @@ -135,29 +157,40 @@ **Story Location:** `{story_path}` -**Next Steps (choose one path):** +**Next Steps:** -**Option A - Full Context (Recommended for complex changes):** +**🎯 RECOMMENDED - Direct to Development (Level 0):** -1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md` -2. Run story-context workflow -3. Then load DEV agent and run dev-story workflow +Since the tech-spec is now CONTEXT-RICH with: -**Option B - Direct to Dev (For simple, well-understood changes):** +- ✅ Brownfield codebase analysis (if applicable) +- ✅ Framework and library details with exact versions +- ✅ Existing patterns and code references +- ✅ Complete file paths and integration points + +**You can skip story-context and go straight to dev!** 1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md` -2. Run dev-story workflow (will auto-discover story) -3. Begin implementation +2. Run `dev-story` workflow +3. Begin implementation immediately + +**Option B - Generate Additional Context (optional):** + +Only needed for extremely complex scenarios: + +1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md` +2. Run `story-context` workflow (generates additional XML context) +3. Then load DEV agent and run `dev-story` workflow **Progress Tracking:** -- All decisions logged in: `bmm-workflow-status.md` +- All decisions logged in: `bmm-workflow-status.yaml` - Next action clearly identified Ready to proceed? Choose your path: -1. Generate story context (Option A - recommended) -2. Go directly to dev-story implementation (Option B - faster) +1. Go directly to dev-story (RECOMMENDED - tech-spec has all context) +2. Generate additional story context (for complex edge cases) 3. Exit for now Select option (1-3): diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md index 258f3c33..843ab9e6 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md @@ -11,12 +11,23 @@ Read the completed tech-spec.md file from {output_folder}/tech-spec.md -Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md +Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists) Extract dev_story_location from config (where stories are stored) -Identify all implementation tasks from the "Implementation Guide" section -Identify the overall feature goal from "Technical Approach" section -Extract time estimates for each implementation phase -Identify any dependencies between implementation tasks + +Extract from the ENHANCED tech-spec structure: + +- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution" +- Implementation tasks from "Implementation Guide → Implementation Steps" +- Time estimates from "Implementation Guide → Implementation Steps" +- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies" +- Source tree from "Implementation Details → Source Tree Changes" +- Framework dependencies from "Development Context → Framework/Libraries" +- Existing code references from "Development Context → Relevant Existing Code" +- File paths from "Developer Resources → File Paths Reference" +- Key code locations from "Developer Resources → Key Code Locations" +- Testing locations from "Developer Resources → Testing Locations" +- Acceptance criteria from "Implementation Guide → Acceptance Criteria" + @@ -60,6 +71,9 @@ Initialize epics.md summary document using epics_template +Also capture project_level for the epic template + +project_level epic_title epic_slug epic_goal @@ -113,6 +127,25 @@ - Include technical acceptance criteria from tech spec tasks - Link back to tech spec sections for implementation details +**CRITICAL: Acceptance Criteria Must Be:** + +1. **Numbered** - AC #1, AC #2, AC #3, etc. +2. **Specific** - No vague statements like "works well" or "is fast" +3. **Testable** - Can be verified objectively +4. **Complete** - Covers all success conditions +5. **Independent** - Each AC tests one thing +6. **Format**: Use Given/When/Then when applicable + +**Good AC Examples:** +✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds +✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message +✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage + +**Bad AC Examples:** +❌ "User can create account" (too vague) +❌ "System performs well" (not measurable) +❌ "Works correctly" (not specific) + **Story Point Estimation:** - 1 point = < 1 day (2-4 hours) @@ -134,7 +167,14 @@ - Acceptance Criteria: Numbered list from tech spec - Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references) - Dev Notes: Technical summary, project structure notes, references -- Dev Agent Record: Empty sections for context workflow to populate +- Dev Agent Record: Empty sections (tech-spec provides context) + +**NEW: Comprehensive Context Fields** + +Since tech-spec is context-rich, populate ALL template fields: + +- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points" +- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations" @@ -149,10 +189,12 @@ - acceptance_criteria: Specific, measurable criteria from tech spec - tasks_subtasks: Implementation tasks with AC references - technical_summary: High-level approach, key decisions - - files_to_modify: List of files that will change - - test_locations: Where tests will be added + - files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference") + - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations") - story_points: Estimated effort (1/2/3/5) - time_estimate: Days/hours estimate + - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points") + - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations") - architecture_references: Links to tech-spec.md sections @@ -161,12 +203,35 @@ - + -Generate visual story map showing epic → stories hierarchy +Stories MUST be ordered so earlier stories don't depend on later ones +Each story must have CLEAR, TESTABLE acceptance criteria + +Analyze dependencies between stories: + +**Dependency Rules:** + +1. Infrastructure/setup → Feature implementation → Testing/polish +2. Database changes → API changes → UI changes +3. Backend services → Frontend components +4. Core functionality → Enhancement features +5. No story can depend on a later story! + +**Validate Story Sequence:** +For each story N, check: + +- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID +- Does it only use things from Story 1...N-1? ✅ VALID +- Can it be implemented independently or using only prior stories? ✅ VALID + +If invalid dependencies found, REORDER stories! + + +Generate visual story map showing epic → stories hierarchy with dependencies Calculate total story points across all stories Estimate timeline based on total points (1-2 points per day typical) -Define implementation sequence considering dependencies +Define implementation sequence with explicit dependency notes ## Story Map @@ -174,7 +239,10 @@ ``` Epic: Icon Reliability ├── Story 1: Build Icon Infrastructure (3 points) +│ Dependencies: None (foundational work) +│ └── Story 2: Test and Deploy Icons (2 points) + Dependencies: Story 1 (requires infrastructure) ``` **Total Story Points:** 5 @@ -183,8 +251,15 @@ Epic: Icon Reliability ## Implementation Sequence 1. **Story 1** → Build icon infrastructure (setup, download, configure) + - Dependencies: None + - Deliverable: Icon files downloaded, organized, accessible + 2. **Story 2** → Test and deploy (depends on Story 1) - + - Dependencies: Story 1 must be complete + - Deliverable: Icons verified, tested, deployed to production + +**Dependency Validation:** ✅ Valid sequence - no forward dependencies + story_summaries story_map @@ -214,12 +289,90 @@ Epic: Icon Reliability - + -Confirm all stories map to tech spec implementation tasks +Auto-run validation - NOT optional! + +Running automatic story validation... + +**Validate Story Sequence (CRITICAL):** + +For each story, check: + +1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required! +2. Are dependencies clearly documented? ✅ PASS +3. Can stories be implemented in order 1→2→3? ✅ PASS + +If sequence validation FAILS: + +- Identify the problem dependencies +- Propose new ordering +- Ask user to confirm reordering + + +**Validate Acceptance Criteria Quality:** + +For each story's AC, check: + +1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required +2. Is it specific and testable? ✅ Required +3. Does it use Given/When/Then or equivalent? ✅ Recommended +4. Are all success conditions covered? ✅ Required + +Count vague AC (contains "works", "good", "fast", "well"): + +- 0 vague AC: ✅ EXCELLENT +- 1-2 vague AC: ⚠️ WARNING - Should improve +- 3+ vague AC: ❌ FAIL - Must improve + + +**Validate Story Completeness:** + +1. Do all stories map to tech spec tasks? ✅ Required +2. Do story points align with tech spec estimates? ✅ Recommended +3. Are dependencies clearly noted? ✅ Required +4. Does each story have testable AC? ✅ Required + + +Generate validation report + + + ❌ **Story Validation Failed:** + +{{issues_found}} + +**Recommended Fixes:** +{{recommended_fixes}} + +Shall I fix these issues? (yes/no) + +Apply fixes? (yes/no) + + + Apply fixes (reorder stories, rewrite vague AC, add missing details) + Re-validate + ✅ Validation passed after fixes! + + + + + ✅ **Story Validation Passed!** + +**Sequence:** ✅ Valid (no forward dependencies) +**AC Quality:** ✅ All specific and testable +**Completeness:** ✅ All tech spec tasks covered +**Dependencies:** ✅ Clearly documented + +Stories are implementation-ready! + + + + + + +Confirm all validation passed Verify total story points align with tech spec time estimates -Verify stories are properly sequenced with dependencies noted -Confirm all stories have measurable acceptance criteria +Confirm epic and stories are complete **Level 1 Planning Complete!** @@ -242,33 +395,53 @@ Epic: Icon Reliability **Next Steps - Iterative Implementation:** +**🎯 RECOMMENDED - Direct to Development (Level 1):** + +Since the tech-spec is now CONTEXT-RICH with: + +- ✅ Brownfield codebase analysis (if applicable) +- ✅ Framework and library details with exact versions +- ✅ Existing patterns and code references +- ✅ Complete file paths and integration points +- ✅ Dependencies clearly mapped + +**You can skip story-context for most Level 1 stories!** + **1. Start with Story 1:** -a. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md` -b. Run story-context workflow (select story-{epic_slug}-1.md) -c. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md` -d. Run dev-story workflow to implement story 1 +a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md` +b. Run `dev-story` workflow (select story-{epic_slug}-1.md) +c. Tech-spec provides all context needed +d. Implement story 1 **2. After Story 1 Complete:** -- Repeat process for story-{epic_slug}-2.md -- Story context will auto-reference completed story 1 +- Repeat for story-{epic_slug}-2.md +- Reference completed story 1 in your work **3. After Story 2 Complete:** {{#if story_3}} -- Repeat process for story-{epic_slug}-3.md +- Repeat for story-{epic_slug}-3.md {{/if}} - Level 1 feature complete! +**Option B - Generate Additional Context (optional):** + +Only needed for extremely complex multi-story dependencies: + +1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md` +2. Run `story-context` workflow for complex stories +3. Then load DEV agent and run `dev-story` + **Progress Tracking:** -- All decisions logged in: `bmm-workflow-status.md` +- All decisions logged in: `bmm-workflow-status.yaml` - Next action clearly identified Ready to proceed? Choose your path: -1. Generate context for story 1 (recommended - run story-context) -2. Go directly to dev-story for story 1 (faster) +1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context) +2. Generate additional story context first (for complex dependencies) 3. Exit for now Select option (1-3): diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md index 514de8a1..809ae627 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md @@ -1,21 +1,21 @@ -# PRD Workflow - Small Projects (Level 0-1) +# Tech-Spec Workflow - Context-Aware Technical Planning (Level 0-1) -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} -This is the SMALL instruction set for Level 0-1 projects - tech-spec with story generation +This is for Level 0-1 projects - tech-spec with context-rich story generation Level 0: tech-spec + single user story | Level 1: tech-spec + epic/stories -Project analysis already completed - proceeding directly to technical specification -NO PRD generated - uses tech_spec_template + story templates +LIVING DOCUMENT: Write to tech-spec.md continuously as you discover - never wait until the end +CONTEXT IS KING: Gather ALL available context before generating specs DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content. ## 📚 Input Document Discovery -This workflow may reference: product brief, research documents, or brownfield project documentation. +This workflow intelligently discovers and loads all available context including: product brief, research documents, brownfield project documentation, and project setup files. **Discovery Process** (execute for each referenced document): @@ -31,19 +31,55 @@ This workflow may reference: product brief, research documents, or brownfield pr **Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions. - + Check if {output_folder}/bmm-workflow-status.yaml exists No workflow status file found. Tech-spec workflow can run standalone or as part of BMM workflow path. **Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing. + **Quick Start:** Continue in standalone mode - perfect for rapid prototyping and quick changes! Continue in standalone mode or exit to run workflow-init? (continue/exit) Set standalone_mode = true - - - Exit workflow - + + Great! Let's quickly configure your project... + + What level is this project? + +**Level 0** - Single atomic change (bug fix, small isolated feature, single file change) +→ Generates: 1 tech-spec + 1 story +→ Example: "Fix login validation bug" or "Add email field to user form" + +**Level 1** - Coherent feature (multiple related changes, small feature set) +→ Generates: 1 tech-spec + 1 epic + 2-3 stories +→ Example: "Add OAuth integration" or "Build user profile page" + +Enter **0** or **1**: + + Capture user response as project_level (0 or 1) + Validate: If not 0 or 1, ask again + + Is this a **greenfield** (new/empty codebase) or **brownfield** (existing codebase) project? + +**Greenfield** - Starting fresh, no existing code +**Brownfield** - Adding to or modifying existing code + +Enter **greenfield** or **brownfield**: + + Capture user response as field_type (greenfield or brownfield) + Validate: If not greenfield or brownfield, ask again + + Perfect! Running as: + +- **Project Level:** {{project_level}} +- **Field Type:** {{field_type}} +- **Mode:** Standalone (no status file tracking) + +Let's build your tech-spec! + + +Exit workflow + @@ -51,6 +87,7 @@ This workflow may reference: product brief, research documents, or brownfield pr Parse workflow_status section Check status of "tech-spec" workflow Get project_level from YAML metadata + Get field_type from YAML metadata (greenfield or brownfield) Find first non-completed workflow (next expected workflow) @@ -58,7 +95,7 @@ This workflow may reference: product brief, research documents, or brownfield pr Tech-spec is for Level 0-1 projects. Level 2-4 should use PRD workflow. -**Correct workflow:** `prd` (PM agent) +**Correct workflow:** `create-prd` (PM agent) Exit and redirect to prd @@ -85,185 +122,1010 @@ Tech-spec is for Level 0-1 projects. Level 2-4 should use PRD workflow. - + -Use {{project_level}} from status data +Welcome {user_name} warmly and explain what we're about to do: -Update Workflow Status: -current_workflow - -Set to: "tech-spec (Level 0 - generating tech spec)" - - -Set to: "tech-spec (Level 1 - generating tech spec)" +"I'm going to gather all available context about your project before we dive into the technical spec. This includes: + +- Any existing documentation (product briefs, research) +- Brownfield codebase analysis (if applicable) +- Your project's tech stack and dependencies +- Existing code patterns and structure + +This ensures the tech-spec is grounded in reality and gives developers everything they need." + + +**PHASE 1: Load Existing Documents** + +Search for and load (using dual-strategy: whole first, then sharded): + +1. **Product Brief:** + - Search pattern: {output*folder}/\_brief*.md + - Sharded: {output*folder}/\_brief*/index.md + - If found: Load completely and extract key context + +2. **Research Documents:** + - Search pattern: {output*folder}/\_research*.md + - Sharded: {output*folder}/\_research*/index.md + - If found: Load completely and extract insights + +3. **Document-Project Output (CRITICAL for brownfield):** + - Always check: {output_folder}/docs/index.md + - If found: This is the brownfield codebase map - load ALL shards! + - Extract: File structure, key modules, existing patterns, naming conventions + +Create a summary of what was found: + +- List of loaded documents +- Key insights from each +- Brownfield vs greenfield determination + + +**PHASE 2: Detect Project Type from Setup Files** + +Search for project setup files in {project-root}: + +**Node.js/JavaScript:** + +- package.json → Parse for framework, dependencies, scripts + +**Python:** + +- requirements.txt → Parse for packages +- pyproject.toml → Parse for modern Python projects +- Pipfile → Parse for pipenv projects + +**Ruby:** + +- Gemfile → Parse for gems and versions + +**Java:** + +- pom.xml → Parse for Maven dependencies +- build.gradle → Parse for Gradle dependencies + +**Go:** + +- go.mod → Parse for modules + +**Rust:** + +- Cargo.toml → Parse for crates + +**PHP:** + +- composer.json → Parse for packages + +If setup file found, extract: + +1. Framework name and EXACT version (e.g., "React 18.2.0", "Django 4.2.1") +2. All production dependencies with versions +3. Dev dependencies and tools (TypeScript, Jest, ESLint, pytest, etc.) +4. Available scripts (npm run test, npm run build, etc.) +5. Project type indicators (is it an API? Web app? CLI tool?) +6. **Test framework** (Jest, pytest, RSpec, JUnit, Mocha, etc.) + +**Check for Outdated Dependencies:** + +Use WebSearch to find current recommended version + +If package.json shows "react": "16.14.0" (from 2020): + +Note both current version AND migration complexity in stack summary + -progress_percentage -Set to: 20% +**For Greenfield Projects:** + +Use WebSearch for current best practices AND starter templates + + + + + + -Save {{status_file_path}} +**RECOMMEND STARTER TEMPLATES:** +Look for official or well-maintained starter templates: - - Confirm Level 0 - Single atomic change - Please describe the specific change/fix you need to implement: +- React: Create React App, Vite, Next.js starter +- Vue: create-vue, Nuxt starter +- Python: cookiecutter templates, FastAPI template +- Node.js: express-generator, NestJS CLI +- Ruby: Rails new, Sinatra template +- Go: go-blueprint, standard project layout + +Benefits of starters: + +- ✅ Modern best practices baked in +- ✅ Proper project structure +- ✅ Build tooling configured +- ✅ Testing framework set up +- ✅ Linting/formatting included +- ✅ Faster time to first feature + +**Present recommendations to user:** +"I found these starter templates for {{framework}}: + +1. {{official_template}} - Official, well-maintained +2. {{community_template}} - Popular community template + +These provide {{benefits}}. Would you like to use one? (yes/no/show-me-more)" + +Capture user preference on starter template +If yes, include starter setup in implementation stack - - Confirm Level 1 - Coherent feature - Please describe the feature you need to implement: +Store this as {{project_stack_summary}} + + +**PHASE 3: Brownfield Codebase Reconnaissance** (if applicable) + + + +Analyze the existing project structure: + +1. **Directory Structure:** + - Identify main code directories (src/, lib/, app/, components/, services/) + - Note organization patterns (feature-based, layer-based, domain-driven) + - Identify test directories and patterns + +2. **Code Patterns:** + - Look for dominant patterns (class-based, functional, MVC, microservices) + - Identify naming conventions (camelCase, snake_case, PascalCase) + - Note file organization patterns + +3. **Key Modules/Services:** + - Identify major modules or services already in place + - Note entry points (main.js, app.py, index.ts) + - Document important utilities or shared code + +4. **Testing Patterns & Standards (CRITICAL):** + - Identify test framework in use (from package.json/requirements.txt) + - Note test file naming patterns (.test.js, \_test.py, .spec.ts, Test.java) + - Document test organization (tests/, **tests**, spec/, test/) + - Look for test configuration files (jest.config.js, pytest.ini, .rspec) + - Check for coverage requirements (in CI config, test scripts) + - Identify mocking/stubbing libraries (jest.mock, unittest.mock, sinon) + - Note assertion styles (expect, assert, should) + +5. **Code Style & Conventions (MUST CONFORM):** + - Check for linter config (.eslintrc, .pylintrc, rubocop.yml) + - Check for formatter config (.prettierrc, .black, .editorconfig) + - Identify code style: + - Semicolons: yes/no (JavaScript/TypeScript) + - Quotes: single/double + - Indentation: spaces/tabs, size + - Line length limits + - Import/export patterns (named vs default, organization) + - Error handling patterns (try/catch, Result types, error classes) + - Logging patterns (console, winston, logging module, specific formats) + - Documentation style (JSDoc, docstrings, YARD, JavaDoc) + +Store this as {{existing_structure_summary}} + +**CRITICAL: Confirm Conventions with User** +I've detected these conventions in your codebase: + +**Code Style:** +{{detected_code_style}} + +**Test Patterns:** +{{detected_test_patterns}} + +**File Organization:** +{{detected_file_organization}} + +Should I follow these existing conventions for the new code? + +Enter **yes** to conform to existing patterns, or **no** if you want to establish new standards: + +Capture user response as conform_to_conventions (yes/no) + + + What conventions would you like to use instead? (Or should I suggest modern best practices?) + Capture new conventions or use WebSearch for current best practices +Store confirmed conventions as {{existing_conventions}} + + + + + Note: Greenfield project - no existing code to analyze + Set {{existing_structure_summary}} = "Greenfield project - new codebase" + + + + +**PHASE 4: Synthesize Context Summary** + +Create {{loaded_documents_summary}} that includes: + +- Documents found and loaded +- Brownfield vs greenfield status +- Tech stack detected (or "To be determined" if greenfield) +- Existing patterns identified (or "None - greenfield" if applicable) + +Present this summary to {user_name} conversationally: + +"Here's what I found about your project: + +**Documents Available:** +[List what was found] + +**Project Type:** +[Brownfield with X framework Y version OR Greenfield - new project] + +**Existing Stack:** +[Framework and dependencies OR "To be determined"] + +**Code Structure:** +[Existing patterns OR "New codebase"] + +This gives me a solid foundation for creating a context-rich tech spec!" + + +loaded_documents_summary +project_stack_summary +existing_structure_summary + - + + +Now engage in natural conversation to understand what needs to be built. + +Adapt questioning based on project_level: + + + + **Level 0: Atomic Change Discovery** + +Engage warmly and get specific details: + +"Let's talk about this change. I need to understand it deeply so the tech-spec gives developers everything they need." + +**Core Questions (adapt naturally, don't interrogate):** + +1. "What problem are you solving?" + - Listen for: Bug fix, missing feature, technical debt, improvement + - Capture as {{change_type}} + +2. "Where in the codebase should this live?" + - If brownfield: "I see you have [existing modules]. Does this fit in any of those?" + - If greenfield: "Let's figure out the right structure for this." + - Capture affected areas + +3. + "Are there existing patterns or similar code I should follow?" + - Look for consistency requirements + - Identify reference implementations + + +4. "What's the expected behavior after this change?" + - Get specific success criteria + - Understand edge cases + +5. "Any constraints or gotchas I should know about?" + - Technical limitations + - Dependencies on other systems + - Performance requirements + +**Discovery Goals:** + +- Understand the WHY (problem) +- Understand the WHAT (solution) +- Understand the WHERE (location in code) +- Understand the HOW (approach and patterns) + +Synthesize into clear problem statement and solution overview. + + + + + **Level 1: Feature Discovery** + +Engage in deeper feature exploration: + +"This is a Level 1 feature - coherent but focused. Let's explore what you're building." + +**Core Questions (natural conversation):** + +1. "What user need are you addressing?" + - Get to the core value + - Understand the user's pain point + +2. "How should this integrate with existing code?" + - If brownfield: "I saw [existing features]. How does this relate?" + - Identify integration points + - Note dependencies + +3. + "Can you point me to similar features I can reference for patterns?" + - Get example implementations + - Understand established patterns + + +4. "What's IN scope vs OUT of scope for this feature?" + - Define clear boundaries + - Identify MVP vs future enhancements + - Keep it focused (remind: Level 1 = 2-3 stories max) + +5. "Are there dependencies on other systems or services?" + - External APIs + - Databases + - Third-party libraries + +6. "What does success look like?" + - Measurable outcomes + - User-facing impact + - Technical validation + +**Discovery Goals:** + +- Feature purpose and value +- Integration strategy +- Scope boundaries +- Success criteria +- Dependencies + +Synthesize into comprehensive feature description. + + + +problem_statement +solution_overview +change_type +scope_in +scope_out + + + + -Generate tech-spec.md - this is the TECHNICAL SOURCE OF TRUTH ALL TECHNICAL DECISIONS MUST BE DEFINITIVE - NO AMBIGUITY ALLOWED +Use existing stack info to make SPECIFIC decisions +Reference brownfield code to guide implementation -Update progress: -progress_percentage -Set to: 40% -Save {{status_file_path}} +Initialize tech-spec.md with the rich template -Initialize and write out tech-spec.md using tech_spec_template +**Generate Context Section (already captured):** -DEFINITIVE DECISIONS REQUIRED: +These template variables are already populated from Step 1: -**BAD Examples (NEVER DO THIS):** +- {{loaded_documents_summary}} +- {{project_stack_summary}} +- {{existing_structure_summary}} -- "Python 2 or 3" ❌ -- "Use a logger like pino or winston" ❌ +Just save them to the file. + -**GOOD Examples (ALWAYS DO THIS):** +loaded_documents_summary +project_stack_summary +existing_structure_summary -- "Python 3.11" ✅ -- "winston v3.8.2 for logging" ✅ +**Generate The Change Section:** -**Source Tree Structure**: EXACT file changes needed -source_tree +Already captured from Step 2: + +- {{problem_statement}} +- {{solution_overview}} +- {{scope_in}} +- {{scope_out}} + +Save to file. + + +problem_statement +solution_overview +scope_in +scope_out + +**Generate Implementation Details:** + +Now make DEFINITIVE technical decisions using all the context gathered. + +**Source Tree Changes - BE SPECIFIC:** + +Bad (NEVER do this): + +- "Update some files in the services folder" +- "Add tests somewhere" + +Good (ALWAYS do this): + +- "src/services/UserService.ts - MODIFY - Add validateEmail() method at line 45" +- "src/routes/api/users.ts - MODIFY - Add POST /users/validate endpoint" +- "tests/services/UserService.test.ts - CREATE - Test suite for email validation" + +Include: + +- Exact file paths +- Action: CREATE, MODIFY, DELETE +- Specific what changes (methods, classes, endpoints, components) + +**Use brownfield context:** + +- If modifying existing files, reference current structure +- Follow existing naming patterns +- Place new code logically based on current organization + + +source_tree_changes + +**Technical Approach - BE DEFINITIVE:** + +Bad (ambiguous): + +- "Use a logging library like winston or pino" +- "Use Python 2 or 3" +- "Set up some kind of validation" + +Good (definitive): + +- "Use winston v3.8.2 (already in package.json) for logging" +- "Implement using Python 3.11 as specified in pyproject.toml" +- "Use Joi v17.9.0 for request validation following pattern in UserController.ts" + +**Use detected stack:** + +- Reference exact versions from package.json/requirements.txt +- Specify frameworks already in use +- Make decisions based on what's already there + +**For greenfield:** + +- Make definitive choices and justify them +- Specify exact versions +- No "or" statements allowed + -**Technical Approach**: SPECIFIC implementation for the change technical_approach -**Implementation Stack**: DEFINITIVE tools and versions +**Existing Patterns to Follow:** + + +Document patterns from the existing codebase: +- Class structure patterns +- Function naming conventions +- Error handling approach +- Testing patterns +- Documentation style + +Example: +"Follow the service pattern established in UserService.ts: + +- Export class with constructor injection +- Use async/await for all asynchronous operations +- Throw ServiceError with error codes +- Include JSDoc comments for all public methods" + + + +"Greenfield project - establishing new patterns: +- [Define the patterns to establish]" + + + + +existing_patterns + +**Integration Points:** + +Identify how this change connects: + +- Internal modules it depends on +- External APIs or services +- Database interactions +- Event emitters/listeners +- State management + +Be specific about interfaces and contracts. + + +integration_points + +**Development Context:** + +**Relevant Existing Code:** + +Reference specific files or code sections developers should review: + +- "See UserService.ts lines 120-150 for similar validation pattern" +- "Reference AuthMiddleware.ts for authentication approach" +- "Follow error handling in PaymentService.ts" + + +**Framework/Libraries:** +List with EXACT versions from detected stack: + +- Express 4.18.2 (web framework) +- winston 3.8.2 (logging) +- Joi 17.9.0 (validation) +- TypeScript 5.1.6 (language) + +**Internal Modules:** +List internal dependencies: + +- @/services/UserService +- @/middleware/auth +- @/utils/validation + +**Configuration Changes:** +Any config files to update: + +- Update .env with new SMTP settings +- Add validation schema to config/schemas.ts +- Update package.json scripts if needed + + +existing_code_references +framework_dependencies +internal_dependencies +configuration_changes + + + existing_conventions + + + + Set {{existing_conventions}} = "Greenfield project - establishing new conventions per modern best practices" + existing_conventions + + +**Implementation Stack:** + +Comprehensive stack with versions: + +- Runtime: Node.js 20.x +- Framework: Express 4.18.2 +- Language: TypeScript 5.1.6 +- Testing: Jest 29.5.0 +- Linting: ESLint 8.42.0 +- Validation: Joi 17.9.0 + +All from detected project setup! + + implementation_stack -**Technical Details**: PRECISE change details +**Technical Details:** + +Deep technical specifics: + +- Algorithms to implement +- Data structures to use +- Performance considerations +- Security considerations +- Error scenarios and handling +- Edge cases + +Be thorough - developers need details! + + technical_details -**Testing Approach**: How to verify the change +**Development Setup:** + +What does a developer need to run this locally? + +Based on detected stack and scripts: + +``` +1. Clone repo (if not already) +2. npm install (installs all deps from package.json) +3. cp .env.example .env (configure environment) +4. npm run dev (starts development server) +5. npm test (runs test suite) +``` + +Or for Python: + +``` +1. python -m venv venv +2. source venv/bin/activate +3. pip install -r requirements.txt +4. python manage.py runserver +``` + +Use the actual scripts from package.json/setup files! + + +development_setup + +**Implementation Guide:** + +**Setup Steps:** +Pre-implementation checklist: + +- Create feature branch +- Verify dev environment running +- Review existing code references +- Set up test data if needed + +**Implementation Steps:** +Step-by-step breakdown: + +For Level 0: + +1. [Step 1 with specific file and action] +2. [Step 2 with specific file and action] +3. [Write tests] +4. [Verify acceptance criteria] + +For Level 1: +Organize by story/phase: + +1. Phase 1: [Foundation work] +2. Phase 2: [Core implementation] +3. Phase 3: [Testing and validation] + +**Testing Strategy:** + +- Unit tests for [specific functions] +- Integration tests for [specific flows] +- Manual testing checklist +- Performance testing if applicable + +**Acceptance Criteria:** +Specific, measurable, testable criteria: + +1. Given [scenario], when [action], then [outcome] +2. [Metric] meets [threshold] +3. [Feature] works in [environment] + + +setup_steps +implementation_steps +testing_strategy +acceptance_criteria + +**Developer Resources:** + +**File Paths Reference:** +Complete list of all files involved: + +- /src/services/UserService.ts +- /src/routes/api/users.ts +- /tests/services/UserService.test.ts +- /src/types/user.ts + +**Key Code Locations:** +Important functions, classes, modules: + +- UserService class (src/services/UserService.ts:15) +- validateUser function (src/utils/validation.ts:42) +- User type definition (src/types/user.ts:8) + +**Testing Locations:** +Where tests go: + +- Unit: tests/services/ +- Integration: tests/integration/ +- E2E: tests/e2e/ + +**Documentation to Update:** +Docs that need updating: + +- README.md - Add new endpoint documentation +- API.md - Document /users/validate endpoint +- CHANGELOG.md - Note the new feature + + +file_paths_complete +key_code_locations +testing_locations +documentation_updates + +**UX/UI Considerations:** + + + **Determine if this change has UI/UX impact:** + - Does it change what users see? + - Does it change how users interact? + - Does it affect user workflows? + +If YES, document: + +**UI Components Affected:** + +- List specific components (buttons, forms, modals, pages) +- Note which need creation vs modification + +**UX Flow Changes:** + +- Current flow vs new flow +- User journey impact +- Navigation changes + +**Visual/Interaction Patterns:** + +- Follow existing design system? (check for design tokens, component library) +- New patterns needed? +- Responsive design considerations (mobile, tablet, desktop) + +**Accessibility:** + +- Keyboard navigation requirements +- Screen reader compatibility +- ARIA labels needed +- Color contrast standards + +**User Feedback:** + +- Loading states +- Error messages +- Success confirmations +- Progress indicators + + + + "No UI/UX impact - backend/API/infrastructure change only" + + + +ux_ui_considerations + +**Testing Approach:** + +Comprehensive testing strategy using {{test_framework_info}}: + +**CONFORM TO EXISTING TEST STANDARDS:** + + +- Follow existing test file naming: {{detected_test_patterns.file_naming}} +- Use existing test organization: {{detected_test_patterns.organization}} +- Match existing assertion style: {{detected_test_patterns.assertion_style}} +- Meet existing coverage requirements: {{detected_test_patterns.coverage}} + + +**Test Strategy:** + +- Test framework: {{detected_test_framework}} (from project dependencies) +- Unit tests for [specific functions/methods] +- Integration tests for [specific flows/APIs] +- E2E tests if UI changes +- Mock/stub strategies (use existing patterns: {{detected_test_patterns.mocking}}) +- Performance benchmarks if applicable +- Accessibility tests if UI changes + +**Coverage:** + +- Unit test coverage: [target %] +- Integration coverage: [critical paths] +- Ensure all acceptance criteria have corresponding tests + + +test_framework_info testing_approach -**Deployment Strategy**: How to deploy the change -deployment_strategy +**Deployment Strategy:** + +**Deployment Steps:** +How to deploy this change: + +1. Merge to main branch +2. Run CI/CD pipeline +3. Deploy to staging +4. Verify in staging +5. Deploy to production +6. Monitor for issues + +**Rollback Plan:** +How to undo if problems: + +1. Revert commit [hash] +2. Redeploy previous version +3. Verify rollback successful + +**Monitoring:** +What to watch after deployment: + +- Error rates in [logging service] +- Response times for [endpoint] +- User feedback on [feature] + + +deployment_steps +rollback_plan +monitoring_approach {project-root}/bmad/core/tasks/adv-elicit.xml - + -Offer to run cohesion validation +Always run validation - this is NOT optional! -Tech-spec complete! Before proceeding to implementation, would you like to validate project cohesion? +Tech-spec generation complete! Now running automatic validation... -**Cohesion Validation** checks: +Load {installed_path}/checklist.md +Review tech-spec.md against ALL checklist criteria: -- Tech spec completeness and definitiveness -- Feature sequencing and dependencies -- External dependencies properly planned -- User/agent responsibilities clear -- Greenfield/brownfield-specific considerations +**Section 1: Output Files Exist** -Run cohesion validation? (y/n) +- Verify tech-spec.md created +- Check for unfilled template variables - - Load {installed_path}/checklist.md - Review tech-spec.md against "Cohesion Validation (All Levels)" section - Focus on Section A (Tech Spec), Section D (Feature Sequencing) - Apply Section B (Greenfield) or Section C (Brownfield) based on field_type - Generate validation report with findings +**Section 2: Context Gathering** + +- Validate all available documents were loaded +- Confirm stack detection worked +- Verify brownfield analysis (if applicable) + +**Section 3: Tech-Spec Definitiveness** + +- Scan for "or" statements (FAIL if found) +- Verify all versions are specific +- Check stack alignment + +**Section 4: Context-Rich Content** + +- Verify all new template sections populated +- Check existing code references (brownfield) +- Validate framework dependencies listed + +**Section 5-6: Story Quality (deferred to Step 5)** + +**Section 7: Workflow Status (if applicable)** + +**Section 8: Implementation Readiness** + +- Can developer start immediately? +- Is tech-spec comprehensive enough? + + +Generate validation report with specific scores: + +- Context Gathering: [Comprehensive/Partial/Insufficient] +- Definitiveness: [All definitive/Some ambiguity/Major issues] +- Brownfield Integration: [N/A/Excellent/Partial/Missing] +- Stack Alignment: [Perfect/Good/Partial/None] +- Implementation Readiness: [Yes/No] + + + + ⚠️ **Validation Issues Detected:** + +{{list_of_issues}} + +I can fix these automatically. Shall I proceed? (yes/no) + +Fix validation issues? (yes/no) + + + Fix each issue and re-validate + ✅ Issues fixed! Re-validation passed. + + + + ⚠️ Proceeding with warnings. Issues should be addressed manually. + + + + + ✅ **Validation Passed!** + +**Scores:** + +- Context Gathering: {{context_score}} +- Definitiveness: {{definitiveness_score}} +- Brownfield Integration: {{brownfield_score}} +- Stack Alignment: {{stack_score}} +- Implementation Readiness: ✅ Ready + +Tech-spec is high quality and ready for story generation! - + -Use {{project_level}} from status data +Now generate stories that reference the rich tech-spec context - Invoke instructions-level0-story.md to generate single user story - Story will be saved to user-story.md - Story links to tech-spec.md for technical implementation details + Invoke {installed_path}/instructions-level0-story.md to generate single user story + Story will leverage tech-spec.md as primary context + Developers can skip story-context workflow since tech-spec is comprehensive - Invoke instructions-level1-stories.md to generate epic and stories - Epic and stories will be saved to epics.md - Stories link to tech-spec.md implementation tasks + Invoke {installed_path}/instructions-level1-stories.md to generate epic and stories + Stories will reference tech-spec.md for all technical details + Epic provides organization, tech-spec provides implementation context - - -Confirm tech-spec is complete and definitive - - - Confirm user-story.md generated successfully - - - - Confirm epics.md generated successfully - - -## Summary - - -- **Level 0 Output**: tech-spec.md + user-story.md -- **No PRD required** -- **Direct to implementation with story tracking** - - - -- **Level 1 Output**: tech-spec.md + epics.md -- **No PRD required** -- **Ready for sprint planning with epic/story breakdown** - - -## Next Steps - - - Load the FULL file: {output_folder}/bmm-workflow-status.yaml - Find workflow_status key "tech-spec" - ONLY write the file path as the status value - no other text, notes, or metadata - Update workflow_status["tech-spec"] = "{output_folder}/bmm-tech-spec-{{date}}.md" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - -Find first non-completed workflow in workflow_status (next workflow to do) -Determine next agent from path file based on next workflow - + **✅ Tech-Spec Complete, {user_name}!** **Deliverables Created:** -- ✅ tech-spec.md - Technical specification -- ✅ user-story.md - Single user story +- ✅ **tech-spec.md** - Context-rich technical specification + - Includes: brownfield analysis, framework details, existing patterns +- ✅ **story-{slug}.md** - Implementation-ready user story + - References tech-spec as primary context -- ✅ tech-spec.md - Technical specification -- ✅ epics.md - Epic and story breakdown +- ✅ **tech-spec.md** - Context-rich technical specification +- ✅ **epics.md** - Epic and story organization +- ✅ **story-{epic-slug}-1.md** - First story +- ✅ **story-{epic-slug}-2.md** - Second story +{{#if story_3}} +- ✅ **story-{epic-slug}-3.md** - Third story +{{/if}} +**What Makes This Tech-Spec Special:** + +The tech-spec is comprehensive enough to serve as the primary context document: + +- ✨ Brownfield codebase analysis (if applicable) +- ✨ Exact framework and library versions from your project +- ✨ Existing patterns and code references +- ✨ Specific file paths and integration points +- ✨ Complete developer resources + **Next Steps:** -- **Next required:** {{next_workflow}} ({{next_agent}} agent) -- **Optional:** Create test plan or document UI changes if applicable + +**For Single Story (Level 0):** -Check status anytime with: `workflow-status` +**Option A - With Story Context (for complex changes):** + +1. Ask SM agent to run `create-story-context` for the story + - This generates additional XML context if needed +2. Then ask DEV agent to run `dev-story` to implement + +**Option B - Direct to Dev (most Level 0):** + +1. Ask DEV agent to run `dev-story` directly + - Tech-spec provides all the context needed! + - Story is ready to implement + +💡 **Tip:** Most Level 0 changes don't need separate story context since tech-spec is comprehensive! + + + +**For Multiple Stories (Level 1):** + +**Recommended: Story-by-Story Approach** + +For the **first story** ({{first_story_name}}): + +**Option A - With Story Context (recommended for first story):** + +1. Ask SM agent to run `create-story-context` for story 1 + - Generates focused context for this specific story +2. Then ask DEV agent to run `dev-story` to implement story 1 + +**Option B - Direct to Dev:** + +1. Ask DEV agent to run `dev-story` for story 1 + - Tech-spec has most context needed + +After completing story 1, repeat for stories 2 and 3. + +**Alternative: Sprint Planning Approach** + +- If managing multiple stories as a sprint, ask SM agent to run `sprint-planning` +- This organizes all stories for coordinated implementation + + +**Your Tech-Spec:** + +- 📄 Saved to: `{output_folder}/tech-spec.md` +- Contains: All context, decisions, patterns, and implementation guidance +- Ready for: Direct development or story context generation + +The tech-spec is your single source of truth! 🚀 diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md index 372fad6c..8140d8c2 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md @@ -3,21 +3,97 @@ **Author:** {{user_name}} **Date:** {{date}} **Project Level:** {{project_level}} -**Project Type:** {{project_type}} +**Change Type:** {{change_type}} **Development Context:** {{development_context}} --- -## Source Tree Structure +## Context -{{source_tree}} +### Available Documents + +{{loaded_documents_summary}} + +### Project Stack + +{{project_stack_summary}} + +### Existing Codebase Structure + +{{existing_structure_summary}} --- -## Technical Approach +## The Change + +### Problem Statement + +{{problem_statement}} + +### Proposed Solution + +{{solution_overview}} + +### Scope + +**In Scope:** + +{{scope_in}} + +**Out of Scope:** + +{{scope_out}} + +--- + +## Implementation Details + +### Source Tree Changes + +{{source_tree_changes}} + +### Technical Approach {{technical_approach}} +### Existing Patterns to Follow + +{{existing_patterns}} + +### Integration Points + +{{integration_points}} + +--- + +## Development Context + +### Relevant Existing Code + +{{existing_code_references}} + +### Dependencies + +**Framework/Libraries:** + +{{framework_dependencies}} + +**Internal Modules:** + +{{internal_dependencies}} + +### Configuration Changes + +{{configuration_changes}} + +### Existing Conventions (Brownfield) + +{{existing_conventions}} + +### Test Framework & Standards + +{{test_framework_info}} + --- ## Implementation Stack @@ -40,7 +116,47 @@ ## Implementation Guide -{{implementation_guide}} +### Setup Steps + +{{setup_steps}} + +### Implementation Steps + +{{implementation_steps}} + +### Testing Strategy + +{{testing_strategy}} + +### Acceptance Criteria + +{{acceptance_criteria}} + +--- + +## Developer Resources + +### File Paths Reference + +{{file_paths_complete}} + +### Key Code Locations + +{{key_code_locations}} + +### Testing Locations + +{{testing_locations}} + +### Documentation to Update + +{{documentation_updates}} + +--- + +## UX/UI Considerations + +{{ux_ui_considerations}} --- @@ -52,4 +168,14 @@ ## Deployment Strategy -{{deployment_strategy}} +### Deployment Steps + +{{deployment_steps}} + +### Rollback Plan + +{{rollback_plan}} + +### Monitoring + +{{monitoring_approach}} diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md index c2e75358..aae72447 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md @@ -22,22 +22,43 @@ so that {{benefit}}. {{technical_summary}} +### Tech-Spec Reference + +**Full details:** See [tech-spec.md](../tech-spec.md) + +The tech-spec contains comprehensive context including: + +- Brownfield codebase analysis (if applicable) +- Framework and library details with versions +- Existing patterns to follow +- Integration points and dependencies +- Complete implementation guidance + ### Project Structure Notes -- Files to modify: {{files_to_modify}} -- Expected test locations: {{test_locations}} -- Estimated effort: {{story_points}} story points ({{time_estimate}}) +- **Files to modify:** {{files_to_modify}} +- **Expected test locations:** {{test_locations}} +- **Estimated effort:** {{story_points}} story points ({{time_estimate}}) +- **Dependencies:** {{dependencies}} + +### Key Code References + +{{existing_code_references}} ### References -- **Tech Spec:** See tech-spec.md for detailed implementation +- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document - **Architecture:** {{architecture_references}} +--- + ## Dev Agent Record ### Context Reference - +**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance + + ### Agent Model Used @@ -54,3 +75,13 @@ so that {{benefit}}. ### File List + +### Test Results + + + +--- + +## Review Notes + + diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml index b2090f8e..39a65f2d 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml @@ -13,6 +13,13 @@ document_output_language: "{config_source}:document_output_language" user_skill_level: "{config_source}:user_skill_level" date: system-generated +# Runtime variables (captured during workflow execution) +project_level: runtime-captured +project_type: runtime-captured +development_context: runtime-captured +change_type: runtime-captured +field_type: runtime-captured + # Workflow components installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec" instructions: "{installed_path}/instructions.md" diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index 49d9d67f..0df50d0c 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -52,6 +52,9 @@ input_file_patterns: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" + tech_spec: + whole: "{output_folder}/tech-spec.md" + architecture: whole: "{output_folder}/*architecture*.md" sharded: "{output_folder}/*architecture*/index.md" diff --git a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md index d62d1ca2..515d1335 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -120,7 +120,8 @@ All stories are either still in backlog or already marked ready/in-progress/done Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks. - Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs. + Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs. + Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance. For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md"). Add artifacts.docs entries with {path, title, section, snippet}: diff --git a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml index 6d244523..5945a69c 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml @@ -31,6 +31,9 @@ input_file_patterns: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" + tech_spec: + whole: "{output_folder}/tech-spec.md" + architecture: whole: "{output_folder}/*architecture*.md" sharded: "{output_folder}/*architecture*/index.md"