From ccebde40f79ef197f978f25553c1f887966c8128 Mon Sep 17 00:00:00 2001 From: danlawless Date: Fri, 23 Jan 2026 08:43:52 -0600 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20Add=20BMAD-METHOD=20integrat?= =?UTF-8?q?ion=20proposal=20document?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explores the opportunity to combine ai-coding-config with BMAD-METHOD: - Framework comparison and key differences - Integration architecture showing complementary layers - Three potential integration approaches - Challenges and recommended next steps Co-Authored-By: Claude Opus 4.5 --- docs/bmad-method-integration.md | 287 ++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 docs/bmad-method-integration.md diff --git a/docs/bmad-method-integration.md b/docs/bmad-method-integration.md new file mode 100644 index 0000000..7f625ee --- /dev/null +++ b/docs/bmad-method-integration.md @@ -0,0 +1,287 @@ +# BMAD-METHOD Integration Opportunity + +A proposal for combining ai-coding-config with BMAD-METHOD to create a more comprehensive AI development framework. + +## Executive Summary + +Two complementary frameworks exist in the AI-assisted development space: + +- **ai-coding-config**: An "operating system layer" for AI coding tools focused on consistency, persistence, and workflow automation +- **BMAD-METHOD**: An agile development methodology with structured planning, architectural guidance, and scale-adaptive intelligence + +These frameworks solve different problems at different abstraction levels. Combining them could create a unified system that handles the entire development lifecycle—from strategic planning to code-level execution. + +--- + +## Framework Comparison + +### ai-coding-config + +**Focus**: Tooling standardization and execution-layer automation + +| Component | Count | Purpose | +|-----------|-------|---------| +| Commands | 18 | Automated workflows (PR review, session management, debugging) | +| Agents | 24 | Specialized reviewers (security, performance, UX, architecture) | +| Rules | 33 | Coding standards (.mdc format) | +| Skills | 6 | Multi-step autonomous capabilities | +| Personalities | 7 | Communication style variants | + +**Core Problems Solved**: +- Context loss during compaction (todo persistence) +- Inconsistent code standards across projects +- Repetitive workflow tasks +- Tool fragmentation between Cursor, Claude Code, Windsurf + +**Philosophy**: Plugin-first architecture with single-source-of-truth maintenance. Encode patterns once, apply everywhere. + +### BMAD-METHOD + +**Focus**: Agile methodology and decision-making process + +| Component | Count | Purpose | +|-----------|-------|---------| +| Specialized Agents | 21 | Domain experts (PM, Architect, Developer, UX, Scrum Master) | +| Guided Workflows | 50+ | Structured processes across development phases | +| Development Phases | 4 | Analysis, Planning, Architecture, Implementation | +| Scale Levels | 5 | Complexity tiers (0-4) adapting planning depth | + +**Core Problems Solved**: +- Shallow AI decisions from "thinking-for-you" tools +- Lack of structured planning process +- No methodology scaling based on project complexity +- Missing agile best practices in AI workflows + +**Philosophy**: AI as expert collaborator guiding methodical decision-making. Process rigor over automation. + +--- + +## Key Differences + +| Dimension | ai-coding-config | BMAD-METHOD | +|-----------|------------------|-------------| +| **Abstraction Level** | Tooling/config layer | Methodology layer | +| **Primary Question** | "How do we write code consistently?" | "What should we build and how?" | +| **Decision Scope** | Code standards, formatting, PR flow | Architecture, feature design, project structure | +| **When It Helps** | During implementation | Before implementation | +| **Scaling Approach** | Rule sets per tech stack | Planning depth per project complexity | + +### Concrete Examples + +**Scenario: "Add user authentication"** + +- BMAD-METHOD asks: "OAuth vs JWT? Session-based vs stateless? What's the threat model?" +- ai-coding-config ensures: Consistent error handling, proper logging, security review checklist + +**Scenario: "Fix the login bug"** + +- BMAD-METHOD: Quick Flow track (~10-30 min structured process) +- ai-coding-config: `/troubleshoot` command with systematic debugging framework + +--- + +## The Integration Opportunity + +These frameworks are complementary, not competing. They operate at different layers: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ BMAD-METHOD Layer │ +│ │ +│ Scale Assessment → Analysis → Planning → Architecture │ +│ │ +│ "Should we use microservices? What's the data model?" │ +└─────────────────────────────┬───────────────────────────────┘ + │ + │ Decisions feed into + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ ai-coding-config Layer │ +│ │ +│ Rules → Commands → Agents → Session Persistence │ +│ │ +│ "Use conventional commits. Run security review on PR." │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Natural Handoff Points + +1. **BMAD Planning → ai-coding-config Execution** + - BMAD completes architecture phase with decisions documented + - ai-coding-config `/autotask` implements features following those decisions + - Rules enforce the architectural patterns chosen during planning + +2. **ai-coding-config Persistence → BMAD Context** + - Session save/resume preserves architectural decisions + - Todo persistence maintains planning artifacts + - BMAD agents can reference prior decisions without context loss + +3. **Scale-Adaptive Planning → Stack-Specific Rules** + - BMAD Level 0-1 (quick fixes) → Minimal rule loading + - BMAD Level 2-3 (features/products) → Full stack rules + - BMAD Level 4 (enterprise) → Additional compliance rules + +### Combined Agent Roster + +| Category | BMAD Agents | ai-coding-config Agents | +|----------|-------------|-------------------------| +| **Planning** | PM, Scrum Master | - | +| **Architecture** | Architect, Tech Lead | architecture-reviewer | +| **Development** | Developer, Engineer | autonomous-developer, test-engineer | +| **Quality** | QA Lead | logic-reviewer, robustness-reviewer | +| **Security** | - | security-reviewer | +| **UX** | UX Designer | ux-reviewer (mobile, desktop) | +| **Performance** | - | performance-reviewer | +| **Documentation** | Doc Writer | doc-reviewer | + +Total: ~45 specialized agents covering the full development lifecycle. + +--- + +## Potential Integration Approaches + +### Option A: Sequential Workflow + +Use BMAD for early phases, switch to ai-coding-config for implementation. + +``` +Project Start + │ + ▼ +┌─────────────────────┐ +│ BMAD: /bmad-help │ "What kind of project is this?" +│ Scale Assessment │ +└─────────┬───────────┘ + │ + ▼ +┌─────────────────────┐ +│ BMAD: Analysis │ Requirements, user stories, constraints +│ BMAD: Planning │ Sprint structure, milestones +│ BMAD: Architecture │ Tech decisions, data models +└─────────┬───────────┘ + │ + │ Architecture decisions documented + ▼ +┌─────────────────────┐ +│ ai-coding-config: │ Load rules for chosen stack +│ /load-rules │ +└─────────┬───────────┘ + │ + ▼ +┌─────────────────────┐ +│ ai-coding-config: │ Implement features following rules +│ /autotask │ Session persistence across work +│ /session save │ PR automation with reviews +└─────────────────────┘ +``` + +**Pros**: Clear separation, minimal conflicts, easy to adopt incrementally +**Cons**: Manual handoff, context may need re-establishment + +### Option B: Unified Command Namespace + +Merge command sets under a single namespace with phase prefixes. + +``` +/plan:start → BMAD scale assessment +/plan:analyze → BMAD analysis phase +/plan:architect → BMAD architecture phase +/build:autotask → ai-coding-config autonomous implementation +/build:review → ai-coding-config PR review +/session:save → ai-coding-config persistence +``` + +**Pros**: Single mental model, clear phase boundaries +**Cons**: Significant integration work, namespace management + +### Option C: Adapter Layer + +Create a thin adapter that routes to appropriate framework based on context. + +```typescript +// Pseudo-code for unified entry point +async function handleCommand(command: string, context: ProjectContext) { + const phase = detectPhase(context); // planning vs implementation + + if (phase === 'planning' || command.startsWith('plan')) { + return bmadMethod.execute(command, context); + } else { + return aiCodingConfig.execute(command, context); + } +} +``` + +**Pros**: Transparent routing, preserves both systems intact +**Cons**: Additional complexity, potential edge cases + +--- + +## Challenges to Address + +### 1. Agent Overlap + +Both frameworks define specialized agents. Resolution strategies: + +- **Namespace prefixing**: `bmad:architect` vs `acc:architecture-reviewer` +- **Role clarity**: BMAD agents for decisions, ai-coding-config agents for reviews +- **Consolidation**: Merge overlapping agents where functionality is identical + +### 2. Command Conflicts + +Both use slash commands. Mitigation: + +- Audit both command sets for conflicts +- Establish naming conventions (verbs vs nouns, phases vs actions) +- Consider hierarchical namespacing + +### 3. Cognitive Overhead + +Two systems means two mental models. Approaches: + +- Clear documentation on when to use which +- Guided onboarding that introduces concepts gradually +- Smart defaults that auto-select the right tool + +### 4. Maintenance Burden + +Upstream changes in both repos require reconciliation: + +- Pin to specific versions for stability +- Maintain a changelog of integration-relevant changes +- Consider contributing upstream to align approaches + +--- + +## Recommended Next Steps + +1. **Pilot Integration**: Try sequential workflow (Option A) on a real project +2. **Document Friction**: Note where handoffs are awkward or context is lost +3. **Identify Quick Wins**: Find low-effort, high-value integration points +4. **Community Discussion**: Engage BMAD-METHOD maintainers about alignment interest +5. **Prototype Adapter**: Build minimal adapter layer to test Option C feasibility + +--- + +## Conclusion + +ai-coding-config and BMAD-METHOD address different parts of the development lifecycle: + +- **BMAD-METHOD** excels at structured planning and architectural decision-making +- **ai-coding-config** excels at consistent execution and workflow automation + +Combining them creates a comprehensive system: + +| Phase | Framework | Value | +|-------|-----------|-------| +| Project Assessment | BMAD | Scale-adaptive planning depth | +| Analysis & Planning | BMAD | Methodical requirements, agile process | +| Architecture | BMAD | Structured tech decisions | +| Implementation | ai-coding-config | Consistent code, automated workflows | +| Code Review | ai-coding-config | Multi-dimensional quality checks | +| Session Management | ai-coding-config | Context persistence across work | + +The opportunity is real. The frameworks are complementary. The question is whether the integration complexity is worth the combined power. + +--- + +*This document is a proposal for discussion, not a commitment to implementation.* From 7e62df3b452f097e5db087b0d8b7e47b68c2c3f4 Mon Sep 17 00:00:00 2001 From: danlawless Date: Fri, 23 Jan 2026 08:59:45 -0600 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20Rewrite=20BMAD=20integration?= =?UTF-8?q?=20doc=20with=20submodule=20architecture?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarifies the integration approach: - Complete isolation via Git submodules - Document-based handoff (BMAD writes docs, ai-coding-config reads) - Forked repos maintain upstream connection - Unified command namespace (/bmad:* for planning, /build:* for execution) - Clear phase separation with explicit handoff trigger Co-Authored-By: Claude Opus 4.5 --- docs/bmad-method-integration.md | 480 ++++++++++++++++++-------------- 1 file changed, 277 insertions(+), 203 deletions(-) diff --git a/docs/bmad-method-integration.md b/docs/bmad-method-integration.md index 7f625ee..1f865cc 100644 --- a/docs/bmad-method-integration.md +++ b/docs/bmad-method-integration.md @@ -1,287 +1,361 @@ -# BMAD-METHOD Integration Opportunity +# BMAD-METHOD + ai-coding-config: Unified Development Lifecycle -A proposal for combining ai-coding-config with BMAD-METHOD to create a more comprehensive AI development framework. +A two-phase development system where BMAD handles planning and ai-coding-config handles execution—completely isolated, connected only by documentation. -## Executive Summary +--- -Two complementary frameworks exist in the AI-assisted development space: +## The Architecture -- **ai-coding-config**: An "operating system layer" for AI coding tools focused on consistency, persistence, and workflow automation -- **BMAD-METHOD**: An agile development methodology with structured planning, architectural guidance, and scale-adaptive intelligence +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Your Project Repository │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ .bmad/ .ai-coding-config/ │ +│ └── (submodule) └── (submodule) │ +│ ↓ ↓ │ +│ Fork of BMAD-METHOD Fork of ai-coding-config │ +│ github.com/you/bmad github.com/you/ai-coding-config │ +│ │ +│ docs/ src/ │ +│ ├── strategy.md ───→ ├── components/ │ +│ ├── architecture.md ───→ ├── services/ │ +│ ├── brand-guidelines.md └── ... │ +│ ├── user-stories.md │ +│ └── tech-decisions.md │ +│ │ +│ BMAD WRITES AI-CODING-CONFIG READS │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` -These frameworks solve different problems at different abstraction levels. Combining them could create a unified system that handles the entire development lifecycle—from strategic planning to code-level execution. +### Core Principle ---- +**Complete isolation. Document-based handoff.** -## Framework Comparison +- BMAD and ai-coding-config never communicate directly +- BMAD produces documentation artifacts +- ai-coding-config consumes those artifacts to guide implementation +- Each framework lives in its own submodule, pulls upstream updates independently -### ai-coding-config +--- -**Focus**: Tooling standardization and execution-layer automation +## Phase 1: Planning (BMAD) -| Component | Count | Purpose | -|-----------|-------|---------| -| Commands | 18 | Automated workflows (PR review, session management, debugging) | -| Agents | 24 | Specialized reviewers (security, performance, UX, architecture) | -| Rules | 33 | Coding standards (.mdc format) | -| Skills | 6 | Multi-step autonomous capabilities | -| Personalities | 7 | Communication style variants | +BMAD owns everything before code gets written. -**Core Problems Solved**: -- Context loss during compaction (todo persistence) -- Inconsistent code standards across projects -- Repetitive workflow tasks -- Tool fragmentation between Cursor, Claude Code, Windsurf +### What BMAD Produces -**Philosophy**: Plugin-first architecture with single-source-of-truth maintenance. Encode patterns once, apply everywhere. +| Document | Purpose | +|----------|---------| +| `docs/strategy.md` | Project vision, goals, success metrics | +| `docs/requirements.md` | User stories, acceptance criteria | +| `docs/architecture.md` | System design, data models, tech stack decisions | +| `docs/brand-guidelines.md` | Voice, tone, visual identity, naming conventions | +| `docs/api-contracts.md` | Endpoint definitions, request/response schemas | +| `docs/tech-decisions.md` | ADRs (Architecture Decision Records) | -### BMAD-METHOD +### BMAD Workflow -**Focus**: Agile methodology and decision-making process +``` +/bmad:start → Scale assessment, project classification +/bmad:analyze → Requirements gathering, user research +/bmad:plan → Sprint structure, milestones, priorities +/bmad:architect → Tech stack, data models, system design +/bmad:brand → Guidelines, voice, naming conventions +/bmad:finalize → Review all docs, mark planning complete +``` -| Component | Count | Purpose | -|-----------|-------|---------| -| Specialized Agents | 21 | Domain experts (PM, Architect, Developer, UX, Scrum Master) | -| Guided Workflows | 50+ | Structured processes across development phases | -| Development Phases | 4 | Analysis, Planning, Architecture, Implementation | -| Scale Levels | 5 | Complexity tiers (0-4) adapting planning depth | +### Planning Complete Checklist -**Core Problems Solved**: -- Shallow AI decisions from "thinking-for-you" tools -- Lack of structured planning process -- No methodology scaling based on project complexity -- Missing agile best practices in AI workflows +Before handing off to ai-coding-config: -**Philosophy**: AI as expert collaborator guiding methodical decision-making. Process rigor over automation. +- [ ] Strategy document defines clear success metrics +- [ ] All user stories have acceptance criteria +- [ ] Architecture decisions are documented with rationale +- [ ] Tech stack is chosen and justified +- [ ] Data models are defined +- [ ] API contracts are specified +- [ ] Brand/style guidelines exist (if applicable) --- -## Key Differences +## Phase 2: Execution (ai-coding-config) -| Dimension | ai-coding-config | BMAD-METHOD | -|-----------|------------------|-------------| -| **Abstraction Level** | Tooling/config layer | Methodology layer | -| **Primary Question** | "How do we write code consistently?" | "What should we build and how?" | -| **Decision Scope** | Code standards, formatting, PR flow | Architecture, feature design, project structure | -| **When It Helps** | During implementation | Before implementation | -| **Scaling Approach** | Rule sets per tech stack | Planning depth per project complexity | +ai-coding-config owns everything once code starts. -### Concrete Examples +### What ai-coding-config Consumes -**Scenario: "Add user authentication"** +The execution phase reads BMAD's output: -- BMAD-METHOD asks: "OAuth vs JWT? Session-based vs stateless? What's the threat model?" -- ai-coding-config ensures: Consistent error handling, proper logging, security review checklist +```typescript +// ai-coding-config looks for planning docs in standard locations +const PLANNING_DOCS = [ + 'docs/architecture.md', // Tech decisions guide implementation + 'docs/requirements.md', // User stories become tasks + 'docs/api-contracts.md', // Contracts enforce interfaces + 'docs/brand-guidelines.md' // Style guides inform UI code +]; +``` -**Scenario: "Fix the login bug"** +### ai-coding-config Workflow -- BMAD-METHOD: Quick Flow track (~10-30 min structured process) -- ai-coding-config: `/troubleshoot` command with systematic debugging framework +``` +/build:load-context → Ingest planning docs, understand project +/build:autotask → Implement features per requirements +/build:review → Multi-agent code review +/build:troubleshoot → Debug issues using documented architecture +/session:save → Persist progress +/session:resume → Continue work with full context +``` ---- +### Execution Standards -## The Integration Opportunity +ai-coding-config enforces: -These frameworks are complementary, not competing. They operate at different layers: +- Code standards from `.ai-coding-config/rules/` +- Commit conventions +- PR review checklists +- Test coverage requirements +- Security review gates -``` -┌─────────────────────────────────────────────────────────────┐ -│ BMAD-METHOD Layer │ -│ │ -│ Scale Assessment → Analysis → Planning → Architecture │ -│ │ -│ "Should we use microservices? What's the data model?" │ -└─────────────────────────────┬───────────────────────────────┘ - │ - │ Decisions feed into - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ ai-coding-config Layer │ -│ │ -│ Rules → Commands → Agents → Session Persistence │ -│ │ -│ "Use conventional commits. Run security review on PR." │ -└─────────────────────────────────────────────────────────────┘ -``` +--- -### Natural Handoff Points +## Submodule Setup -1. **BMAD Planning → ai-coding-config Execution** - - BMAD completes architecture phase with decisions documented - - ai-coding-config `/autotask` implements features following those decisions - - Rules enforce the architectural patterns chosen during planning +### Initial Installation -2. **ai-coding-config Persistence → BMAD Context** - - Session save/resume preserves architectural decisions - - Todo persistence maintains planning artifacts - - BMAD agents can reference prior decisions without context loss +```bash +# Fork both repos to your org first, then: -3. **Scale-Adaptive Planning → Stack-Specific Rules** - - BMAD Level 0-1 (quick fixes) → Minimal rule loading - - BMAD Level 2-3 (features/products) → Full stack rules - - BMAD Level 4 (enterprise) → Additional compliance rules +# Add BMAD as submodule +git submodule add https://github.com/YOUR-ORG/bmad-method .bmad +git submodule update --init --recursive -### Combined Agent Roster +# Add ai-coding-config as submodule +git submodule add https://github.com/YOUR-ORG/ai-coding-config .ai-coding-config +git submodule update --init --recursive +``` -| Category | BMAD Agents | ai-coding-config Agents | -|----------|-------------|-------------------------| -| **Planning** | PM, Scrum Master | - | -| **Architecture** | Architect, Tech Lead | architecture-reviewer | -| **Development** | Developer, Engineer | autonomous-developer, test-engineer | -| **Quality** | QA Lead | logic-reviewer, robustness-reviewer | -| **Security** | - | security-reviewer | -| **UX** | UX Designer | ux-reviewer (mobile, desktop) | -| **Performance** | - | performance-reviewer | -| **Documentation** | Doc Writer | doc-reviewer | +### Directory Structure -Total: ~45 specialized agents covering the full development lifecycle. +``` +your-project/ +├── .bmad/ # BMAD submodule (forked) +│ ├── agents/ +│ ├── workflows/ +│ └── ... +├── .ai-coding-config/ # ai-coding-config submodule (forked) +│ ├── commands/ +│ ├── agents/ +│ ├── rules/ +│ └── ... +├── docs/ # BMAD writes here +│ ├── strategy.md +│ ├── architecture.md +│ └── ... +├── src/ # ai-coding-config builds here +└── ... +``` + +### Pulling Upstream Updates + +```bash +# Update BMAD from upstream +cd .bmad +git fetch upstream +git merge upstream/main +cd .. +git add .bmad +git commit -m "🔄 Update BMAD submodule" + +# Update ai-coding-config from upstream +cd .ai-coding-config +git fetch upstream +git merge upstream/main +cd .. +git add .ai-coding-config +git commit -m "🔄 Update ai-coding-config submodule" +``` --- -## Potential Integration Approaches +## The Handoff + +The transition from planning to execution is explicit and documented. -### Option A: Sequential Workflow +### Handoff Trigger -Use BMAD for early phases, switch to ai-coding-config for implementation. +When BMAD completes planning: ``` -Project Start - │ - ▼ -┌─────────────────────┐ -│ BMAD: /bmad-help │ "What kind of project is this?" -│ Scale Assessment │ -└─────────┬───────────┘ - │ - ▼ -┌─────────────────────┐ -│ BMAD: Analysis │ Requirements, user stories, constraints -│ BMAD: Planning │ Sprint structure, milestones -│ BMAD: Architecture │ Tech decisions, data models -└─────────┬───────────┘ - │ - │ Architecture decisions documented - ▼ -┌─────────────────────┐ -│ ai-coding-config: │ Load rules for chosen stack -│ /load-rules │ -└─────────┬───────────┘ - │ - ▼ -┌─────────────────────┐ -│ ai-coding-config: │ Implement features following rules -│ /autotask │ Session persistence across work -│ /session save │ PR automation with reviews -└─────────────────────┘ +/bmad:finalize ``` -**Pros**: Clear separation, minimal conflicts, easy to adopt incrementally -**Cons**: Manual handoff, context may need re-establishment +This command: +1. Validates all required docs exist +2. Runs completeness checks +3. Generates a `docs/PLANNING_COMPLETE.md` summary +4. Signals readiness for execution phase -### Option B: Unified Command Namespace +### Handoff Artifact -Merge command sets under a single namespace with phase prefixes. +```markdown + +# Planning Phase Complete -``` -/plan:start → BMAD scale assessment -/plan:analyze → BMAD analysis phase -/plan:architect → BMAD architecture phase -/build:autotask → ai-coding-config autonomous implementation -/build:review → ai-coding-config PR review -/session:save → ai-coding-config persistence -``` +## Summary +- Project: [Name] +- Scale Level: [0-4] +- Tech Stack: [Chosen technologies] + +## Documents Ready +- [x] strategy.md +- [x] requirements.md +- [x] architecture.md +- [x] api-contracts.md -**Pros**: Single mental model, clear phase boundaries -**Cons**: Significant integration work, namespace management +## Key Decisions +1. Using PostgreSQL for persistence (see tech-decisions.md#database) +2. React + TypeScript frontend (see tech-decisions.md#frontend) +3. REST API with OpenAPI spec (see api-contracts.md) -### Option C: Adapter Layer +## Ready for Execution +Planning is complete. Run `/build:load-context` to begin implementation. +``` -Create a thin adapter that routes to appropriate framework based on context. +### Starting Execution -```typescript -// Pseudo-code for unified entry point -async function handleCommand(command: string, context: ProjectContext) { - const phase = detectPhase(context); // planning vs implementation - - if (phase === 'planning' || command.startsWith('plan')) { - return bmadMethod.execute(command, context); - } else { - return aiCodingConfig.execute(command, context); - } -} +``` +/build:load-context docs/ ``` -**Pros**: Transparent routing, preserves both systems intact -**Cons**: Additional complexity, potential edge cases +ai-coding-config: +1. Reads all planning documents +2. Extracts requirements as actionable tasks +3. Loads appropriate rules for the tech stack +4. Begins implementation following documented architecture --- -## Challenges to Address +## Why This Works -### 1. Agent Overlap +### Complete Isolation -Both frameworks define specialized agents. Resolution strategies: +| Aspect | Benefit | +|--------|---------| +| Separate submodules | Each framework updates independently | +| No runtime coupling | No complex integration code to maintain | +| Forked repos | Customize without losing upstream connection | +| Document contract | Clear interface between phases | -- **Namespace prefixing**: `bmad:architect` vs `acc:architecture-reviewer` -- **Role clarity**: BMAD agents for decisions, ai-coding-config agents for reviews -- **Consolidation**: Merge overlapping agents where functionality is identical +### Clear Responsibilities -### 2. Command Conflicts +| Phase | Owner | Artifacts | +|-------|-------|-----------| +| Planning | BMAD | Markdown docs in `docs/` | +| Execution | ai-coding-config | Code in `src/`, tests, PRs | -Both use slash commands. Mitigation: +### Upstream Maintenance -- Audit both command sets for conflicts -- Establish naming conventions (verbs vs nouns, phases vs actions) -- Consider hierarchical namespacing +Both frameworks evolve independently: -### 3. Cognitive Overhead +- Pull BMAD updates for new planning workflows +- Pull ai-coding-config updates for new review agents +- Your forks let you customize while staying connected +- Submodules pin to specific commits for stability -Two systems means two mental models. Approaches: +--- -- Clear documentation on when to use which -- Guided onboarding that introduces concepts gradually -- Smart defaults that auto-select the right tool +## Unified Command Namespace -### 4. Maintenance Burden +While the systems are isolated, the developer experience is unified through namespaced commands: -Upstream changes in both repos require reconciliation: +### Planning Commands (BMAD) -- Pin to specific versions for stability -- Maintain a changelog of integration-relevant changes -- Consider contributing upstream to align approaches +``` +/bmad:help → Show available planning workflows +/bmad:start → Begin new project planning +/bmad:analyze → Requirements and analysis phase +/bmad:plan → Sprint and milestone planning +/bmad:architect → Technical architecture +/bmad:brand → Brand and style guidelines +/bmad:finalize → Complete planning, prepare handoff +``` ---- +### Execution Commands (ai-coding-config) + +``` +/build:load-context → Ingest planning docs +/build:autotask → Autonomous implementation +/build:review → Code review workflow +/build:troubleshoot → Debugging assistance +/session:save → Persist current state +/session:resume → Restore previous session +/load-rules → Load stack-specific rules +``` -## Recommended Next Steps +### The Mental Model -1. **Pilot Integration**: Try sequential workflow (Option A) on a real project -2. **Document Friction**: Note where handoffs are awkward or context is lost -3. **Identify Quick Wins**: Find low-effort, high-value integration points -4. **Community Discussion**: Engage BMAD-METHOD maintainers about alignment interest -5. **Prototype Adapter**: Build minimal adapter layer to test Option C feasibility +``` +Am I deciding WHAT to build? → /bmad:* +Am I writing HOW to build it? → /build:* +``` --- -## Conclusion +## Getting Started -ai-coding-config and BMAD-METHOD address different parts of the development lifecycle: +### 1. Fork Both Repos -- **BMAD-METHOD** excels at structured planning and architectural decision-making -- **ai-coding-config** excels at consistent execution and workflow automation +- Fork `bmad-code-org/BMAD-METHOD` → `your-org/bmad-method` +- Fork `Light-Brands/ai-coding-config` → `your-org/ai-coding-config` -Combining them creates a comprehensive system: +### 2. Add Submodules to Your Project + +```bash +git submodule add https://github.com/your-org/bmad-method .bmad +git submodule add https://github.com/your-org/ai-coding-config .ai-coding-config +``` -| Phase | Framework | Value | -|-------|-----------|-------| -| Project Assessment | BMAD | Scale-adaptive planning depth | -| Analysis & Planning | BMAD | Methodical requirements, agile process | -| Architecture | BMAD | Structured tech decisions | -| Implementation | ai-coding-config | Consistent code, automated workflows | -| Code Review | ai-coding-config | Multi-dimensional quality checks | -| Session Management | ai-coding-config | Context persistence across work | +### 3. Start Planning + +``` +/bmad:start +``` -The opportunity is real. The frameworks are complementary. The question is whether the integration complexity is worth the combined power. +### 4. Complete Planning Docs + +Work through BMAD workflows until all docs are ready. + +### 5. Finalize and Hand Off + +``` +/bmad:finalize +``` + +### 6. Begin Execution + +``` +/build:load-context docs/ +/build:autotask "Implement user authentication per docs/architecture.md" +``` --- -*This document is a proposal for discussion, not a commitment to implementation.* +## Summary + +| Question | Answer | +|----------|--------| +| Are they integrated? | No—completely isolated | +| How do they communicate? | Through documentation only | +| Can I update them independently? | Yes—separate submodules, forked repos | +| What's the handoff? | BMAD writes docs, ai-coding-config reads them | +| When do I use BMAD? | Before writing code | +| When do I use ai-coding-config? | When writing code | + +**BMAD answers:** "What are we building and why?" + +**ai-coding-config answers:** "How do we build it correctly?" + +One plans. One executes. Documentation is the contract. From 481644122e29a9a009ad496d421c81d317a525aa Mon Sep 17 00:00:00 2001 From: danlawless Date: Fri, 23 Jan 2026 09:11:21 -0600 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Expand=20BMAD=20integration?= =?UTF-8?q?=20doc=20with=20full=20framework=20capabilities?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive documentation of both frameworks' complete feature sets: BMAD (Planning): - 8 named agents with specialties (Mary, John, Winston, Sally, Bob, Amelia, Murat, Barry) - 4 workflow phases with all commands - 50+ workflows, 60+ ideation techniques - Party mode multi-agent collaboration - Scale-adaptive tracks (Quick Flow, BMad Method, Enterprise) ai-coding-config (Execution): - Git worktree setup and isolation - 21 commands with full /autotask pipeline - 24 review agents across 7 categories - Complete PR automation lifecycle - Bot feedback iteration loop - Merge and cleanup workflow Includes complete workflow diagram from idea → merged PR Co-Authored-By: Claude Opus 4.5 --- docs/bmad-method-integration.md | 744 +++++++++++++++++++++----------- 1 file changed, 497 insertions(+), 247 deletions(-) diff --git a/docs/bmad-method-integration.md b/docs/bmad-method-integration.md index 1f865cc..d25b248 100644 --- a/docs/bmad-method-integration.md +++ b/docs/bmad-method-integration.md @@ -1,361 +1,611 @@ -# BMAD-METHOD + ai-coding-config: Unified Development Lifecycle +# BMAD-METHOD + ai-coding-config: Complete Development Lifecycle -A two-phase development system where BMAD handles planning and ai-coding-config handles execution—completely isolated, connected only by documentation. +A two-phase development system combining BMAD's structured planning methodology with ai-coding-config's autonomous execution engine—from initial idea to merged PR. --- -## The Architecture - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ Your Project Repository │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ .bmad/ .ai-coding-config/ │ -│ └── (submodule) └── (submodule) │ -│ ↓ ↓ │ -│ Fork of BMAD-METHOD Fork of ai-coding-config │ -│ github.com/you/bmad github.com/you/ai-coding-config │ -│ │ -│ docs/ src/ │ -│ ├── strategy.md ───→ ├── components/ │ -│ ├── architecture.md ───→ ├── services/ │ -│ ├── brand-guidelines.md └── ... │ -│ ├── user-stories.md │ -│ └── tech-decisions.md │ -│ │ -│ BMAD WRITES AI-CODING-CONFIG READS │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Your Project Repository │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ .bmad/ .ai-coding-config/ │ +│ └── (forked submodule) └── (forked submodule) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ PHASE 1: PLANNING (BMAD) │ │ +│ │ │ │ +│ │ 8 Specialized Agents │ 50+ Workflows │ 60+ Ideation Techniques │ │ +│ │ │ │ +│ │ Analysis → Planning → Solutioning → Handoff │ │ +│ │ │ │ +│ │ OUTPUT: docs/ │ │ +│ │ ├── product-brief.md ├── architecture.md │ │ +│ │ ├── prd.md ├── epic-*.md │ │ +│ │ ├── ux-design.md ├── story-*.md │ │ +│ │ └── tech-decisions.md └── PLANNING_COMPLETE.md │ │ +│ └─────────────────────────────┬───────────────────────────────────────┘ │ +│ │ │ +│ │ Document Handoff │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ PHASE 2: EXECUTION (ai-coding-config) │ │ +│ │ │ │ +│ │ 21 Commands │ 24 Review Agents │ Git Worktrees │ PR Automation │ │ +│ │ │ │ +│ │ Setup → Implement → Review → PR → Iterate → Merge → Cleanup │ │ +│ │ │ │ +│ │ OUTPUT: src/ │ │ +│ │ ├── components/ ├── Pull Requests │ │ +│ │ ├── services/ ├── Automated Reviews │ │ +│ │ └── tests/ └── Merged Code │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ ``` ### Core Principle -**Complete isolation. Document-based handoff.** +**Complete isolation. Document-based handoff. Full automation.** -- BMAD and ai-coding-config never communicate directly -- BMAD produces documentation artifacts -- ai-coding-config consumes those artifacts to guide implementation +- BMAD produces comprehensive planning documentation +- ai-coding-config consumes those docs and executes autonomously - Each framework lives in its own submodule, pulls upstream updates independently +- The entire lifecycle—from idea to merged PR—can run with minimal human intervention --- ## Phase 1: Planning (BMAD) -BMAD owns everything before code gets written. - -### What BMAD Produces - -| Document | Purpose | -|----------|---------| -| `docs/strategy.md` | Project vision, goals, success metrics | -| `docs/requirements.md` | User stories, acceptance criteria | -| `docs/architecture.md` | System design, data models, tech stack decisions | -| `docs/brand-guidelines.md` | Voice, tone, visual identity, naming conventions | -| `docs/api-contracts.md` | Endpoint definitions, request/response schemas | -| `docs/tech-decisions.md` | ADRs (Architecture Decision Records) | - -### BMAD Workflow - -``` -/bmad:start → Scale assessment, project classification -/bmad:analyze → Requirements gathering, user research -/bmad:plan → Sprint structure, milestones, priorities -/bmad:architect → Tech stack, data models, system design -/bmad:brand → Guidelines, voice, naming conventions -/bmad:finalize → Review all docs, mark planning complete -``` - -### Planning Complete Checklist +BMAD provides structured methodology with specialized AI agents that guide you through rigorous planning before any code is written. -Before handing off to ai-coding-config: +### The BMAD Agent Team -- [ ] Strategy document defines clear success metrics -- [ ] All user stories have acceptance criteria -- [ ] Architecture decisions are documented with rationale -- [ ] Tech stack is chosen and justified -- [ ] Data models are defined -- [ ] API contracts are specified -- [ ] Brand/style guidelines exist (if applicable) +| Agent | Name | Specialty | +|-------|------|-----------| +| **Analyst** | Mary | Discovery, research, brainstorming, market analysis, brownfield documentation | +| **PM** | John | PRDs, requirements definition, epic/story creation, acceptance criteria | +| **Architect** | Winston | System design, ADRs, technical standards, implementation readiness | +| **UX Designer** | Sally | User journeys, wireframes, design systems, accessibility | +| **Scrum Master** | Bob | Sprint planning, story prep, retrospectives, course correction | +| **Developer** | Amelia | Implementation guidance, code review, pattern enforcement | +| **Test Architect** | Murat | Test strategy, automation framework, NFR assessment, quality gates | +| **Quick Flow Dev** | Barry | Rapid solo development for small changes (spec → dev → review) | ---- +### Development Tracks -## Phase 2: Execution (ai-coding-config) +BMAD adapts planning depth to project complexity: -ai-coding-config owns everything once code starts. +| Track | Scope | Planning Depth | When to Use | +|-------|-------|----------------|-------------| +| **Quick Flow** | Bug fixes, small features | Tech spec only | Single focused change | +| **BMad Method** | Products, platforms | Full PRD + Architecture | New features, refactors | +| **Enterprise** | Compliance-heavy systems | Extended analysis + research | Regulated industries | -### What ai-coding-config Consumes +### BMAD Workflow Phases -The execution phase reads BMAD's output: +#### Phase 1: Analysis (Optional) -```typescript -// ai-coding-config looks for planning docs in standard locations -const PLANNING_DOCS = [ - 'docs/architecture.md', // Tech decisions guide implementation - 'docs/requirements.md', // User stories become tasks - 'docs/api-contracts.md', // Contracts enforce interfaces - 'docs/brand-guidelines.md' // Style guides inform UI code -]; +``` +/bmad:brainstorm → 60+ ideation techniques for solution exploration +/bmad:research → Market, technical, competitive analysis +/bmad:product-brief → Strategic vision with problem statement ``` -### ai-coding-config Workflow +**Capabilities:** +- 60+ brainstorming techniques (First Principles, 5 Whys, Socratic Questioning) +- Expert panels and stakeholder round tables +- Tree of Thoughts and Graph of Thoughts frameworks +- Red Team vs Blue Team analysis + +#### Phase 2: Planning (Required) ``` -/build:load-context → Ingest planning docs, understand project -/build:autotask → Implement features per requirements -/build:review → Multi-agent code review -/build:troubleshoot → Debug issues using documented architecture -/session:save → Persist progress -/session:resume → Continue work with full context +/bmad:prd → Product Requirements Document (scale-adaptive) +/bmad:ux-design → User journeys, wireframes, design system +/bmad:nfr-assess → Non-functional requirements evaluation ``` -### Execution Standards - -ai-coding-config enforces: +**Output Artifacts:** +- `prd.md` — Functional requirements, user stories, acceptance criteria +- `ux-design.md` — UX specification with journeys and wireframes +- `nfr-assessment.md` — Security, performance, reliability evaluation -- Code standards from `.ai-coding-config/rules/` -- Commit conventions -- PR review checklists -- Test coverage requirements -- Security review gates +#### Phase 3: Solutioning (Track-Dependent) ---- +``` +/bmad:architecture → System design with Architecture Decision Records +/bmad:epics-and-stories → Work breakdown structure +/bmad:test-design → Risk assessment and coverage strategy +/bmad:implementation-readiness → Gate validation before coding +``` -## Submodule Setup +**Output Artifacts:** +- `architecture.md` — System design, component diagrams, data flows, ADRs +- `epic-N.md` — Epic breakdown with stories and acceptance criteria +- `story-{id}.md` — Individual stories with implementation details +- `test-design-*.md` — Test strategy per epic -### Initial Installation +#### Phase 4: Handoff -```bash -# Fork both repos to your org first, then: +``` +/bmad:finalize → Validate completeness, generate handoff summary +``` -# Add BMAD as submodule -git submodule add https://github.com/YOUR-ORG/bmad-method .bmad -git submodule update --init --recursive +**Output:** +- `PLANNING_COMPLETE.md` — Summary of all decisions, ready for execution -# Add ai-coding-config as submodule -git submodule add https://github.com/YOUR-ORG/ai-coding-config .ai-coding-config -git submodule update --init --recursive -``` +### BMAD Special Capabilities -### Directory Structure +#### Party Mode +Multi-agent collaboration where the BMad Master orchestrates 2-3 relevant agents per topic for real-time multi-perspective analysis. ``` -your-project/ -├── .bmad/ # BMAD submodule (forked) -│ ├── agents/ -│ ├── workflows/ -│ └── ... -├── .ai-coding-config/ # ai-coding-config submodule (forked) -│ ├── commands/ -│ ├── agents/ -│ ├── rules/ -│ └── ... -├── docs/ # BMAD writes here -│ ├── strategy.md -│ ├── architecture.md -│ └── ... -├── src/ # ai-coding-config builds here -└── ... +/bmad:party-mode → Launch collaborative session with multiple agents ``` -### Pulling Upstream Updates +#### Advanced Elicitation +50+ reasoning methods for LLM re-examination of generated content: +- First Principles Analysis +- Stakeholder Round Tables +- Expert Panels +- Red Team vs Blue Team +- Tree of Thoughts frameworks -```bash -# Update BMAD from upstream -cd .bmad -git fetch upstream -git merge upstream/main -cd .. -git add .bmad -git commit -m "🔄 Update BMAD submodule" - -# Update ai-coding-config from upstream -cd .ai-coding-config -git fetch upstream -git merge upstream/main -cd .. -git add .ai-coding-config -git commit -m "🔄 Update ai-coding-config submodule" -``` +#### Context Auto-Discovery +Automatically analyzes `package.json`, `requirements.txt`, `go.mod` to detect: +- Project stack and dependencies +- Existing patterns and conventions +- Test frameworks and code style --- -## The Handoff - -The transition from planning to execution is explicit and documented. +## Phase 2: Execution (ai-coding-config) -### Handoff Trigger +ai-coding-config provides autonomous execution with 21 commands, 24 review agents, and full PR lifecycle automation. -When BMAD completes planning: +### The Execution Pipeline ``` -/bmad:finalize +┌──────────────────────────────────────────────────────────────────────────┐ +│ AUTONOMOUS EXECUTION FLOW │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ SETUP │ │ IMPLEMENT │ │ REVIEW │ │ +│ │ │───→│ │───→│ │ │ +│ │ /setup- │ │ /autotask │ │ /multi- │ │ +│ │ environment │ │ │ │ review │ │ +│ └─────────────┘ └─────────────┘ └──────┬──────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ WORKTREE │ │ CREATE │ │ ADDRESS │ │ +│ │ CREATION │ │ PR │───→│ COMMENTS │◄─────┐ │ +│ │ │ │ │ │ │ │ │ +│ │ Isolated │ │ Auto-commit │ │ Fix issues │ │ │ +│ │ environment │ │ Auto-push │ │ Decline bad │ Iterate │ +│ └─────────────┘ └─────────────┘ │ suggestions │ │ │ +│ └──────┬──────┘ │ │ +│ │ │ │ +│ ▼ │ │ +│ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ CLEANUP │ │ BOT RE- │ │ │ +│ │ │◄───│ ANALYSIS │──────┘ │ +│ │ /wrap-up │ │ │ │ +│ │ /cleanup- │ │ Cursor │ │ +│ │ worktree │ │ Claude │ │ +│ └─────────────┘ │ Codex │ │ +│ │ Greptile │ │ +│ └─────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────┘ ``` -This command: -1. Validates all required docs exist -2. Runs completeness checks -3. Generates a `docs/PLANNING_COMPLETE.md` summary -4. Signals readiness for execution phase +### Pre-Implementation: Environment Setup -### Handoff Artifact +#### Git Worktree Workflow -```markdown - -# Planning Phase Complete +ai-coding-config uses git worktrees for isolated, parallel development: -## Summary -- Project: [Name] -- Scale Level: [0-4] -- Tech Stack: [Chosen technologies] - -## Documents Ready -- [x] strategy.md -- [x] requirements.md -- [x] architecture.md -- [x] api-contracts.md +``` +/setup-environment → Initialize worktree with full dev environment +``` -## Key Decisions -1. Using PostgreSQL for persistence (see tech-decisions.md#database) -2. React + TypeScript frontend (see tech-decisions.md#frontend) -3. REST API with OpenAPI spec (see api-contracts.md) +**What it does:** +- Detects project type (Node.js, Python, Ruby, Go, Rust, Java, .NET) +- Identifies package manager (pnpm, yarn, bun, npm) +- Creates isolated worktree from main +- Installs dependencies with locked versions +- Copies environment files (.env, .env.local, secrets) +- Sets up git hooks (Husky, pre-commit) +- Runs code generation (Prisma, GraphQL, TypeScript) +- Validates environment is ready -## Ready for Execution -Planning is complete. Run `/build:load-context` to begin implementation. -``` +**Why worktrees:** +- Work on multiple features simultaneously +- Keep main branch clean +- Isolated dependencies per feature +- Easy cleanup after merge -### Starting Execution +### Implementation: Autonomous Task Execution ``` -/build:load-context docs/ +/autotask "Implement user authentication per docs/architecture.md" ``` -ai-coding-config: -1. Reads all planning documents -2. Extracts requirements as actionable tasks -3. Loads appropriate rules for the tech stack -4. Begins implementation following documented architecture +**Complexity Levels:** ---- +| Level | Scope | Planning | Review | Bot Handling | +|-------|-------|----------|--------|--------------| +| **quick** | Single file, clear requirements | Skip | Self-review | 2 min wait | +| **balanced** | Multi-file, some design | /load-rules | 2-3 agents | 5 min wait | +| **deep** | Architectural, high-risk | Full exploration | 5+ agents | 15 min wait | -## Why This Works +**The /autotask Pipeline:** -### Complete Isolation +1. **Analyze** — Determine complexity, load relevant rules +2. **Explore** — Delegate codebase exploration to sub-agents +3. **Plan** — Create implementation outline (deep: review plan with agents first) +4. **Implement** — Execute with autonomous-developer agent +5. **Validate** — Run tests, verify behavior +6. **Review** — Multi-agent code review +7. **Create PR** — Auto-commit, push, create PR with full description +8. **Bot Feedback** — Wait for CI bots, then address feedback +9. **Iterate** — Fix valid issues, decline incorrect suggestions +10. **Complete** — PR ready for human review -| Aspect | Benefit | -|--------|---------| -| Separate submodules | Each framework updates independently | -| No runtime coupling | No complex integration code to maintain | -| Forked repos | Customize without losing upstream connection | -| Document contract | Clear interface between phases | +### Review: Multi-Agent Code Analysis -### Clear Responsibilities +``` +/multi-review deep → Run 5+ parallel review agents +``` -| Phase | Owner | Artifacts | -|-------|-------|-----------| -| Planning | BMAD | Markdown docs in `docs/` | -| Execution | ai-coding-config | Code in `src/`, tests, PRs | +**The 24 Review Agents:** -### Upstream Maintenance +| Category | Agents | Focus | +|----------|--------|-------| +| **Correctness** | logic-reviewer, error-handling-reviewer, security-reviewer, robustness-reviewer | Bugs, exceptions, OWASP top 10, production readiness | +| **Performance** | performance-reviewer, simplifier | N+1 queries, complexity, optimization | +| **UX** | empathy-reviewer, ux-designer, design-reviewer, mobile-ux-reviewer | User experience, accessibility, responsive design | +| **Architecture** | architecture-auditor, style-reviewer, observability-reviewer | Design patterns, conventions, logging | +| **Quality** | comment-analyzer, test-analyzer, seo-specialist | Comment accuracy, test coverage, SEO | +| **Development** | autonomous-developer, test-engineer, debugger | Implementation, testing, root cause analysis | +| **Specialized** | git-writer, prompt-engineer, library-advisor | Commits, prompts, dependencies | -Both frameworks evolve independently: +### PR Automation: Full Lifecycle -- Pull BMAD updates for new planning workflows -- Pull ai-coding-config updates for new review agents -- Your forks let you customize while staying connected -- Submodules pin to specific commits for stability +#### Creating the PR ---- +``` +/autotask creates PR with: +- Proper branch from worktree +- Conventional commits +- Full description with: + - Summary of changes + - Design decisions with rationale + - Complexity level and why + - Validation performed +``` -## Unified Command Namespace +#### Addressing Bot Feedback -While the systems are isolated, the developer experience is unified through namespaced commands: +``` +/address-pr-comments → Autonomous bot feedback triage +``` -### Planning Commands (BMAD) +**What it handles:** +- Fetches comments from all code review bots (Claude, Cursor, Codex, Greptile) +- Triages each comment: + - **Fix** — Valid issue, implements the fix + - **Incorrect** — Bot lacks context, explains why with 👎 reaction + - **WONTFIX** — Technically correct but unwanted, declines with explanation + - **GitHub Issue** — Valid but out of scope, creates trackable issue +- Adds reactions to train bot behavior (👍, ❤️, 👎, 🚀) +- Pushes fixes, waits for re-analysis, iterates until clean +- Tracks processed comments to avoid re-processing + +**Iteration Protocol:** +1. Poll for bot completion (2-15 min based on complexity) +2. Process available feedback immediately +3. Fix valid issues, commit, push +4. Bots re-analyze +5. Repeat until no new actionable feedback +6. Report summary: Fixed (N), Declined (N), Issues Created (N) + +#### Merging and Cleanup ``` -/bmad:help → Show available planning workflows -/bmad:start → Begin new project planning -/bmad:analyze → Requirements and analysis phase -/bmad:plan → Sprint and milestone planning -/bmad:architect → Technical architecture -/bmad:brand → Brand and style guidelines -/bmad:finalize → Complete planning, prepare handoff +/wrap-up → Merge PR, sync local, clean up branch +/cleanup-worktree → Remove worktree after merge verification ``` -### Execution Commands (ai-coding-config) +**What /wrap-up does:** +- Verifies PR is mergeable (no conflicts, checks pass) +- Merges with `gh pr merge --merge --delete-branch` +- Checks out main, pulls latest +- Deletes local feature branch +- Reports clear state for context-switching + +**What /cleanup-worktree does:** +- Verifies branch was merged to main +- Removes worktree directory +- Preserves all branches for git history +- Returns to primary repo on main + +### Session Management: Context Preservation ``` -/build:load-context → Ingest planning docs -/build:autotask → Autonomous implementation -/build:review → Code review workflow -/build:troubleshoot → Debugging assistance -/session:save → Persist current state -/session:resume → Restore previous session -/load-rules → Load stack-specific rules +/session save → Persist context, decisions, progress +/session resume → Restore exactly where you left off +/handoff-context → Generate context transfer documentation ``` -### The Mental Model +**Survives:** +- Context compaction +- Tool restarts +- Multi-day work sessions +- Team handoffs + +### Additional Commands + +| Command | Purpose | +|---------|---------| +| `/do-issue 123` | Full issue lifecycle: triage → implement → PR → merge | +| `/troubleshoot` | Connect to error tracking, analyze, fix bugs | +| `/verify-fix` | Confirm solutions work from user perspective | +| `/load-rules` | Load stack-specific coding standards | +| `/repo-tooling` | Configure linting, formatting, CI/CD | +| `/product-intel` | Competitive research and analysis | +| `/polish-sweep` | Final quality pass before release | +| `/upgrade-deps` | Safe dependency updates | + +--- + +## The Complete Lifecycle + +### From Idea to Merged PR ``` -Am I deciding WHAT to build? → /bmad:* -Am I writing HOW to build it? → /build:* +┌─────────────────────────────────────────────────────────────────────────────┐ +│ COMPLETE WORKFLOW │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ IDEA │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ BMAD PLANNING │ │ +│ │ │ │ +│ │ /bmad:brainstorm "What if we add real-time collaboration?" │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /bmad:research Market analysis, competitor features │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /bmad:prd Requirements, user stories, acceptance │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /bmad:architecture WebSocket vs SSE, data sync strategy │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /bmad:epics-and-stories Work breakdown: 3 epics, 12 stories │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /bmad:finalize All docs ready, handoff complete │ │ +│ │ │ │ +│ │ OUTPUT: docs/architecture.md, docs/prd.md, docs/epic-*.md │ │ +│ └─────────────────────────────┬───────────────────────────────────────┘ │ +│ │ │ +│ Document Handoff │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ AI-CODING-CONFIG EXECUTION │ │ +│ │ │ │ +│ │ /setup-environment Create worktree, install deps, setup env │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /autotask "Implement story-1 per docs/epic-1.md" │ │ +│ │ │ │ │ +│ │ ├── Explores codebase via sub-agents │ │ +│ │ ├── Implements with autonomous-developer │ │ +│ │ ├── Writes tests with test-engineer │ │ +│ │ ├── Runs /multi-review (5 agents) │ │ +│ │ ├── Creates PR #47 │ │ +│ │ ├── Waits for bots (Claude, Cursor, Codex) │ │ +│ │ └── Runs /address-pr-comments │ │ +│ │ │ │ │ +│ │ ├── Fixes 3 valid issues │ │ +│ │ ├── Declines 2 incorrect suggestions │ │ +│ │ └── Creates 1 follow-up issue │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ PR #47 ready for human review │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /wrap-up Merge, sync main, delete branch │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ /cleanup-worktree Remove worktree, preserve history │ │ +│ │ │ │ +│ │ OUTPUT: Merged code in main, clean git state │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ SHIPPED │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ ``` --- -## Getting Started +## Submodule Installation ### 1. Fork Both Repos -- Fork `bmad-code-org/BMAD-METHOD` → `your-org/bmad-method` -- Fork `Light-Brands/ai-coding-config` → `your-org/ai-coding-config` +```bash +# Fork to your organization +# bmad-code-org/BMAD-METHOD → your-org/bmad-method +# Light-Brands/ai-coding-config → your-org/ai-coding-config +``` -### 2. Add Submodules to Your Project +### 2. Add as Submodules ```bash +# Add BMAD git submodule add https://github.com/your-org/bmad-method .bmad +git submodule update --init --recursive + +# Add ai-coding-config git submodule add https://github.com/your-org/ai-coding-config .ai-coding-config +git submodule update --init --recursive ``` -### 3. Start Planning +### 3. Configure Upstream Remotes -``` -/bmad:start -``` - -### 4. Complete Planning Docs +```bash +# In .bmad/ +cd .bmad +git remote add upstream https://github.com/bmad-code-org/BMAD-METHOD +cd .. -Work through BMAD workflows until all docs are ready. +# In .ai-coding-config/ +cd .ai-coding-config +git remote add upstream https://github.com/Light-Brands/ai-coding-config +cd .. +``` -### 5. Finalize and Hand Off +### 4. Directory Structure ``` -/bmad:finalize +your-project/ +├── .bmad/ # BMAD submodule (forked) +│ ├── agents/ # 8 specialized planning agents +│ ├── workflows/ # 50+ guided workflows +│ ├── tasks/ # Reusable task definitions +│ └── templates/ # Document templates +├── .ai-coding-config/ # ai-coding-config submodule (forked) +│ ├── commands/ # 21 automation commands +│ ├── agents/ # 24 review agents +│ ├── rules/ # 33 coding standards +│ ├── skills/ # 6 multi-step capabilities +│ └── personalities/ # 7 communication styles +├── docs/ # BMAD writes here +│ ├── product-brief.md +│ ├── prd.md +│ ├── architecture.md +│ ├── epic-*.md +│ ├── story-*.md +│ └── PLANNING_COMPLETE.md +├── src/ # ai-coding-config builds here +└── .gitworktrees/ # Isolated development environments ``` -### 6. Begin Execution +### 5. Pulling Upstream Updates -``` -/build:load-context docs/ -/build:autotask "Implement user authentication per docs/architecture.md" +```bash +# Update BMAD +cd .bmad +git fetch upstream +git merge upstream/main +cd .. +git add .bmad && git commit -m "🔄 Update BMAD submodule" + +# Update ai-coding-config +cd .ai-coding-config +git fetch upstream +git merge upstream/main +cd .. +git add .ai-coding-config && git commit -m "🔄 Update ai-coding-config submodule" ``` --- -## Summary +## Command Reference + +### BMAD Commands (Planning) + +| Command | Phase | Output | +|---------|-------|--------| +| `/bmad:brainstorm` | Analysis | Ideas, themes, action plans | +| `/bmad:research` | Analysis | Market/technical findings | +| `/bmad:product-brief` | Analysis | Strategic vision document | +| `/bmad:prd` | Planning | Product Requirements Document | +| `/bmad:ux-design` | Planning | UX specification | +| `/bmad:nfr-assess` | Planning | Non-functional requirements | +| `/bmad:architecture` | Solutioning | System design with ADRs | +| `/bmad:epics-and-stories` | Solutioning | Work breakdown structure | +| `/bmad:test-design` | Solutioning | Test strategy and coverage | +| `/bmad:implementation-readiness` | Solutioning | Gate validation | +| `/bmad:party-mode` | Any | Multi-agent collaboration | +| `/bmad:finalize` | Handoff | PLANNING_COMPLETE.md | + +### ai-coding-config Commands (Execution) + +| Command | Stage | Purpose | +|---------|-------|---------| +| `/setup-environment` | Setup | Initialize worktree with deps | +| `/load-rules` | Setup | Load stack-specific standards | +| `/autotask` | Implement | Full autonomous implementation | +| `/do-issue` | Implement | Issue → PR lifecycle | +| `/troubleshoot` | Debug | Error analysis and fixing | +| `/verify-fix` | Validate | Confirm behavior works | +| `/multi-review` | Review | Parallel multi-agent review | +| `/address-pr-comments` | PR | Triage and fix bot feedback | +| `/wrap-up` | Merge | Merge PR, sync, cleanup | +| `/cleanup-worktree` | Cleanup | Remove worktree post-merge | +| `/session save` | Persist | Save context and progress | +| `/session resume` | Persist | Restore previous session | +| `/handoff-context` | Persist | Generate transfer docs | -| Question | Answer | -|----------|--------| -| Are they integrated? | No—completely isolated | -| How do they communicate? | Through documentation only | -| Can I update them independently? | Yes—separate submodules, forked repos | -| What's the handoff? | BMAD writes docs, ai-coding-config reads them | -| When do I use BMAD? | Before writing code | -| When do I use ai-coding-config? | When writing code | +--- -**BMAD answers:** "What are we building and why?" +## The Mental Model -**ai-coding-config answers:** "How do we build it correctly?" +``` +┌────────────────────────────────────────────────────────────────┐ +│ │ +│ "What are we building?" "How do we build it?" │ +│ │ +│ BMAD ai-coding-config │ +│ │ +│ • Strategy & vision • Environment setup │ +│ • Requirements • Implementation │ +│ • Architecture • Testing │ +│ • User stories • Code review │ +│ • Test strategy • PR automation │ +│ • Brand guidelines • Bot feedback │ +│ • Merge & cleanup │ +│ │ +│ /bmad:* /build:* │ +│ │ +│ OUTPUT: Documentation OUTPUT: Shipped Code │ +│ │ +└────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Summary -One plans. One executes. Documentation is the contract. +| Dimension | BMAD | ai-coding-config | +|-----------|------|------------------| +| **Phase** | Planning | Execution | +| **Agents** | 8 planning specialists | 24 review specialists | +| **Workflows** | 50+ structured processes | 21 automation commands | +| **Input** | Ideas, requirements | Planning documentation | +| **Output** | PRD, architecture, stories | Merged, tested code | +| **Special Powers** | Party mode, 60+ ideation techniques | Git worktrees, PR automation | + +**Together they provide:** + +- Structured planning that prevents "just start coding" mistakes +- Comprehensive documentation before implementation +- Autonomous execution with full test coverage +- Multi-agent code review from 24 perspectives +- Full PR lifecycle automation with iterative bot feedback +- Clean git workflow with worktrees and proper cleanup + +**One plans. One executes. Documentation is the contract.**