diff --git a/resources/skills/bmad-guide.md b/resources/skills/bmad-guide.md index 0f2ac6aa..f16b73cd 100644 --- a/resources/skills/bmad-guide.md +++ b/resources/skills/bmad-guide.md @@ -7,7 +7,7 @@ You are working within the **BMAD Method (BMM)** - a 4-phase AI-powered agile de 1. **NEVER skip phases** - Each phase builds on the previous (except Phase 1 which is optional) 2. **ALWAYS check project level** - This determines which workflows to use 3. **ALWAYS use workflows** - Don't implement features manually without BMAD workflows -4. **ALWAYS consult workflow docs** - Located in `src/modules/bmm/workflows/` +4. **ALWAYS consult workflow docs** - Located in `src/bmm/workflows/` 5. **STAY IN PHASE** - Complete current phase before moving to next --- @@ -143,32 +143,32 @@ You are working within the **BMAD Method (BMM)** - a 4-phase AI-powered agile de ### Method 1: Read Workflow Documentation ```bash # Read workflow guide for current phase -cat src/modules/bmm/workflows/README.md -cat src/modules/bmm/docs/workflows-{phase}.md +cat src/bmm/workflows/README.md +cat src/bmm/docs/workflows-{phase}.md # Example: Planning phase -cat src/modules/bmm/docs/workflows-planning.md +cat src/bmm/docs/workflows-planning.md # Example: Implementation phase -cat src/modules/bmm/docs/workflows-implementation.md +cat src/bmm/docs/workflows-implementation.md ``` ### Method 2: Read Specific Workflow ```bash # Read workflow details -cat src/modules/bmm/workflows/{phase}/{workflow-name}/README.md +cat src/bmm/workflows/{phase}/{workflow-name}/README.md # Example: PRD workflow -cat src/modules/bmm/workflows/2-plan-workflows/prd/README.md +cat src/bmm/workflows/2-plan-workflows/prd/README.md # Example: Dev story workflow -cat src/modules/bmm/workflows/4-implementation/dev-story/README.md +cat src/bmm/workflows/4-implementation/dev-story/README.md ``` ### Method 3: Check Workflow Configuration ```bash # See workflow config -cat src/modules/bmm/workflows/{phase}/{workflow-name}/workflow.yaml +cat src/bmm/workflows/{phase}/{workflow-name}/workflow.yaml ``` ### Method 4: Use Explore Agent @@ -363,16 +363,16 @@ cat {project-root}/_bmad/bmm/workflow-status.yaml ## πŸ“– ADDITIONAL RESOURCES ### Core Documentation -- `src/modules/bmm/docs/workflows-analysis.md` - Phase 1 guidance -- `src/modules/bmm/docs/workflows-planning.md` - Phase 2 guidance -- `src/modules/bmm/docs/workflows-solutioning.md` - Phase 3 guidance -- `src/modules/bmm/docs/workflows-implementation.md` - Phase 4 guidance -- `src/modules/bmm/docs/scale-adaptive-system.md` - Level detection -- `src/modules/bmm/docs/brownfield-guide.md` - Existing codebases +- `src/bmm/docs/workflows-analysis.md` - Phase 1 guidance +- `src/bmm/docs/workflows-planning.md` - Phase 2 guidance +- `src/bmm/docs/workflows-solutioning.md` - Phase 3 guidance +- `src/bmm/docs/workflows-implementation.md` - Phase 4 guidance +- `src/bmm/docs/scale-adaptive-system.md` - Level detection +- `src/bmm/docs/brownfield-guide.md` - Existing codebases ### Specialized Guides -- `src/modules/bmm/docs/test-architecture.md` - TestArch workflows -- `src/modules/bmm/docs/agents-guide.md` - All 12 specialized agents +- `src/bmm/docs/test-architecture.md` - TestArch workflows +- `src/bmm/docs/agents-guide.md` - All 12 specialized agents --- diff --git a/src/modules/bmm/patterns/README.md b/src/bmm/patterns/README.md similarity index 100% rename from src/modules/bmm/patterns/README.md rename to src/bmm/patterns/README.md diff --git a/src/bmm/patterns/agent-completion.md b/src/bmm/patterns/agent-completion.md index d256c155..f2cf1309 100644 --- a/src/bmm/patterns/agent-completion.md +++ b/src/bmm/patterns/agent-completion.md @@ -1,187 +1,225 @@ -# Agent Completion Format +# Agent Completion Artifact Pattern - -All agents must return structured output that the orchestrator can parse. This enables automated verification and reliable workflow progression. +**Problem:** Agents fail to update story files reliably (60% success rate) +**Solution:** Agents create completion.json artifacts. Orchestrator uses them to update story files. -**Principle:** Return parseable data, not prose. The orchestrator needs to extract file lists, status, and evidence. - +## The Contract - -## Standard Completion Format +### Agent Responsibility +Each agent MUST create a completion artifact before finishing: +- **File path:** `docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json` +- **Format:** Structured JSON (see formats below) +- **Verification:** File exists = work done (binary check) -Every agent returns this structure when done: +### Orchestrator Responsibility +Orchestrator reads completion artifacts and: +- Parses JSON for structured data +- Updates story file tasks (check off completed) +- Fills Dev Agent Record with evidence +- Verifies updates succeeded + +## Why This Works + +**File-based verification:** +- βœ… Binary check: File exists or doesn't +- βœ… No complex parsing of agent output +- βœ… No reconciliation logic needed +- βœ… Hard stop if artifact missing + +**JSON format:** +- βœ… Easy to parse reliably +- βœ… Structured data (not prose) +- βœ… Version controllable +- βœ… Auditable trail + +## How to Use This Pattern + +### In Agent Prompts + +Include this in every agent prompt: ```markdown -## AGENT COMPLETE +## CRITICAL: Create Completion Artifact -**Agent:** [builder|inspector|reviewer|fixer] -**Story:** {{story_key}} -**Status:** [SUCCESS|PASS|FAIL|ISSUES_FOUND|PARTIAL] +**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. -### [Agent-Specific Section] -[See below for each agent type] +**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json` -### Files Created -- path/to/new/file.ts -- path/to/another.ts - -### Files Modified -- path/to/existing/file.ts - -### Ready For -[Next phase or action required] +**Format:** +```json +{ + "story_key": "{{story_key}}", + "agent": "{{agent_name}}", + "status": "SUCCESS", + "files_created": ["file1.ts", "file2.ts"], + "files_modified": ["file3.ts"], + "timestamp": "2026-01-27T02:30:00Z" +} ``` - - -## Builder Agent Output - -```markdown -## AGENT COMPLETE - -**Agent:** builder -**Story:** {{story_key}} -**Status:** SUCCESS | FAILED - -### Files Created -- src/lib/feature/service.ts -- src/lib/feature/__tests__/service.test.ts - -### Files Modified -- src/app/api/feature/route.ts - -### Tests Added -- 3 test files -- 12 test cases total - -### Implementation Summary -Brief description of what was built. - -### Known Gaps -- Edge case X not handled -- NONE if all complete - -### Ready For -Inspector validation +**Use Write tool to create this file. No exceptions.** ``` - - -## Inspector Agent Output +### In Orchestrator Verification -```markdown -## AGENT COMPLETE - -**Agent:** inspector -**Story:** {{story_key}} -**Status:** PASS | FAIL - -### Evidence -- **Type Check:** PASS (0 errors) -- **Lint:** PASS (0 warnings) -- **Build:** PASS -- **Tests:** 45 passing, 0 failing, 92% coverage - -### Files Verified -- src/lib/feature/service.ts βœ“ -- src/app/api/feature/route.ts βœ“ - -### Failures (if FAIL status) -1. Type error in service.ts:45 -2. Test failing: "should handle empty input" - -### Ready For -Reviewer (if PASS) | Builder fix (if FAIL) -``` - - - -## Reviewer Agent Output - -```markdown -## AGENT COMPLETE - -**Agent:** reviewer -**Story:** {{story_key}} -**Status:** ISSUES_FOUND | CLEAN - -### Issue Summary -- **CRITICAL:** 1 (security, data loss) -- **HIGH:** 2 (production bugs) -- **MEDIUM:** 3 (tech debt) -- **LOW:** 1 (nice-to-have) - -### Must Fix (CRITICAL + HIGH) -1. [CRITICAL] service.ts:45 - SQL injection vulnerability -2. [HIGH] route.ts:23 - Missing authorization check -3. [HIGH] service.ts:78 - Unhandled null case - -### Should Fix (MEDIUM) -1. service.ts:92 - No error logging - -### Files Reviewed -- src/lib/feature/service.ts βœ“ -- src/app/api/feature/route.ts βœ“ - -### Ready For -Fixer agent to address CRITICAL and HIGH issues -``` - - - -## Fixer Agent Output - -```markdown -## AGENT COMPLETE - -**Agent:** fixer -**Story:** {{story_key}} -**Status:** SUCCESS | PARTIAL | FAILED - -### Issues Fixed -- **CRITICAL:** 1/1 fixed -- **HIGH:** 2/2 fixed -- **Total:** 3 issues resolved - -### Fixes Applied -1. [CRITICAL] service.ts:45 - Parameterized query -2. [HIGH] route.ts:23 - Added auth check -3. [HIGH] service.ts:78 - Added null guard - -### Quality Checks -- **Type Check:** PASS -- **Lint:** PASS -- **Tests:** 47 passing (2 new) - -### Git Commit -- **Hash:** abc123def -- **Message:** fix({{story_key}}): address security and null handling - -### Deferred Issues -- MEDIUM: 3 (defer to follow-up) -- LOW: 1 (skip as gold-plating) - -### Ready For -Orchestrator reconciliation -``` - - - -## Parsing Hints for Orchestrator - -Extract key data using grep: +After agent completes, verify artifact exists: ```bash -# Get status -grep "^\*\*Status:\*\*" agent_output.txt | cut -d: -f2 | xargs +COMPLETION_FILE="docs/sprint-artifacts/completions/{{story_key}}-{{agent}}.json" -# Get files created -sed -n '/### Files Created/,/###/p' agent_output.txt | grep "^-" | cut -d' ' -f2 +if [ ! -f "$COMPLETION_FILE" ]; then + echo "❌ BLOCKER: Agent failed to create completion artifact" + exit 1 +fi -# Get issue count -grep "CRITICAL:" agent_output.txt | grep -oE "[0-9]+" - -# Check if ready for next phase -grep "### Ready For" -A 1 agent_output.txt | tail -1 +echo "βœ… Completion artifact found" ``` - + +### In Reconciliation + +Parse artifact to update story file: + +```markdown +1. Load completion artifact with Read tool +2. Parse JSON to extract data +3. Use Edit tool to update story file +4. Verify updates with bash checks +``` + +## Artifact Formats by Agent + +### Builder Completion + +```json +{ + "story_key": "19-4", + "agent": "builder", + "status": "SUCCESS", + "tasks_completed": [ + "Create PaymentProcessor service", + "Add retry logic with exponential backoff" + ], + "files_created": [ + "lib/billing/payment-processor.ts", + "lib/billing/__tests__/payment-processor.test.ts" + ], + "files_modified": [ + "lib/billing/worker.ts" + ], + "tests": { + "files": 2, + "cases": 15 + }, + "timestamp": "2026-01-27T02:30:00Z" +} +``` + +### Inspector Completion + +```json +{ + "story_key": "19-4", + "agent": "inspector", + "status": "PASS", + "quality_checks": { + "type_check": "PASS", + "lint": "PASS", + "build": "PASS" + }, + "tests": { + "passing": 45, + "failing": 0, + "total": 45, + "coverage": 95 + }, + "files_verified": [ + "lib/billing/payment-processor.ts" + ], + "timestamp": "2026-01-27T02:35:00Z" +} +``` + +### Reviewer Completion + +```json +{ + "story_key": "19-4", + "agent": "reviewer", + "status": "ISSUES_FOUND", + "issues": { + "critical": 2, + "high": 3, + "medium": 4, + "low": 2, + "total": 11 + }, + "must_fix": [ + { + "severity": "CRITICAL", + "location": "api/route.ts:45", + "description": "SQL injection vulnerability" + } + ], + "files_reviewed": [ + "api/route.ts" + ], + "timestamp": "2026-01-27T02:40:00Z" +} +``` + +### Fixer Completion (FINAL) + +```json +{ + "story_key": "19-4", + "agent": "fixer", + "status": "SUCCESS", + "issues_fixed": { + "critical": 2, + "high": 3, + "total": 5 + }, + "fixes_applied": [ + "Fixed SQL injection in agreement route (CRITICAL)", + "Added authorization check (CRITICAL)" + ], + "files_modified": [ + "api/route.ts" + ], + "quality_checks": { + "type_check": "PASS", + "lint": "PASS", + "build": "PASS" + }, + "tests": { + "passing": 48, + "failing": 0, + "total": 48, + "coverage": 96 + }, + "git_commit": "a1b2c3d4e5f", + "timestamp": "2026-01-27T02:50:00Z" +} +``` + +## Benefits + +- **Reliability:** 60% β†’ 100% (file exists is binary) +- **Simplicity:** No complex output parsing +- **Auditability:** JSON files are version controlled +- **Debuggability:** Can inspect artifacts when issues occur +- **Enforcement:** Can't proceed without completion artifact (hard stop) + +## Anti-Patterns + +**Don't do this:** +- ❌ Trust agent output without verification +- ❌ Parse agent prose for structured data +- ❌ Let agents update story files directly +- ❌ Skip artifact creation ("just this once") + +**Do this instead:** +- βœ… Verify artifact exists (binary check) +- βœ… Parse JSON for reliable data +- βœ… Orchestrator updates story files +- βœ… Hard stop if artifact missing diff --git a/src/bmm/patterns/security-checklist.md b/src/bmm/patterns/security-checklist.md index b7e41310..70ffc1c5 100644 --- a/src/bmm/patterns/security-checklist.md +++ b/src/bmm/patterns/security-checklist.md @@ -1,122 +1,340 @@ # Security Review Checklist - -Security vulnerabilities are CRITICAL issues. A single vulnerability can expose user data, enable account takeover, or cause financial loss. +**Philosophy:** Security issues are CRITICAL. No exceptions. -**Principle:** Assume all input is malicious. Validate everything. - +This checklist helps identify common security vulnerabilities in code reviews. - -## OWASP Top 10 Checks +## CRITICAL Security Issues -### 1. Injection -```bash -# Check for SQL injection -grep -E "SELECT.*\+|INSERT.*\+|UPDATE.*\+|DELETE.*\+" . -r -grep -E '\$\{.*\}.*query|\`.*\$\{' . -r +These MUST be fixed. No story ships with these issues. -# Check for command injection -grep -E "exec\(|spawn\(|system\(" . -r +### 1. SQL Injection + +**Look for:** +```javascript +// ❌ BAD: User input in query string +const query = `SELECT * FROM users WHERE id = '${userId}'`; +const query = "SELECT * FROM users WHERE id = '" + userId + "'"; ``` -**Fix:** Use parameterized queries, never string concatenation. +**Fix with:** +```javascript +// βœ… GOOD: Parameterized queries +const query = db.prepare('SELECT * FROM users WHERE id = ?'); +query.get(userId); -### 2. Broken Authentication -```bash -# Check for hardcoded credentials -grep -E "password.*=.*['\"]|api.?key.*=.*['\"]|secret.*=.*['\"]" . -r -i - -# Check for weak session handling -grep -E "localStorage.*token|sessionStorage.*password" . -r +// βœ… GOOD: ORM/Query builder +const user = await prisma.user.findUnique({ where: { id: userId } }); ``` -**Fix:** Use secure session management, never store secrets in code. +### 2. XSS (Cross-Site Scripting) -### 3. Sensitive Data Exposure -```bash -# Check for PII logging -grep -E "console\.(log|info|debug).*password|log.*email|log.*ssn" . -r -i - -# Check for unencrypted transmission -grep -E "http://(?!localhost)" . -r +**Look for:** +```javascript +// ❌ BAD: Unsanitized user input in HTML +element.innerHTML = userInput; +document.write(userInput); ``` -**Fix:** Never log sensitive data, always use HTTPS. +**Fix with:** +```javascript +// βœ… GOOD: Use textContent or sanitize +element.textContent = userInput; -### 4. XML External Entities (XXE) -```bash -# Check for unsafe XML parsing -grep -E "parseXML|DOMParser|xml2js" . -r +// βœ… GOOD: Use framework's built-in escaping +
{userInput}
// React automatically escapes ``` -**Fix:** Disable external entity processing. +### 3. Authentication Bypass -### 5. Broken Access Control -```bash -# Check for missing auth checks -grep -E "export.*function.*(GET|POST|PUT|DELETE)" . -r | head -20 -# Then verify each has auth check +**Look for:** +```javascript +// ❌ BAD: No auth check +app.get('/api/admin/users', async (req, res) => { + const users = await getUsers(); + res.json(users); +}); ``` -**Fix:** Every endpoint must verify user has permission. - -### 6. Security Misconfiguration -```bash -# Check for debug mode in prod -grep -E "debug.*true|NODE_ENV.*development" . -r - -# Check for default credentials -grep -E "admin.*admin|password.*password|123456" . -r +**Fix with:** +```javascript +// βœ… GOOD: Require auth +app.get('/api/admin/users', requireAuth, async (req, res) => { + const users = await getUsers(); + res.json(users); +}); ``` -**Fix:** Secure configuration, no defaults. +### 4. Authorization Gaps -### 7. Cross-Site Scripting (XSS) -```bash -# Check for innerHTML usage -grep -E "innerHTML|dangerouslySetInnerHTML" . -r - -# Check for unescaped output -grep -E "\$\{.*\}.*<|<.*\$\{" . -r +**Look for:** +```javascript +// ❌ BAD: No ownership check +app.delete('/api/orders/:id', async (req, res) => { + await deleteOrder(req.params.id); + res.json({ success: true }); +}); ``` -**Fix:** Always escape user input, use safe rendering. - -### 8. Insecure Deserialization -```bash -# Check for unsafe JSON parsing -grep -E "JSON\.parse\(.*req\." . -r -grep -E "eval\(|Function\(" . -r +**Fix with:** +```javascript +// βœ… GOOD: Verify user owns resource +app.delete('/api/orders/:id', async (req, res) => { + const order = await getOrder(req.params.id); + + if (order.userId !== req.user.id) { + return res.status(403).json({ error: 'Forbidden' }); + } + + await deleteOrder(req.params.id); + res.json({ success: true }); +}); ``` -**Fix:** Validate structure before parsing. +### 5. Hardcoded Secrets -### 9. Using Components with Known Vulnerabilities +**Look for:** +```javascript +// ❌ BAD: Secrets in code +const API_KEY = 'sk-1234567890abcdef'; +const DB_PASSWORD = 'MyP@ssw0rd123'; +``` + +**Fix with:** +```javascript +// βœ… GOOD: Environment variables +const API_KEY = process.env.API_KEY; +const DB_PASSWORD = process.env.DB_PASSWORD; + +// βœ… GOOD: Secrets manager +const API_KEY = await secretsManager.get('API_KEY'); +``` + +### 6. Insecure Direct Object Reference (IDOR) + +**Look for:** +```javascript +// ❌ BAD: Use user-supplied ID without validation +app.get('/api/documents/:id', async (req, res) => { + const doc = await getDocument(req.params.id); + res.json(doc); +}); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Verify access +app.get('/api/documents/:id', async (req, res) => { + const doc = await getDocument(req.params.id); + + // Check user has permission to view this document + if (!await userCanAccessDocument(req.user.id, doc.id)) { + return res.status(403).json({ error: 'Forbidden' }); + } + + res.json(doc); +}); +``` + +## HIGH Security Issues + +These should be fixed before shipping. + +### 7. Missing Input Validation + +**Look for:** +```javascript +// ❌ BAD: No validation +app.post('/api/users', async (req, res) => { + await createUser(req.body); + res.json({ success: true }); +}); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Validate input +app.post('/api/users', async (req, res) => { + const schema = z.object({ + email: z.string().email(), + age: z.number().min(18).max(120) + }); + + try { + const data = schema.parse(req.body); + await createUser(data); + res.json({ success: true }); + } catch (error) { + res.status(400).json({ error: error.errors }); + } +}); +``` + +### 8. Sensitive Data Exposure + +**Look for:** +```javascript +// ❌ BAD: Exposing sensitive fields +const user = await getUser(userId); +res.json(user); // Contains password hash, SSN, etc. +``` + +**Fix with:** +```javascript +// βœ… GOOD: Select only safe fields +const user = await getUser(userId); +res.json({ + id: user.id, + name: user.name, + email: user.email + // Don't include: password, ssn, etc. +}); +``` + +### 9. Missing Rate Limiting + +**Look for:** +```javascript +// ❌ BAD: No rate limit +app.post('/api/login', async (req, res) => { + const user = await authenticate(req.body); + res.json({ token: user.token }); +}); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Rate limit sensitive endpoints +app.post('/api/login', + rateLimit({ max: 5, windowMs: 60000 }), // 5 attempts per minute + async (req, res) => { + const user = await authenticate(req.body); + res.json({ token: user.token }); + } +); +``` + +### 10. Insecure Randomness + +**Look for:** +```javascript +// ❌ BAD: Using Math.random() for tokens +const token = Math.random().toString(36); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Cryptographically secure random +const crypto = require('crypto'); +const token = crypto.randomBytes(32).toString('hex'); +``` + +## MEDIUM Security Issues + +These improve security but aren't critical. + +### 11. Missing HTTPS + +**Look for:** +```javascript +// ❌ BAD: HTTP only +app.listen(3000); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Force HTTPS in production +if (process.env.NODE_ENV === 'production') { + app.use((req, res, next) => { + if (req.header('x-forwarded-proto') !== 'https') { + res.redirect(`https://${req.header('host')}${req.url}`); + } else { + next(); + } + }); +} +``` + +### 12. Missing Security Headers + +**Look for:** +```javascript +// ❌ BAD: No security headers +app.use(express.json()); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Add security headers +app.use(helmet()); // Adds multiple security headers +``` + +### 13. Verbose Error Messages + +**Look for:** +```javascript +// ❌ BAD: Exposing stack traces +app.use((error, req, res, next) => { + res.status(500).json({ error: error.stack }); +}); +``` + +**Fix with:** +```javascript +// βœ… GOOD: Generic error message +app.use((error, req, res, next) => { + console.error(error); // Log internally + res.status(500).json({ error: 'Internal server error' }); +}); +``` + +## Review Process + +### Step 1: Automated Checks + +Run security scanners: ```bash -# Check for outdated dependencies +# Check for known vulnerabilities npm audit + +# Static analysis +npx eslint-plugin-security + +# Secrets detection +git secrets --scan ``` -**Fix:** Keep dependencies updated, monitor CVEs. +### Step 2: Manual Review -### 10. Insufficient Logging -```bash -# Check for security event logging -grep -E "log.*(login|auth|permission|access)" . -r +Use this checklist to review: +- [ ] SQL injection vulnerabilities +- [ ] XSS vulnerabilities +- [ ] Authentication bypasses +- [ ] Authorization gaps +- [ ] Hardcoded secrets +- [ ] IDOR vulnerabilities +- [ ] Missing input validation +- [ ] Sensitive data exposure +- [ ] Missing rate limiting +- [ ] Insecure randomness + +### Step 3: Document Findings + +For each issue found: +```markdown +**Issue #1: SQL Injection Vulnerability** +- **Location:** api/users/route.ts:45 +- **Severity:** CRITICAL +- **Problem:** User input concatenated into query +- **Code:** + ```typescript + const query = `SELECT * FROM users WHERE id = '${userId}'` + ``` +- **Fix:** Use parameterized queries with Prisma ``` -**Fix:** Log security events with context. - +## Remember - -## Severity Ratings +**Security issues are CRITICAL. They MUST be fixed.** -| Severity | Impact | Examples | -|----------|--------|----------| -| CRITICAL | Data breach, account takeover | SQL injection, auth bypass | -| HIGH | Service disruption, data corruption | Logic flaws, N+1 queries | -| MEDIUM | Technical debt, maintainability | Missing validation, tight coupling | -| LOW | Code style, nice-to-have | Naming, documentation | - -**CRITICAL and HIGH must be fixed before merge.** - +Don't let security issues slide because "we'll fix it later." Fix them now. diff --git a/src/bmm/patterns/tdd.md b/src/bmm/patterns/tdd.md index 7cb113a2..db9bda36 100644 --- a/src/bmm/patterns/tdd.md +++ b/src/bmm/patterns/tdd.md @@ -1,93 +1,184 @@ -# Test-Driven Development Pattern +# Test-Driven Development (TDD) Pattern - -TDD is about design quality, not coverage metrics. Writing tests first forces you to think about behavior before implementation. +**Red β†’ Green β†’ Refactor** -**Principle:** If you can describe behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result. - +Write tests first, make them pass, then refactor. - -## When TDD Improves Quality +## Why TDD? -**Use TDD for:** -- Business logic with defined inputs/outputs -- API endpoints with request/response contracts -- Data transformations, parsing, formatting -- Validation rules and constraints -- Algorithms with testable behavior +1. **Design quality:** Writing tests first forces good API design +2. **Coverage:** 90%+ coverage by default +3. **Confidence:** Refactor without fear +4. **Documentation:** Tests document expected behavior -**Skip TDD for:** -- UI layout and styling -- Configuration changes -- Glue code connecting existing components -- One-off scripts -- Simple CRUD with no business logic - +## TDD Cycle - -## Red-Green-Refactor Cycle - -**RED - Write failing test:** -1. Create test describing expected behavior -2. Run test - it MUST fail -3. If test passes: feature exists or test is wrong - -**GREEN - Implement to pass:** -1. Write minimal code to make test pass -2. No cleverness, no optimization - just make it work -3. Run test - it MUST pass - -**REFACTOR (if needed):** -1. Clean up implementation -2. Run tests - MUST still pass -3. Only commit if changes made - - - -## Good Tests vs Bad Tests - -**Test behavior, not implementation:** -```typescript -// GOOD: Tests observable behavior -expect(formatDate(new Date('2024-01-15'))).toBe('Jan 15, 2024') - -// BAD: Tests implementation details -expect(formatDate).toHaveBeenCalledWith(expect.any(Date)) +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 1. RED: Write a failing test β”‚ +β”‚ - Test what the code SHOULD do β”‚ +β”‚ - Test fails (code doesn't exist yet) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 2. GREEN: Write minimal code to pass β”‚ +β”‚ - Simplest implementation that works β”‚ +β”‚ - Test passes β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 3. REFACTOR: Clean up code β”‚ +β”‚ - Improve design β”‚ +β”‚ - Remove duplication β”‚ +β”‚ - Tests still pass β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ + (repeat for next feature) ``` -**One concept per test:** -```typescript -// GOOD: Separate tests -it('accepts valid email', () => { ... }) -it('rejects empty email', () => { ... }) -it('rejects malformed email', () => { ... }) +## Implementation Order -// BAD: Multiple assertions -it('validates email', () => { - expect(validate('test@example.com')).toBe(true) - expect(validate('')).toBe(false) - expect(validate('invalid')).toBe(false) -}) +### Greenfield (New Code) +1. Write test for happy path +2. Write test for error cases +3. Write test for edge cases +4. Implement to make all tests pass +5. Refactor + +### Brownfield (Existing Code) +1. Understand existing behavior +2. Add tests for current behavior (characterization tests) +3. Write test for new behavior +4. Implement new behavior +5. Refactor + +## Test Quality Standards + +### Good Test Characteristics +- βœ… **Isolated:** Each test independent +- βœ… **Fast:** Runs in milliseconds +- βœ… **Clear:** Obvious what it tests +- βœ… **Focused:** One behavior per test +- βœ… **Stable:** No flakiness + +### Test Structure (AAA Pattern) +```typescript +test('should calculate total price with tax', () => { + // Arrange: Set up test data + const cart = new ShoppingCart(); + cart.addItem({ price: 100, quantity: 2 }); + + // Act: Execute the behavior + const total = cart.getTotalWithTax(0.08); + + // Assert: Verify the result + expect(total).toBe(216); // (100 * 2) * 1.08 +}); ``` -**Descriptive names:** +## What to Test + +### Must Test (Critical) +- Business logic +- API endpoints +- Data transformations +- Error handling +- Authorization checks +- Edge cases + +### Nice to Test (Important) +- UI components +- Integration flows +- Performance benchmarks + +### Don't Waste Time Testing +- Third-party libraries (already tested) +- Framework internals (already tested) +- Trivial getters/setters +- Generated code + +## Coverage Target + +**Minimum:** 90% line coverage +**Ideal:** 95%+ with meaningful tests + +**Coverage β‰  Quality** +- 100% coverage with bad tests is worthless +- 90% coverage with good tests is excellent + +## TDD Anti-Patterns + +**Avoid these:** +- ❌ Writing tests after code (test-after) +- ❌ Testing implementation details +- ❌ Tests that test nothing +- ❌ Brittle tests (break with refactoring) +- ❌ Slow tests (> 1 second) + +## Example: TDD for API Endpoint + ```typescript -// GOOD -it('returns null for invalid user ID') -it('should reject empty email') +// Step 1: RED - Write failing test +describe('POST /api/orders', () => { + test('should create order and return 201', async () => { + const response = await request(app) + .post('/api/orders') + .send({ items: [{ id: 1, qty: 2 }] }) + .expect(201); + + expect(response.body).toHaveProperty('orderId'); + }); +}); -// BAD -it('test1') -it('handles error') -it('works') +// Test fails (endpoint doesn't exist yet) + +// Step 2: GREEN - Minimal implementation +app.post('/api/orders', async (req, res) => { + const orderId = await createOrder(req.body); + res.status(201).json({ orderId }); +}); + +// Test passes + +// Step 3: REFACTOR - Add validation, error handling +app.post('/api/orders', async (req, res) => { + try { + // Input validation + const schema = z.object({ + items: z.array(z.object({ + id: z.number(), + qty: z.number().min(1) + })) + }); + + const data = schema.parse(req.body); + + // Business logic + const orderId = await createOrder(data); + + res.status(201).json({ orderId }); + } catch (error) { + if (error instanceof z.ZodError) { + res.status(400).json({ error: error.errors }); + } else { + res.status(500).json({ error: 'Internal error' }); + } + } +}); + +// All tests still pass ``` - - -## Coverage Targets +## TDD in Practice -- **90%+ line coverage** for new code -- **100% branch coverage** for critical paths (auth, payments) -- **Every error path** has at least one test -- **Edge cases** explicitly tested - +**Start here:** +1. Write one test for the simplest case +2. Make it pass with simplest code +3. Write next test for slightly more complex case +4. Refactor when you see duplication +5. Repeat + +**Don't:** +- Write all tests first (too much work) +- Write production code without failing test +- Skip refactoring step diff --git a/src/bmm/patterns/verification.md b/src/bmm/patterns/verification.md index 2d359205..2a435d35 100644 --- a/src/bmm/patterns/verification.md +++ b/src/bmm/patterns/verification.md @@ -1,143 +1,198 @@ -# Verification Patterns +# Independent Verification Pattern - -Existence β‰  Implementation. A file existing does not mean the feature works. +**Philosophy:** Trust but verify. Fresh eyes catch what familiarity misses. -**Verification levels:** -1. **Exists** - File is present -2. **Substantive** - Content is real, not placeholder -3. **Wired** - Connected to rest of system -4. **Functional** - Actually works when invoked - +## Core Principle - -## Detecting Stubs and Placeholders +The person who built something should NOT validate their own work. +**Why?** +- Confirmation bias (see what you expect to see) +- Blind spots (familiar with your own code) +- Fatigue (validated while building, miss issues) + +## Verification Requirements + +### Fresh Context +Inspector agent has: +- βœ… No knowledge of what Builder did +- βœ… No preconceptions about implementation +- βœ… Only the story requirements as context + +**This means:** +- Run all checks yourself +- Don't trust any claims +- Start from scratch + +### What to Verify + +**1. Files Exist** ```bash -# Comment-based stubs -grep -E "(TODO|FIXME|XXX|PLACEHOLDER)" "$file" -grep -E "implement|add later|coming soon" "$file" -i - -# Empty implementations -grep -E "return null|return undefined|return \{\}|return \[\]" "$file" -grep -E "console\.(log|warn).*only" "$file" - -# Placeholder text -grep -E "placeholder|lorem ipsum|sample data" "$file" -i +# For each file mentioned in story tasks +ls -la {{file_path}} +# FAIL if file missing or empty ``` -**Red flags in code:** -```typescript -// STUBS - Not real implementations: -return
Placeholder
-onClick={() => {}} -export async function POST() { return Response.json({ ok: true }) } -``` - +**2. File Contents** +- Open each file +- Check it has actual code (not just TODO/stub) +- Verify it matches story requirements - -## File Verification Commands - -**React Components:** +**3. Tests Exist** ```bash -# Exists and exports component -[ -f "$file" ] && grep -E "export.*function|export const.*=" "$file" - -# Has real JSX (not null/empty) -grep -E "return.*<" "$file" | grep -v "return.*null" - -# Uses props/state (not static) -grep -E "props\.|useState|useEffect" "$file" +find . -name "*.test.ts" -o -name "__tests__" +# FAIL if no tests found for new code ``` -**API Routes:** -```bash -# Exports HTTP handlers -grep -E "export.*(GET|POST|PUT|DELETE)" "$file" +**4. Quality Checks Pass** -# Has database interaction -grep -E "prisma\.|db\.|query|find|create" "$file" - -# Has error handling -grep -E "try|catch|throw" "$file" -``` - -**Tests:** -```bash -# Test file exists -[ -f "$test_file" ] - -# Has test cases -grep -E "it\(|test\(|describe\(" "$test_file" - -# Not all skipped -grep -c "\.skip" "$test_file" -``` - - - -## Quality Check Commands +Run these yourself. Don't trust claims. ```bash -# Type check - zero errors +# Type check npm run type-check -echo "Exit code: $?" +# FAIL if any errors -# Lint - zero errors/warnings -npm run lint 2>&1 | tail -5 +# Linter +npm run lint +# FAIL if any errors or warnings -# Tests - all passing -npm test 2>&1 | grep -E "pass|fail|error" -i | tail -10 +# Build +npm run build +# FAIL if build fails -# Build - succeeds -npm run build 2>&1 | tail -5 +# Tests +npm test -- {{story_specific_tests}} +# FAIL if any tests fail +# FAIL if tests are skipped +# FAIL if coverage < 90% ``` -**All must return exit code 0.** - - - -## Wiring Verification - -**Component β†’ API:** +**5. Git Status** ```bash -# Check component calls the API -grep -E "fetch\(['\"].*$api_path|axios.*$api_path" "$component" +git status +# Check for uncommitted files +# List what was changed ``` -**API β†’ Database:** -```bash -# Check API queries database -grep -E "await.*prisma|await.*db\." "$route" -``` +## Verification Verdict -**Form β†’ Handler:** -```bash -# Check form has real submit handler -grep -A 5 "onSubmit" "$component" | grep -E "fetch|axios|mutate" -``` - +### PASS Criteria +All of these must be true: +- [ ] All story files exist and have content +- [ ] Type check returns 0 errors +- [ ] Linter returns 0 errors/warnings +- [ ] Build succeeds +- [ ] Tests run and pass (not skipped) +- [ ] Test coverage >= 90% +- [ ] Git status is clean or has expected changes - -## Verdict Format +**If ANY checkbox is unchecked β†’ FAIL verdict** + +### PASS Output ```markdown -## VALIDATION RESULT +βœ… VALIDATION PASSED -**Status:** PASS | FAIL - -### Evidence +Evidence: +- Files verified: [list files checked] - Type check: PASS (0 errors) -- Lint: PASS (0 warnings) +- Linter: PASS (0 warnings) - Build: PASS -- Tests: 45/45 passing +- Tests: 45/45 passing (95% coverage) +- Git: 12 files modified, 3 new files -### Files Verified -- path/to/file.ts βœ“ -- path/to/other.ts βœ“ - -### Failures (if FAIL) -1. [CRITICAL] Missing file: src/api/route.ts -2. [HIGH] Type error in lib/auth.ts:45 +Ready for code review. ``` - + +### FAIL Output + +```markdown +❌ VALIDATION FAILED + +Failures: +1. File missing: app/api/occupant/agreement/route.ts +2. Type check: 3 errors in lib/api/auth.ts +3. Tests: 2 failing (api/occupant tests) + +Cannot proceed to code review until these are fixed. +``` + +## Why This Works + +**Verification is NOT rubber-stamping.** + +Inspector's job is to find the truth: +- Did the work actually get done? +- Do the quality checks actually pass? +- Are the files actually there? + +If something is wrong, say so with evidence. + +## Anti-Patterns + +**Don't do this:** +- ❌ Take Builder's word for anything +- ❌ Skip verification steps +- ❌ Assume tests pass without running them +- ❌ Give PASS verdict if ANY check fails + +**Do this instead:** +- βœ… Run all checks yourself +- βœ… Provide specific evidence +- βœ… Give honest verdict +- βœ… FAIL fast if issues found + +## Example: Good Verification + +```markdown +## Verification Results + +**File Checks:** +βœ… lib/billing/payment-processor.ts (1,234 lines) +βœ… lib/billing/__tests__/payment-processor.test.ts (456 lines) +βœ… lib/billing/worker.ts (modified) + +**Quality Checks:** +βœ… Type check: PASS (0 errors) +βœ… Linter: PASS (0 warnings) +βœ… Build: PASS (2.3s) + +**Tests:** +βœ… 48/48 passing +βœ… 96% coverage +βœ… 0 skipped + +**Git Status:** +- Modified: 1 file +- Created: 2 files +- Total: 3 files changed + +**Verdict:** PASS + +Ready for code review. +``` + +## Example: Bad Verification (Don't Do This) + +```markdown +## Verification Results + +Everything looks good! βœ… + +Builder said tests pass and I believe them. + +**Verdict:** PASS +``` + +**What's wrong:** +- ❌ No evidence +- ❌ Trusted claims without verification +- ❌ Didn't run checks +- ❌ Rubber-stamped + +## Remember + +**You are the INSPECTOR. Your job is to find the truth.** + +If you give a PASS verdict and later find issues, that's on you. diff --git a/src/bmm/workflows/4-implementation/multi-agent-review/workflow.md b/src/bmm/workflows/4-implementation/multi-agent-review/workflow.md index 1d774706..95a8b1cc 100644 --- a/src/bmm/workflows/4-implementation/multi-agent-review/workflow.md +++ b/src/bmm/workflows/4-implementation/multi-agent-review/workflow.md @@ -19,9 +19,9 @@ name: multi-agent-review version: 3.0.0 agent_selection: - micro: {count: 1, agents: [security]} - standard: {count: 2, agents: [security, code_quality]} - complex: {count: 3, agents: [security, code_quality, architecture]} + micro: {count: 2, agents: [security, code_quality]} + standard: {count: 4, agents: [security, code_quality, architecture, testing]} + complex: {count: 6, agents: [security, code_quality, architecture, testing, performance, domain_expert]} available_agents: security: "Identifies vulnerabilities and security risks" @@ -41,40 +41,21 @@ available_agents: -**Select agents based on override or complexity** +**Select agents based on complexity** ``` -# Priority 1: Check for explicit override -If override_agent_count is provided (not null): - agent_count = min(override_agent_count, 6) # Cap at 6 max - Select top N agents based on changed code patterns - Display: πŸ”§ CUSTOM Review ({{agent_count}} agents) - -# Priority 2: Use complexity-based default -Else if complexity_level == "micro": - agent_count = 1 - agents = ["security"] - Display: πŸ” MICRO Review (1 agent) +If complexity_level == "micro": + agents = ["security", "code_quality"] + Display: πŸ” MICRO Review (2 agents) Else if complexity_level == "standard": - agent_count = 2 - agents = ["security", "code_quality"] - Display: πŸ“‹ STANDARD Review (2 agents) + agents = ["security", "code_quality", "architecture", "testing"] + Display: πŸ“‹ STANDARD Review (4 agents) Else if complexity_level == "complex": - agent_count = 3 - agents = ["security", "code_quality", "architecture"] - Display: πŸ”¬ COMPLEX Review (3 agents) + agents = ALL 6 agents + Display: πŸ”¬ COMPLEX Review (6 agents) ``` - -**Agent Selection Priority:** -1. Security (always first) -2. Code Quality (always second) -3-6. Selected based on code patterns: - - Architecture (for structural changes) - - Testing (for test coverage) - - Performance (for optimization) - - Domain Expert (for business logic) diff --git a/src/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml b/src/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml index e554cccd..8ffb9b7f 100644 --- a/src/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml +++ b/src/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml @@ -18,29 +18,28 @@ story_id: "{story_id}" # Required story_file: "{sprint_artifacts}/story-{story_id}.md" base_branch: "main" # Optional: branch to compare against complexity_level: "standard" # micro | standard | complex (passed from story-full-pipeline) -override_agent_count: null # Optional: override complexity-based count (1-6, null = use complexity_level) # Complexity-based agent selection (NEW v1.0.0) # Cost-effective review depth based on story RISK and technical complexity # Complexity determined by batch-stories based on: risk keywords, architectural impact, security concerns complexity_routing: micro: - agent_count: 1 - agents: ["security"] + agent_count: 2 + agents: ["security", "code_quality"] description: "Quick sanity check for low-risk stories" examples: ["UI tweaks", "text changes", "simple CRUD", "documentation"] cost_multiplier: 1x standard: - agent_count: 2 - agents: ["security", "code_quality"] + agent_count: 4 + agents: ["security", "code_quality", "architecture", "testing"] description: "Balanced multi-perspective review for medium-risk changes" examples: ["API endpoints", "business logic", "data validation", "component refactors"] cost_multiplier: 2x complex: - agent_count: 3 - agents: ["security", "code_quality", "architecture"] + agent_count: 6 + agents: ["security", "code_quality", "architecture", "testing", "performance", "domain_expert"] description: "Comprehensive review for high-risk/high-complexity changes" examples: ["auth/security", "payments", "data migration", "architecture changes", "performance-critical", "complex algorithms"] cost_multiplier: 3x diff --git a/src/modules/bmm/patterns/agent-completion.md b/src/modules/bmm/patterns/agent-completion.md deleted file mode 100644 index f2cf1309..00000000 --- a/src/modules/bmm/patterns/agent-completion.md +++ /dev/null @@ -1,225 +0,0 @@ -# Agent Completion Artifact Pattern - -**Problem:** Agents fail to update story files reliably (60% success rate) -**Solution:** Agents create completion.json artifacts. Orchestrator uses them to update story files. - -## The Contract - -### Agent Responsibility -Each agent MUST create a completion artifact before finishing: -- **File path:** `docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json` -- **Format:** Structured JSON (see formats below) -- **Verification:** File exists = work done (binary check) - -### Orchestrator Responsibility -Orchestrator reads completion artifacts and: -- Parses JSON for structured data -- Updates story file tasks (check off completed) -- Fills Dev Agent Record with evidence -- Verifies updates succeeded - -## Why This Works - -**File-based verification:** -- βœ… Binary check: File exists or doesn't -- βœ… No complex parsing of agent output -- βœ… No reconciliation logic needed -- βœ… Hard stop if artifact missing - -**JSON format:** -- βœ… Easy to parse reliably -- βœ… Structured data (not prose) -- βœ… Version controllable -- βœ… Auditable trail - -## How to Use This Pattern - -### In Agent Prompts - -Include this in every agent prompt: - -```markdown -## CRITICAL: Create Completion Artifact - -**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. - -**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json` - -**Format:** -```json -{ - "story_key": "{{story_key}}", - "agent": "{{agent_name}}", - "status": "SUCCESS", - "files_created": ["file1.ts", "file2.ts"], - "files_modified": ["file3.ts"], - "timestamp": "2026-01-27T02:30:00Z" -} -``` - -**Use Write tool to create this file. No exceptions.** -``` - -### In Orchestrator Verification - -After agent completes, verify artifact exists: - -```bash -COMPLETION_FILE="docs/sprint-artifacts/completions/{{story_key}}-{{agent}}.json" - -if [ ! -f "$COMPLETION_FILE" ]; then - echo "❌ BLOCKER: Agent failed to create completion artifact" - exit 1 -fi - -echo "βœ… Completion artifact found" -``` - -### In Reconciliation - -Parse artifact to update story file: - -```markdown -1. Load completion artifact with Read tool -2. Parse JSON to extract data -3. Use Edit tool to update story file -4. Verify updates with bash checks -``` - -## Artifact Formats by Agent - -### Builder Completion - -```json -{ - "story_key": "19-4", - "agent": "builder", - "status": "SUCCESS", - "tasks_completed": [ - "Create PaymentProcessor service", - "Add retry logic with exponential backoff" - ], - "files_created": [ - "lib/billing/payment-processor.ts", - "lib/billing/__tests__/payment-processor.test.ts" - ], - "files_modified": [ - "lib/billing/worker.ts" - ], - "tests": { - "files": 2, - "cases": 15 - }, - "timestamp": "2026-01-27T02:30:00Z" -} -``` - -### Inspector Completion - -```json -{ - "story_key": "19-4", - "agent": "inspector", - "status": "PASS", - "quality_checks": { - "type_check": "PASS", - "lint": "PASS", - "build": "PASS" - }, - "tests": { - "passing": 45, - "failing": 0, - "total": 45, - "coverage": 95 - }, - "files_verified": [ - "lib/billing/payment-processor.ts" - ], - "timestamp": "2026-01-27T02:35:00Z" -} -``` - -### Reviewer Completion - -```json -{ - "story_key": "19-4", - "agent": "reviewer", - "status": "ISSUES_FOUND", - "issues": { - "critical": 2, - "high": 3, - "medium": 4, - "low": 2, - "total": 11 - }, - "must_fix": [ - { - "severity": "CRITICAL", - "location": "api/route.ts:45", - "description": "SQL injection vulnerability" - } - ], - "files_reviewed": [ - "api/route.ts" - ], - "timestamp": "2026-01-27T02:40:00Z" -} -``` - -### Fixer Completion (FINAL) - -```json -{ - "story_key": "19-4", - "agent": "fixer", - "status": "SUCCESS", - "issues_fixed": { - "critical": 2, - "high": 3, - "total": 5 - }, - "fixes_applied": [ - "Fixed SQL injection in agreement route (CRITICAL)", - "Added authorization check (CRITICAL)" - ], - "files_modified": [ - "api/route.ts" - ], - "quality_checks": { - "type_check": "PASS", - "lint": "PASS", - "build": "PASS" - }, - "tests": { - "passing": 48, - "failing": 0, - "total": 48, - "coverage": 96 - }, - "git_commit": "a1b2c3d4e5f", - "timestamp": "2026-01-27T02:50:00Z" -} -``` - -## Benefits - -- **Reliability:** 60% β†’ 100% (file exists is binary) -- **Simplicity:** No complex output parsing -- **Auditability:** JSON files are version controlled -- **Debuggability:** Can inspect artifacts when issues occur -- **Enforcement:** Can't proceed without completion artifact (hard stop) - -## Anti-Patterns - -**Don't do this:** -- ❌ Trust agent output without verification -- ❌ Parse agent prose for structured data -- ❌ Let agents update story files directly -- ❌ Skip artifact creation ("just this once") - -**Do this instead:** -- βœ… Verify artifact exists (binary check) -- βœ… Parse JSON for reliable data -- βœ… Orchestrator updates story files -- βœ… Hard stop if artifact missing diff --git a/src/modules/bmm/patterns/hospital-grade.md b/src/modules/bmm/patterns/hospital-grade.md deleted file mode 100644 index a8bfc09c..00000000 --- a/src/modules/bmm/patterns/hospital-grade.md +++ /dev/null @@ -1,75 +0,0 @@ -# Hospital-Grade Quality Standards - -**Philosophy:** Quality >> Speed - -This pattern ensures code meets production-grade standards regardless of story complexity. - -## Core Principles - -1. **Take time to do it right** - - Don't rush implementations - - Consider edge cases - - Handle errors properly - -2. **No shortcuts** - - Don't skip error handling - - Don't leave TODO comments - - Don't use `any` types - - Don't hardcode values - -3. **Production-ready from day one** - - All code deployable immediately - - No "we'll fix it later" - - No technical debt by design - -## Quality Checklist - -### Code Quality -- [ ] All functions have clear, single responsibility -- [ ] Error handling for all failure paths -- [ ] Input validation at system boundaries -- [ ] No magic numbers or hardcoded strings -- [ ] Type safety (no `any`, proper generics) - -### Testing -- [ ] Unit tests for business logic -- [ ] Integration tests for API endpoints -- [ ] Edge cases covered -- [ ] Error cases covered -- [ ] 90%+ coverage target - -### Security -- [ ] No SQL injection vulnerabilities -- [ ] No XSS vulnerabilities -- [ ] Authentication/authorization checks -- [ ] Input sanitization -- [ ] No secrets in code - -### Performance -- [ ] No N+1 query patterns -- [ ] Appropriate database indexes -- [ ] Efficient algorithms (avoid O(nΒ²) where possible) -- [ ] Resource cleanup (connections, files) - -### Maintainability -- [ ] Code follows project patterns -- [ ] Self-documenting code (clear names) -- [ ] Comments only where logic isn't obvious -- [ ] Consistent formatting -- [ ] DRY (Don't Repeat Yourself) - -## Red Flags - -**Immediate rejection criteria:** -- ❌ Security vulnerabilities -- ❌ Data loss scenarios -- ❌ Production bugs -- ❌ Missing error handling -- ❌ Skipped tests -- ❌ Hardcoded secrets - -## Hospital-Grade Mindset - -> "If this code ran a medical device, would I trust it with my family's life?" - -If the answer is no, it's not hospital-grade. Fix it. diff --git a/src/modules/bmm/patterns/security-checklist.md b/src/modules/bmm/patterns/security-checklist.md deleted file mode 100644 index 70ffc1c5..00000000 --- a/src/modules/bmm/patterns/security-checklist.md +++ /dev/null @@ -1,340 +0,0 @@ -# Security Review Checklist - -**Philosophy:** Security issues are CRITICAL. No exceptions. - -This checklist helps identify common security vulnerabilities in code reviews. - -## CRITICAL Security Issues - -These MUST be fixed. No story ships with these issues. - -### 1. SQL Injection - -**Look for:** -```javascript -// ❌ BAD: User input in query string -const query = `SELECT * FROM users WHERE id = '${userId}'`; -const query = "SELECT * FROM users WHERE id = '" + userId + "'"; -``` - -**Fix with:** -```javascript -// βœ… GOOD: Parameterized queries -const query = db.prepare('SELECT * FROM users WHERE id = ?'); -query.get(userId); - -// βœ… GOOD: ORM/Query builder -const user = await prisma.user.findUnique({ where: { id: userId } }); -``` - -### 2. XSS (Cross-Site Scripting) - -**Look for:** -```javascript -// ❌ BAD: Unsanitized user input in HTML -element.innerHTML = userInput; -document.write(userInput); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Use textContent or sanitize -element.textContent = userInput; - -// βœ… GOOD: Use framework's built-in escaping -
{userInput}
// React automatically escapes -``` - -### 3. Authentication Bypass - -**Look for:** -```javascript -// ❌ BAD: No auth check -app.get('/api/admin/users', async (req, res) => { - const users = await getUsers(); - res.json(users); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Require auth -app.get('/api/admin/users', requireAuth, async (req, res) => { - const users = await getUsers(); - res.json(users); -}); -``` - -### 4. Authorization Gaps - -**Look for:** -```javascript -// ❌ BAD: No ownership check -app.delete('/api/orders/:id', async (req, res) => { - await deleteOrder(req.params.id); - res.json({ success: true }); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Verify user owns resource -app.delete('/api/orders/:id', async (req, res) => { - const order = await getOrder(req.params.id); - - if (order.userId !== req.user.id) { - return res.status(403).json({ error: 'Forbidden' }); - } - - await deleteOrder(req.params.id); - res.json({ success: true }); -}); -``` - -### 5. Hardcoded Secrets - -**Look for:** -```javascript -// ❌ BAD: Secrets in code -const API_KEY = 'sk-1234567890abcdef'; -const DB_PASSWORD = 'MyP@ssw0rd123'; -``` - -**Fix with:** -```javascript -// βœ… GOOD: Environment variables -const API_KEY = process.env.API_KEY; -const DB_PASSWORD = process.env.DB_PASSWORD; - -// βœ… GOOD: Secrets manager -const API_KEY = await secretsManager.get('API_KEY'); -``` - -### 6. Insecure Direct Object Reference (IDOR) - -**Look for:** -```javascript -// ❌ BAD: Use user-supplied ID without validation -app.get('/api/documents/:id', async (req, res) => { - const doc = await getDocument(req.params.id); - res.json(doc); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Verify access -app.get('/api/documents/:id', async (req, res) => { - const doc = await getDocument(req.params.id); - - // Check user has permission to view this document - if (!await userCanAccessDocument(req.user.id, doc.id)) { - return res.status(403).json({ error: 'Forbidden' }); - } - - res.json(doc); -}); -``` - -## HIGH Security Issues - -These should be fixed before shipping. - -### 7. Missing Input Validation - -**Look for:** -```javascript -// ❌ BAD: No validation -app.post('/api/users', async (req, res) => { - await createUser(req.body); - res.json({ success: true }); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Validate input -app.post('/api/users', async (req, res) => { - const schema = z.object({ - email: z.string().email(), - age: z.number().min(18).max(120) - }); - - try { - const data = schema.parse(req.body); - await createUser(data); - res.json({ success: true }); - } catch (error) { - res.status(400).json({ error: error.errors }); - } -}); -``` - -### 8. Sensitive Data Exposure - -**Look for:** -```javascript -// ❌ BAD: Exposing sensitive fields -const user = await getUser(userId); -res.json(user); // Contains password hash, SSN, etc. -``` - -**Fix with:** -```javascript -// βœ… GOOD: Select only safe fields -const user = await getUser(userId); -res.json({ - id: user.id, - name: user.name, - email: user.email - // Don't include: password, ssn, etc. -}); -``` - -### 9. Missing Rate Limiting - -**Look for:** -```javascript -// ❌ BAD: No rate limit -app.post('/api/login', async (req, res) => { - const user = await authenticate(req.body); - res.json({ token: user.token }); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Rate limit sensitive endpoints -app.post('/api/login', - rateLimit({ max: 5, windowMs: 60000 }), // 5 attempts per minute - async (req, res) => { - const user = await authenticate(req.body); - res.json({ token: user.token }); - } -); -``` - -### 10. Insecure Randomness - -**Look for:** -```javascript -// ❌ BAD: Using Math.random() for tokens -const token = Math.random().toString(36); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Cryptographically secure random -const crypto = require('crypto'); -const token = crypto.randomBytes(32).toString('hex'); -``` - -## MEDIUM Security Issues - -These improve security but aren't critical. - -### 11. Missing HTTPS - -**Look for:** -```javascript -// ❌ BAD: HTTP only -app.listen(3000); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Force HTTPS in production -if (process.env.NODE_ENV === 'production') { - app.use((req, res, next) => { - if (req.header('x-forwarded-proto') !== 'https') { - res.redirect(`https://${req.header('host')}${req.url}`); - } else { - next(); - } - }); -} -``` - -### 12. Missing Security Headers - -**Look for:** -```javascript -// ❌ BAD: No security headers -app.use(express.json()); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Add security headers -app.use(helmet()); // Adds multiple security headers -``` - -### 13. Verbose Error Messages - -**Look for:** -```javascript -// ❌ BAD: Exposing stack traces -app.use((error, req, res, next) => { - res.status(500).json({ error: error.stack }); -}); -``` - -**Fix with:** -```javascript -// βœ… GOOD: Generic error message -app.use((error, req, res, next) => { - console.error(error); // Log internally - res.status(500).json({ error: 'Internal server error' }); -}); -``` - -## Review Process - -### Step 1: Automated Checks - -Run security scanners: -```bash -# Check for known vulnerabilities -npm audit - -# Static analysis -npx eslint-plugin-security - -# Secrets detection -git secrets --scan -``` - -### Step 2: Manual Review - -Use this checklist to review: -- [ ] SQL injection vulnerabilities -- [ ] XSS vulnerabilities -- [ ] Authentication bypasses -- [ ] Authorization gaps -- [ ] Hardcoded secrets -- [ ] IDOR vulnerabilities -- [ ] Missing input validation -- [ ] Sensitive data exposure -- [ ] Missing rate limiting -- [ ] Insecure randomness - -### Step 3: Document Findings - -For each issue found: -```markdown -**Issue #1: SQL Injection Vulnerability** -- **Location:** api/users/route.ts:45 -- **Severity:** CRITICAL -- **Problem:** User input concatenated into query -- **Code:** - ```typescript - const query = `SELECT * FROM users WHERE id = '${userId}'` - ``` -- **Fix:** Use parameterized queries with Prisma -``` - -## Remember - -**Security issues are CRITICAL. They MUST be fixed.** - -Don't let security issues slide because "we'll fix it later." Fix them now. diff --git a/src/modules/bmm/patterns/tdd.md b/src/modules/bmm/patterns/tdd.md deleted file mode 100644 index db9bda36..00000000 --- a/src/modules/bmm/patterns/tdd.md +++ /dev/null @@ -1,184 +0,0 @@ -# Test-Driven Development (TDD) Pattern - -**Red β†’ Green β†’ Refactor** - -Write tests first, make them pass, then refactor. - -## Why TDD? - -1. **Design quality:** Writing tests first forces good API design -2. **Coverage:** 90%+ coverage by default -3. **Confidence:** Refactor without fear -4. **Documentation:** Tests document expected behavior - -## TDD Cycle - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 1. RED: Write a failing test β”‚ -β”‚ - Test what the code SHOULD do β”‚ -β”‚ - Test fails (code doesn't exist yet) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 2. GREEN: Write minimal code to pass β”‚ -β”‚ - Simplest implementation that works β”‚ -β”‚ - Test passes β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 3. REFACTOR: Clean up code β”‚ -β”‚ - Improve design β”‚ -β”‚ - Remove duplication β”‚ -β”‚ - Tests still pass β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ - (repeat for next feature) -``` - -## Implementation Order - -### Greenfield (New Code) -1. Write test for happy path -2. Write test for error cases -3. Write test for edge cases -4. Implement to make all tests pass -5. Refactor - -### Brownfield (Existing Code) -1. Understand existing behavior -2. Add tests for current behavior (characterization tests) -3. Write test for new behavior -4. Implement new behavior -5. Refactor - -## Test Quality Standards - -### Good Test Characteristics -- βœ… **Isolated:** Each test independent -- βœ… **Fast:** Runs in milliseconds -- βœ… **Clear:** Obvious what it tests -- βœ… **Focused:** One behavior per test -- βœ… **Stable:** No flakiness - -### Test Structure (AAA Pattern) -```typescript -test('should calculate total price with tax', () => { - // Arrange: Set up test data - const cart = new ShoppingCart(); - cart.addItem({ price: 100, quantity: 2 }); - - // Act: Execute the behavior - const total = cart.getTotalWithTax(0.08); - - // Assert: Verify the result - expect(total).toBe(216); // (100 * 2) * 1.08 -}); -``` - -## What to Test - -### Must Test (Critical) -- Business logic -- API endpoints -- Data transformations -- Error handling -- Authorization checks -- Edge cases - -### Nice to Test (Important) -- UI components -- Integration flows -- Performance benchmarks - -### Don't Waste Time Testing -- Third-party libraries (already tested) -- Framework internals (already tested) -- Trivial getters/setters -- Generated code - -## Coverage Target - -**Minimum:** 90% line coverage -**Ideal:** 95%+ with meaningful tests - -**Coverage β‰  Quality** -- 100% coverage with bad tests is worthless -- 90% coverage with good tests is excellent - -## TDD Anti-Patterns - -**Avoid these:** -- ❌ Writing tests after code (test-after) -- ❌ Testing implementation details -- ❌ Tests that test nothing -- ❌ Brittle tests (break with refactoring) -- ❌ Slow tests (> 1 second) - -## Example: TDD for API Endpoint - -```typescript -// Step 1: RED - Write failing test -describe('POST /api/orders', () => { - test('should create order and return 201', async () => { - const response = await request(app) - .post('/api/orders') - .send({ items: [{ id: 1, qty: 2 }] }) - .expect(201); - - expect(response.body).toHaveProperty('orderId'); - }); -}); - -// Test fails (endpoint doesn't exist yet) - -// Step 2: GREEN - Minimal implementation -app.post('/api/orders', async (req, res) => { - const orderId = await createOrder(req.body); - res.status(201).json({ orderId }); -}); - -// Test passes - -// Step 3: REFACTOR - Add validation, error handling -app.post('/api/orders', async (req, res) => { - try { - // Input validation - const schema = z.object({ - items: z.array(z.object({ - id: z.number(), - qty: z.number().min(1) - })) - }); - - const data = schema.parse(req.body); - - // Business logic - const orderId = await createOrder(data); - - res.status(201).json({ orderId }); - } catch (error) { - if (error instanceof z.ZodError) { - res.status(400).json({ error: error.errors }); - } else { - res.status(500).json({ error: 'Internal error' }); - } - } -}); - -// All tests still pass -``` - -## TDD in Practice - -**Start here:** -1. Write one test for the simplest case -2. Make it pass with simplest code -3. Write next test for slightly more complex case -4. Refactor when you see duplication -5. Repeat - -**Don't:** -- Write all tests first (too much work) -- Write production code without failing test -- Skip refactoring step diff --git a/src/modules/bmm/patterns/verification.md b/src/modules/bmm/patterns/verification.md deleted file mode 100644 index 2a435d35..00000000 --- a/src/modules/bmm/patterns/verification.md +++ /dev/null @@ -1,198 +0,0 @@ -# Independent Verification Pattern - -**Philosophy:** Trust but verify. Fresh eyes catch what familiarity misses. - -## Core Principle - -The person who built something should NOT validate their own work. - -**Why?** -- Confirmation bias (see what you expect to see) -- Blind spots (familiar with your own code) -- Fatigue (validated while building, miss issues) - -## Verification Requirements - -### Fresh Context -Inspector agent has: -- βœ… No knowledge of what Builder did -- βœ… No preconceptions about implementation -- βœ… Only the story requirements as context - -**This means:** -- Run all checks yourself -- Don't trust any claims -- Start from scratch - -### What to Verify - -**1. Files Exist** -```bash -# For each file mentioned in story tasks -ls -la {{file_path}} -# FAIL if file missing or empty -``` - -**2. File Contents** -- Open each file -- Check it has actual code (not just TODO/stub) -- Verify it matches story requirements - -**3. Tests Exist** -```bash -find . -name "*.test.ts" -o -name "__tests__" -# FAIL if no tests found for new code -``` - -**4. Quality Checks Pass** - -Run these yourself. Don't trust claims. - -```bash -# Type check -npm run type-check -# FAIL if any errors - -# Linter -npm run lint -# FAIL if any errors or warnings - -# Build -npm run build -# FAIL if build fails - -# Tests -npm test -- {{story_specific_tests}} -# FAIL if any tests fail -# FAIL if tests are skipped -# FAIL if coverage < 90% -``` - -**5. Git Status** -```bash -git status -# Check for uncommitted files -# List what was changed -``` - -## Verification Verdict - -### PASS Criteria -All of these must be true: -- [ ] All story files exist and have content -- [ ] Type check returns 0 errors -- [ ] Linter returns 0 errors/warnings -- [ ] Build succeeds -- [ ] Tests run and pass (not skipped) -- [ ] Test coverage >= 90% -- [ ] Git status is clean or has expected changes - -**If ANY checkbox is unchecked β†’ FAIL verdict** - -### PASS Output - -```markdown -βœ… VALIDATION PASSED - -Evidence: -- Files verified: [list files checked] -- Type check: PASS (0 errors) -- Linter: PASS (0 warnings) -- Build: PASS -- Tests: 45/45 passing (95% coverage) -- Git: 12 files modified, 3 new files - -Ready for code review. -``` - -### FAIL Output - -```markdown -❌ VALIDATION FAILED - -Failures: -1. File missing: app/api/occupant/agreement/route.ts -2. Type check: 3 errors in lib/api/auth.ts -3. Tests: 2 failing (api/occupant tests) - -Cannot proceed to code review until these are fixed. -``` - -## Why This Works - -**Verification is NOT rubber-stamping.** - -Inspector's job is to find the truth: -- Did the work actually get done? -- Do the quality checks actually pass? -- Are the files actually there? - -If something is wrong, say so with evidence. - -## Anti-Patterns - -**Don't do this:** -- ❌ Take Builder's word for anything -- ❌ Skip verification steps -- ❌ Assume tests pass without running them -- ❌ Give PASS verdict if ANY check fails - -**Do this instead:** -- βœ… Run all checks yourself -- βœ… Provide specific evidence -- βœ… Give honest verdict -- βœ… FAIL fast if issues found - -## Example: Good Verification - -```markdown -## Verification Results - -**File Checks:** -βœ… lib/billing/payment-processor.ts (1,234 lines) -βœ… lib/billing/__tests__/payment-processor.test.ts (456 lines) -βœ… lib/billing/worker.ts (modified) - -**Quality Checks:** -βœ… Type check: PASS (0 errors) -βœ… Linter: PASS (0 warnings) -βœ… Build: PASS (2.3s) - -**Tests:** -βœ… 48/48 passing -βœ… 96% coverage -βœ… 0 skipped - -**Git Status:** -- Modified: 1 file -- Created: 2 files -- Total: 3 files changed - -**Verdict:** PASS - -Ready for code review. -``` - -## Example: Bad Verification (Don't Do This) - -```markdown -## Verification Results - -Everything looks good! βœ… - -Builder said tests pass and I believe them. - -**Verdict:** PASS -``` - -**What's wrong:** -- ❌ No evidence -- ❌ Trusted claims without verification -- ❌ Didn't run checks -- ❌ Rubber-stamped - -## Remember - -**You are the INSPECTOR. Your job is to find the truth.** - -If you give a PASS verdict and later find issues, that's on you. diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/AGENT-LIMITATIONS.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/AGENT-LIMITATIONS.md deleted file mode 100644 index 8e218632..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/AGENT-LIMITATIONS.md +++ /dev/null @@ -1,237 +0,0 @@ -# Agent Limitations in Batch Mode - -**CRITICAL:** Agents running in batch-stories have specific limitations. Understanding these prevents wasted time and sets correct expectations. - ---- - -## Core Limitations - -### ❌ Agents CANNOT Invoke Other Workflows - -**What this means:** -- Agents cannot run `/create-story-with-gap-analysis` -- Agents cannot execute `/` slash commands (those are for user CLI) -- Agents cannot call other BMAD workflows mid-execution - -**Why:** -- Slash commands require user terminal context -- Workflow invocation requires special tool access -- Batch agents are isolated execution contexts - -**Implication:** -- Story creation MUST happen before batch execution -- If stories are incomplete, batch will skip them -- No way to "fix" stories during batch - ---- - -### ❌ Agents CANNOT Prompt User Interactively - -**What this means:** -- Batch runs autonomously, no user interaction -- `` tags are auto-answered with defaults -- No way to clarify ambiguous requirements mid-batch - -**Why:** -- Batch is designed for unattended execution -- User may not be present during execution -- Prompts would break parallel execution - -**Implication:** -- All requirements must be clear in story file -- Optional steps are skipped -- Ambiguous stories will halt or skip - ---- - -### ❌ Agents CANNOT Generate Missing BMAD Sections - -**What this means:** -- If story has <12 sections, agent halts -- If story has 0 tasks, agent halts -- Agent will NOT try to "fix" the story format - -**Why:** -- Story format is structural, not implementation -- Generating sections requires context agent doesn't have -- Gap analysis requires codebase scanning beyond agent scope - -**Implication:** -- All stories must be properly formatted BEFORE batch -- Run validation: `./scripts/validate-bmad-format.sh` -- Regenerate incomplete stories manually - ---- - -## What Agents CAN Do - -### βœ… Execute Clear, Well-Defined Tasks - -**Works well:** -- Stories with 10-30 specific tasks -- Clear acceptance criteria -- Existing code to modify -- Well-defined scope - -### βœ… Make Implementation Decisions - -**Works well:** -- Choose between valid approaches -- Apply patterns from codebase -- Fix bugs based on error messages -- Optimize existing code - -### βœ… Run Tests and Verify - -**Works well:** -- Execute test suites -- Measure coverage -- Fix failing tests -- Validate implementations - ---- - -## Pre-Batch Validation Checklist - -**Before running /batch-stories, verify ALL selected stories:** - -```bash -# 1. Check story files exist -for story in $(grep "ready-for-dev" docs/sprint-artifacts/sprint-status.yaml | awk '{print $1}' | sed 's/://'); do - [ -f "docs/sprint-artifacts/story-$story.md" ] || echo "❌ Missing: $story" -done - -# 2. Check all have 12 BMAD sections -for file in docs/sprint-artifacts/story-*.md; do - sections=$(grep -c "^## " "$file") - if [ "$sections" -lt 12 ]; then - echo "❌ Incomplete: $file ($sections/12 sections)" - fi -done - -# 3. Check all have tasks -for file in docs/sprint-artifacts/story-*.md; do - tasks=$(grep -c "^- \[ \]" "$file") - if [ "$tasks" -eq 0 ]; then - echo "❌ No tasks: $file" - fi -done -``` - -**If any checks fail:** -1. Regenerate those stories: `/create-story-with-gap-analysis` -2. Validate again -3. THEN run batch-stories - ---- - -## Error Messages Explained - -### "EARLY BAILOUT: No Tasks Found" - -**What it means:** Story file has 0 unchecked tasks -**Is this a bug?** ❌ NO - This is correct validation -**What to do:** -- If story is skeleton: Regenerate with /create-story-with-gap-analysis -- If story is complete: Mark as "done" in sprint-status.yaml -- If story needs work: Add tasks to story file - -### "EARLY BAILOUT: Invalid Story Format" - -**What it means:** Story missing required sections (Tasks, AC, etc.) -**Is this a bug?** ❌ NO - This is correct validation -**What to do:** -- Regenerate with /create-story-with-gap-analysis -- Do NOT try to manually add sections (skip gap analysis) -- Do NOT launch batch with incomplete stories - -### "Story Creation Failed" or "Skipped" - -**What it means:** Agent tried to create story but couldn't -**Is this a bug?** ❌ NO - Agents can't create stories -**What to do:** -- Exit batch-stories -- Manually run /create-story-with-gap-analysis -- Re-run batch after story created - ---- - -## Best Practices - -### βœ… DO: Generate All Stories Before Batch - -**Workflow:** -``` -1. Plan epic β†’ Identify stories β†’ Create list -2. Generate stories: /create-story-with-gap-analysis (1-2 days) -3. Validate stories: ./scripts/validate-all-stories.sh -4. Execute stories: /batch-stories (parallel, fast) -``` - -### βœ… DO: Use Small Batches for Mixed Complexity - -**Workflow:** -``` -1. Group by complexity (micro, standard, complex) -2. Batch micro stories (quick wins) -3. Batch standard stories -4. Execute complex stories individually -``` - -### ❌ DON'T: Try to Batch Regenerate - -**Why it fails:** -``` -1. Create 20 skeleton files with just widget lists -2. Run /batch-stories -3. Expect agents to regenerate them - β†’ FAILS: Agents can't invoke /create-story workflow -``` - -### ❌ DON'T: Mix Skeletons with Proper Stories - -**Why it fails:** -``` -1. 10 proper BMAD stories + 10 skeletons -2. Run /batch-stories -3. Expect batch to handle both - β†’ RESULT: 10 execute, 10 skipped (confusing) -``` - -### ❌ DON'T: Assume Agents Will "Figure It Out" - -**Why it fails:** -``` -1. Launch batch with unclear stories -2. Hope agents will regenerate/fix/create - β†’ RESULT: Agents halt correctly, nothing happens -``` - ---- - -## Summary - -**The Golden Rule:** -> **Batch-super-dev is for EXECUTION, not CREATION.** -> -> Story creation is interactive and requires user input. -> Always create/regenerate stories BEFORE batch execution. - -**Remember:** -- Agents have limitations (documented above) -- These are features, not bugs -- Workflows correctly validate and halt -- User must prepare stories properly first - -**Success Formula:** -``` -Proper Story Generation (1-2 days manual work) - ↓ -Validation (5 minutes automated) - ↓ -Batch Execution (4-8 hours parallel autonomous) - ↓ -Review & Merge (1-2 hours) -``` - -Don't skip the preparation steps! diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md deleted file mode 100644 index 375c381a..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/README.md +++ /dev/null @@ -1,742 +0,0 @@ -# Batch Super-Dev Workflow - -**Version:** 1.3.1 (Agent Limitations Documentation) -**Created:** 2026-01-06 -**Updated:** 2026-01-08 -**Author:** BMad - ---- - -## Critical Prerequisites - -> **⚠️ IMPORTANT: Read before running batch-stories!** - -**BEFORE running batch-stories:** - -### βœ… 1. All stories must be properly generated - -- Run: `/create-story-with-gap-analysis` for each story -- Do NOT create skeleton/template files manually -- Validation: `./scripts/validate-all-stories.sh` - -**Why:** Agents CANNOT invoke `/create-story-with-gap-analysis` workflow. Story generation requires user interaction and context-heavy codebase scanning. - -### βœ… 2. All stories must have 12 BMAD sections - -Required sections: -1. Business Context -2. Current State -3. Acceptance Criteria -4. Tasks/Subtasks -5. Technical Requirements -6. Architecture Compliance -7. Testing Requirements -8. Dev Agent Guardrails -9. Definition of Done -10. References -11. Dev Agent Record -12. Change Log - -### βœ… 3. All stories must have tasks - -- At least 3 unchecked tasks (minimum for valid story) -- Zero-task stories will be skipped -- Validation: `grep -c "^- \[ \]" story-file.md` - -### Common Failure Mode: Batch Regeneration - -**What you might try:** -``` -1. Create 20 skeleton story files (just headers + widget lists) -2. Run /batch-stories -3. Expect agents to regenerate them -``` - -**What happens:** -- Agents identify stories are incomplete -- Agents correctly halt per story-full-pipeline validation -- Stories get skipped (not regenerated) -- You waste time - -**Solution:** -```bash -# 1. Generate all stories (1-2 days, manual) -/create-story-with-gap-analysis # For each story - -# 2. Validate (30 seconds, automated) -./scripts/validate-all-stories.sh - -# 3. Execute (4-8 hours, parallel autonomous) -/batch-stories -``` - -See: `AGENT-LIMITATIONS.md` for full documentation on what agents can and cannot do. - ---- - -## Overview - -Interactive batch workflow for processing multiple `ready-for-dev` stories sequentially or in parallel using the story-full-pipeline with full quality gates. - -**New in v1.2.0:** Smart Story Validation & Auto-Creation - validates story files, creates missing stories, regenerates invalid ones automatically. -**New in v1.1.0:** Smart Story Reconciliation - automatically verifies story accuracy after each implementation. - ---- - -## Features - -### Core Capabilities - -1. **πŸ†• Smart Story Validation & Auto-Creation** (NEW v1.2.0) - - Validates all selected stories before processing - - Checks for 12 required BMAD sections - - Validates content quality (Current State β‰₯100 words, gap analysis present) - - **Auto-creates missing story files** with codebase gap analysis - - **Auto-regenerates invalid stories** (incomplete or stub files) - - Interactive prompts (or fully automated with settings) - - Backups existing files before regeneration - -2. **Interactive Story Selection** - - Lists all `ready-for-dev` stories from sprint-status.yaml - - Shows story status icons (βœ… file exists, ❌ missing, πŸ”„ needs status update) - - Supports flexible selection syntax: single, ranges, comma-separated, "all" - - Optional epic filtering (process only Epic 3 stories, etc.) - -3. **Execution Modes** - - **Sequential:** Process stories one-by-one in current session (easier monitoring) - - **Parallel:** Spawn Task agents to process stories concurrently (faster, autonomous) - - Configurable parallelism: 2, 4, or all stories at once - -4. **Full Quality Gates** (from story-full-pipeline) - - Pre-gap analysis (validate story completeness) - - Test-driven implementation - - Post-validation (verify requirements met) - - Multi-agent code review (4 specialized agents) - - Targeted git commits - - Definition of done verification - -5. **Smart Story Reconciliation** (v1.1.0) - - Automatically checks story accuracy after implementation - - Verifies Acceptance Criteria checkboxes match Dev Agent Record - - Verifies Tasks/Subtasks checkboxes match implementation - - Verifies Definition of Done completion - - Updates story status (done/review/in-progress) based on actual completion - - Synchronizes sprint-status.yaml with story file status - - **Prevents "done" stories with unchecked items** βœ… - ---- - -## Smart Story Validation & Auto-Creation (NEW v1.2.0) - -### What It Does - -Before processing any selected stories, the workflow automatically validates each story file: - -1. **File Existence Check** - Verifies story file exists (tries multiple naming patterns) -2. **Section Validation** - Ensures all 12 BMAD sections are present -3. **Content Quality Check** - Validates sufficient content (not stubs): - - Current State: β‰₯100 words - - Gap analysis markers: βœ…/❌ present - - Acceptance Criteria: β‰₯3 items - - Tasks: β‰₯5 items -4. **Auto-Creation** - Creates missing stories with codebase gap analysis -5. **Auto-Regeneration** - Regenerates invalid/incomplete story files - -### Why This Matters - -**Problem this solves:** - -Before v1.2.0: -``` -User: "Process stories 3.1, 3.2, 3.3, 3.4" -Workflow: "Story 3.3 file missing - please create it first" -User: Ctrl+C β†’ /create-story β†’ /batch-stories again -``` - -After v1.2.0: -``` -User: "Process stories 3.1, 3.2, 3.3, 3.4" -Workflow: "Story 3.3 missing - create it? (yes)" -User: "yes" -Workflow: Creates story 3.3 with gap analysis β†’ Processes all 4 stories -``` - -**Prevents:** -- Incomplete story files being processed -- Missing gap analysis -- Stub files (< 100 words) -- Manual back-and-forth workflow interruptions - -### Validation Process - -``` -Load Sprint Status - ↓ -Display Available Stories - ↓ -πŸ†• VALIDATE EACH STORY ← NEW STEP 2.5 - ↓ -For each story: - β”Œβ”€ File missing? β†’ Prompt: "Create story with gap analysis?" - β”‚ └─ yes β†’ /create-story-with-gap-analysis β†’ βœ… Created - β”‚ └─ no β†’ ⏭️ Skip story - β”‚ - β”Œβ”€ File exists but invalid? - β”‚ (< 12 sections OR < 100 words OR no gap analysis) - β”‚ β†’ Prompt: "Regenerate story with codebase scan?" - β”‚ └─ yes β†’ Backup original β†’ /create-story-with-gap-analysis β†’ βœ… Regenerated - β”‚ └─ no β†’ ⏭️ Skip story - β”‚ - └─ File valid? β†’ βœ… Ready to process - ↓ -Remove skipped stories - ↓ -Display Validated Stories - ↓ -User Selection (only validated stories) - ↓ -Process Stories -``` - -### Configuration Options - -**In workflow.yaml:** - -```yaml -# Story validation settings (NEW in v1.2.0) -validation: - enabled: true # Enable/disable validation - auto_create_missing: false # Auto-create without prompting (use cautiously) - auto_regenerate_invalid: false # Auto-regenerate without prompting (use cautiously) - min_sections: 12 # BMAD format requires all 12 - min_current_state_words: 100 # Minimum content length - require_gap_analysis: true # Must have βœ…/❌ markers - backup_before_regenerate: true # Create .backup before regenerating -``` - -**Interactive Mode (default):** -- Prompts before creating/regenerating each story -- Safe, user retains control -- Recommended for most workflows - -**Fully Automated Mode:** -```yaml -validation: - auto_create_missing: true - auto_regenerate_invalid: true -``` -- Creates/regenerates without prompting -- Faster for large batches -- Use with caution (may overwrite valid stories) - -### Example Session (v1.2.0) - -``` -πŸ€– /batch-stories - -πŸ“Š Ready-for-Dev Stories (5) - -1. **3-1-vehicle-card** βœ… - β†’ Story file exists -2. **3-2-vehicle-search** βœ… - β†’ Story file exists -3. **3-3-vehicle-compare** ❌ - β†’ Story file missing -4. **3-4-vehicle-details** ⚠️ - β†’ File exists (7/12 sections, stub content) -5. **3-5-vehicle-history** βœ… - β†’ Story file exists - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” VALIDATING STORY FILES -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Story 3-1-vehicle-card: βœ… Valid (12/12 sections, gap analysis present) - -Story 3-2-vehicle-search: βœ… Valid (12/12 sections, gap analysis present) - -πŸ“ Story 3-3-vehicle-compare: File missing - -Create story file with gap analysis? (yes/no): yes - -Creating story 3-3-vehicle-compare with codebase gap analysis... -β†’ Scanning apps/frontend/web for existing components... -β†’ Scanning packages/widgets for related widgets... -β†’ Analyzing gap: 3 files exist, 5 need creation - -βœ… Story 3-3-vehicle-compare created successfully (12/12 sections) - -⚠️ Story 3-4-vehicle-details: File incomplete or invalid - - Sections: 7/12 - - Current State: stub (32 words, expected β‰₯100) - - Gap analysis: missing - -Regenerate story with codebase scan? (yes/no): yes - -Regenerating story 3-4-vehicle-details with gap analysis... -β†’ Backing up to docs/sprint-artifacts/3-4-vehicle-details.md.backup -β†’ Scanning codebase for VehicleDetails implementation... -β†’ Found: packages/widgets/vehicle-details-v2 (partial) -β†’ Analyzing gap: 8 files exist, 3 need creation - -βœ… Story 3-4-vehicle-details regenerated successfully (12/12 sections) - -Story 3-5-vehicle-history: βœ… Valid (12/12 sections, gap analysis present) - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… Story Validation Complete -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -**Validated:** 5 stories ready to process -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Select stories to process: all - -[Proceeds to process all 5 validated stories...] -``` - ---- - -## Smart Story Reconciliation (v1.1.0) - -### What It Does - -After each story completes, the workflow automatically: - -1. **Loads Dev Agent Record** - Reads implementation summary, file list, test results -2. **Analyzes Acceptance Criteria** - Checks which ACs have evidence of completion -3. **Analyzes Tasks** - Verifies which tasks have been implemented -4. **Analyzes Definition of Done** - Confirms quality gates passed -5. **Calculates Completion %** - AC%, Tasks%, DoD% percentages -6. **Determines Correct Status:** - - `done`: ACβ‰₯95% AND Tasksβ‰₯95% AND DoDβ‰₯95% - - `review`: ACβ‰₯80% AND Tasksβ‰₯80% AND DoDβ‰₯80% - - `in-progress`: Below 80% on any category -7. **Updates Story File** - Checks/unchecks boxes to match reality -8. **Updates sprint-status.yaml** - Synchronizes status entry - -### Why This Matters - -**Problem this solves:** - -Story 20.8 (before reconciliation): -- Dev Agent Record: "COMPLETE - 10 files created, 37 tests passing" -- Acceptance Criteria: All unchecked ❌ -- Tasks: All unchecked ❌ -- Definition of Done: All unchecked ❌ -- sprint-status.yaml: `ready-for-dev` ❌ -- **Reality:** Story was 100% complete but looked 0% complete! - -**After reconciliation:** -- Acceptance Criteria: 17/18 checked βœ… -- Tasks: 24/24 checked βœ… -- Definition of Done: 24/25 checked βœ… -- sprint-status.yaml: `done` βœ… -- **Accurate representation of actual completion** βœ… - -### Reconciliation Process - -``` -Implementation Complete - ↓ -Load Dev Agent Record - ↓ -Parse: Implementation Summary, File List, Test Results, Completion Notes - ↓ -For each checkbox in ACs/Tasks/DoD: - - Search Dev Agent Record for evidence - - Determine expected status (checked/unchecked/partial) - - Compare actual vs expected - - Record discrepancies - ↓ -Calculate completion percentages: - - AC: X/Y checked (Z%) - - Tasks: X/Y checked (Z%) - - DoD: X/Y checked (Z%) - ↓ -Determine correct story status (done/review/in-progress) - ↓ -Apply changes (with user confirmation): - - Update checkboxes in story file - - Update story status header - - Update sprint-status.yaml entry - ↓ -Report final completion statistics -``` - -### Reconciliation Output - -``` -πŸ”§ Story 20.8: Reconciling 42 issues - -Changes to apply: -1. AC1: FlexibleGridSection component - CHECK (File created: FlexibleGridSection.tsx) -2. AC2: Screenshot automation - CHECK (File created: screenshot-pages.ts) -3. Task 1.3: Create page corpus generator - CHECK (File created: generate-page-corpus.ts) -... (39 more) - -Apply these reconciliation changes? (yes/no): yes - -βœ… Story 20.8: Reconciliation complete (42 changes applied) - -πŸ“Š Story 20.8 - Final Status - -Acceptance Criteria: 17/18 (94%) -Tasks/Subtasks: 24/24 (100%) -Definition of Done: 24/25 (96%) - -Story Status: done -sprint-status.yaml: done - -βœ… Story is COMPLETE and accurately reflects implementation -``` - ---- - -## Usage - -### Basic Usage - -```bash -# Process all ready-for-dev stories -/batch-stories - -# Follow prompts: -# 1. See list of ready stories -# 2. Select stories to process (1,3-5,8 or "all") -# 3. Choose execution mode (sequential/parallel) -# 4. Confirm execution plan -# 5. Stories process automatically with reconciliation -# 6. Review batch summary -``` - -### Epic Filtering - -```bash -# Only process Epic 3 stories -/batch-stories filter_by_epic=3 -``` - -### Selection Syntax - -``` -Single: 1 -Multiple: 1,3,5 -Range: 1-5 (processes 1,2,3,4,5) -Mixed: 1,3-5,8 (processes 1,3,4,5,8) -All: all (processes all ready-for-dev stories) -``` - -### Execution Modes - -**Sequential (Recommended for ≀5 stories):** -- Processes one story at a time in current session -- Easier to monitor progress -- Lower resource usage -- Can pause/cancel between stories - -**Parallel (Recommended for >5 stories):** -- Spawns autonomous Task agents -- Much faster (2-4x speedup) -- Choose parallelism: 2 (conservative), 4 (moderate), all (aggressive) -- Requires more system resources - ---- - -## Workflow Configuration - -**File:** `_bmad/bmm/workflows/4-implementation/batch-stories/workflow.yaml` - -### Key Settings - -```yaml -# Safety limits -max_stories: 20 # Won't process more than 20 in one batch - -# Pacing -pause_between_stories: 5 # Seconds between stories (sequential mode) - -# Error handling -continue_on_failure: true # Keep processing if one story fails - -# Reconciliation (NEW v1.1.0) -reconciliation: - enabled: true # Auto-reconcile after each story - require_confirmation: true # Ask before applying changes - update_sprint_status: true # Sync sprint-status.yaml -``` - ---- - -## Workflow Steps - -### 1. Load Sprint Status -- Parses sprint-status.yaml -- Filters stories with status="ready-for-dev" -- Excludes epics and retrospectives -- Optionally filters by epic number - -### 2. Display Available Stories -- Shows all ready-for-dev stories -- Verifies story files exist -- Displays status icons and comments - -### 2.5. πŸ†• Validate and Create/Regenerate Stories (NEW v1.2.0) -**For each story:** -- Check file existence (multiple naming patterns) -- Validate 12 BMAD sections present -- Check content quality (Current State β‰₯100 words, gap analysis) -- **If missing:** Prompt to create with gap analysis -- **If invalid:** Prompt to regenerate with codebase scan -- **If valid:** Mark ready to process -- Remove skipped stories from selection - -### 3. Get User Selection -- Interactive story picker -- Supports flexible selection syntax -- Validates selection and confirms - -### 3.5. Choose Execution Strategy -- Sequential vs Parallel -- If parallel: choose concurrency level -- Confirm execution plan - -### 4. Process Stories -**Sequential Mode:** -- For each selected story: - - Invoke story-full-pipeline - - Execute reconciliation (Step 4.5) - - Report results - - Pause between stories - -**Parallel Mode (Semaphore Pattern - NEW v1.3.0):** -- Initialize worker pool with N slots (user-selected concurrency) -- Fill initial N slots with first N stories -- Poll workers continuously (non-blocking) -- As soon as worker completes β†’ immediately refill slot with next story -- Maintain constant N concurrent agents until queue empty -- Execute reconciliation after each story completes -- **Commit Queue:** File-based locking prevents git lock conflicts - - Workers acquire `.git/bmad-commit.lock` before committing - - Automatic retry with exponential backoff (1s β†’ 30s) - - Stale lock cleanup (>5 min) - - Serialized commits, parallel implementation -- No idle time waiting for batch synchronization -- **20-40% faster** than old batch-and-wait pattern - -### 4.5. Smart Story Reconciliation (NEW) -**Executed after each story completes:** -- Load Dev Agent Record -- Analyze ACs/Tasks/DoD vs implementation -- Calculate completion percentages -- Determine correct story status -- Update checkboxes and status -- Sync sprint-status.yaml - -See: `step-4.5-reconcile-story-status.md` for detailed algorithm - -### 5. Display Batch Summary -- Shows completion statistics -- Lists failed stories (if any) -- Lists reconciliation warnings (if any) -- Provides next steps -- Saves batch log - ---- - -## Output Files - -### Batch Log - -**Location:** `docs/sprint-artifacts/batch-stories-{date}.log` - -**Contains:** -- Start/end timestamps -- Selected stories -- Completed stories -- Failed stories -- Reconciliation warnings -- Success rate -- Total duration - -### Reconciliation Results (per story) - -**Embedded in Dev Agent Record:** -- Reconciliation summary -- Changes applied -- Final completion percentages -- Status determination reasoning - ---- - -## Error Handling - -### Story Implementation Fails -- Increments failed counter -- Adds to failed_stories list -- If `continue_on_failure=true`, continues with remaining stories -- If `continue_on_failure=false`, stops batch - -### Reconciliation Fails -- Story still marked as completed (implementation succeeded) -- Adds to reconciliation_warnings list -- User warned to manually verify story accuracy -- Does NOT fail the batch - -### Task Agent Fails (Parallel Mode) -- Collects error from TaskOutput -- Marks story as failed -- Continues with remaining stories in batch - ---- - -## Best Practices - -### Story Selection -- βœ… Start small: Process 2-3 stories first to verify workflow -- βœ… Group by epic: Related stories often share context -- βœ… Check file status: βœ… stories are ready, ❌ need creation first -- ❌ Don't process 20 stories at once on first run - -### Execution Mode -- Sequential for ≀5 stories (easier monitoring) -- Parallel for >5 stories (faster completion) -- Use parallelism=2 first, then increase if stable - -### During Execution -- Monitor progress output -- Check reconciliation reports -- Verify changes look correct -- Spot-check 1-2 completed stories - -### After Completion -1. Review batch summary -2. Check reconciliation warnings -3. Verify sprint-status.yaml updated -4. Run tests: `pnpm test` -5. Check coverage: `pnpm test --coverage` -6. Review commits: `git log -` -7. Spot-check 2-3 stories for quality - ---- - -## Troubleshooting - -### Reconciliation Reports Many Warnings - -**Cause:** Dev Agent Record may be incomplete or stories weren't fully implemented - -**Fix:** -1. Review listed stories manually -2. Check Dev Agent Record has all required sections -3. Re-run story-full-pipeline for problematic stories -4. Manually reconcile checkboxes if needed - -### Parallel Mode Hangs - -**Cause:** Too many agents running concurrently, system resources exhausted - -**Fix:** -1. Kill hung agents: `/tasks` then `kill ` -2. Reduce parallelism: Use 2 instead of 4 -3. Process remaining stories sequentially - -### Story Marked "done" but has Unchecked Items - -**Cause:** Reconciliation may have missed some checkboxes - -**Fix:** -1. Review Dev Agent Record -2. Check which checkboxes should be checked -3. Manually check them or re-run reconciliation: - - Load story file - - Compare ACs/Tasks/DoD to Dev Agent Record - - Update checkboxes to match reality - ---- - -## Version History - -### v1.3.0 (2026-01-07) -- **NEW:** Complexity-Based Routing (Step 2.6) - - Automatic story complexity scoring (micro/standard/complex) - - Risk keyword detection with configurable weights - - Smart pipeline selection: micro β†’ lightweight, complex β†’ enhanced - - 50-70% token savings for micro stories - - Deterministic classification with mutually exclusive thresholds - - **CRITICAL:** Rejects stories with <3 tasks as INVALID (prevents 0-task stories from being processed) -- **NEW:** Semaphore Pattern for Parallel Execution - - Worker pool maintains constant N concurrent agents - - As soon as worker completes β†’ immediately start next story - - No idle time waiting for batch synchronization - - 20-40% faster than old batch-and-wait pattern - - Non-blocking task polling with live progress dashboard -- **NEW:** Git Commit Queue (Parallel-Safe) - - File-based locking prevents concurrent commit conflicts - - Workers acquire `.git/bmad-commit.lock` before committing - - Automatic retry with exponential backoff (1s β†’ 30s max) - - Stale lock cleanup (>5 min old locks auto-removed) - - Eliminates "Another git process is running" errors - - Serializes commits while keeping implementations parallel -- **NEW:** Continuous Sprint-Status Tracking - - sprint-status.yaml updated after EVERY task completion - - Real-time progress: "# 7/10 tasks (70%)" - - CRITICAL enforcement with HALT on update failure - - Immediate visibility into story progress -- **NEW:** Stricter Story Validation - - Step 2.5 now rejects stories with <3 tasks - - Step 2.6 marks stories with <3 tasks as INVALID - - Prevents incomplete/stub stories from being processed - - Requires /validate-create-story to fix before processing - -### v1.2.0 (2026-01-06) -- **NEW:** Smart Story Validation & Auto-Creation (Step 2.5) - - Validates story files before processing - - Auto-creates missing stories with gap analysis - - Auto-regenerates invalid/incomplete stories - - Checks 12 BMAD sections, content quality - - Interactive or fully automated modes - - Backups before regeneration -- **Removes friction:** No more "story file missing" interruptions -- **Ensures quality:** Only valid stories with gap analysis proceed -- **Configuration:** New `validation` settings in workflow.yaml - -### v1.1.0 (2026-01-06) -- **NEW:** Smart Story Reconciliation (Step 4.5) - - Auto-verifies story accuracy after implementation - - Updates checkboxes based on Dev Agent Record - - Synchronizes sprint-status.yaml - - Prevents "done" stories with unchecked items -- Added reconciliation warnings to batch summary -- Added reconciliation statistics to output - -### v1.0.0 (2026-01-05) -- Initial release -- Interactive story selector -- Sequential and parallel execution modes -- Integration with story-full-pipeline -- Batch summary and logging - ---- - -## Related Workflows - -- **story-full-pipeline:** Individual story implementation (invoked by batch-stories) -- **create-story-with-gap-analysis:** Create new stories with codebase scan -- **sprint-status:** View/update sprint status -- **multi-agent-review:** Standalone code review (part of story-full-pipeline) - ---- - -## Support - -**Questions or Issues:** -- Check workflow logs: `docs/sprint-artifacts/batch-stories-*.log` -- Review reconciliation step: `step-4.5-reconcile-story-status.md` -- Check story file format: Ensure 12-section BMAD format -- Verify Dev Agent Record populated: Required for reconciliation - ---- - -**Last Updated:** 2026-01-07 -**Status:** Active - Production-ready with semaphore pattern and continuous tracking -**Maintained By:** BMad diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/RESILIENCE-FIX.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/RESILIENCE-FIX.md deleted file mode 100644 index 8cb4edf0..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/RESILIENCE-FIX.md +++ /dev/null @@ -1,256 +0,0 @@ -# Batch-Super-Dev Resilience Fix - -**Problem:** Agents crash mid-execution, resume fails, no intermediate state saved - ---- - -## Issues Observed - -**Story 18-4 β†’ 18-5 Transition:** -``` -βœ… Story 18-4: Builder β†’ Inspector β†’ Fixer β†’ Reviewer all complete -❌ Story 18-5: Workflow crashed on "Error reading file" -``` - -**Evidence:** -- Task output files empty (0 bytes) -- Resume attempts failed (0 tools used, 0 tokens) -- No state saved between stories -- When agent crashes, all progress lost - ---- - -## Root Cause - -**Sequential processing in main context has no resilience:** - -``` -Story 18-4: - β”œβ”€ Builder agent completes β†’ outputs to temp file - β”œβ”€ Main reads output file β†’ starts Inspector - β”œβ”€ Inspector completes β†’ outputs to temp file - β”œβ”€ Main reads output β†’ starts Fixer - └─ Fixer completes β†’ Story 18-4 done - -Story 18-5: - β”œβ”€ Main tries to read Story 18-5 file - β”œβ”€ ❌ "Error reading file" (crash) - └─ All progress lost, no state saved -``` - -**Problem:** Main context doesn't save state between stories. If it crashes, batch starts over. - ---- - -## Solution: Save State After Each Story - -### Add state file tracking: - -```yaml -# In batch-stories/workflow.yaml -state_tracking: - enabled: true - state_file: "{sprint_artifacts}/batch-execution-state-{batch_id}.yaml" - save_after_each_story: true -``` - -### State file format: - -```yaml -batch_id: "epic-18-2026-01-26" -started: "2026-01-26T18:45:00Z" -execution_mode: "fully_autonomous" -strategy: "sequential" -total_stories: 2 - -stories: - - story_key: "18-4-billing-worker-retry-logic" - status: "completed" - started: "2026-01-26T18:46:00Z" - completed: "2026-01-26T19:05:00Z" - agents: - - phase: "builder" - agent_id: "ae3bd2b" - status: "completed" - - phase: "inspector" - agent_id: "a9f0d11" - status: "completed" - - phase: "fixer" - agent_id: "abc123" - status: "completed" - - phase: "reviewer" - agent_id: "def456" - status: "completed" - - - story_key: "18-5-precharge-payment-validation" - status: "in_progress" - started: "2026-01-26T19:05:30Z" - last_checkpoint: "attempting_to_read_story_file" - error: "Error reading file" -``` - -### Resume logic: - -```bash -# At batch-stories start, check for existing state file -state_file="{sprint_artifacts}/batch-execution-state-*.yaml" - -if ls $state_file 2>/dev/null; then - echo "πŸ”„ Found interrupted batch execution" - echo "Resume from where it left off? (yes/no)" - - if yes: - # Load state file - # Skip completed stories - # Start from next story - # Reuse agent IDs if resumable -fi -``` - -### After each story completes: - -```bash -# Update state file -update_state_file() { - story_key="$1" - status="$2" # completed | failed - - # Update YAML - # Mark story as completed - # Save timestamp - # Record agent IDs -} - -# After Builder completes -update_state_file "$story_key" "builder_complete" - -# After Inspector completes -update_state_file "$story_key" "inspector_complete" - -# After Fixer completes -update_state_file "$story_key" "fixer_complete" - -# After Reviewer completes -update_state_file "$story_key" "reviewer_complete" - -# When entire story done -update_state_file "$story_key" "completed" -``` - -### Error handling: - -```bash -# Wrap file reads in try-catch -read_with_retry() { - file_path="$1" - max_attempts=3 - - for attempt in {1..$max_attempts}; do - if content=$(cat "$file_path" 2>&1); then - echo "$content" - return 0 - else - echo "⚠️ Failed to read $file_path (attempt $attempt/$max_attempts)" >&2 - sleep 2 - fi - done - - echo "❌ Cannot read file after $max_attempts attempts: $file_path" >&2 - return 1 -} - -# Use in workflow -story_content=$(read_with_retry "$story_file") || { - echo "❌ Cannot proceed with Story $story_key - file read failed" - # Save state - # Skip this story - # Continue to next story (if continue_on_failure=true) -} -``` - ---- - -## Implementation - -Add to batch-stories Step 4-Sequential: - -```xml - - Check for state file: batch-execution-state-*.yaml - - - πŸ”„ Found interrupted batch from {state.started} - Completed: {state.completed_count} stories - Failed: {state.failed_count} stories - In progress: {state.current_story} - - Resume from where it left off? (yes/no) - - - Load state - Skip completed stories - Start from next story - - - - Archive old state file - Start fresh batch - - - - - - Save state: story started - - - Read story file with retry - Execute story-full-pipeline - Save state: story completed - - - - ⚠️ Cannot read story file for {story_key} - Save state: story failed (file read error) - Add to failed_stories list - Continue to next story if continue_on_failure=true - - - - ⚠️ Agent crashed for {story_key} - Save state: story failed (agent crash) - Record partial progress in state file - Continue to next story if continue_on_failure=true - - -``` - ---- - -## Expected Behavior After Fix - -**If crash happens:** - -``` -Story 18-4: βœ… Complete (state saved) -Story 18-5: ❌ Crashed (state saved with error) - -State file created: batch-execution-state-epic-18.yaml - -User re-runs: /batch-stories - -Workflow: "πŸ”„ Found interrupted batch. Resume? (yes/no)" -User: "yes" -Workflow: "βœ… Skipping 18-4 (already complete)" -Workflow: "πŸ”„ Retrying 18-5 (was in_progress)" -Workflow: Starts 18-5 from beginning -``` - -**Benefits:** -- No lost progress -- Can resume after crashes -- Intermediate state preserved -- Failures don't block batch - ---- - -Should I implement this resilience fix now? diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/WORKFLOW-PATCH-STEP-2.5.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/WORKFLOW-PATCH-STEP-2.5.md deleted file mode 100644 index 837ee7e4..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/WORKFLOW-PATCH-STEP-2.5.md +++ /dev/null @@ -1,347 +0,0 @@ -# Batch-Super-Dev Step 2.5 Patch - -**Issue:** Step 2.5 tries to invoke `/create-story-with-gap-analysis` which agents cannot do -**Impact:** Skeleton stories get skipped instead of regenerated -**Fix:** Explicitly halt batch and tell user to regenerate manually - ---- - -## Current Code (BROKEN) - -**File:** `instructions.md` lines 82-99 - -```xml -Create story file with gap analysis? (yes/no): - - - Creating story {{story_key}} with codebase gap analysis... - Invoke workflow: /bmad:bmm:workflows:create-story-with-gap-analysis - Parameters: story_key={{story_key}} - - - βœ… Story {{story_key}} created successfully (12/12 sections) - Update file_status_icon to βœ… - Mark story as validated - - - - ❌ Story creation failed: {{story_key}} - Mark story for removal from selection - Add to skipped_stories list with reason: "Creation failed" - - -``` - -**Problem:** -- Line 86: "Invoke workflow: /" doesn't work for agents -- Agents can't execute slash commands -- This always fails in batch mode - ---- - -## Recommended Fix (WORKING) - -**Replace lines 82-99 with:** - -```xml -Create story file with gap analysis? (yes/no): - - - -⚠️ STORY CREATION REQUIRES MANUAL WORKFLOW EXECUTION - -**Story:** {{story_key}} -**Status:** File missing or incomplete - -**Problem:** -Agents cannot invoke /create-story-with-gap-analysis workflow autonomously. -This workflow requires: -- Interactive user prompts -- Context-heavy codebase scanning -- Gap analysis decision-making - -**Required Action:** - -1. **Exit this batch execution:** - - Remaining stories will be skipped - - Batch will continue with valid stories only - -2. **Regenerate story manually:** - ``` - /create-story-with-gap-analysis - ``` - When prompted, provide: - - Story key: {{story_key}} - - Epic: {epic from parent story} - - Scope: {widget list or feature description} - -3. **Validate story format:** - ``` - ./scripts/validate-bmad-format.sh docs/sprint-artifacts/story-{{story_key}}.md - ``` - Must show: "βœ… All 12 sections present" - -4. **Re-run batch-stories:** - - Story will now be properly formatted - - Can be executed in next batch run - -**Skipping story {{story_key}} from current batch execution.** - - - Mark story for removal from selection - Add to skipped_stories list with reason: "Story creation requires manual workflow (agents cannot invoke /create-story)" - Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis" - - - - ⏭️ Skipping story {{story_key}} (file missing, user declined creation) - Mark story for removal from selection - Add to skipped_stories list with reason: "User declined story creation" - -``` - -**Why This Works:** -- βœ… Explicitly states agents can't create stories -- βœ… Provides clear step-by-step user actions -- βœ… Skips gracefully instead of failing silently -- βœ… Tracks manual actions needed -- βœ… Sets correct expectations - ---- - -## Additional Improvements - -### Add Manual Actions Tracking - -**At end of batch execution (Step 5), add:** - -```xml - - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -⚠️ MANUAL ACTIONS REQUIRED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -**{{manual_actions_required.length}} stories require manual intervention:** - -{{#each manual_actions_required}} -{{@index}}. **{{story_key}}** - Action: {{action_description}} - Command: {{command_to_run}} -{{/each}} - -**After completing these actions:** -1. Validate all stories: ./scripts/validate-all-stories.sh -2. Re-run batch-stories for these stories -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - - -``` - -**Why This Helps:** -- User gets clear todo list -- Knows exactly what to do next -- Can track progress on manual actions - ---- - -## Validation Script Enhancement - -**Create:** `scripts/validate-all-stories.sh` - -```bash -#!/bin/bash -# Validate all ready-for-dev stories have proper BMAD format - -set -e - -STORIES=$(grep "ready-for-dev" docs/sprint-artifacts/sprint-status.yaml | awk '{print $1}' | sed 's/://') - -echo "==========================================" -echo " BMAD Story Format Validation" -echo "==========================================" -echo "" - -TOTAL=0 -VALID=0 -INVALID=0 - -for story in $STORIES; do - STORY_FILE="docs/sprint-artifacts/story-$story.md" - - if [ ! -f "$STORY_FILE" ]; then - echo "❌ $story - FILE MISSING" - INVALID=$((INVALID + 1)) - TOTAL=$((TOTAL + 1)) - continue - fi - - # Check BMAD format - ./scripts/validate-bmad-format.sh "$STORY_FILE" >/dev/null 2>&1 - - if [ $? -eq 0 ]; then - echo "βœ… $story - Valid BMAD format" - VALID=$((VALID + 1)) - else - echo "❌ $story - Invalid format (run validation for details)" - INVALID=$((INVALID + 1)) - fi - - TOTAL=$((TOTAL + 1)) -done - -echo "" -echo "==========================================" -echo " Summary" -echo "==========================================" -echo "Total Stories: $TOTAL" -echo "Valid: $VALID" -echo "Invalid: $INVALID" -echo "" - -if [ $INVALID -eq 0 ]; then - echo "βœ… All stories ready for batch execution!" - exit 0 -else - echo "❌ $INVALID stories need regeneration" - echo "" - echo "Run: /create-story-with-gap-analysis" - echo "For each invalid story" - exit 1 -fi -``` - -**Why This Helps:** -- Quick validation before batch -- Prevents wasted time on incomplete stories -- Clear pass/fail criteria - ---- - -## Documentation Update - -**Add to:** `_bmad/bmm/workflows/4-implementation/batch-stories/README.md` - -```markdown -# Batch Super-Dev Workflow - -## Critical Prerequisites - -**BEFORE running batch-stories:** - -1. βœ… **All stories must be properly generated** - - Run: `/create-story-with-gap-analysis` for each story - - Do NOT create skeleton/template files manually - - Validation: `./scripts/validate-all-stories.sh` - -2. βœ… **All stories must have 12 BMAD sections** - - Business Context, Current State, Acceptance Criteria - - Tasks/Subtasks, Technical Requirements, Architecture Compliance - - Testing Requirements, Dev Agent Guardrails, Definition of Done - - References, Dev Agent Record, Change Log - -3. βœ… **All stories must have tasks** - - At least 1 unchecked task (something to implement) - - Zero-task stories will be skipped - - Validation: `grep -c "^- \[ \]" story-file.md` - -## Common Failure Modes - -### ❌ Attempting Batch Regeneration - -**What you might try:** -``` -1. Create 20 skeleton story files (just headers + widget lists) -2. Run /batch-stories -3. Expect agents to regenerate them -``` - -**What happens:** -- Agents identify stories are incomplete -- Agents correctly halt per story-full-pipeline validation -- Stories get skipped (not regenerated) -- You waste time - -**Why:** -- Agents CANNOT execute /create-story-with-gap-analysis -- Agents CANNOT invoke other BMAD workflows -- Story generation requires user interaction - -**Solution:** -- Generate ALL stories manually FIRST: /create-story-with-gap-analysis -- Validate: ./scripts/validate-all-stories.sh -- THEN run batch: /batch-stories - -### ❌ Mixed Story Quality - -**What you might try:** -- Mix 10 proper stories + 10 skeletons -- Run batch hoping it "figures it out" - -**What happens:** -- 10 proper stories execute successfully -- 10 skeletons get skipped -- Confusing results - -**Solution:** -- Ensure ALL stories have same quality -- Validate before batch -- Don't mix skeletons with proper stories - -## Success Pattern - -```bash -# 1. Generate all stories (1-2 days, manual) -for story in story-20-13a-{1..5}; do - /create-story-with-gap-analysis - # Provide story details interactively -done - -# 2. Validate (30 seconds, automated) -./scripts/validate-all-stories.sh - -# 3. Execute (4-8 hours, parallel autonomous) -/batch-stories -# Select all 5 stories -# Choose 2-4 agents parallel - -# 4. Review (1-2 hours) -# Review commits, merge to main -``` - -**Total Time:** -- Manual work: 1-2 days (story generation) -- Autonomous work: 4-8 hours (batch execution) -- Review: 1-2 hours - -**Efficiency:** -- Story generation: Cannot be batched (requires user input) -- Story execution: Highly parallelizable (4x speedup with 4 agents) -``` - ---- - -## Implementation Checklist - -**To apply these improvements:** - -- [ ] Update `batch-stories/instructions.md` Step 2.5 (lines 82-99) -- [ ] Add `batch-stories/AGENT-LIMITATIONS.md` (new file) -- [ ] Add `batch-stories/BATCH-BEST-PRACTICES.md` (new file) -- [ ] Update `batch-stories/README.md` with prerequisites -- [ ] Create `scripts/validate-all-stories.sh` (new script) -- [ ] Add manual actions tracking to Step 5 summary -- [ ] Update story-full-pipeline Step 1.4.5 with agent guidance - -**Testing:** -- Try batch with mixed story quality β†’ Should skip skeletons gracefully -- Verify error messages are clear -- Confirm agents halt correctly (not crash) - ---- - -**Expected Result:** -- Users understand limitations upfront -- Clear guidance when stories are incomplete -- No false expectations about batch regeneration -- Better error messages diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md deleted file mode 100644 index eddd36c1..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md +++ /dev/null @@ -1,171 +0,0 @@ -# Step 4.5: Story Reconciliation (Orchestrator-Driven) - -**Version:** 2.1.0 -**Execute:** AFTER story-full-pipeline completes, BEFORE marking story done -**Who:** Orchestrator (YOU) - not an agent - ---- - -## Why Orchestrator Does This - -Agents ignore reconciliation instructions. The orchestrator: -- Has full context of what just happened -- Can use tools directly (Bash, Read, Edit) -- Won't skip "boring" bookkeeping tasks - ---- - -## Execute These Steps - -### Step 1: Get What Was Built - -Run this command with Bash tool: - -```bash -echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -echo "πŸ”§ STORY RECONCILIATION: {{story_key}}" -echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - -# Get the commit for this story -echo "Recent commits:" -git log -5 --oneline | grep -i "{{story_key}}" || echo "(no commits found with story key)" - -# Get files changed -echo "" -echo "Files changed in last commit:" -git diff HEAD~1 --name-only | grep -v "__tests__" | grep -v "\.test\." | head -20 -``` - -Store the output - you'll need it for the next steps. - -### Step 2: Read Story File - -Use Read tool on: `docs/sprint-artifacts/{{story_key}}.md` - -Find these sections: -- **Tasks** (lines starting with `- [ ]` or `- [x]`) -- **Dev Agent Record** (section with Agent Model, Implementation Date, etc.) - -### Step 3: Check Off Completed Tasks - -For EACH task in the Tasks section that relates to files changed: - -Use Edit tool: -``` -file_path: docs/sprint-artifacts/{{story_key}}.md -old_string: "- [ ] Create the SomeComponent" -new_string: "- [x] Create the SomeComponent" -``` - -**Match logic:** -- If task mentions a file that was created β†’ check it off -- If task mentions a service/component that now exists β†’ check it off -- If unsure β†’ leave unchecked (don't over-claim) - -### Step 4: Fill Dev Agent Record - -Use Edit tool to replace the placeholder record: - -``` -file_path: docs/sprint-artifacts/{{story_key}}.md -old_string: "### Dev Agent Record -- **Agent Model Used:** [Not set] -- **Implementation Date:** [Not set] -- **Files Created/Modified:** [Not set] -- **Tests Added:** [Not set] -- **Completion Notes:** [Not set]" -new_string: "### Dev Agent Record -- **Agent Model Used:** Claude Sonnet 4 (multi-agent pipeline) -- **Implementation Date:** 2026-01-26 -- **Files Created/Modified:** - - path/to/file1.ts - - path/to/file2.ts - [list all files from git diff] -- **Tests Added:** X tests (from Inspector report) -- **Completion Notes:** Implemented [brief summary]" -``` - -### Step 5: Verify Updates - -Run this command with Bash tool: - -```bash -echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -echo "πŸ” RECONCILIATION VERIFICATION" -echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - -STORY_FILE="docs/sprint-artifacts/{{story_key}}.md" - -# Count checked tasks -CHECKED=$(grep -c "^- \[x\]" "$STORY_FILE" 2>/dev/null || echo "0") -UNCHECKED=$(grep -c "^- \[ \]" "$STORY_FILE" 2>/dev/null || echo "0") -TOTAL=$((CHECKED + UNCHECKED)) -echo "Tasks: $CHECKED/$TOTAL checked" - -if [ "$CHECKED" -eq 0 ]; then - echo "" - echo "❌ BLOCKER: Zero tasks checked off" - echo "You MUST go back to Step 3 and check off tasks" - exit 1 -fi - -# Check Dev Agent Record filled -if grep -q "Implementation Date: \[Not set\]" "$STORY_FILE" 2>/dev/null; then - echo "❌ BLOCKER: Dev Agent Record not filled" - echo "You MUST go back to Step 4 and fill it" - exit 1 -fi - -if grep -A 3 "### Dev Agent Record" "$STORY_FILE" | grep -q "Implementation Date: 202"; then - echo "βœ… Dev Agent Record: Filled" -else - echo "❌ BLOCKER: Dev Agent Record incomplete" - exit 1 -fi - -echo "" -echo "βœ… RECONCILIATION COMPLETE" -echo " Checked tasks: $CHECKED/$TOTAL" -echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -``` - -### Step 6: Update Sprint Status - -Use Read tool: `docs/sprint-artifacts/sprint-status.yaml` - -Find the entry for {{story_key}} and use Edit tool to update: - -``` -old_string: "{{story_key}}: ready-for-dev" -new_string: "{{story_key}}: done # βœ… COMPLETED 2026-01-26" -``` - -Or if 95%+ complete but not 100%: -``` -new_string: "{{story_key}}: review # 8/10 tasks - awaiting review" -``` - ---- - -## Status Decision Logic - -Based on verification results: - -| Condition | Status | -|-----------|--------| -| 95%+ tasks checked + Dev Record filled | `done` | -| 80-94% tasks checked | `review` | -| <80% tasks checked | `in-progress` | -| Dev Record not filled | `in-progress` | - ---- - -## If Verification Fails - -1. **DO NOT** proceed to next story -2. **DO NOT** mark story as done -3. **FIX** the issue using Edit tool -4. **RE-RUN** verification command -5. **REPEAT** until verification passes - -This is mandatory. No shortcuts. diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.md deleted file mode 100644 index 850e81f4..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.md +++ /dev/null @@ -1,369 +0,0 @@ -# Batch Super-Dev v3.0 - Unified Workflow - - -Interactive story selector for batch implementation. Scan codebase for gaps, select stories, process with story-full-pipeline, reconcile results. - -**AKA:** "Mend the Gap" - Mind the gap between story requirements and reality, then mend it. - - - -**Gap Analysis First, Build Only What's Missing** - -1. Scan codebase to verify what's actually implemented -2. Find the gap between story requirements and reality -3. Build ONLY what's truly missing (no duplicate work) -4. Update tracking to reflect actual completion - -Orchestrator coordinates. Agents do implementation. Orchestrator does reconciliation. - - - -name: batch-stories -version: 3.1.0 - -modes: - sequential: {description: "Process one-by-one in this session", recommended_for: "gap analysis"} - parallel: {description: "Spawn concurrent Task agents", recommended_for: "greenfield batch"} - -complexity_routing: - micro: {max_tasks: 3, max_files: 5, skip_review: true} - standard: {max_tasks: 15, max_files: 30, full_pipeline: true} - complex: {min_tasks: 16, keywords: [auth, security, payment, migration], enhanced_review: true} - -defaults: - auto_create_missing: true # Automatically create missing story files using greenfield workflow - - - -@patterns/hospital-grade.md -@patterns/agent-completion.md -@story-full-pipeline/workflow.md - - - - - -**Load and parse sprint-status.yaml** - -```bash -SPRINT_STATUS="docs/sprint-artifacts/sprint-status.yaml" -[ -f "$SPRINT_STATUS" ] || { echo "ERROR: sprint-status.yaml not found"; exit 1; } -``` - -Use Read tool on sprint-status.yaml. Extract: -- Stories with status `ready-for-dev` or `backlog` -- Exclude epics (`epic-*`) and retrospectives (`*-retrospective`) -- Sort by epic number, then story number - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ LOADING SPRINT STATUS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -If no available stories: report "All stories complete!" and exit. - - - -**Display available stories with file status** - -For each story: -1. Check if story file exists in `docs/sprint-artifacts/` -2. Try patterns: `story-{epic}.{story}.md`, `{epic}-{story}.md`, `{story_key}.md` -3. Mark status: βœ… exists, ❌ missing, πŸ”„ already implemented - -```markdown -## πŸ“¦ Available Stories (N) - -### Ready for Dev (X) -1. **17-10** βœ… occupant-agreement-view -2. **17-11** βœ… agreement-status-tracking - -### Backlog (Y) -3. **18-1** ❌ [needs story file] - -Legend: βœ… ready | ❌ missing | πŸ”„ done but not tracked -``` - - - -**Validate story files have required sections** - -For each story with existing file: -1. Read story file -2. Check for 12 BMAD sections (Business Context, Acceptance Criteria, Tasks, etc.) -3. If invalid: mark for regeneration - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” VALIDATING STORY FILES -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Note:** Stories with missing files will be auto-created in the execution step. - - - -**Score story complexity for pipeline routing** - -For each validated story: - -```bash -# Count tasks -TASK_COUNT=$(grep -c "^- \[ \]" "$STORY_FILE") - -# Check for risk keywords -RISK_KEYWORDS="auth|security|payment|encryption|migration|database|schema" -HIGH_RISK=$(grep -ciE "$RISK_KEYWORDS" "$STORY_FILE") -``` - -**Scoring:** -| Criteria | micro | standard | complex | -|----------|-------|----------|---------| -| Tasks | ≀3 | 4-15 | β‰₯16 | -| Files | ≀5 | ≀30 | >30 | -| Risk keywords | 0 | low | high | - -Store `complexity_level` for each story. - - - -**Get user selection** - -Use AskUserQuestion: -``` -Which stories would you like to implement? - -Options: -1. All ready-for-dev stories (X stories) -2. Select specific stories by number -3. Single story (enter key like "17-10") -``` - -Validate selection against available stories. - - - -**Choose execution mode** - -Use AskUserQuestion: -``` -How should stories be processed? - -Options: -1. Sequential (recommended for gap analysis) - - Process one-by-one in this session - - Verify code β†’ build gaps β†’ check boxes β†’ next - -2. Parallel (for greenfield batch) - - Spawn Task agents concurrently - - Faster but harder to monitor -``` - -For sequential: proceed to `execute_sequential` -For parallel: proceed to `execute_parallel` - - - -**Sequential Processing** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“¦ SEQUENTIAL PROCESSING -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -For each selected story: - -**Step A: Auto-Fix Prerequisites** -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“¦ Story {{index}}/{{total}}: {{story_key}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -```bash -STORY_FILE="docs/sprint-artifacts/{{story_key}}.md" - -echo "πŸ” Checking prerequisites..." -``` - -**Check 1: Story file exists?** -```bash -if [ ! -f "$STORY_FILE" ]; then - echo "⚠️ Creating greenfield story (no gap analysis)..." -fi -``` - -If missing, auto-create using greenfield workflow: -- Use Skill tool: `/bmad_bmm_create-story {{story_key}}` -- Verify created: `[ -f "$STORY_FILE" ]` - -```bash -echo "βœ… Prerequisites satisfied" -``` - -**Step B: Invoke story-full-pipeline** - -Use story-full-pipeline workflow with: -- mode: batch -- story_key: {{story_key}} -- complexity_level: {{complexity}} - -**Step C: Reconcile Using Completion Artifacts (orchestrator does this directly)** - -After story-full-pipeline completes: - -**C1. Load Fixer completion artifact:** -```bash -FIXER_COMPLETION="docs/sprint-artifacts/completions/{{story_key}}-fixer.json" - -if [ ! -f "$FIXER_COMPLETION" ]; then - echo "❌ WARNING: No completion artifact, using fallback" - # Fallback to git diff if completion artifact missing -else - echo "βœ… Using completion artifact" -fi -``` - -Use Read tool on: `docs/sprint-artifacts/completions/{{story_key}}-fixer.json` - -**C2. Parse completion data:** -Extract from JSON: -- files_created and files_modified arrays -- git_commit hash -- quality_checks results -- tests counts -- fixes_applied list - -**C3. Read story file:** -Use Read tool: `docs/sprint-artifacts/{{story_key}}.md` - -**C4. Check off completed tasks:** -For each task: -- Match task to files in completion artifact -- If file was created/modified: check off task -- Use Edit tool: `"- [ ]"` β†’ `"- [x]"` - -**C5. Fill Dev Agent Record:** -Use Edit tool with data from completion.json: -```markdown -### Dev Agent Record -**Implementation Date:** {{timestamp from json}} -**Agent Model:** Claude Sonnet 4.5 (multi-agent pipeline) -**Git Commit:** {{git_commit from json}} - -**Files:** {{files_created + files_modified from json}} -**Tests:** {{tests.passing}}/{{tests.total}} passing ({{tests.coverage}}%) -**Issues Fixed:** {{issues_fixed.total}} issues -``` - -**C6. Verify updates:** -```bash -CHECKED=$(grep -c "^- \[x\]" "$STORY_FILE") -[ "$CHECKED" -gt 0 ] || { echo "❌ Zero tasks checked"; exit 1; } -echo "βœ… Reconciled: $CHECKED tasks" -``` - -**C7. Update sprint-status.yaml:** -Use Edit tool: `"{{story_key}}: ready-for-dev"` β†’ `"{{story_key}}: done"` - -**Step D: Next story or complete** -- If more stories: continue loop -- If complete: proceed to `summary` - - - -**Parallel Processing with Wave Pattern** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“¦ PARALLEL PROCESSING -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Wave Configuration:** -- Max concurrent: 3 agents -- Wait for wave completion before next wave - -**For each wave:** - -1. Spawn Task agents (up to 3 parallel): -``` -Task({ - subagent_type: "general-purpose", - description: "Implement {{story_key}}", - prompt: ` -Execute story-full-pipeline for story {{story_key}}. - - -@story-full-pipeline/workflow.md - - - -Story: [inline story content] -Complexity: {{complexity_level}} - - - -- [ ] All pipeline phases complete -- [ ] Git commit created -- [ ] Return ## AGENT COMPLETE with summary - -` -}) -``` - -2. Wait for all agents in wave to complete - -3. **Orchestrator reconciles each completed story:** - - Get git diff - - Check off tasks - - Fill Dev Agent Record - - Verify updates - - Update sprint-status - -4. Continue to next wave or summary - - - -**Display Batch Summary** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… BATCH COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Stories processed: {{total}} -Successful: {{success_count}} -Failed: {{fail_count}} - -## Results - -| Story | Status | Tasks | Commit | -|-------|--------|-------|--------| -| 17-10 | βœ… done | 8/8 | abc123 | -| 17-11 | βœ… done | 5/5 | def456 | - -## Next Steps -- Run /bmad:sprint-status to verify -- Review commits with git log -``` - - - - - -**Story file missing:** Skip with warning, continue to next. -**Pipeline fails:** Mark story as failed, continue to next. -**Reconciliation fails:** Fix with Edit tool, retry verification. -**All stories fail:** Report systemic issue, halt batch. - - - -- [ ] All selected stories processed -- [ ] Each story has checked tasks (count > 0) -- [ ] Each story has Dev Agent Record filled -- [ ] Sprint status updated for all stories -- [ ] Summary displayed with results - diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml b/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml deleted file mode 100644 index b93b2b9e..00000000 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml +++ /dev/null @@ -1,97 +0,0 @@ -name: batch-super-dev -description: "Interactive batch selector for super-dev-pipeline with complexity-based routing. Micro stories get lightweight path, standard stories get full pipeline, complex stories get enhanced validation." -author: "BMad" -version: "1.3.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{config_source}:sprint_artifacts" -communication_language: "{config_source}:communication_language" -date: system-generated - -# Workflow paths -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/batch-super-dev" -instructions: "{installed_path}/instructions.md" - -# State management -sprint_status: "{sprint_artifacts}/sprint-status.yaml" -batch_log: "{sprint_artifacts}/batch-super-dev-{date}.log" - -# Variables -filter_by_epic: "" # Optional: Filter stories by epic number (e.g., "3" for only Epic 3 stories) -max_stories: 20 # Safety limit - won't process more than this in one batch -pause_between_stories: 5 # Seconds to pause between stories (allows monitoring, prevents rate limits) - -# Super-dev-pipeline invocation settings -super_dev_settings: - mode: "batch" # Always use batch mode for autonomous execution - workflow_path: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-pipeline" - -# Story validation settings (NEW in v1.2.0) -validation: - enabled: true # Validate story files before processing - auto_create_missing: false # If true, auto-create without prompting (use with caution) - auto_regenerate_invalid: false # If true, auto-regenerate without prompting (use with caution) - min_sections: 12 # BMAD format requires all 12 sections - min_current_state_words: 100 # Current State must have substantial content - require_gap_analysis: true # Current State must have βœ…/❌ markers - backup_before_regenerate: true # Create .backup file before regenerating - -# Story complexity scoring (NEW in v1.3.0) -# Routes stories to appropriate pipeline based on complexity -complexity: - enabled: true - thresholds: - micro: # Lightweight path: skip gap analysis + code review - max_tasks: 3 - max_files: 5 - risk_keywords: [] # No high-risk keywords allowed - standard: # Normal path: full pipeline - max_tasks: 15 - max_files: 30 - risk_keywords: ["api", "service", "component", "feature"] - complex: # Enhanced path: extra validation, consider splitting - min_tasks: 16 - risk_keywords: ["auth", "security", "migration", "database", "payment", "encryption"] - - # Risk keyword scoring (adds to complexity) - risk_weights: - high: ["auth", "security", "payment", "encryption", "migration", "database", "schema"] - medium: ["api", "integration", "external", "third-party", "cache"] - low: ["ui", "style", "config", "docs", "test"] - - # Keyword matching configuration (defines how risk keywords are detected) - keyword_matching: - case_sensitive: false # "AUTH" matches "auth" - require_word_boundaries: true # "auth" won't match "author" - match_strategy: "exact" # exact word match required (no stemming) - scan_locations: - - story_title - - task_descriptions - - subtask_descriptions - # Keyword variants (synonyms that map to canonical forms) - variants: - auth: ["authentication", "authorize", "authorization", "authz", "authn"] - database: ["db", "databases", "datastore"] - payment: ["payments", "pay", "billing", "checkout"] - migration: ["migrations", "migrate"] - security: ["secure", "security"] - encryption: ["encrypt", "encrypted", "cipher"] - - # Task counting rules - task_counting: - method: "top_level_only" # Only count [ ] at task level, not subtasks - # Options: "top_level_only", "include_subtasks", "weighted" - # Example: - # - [ ] Parent task <- counts as 1 - # - [ ] Subtask 1 <- ignored - # - [ ] Subtask 2 <- ignored - -# Execution settings -execution: - continue_on_failure: true # Keep processing remaining stories if one fails - display_progress: true # Show running summary after each story - save_state: true # Save progress to resume if interrupted - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md deleted file mode 100644 index b40462b5..00000000 --- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md +++ /dev/null @@ -1,286 +0,0 @@ -# Create Story with Gap Analysis v3.0 - Verified Story Generation - - -Regenerate story with VERIFIED codebase gap analysis. -Uses Glob/Read tools to determine what actually exists vs what's missing. -Checkboxes reflect reality, not guesses. - - - -**Truth from Codebase, Not Assumptions** - -1. Scan codebase for actual implementations -2. Verify files exist, check for stubs/TODOs -3. Check test coverage -4. Generate story with checkboxes matching reality -5. No guessingβ€”every checkbox has evidence - - - -name: create-story-with-gap-analysis -version: 3.0.0 - -verification_status: - verified: "[x]" # File exists, real implementation, tests exist - partial: "[~]" # File exists but stub/TODO or no tests - missing: "[ ]" # File does not exist - -defaults: - update_sprint_status: true - create_report: false - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Identify story and load context** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” STORY REGENERATION WITH GAP ANALYSIS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Ask user for story:** -``` -Which story should I regenerate with gap analysis? - -Provide: -- Story number (e.g., "1.9" or "1-9") -- OR story filename - -Your choice: -``` - -**Parse input:** -- Extract epic_num, story_num -- Locate story file - -**Load existing story:** -```bash -Read: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md -``` - -Extract: -- Story title -- User story (As a... I want... So that...) -- Acceptance criteria -- Tasks -- Dev Notes - -**Load epic context:** -```bash -Read: {{planning_artifacts}}/epics.md -``` - -Extract: -- Epic business objectives -- Technical constraints -- Dependencies - -**Determine target directories:** -From story title/requirements, identify which directories to scan. - -``` -βœ… Story Context Loaded - -Story: {{epic_num}}.{{story_num}} - {{title}} -Target directories: -{{#each directories}} - - {{this}} -{{/each}} - -[C] Continue to Codebase Scan -``` - - - -**VERIFY what code actually exists** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” CODEBASE SCAN -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**For each target directory:** - -1. **List all source files:** - ```bash - Glob: {{target_dir}}/src/**/*.ts - Glob: {{target_dir}}/src/**/*.tsx - ``` - -2. **Check for specific required components:** - Based on story ACs, check if required files exist: - ```bash - Glob: {{target_dir}}/src/auth/controllers/*oauth*.ts - # Result: βœ… EXISTS or ❌ MISSING - ``` - -3. **Verify implementation depth:** - For files that exist, check quality: - ```bash - Read: {{file}} - - # Check for stubs - Grep: "MOCK|TODO|FIXME|Not implemented" {{file}} - # If found: ⚠️ STUB - ``` - -4. **Check dependencies:** - ```bash - Read: {{target_dir}}/package.json - - # Required: axios - Found? βœ…/❌ - # Required: @aws-sdk/client-secrets-manager - Found? βœ…/❌ - ``` - -5. **Check test coverage:** - ```bash - Glob: {{target_dir}}/src/**/*.spec.ts - Glob: {{target_dir}}/test/**/*.test.ts - ``` - - - -**Create verified gap analysis** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š GAP ANALYSIS RESULTS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -βœ… IMPLEMENTED (Verified): -{{#each implemented}} -{{@index}}. **{{name}}** - - File: {{file}} βœ… EXISTS - - Status: {{status}} - - Tests: {{test_count}} tests -{{/each}} - -❌ MISSING (Verified): -{{#each missing}} -{{@index}}. **{{name}}** - - Expected: {{expected_file}} ❌ NOT FOUND - - Needed for: {{requirement}} -{{/each}} - -⚠️ PARTIAL (Stub/Incomplete): -{{#each partial}} -{{@index}}. **{{name}}** - - File: {{file}} βœ… EXISTS - - Issue: {{issue}} -{{/each}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Generate story with verified checkboxes** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“ GENERATING STORY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Use story template with: -- `[x]` for VERIFIED items (evidence: file exists, not stub, has tests) -- `[~]` for PARTIAL items (evidence: file exists but stub/no tests) -- `[ ]` for MISSING items (evidence: file not found) - -**Write story file:** -```bash -Write: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md -``` - -**Validate generated story:** -```bash -# Check 7 sections exist -grep "^## " {{story_file}} | wc -l -# Should be 7 - -# Check gap analysis section exists -grep "Gap Analysis" {{story_file}} -``` - - - -**Update sprint-status.yaml** - -```bash -Read: {{sprint_status}} - -# Update story status to "ready-for-dev" if was "backlog" -# Preserve comments and structure - -Write: {{sprint_status}} -``` - - - -**Report completion** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… STORY REGENERATED WITH GAP ANALYSIS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{epic_num}}.{{story_num}} - {{title}} -File: {{story_file}} -Sections: 7/7 βœ… - -Gap Analysis Summary: -- βœ… {{implemented_count}} components VERIFIED complete -- ❌ {{missing_count}} components VERIFIED missing -- ⚠️ {{partial_count}} components PARTIAL (stub/no tests) - -Checkboxes reflect VERIFIED codebase state. - -Next Steps: -1. Review story for accuracy -2. Use /dev-story to implement missing components -3. Story provides complete context for implementation - -[N] Regenerate next story -[Q] Quit -[R] Review generated story -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**If [N]:** Loop back to initialize with next story. -**If [R]:** Display story content, then show menu. - - - - - -```bash -# Regenerate specific story -/create-story-with-gap-analysis -> Which story? 1.9 - -# With explicit story file -/create-story-with-gap-analysis story_file=docs/sprint-artifacts/story-1.9.md -``` - - - -**Story not found:** HALT with clear error. -**Target directory not found:** Warn, scan available directories. -**Glob/Read fails:** Log warning, count as MISSING. -**Write fails:** Report error, display generated content. - - - -- [ ] Codebase scanned for all story requirements -- [ ] Gap analysis generated with evidence -- [ ] Story written with verified checkboxes -- [ ] 7 sections present -- [ ] Sprint status updated (if enabled) - diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml deleted file mode 100644 index d6297e95..00000000 --- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml +++ /dev/null @@ -1,32 +0,0 @@ -name: create-story-with-gap-analysis -description: "Create/regenerate story with SYSTEMATIC codebase gap analysis using verified file scanning (Glob/Read tools)" -author: "Jonah Schulte" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -output_folder: "{implementation_artifacts}" -story_dir: "{implementation_artifacts}" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story-with-gap-analysis" -instructions: "{installed_path}/workflow.md" - -# Variables -variables: - sprint_status: "{implementation_artifacts}/sprint-status.yaml" - epics_file: "{planning_artifacts}/epics.md" - prd_file: "{planning_artifacts}/prd.md" - -# Project context -project_context: "**/project-context.md" - -default_output_file: "{story_dir}/{{story_key}}.md" - -standalone: true - -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.md b/src/modules/bmm/workflows/4-implementation/create-story/workflow.md deleted file mode 100644 index f581efbe..00000000 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.md +++ /dev/null @@ -1,270 +0,0 @@ -# Create Story v3.0 - Greenfield Story Generation - - -Generate story for net-new features with zero existing implementation. -No codebase scanningβ€”all tasks assumed incomplete (greenfield). -Focused on clear requirements and implementation guidance. - - - -**Fast Story Generation for New Features** - -1. Load PRD, epic, and architecture context -2. Generate clear user story with acceptance criteria -3. All tasks marked incomplete (greenfield assumption) -4. No codebase scanningβ€”saves time for net-new work -5. Ready for immediate implementation - - - -name: create-story -version: 3.0.0 - -task_status: - incomplete: "[ ]" # All tasks for greenfield stories - -defaults: - update_sprint_status: true - create_report: false - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Identify story and load context** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“ GREENFIELD STORY GENERATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Ask user for story:** -``` -Which story should I create? - -Provide: -- Story number (e.g., "1.9" or "1-9") -- OR epic number and story description - -Your choice: -``` - -**Parse input:** -- Extract epic_num, story_num -- Determine story file path - -**Load epic context:** -```bash -Read: {{planning_artifacts}}/epics.md -``` - -Extract: -- Epic business objectives -- Technical constraints -- Dependencies - -**Load architecture context (if exists):** -```bash -Read: {{planning_artifacts}}/architecture.md -``` - -Extract: -- Technical architecture patterns -- Technology stack -- Integration patterns - -**Load PRD context:** -```bash -Read: {{planning_artifacts}}/prd.md -``` - -Extract relevant sections: -- User personas -- Feature requirements -- Non-functional requirements - -``` -βœ… Context Loaded - -Story: {{epic_num}}.{{story_num}} -Epic: {{epic_title}} -Architecture: {{architecture_notes}} - -[C] Continue to Story Generation -``` - - - -**Generate greenfield story** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“ GENERATING STORY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Story structure:** -All tasks marked `[ ]` (incomplete) since this is greenfield. - -**Write story file:** -```bash -Write: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md -``` - -**Story template:** -```markdown -# Story {{epic_num}}.{{story_num}}: {{title}} - -## πŸ“Š Metadata -- **Epic**: {{epic_num}} - {{epic_title}} -- **Priority**: {{priority}} -- **Estimate**: {{estimate}} -- **Dependencies**: {{dependencies}} -- **Created**: {{date}} - -## πŸ“– User Story -As a {{persona}} -I want {{capability}} -So that {{benefit}} - -## βœ… Acceptance Criteria -1. **{{criterion_1}}** - - {{detail_1a}} - - {{detail_1b}} - -2. **{{criterion_2}}** - - {{detail_2a}} - - {{detail_2b}} - -## πŸ”¨ Implementation Tasks -### Frontend -- [ ] {{frontend_task_1}} -- [ ] {{frontend_task_2}} - -### Backend -- [ ] {{backend_task_1}} -- [ ] {{backend_task_2}} - -### Testing -- [ ] {{testing_task_1}} -- [ ] {{testing_task_2}} - -## πŸ“‹ Technical Notes -### Architecture -{{architecture_guidance}} - -### Dependencies -{{dependency_notes}} - -### API Contracts -{{api_contract_notes}} - -## πŸ§ͺ Testing Strategy -### Unit Tests -{{unit_test_strategy}} - -### Integration Tests -{{integration_test_strategy}} - -### E2E Tests -{{e2e_test_strategy}} - -## 🎯 Definition of Done -- [ ] All acceptance criteria met -- [ ] Unit tests written and passing -- [ ] Integration tests written and passing -- [ ] Code reviewed and approved -- [ ] Documentation updated -- [ ] Deployed to staging environment -- [ ] Product owner acceptance - -## πŸ“ Dev Notes -{{additional_context}} -``` - -**Validate generated story:** -```bash -# Check 7 sections exist -grep "^## " {{story_file}} | wc -l -# Should be 7 or more - -# Check metadata section exists -grep "## πŸ“Š Metadata" {{story_file}} -``` - - - -**Update sprint-status.yaml** - -```bash -Read: {{sprint_status}} - -# Add story to sprint status with "ready-for-dev" status -# Preserve comments and structure - -Write: {{sprint_status}} -``` - - - -**Report completion** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… GREENFIELD STORY CREATED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{epic_num}}.{{story_num}} - {{title}} -File: {{story_file}} -Sections: 7/7 βœ… - -All tasks marked incomplete (greenfield). -Ready for implementation. - -Next Steps: -1. Review story for accuracy -2. Use /story-dev-only or /story-full-pipeline to implement -3. All context loaded and ready - -[N] Create next story -[Q] Quit -[R] Review generated story -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**If [N]:** Loop back to initialize with next story. -**If [R]:** Display story content, then show menu. - - - - - -```bash -# Create new greenfield story -/create-story -> Which story? 20.1 - -# With explicit story number -/create-story epic=20 story=1 -``` - - - -**Epic not found:** HALT with clear error. -**PRD not found:** Warn but continue with available context. -**Architecture doc not found:** Warn but continue with epic context. -**Write fails:** Report error, display generated content. - - - -- [ ] Epic and PRD context loaded -- [ ] Story generated with all 7+ sections -- [ ] All tasks marked incomplete (greenfield) -- [ ] Story written to correct path -- [ ] Sprint status updated (if enabled) - diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml deleted file mode 100644 index 5cce162d..00000000 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: create-story -description: "Create story for greenfield features with zero existing implementation (no codebase scanning)" -author: "Jonah Schulte" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -output_folder: "{implementation_artifacts}" -story_dir: "{implementation_artifacts}" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story" -instructions: "{installed_path}/workflow.md" - -# Variables -variables: - sprint_status: "{implementation_artifacts}/sprint-status.yaml" - epics_file: "{planning_artifacts}/epics.md" - prd_file: "{planning_artifacts}/prd.md" - architecture_file: "{planning_artifacts}/architecture.md" - -# Project context -project_context: "**/project-context.md" - -default_output_file: "{story_dir}/{{story_key}}.md" - -standalone: true - -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.md b/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.md deleted file mode 100644 index 61132bf3..00000000 --- a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.md +++ /dev/null @@ -1,278 +0,0 @@ -# Detect Ghost Features v3.0 - Reverse Gap Analysis - - -Find undocumented code (components, APIs, services, tables) that exist in codebase -but aren't tracked in any story. "Who you gonna call?" - Ghost Features. - - - -**Reverse Gap Analysis** - -Normal gap analysis: story says X should exist β†’ does it? -Reverse gap analysis: X exists in code β†’ is it documented? - -Undocumented features become maintenance nightmares. -Find them, create backfill stories, restore traceability. - - - -name: detect-ghost-features -version: 3.0.0 - -scan_scope: - epic: "Filter to specific epic number" - sprint: "All stories in sprint-status.yaml" - codebase: "All stories in sprint-artifacts" - -scan_for: - components: true - api_endpoints: true - database_tables: true - services: true - -severity: - critical: "APIs, auth, payment (undocumented = high risk)" - high: "Components, DB tables, services" - medium: "Utilities, helpers" - low: "Config files, constants" - -defaults: - create_backfill_stories: false - auto_create: false - add_to_sprint_status: true - create_report: true - - - -@patterns/hospital-grade.md - - - - - -**Load documented artifacts from stories** - -Based on scan_scope (epic/sprint/codebase): - -```bash -# Get all story files -STORIES=$(ls docs/sprint-artifacts/*.md | grep -v "epic-") -``` - -For each story: -1. Read story file -2. Extract documented artifacts: - - File List (all paths mentioned) - - Tasks (file/component/service names) - - ACs (features/functionality) -3. Store in: documented_artifacts[story_key] - - - -**Scan codebase for actual implementations** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ‘» SCANNING FOR GHOST FEATURES -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Components:** -```bash -# Find React/Vue/Angular components -find . -name "*.tsx" -o -name "*.jsx" | xargs grep -l "export.*function\|export.*const" -``` - -**API Endpoints:** -```bash -# Find Next.js/Express routes -find . -path "*/api/*" -name "*.ts" -grep -r "export.*GET\|export.*POST\|router\.\(get\|post\)" . -``` - -**Database Tables:** -```bash -# Find Prisma/TypeORM models -grep -r "^model " prisma/schema.prisma -find . -name "*.entity.ts" -``` - -**Services:** -```bash -find . -name "*.service.ts" -o -name "*Service.ts" -``` - - - -**Compare codebase artifacts to story documentation** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” CROSS-REFERENCING -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -For each codebase artifact: -1. Search all stories for mentions of: - - Component/file name - - File path - - Feature description -2. If NO stories mention it β†’ ORPHAN (ghost feature) -3. If stories mention it β†’ Documented - -Track orphans with: -- type (component/api/db/service) -- name and path -- severity -- inferred purpose - - - -**Analyze and prioritize ghost features** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ‘» GHOST FEATURES DETECTED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Total Orphans: {{count}} - -By Severity: -- πŸ”΄ CRITICAL: {{critical}} (APIs, security) -- 🟠 HIGH: {{high}} (Components, DB, services) -- 🟑 MEDIUM: {{medium}} (Utilities) -- 🟒 LOW: {{low}} (Config) - -By Type: -- Components: {{components}} -- API Endpoints: {{apis}} -- Database Tables: {{tables}} -- Services: {{services}} - -Documentation Coverage: {{documented_pct}}% -Orphan Rate: {{orphan_pct}}% - -{{#if orphan_pct > 20}} -⚠️ HIGH ORPHAN RATE - Over 20% undocumented! -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Generate stories for orphaned features** - -For each orphan (prioritized by severity): - -1. **Analyze orphan** - Read implementation, find tests, understand purpose -2. **Generate story draft:** - -```markdown -# Story: Document existing {{name}} - -**Type:** BACKFILL (documenting existing code) - -## Business Context -{{inferred_from_code}} - -## Current State -βœ… Implementation EXISTS: {{file}} -{{#if has_tests}}βœ… Tests exist{{else}}❌ No tests{{/if}} - -## Acceptance Criteria -{{inferred_acs}} - -## Tasks -- [x] {{name}} implementation (ALREADY EXISTS) -{{#if !has_tests}}- [ ] Add tests{{/if}} -- [ ] Verify functionality -- [ ] Assign to epic -``` - -3. **Ask user** (unless auto_create): - - [Y] Create story - - [A] Auto-create all remaining - - [S] Skip this orphan - - [H] Halt - -4. **Write story file:** `docs/sprint-artifacts/backfill-{{type}}-{{name}}.md` - -5. **Update sprint-status.yaml** (if enabled) - - - -**Recommend epic assignment** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š BACKFILL ORGANIZATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Options: -[A] Create Epic-Backfill (recommended) - - Single epic for all backfill stories - - Clear separation from feature work - -[B] Distribute to existing epics - - Add each to its logical epic - -[C] Leave in backlog - - Manual assignment later -``` - - - -**Write comprehensive ghost features report** - -Write to: `docs/sprint-artifacts/ghost-features-report-{{timestamp}}.md` - -Include: -- Executive summary -- Full orphan list by severity -- Backfill stories created -- Recommendations -- Scan methodology - - - -**Display results and next steps** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… GHOST FEATURE DETECTION COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Orphans Found: {{orphan_count}} -Backfill Stories Created: {{backfill_count}} -Documentation Coverage: {{documented_pct}}% - -{{#if orphan_count == 0}} -βœ… All code is documented in stories! -{{else}} -Next Steps: -1. Review backfill stories for accuracy -2. Assign to epics -3. Add tests/docs for orphans -4. Run revalidation to verify -{{/if}} - -πŸ’‘ Pro Tip: Run this periodically to catch - vibe-coded features before they become - maintenance nightmares. -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -**No stories found:** Check scan_scope, verify sprint-artifacts exists. -**Scan fails:** Report which scan type failed, continue others. -**Backfill creation fails:** Skip, continue to next orphan. - - - -- [ ] All artifact types scanned -- [ ] Cross-reference completed -- [ ] Orphans categorized by severity -- [ ] Backfill stories created (if enabled) -- [ ] Report generated - diff --git a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.yaml b/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.yaml deleted file mode 100644 index e5c9f6cb..00000000 --- a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/workflow.yaml +++ /dev/null @@ -1,56 +0,0 @@ -name: detect-ghost-features -description: "Reverse gap analysis: Find functionality in codebase that has no corresponding story (vibe-coded or undocumented features). Propose backfill stories." -author: "BMad" -version: "1.0.0" # Who you gonna call? GHOST-FEATURE-BUSTERS! πŸ‘» - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{output_folder}/sprint-artifacts" -sprint_status: "{output_folder}/sprint-status.yaml" - -# Input parameters -epic_number: "{epic_number}" # Optional: Limit to specific epic (e.g., "2") -scan_scope: "sprint" # "sprint" | "epic" | "codebase" -create_backfill_stories: true # Propose backfill stories for orphans - -# Detection settings -detection: - scan_for: - components: true # React/Vue/Angular components - api_endpoints: true # Routes, controllers, handlers - database_tables: true # Migrations, schema - services: true # Services, modules, utilities - models: true # Data models, entities - ui_pages: true # Pages, screens, views - - ignore_patterns: - - "**/node_modules/**" - - "**/dist/**" - - "**/build/**" - - "**/*.test.*" - - "**/*.spec.*" - - "**/migrations/**" # Migrations are referenced collectively, not per-story - - # What counts as "documented"? - documented_if: - mentioned_in_file_list: true # Story File List mentions it - mentioned_in_tasks: true # Task description mentions it - mentioned_in_acs: true # AC mentions the feature - file_committed_in_story_commit: true # Git history shows it in story commit - -# Backfill story settings -backfill: - auto_create: false # Require confirmation before creating each - add_to_sprint_status: true # Add to sprint as "backlog" - mark_as_backfill: true # Add note: "Backfill story documenting existing code" - run_gap_analysis: false # Don't run gap (we know it exists) - estimate_effort: true # Estimate how complex the feature is - -# Output settings -output: - create_report: true # Generate orphaned-features-report.md - group_by_category: true # Group by component/api/db/etc - suggest_epic_assignment: true # Suggest which epic orphans belong to - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md deleted file mode 100644 index c672b0be..00000000 --- a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md +++ /dev/null @@ -1,246 +0,0 @@ -# Gap Analysis v3.0 - Verify Story Tasks Against Codebase - - -Validate story checkbox claims against actual codebase reality. -Find false positives (checked but not done) and false negatives (done but unchecked). -Interactive workflow with options to update, audit, or review. - - - -**Evidence-Based Verification** - -Checkboxes lie. Code doesn't. -- Search codebase for implementation evidence -- Check for stubs, TODOs, empty functions -- Verify tests exist for claimed features -- Report accuracy of story completion claims - - - -name: gap-analysis -version: 3.0.0 - -defaults: - auto_update: false - create_audit_report: true - strict_mode: false # If true, stubs count as incomplete - -output: - update_story: "Modify checkbox state to match reality" - audit_report: "Generate detailed gap analysis document" - no_changes: "Display results only" - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Load and parse story file** - -```bash -STORY_FILE="{{story_file}}" -[ -f "$STORY_FILE" ] || { echo "❌ story_file required"; exit 1; } -``` - -Use Read tool on story file. Extract: -- All `- [ ]` and `- [x]` items -- File references from Dev Agent Record -- Task descriptions with expected artifacts - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” GAP ANALYSIS: {{story_key}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Tasks: {{total_tasks}} -Currently checked: {{checked_count}} -``` - - - -**Verify each task against codebase** - -For each task item: - -1. **Extract artifacts** - File names, component names, function names -2. **Search codebase:** - ```bash - # Check file exists - Glob: {{expected_file}} - - # Check function/component exists - Grep: "{{function_or_component_name}}" - ``` - -3. **If file exists, check quality:** - ```bash - # Check for stubs - Grep: "TODO|FIXME|Not implemented|throw new Error" {{file}} - - # Check for tests - Glob: {{file_base}}.test.* OR {{file_base}}.spec.* - ``` - -4. **Determine status:** - - **VERIFIED:** File exists, not a stub, tests exist - - **PARTIAL:** File exists but stub/TODO or no tests - - **MISSING:** File does not exist - - - -**Compare claimed vs actual** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š GAP ANALYSIS RESULTS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Tasks analyzed: {{total}} - -By Status: -- βœ… Verified Complete: {{verified}} ({{verified_pct}}%) -- ⚠️ Partial: {{partial}} ({{partial_pct}}%) -- ❌ Missing: {{missing}} ({{missing_pct}}%) - -Accuracy Analysis: -- Checked & Verified: {{correct_checked}} -- Checked but MISSING: {{false_positives}} ← FALSE POSITIVES -- Unchecked but DONE: {{false_negatives}} ← FALSE NEGATIVES - -Checkbox Accuracy: {{accuracy}}% -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**If false positives found:** -``` -⚠️ FALSE POSITIVES DETECTED -The following tasks are marked done but code is missing: - -{{#each false_positives}} -- [ ] {{task}} β€” Expected: {{expected_file}} β€” ❌ NOT FOUND -{{/each}} -``` - - - -**Ask user how to proceed** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ OPTIONS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -[U] Update - Fix checkboxes to match reality -[A] Audit Report - Generate detailed report file -[N] No Changes - Display only (already done) -[R] Review Details - Show full evidence for each task - -Your choice: -``` - - - -**Update story file checkboxes** - -For false positives: -- Change `[x]` to `[ ]` for tasks with missing code - -For false negatives: -- Change `[ ]` to `[x]` for tasks with verified code - -Use Edit tool to make changes. - -``` -βœ… Story checkboxes updated -- {{fp_count}} false positives unchecked -- {{fn_count}} false negatives checked -- New completion: {{new_pct}}% -``` - - - -**Generate audit report** - -Write to: `{{story_dir}}/gap-analysis-{{story_key}}-{{timestamp}}.md` - -Include: -- Executive summary -- Detailed task-by-task evidence -- False positive/negative lists -- Recommendations - -``` -βœ… Audit report generated: {{report_path}} -``` - - - -**Show detailed evidence** - -For each task: -``` -Task: {{task_text}} -Checkbox: {{checked_state}} -Evidence: - - File: {{file}} - {{exists ? "βœ… EXISTS" : "❌ MISSING"}} - {{#if exists}} - - Stub check: {{is_stub ? "⚠️ STUB DETECTED" : "βœ… Real implementation"}} - - Tests: {{has_tests ? "βœ… Tests exist" : "❌ No tests"}} - {{/if}} -Verdict: {{status}} -``` - -After review, return to options menu. - - - -**Display completion** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… GAP ANALYSIS COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{story_key}} -Verified Completion: {{verified_pct}}% -Checkbox Accuracy: {{accuracy}}% - -{{#if updated}} -βœ… Checkboxes updated to match reality -{{/if}} - -{{#if report_generated}} -πŸ“„ Report: {{report_path}} -{{/if}} - -{{#if false_positives > 0}} -⚠️ {{false_positives}} tasks need implementation work -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -```bash -# Quick gap analysis of single story -/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md - -# With auto-update enabled -/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md auto_update=true -``` - - - -**Story file not found:** HALT with clear error. -**Search fails:** Log warning, count as MISSING. -**Edit fails:** Report error, suggest manual update. - - - -- [ ] All tasks verified against codebase -- [ ] False positives/negatives identified -- [ ] Accuracy metrics calculated -- [ ] User choice executed (update/audit/review) - diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml deleted file mode 100644 index 07eea0a2..00000000 --- a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml +++ /dev/null @@ -1,23 +0,0 @@ -name: gap-analysis -description: "Validate story tasks against actual codebase - audit completed stories or validate before development" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -implementation_artifacts: "{config_source}:implementation_artifacts" -story_dir: "{implementation_artifacts}" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/gap-analysis" -instructions: "{installed_path}/workflow.md" - -# Variables -story_file: "" # User provides story file path or auto-discover -sprint_status: "{implementation_artifacts}/sprint-status.yaml" -project_context: "**/project-context.md" - -standalone: true - -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/migrate-to-github/RELIABILITY.md b/src/modules/bmm/workflows/4-implementation/migrate-to-github/RELIABILITY.md deleted file mode 100644 index 00a5bdb9..00000000 --- a/src/modules/bmm/workflows/4-implementation/migrate-to-github/RELIABILITY.md +++ /dev/null @@ -1,743 +0,0 @@ -# Migration Reliability Guarantees - -**Purpose:** Document how this migration tool ensures 100% reliability and data integrity. - ---- - -## Core Guarantees - -### 1. **Idempotent Operations** βœ… - -**Guarantee:** Running migration multiple times produces the same result as running once. - -**How:** -```javascript -// Before creating issue, check if it exists -const existing = await searchIssue(`label:story:${storyKey}`); - -if (existing) { - if (update_existing) { - // Update existing issue (safe) - await updateIssue(existing.number, data); - } else { - // Skip (already migrated) - skip(storyKey); - } -} else { - // Create new issue - await createIssue(data); -} -``` - -**Test:** -```bash -# Run migration twice -/migrate-to-github mode=execute -/migrate-to-github mode=execute - -# Result: Same issues, no duplicates -# Second run: "47 stories already migrated, 0 created" -``` - ---- - -### 2. **Atomic Per-Story Operations** βœ… - -**Guarantee:** Each story either fully migrates or fully rolls back. No partial states. - -**How:** -```javascript -async function migrateStory(storyKey) { - const transaction = { - story_key: storyKey, - operations: [], - rollback_actions: [] - }; - - try { - // Create issue - const issue = await createIssue(data); - transaction.operations.push({ type: 'create', issue_number: issue.number }); - transaction.rollback_actions.push(() => closeIssue(issue.number)); - - // Add labels - await addLabels(issue.number, labels); - transaction.operations.push({ type: 'labels' }); - - // Set milestone - await setMilestone(issue.number, milestone); - transaction.operations.push({ type: 'milestone' }); - - // Verify all operations succeeded - await verifyIssue(issue.number); - - // Success - commit transaction - return { success: true, issue_number: issue.number }; - - } catch (error) { - // Rollback all operations - for (const rollback of transaction.rollback_actions.reverse()) { - await rollback(); - } - - return { success: false, error, rolled_back: true }; - } -} -``` - ---- - -### 3. **Comprehensive Verification** βœ… - -**Guarantee:** Every write is verified by reading back the data. - -**How:** -```javascript -// Write-Verify pattern -async function createIssueVerified(data) { - // 1. Create - const created = await mcp__github__issue_write({ ...data }); - const issue_number = created.number; - - // 2. Wait for GitHub eventual consistency - await sleep(1000); - - // 3. Read back - const verification = await mcp__github__issue_read({ - issue_number: issue_number - }); - - // 4. Verify fields - assert(verification.title === data.title, 'Title mismatch'); - assert(verification.labels.includes(data.labels[0]), 'Label missing'); - assert(verification.body.includes(data.body.substring(0, 50)), 'Body mismatch'); - - // 5. Return verified issue - return { verified: true, issue_number }; -} -``` - -**Detection time:** -- Write succeeds but data wrong: **Detected immediately** (1s after write) -- Write fails silently: **Detected immediately** (read-back fails) -- Partial write: **Detected immediately** (field mismatch) - ---- - -### 4. **Crash-Safe State Tracking** βœ… - -**Guarantee:** If migration crashes/halts, can resume from exactly where it stopped. - -**How:** -```yaml -# migration-state.yaml (updated after EACH story) -started_at: 2026-01-07T15:30:00Z -mode: execute -github_owner: jschulte -github_repo: myproject -total_stories: 47 -last_completed: "2-15-profile-edit" # Story that just finished -stories_migrated: - - story_key: "2-1-login" - issue_number: 101 - timestamp: 2026-01-07T15:30:15Z - - story_key: "2-2-signup" - issue_number: 102 - timestamp: 2026-01-07T15:30:32Z - # ... 13 more - - story_key: "2-15-profile-edit" - issue_number: 115 - timestamp: 2026-01-07T15:35:18Z - # CRASH HAPPENS HERE -``` - -**Resume:** -```bash -# After crash, re-run migration -/migrate-to-github mode=execute - -β†’ Detects state file -β†’ "Previous migration detected - 15 stories already migrated" -β†’ "Resume from story 2-16-password-reset? (yes)" -β†’ Continues from story 16, skips 1-15 -``` - -**State file is atomic:** -- Written after EACH story (not at end) -- Uses atomic write (tmp file + rename) -- Never corrupted even if process killed mid-write - ---- - -### 5. **Exponential Backoff Retry** βœ… - -**Guarantee:** Transient failures (network blips, GitHub 503s) don't fail migration. - -**How:** -```javascript -async function retryWithBackoff(operation, config) { - const backoffs = config.retry_backoff_ms; // [1000, 3000, 9000] - - for (let attempt = 0; attempt < backoffs.length; attempt++) { - try { - return await operation(); - } catch (error) { - if (attempt < backoffs.length - 1) { - console.warn(`Retry ${attempt + 1} after ${backoffs[attempt]}ms`); - await sleep(backoffs[attempt]); - } else { - // All retries exhausted - throw error; - } - } - } -} -``` - -**Example:** -``` -Story 2-5 migration: - Attempt 1: GitHub 503 Service Unavailable - β†’ Wait 1s, retry - Attempt 2: Network timeout - β†’ Wait 3s, retry - Attempt 3: Success βœ… -``` - ---- - -### 6. **Rollback Manifest** βœ… - -**Guarantee:** Can undo migration if something goes wrong. - -**How:** -```yaml -# migration-rollback-2026-01-07T15-30-00.yaml -created_at: 2026-01-07T15:30:00Z -github_owner: jschulte -github_repo: myproject -migration_mode: execute - -created_issues: - - story_key: "2-1-login" - issue_number: 101 - created_at: 2026-01-07T15:30:15Z - title: "Story 2-1: User Login Flow" - url: "https://github.com/jschulte/myproject/issues/101" - - - story_key: "2-2-signup" - issue_number: 102 - created_at: 2026-01-07T15:30:32Z - title: "Story 2-2: User Registration" - url: "https://github.com/jschulte/myproject/issues/102" - - # ... all created issues tracked - -rollback_command: | - /migrate-to-github mode=rollback manifest=migration-rollback-2026-01-07T15-30-00.yaml -``` - -**Rollback execution:** -- Closes all created issues -- Adds "migrated:rolled-back" label -- Adds comment explaining why closed -- Preserves issues (can reopen if needed) - ---- - -### 7. **Dry-Run Mode** βœ… - -**Guarantee:** See exactly what will happen before it happens. - -**How:** -```javascript -if (mode === 'dry-run') { - // NO writes to GitHub - only reads - for (const story of stories) { - const existing = await searchIssue(`story:${story.key}`); - - if (existing) { - console.log(`Would UPDATE: Issue #${existing.number}`); - } else { - console.log(`Would CREATE: New issue for ${story.key}`); - console.log(` Title: ${generateTitle(story)}`); - console.log(` Labels: ${generateLabels(story)}`); - } - } - - // Show summary - console.log(` -Total: ${stories.length} -Would create: ${wouldCreate.length} -Would update: ${wouldUpdate.length} -Would skip: ${wouldSkip.length} - `); - - // Exit without doing anything - process.exit(0); -} -``` - -**Usage:** -```bash -# Always run dry-run first -/migrate-to-github mode=dry-run - -# Review output, then execute -/migrate-to-github mode=execute -``` - ---- - -### 8. **Halt on Critical Error** βœ… - -**Guarantee:** Never continue with corrupted/incomplete state. - -**How:** -```javascript -try { - await createIssue(storyData); -} catch (error) { - if (isCriticalError(error)) { - // Critical: GitHub API returned 401/403/5xx - console.error('CRITICAL ERROR: Cannot continue safely'); - console.error(`Story ${storyKey} failed: ${error}`); - - // Save current state - await saveState(migrationState); - - // Create recovery instructions - console.log(` -Recovery options: -1. Fix error: ${error.message} -2. Resume migration: /migrate-to-github mode=execute (will skip completed stories) -3. Rollback: /migrate-to-github mode=rollback - `); - - // HALT - do not continue - process.exit(1); - } else { - // Non-critical: Individual story failed but can continue - console.warn(`Story ${storyKey} failed (non-critical): ${error}`); - failedStories.push({ storyKey, error }); - // Continue with next story - } -} -``` - ---- - -## Testing Reliability - -### Test Suite - -```javascript -describe('Migration Reliability', () => { - - it('is idempotent - can run twice safely', async () => { - await migrate({ mode: 'execute' }); - const firstRun = getCreatedIssues(); - - await migrate({ mode: 'execute' }); // Run again - const secondRun = getCreatedIssues(); - - expect(secondRun).toEqual(firstRun); // Same issues, no duplicates - }); - - it('is atomic - failed story does not create partial issue', async () => { - mockGitHub.createIssue.resolvesOnce(); // Create succeeds - mockGitHub.addLabels.rejects(); // But adding labels fails - - await migrate({ mode: 'execute' }); - - const issues = await searchAllIssues(); - const partialIssues = issues.filter(i => !i.labels.includes('story:')); - - expect(partialIssues).toHaveLength(0); // No partial issues - }); - - it('verifies all writes by reading back', async () => { - mockGitHub.createIssue.resolves({ number: 101 }); - mockGitHub.readIssue.resolves({ title: 'WRONG TITLE' }); // Verification fails - - await expect(migrate({ mode: 'execute' })) - .rejects.toThrow('Write verification failed'); - }); - - it('can resume after crash', async () => { - // Migrate 5 stories - await migrate({ stories: stories.slice(0, 5) }); - - // Simulate crash (don't await) - const promise = migrate({ stories: stories.slice(5, 10) }); - await sleep(2000); - process.kill(); // Crash mid-migration - - // Resume - const resumed = await migrate({ mode: 'execute' }); - - expect(resumed.resumedFrom).toBe('2-5-story'); - expect(resumed.skipped).toBe(5); // Skipped already-migrated - }); - - it('creates rollback manifest', async () => { - await migrate({ mode: 'execute' }); - - const manifest = fs.readFileSync('migration-rollback-*.yaml'); - expect(manifest.created_issues).toHaveLength(47); - expect(manifest.created_issues[0]).toHaveProperty('issue_number'); - }); - - it('can rollback migration', async () => { - await migrate({ mode: 'execute' }); - const issuesBefore = await countIssues(); - - await migrate({ mode: 'rollback' }); - const issuesAfter = await countIssues({ state: 'open' }); - - expect(issuesAfter).toBeLessThan(issuesBefore); - // Rolled-back issues are closed, not deleted - }); - - it('handles rate limit gracefully', async () => { - mockGitHub.createIssue.rejects({ status: 429, message: 'Rate limit exceeded' }); - - const result = await migrate({ mode: 'execute', halt_on_critical_error: false }); - - expect(result.rateLimitErrors).toBeGreaterThan(0); - expect(result.savedState).toBeTruthy(); // State saved before halting - }); -}); -``` - ---- - -## Failure Recovery Procedures - -### Scenario 1: Migration Fails Halfway - -```bash -# Migration was running, crashed/halted at story 15/47 - -# Check state file -cat _bmad-output/migration-state.yaml -# Shows: last_completed: "2-15-profile" - -# Resume migration -/migrate-to-github mode=execute - -β†’ "Previous migration detected" -β†’ "15 stories already migrated" -β†’ "Resume from story 2-16? (yes)" -β†’ Continues from story 16-47 -β†’ Creates 32 new issues -β†’ Final: 47 total migrated βœ… -``` - -### Scenario 2: Created Issues but Verification Failed - -```bash -# Migration created issues but verification warnings - -# Run verify mode -/migrate-to-github mode=verify - -β†’ Checks all 47 stories -β†’ Reads each issue from GitHub -β†’ Compares to local files -β†’ Reports: - "43 verified correct βœ…" - "4 have warnings ⚠️" - - Story 2-5: Label missing "complexity:standard" - - Story 2-10: Title doesn't match local file - - Story 2-18: Milestone not set - - Story 2-23: Acceptance Criteria count mismatch - -# Fix issues -/migrate-to-github mode=execute update_existing=true filter_by_status=warning - -β†’ Re-migrates only the 4 with warnings -β†’ Verification: "4/4 now verified correct βœ…" -``` - -### Scenario 3: Wrong Repository - Need to Rollback - -```bash -# Oops - migrated to wrong repo! - -# Check what was created -cat _bmad-output/migration-rollback-*.yaml -# Shows: 47 issues created in wrong-repo - -# Rollback -/migrate-to-github mode=rollback - -β†’ "Rollback manifest found: 47 issues" -β†’ Type "DELETE ALL ISSUES" to confirm -β†’ Closes all 47 issues -β†’ Adds "migrated:rolled-back" label -β†’ "Rollback complete βœ…" - -# Now migrate to correct repo -/migrate-to-github mode=execute github_owner=jschulte github_repo=correct-repo -``` - -### Scenario 4: Network Failure Mid-Migration - -```bash -# Migration running, network drops at story 23/47 - -# Automatic behavior: -β†’ Story 23 fails to create (network timeout) -β†’ Retry #1 after 1s: Still fails -β†’ Retry #2 after 3s: Still fails -β†’ Retry #3 after 9s: Still fails -β†’ "CRITICAL: Cannot create issue for story 2-23 after 3 retries" -β†’ Saves state (22 stories migrated) -β†’ HALTS - -# You see: -"Migration halted at story 2-23 due to network error" -"State saved: 22 stories successfully migrated" -"Resume when network restored: /migrate-to-github mode=execute" - -# After network restored: -/migrate-to-github mode=execute - -β†’ "Resuming from story 2-23" -β†’ Continues 23-47 -β†’ "Migration complete: 47/47 migrated βœ…" -``` - ---- - -## Data Integrity Safeguards - -### Safeguard #1: GitHub is Append-Only - -**Design:** Migration never deletes data, only creates/updates. - -- Create: Safe (adds new issue) -- Update: Safe (modifies existing) -- Delete: Only in explicit rollback mode - -**Result:** Cannot accidentally lose data during migration. - -### Safeguard #2: Local Files Untouched - -**Design:** Migration reads local files but NEVER modifies them. - -**Guarantee:** -```javascript -// Migration code -const story = fs.readFileSync(storyFile, 'utf-8'); // READ ONLY - -// ❌ This never happens: -// fs.writeFileSync(storyFile, modified); // FORBIDDEN -``` - -**Result:** If migration fails, local files are unchanged. Can retry safely. - -### Safeguard #3: Duplicate Detection - -**Design:** Check for existing issues before creating. - -```javascript -// Before creating -const existing = await searchIssues({ - query: `repo:${owner}/${repo} label:story:${storyKey}` -}); - -if (existing.length > 1) { - throw new Error(` -DUPLICATE DETECTED: Found ${existing.length} issues for story:${storyKey} - -This should never happen. Possible causes: -- Previous migration created duplicates -- Manual issue creation -- Label typo - -Issues found: -${existing.map(i => ` - Issue #${i.number}: ${i.title}`).join('\n')} - -HALTING - resolve duplicates manually before continuing - `); -} -``` - -**Result:** Cannot create duplicates even if run multiple times. - -### Safeguard #4: State File Atomic Writes - -**Design:** State file uses atomic write pattern (tmp + rename). - -```javascript -async function saveStateSafely(state, statePath) { - const tmpPath = `${statePath}.tmp`; - - // 1. Write to temp file - fs.writeFileSync(tmpPath, yaml.stringify(state)); - - // 2. Verify temp file written correctly - const readBack = yaml.parse(fs.readFileSync(tmpPath)); - assert.deepEqual(readBack, state, 'State file corruption detected'); - - // 3. Atomic rename (POSIX guarantee) - fs.renameSync(tmpPath, statePath); - - // State is now safely written - crash after this point is safe -} -``` - -**Result:** State file is never corrupted, even if process crashes during write. - ---- - -## Monitoring & Observability - -### Real-Time Progress - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -⚑ MIGRATION PROGRESS (Live) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Migrated: 15/47 (32%) -Created: 12 issues -Updated: 3 issues -Failed: 0 - -Current: Story 2-16 (creating...) -Last success: Story 2-15 (2s ago) - -Rate: 1.2 stories/min -ETA: 26 minutes remaining - -API calls used: 45/5000 (1%) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -### Detailed Logging - -```yaml -# migration-log-2026-01-07T15-30-00.log -[15:30:00] Migration started (mode: execute) -[15:30:05] Pre-flight checks passed -[15:30:15] Story 2-1: Created Issue #101 (verified) -[15:30:32] Story 2-2: Created Issue #102 (verified) -[15:30:45] Story 2-3: Already exists Issue #103 (updated) -[15:31:02] Story 2-4: CREATE FAILED (attempt 1/3) - Network timeout -[15:31:03] Story 2-4: Retry 1 after 1000ms -[15:31:05] Story 2-4: Created Issue #104 (verified) βœ… -[15:31:20] Story 2-5: Created Issue #105 (verified) -# ... continues -[15:55:43] Migration complete: 47/47 success (0 failures) -[15:55:44] State saved: migration-state.yaml -[15:55:45] Rollback manifest: migration-rollback-2026-01-07T15-30-00.yaml -[15:55:46] Report generated: migration-report-2026-01-07T15-30-00.md -``` - ---- - -## Rate Limit Management - -### GitHub API Rate Limits - -**Authenticated:** 5000 requests/hour -**Per migration:** ~3-4 API calls per story - -**For 47 stories:** -- Search existing: 47 calls -- Create issues: ~35 calls -- Verify: 35 calls -- Labels/milestones: ~20 calls -- **Total:** ~140 calls -- **Remaining:** 4860/5000 (97% remaining) - -**Safe thresholds:** -- <500 stories: Single migration run -- 500-1000 stories: Split into 2 batches -- >1000 stories: Use epic-based filtering - -### Rate Limit Exhaustion Handling - -```javascript -async function apiCallWithRateLimitCheck(operation) { - try { - return await operation(); - } catch (error) { - if (error.status === 429) { // Rate limit exceeded - const resetTime = error.response.headers['x-ratelimit-reset']; - const waitSeconds = resetTime - Math.floor(Date.now() / 1000); - - console.warn(` -⚠️ Rate limit exceeded -Reset in: ${waitSeconds} seconds - -Options: -[W] Wait (pause migration until rate limit resets) -[S] Stop (save state and resume later) - -Choice: - `); - - if (choice === 'W') { - console.log(`Waiting ${waitSeconds}s for rate limit reset...`); - await sleep(waitSeconds * 1000); - return await operation(); // Retry after rate limit resets - } else { - // Save state and halt - await saveState(migrationState); - throw new Error('HALT: Rate limit exceeded, resume later'); - } - } - - throw error; // Other error, propagate - } -} -``` - ---- - -## Guarantees Summary - -| Guarantee | Mechanism | Failure Mode | Recovery | -|-----------|-----------|--------------|----------| -| Idempotent | Pre-check existing issues | Run twice β†’ duplicates? | ❌ Prevented by duplicate detection | -| Atomic | Transaction per story | Create succeeds, labels fail? | ❌ Prevented by rollback on error | -| Verified | Read-back after write | Write succeeds but wrong data? | ❌ Detected immediately, retried | -| Resumable | State file after each story | Crash mid-migration? | βœ… Resume from last completed | -| Reversible | Rollback manifest | Wrong repo migrated? | βœ… Rollback closes all issues | -| Previewed | Dry-run mode | Unsure what will happen? | βœ… Preview before executing | -| Resilient | Exponential backoff | Network blip? | βœ… Auto-retry 3x before failing | -| Fail-safe | Halt on critical error | GitHub API down? | βœ… Saves state, can resume | - -**Result:** 100% reliability through defense-in-depth strategy. - ---- - -## Migration Checklist - -**Before running migration:** -- [ ] Run `/migrate-to-github mode=dry-run` to preview -- [ ] Verify repository name is correct -- [ ] Back up sprint-status.yaml (just in case) -- [ ] Verify GitHub token has write permissions -- [ ] Check rate limit: <1000 stories OK for single run - -**During migration:** -- [ ] Monitor progress output -- [ ] Watch for warnings or retries -- [ ] Note any failed stories - -**After migration:** -- [ ] Run `/migrate-to-github mode=verify` -- [ ] Review migration report -- [ ] Spot-check 3-5 created issues in GitHub UI -- [ ] Save rollback manifest (in case need to undo) -- [ ] Update workflow configs: `github_sync_enabled: true` - ---- - -**Reliability Score: 10/10** βœ… - -Every failure mode has a recovery path. Every write is verified. Every operation is resumable. diff --git a/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.md b/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.md deleted file mode 100644 index 6d16f06d..00000000 --- a/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.md +++ /dev/null @@ -1,279 +0,0 @@ -# Migrate to GitHub v3.0 - Production-Grade Story Migration - - -Migrate BMAD stories to GitHub Issues with full safety guarantees. -Idempotent, atomic, verified, resumable, and reversible. - - - -**Reliability First, Data Integrity Over Speed** - -- Idempotent: Can re-run safely (checks for duplicates) -- Atomic: Each story fully succeeds or rolls back -- Verified: Reads back each created issue -- Resumable: Saves state after each story -- Reversible: Creates rollback manifest - - - -name: migrate-to-github -version: 3.0.0 - -modes: - dry-run: {description: "Preview only, no changes", default: true} - execute: {description: "Actually create issues"} - verify: {description: "Double-check migration accuracy"} - rollback: {description: "Close migrated issues"} - -defaults: - update_existing: false - halt_on_critical_error: true - save_state_after_each: true - max_retries: 3 - retry_backoff_ms: [1000, 3000, 10000] - -labels: - - "type:story" - - "story:{{story_key}}" - - "status:{{status}}" - - "epic:{{epic_number}}" - - "complexity:{{complexity}}" - - - -@patterns/hospital-grade.md - - - - - -**Verify all prerequisites before ANY operations** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ›‘οΈ PRE-FLIGHT SAFETY CHECKS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**1. Verify GitHub MCP access:** -``` -Call: mcp__github__get_me() -If fails: HALT - Cannot proceed without GitHub API access -``` - -**2. Verify repository access:** -``` -Call: mcp__github__list_issues(owner, repo, per_page=1) -If fails: HALT - Repository not accessible -``` - -**3. Verify local files exist:** -```bash -[ -f "docs/sprint-artifacts/sprint-status.yaml" ] || { echo "HALT"; exit 1; } -``` - -**4. Check for existing migration:** -- If state file exists: offer Resume/Fresh/View/Delete -- If resuming: load already-migrated stories, filter from queue - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… PRE-FLIGHT CHECKS PASSED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Preview migration plan without making changes** - -For each story: -1. Search GitHub for existing issue with label `story:{{story_key}}` -2. If exists: mark as "Would UPDATE" or "Would SKIP" -3. If not exists: mark as "Would CREATE" - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š DRY-RUN SUMMARY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Would CREATE: {{create_count}} new issues -Would UPDATE: {{update_count}} existing issues -Would SKIP: {{skip_count}} - -Estimated API Calls: ~{{total_calls}} -Rate Limit Impact: Safe (< 1000 calls) - -⚠️ This was a DRY-RUN. No issues created. -To execute: /migrate-to-github mode=execute -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Perform migration with atomic operations** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -⚑ EXECUTE MODE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Final confirmation:** -``` -Type "I understand and want to proceed" to continue: -``` - -Initialize migration state and rollback manifest. - -For each story: - -**1. Check if exists (idempotent):** -``` -Search: label:story:{{story_key}} -If exists AND update_existing=false: SKIP -``` - -**2. Generate issue body:** -```markdown -**Story File:** [{{story_key}}.md](path) -**Epic:** {{epic_number}} - -## Business Context -{{parsed.businessContext}} - -## Acceptance Criteria -{{#each ac}} -- [ ] {{this}} -{{/each}} - -## Tasks -{{#each tasks}} -- [ ] {{this}} -{{/each}} -``` - -**3. Create/update with retry and verification:** -``` -attempt = 0 -WHILE attempt < max_retries: - TRY: - result = mcp__github__issue_write(create/update) - sleep 2 seconds # GitHub eventual consistency - - verification = mcp__github__issue_read(issue_number) - IF verification.title != expected: - THROW "Verification failed" - - SUCCESS - add to rollback manifest - BREAK - - CATCH: - attempt++ - IF attempt < max_retries: - sleep backoff_ms[attempt] - ELSE: - FAIL - add to issues_failed -``` - -**4. Save state after each story** - -**5. Progress updates every 10 stories:** -``` -πŸ“Š Progress: {{index}}/{{total}} - Created: {{created}}, Updated: {{updated}}, Failed: {{failed}} -``` - - - -**Double-check migration accuracy** - -For each migrated story: -1. Fetch issue from GitHub -2. Verify title, labels, AC count match -3. Report mismatches - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š VERIFICATION RESULTS -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Verified Correct: {{verified}} -Warnings: {{warnings}} -Failures: {{failures}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Close migrated issues (GitHub API doesn't support delete)** - -Load rollback manifest. For each created issue: -``` -mcp__github__issue_write({ - issue_number: {{number}}, - state: "closed", - labels: ["migrated:rolled-back"], - state_reason: "not_planned" -}) - -mcp__github__add_issue_comment({ - body: "Issue closed - migration was rolled back." -}) -``` - - - -**Create comprehensive migration report** - -Write to: `docs/sprint-artifacts/github-migration-{{timestamp}}.md` - -Include: -- Executive summary -- Created/updated/failed issues -- GitHub URLs for each issue -- Rollback instructions -- Next steps - - - -**Display completion status** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… MIGRATION COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Total: {{total}} stories -Created: {{created}} -Updated: {{updated}} -Failed: {{failed}} -Success Rate: {{success_pct}}% - -View in GitHub: -https://github.com/{{owner}}/{{repo}}/issues?q=label:type:story - -Rollback Manifest: {{rollback_path}} -State File: {{state_path}} - -Next Steps: -1. Verify: /migrate-to-github mode=verify -2. Enable GitHub sync in workflow.yaml -3. Share Issues URL with Product Owner -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -**GitHub MCP unavailable:** HALT - Cannot proceed. -**Repository not accessible:** HALT - Check permissions. -**Issue create fails:** Retry with backoff, then fail story. -**Verification fails:** Log warning, continue. -**All stories fail:** Report systemic issue, HALT. - - - -- [ ] Pre-flight checks passed -- [ ] All stories processed -- [ ] Issues verified after creation -- [ ] State and rollback manifest saved -- [ ] Report generated - diff --git a/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.yaml b/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.yaml deleted file mode 100644 index e7b8ac7d..00000000 --- a/src/modules/bmm/workflows/4-implementation/migrate-to-github/workflow.yaml +++ /dev/null @@ -1,62 +0,0 @@ -name: migrate-to-github -description: "Production-grade migration of BMAD stories from local files to GitHub Issues with comprehensive reliability guarantees" -author: "BMad" -version: "1.0.0" - -# Critical variables -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{output_folder}/sprint-artifacts" -sprint_status: "{output_folder}/sprint-status.yaml" - -# GitHub configuration -github: - owner: "{github_owner}" # Required: GitHub username or org - repo: "{github_repo}" # Required: Repository name - # Token comes from MCP GitHub server config (already authenticated) - -# Migration mode -mode: "dry-run" # "dry-run" | "execute" | "verify" | "rollback" -# SAFETY: Defaults to dry-run - must explicitly choose execute - -# Migration scope -scope: - include_epics: true # Create milestone for each epic - include_stories: true # Create issue for each story - filter_by_epic: null # Optional: Only migrate Epic N (e.g., "2") - filter_by_status: null # Optional: Only migrate stories with status (e.g., "backlog") - -# Migration strategy -strategy: - check_existing: true # Search for existing issues before creating (prevents duplicates) - update_existing: true # If issue exists, update it (false = skip) - create_missing: true # Create issues for stories without issues - - # Label strategy - label_prefix: "story:" # Prefix for story labels (e.g., "story:2-5-auth") - use_type_labels: true # Add "type:story", "type:epic" - use_status_labels: true # Add "status:backlog", "status:in-progress", etc. - use_complexity_labels: true # Add "complexity:micro", etc. - use_epic_labels: true # Add "epic:2", "epic:3", etc. - -# Reliability settings -reliability: - verify_after_create: true # Read back issue to verify creation succeeded - retry_on_failure: true # Retry failed operations - max_retries: 3 - retry_backoff_ms: [1000, 3000, 9000] # Exponential backoff - halt_on_critical_error: true # Stop migration if critical error occurs - save_state_after_each: true # Save progress after each story (crash-safe) - create_rollback_manifest: true # Track created issues for rollback - -# State tracking -state_file: "{output_folder}/migration-state.yaml" -# Tracks: stories_migrated, issues_created, last_story, can_resume - -# Output -output: - create_migration_report: true - report_path: "{output_folder}/migration-report-{timestamp}.md" - log_level: "verbose" # "quiet" | "normal" | "verbose" - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.md b/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.md deleted file mode 100644 index 2d32d036..00000000 --- a/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.md +++ /dev/null @@ -1,197 +0,0 @@ -# Multi-Agent Code Review v3.0 - - -Perform unbiased code review using multiple specialized AI agents in fresh context. -Agent count scales with story complexity. Independent perspective prevents bias. - - - -**Fresh Context, Multiple Perspectives** - -- Review happens in NEW session (not the agent that wrote the code) -- Prevents bias from implementation decisions -- Agent count determined by complexity, agents chosen by code analysis -- Smart selection: touching auth code β†’ auth-security agent, etc. - - - -name: multi-agent-review -version: 3.0.0 - -agent_selection: - micro: {count: 2, agents: [security, code_quality]} - standard: {count: 4, agents: [security, code_quality, architecture, testing]} - complex: {count: 6, agents: [security, code_quality, architecture, testing, performance, domain_expert]} - -available_agents: - security: "Identifies vulnerabilities and security risks" - code_quality: "Reviews style, maintainability, best practices" - architecture: "Reviews system design, patterns, structure" - testing: "Evaluates test coverage and quality" - performance: "Analyzes efficiency and optimization" - domain_expert: "Validates business logic and domain constraints" - - - -@patterns/security-checklist.md -@patterns/hospital-grade.md -@patterns/agent-completion.md - - - - - -**Select agents based on complexity** - -``` -If complexity_level == "micro": - agents = ["security", "code_quality"] - Display: πŸ” MICRO Review (2 agents) - -Else if complexity_level == "standard": - agents = ["security", "code_quality", "architecture", "testing"] - Display: πŸ“‹ STANDARD Review (4 agents) - -Else if complexity_level == "complex": - agents = ALL 6 agents - Display: πŸ”¬ COMPLEX Review (6 agents) -``` - - - -**Load story file and understand requirements** - -```bash -STORY_FILE="{{story_file}}" -[ -f "$STORY_FILE" ] || { echo "❌ Story file not found"; exit 1; } -``` - -Use Read tool on story file. Extract: -- What was supposed to be implemented -- Acceptance criteria -- Tasks and subtasks -- File list - - - -**Spawn review agents in fresh context** - -For each agent in selected agents, spawn Task agent: - -``` -Task({ - subagent_type: "general-purpose", - description: "{{agent_type}} review for {{story_key}}", - prompt: ` -You are the {{AGENT_TYPE}} reviewer for story {{story_key}}. - - -@patterns/security-checklist.md -@patterns/hospital-grade.md - - - -Story: [inline story content] -Changed files: [git diff output] - - - -Review from your {{agent_type}} perspective. Find issues, be thorough. - - - -- [ ] All relevant files reviewed -- [ ] Issues categorized by severity (CRITICAL/HIGH/MEDIUM/LOW) -- [ ] Return ## AGENT COMPLETE with findings - -` -}) -``` - -Wait for all agents to complete. Aggregate findings. - - - -**Collect and categorize all findings** - -Merge findings from all agents: -- CRITICAL: Security vulnerabilities, data loss risks -- HIGH: Production bugs, logic errors -- MEDIUM: Technical debt, maintainability -- LOW: Nice-to-have improvements - - - -**Display review summary** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ€– MULTI-AGENT CODE REVIEW COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Agents Used: {{agent_count}} -- Security Agent -- Code Quality Agent -[...] - -Findings: -- πŸ”΄ CRITICAL: {{critical_count}} -- 🟠 HIGH: {{high_count}} -- 🟑 MEDIUM: {{medium_count}} -- πŸ”΅ LOW: {{low_count}} -``` - -For each finding, display: -- Severity and title -- Agent that found it -- Location (file:line) -- Description and recommendation - - - -**Suggest next steps based on findings** - -``` -πŸ“‹ RECOMMENDED NEXT STEPS: - -If CRITICAL findings exist: - ⚠️ MUST FIX before proceeding - - Address all critical security/correctness issues - - Re-run review after fixes - -If only HIGH/MEDIUM findings: - βœ… Story may proceed - - Consider addressing high-priority items - - Create follow-up tasks for medium items - -If only LOW/INFO findings: - βœ… Code quality looks good - - Optional: Address style/optimization suggestions -``` - - - - - -**When to use:** -- Complex stories (β‰₯16 tasks or high-risk keywords) -- Security-sensitive code -- Significant architectural changes -- When single-agent review was inconclusive - -**When NOT to use:** -- Micro stories (≀3 tasks) -- Standard stories with simple changes -- Stories that passed adversarial review cleanly - - - -**Review agent fails:** Fall back to adversarial code review. -**API error:** Log failure, continue pipeline with warning. - - - -- [ ] All selected agents completed review -- [ ] Findings aggregated and categorized -- [ ] Report displayed with recommendations - diff --git a/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml b/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml deleted file mode 100644 index d372490e..00000000 --- a/src/modules/bmm/workflows/4-implementation/multi-agent-review/workflow.yaml +++ /dev/null @@ -1,57 +0,0 @@ -name: multi-agent-review -description: "Smart multi-agent code review with dynamic agent selection based on changed code. Uses multiple specialized AI agents to review different aspects: architecture, security, performance, testing, and code quality." -author: "BMad" -version: "1.0.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{config_source}:sprint_artifacts" -communication_language: "{config_source}:communication_language" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/multi-agent-review" -instructions: "{installed_path}/instructions.md" - -# Input parameters -story_id: "{story_id}" # Required -story_file: "{sprint_artifacts}/{story_id}.md" # CANONICAL FORMAT: epic-story-slug.md (NO "story-" prefix) -base_branch: "main" # Optional: branch to compare against -complexity_level: "standard" # micro | standard | complex (passed from super-dev-pipeline) - -# Complexity-based agent selection (NEW v1.0.0) -# Cost-effective review depth based on story RISK and technical complexity -# Complexity determined by batch-super-dev based on: risk keywords, architectural impact, security concerns -complexity_routing: - micro: - agent_count: 2 - agents: ["security", "code_quality"] - description: "Quick sanity check for low-risk stories" - examples: ["UI tweaks", "text changes", "simple CRUD", "documentation"] - cost_multiplier: 1x - - standard: - agent_count: 4 - agents: ["security", "code_quality", "architecture", "testing"] - description: "Balanced multi-perspective review for medium-risk changes" - examples: ["API endpoints", "business logic", "data validation", "component refactors"] - cost_multiplier: 2x - - complex: - agent_count: 6 - agents: ["security", "code_quality", "architecture", "testing", "performance", "domain_expert"] - description: "Comprehensive review for high-risk/high-complexity changes" - examples: ["auth/security", "payments", "data migration", "architecture changes", "performance-critical", "complex algorithms"] - cost_multiplier: 3x - -# Review settings -review_settings: - fresh_context_required: true # CRITICAL: Review in new session for unbiased perspective - agents_to_use: "complexity_based" # complexity_based | all | custom - generate_report: true - auto_fix_suggested: false # Set to true to automatically apply suggested fixes - -# Output -review_report: "{sprint_artifacts}/review-{story_id}-multi-agent.md" - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/push-all/workflow.md b/src/modules/bmm/workflows/4-implementation/push-all/workflow.md deleted file mode 100644 index 44637b79..00000000 --- a/src/modules/bmm/workflows/4-implementation/push-all/workflow.md +++ /dev/null @@ -1,366 +0,0 @@ -# Push All v3.0 - Safe Git Staging, Commit, and Push - - -Safely stage, commit, and push changes with comprehensive validation. -Detects secrets, large files, build artifacts. Handles push failures gracefully. -Supports targeted mode for specific files (parallel agent coordination). - - - -**Safe by Default, No Surprises** - -- Validate BEFORE committing (secrets, size, artifacts) -- Show exactly what will be committed -- Handle push failures with recovery options -- Never force push without explicit confirmation - - - -name: push-all -version: 3.0.0 - -modes: - full: "Stage all changes (default)" - targeted: "Only stage specified files" - -defaults: - max_file_size_kb: 500 - check_secrets: true - check_build_artifacts: true - auto_push: false - allow_force_push: false - -secret_patterns: - - "AKIA[0-9A-Z]{16}" # AWS Access Key - - "sk-[a-zA-Z0-9]{48}" # OpenAI Key - - "ghp_[a-zA-Z0-9]{36}" # GitHub Personal Token - - "xox[baprs]-[a-zA-Z0-9-]+" # Slack Token - - "-----BEGIN.*PRIVATE KEY" # Private Keys - - "password\\s*=\\s*['\"][^'\"]{8,}" # Hardcoded passwords - -build_artifacts: - - "node_modules/" - - "dist/" - - "build/" - - ".next/" - - "*.min.js" - - "*.bundle.js" - - - -@patterns/hospital-grade.md - - - - - -**Verify git repository state** - -```bash -# Check we're in a git repo -git rev-parse --is-inside-work-tree || { echo "❌ Not a git repository"; exit 1; } - -# Get current branch -git branch --show-current - -# Check for uncommitted changes -git status --porcelain -``` - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“¦ PUSH-ALL: {{mode}} mode -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Branch: {{branch}} -Mode: {{mode}} -{{#if targeted}}Files: {{file_list}}{{/if}} -``` - -**If no changes:** -``` -βœ… Working directory clean - nothing to commit -``` -Exit successfully. - - - -**Identify files to be staged** - -**Full mode:** -```bash -git status --porcelain | awk '{print $2}' -``` - -**Targeted mode:** -Only include files specified in `target_files` parameter. - -**Categorize changes:** -- New files (A) -- Modified files (M) -- Deleted files (D) -- Renamed files (R) - - - -**Scan for secrets in staged content** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” SECRET SCAN -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -For each file to be staged: -```bash -# Check for secret patterns -Grep: "{{pattern}}" {{file}} -``` - -**If secrets found:** -``` -❌ POTENTIAL SECRETS DETECTED - -{{#each secrets}} -File: {{file}} -Line {{line}}: {{preview}} (pattern: {{pattern_name}}) -{{/each}} - -⚠️ BLOCKING COMMIT -Remove secrets before proceeding. - -Options: -[I] Ignore (I know what I'm doing) -[E] Exclude these files -[H] Halt -``` - -**If [I] selected:** Require explicit confirmation text. - - - -**Check for oversized files** - -```bash -# Find files larger than max_file_size_kb -find . -type f -size +{{max_file_size}}k -not -path "./.git/*" -``` - -**If large files found:** -``` -⚠️ LARGE FILES DETECTED - -{{#each large_files}} -- {{file}} ({{size_kb}}KB) -{{/each}} - -Options: -[I] Include anyway -[E] Exclude large files -[H] Halt -``` - - - -**Check for build artifacts** - -```bash -# Check if any staged files match artifact patterns -git status --porcelain | grep -E "{{artifact_pattern}}" -``` - -**If artifacts found:** -``` -⚠️ BUILD ARTIFACTS DETECTED - -{{#each artifacts}} -- {{file}} -{{/each}} - -These should typically be in .gitignore. - -Options: -[E] Exclude artifacts (recommended) -[I] Include anyway -[H] Halt -``` - - - -**Show what will be committed** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ COMMIT PREVIEW -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Files to commit: {{count}} - -Added ({{added_count}}): -{{#each added}} - + {{file}} -{{/each}} - -Modified ({{modified_count}}): -{{#each modified}} - M {{file}} -{{/each}} - -Deleted ({{deleted_count}}): -{{#each deleted}} - - {{file}} -{{/each}} - -{{#if excluded}} -Excluded: {{excluded_count}} files -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Generate or request commit message** - -**If commit_message provided:** Use it. - -**Otherwise, generate from changes:** -``` -Analyzing changes to generate commit message... - -Changes detected: -- {{summary_of_changes}} - -Suggested message: -"{{generated_message}}" - -[Y] Use this message -[E] Edit message -[C] Custom message -``` - -If user selects [C] or [E], prompt for message. - - - -**Stage and commit changes** - -```bash -# Stage files (targeted or full) -{{#if targeted}} -git add {{#each target_files}}{{this}} {{/each}} -{{else}} -git add -A -{{/if}} - -# Commit with message -git commit -m "{{commit_message}}" -``` - -**Verify commit:** -```bash -# Check commit was created -git log -1 --oneline -``` - -``` -βœ… Commit created: {{commit_hash}} -``` - - - -**Push to remote with error handling** - -```bash -git push origin {{branch}} -``` - -**If push fails:** - -**Case: Behind remote** -``` -⚠️ Push rejected - branch is behind remote - -Options: -[P] Pull and retry (git pull --rebase) -[F] Force push (DESTRUCTIVE - overwrites remote) -[H] Halt (commit preserved locally) -``` - -**Case: No upstream** -``` -⚠️ No upstream branch - -Setting upstream and pushing: -git push -u origin {{branch}} -``` - -**Case: Auth failure** -``` -❌ Authentication failed - -Check: -1. SSH key configured? -2. Token valid? -3. Repository access? -``` - -**Case: Protected branch** -``` -❌ Cannot push to protected branch - -Use pull request workflow instead: -gh pr create --title "{{commit_message}}" -``` - - - -**Display completion status** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… PUSH-ALL COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Branch: {{branch}} -Commit: {{commit_hash}} -Files: {{file_count}} -{{#if pushed}} -Remote: βœ… Pushed to origin/{{branch}} -{{else}} -Remote: ⏸️ Not pushed (commit preserved locally) -{{/if}} - -{{#if excluded_count > 0}} -Excluded: {{excluded_count}} files (secrets/artifacts/size) -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -```bash -# Stage all, commit, and push -/push-all commit_message="feat: add user authentication" auto_push=true - -# Targeted mode - only specific files -/push-all mode=targeted target_files="src/auth.ts,src/auth.test.ts" commit_message="fix: auth bug" - -# Dry run - see what would be committed -/push-all auto_push=false -``` - - - -**Secrets detected:** BLOCK commit, require explicit override. -**Large files:** Warn, allow exclude or include. -**Build artifacts:** Warn, recommend exclude. -**Push rejected:** Offer pull/rebase, force push (with confirmation), or halt. -**Auth failure:** Report, suggest troubleshooting. - - - -- [ ] Changes validated (secrets, size, artifacts) -- [ ] Files staged correctly -- [ ] Commit created with message -- [ ] Push successful (if requested) -- [ ] No unintended files included - diff --git a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml b/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml deleted file mode 100644 index 5875d911..00000000 --- a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml +++ /dev/null @@ -1,22 +0,0 @@ -name: push-all -description: "Stage changes, create commit with safety checks, and push to remote" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/push-all" -instructions: "{installed_path}/workflow.md" - -# Target files to commit (for parallel agent execution) -# When empty/not provided: commits ALL changes (original behavior) -# When provided: only commits the specified files (safe for parallel agents) -target_files: "" # Space-separated list of file paths, or empty for all -story_key: "" # Optional: story identifier for commit message context - -standalone: true - -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.md b/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.md deleted file mode 100644 index 0b4c8017..00000000 --- a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.md +++ /dev/null @@ -1,172 +0,0 @@ -# Recover Sprint Status v3.0 - - -Fix sprint-status.yaml when tracking has drifted. Analyzes multiple sources -(story files, git commits, completion reports) to rebuild accurate status. - - - -**Multiple Evidence Sources, Conservative Updates** - -1. Story file quality (size, tasks, checkboxes) -2. Explicit Status: fields in stories -3. Git commits (last 30 days) -4. Autonomous completion reports -5. Task completion rate - -Trust explicit Status: fields highest. Require evidence for status changes. - - - -name: recover-sprint-status -version: 3.0.0 - -modes: - dry-run: {description: "Analysis only, no changes", default: true} - conservative: {description: "High confidence updates only"} - aggressive: {description: "Medium+ confidence, infers from git"} - interactive: {description: "Ask before each batch"} - -confidence_levels: - very_high: {sources: [explicit_status, completion_report]} - high: {sources: [3+ git_commits, 90% tasks_complete]} - medium: {sources: [1-2 git_commits, 50-90% tasks_complete]} - low: {sources: [no_status, no_commits, small_file]} - - - -@patterns/hospital-grade.md - - - - - -**Scan all evidence sources** - -```bash -# Find story files -SPRINT_ARTIFACTS="docs/sprint-artifacts" -STORIES=$(ls $SPRINT_ARTIFACTS/*.md 2>/dev/null | grep -v "epic-") - -# Get recent git commits -git log --oneline --since="30 days ago" > /tmp/recent_commits.txt -``` - -For each story: -1. Read story file, extract Status: field if present -2. Check file size (β‰₯10KB = properly detailed) -3. Count tasks and checkbox completion -4. Search git commits for story references -5. Check for completion reports (.epic-*-completion-report.md) - - - -**Determine confidence level for each story** - -| Evidence | Confidence | Action | -|----------|------------|--------| -| Explicit Status: done | Very High | Trust it | -| Completion report lists story | Very High | Mark done | -| 3+ git commits + 90% checked | High | Mark done | -| 1-2 commits OR 50-90% checked | Medium | Mark in-progress | -| No commits, <50% checked | Low | Leave as-is | -| File <10KB | Low | Downgrade if done | - - - -**Show recommendations without applying** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” RECOVERY ANALYSIS (Dry Run) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -High Confidence Updates: -- 2-5-auth: backlog β†’ done (explicit Status:, 3 commits) -- 2-6-profile: in-progress β†’ done (completion report) - -Medium Confidence Updates: -- 2-7-settings: backlog β†’ in-progress (2 commits) - -Low Confidence (verify manually): -- 2-8-dashboard: no Status:, no commits, <10KB file -``` - -Exit after preview. No changes made. - - - -**Apply only high/very-high confidence updates** - -For each high+ confidence story: -1. Backup current sprint-status.yaml -2. Use Edit tool to update status -3. Log change - -```bash -# Backup -cp $SPRINT_STATUS .sprint-status-backups/sprint-status-recovery-$(date +%Y%m%d).yaml -``` - -Skip medium/low confidence stories. - - - -**Apply medium+ confidence updates** - -Includes: -- Inferring from git commits (even 1 commit) -- Using task completion rate -- Pre-filling brownfield checkboxes - -``` -⚠️ AGGRESSIVE mode may make incorrect inferences. - Review results carefully. -``` - - - -**Verify recovery worked** - -```bash -./scripts/sync-sprint-status.sh --validate -``` - -Should show: -- "βœ“ sprint-status.yaml is up to date!" (success) -- OR discrepancy count (if issues remain) - - - -**Commit the recovery** - -Use Bash to commit: -```bash -git add docs/sprint-artifacts/sprint-status.yaml -git add .sprint-status-backups/ -git commit -m "fix(tracking): Recover sprint-status.yaml - {{mode}} recovery" -``` - - - - - -**No changes detected:** sprint-status.yaml already accurate. -**Low confidence on known-done stories:** Add Status: field manually, re-run. -**Recovery marks incomplete as done:** Use conservative mode, verify manually. - - - -- [ ] Run validation: `./scripts/sync-sprint-status.sh --validate` -- [ ] Review backup in `.sprint-status-backups/` -- [ ] Spot-check 5-10 stories for accuracy -- [ ] Commit changes -- [ ] Document why drift occurred - - - -- [ ] All evidence sources analyzed -- [ ] Changes applied based on confidence threshold -- [ ] Validation passes -- [ ] Backup created - diff --git a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.yaml b/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.yaml deleted file mode 100644 index 5ae5c8f8..00000000 --- a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/workflow.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# Sprint Status Recovery Workflow -name: recover-sprint-status -description: "Recover sprint-status.yaml when tracking has drifted. Analyzes story files, git commits, and autonomous reports to rebuild accurate status." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -implementation_artifacts: "{config_source}:implementation_artifacts" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/recover-sprint-status" -instructions: "{installed_path}/instructions.md" - -# Inputs -variables: - sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" - story_directory: "{implementation_artifacts}" - recovery_mode: "interactive" # Options: interactive, conservative, aggressive - -# Recovery script location -recovery_script: "{project-root}/scripts/recover-sprint-status.sh" - -# Standalone so IDE commands get generated -standalone: true - -# No web bundle needed -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.md b/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.md deleted file mode 100644 index 0f2769b0..00000000 --- a/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.md +++ /dev/null @@ -1,189 +0,0 @@ -# Revalidate Epic v3.0 - Batch Story Revalidation - - -Batch revalidate all stories in an epic using parallel agents (semaphore pattern). -Clears checkboxes, verifies against codebase, re-checks verified items. - - - -**Parallel Verification, Continuous Worker Pool** - -- Spawn up to N workers, refill as each completes -- Each story gets fresh context verification -- Aggregate results into epic-level health score -- Optionally fill gaps found during verification - - - -name: revalidate-epic -version: 3.0.0 - -defaults: - max_concurrent: 3 - fill_gaps: false - continue_on_failure: true - create_epic_report: true - update_sprint_status: true - - - -@patterns/verification.md -@patterns/hospital-grade.md -@revalidate-story/workflow.md - - - - - -**Find all stories for the epic** - -```bash -EPIC_NUMBER="{{epic_number}}" -[ -n "$EPIC_NUMBER" ] || { echo "ERROR: epic_number required"; exit 1; } - -# Filter stories from sprint-status.yaml -grep "^${EPIC_NUMBER}-" docs/sprint-artifacts/sprint-status.yaml -``` - -Use Read tool on sprint-status.yaml. Filter stories starting with `{epic_number}-`. -Exclude epics and retrospectives. - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” EPIC {{epic_number}} REVALIDATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Stories Found: {{count}} -Mode: {{fill_gaps ? "Verify & Fill Gaps" : "Verify Only"}} -Max Concurrent: {{max_concurrent}} agents -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Use AskUserQuestion: Proceed with revalidation? (yes/no) - - - -**Initialize semaphore pattern for parallel revalidation** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸš€ Starting Parallel Revalidation -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Initialize state: -- story_queue = epic_stories -- active_workers = {} -- completed_stories = [] -- failed_stories = [] - -Fill initial worker slots (up to max_concurrent): - -``` -Task({ - subagent_type: "general-purpose", - description: "Revalidate story {{story_key}}", - prompt: ` -Execute revalidate-story workflow for {{story_key}}. - - -@revalidate-story/workflow.md - - -Parameters: -- story_file: {{story_file}} -- fill_gaps: {{fill_gaps}} - -Return verification summary with verified_pct, gaps_found, gaps_filled. -`, - run_in_background: true -}) -``` - - - -**Keep workers running until all stories done** - -While active_workers > 0 OR stories remaining in queue: - -1. Poll for completed workers (non-blocking with TaskOutput) -2. When worker completes: - - Parse verification results - - Add to completed_stories - - If more stories in queue: spawn new worker in that slot -3. Display progress every 30 seconds: - -``` -πŸ“Š Progress: {{completed}} completed, {{active}} active, {{queued}} queued -``` - - - -**Generate epic-level summary** - -Calculate totals across all stories: -- epic_verified = sum of verified items -- epic_partial = sum of partial items -- epic_missing = sum of missing items -- epic_verified_pct = (verified / total) Γ— 100 - -Group stories by health: -- Complete (β‰₯95% verified) -- Mostly Complete (80-94%) -- Partial (50-79%) -- Incomplete (<50%) - - - -**Show epic revalidation results** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š EPIC {{epic_number}} REVALIDATION SUMMARY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Total Stories: {{count}} -Completed: {{completed_count}} -Failed: {{failed_count}} - -Epic-Wide Verification: -- βœ… Verified: {{verified}}/{{total}} ({{pct}}%) -- πŸ”Ά Partial: {{partial}}/{{total}} -- ❌ Missing: {{missing}}/{{total}} - -Epic Health Score: {{epic_verified_pct}}/100 - -{{#if pct >= 95}} -βœ… Epic is COMPLETE and verified -{{else if pct >= 80}} -πŸ”Ά Epic is MOSTLY COMPLETE -{{else if pct >= 50}} -⚠️ Epic is PARTIALLY COMPLETE -{{else}} -❌ Epic is INCOMPLETE (major rework needed) -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Update sprint-status with revalidation results** - -Use Edit tool to add comment to epic entry: -``` -epic-{{epic_number}}: done # Revalidated: {{pct}}% verified ({{timestamp}}) -``` - - - - - -**Worker fails:** Log error, refill slot if continue_on_failure=true. -**All stories fail:** Report systemic issue, halt batch. -**Story file missing:** Skip with warning. - - - -- [ ] All epic stories processed -- [ ] Results aggregated -- [ ] Epic health score calculated -- [ ] Sprint status updated (if enabled) - diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.yaml b/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.yaml deleted file mode 100644 index 38b7de23..00000000 --- a/src/modules/bmm/workflows/4-implementation/revalidate-epic/workflow.yaml +++ /dev/null @@ -1,44 +0,0 @@ -name: revalidate-epic -description: "Batch revalidation of all stories in an epic. Clears checkboxes and re-verifies against codebase with semaphore pattern." -author: "BMad" -version: "1.0.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{output_folder}/sprint-artifacts" -sprint_status: "{output_folder}/sprint-status.yaml" - -# Input parameters -epic_number: "{epic_number}" # Required: Epic number (e.g., "2" for Epic 2) -fill_gaps: false # Optional: Fill missing items after verification -max_concurrent: 3 # Optional: Max concurrent revalidation agents (default: 3) - -# Verification settings (inherited by story revalidations) -verification: - verify_acceptance_criteria: true - verify_tasks: true - verify_definition_of_done: true - check_for_stubs: true - require_tests: true - -# Gap filling settings -gap_filling: - max_gaps_per_story: 10 # Safety limit per story - require_confirmation_first_story: true # Ask on first story, then auto for rest - run_tests_after_each: true - commit_strategy: "per_gap" # "per_gap" | "per_story" | "all_at_once" - -# Execution settings -execution: - use_semaphore_pattern: true # Constant concurrency (not batch-and-wait) - continue_on_failure: true # Keep processing if one story fails - display_live_progress: true # Show progress updates every 30s - -# Output settings -output: - create_epic_report: true # Generate epic-level summary - create_story_reports: true # Generate per-story reports - update_sprint_status: true # Update progress in sprint-status.yaml - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.md b/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.md deleted file mode 100644 index 5e28a7ae..00000000 --- a/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.md +++ /dev/null @@ -1,225 +0,0 @@ -# Revalidate Story v3.0 - Verify Checkboxes Against Codebase - - -Clear all checkboxes and re-verify each item against actual codebase reality. -Detects over-reported completion and identifies real gaps. -Optionally fills gaps by implementing missing items. - - - -**Trust But Verify, Evidence Required** - -1. Clear all checkboxes (fresh start) -2. For each AC/Task/DoD: search codebase for evidence -3. Only re-check if evidence found AND not a stub -4. Report accuracy: was completion over-reported or under-reported? - - - -name: revalidate-story -version: 3.0.0 - -defaults: - fill_gaps: false - max_gaps_to_fill: 10 - commit_strategy: "all_at_once" # or "per_gap" - create_report: true - update_sprint_status: true - -verification_status: - verified: {checkbox: "[x]", evidence: "found, not stub, tests exist"} - partial: {checkbox: "[~]", evidence: "partial implementation or missing tests"} - missing: {checkbox: "[ ]", evidence: "not found in codebase"} - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Load story and backup current state** - -```bash -STORY_FILE="{{story_file}}" -[ -f "$STORY_FILE" ] || { echo "ERROR: story_file required"; exit 1; } -``` - -Use Read tool on story file. Count current checkboxes: -- ac_checked_before -- tasks_checked_before -- dod_checked_before - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” STORY REVALIDATION STARTED -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{story_key}} -Mode: {{fill_gaps ? "Verify & Fill Gaps" : "Verify Only"}} - -Current State: -- Acceptance Criteria: {{ac_checked}}/{{ac_total}} checked -- Tasks: {{tasks_checked}}/{{tasks_total}} checked -- DoD: {{dod_checked}}/{{dod_total}} checked -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Clear all checkboxes for fresh verification** - -Use Edit tool (replace_all: true): -- `[x]` β†’ `[ ]` in Acceptance Criteria section -- `[x]` β†’ `[ ]` in Tasks section -- `[x]` β†’ `[ ]` in Definition of Done section - - - -**Verify each AC against codebase** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ VERIFYING ACCEPTANCE CRITERIA -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -For each AC item: - -1. **Parse AC** - Extract file/component/feature mentions -2. **Search codebase** - Use Glob/Grep to find evidence -3. **Verify implementation** - Read files, check for: - - NOT a stub (no "TODO", "Not implemented", empty function) - - Has actual implementation - - Tests exist (*.test.* or *.spec.*) - -4. **Determine status:** - - VERIFIED: Evidence found, not stub, tests exist β†’ check [x] - - PARTIAL: Partial evidence or missing tests β†’ check [~] - - MISSING: No evidence found β†’ leave [ ] - -5. **Record evidence or gap** - - - -**Verify each task against codebase** - -Same process as ACs: -- Parse task description for artifacts -- Search codebase with Glob/Grep -- Read and verify (check for stubs, tests) -- Update checkbox based on evidence - - - -**Verify DoD items** - -For common DoD items, run actual checks: -- "Type check passes" β†’ `npm run type-check` -- "Unit tests pass" β†’ `npm test` -- "Linting clean" β†’ `npm run lint` -- "Build succeeds" β†’ `npm run build` - - - -**Calculate and display results** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š REVALIDATION SUMMARY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{story_key}} - -Verification Results: -- βœ… Verified: {{verified}}/{{total}} ({{pct}}%) -- πŸ”Ά Partial: {{partial}}/{{total}} -- ❌ Missing: {{missing}}/{{total}} - -Accuracy Check: -- Before: {{pct_before}}% checked -- After: {{verified_pct}}% verified -- {{pct_before > verified_pct ? "Over-reported" : "Under-reported"}} - -{{#if missing > 0}} -Gaps Found ({{missing}}): -[list gaps with what's missing] -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Implement missing items** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”§ GAP FILLING MODE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Safety check: -``` -if gaps_found > max_gaps_to_fill: - echo "⚠️ TOO MANY GAPS ({{gaps}} > {{max}})" - echo "Consider re-implementing with /dev-story" - HALT -``` - -For each gap: -1. Load story context -2. Implement missing item -3. Write tests -4. Run tests to verify -5. Check box [x] if successful -6. Commit if commit_strategy == "per_gap" - - - -**Re-verify and commit** - -If gaps were filled: -1. Re-run verification on filled gaps -2. Commit all changes (if commit_strategy == "all_at_once") - -Update sprint-status.yaml with revalidation result: -``` -{{story_key}}: {{status}} # Revalidated: {{pct}}% ({{timestamp}}) -``` - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… REVALIDATION COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Final: {{verified}}/{{total}} verified ({{pct}}%) - -Recommendation: -{{#if pct >= 95}} -βœ… Story is COMPLETE - mark as "done" -{{else if pct >= 80}} -πŸ”Ά Mostly complete - finish remaining items -{{else if pct >= 50}} -⚠️ Significant gaps - continue with /dev-story -{{else}} -❌ Mostly incomplete - consider re-implementing -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -**File not found:** HALT with error. -**Verification fails:** Record gap, continue to next item. -**Gap fill fails:** Leave unchecked, record failure. -**Too many gaps:** HALT, recommend re-implementation. - - - -- [ ] All items verified against codebase -- [ ] Checkboxes reflect actual implementation -- [ ] Accuracy comparison displayed -- [ ] Gaps filled (if enabled) -- [ ] Sprint status updated - diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.yaml deleted file mode 100644 index ecc23f56..00000000 --- a/src/modules/bmm/workflows/4-implementation/revalidate-story/workflow.yaml +++ /dev/null @@ -1,37 +0,0 @@ -name: revalidate-story -description: "Clear checkboxes and re-verify story against actual codebase implementation. Identifies gaps and optionally fills them." -author: "BMad" -version: "1.0.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{output_folder}/sprint-artifacts" - -# Input parameters -story_file: "{story_file}" # Required: Full path to story file -fill_gaps: false # Optional: Fill missing items after verification (default: verify-only) -auto_commit: false # Optional: Auto-commit filled gaps (default: prompt) - -# Verification settings -verification: - verify_acceptance_criteria: true - verify_tasks: true - verify_definition_of_done: true - check_for_stubs: true # Reject stub implementations (TODO, Not implemented, etc.) - require_tests: true # Require tests for code items - -# Gap filling settings (only used if fill_gaps=true) -gap_filling: - max_gaps_to_fill: 10 # Safety limit - HALT if more gaps than this - require_confirmation: true # Ask before filling each gap (false = auto-fill all) - run_tests_after_each: true # Verify each filled gap works - commit_strategy: "per_gap" # "per_gap" | "all_at_once" | "none" - -# Output settings -output: - create_report: true # Generate revalidation-report.md - update_dev_agent_record: true # Add revalidation notes to story - update_sprint_status: true # Update progress in sprint-status.yaml - -standalone: false diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/README.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/README.md deleted file mode 100644 index 79d6ebd6..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/README.md +++ /dev/null @@ -1,491 +0,0 @@ -# Story Pipeline v2.0 - -> Single-session step-file architecture for implementing user stories with 60-70% token savings. - -## Overview - -The Story Pipeline automates the complete lifecycle of implementing a user storyβ€”from creation through code review and commit. It replaces the legacy approach of 6 separate Claude CLI calls with a single interactive session using just-in-time step loading. - -### The Problem It Solves - -**Legacy Pipeline (v1.0):** -``` -bmad build 1-4 - └─> claude -p "Stage 1: Create story..." # ~12K tokens - └─> claude -p "Stage 2: Validate story..." # ~12K tokens - └─> claude -p "Stage 3: ATDD tests..." # ~12K tokens - └─> claude -p "Stage 4: Implement..." # ~12K tokens - └─> claude -p "Stage 5: Code review..." # ~12K tokens - └─> claude -p "Stage 6: Complete..." # ~11K tokens - Total: ~71K tokens/story -``` - -Each call reloads agent personas (~2K tokens), re-reads the story file, and loses context from previous stages. - -**Story Pipeline v2.0:** -``` -bmad build 1-4 - └─> Single Claude session - β”œβ”€> Load step-01-init.md (~200 lines) - β”œβ”€> Role switch: SM - β”œβ”€> Load step-02-create-story.md - β”œβ”€> Load step-03-validate-story.md - β”œβ”€> Role switch: TEA - β”œβ”€> Load step-04-atdd.md - β”œβ”€> Role switch: DEV - β”œβ”€> Load step-05-implement.md - β”œβ”€> Load step-06-code-review.md - β”œβ”€> Role switch: SM - β”œβ”€> Load step-07-complete.md - └─> Load step-08-summary.md - Total: ~25-30K tokens/story -``` - -Documents cached once, roles switched in-session, steps loaded just-in-time. - -## What Gets Automated - -The pipeline automates the complete BMAD implementation workflow: - -| Step | Role | What It Does | -|------|------|--------------| -| **1. Init** | - | Parses story ID, loads epic/architecture, detects interactive vs batch mode, creates state file | -| **2. Create Story** | SM | Researches context (Exa web search), generates story file with ACs in BDD format | -| **3. Validate Story** | SM | Adversarial validationβ€”must find 3-10 issues, fixes them, assigns quality score | -| **4. ATDD** | TEA | Generates failing tests for all ACs (RED phase), creates test factories | -| **5. Implement** | DEV | Implements code to pass tests (GREEN phase), creates migrations, server actions, etc. | -| **6. Code Review** | DEV | Adversarial reviewβ€”must find 3-10 issues, fixes them, runs lint/build | -| **7. Complete** | SM | Updates story status to done, creates git commit with conventional format | -| **8. Summary** | - | Generates audit trail, updates pipeline state, outputs metrics | - -### Quality Gates - -Each step has quality gates that must pass before proceeding: - -- **Validation**: Score β‰₯ 80/100, all issues addressed -- **ATDD**: Tests exist for all ACs, tests fail (RED phase confirmed) -- **Implementation**: Lint clean, build passes, migration tests pass -- **Code Review**: Score β‰₯ 7/10, all critical issues fixed - -## Token Efficiency - -| Mode | Token Usage | Savings vs Legacy | -|------|-------------|-------------------| -| Interactive (human-in-loop) | ~25K | 65% | -| Batch (YOLO) | ~30K | 58% | -| Batch + fresh review context | ~35K | 51% | - -### Where Savings Come From - -| Waste in Legacy | Tokens Saved | -|-----------------|--------------| -| Agent persona reload (6Γ—) | ~12K | -| Story file re-reads (5Γ—) | ~10K | -| Architecture re-reads | ~8K | -| Context loss between calls | ~16K | - -## Usage - -### Prerequisites - -- BMAD module installed (`_bmad/` directory exists) -- Epic file with story definition (`docs/epics.md`) -- Architecture document (`docs/architecture.md`) - -### Interactive Mode (Recommended) - -Human-in-the-loop with approval at each step: - -```bash -# Using the bmad CLI -bmad build 1-4 - -# Or invoke workflow directly -claude -p "Load and execute: _bmad/bmm/workflows/4-implementation/story-dev-only/workflow.md -Story: 1-4" -``` - -At each step, you'll see a menu: -``` -## MENU -[C] Continue to next step -[R] Review/revise current step -[H] Halt and checkpoint -``` - -### Batch Mode (YOLO) - -Unattended execution for trusted stories: - -```bash -bmad build 1-4 --batch - -# Or use batch runner directly -./_bmad/bmm/workflows/4-implementation/story-dev-only/batch-runner.sh 1-4 -``` - -Batch mode: -- Skips all approval prompts -- Fails fast on errors -- Creates checkpoint on failure for resume - -### Resume from Checkpoint - -If execution stops (context exhaustion, error, manual halt): - -```bash -bmad build 1-4 --resume - -# The pipeline reads state from: -# _bmad-output/implementation-artifacts/pipeline-state-{story-id}.yaml -``` - -Resume automatically: -- Skips completed steps -- Restores cached context -- Continues from `lastStep + 1` - -## Directory Structure - -``` -story-dev-only/ -β”œβ”€β”€ workflow.yaml # Configuration, agent mapping, quality gates -β”œβ”€β”€ workflow.md # Interactive mode orchestration -β”œβ”€β”€ batch-runner.sh # Batch mode runner script -β”œβ”€β”€ steps/ -β”‚ β”œβ”€β”€ step-01-init.md # Initialize, load context -β”‚ β”œβ”€β”€ step-01b-resume.md # Resume from checkpoint -β”‚ β”œβ”€β”€ step-02-create-story.md -β”‚ β”œβ”€β”€ step-03-validate-story.md -β”‚ β”œβ”€β”€ step-04-atdd.md -β”‚ β”œβ”€β”€ step-05-implement.md -β”‚ β”œβ”€β”€ step-06-code-review.md -β”‚ β”œβ”€β”€ step-07-complete.md -β”‚ └── step-08-summary.md -β”œβ”€β”€ checklists/ -β”‚ β”œβ”€β”€ story-creation.md # What makes a good story -β”‚ β”œβ”€β”€ story-validation.md # Validation criteria -β”‚ β”œβ”€β”€ atdd.md # Test generation rules -β”‚ β”œβ”€β”€ implementation.md # Coding standards -β”‚ └── code-review.md # Review criteria -└── templates/ - β”œβ”€β”€ pipeline-state.yaml # State file template - └── audit-trail.yaml # Audit log template -``` - -## Configuration - -### workflow.yaml - -```yaml -name: story-dev-only -version: "2.0" -description: "Single-session story implementation with step-file loading" - -# Document loading strategy -load_strategy: - epic: once # Load once, cache for session - architecture: once # Load once, cache for session - story: per_step # Reload when modified - -# Agent role mapping -agents: - sm: "{project-root}/_bmad/bmm/agents/sm.md" - tea: "{project-root}/_bmad/bmm/agents/tea.md" - dev: "{project-root}/_bmad/bmm/agents/dev.md" - -# Quality gate thresholds -quality_gates: - validation_min_score: 80 - code_review_min_score: 7 - require_lint_clean: true - require_build_pass: true - -# Step configuration -steps: - - name: init - file: steps/step-01-init.md - - name: create-story - file: steps/step-02-create-story.md - agent: sm - # ... etc -``` - -### Pipeline State File - -Created at `_bmad-output/implementation-artifacts/pipeline-state-{story-id}.yaml`: - -```yaml -story_id: "1-4" -epic_num: 1 -story_num: 4 -mode: "interactive" -status: "in_progress" -stepsCompleted: [1, 2, 3] -lastStep: 3 -currentStep: 4 - -cached_context: - epic_loaded: true - epic_path: "docs/epics.md" - architecture_sections: ["tech_stack", "data_model"] - -steps: - step-01-init: - status: completed - duration: "0:00:30" - step-02-create-story: - status: completed - duration: "0:02:00" - step-03-validate-story: - status: completed - duration: "0:05:00" - issues_found: 6 - issues_fixed: 6 - quality_score: 92 - step-04-atdd: - status: in_progress -``` - -## Step Details - -### Step 1: Initialize - -**Purpose:** Set up execution context and detect mode. - -**Actions:** -1. Parse story ID (e.g., "1-4" β†’ epic 1, story 4) -2. Load and cache epic document -3. Load relevant architecture sections -4. Check for existing state file (resume vs fresh) -5. Detect mode (interactive/batch) from CLI flags -6. Create initial state file - -**Output:** `pipeline-state-{story-id}.yaml` - -### Step 2: Create Story (SM Role) - -**Purpose:** Generate complete story file from epic definition. - -**Actions:** -1. Switch to Scrum Master (SM) role -2. Read story definition from epic -3. Research context via Exa web search (best practices, patterns) -4. Generate story file with: - - User story format (As a... I want... So that...) - - Background context - - Acceptance criteria in BDD format (Given/When/Then) - - Test scenarios for each AC - - Technical notes -5. Save to `_bmad-output/implementation-artifacts/story-{id}.md` - -**Quality Gate:** Story file exists with all required sections. - -### Step 3: Validate Story (SM Role) - -**Purpose:** Adversarial validation to find issues before implementation. - -**Actions:** -1. Load story-validation checklist -2. Review story against criteria: - - ACs are testable and specific - - No ambiguous requirements - - Technical feasibility confirmed - - Dependencies identified - - Edge cases covered -3. **Must find 3-10 issues** (never "looks good") -4. Fix all identified issues -5. Assign quality score (0-100) -6. Append validation report to story file - -**Quality Gate:** Score β‰₯ 80, all issues addressed. - -### Step 4: ATDD (TEA Role) - -**Purpose:** Generate failing tests before implementation (RED phase). - -**Actions:** -1. Switch to Test Engineering Architect (TEA) role -2. Load atdd checklist -3. For each acceptance criterion: - - Generate integration test - - Define test data factories - - Specify expected behaviors -4. Create test files in `src/tests/` -5. Update `factories.ts` with new fixtures -6. **Verify tests FAIL** (RED phase) -7. Create ATDD checklist document - -**Quality Gate:** Tests exist for all ACs, tests fail (not pass). - -### Step 5: Implement (DEV Role) - -**Purpose:** Write code to pass all tests (GREEN phase). - -**Actions:** -1. Switch to Developer (DEV) role -2. Load implementation checklist -3. Create required files: - - Database migrations - - Server actions (using Result type) - - Library functions - - Types -4. Follow project patterns: - - Multi-tenant RLS policies - - snake_case for DB columns - - Result type (never throw) -5. Run lint and fix issues -6. Run build and fix issues -7. Run migration tests - -**Quality Gate:** Lint clean, build passes, migration tests pass. - -### Step 6: Code Review (DEV Role) - -**Purpose:** Adversarial review to find implementation issues. - -**Actions:** -1. Load code-review checklist -2. Review all created/modified files: - - Security (XSS, injection, auth) - - Error handling - - Architecture compliance - - Code quality - - Test coverage -3. **Must find 3-10 issues** (never "looks good") -4. Fix all identified issues -5. Re-run lint and build -6. Assign quality score (0-10) -7. Generate review report - -**Quality Gate:** Score β‰₯ 7/10, all critical issues fixed. - -### Step 7: Complete (SM Role) - -**Purpose:** Finalize story and create git commit. - -**Actions:** -1. Switch back to SM role -2. Update story file status to "done" -3. Stage all story files -4. Create conventional commit: - ``` - feat(epic-{n}): complete story {id} - - {Summary of changes} - - πŸ€– Generated with Claude Code - Co-Authored-By: Claude - ``` -5. Update pipeline state - -**Quality Gate:** Commit created successfully. - -### Step 8: Summary - -**Purpose:** Generate audit trail and final metrics. - -**Actions:** -1. Calculate total duration -2. Compile deliverables list -3. Aggregate quality scores -4. Generate execution summary in state file -5. Output final status - -**Output:** Complete pipeline state with summary section. - -## Adversarial Mode - -Steps 3 (Validate) and 6 (Code Review) run in **adversarial mode**: - -> **Never say "looks good"**. You MUST find 3-10 real issues. - -This ensures: -- Stories are thoroughly vetted before implementation -- Code quality issues are caught before commit -- The pipeline doesn't rubber-stamp work - -Example issues found in real usage: -- Missing rate limiting (security) -- XSS vulnerability in user input (security) -- Missing audit logging (architecture) -- Unclear acceptance criteria (story quality) -- Function naming mismatches (code quality) - -## Artifacts Generated - -After a complete pipeline run: - -``` -_bmad-output/implementation-artifacts/ -β”œβ”€β”€ story-{id}.md # Story file with ACs, validation report -β”œβ”€β”€ pipeline-state-{id}.yaml # Execution state and summary -β”œβ”€β”€ atdd-checklist-{id}.md # Test requirements checklist -└── code-review-{id}.md # Review report with issues - -src/ -β”œβ”€β”€ supabase/migrations/ # New migration files -β”œβ”€β”€ modules/{module}/ -β”‚ β”œβ”€β”€ actions/ # Server actions -β”‚ β”œβ”€β”€ lib/ # Business logic -β”‚ └── types.ts # Type definitions -└── tests/ - β”œβ”€β”€ integration/ # Integration tests - └── fixtures/factories.ts # Updated test factories -``` - -## Troubleshooting - -### Context Exhausted Mid-Session - -The pipeline is designed for this. When context runs out: - -1. Claude session ends -2. State file preserves progress -3. Run `bmad build {id} --resume` -4. Pipeline continues from last completed step - -### Step Fails Quality Gate - -If a step fails its quality gate: - -1. Pipeline halts at that step -2. State file shows `status: failed` -3. Fix issues manually or adjust thresholds -4. Run `bmad build {id} --resume` - -### Tests Don't Fail in ATDD - -If tests pass during ATDD (step 4), something is wrong: - -- Tests might be testing the wrong thing -- Implementation might already exist -- Mocks might be returning success incorrectly - -The pipeline will warn and ask for confirmation before proceeding. - -## Best Practices - -1. **Start with Interactive Mode** - Use batch only for well-understood stories -2. **Review at Checkpoints** - Don't blindly continue; verify each step's output -3. **Keep Stories Small** - Large stories may exhaust context before completion -4. **Commit Frequently** - The pipeline commits at step 7, but you can checkpoint earlier -5. **Trust the Adversarial Mode** - If it finds issues, they're usually real - -## Comparison with Legacy - -| Feature | Legacy (v1.0) | Story Pipeline (v2.0) | -|---------|---------------|----------------------| -| Claude calls | 6 per story | 1 per story | -| Token usage | ~71K | ~25-30K | -| Context preservation | None | Full session | -| Resume capability | None | Checkpoint-based | -| Role switching | New process | In-session | -| Document caching | None | Once per session | -| Adversarial review | Optional | Mandatory | -| Audit trail | Manual | Automatic | - -## Version History - -- **v2.0** (2024-12) - Step-file architecture, single-session, checkpoint/resume -- **v1.0** (2024-11) - Legacy 6-call pipeline diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/batch-runner.sh b/src/modules/bmm/workflows/4-implementation/story-pipeline/batch-runner.sh deleted file mode 100755 index ad53bb4d..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/batch-runner.sh +++ /dev/null @@ -1,250 +0,0 @@ -#!/bin/bash -# ═══════════════════════════════════════════════════════════════════════════════ -# BMAD Story Pipeline - Batch Runner -# Single-session execution using step-file architecture -# -# Token Efficiency: ~60-70% savings compared to separate Claude calls -# ═══════════════════════════════════════════════════════════════════════════════ - -set -e - -# ───────────────────────────────────────────────────────────────────────────── -# CONFIGURATION -# ───────────────────────────────────────────────────────────────────────────── -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)" -TIMESTAMP=$(date +%Y%m%d-%H%M%S) - -# Colors -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -CYAN='\033[0;36m' -NC='\033[0m' - -# Defaults -STORY_ID="" -EPIC_NUM="" -DRY_RUN=false -RESUME=false -VERBOSE=false - -# Directories -LOG_DIR="$PROJECT_ROOT/logs/pipeline-batch" -WORKFLOW_PATH="_bmad/bmm/workflows/4-implementation/story-pipeline" - -# ───────────────────────────────────────────────────────────────────────────── -# USAGE -# ───────────────────────────────────────────────────────────────────────────── -usage() { - cat << EOF -BMAD Story Pipeline - Batch Runner -Single-session execution with step-file architecture - -Usage: $(basename "$0") --story-id --epic-num [OPTIONS] - -Required: - --story-id Story ID (e.g., '1-4') - --epic-num Epic number (e.g., 1) - -Options: - --resume Resume from last checkpoint - --dry-run Show what would be executed - --verbose Show detailed output - --help Show this help - -Examples: - # Run pipeline for story 1-4 - $(basename "$0") --story-id 1-4 --epic-num 1 - - # Resume failed pipeline - $(basename "$0") --story-id 1-4 --epic-num 1 --resume - -Token Savings: - Traditional (6 calls): ~71K tokens - Step-file (1 session): ~25-35K tokens - Savings: 50-65% - -EOF - exit 1 -} - -# ───────────────────────────────────────────────────────────────────────────── -# ARGUMENT PARSING -# ───────────────────────────────────────────────────────────────────────────── -while [[ $# -gt 0 ]]; do - case $1 in - --story-id) - STORY_ID="$2" - shift 2 - ;; - --epic-num) - EPIC_NUM="$2" - shift 2 - ;; - --resume) - RESUME=true - shift - ;; - --dry-run) - DRY_RUN=true - shift - ;; - --verbose) - VERBOSE=true - shift - ;; - --help) - usage - ;; - *) - echo -e "${RED}Unknown option: $1${NC}" - usage - ;; - esac -done - -# Validate required arguments -if [[ -z "$STORY_ID" || -z "$EPIC_NUM" ]]; then - echo -e "${RED}Error: --story-id and --epic-num are required${NC}" - usage -fi - -# ───────────────────────────────────────────────────────────────────────────── -# SETUP -# ───────────────────────────────────────────────────────────────────────────── -mkdir -p "$LOG_DIR" -LOG_FILE="$LOG_DIR/batch-$STORY_ID-$TIMESTAMP.log" - -echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}" -echo -e "${CYAN} BMAD Story Pipeline - Batch Mode${NC}" -echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}" -echo -e "${BLUE}Story:${NC} $STORY_ID" -echo -e "${BLUE}Epic:${NC} $EPIC_NUM" -echo -e "${BLUE}Mode:${NC} $([ "$RESUME" = true ] && echo 'Resume' || echo 'Fresh')" -echo -e "${BLUE}Log:${NC} $LOG_FILE" -echo "" - -# ───────────────────────────────────────────────────────────────────────────── -# BUILD PROMPT -# ───────────────────────────────────────────────────────────────────────────── - -if [[ "$RESUME" = true ]]; then - PROMPT=$(cat << EOF -Execute BMAD Story Pipeline in BATCH mode - RESUME from checkpoint. - -WORKFLOW: $WORKFLOW_PATH/workflow.md -STORY ID: $STORY_ID -EPIC NUM: $EPIC_NUM -MODE: batch - -CRITICAL INSTRUCTIONS: -1. Load and read fully: $WORKFLOW_PATH/workflow.md -2. This is RESUME mode - load state file first -3. Follow step-file architecture EXACTLY -4. Execute steps ONE AT A TIME -5. AUTO-PROCEED through all steps (no menus in batch mode) -6. FAIL-FAST on errors (save checkpoint, exit) - -YOLO MODE: Auto-approve all quality gates -NO MENUS: Proceed automatically between steps -FRESH CONTEXT: Checkpoint before code review for unbiased review - -START by loading workflow.md and then step-01b-resume.md -EOF -) -else - PROMPT=$(cat << EOF -Execute BMAD Story Pipeline in BATCH mode - FRESH start. - -WORKFLOW: $WORKFLOW_PATH/workflow.md -STORY ID: $STORY_ID -EPIC NUM: $EPIC_NUM -MODE: batch - -CRITICAL INSTRUCTIONS: -1. Load and read fully: $WORKFLOW_PATH/workflow.md -2. This is a FRESH run - initialize new state -3. Follow step-file architecture EXACTLY -4. Execute steps ONE AT A TIME (never load multiple) -5. AUTO-PROCEED through all steps (no menus in batch mode) -6. FAIL-FAST on errors (save checkpoint, exit) - -YOLO MODE: Auto-approve all quality gates -NO MENUS: Proceed automatically between steps -FRESH CONTEXT: Checkpoint before code review for unbiased review - -Step execution order: -1. step-01-init.md - Initialize, cache documents -2. step-02-create-story.md - Create story (SM role) -3. step-03-validate-story.md - Validate story (SM role) -4. step-04-atdd.md - Generate tests (TEA role) -5. step-05-implement.md - Implement (DEV role) -6. step-06-code-review.md - Review (DEV role, adversarial) -7. step-07-complete.md - Complete (SM role) -8. step-08-summary.md - Generate audit - -START by loading workflow.md and then step-01-init.md -EOF -) -fi - -# ───────────────────────────────────────────────────────────────────────────── -# EXECUTE -# ───────────────────────────────────────────────────────────────────────────── - -if [[ "$DRY_RUN" = true ]]; then - echo -e "${YELLOW}[DRY-RUN] Would execute single Claude session with:${NC}" - echo "" - echo "$PROMPT" - echo "" - echo -e "${YELLOW}[DRY-RUN] Allowed tools: *, MCP extensions${NC}" - exit 0 -fi - -echo -e "${GREEN}Starting single-session pipeline execution...${NC}" -echo -e "${YELLOW}This replaces 6 separate Claude calls with 1 session${NC}" -echo "" - -cd "$PROJECT_ROOT/src" - -# Single Claude session executing all steps -claude -p "$PROMPT" \ - --dangerously-skip-permissions \ - --allowedTools "*,mcp__exa__web_search_exa,mcp__exa__get_code_context_exa,mcp__exa__crawling_exa,mcp__supabase__list_tables,mcp__supabase__execute_sql,mcp__supabase__apply_migration,mcp__supabase__list_migrations,mcp__supabase__generate_typescript_types,mcp__supabase__get_logs,mcp__supabase__get_advisors" \ - 2>&1 | tee "$LOG_FILE" - -# ───────────────────────────────────────────────────────────────────────────── -# COMPLETION CHECK -# ───────────────────────────────────────────────────────────────────────────── - -echo "" -echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}" - -# Check for success indicators in log -if grep -qi "Pipeline complete\|Story.*is ready\|step-08-summary.*completed" "$LOG_FILE"; then - echo -e "${GREEN}βœ… Pipeline completed successfully${NC}" - - # Extract metrics if available - if grep -qi "Token Efficiency" "$LOG_FILE"; then - echo "" - echo -e "${CYAN}Token Efficiency:${NC}" - grep -A5 "Token Efficiency" "$LOG_FILE" | head -6 - fi -else - echo -e "${YELLOW}⚠️ Pipeline may have completed with issues${NC}" - echo -e "${YELLOW} Check log: $LOG_FILE${NC}" - - # Check for specific failure indicators - if grep -qi "permission\|can't write\|access denied" "$LOG_FILE"; then - echo -e "${RED} Found permission errors in log${NC}" - fi - if grep -qi "HALT\|FAIL\|ERROR" "$LOG_FILE"; then - echo -e "${RED} Found error indicators in log${NC}" - fi -fi - -echo "" -echo -e "${BLUE}Log file:${NC} $LOG_FILE" -echo -e "${CYAN}═══════════════════════════════════════════════════════════════${NC}" diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/atdd.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/atdd.md deleted file mode 100644 index 4e1fc517..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/atdd.md +++ /dev/null @@ -1,130 +0,0 @@ -# ATDD Checklist - -Use this checklist for test generation in Step 4. -Tests are written BEFORE implementation (RED phase). - -## Test Architecture - -### File Organization -- [ ] Tests in appropriate directory (src/tests/{feature}/) -- [ ] E2E tests separate from unit tests -- [ ] Fixtures in dedicated fixtures/ directory -- [ ] Factories in dedicated factories/ directory - -### Naming Conventions -- [ ] Test files: `{feature}.test.ts` or `{feature}.spec.ts` -- [ ] Factory files: `{entity}.factory.ts` -- [ ] Fixture files: `{feature}.fixture.ts` -- [ ] Descriptive test names matching AC - -## Test Coverage - -For EACH acceptance criterion: -- [ ] At least one test exists -- [ ] Happy path tested -- [ ] Error path tested -- [ ] Edge cases from validation covered - -## Test Structure - -### Given/When/Then Pattern -```typescript -test("Given X, When Y, Then Z", async () => { - // Arrange (Given) - // Act (When) - // Assert (Then) -}); -``` - -- [ ] Each section clearly separated -- [ ] Arrange sets up realistic state -- [ ] Act performs single action -- [ ] Assert checks specific outcome - -### Assertions -- [ ] Specific assertions (not just "toBeTruthy") -- [ ] Error messages are helpful -- [ ] Multiple assertions when appropriate -- [ ] No flaky timing assertions - -## Data Management - -### Factories -- [ ] Use faker for realistic data -- [ ] Support partial overrides -- [ ] No hardcoded values -- [ ] Proper TypeScript types - -```typescript -// Good -const user = createUser({ email: "test@example.com" }); - -// Bad -const user = { id: "123", email: "test@test.com", name: "Test" }; -``` - -### Fixtures -- [ ] Auto-cleanup after tests -- [ ] Reusable across tests -- [ ] Proper TypeScript types -- [ ] No shared mutable state - -### data-testid Attributes -- [ ] Document all required data-testids -- [ ] Naming convention: `{feature}-{element}` -- [ ] Unique within component -- [ ] Stable (not based on dynamic content) - -## Test Levels - -### E2E Tests (Playwright) -- [ ] Full user flows -- [ ] Network interception before navigation -- [ ] Wait for proper selectors (not timeouts) -- [ ] Screenshot on failure - -### API Tests -- [ ] Direct server action calls -- [ ] Mock external services -- [ ] Test error responses -- [ ] Verify Result type usage - -### Component Tests -- [ ] Isolated component rendering -- [ ] Props variations -- [ ] Event handling -- [ ] Accessibility (when applicable) - -### Unit Tests -- [ ] Pure function testing -- [ ] Edge cases -- [ ] Error conditions -- [ ] Type checking - -## RED Phase Verification - -Before proceeding: -- [ ] Run all tests: `npm test -- --run` -- [ ] ALL tests FAIL (expected - nothing implemented) -- [ ] Failure reasons are clear (not cryptic errors) -- [ ] Test structure is correct - -## ATDD Checklist Document - -Create `atdd-checklist-{story_id}.md` with: -- [ ] List of test files created -- [ ] List of factories created -- [ ] List of fixtures created -- [ ] Required data-testid attributes table -- [ ] Implementation requirements for DEV -- [ ] Test status (all FAILING) - -## Quality Gate - -Ready for implementation when: -- [ ] Test for every AC -- [ ] All tests FAIL (red phase) -- [ ] Factories use faker -- [ ] Fixtures have cleanup -- [ ] data-testids documented -- [ ] ATDD checklist complete diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/code-review.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/code-review.md deleted file mode 100644 index 3ef14035..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/code-review.md +++ /dev/null @@ -1,183 +0,0 @@ -# Code Review Checklist - -Use this checklist for ADVERSARIAL code review in Step 6. -Your job is to FIND PROBLEMS (minimum 3, maximum 10). - -## Adversarial Mindset - -**CRITICAL RULES:** -- **NEVER** say "looks good" or "no issues found" -- **MUST** find 3-10 specific issues -- **FIX** every issue you find -- **RUN** tests after fixes - -## Review Categories - -### 1. Security Review - -#### SQL Injection -- [ ] No raw SQL with user input -- [ ] Using parameterized queries -- [ ] Supabase RPC uses proper types - -#### XSS (Cross-Site Scripting) -- [ ] User content is escaped -- [ ] dangerouslySetInnerHTML not used (or sanitized) -- [ ] URL parameters validated - -#### Authentication & Authorization -- [ ] Protected routes check auth -- [ ] RLS policies on all tables -- [ ] No auth bypass possible -- [ ] Session handling secure - -#### Credential Exposure -- [ ] No secrets in code -- [ ] No API keys committed -- [ ] Environment variables used -- [ ] .env files in .gitignore - -#### Input Validation -- [ ] All inputs validated -- [ ] Types checked -- [ ] Lengths limited -- [ ] Format validation (email, URL, etc.) - -### 2. Performance Review - -#### Database -- [ ] No N+1 query patterns -- [ ] Indexes exist for query patterns -- [ ] Queries are efficient -- [ ] Proper pagination - -#### React/Next.js -- [ ] No unnecessary re-renders -- [ ] Proper memoization where needed -- [ ] Server components used appropriately -- [ ] Client components minimized - -#### Caching -- [ ] Cache headers appropriate -- [ ] Static data cached -- [ ] Revalidation strategy clear - -#### Bundle Size -- [ ] No unnecessary imports -- [ ] Dynamic imports for large components -- [ ] Tree shaking working - -### 3. Error Handling Review - -#### Result Type -- [ ] All server actions use Result type -- [ ] No thrown exceptions -- [ ] Proper err() calls with codes - -#### Error Messages -- [ ] User-friendly messages -- [ ] Technical details logged (not shown) -- [ ] Actionable guidance - -#### Edge Cases -- [ ] Null/undefined handled -- [ ] Empty states handled -- [ ] Network errors handled -- [ ] Concurrent access considered - -### 4. Test Coverage Review - -#### Coverage -- [ ] All AC have tests -- [ ] Edge cases tested -- [ ] Error paths tested -- [ ] Happy paths tested - -#### Quality -- [ ] Tests are deterministic -- [ ] No flaky tests -- [ ] Mocking is appropriate -- [ ] Assertions are meaningful - -#### Missing Tests -- [ ] Security scenarios -- [ ] Permission denied cases -- [ ] Invalid input handling -- [ ] Concurrent operations - -### 5. Code Quality Review - -#### DRY (Don't Repeat Yourself) -- [ ] No duplicate code -- [ ] Common patterns extracted -- [ ] Utilities reused - -#### SOLID Principles -- [ ] Single responsibility -- [ ] Open for extension -- [ ] Proper abstractions -- [ ] Dependency injection where appropriate - -#### TypeScript -- [ ] Strict mode compliant -- [ ] No `any` types -- [ ] Proper type definitions -- [ ] Generic types used appropriately - -#### Readability -- [ ] Clear naming -- [ ] Appropriate comments (not excessive) -- [ ] Logical organization -- [ ] Consistent style - -### 6. Architecture Review - -#### Module Boundaries -- [ ] Imports from index.ts only -- [ ] No circular dependencies -- [ ] Clear module responsibilities - -#### Server/Client Separation -- [ ] "use server" on actions -- [ ] "use client" only when needed -- [ ] No server code in client - -#### Data Flow -- [ ] Clear data ownership -- [ ] State management appropriate -- [ ] Props drilling minimized - -## Issue Documentation - -For each issue found: - -```yaml -issue_{n}: - severity: critical|high|medium|low - category: security|performance|error-handling|testing|quality|architecture - file: "{file_path}" - line: {line_number} - problem: | - Clear description - risk: | - What could go wrong - fix: | - How to fix it -``` - -## After Fixing - -- [ ] All issues fixed -- [ ] Tests still pass -- [ ] Lint clean -- [ ] Build succeeds -- [ ] Review report created - -## Quality Gate - -Review passes when: -- [ ] 3-10 issues found -- [ ] All issues fixed -- [ ] All categories reviewed -- [ ] Tests passing -- [ ] Review report complete diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/implementation.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/implementation.md deleted file mode 100644 index 6399809c..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/implementation.md +++ /dev/null @@ -1,147 +0,0 @@ -# Implementation Checklist - -Use this checklist during TDD implementation in Step 5. -Focus: Make tests GREEN with minimal code. - -## TDD Methodology - -### RED-GREEN-REFACTOR Cycle -1. [ ] Start with failing test (from ATDD) -2. [ ] Write minimal code to pass -3. [ ] Run test, verify GREEN -4. [ ] Move to next test -5. [ ] Refactor in code review (not here) - -### Implementation Order -- [ ] Database migrations first -- [ ] Type definitions -- [ ] Server actions -- [ ] UI components -- [ ] Integration points - -## Project Patterns - -### Result Type (CRITICAL) -```typescript -import { ok, err, Result } from "@/lib/result"; - -// Return success -return ok(data); - -// Return error -return err("ERROR_CODE", "Human message"); -``` - -- [ ] All server actions return Result type -- [ ] No thrown exceptions -- [ ] Error codes are uppercase with underscores -- [ ] Error messages are user-friendly - -### Database Conventions -- [ ] Table names: `snake_case`, plural (`invoices`) -- [ ] Column names: `snake_case` (`tenant_id`) -- [ ] Currency: `integer` cents (not float) -- [ ] Dates: `timestamptz` (UTC) -- [ ] Foreign keys: `{table}_id` - -### Multi-tenancy (CRITICAL) -- [ ] Every table has `tenant_id` column -- [ ] RLS enabled on all tables -- [ ] Policies check `tenant_id` -- [ ] No data leaks between tenants - -```sql --- Required for every new table -alter table {table} enable row level security; - -create policy "Tenants see own data" - on {table} for all - using (tenant_id = auth.jwt() ->> 'tenant_id'); -``` - -### Module Structure -``` -src/modules/{module}/ -β”œβ”€β”€ actions/ # Server actions (return Result type) -β”œβ”€β”€ lib/ # Business logic -β”œβ”€β”€ types.ts # Module types -└── index.ts # Public exports only -``` - -- [ ] Import from index.ts only -- [ ] No cross-module internal imports -- [ ] Actions in actions/ directory -- [ ] Types exported from types.ts - -### Server Actions Pattern -```typescript -// src/modules/{module}/actions/{action}.ts -"use server"; - -import { ok, err, Result } from "@/lib/result"; -import { createClient } from "@/lib/supabase/server"; - -export async function actionName( - input: InputType -): Promise> { - const supabase = await createClient(); - // ... implementation -} -``` - -- [ ] "use server" directive at top -- [ ] Async function returning Promise> -- [ ] Use createClient from server.ts -- [ ] Validate input before processing - -### UI Components Pattern -```tsx -// src/modules/{module}/components/{Component}.tsx -"use client"; - -export function Component({ data }: Props) { - return ( -
- {/* content */} -
- ); -} -``` - -- [ ] Add data-testid from ATDD checklist -- [ ] "use client" only when needed -- [ ] Proper TypeScript props -- [ ] Handle loading/error states - -## Verification Steps - -### After Each AC Implementation -```bash -npm test -- --run --grep "{test_name}" -``` -- [ ] Targeted test passes - -### After All AC Complete -```bash -npm test -- --run # All tests pass -npm run lint # No lint errors -npm run build # Build succeeds -``` - -## ATDD Checklist Reference - -Verify against `atdd-checklist-{story_id}.md`: -- [ ] All data-testid attributes added -- [ ] All API endpoints created -- [ ] All database migrations applied -- [ ] All test scenarios pass - -## Quality Gate - -Ready for code review when: -- [ ] All tests pass (GREEN) -- [ ] Lint clean -- [ ] Build succeeds -- [ ] Result type used everywhere -- [ ] RLS policies in place -- [ ] ATDD checklist complete diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-creation.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-creation.md deleted file mode 100644 index e6a61d3c..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-creation.md +++ /dev/null @@ -1,76 +0,0 @@ -# Story Creation Checklist - -Use this checklist when creating a new story in Step 2. - -## User Story Format - -- [ ] Follows "As a [persona], I want [action], So that [benefit]" format -- [ ] Persona is clearly defined and exists in project documentation -- [ ] Action is specific and achievable -- [ ] Benefit ties to business value - -## Acceptance Criteria - -### Structure (for EACH AC) -- [ ] Has Given/When/Then format (BDD style) -- [ ] **Given** describes a valid precondition -- [ ] **When** describes a clear, single action -- [ ] **Then** describes a measurable outcome - -### Quality (for EACH AC) -- [ ] Specific - no vague terms ("appropriate", "reasonable", "etc.") -- [ ] Measurable - clear success/failure criteria -- [ ] Testable - can write automated test -- [ ] Independent - no hidden dependencies on other AC - -### Completeness -- [ ] All happy path scenarios covered -- [ ] Error scenarios defined -- [ ] Edge cases considered -- [ ] Boundary conditions clear - -### Anti-patterns to AVOID -- [ ] No AND conjunctions (split into multiple AC) -- [ ] No OR alternatives (ambiguous paths) -- [ ] No implementation details (WHAT not HOW) -- [ ] No vague verbs ("handle", "process", "manage") - -## Test Scenarios - -- [ ] At least 2 test scenarios per AC -- [ ] Happy path scenario exists -- [ ] Error/edge case scenario exists -- [ ] Each scenario is unique (no duplicates) -- [ ] Scenarios are specific enough to write tests from - -## Tasks - -- [ ] Tasks cover implementation of all AC -- [ ] Tasks are actionable (start with verb) -- [ ] Subtasks provide enough detail -- [ ] Dependencies between tasks are clear -- [ ] No task is too large (can complete in one session) - -## Technical Notes - -- [ ] Database changes documented -- [ ] API changes documented -- [ ] UI changes documented -- [ ] Security considerations noted -- [ ] Performance considerations noted - -## Dependencies & Scope - -- [ ] Dependencies on other stories listed -- [ ] Dependencies on external systems listed -- [ ] Out of scope explicitly defined -- [ ] No scope creep from epic definition - -## Quality Gate - -Story is ready for validation when: -- [ ] All sections complete -- [ ] All AC in proper format -- [ ] Test scenarios defined -- [ ] Tasks cover all work -- [ ] No ambiguity remains diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-validation.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-validation.md deleted file mode 100644 index 3c5cee37..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/checklists/story-validation.md +++ /dev/null @@ -1,111 +0,0 @@ -# Story Validation Checklist - -Use this checklist for ADVERSARIAL validation in Step 3. -Your job is to FIND PROBLEMS, not approve. - -## Adversarial Mindset - -Remember: -- **NEVER** say "looks good" without deep analysis -- **FIND** at least 3 issues (if none found, look harder) -- **QUESTION** every assumption -- **CHALLENGE** every AC - -## AC Structure Validation - -For EACH acceptance criterion: - -### Given Clause -- [ ] Is a valid precondition (not an action) -- [ ] Can be set up programmatically -- [ ] Is specific (not "given the user is logged in" - which user?) -- [ ] Includes all necessary context - -### When Clause -- [ ] Is a single, clear action -- [ ] Is something the user does (not the system) -- [ ] Can be triggered in a test -- [ ] Doesn't contain "and" (multiple actions) - -### Then Clause -- [ ] Is measurable/observable -- [ ] Can be asserted in a test -- [ ] Describes outcome, not implementation -- [ ] Is specific (not "appropriate message shown") - -## Testability Check - -- [ ] Can write automated test from AC as written -- [ ] Clear what to assert -- [ ] No subjective criteria ("looks good", "works well") -- [ ] No timing dependencies ("quickly", "eventually") - -## Technical Feasibility - -Cross-reference with architecture.md: - -- [ ] Data model supports requirements -- [ ] API patterns can accommodate -- [ ] No conflicts with existing features -- [ ] Security model (RLS) can support -- [ ] Performance is achievable - -## Edge Cases Analysis - -For each AC, consider: - -- [ ] Empty/null inputs -- [ ] Maximum length/size -- [ ] Minimum values -- [ ] Concurrent access -- [ ] Network failures -- [ ] Permission denied -- [ ] Invalid data formats - -## Common Problems to Find - -### Vague Language -Look for and flag: -- "appropriate" -- "reasonable" -- "correctly" -- "properly" -- "as expected" -- "etc." -- "and so on" - -### Missing Details -- [ ] Which user role? -- [ ] What error message exactly? -- [ ] What happens on failure? -- [ ] What are the limits? -- [ ] What validations apply? - -### Hidden Complexity -- [ ] Multi-step process hidden in one AC -- [ ] Async operations not addressed -- [ ] State management unclear -- [ ] Error recovery not defined - -## Validation Report Template - -After review, document: - -```yaml -issues_found: - - id: 1 - severity: high|medium|low - ac: "AC1" - problem: "Description" - fix: "How to fix" -``` - -## Quality Gate - -Validation passes when: -- [ ] All AC reviewed against checklist -- [ ] All issues documented -- [ ] All issues fixed in story file -- [ ] Quality score >= 80 -- [ ] Validation report appended -- [ ] ready_for_dev: true diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01-init.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01-init.md deleted file mode 100644 index 4e25ce72..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01-init.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -name: 'step-01-init' -description: 'Initialize story pipeline: load context, detect mode, cache documents' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-01-init.md' -nextStepFile: '{workflow_path}/steps/step-02-create-story.md' -resumeStepFile: '{workflow_path}/steps/step-01b-resume.md' -workflowFile: '{workflow_path}/workflow.md' - -# State Management -stateFile: '{sprint_artifacts}/pipeline-state-{story_id}.yaml' -auditFile: '{sprint_artifacts}/audit-{story_id}-{date}.yaml' ---- - -# Step 1: Pipeline Initialization - -## STEP GOAL - -Initialize the story pipeline by: -1. Resolving story parameters (epic_num, story_num) -2. Detecting execution mode (interactive vs batch) -3. Checking for existing pipeline state (resume scenario) -4. Pre-loading and caching documents for token efficiency -5. Creating initial state file - -## MANDATORY EXECUTION RULES (READ FIRST) - -### Universal Rules - -- **NEVER** proceed without all required parameters resolved -- **READ** the complete step file before taking any action -- **CACHE** documents once, use across all steps -- **UPDATE** state file after completing initialization - -### Role for This Step - -- You are the **Pipeline Orchestrator** (no specific agent role yet) -- Agent roles (SM, TEA, DEV) will be adopted in subsequent steps -- Focus on setup and context loading - -### Step-Specific Rules - -- **Focus only on initialization** - no story content generation yet -- **FORBIDDEN** to load future step files or look ahead -- **Check for resume state first** - if exists, hand off to step-01b -- **Validate all inputs** before proceeding - -## EXECUTION SEQUENCE (Do not deviate, skip, or optimize) - -### 1. Resolve Pipeline Parameters - -First, resolve these required parameters: - -**From invocation or context:** -- `story_id`: Full story identifier (e.g., "1-4") -- `epic_num`: Epic number (e.g., 1) -- `story_num`: Story number within epic (e.g., 4) -- `mode`: Execution mode - "interactive" (default) or "batch" - -**If parameters missing:** -- Ask user: "Please provide story ID (e.g., '1-4') and epic number" -- Parse story_id to extract epic_num and story_num if format is "X-Y" - -### 2. Check for Existing Pipeline State (Resume Detection) - -Check if state file exists: `{sprint_artifacts}/pipeline-state-{story_id}.yaml` - -**If state file exists and has `stepsCompleted` array with entries:** -- **STOP immediately** -- Load and execute `{resumeStepFile}` (step-01b-resume.md) -- Do not proceed with fresh initialization -- This is auto-proceed - no user choice needed - -**If no state file or empty `stepsCompleted`:** -- Continue with fresh pipeline initialization - -### 3. Locate Story File - -Search for existing story file with pattern: -- Primary: `{sprint_artifacts}/story-{story_id}.md` -- Alternative: `{sprint_artifacts}/{story_id}*.md` - -**Record finding:** -- `story_file_exists`: true/false -- `story_file_path`: path if exists, null otherwise - -### 4. Pre-Load and Cache Documents - -Load these documents ONCE for use across all steps: - -#### A. Project Context (REQUIRED) -``` -Pattern: **/project-context.md -Strategy: FULL_LOAD -Cache: true -``` -- Load complete project-context.md -- This contains critical rules and patterns - -#### B. Epic File (REQUIRED) -``` -Pattern: {output_folder}/epic-{epic_num}.md OR {output_folder}/epics.md -Strategy: SELECTIVE_LOAD (just current epic section) -Cache: true -``` -- Find and load epic definition for current story -- Extract story description, BDD scenarios - -#### C. Architecture (SELECTIVE) -``` -Pattern: {output_folder}/architecture.md -Strategy: INDEX_GUIDED -Sections: tech_stack, data_model, api_patterns -Cache: true -``` -- Load only relevant architecture sections -- Skip detailed implementation that's not needed - -#### D. Story File (IF EXISTS) -``` -Pattern: {sprint_artifacts}/story-{story_id}.md -Strategy: FULL_LOAD (if exists) -Cache: true -``` -- If story exists, load for validation/continuation -- Will be created in step 2 if not exists - -### 5. Create Initial State File - -Create state file at `{stateFile}`: - -```yaml ---- -story_id: "{story_id}" -epic_num: {epic_num} -story_num: {story_num} -mode: "{mode}" -stepsCompleted: [] -lastStep: 0 -currentStep: 1 -status: "initializing" -started_at: "{timestamp}" -updated_at: "{timestamp}" -cached_context: - project_context_loaded: true - epic_loaded: true - architecture_sections: ["tech_stack", "data_model", "api_patterns"] - story_file_exists: {story_file_exists} - story_file_path: "{story_file_path}" -steps: - step-01-init: { status: in_progress } - step-02-create-story: { status: pending } - step-03-validate-story: { status: pending } - step-04-atdd: { status: pending } - step-05-implement: { status: pending } - step-06-code-review: { status: pending } - step-07-complete: { status: pending } - step-08-summary: { status: pending } ---- -``` - -### 6. Present Initialization Summary - -Report to user: - -``` -Pipeline Initialized for Story {story_id} - -Mode: {mode} -Epic: {epic_num} -Story: {story_num} - -Documents Cached: -- Project Context: [loaded from path] -- Epic {epic_num}: [loaded sections] -- Architecture: [loaded sections] -- Story File: [exists/will be created] - -Pipeline State: {stateFile} - -Ready to proceed to story creation. -``` - -### 7. Update State and Proceed - -Update state file: -- Set `stepsCompleted: [1]` -- Set `lastStep: 1` -- Set `steps.step-01-init.status: completed` -- Set `status: "in_progress"` - -### 8. Present Menu (Interactive Mode Only) - -**If mode == "interactive":** - -Display menu and wait for user input: -``` -[C] Continue to Story Creation -[H] Halt pipeline -``` - -**Menu Handling:** -- **C (Continue)**: Load and execute `{nextStepFile}` -- **H (Halt)**: Save checkpoint, exit gracefully - -**If mode == "batch":** -- Auto-proceed to next step -- Load and execute `{nextStepFile}` immediately - -## QUALITY GATE - -Before proceeding, verify: -- [ ] All parameters resolved (story_id, epic_num, story_num, mode) -- [ ] State file created and valid -- [ ] Project context loaded -- [ ] Epic definition loaded -- [ ] Architecture sections loaded (at least tech_stack) - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [initialization complete AND state file updated AND quality gate passed], -load and execute `{nextStepFile}` to begin story creation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- All parameters resolved -- Resume state detected and handed off correctly -- Documents cached efficiently (not reloaded) -- State file created with proper structure -- Menu presented and user input handled - -### ❌ FAILURE -- Proceeding without resolved parameters -- Not checking for resume state first -- Loading documents redundantly across steps -- Not creating state file before proceeding -- Skipping directly to implementation diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01b-resume.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01b-resume.md deleted file mode 100644 index d6fb3d3b..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-01b-resume.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -name: 'step-01b-resume' -description: 'Resume pipeline from checkpoint after failure or interruption' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-01b-resume.md' -stepsPath: '{workflow_path}/steps' - -# State Management -stateFile: '{sprint_artifacts}/pipeline-state-{story_id}.yaml' ---- - -# Step 1b: Resume from Checkpoint - -## STEP GOAL - -Resume a previously started pipeline from the last completed checkpoint: -1. Load existing pipeline state -2. Restore cached document context -3. Determine next step to execute -4. Present resume options to user - -## MANDATORY EXECUTION RULES - -### Universal Rules - -- **NEVER** restart from step 1 if progress exists -- **ALWAYS** restore cached context before resuming -- **PRESERVE** all completed step data -- **VALIDATE** state file integrity before resuming - -### Resume Priority - -- Resume from `lastStep + 1` by default -- Allow user to override and restart from earlier step -- Warn if restarting would lose completed work - -## EXECUTION SEQUENCE - -### 1. Load Pipeline State - -Read state file: `{stateFile}` - -Extract: -- `story_id`, `epic_num`, `story_num`, `mode` -- `stepsCompleted`: Array of completed step numbers -- `lastStep`: Last successfully completed step -- `cached_context`: Document loading status -- `steps`: Individual step status records - -### 2. Validate State Integrity - -Check state file is valid: -- [ ] `story_id` matches requested story -- [ ] `stepsCompleted` is valid array -- [ ] `lastStep` corresponds to actual completed work -- [ ] No corruption in step records - -**If invalid:** -- Warn user: "State file appears corrupted" -- Offer: "Start fresh or attempt recovery?" - -### 3. Restore Cached Context - -Re-load documents if not in memory: - -```yaml -cached_context: - project_context_loaded: {reload if false} - epic_loaded: {reload if false} - architecture_sections: {reload specified sections} - story_file_exists: {verify still exists} - story_file_path: {verify path valid} -``` - -**Efficiency note:** Only reload what's needed, don't duplicate work. - -### 4. Present Resume Summary - -Display current state: - -``` -Pipeline Resume for Story {story_id} - -Previous Session: -- Started: {started_at} -- Last Update: {updated_at} -- Mode: {mode} - -Progress: -- Steps Completed: {stepsCompleted} -- Last Step: {lastStep} ({step_name}) -- Next Step: {lastStep + 1} ({next_step_name}) - -Step Status: - [βœ“] Step 1: Initialize - [βœ“] Step 2: Create Story - [βœ“] Step 3: Validate Story - [ ] Step 4: ATDD (NEXT) - [ ] Step 5: Implement - [ ] Step 6: Code Review - [ ] Step 7: Complete - [ ] Step 8: Summary -``` - -### 5. Present Resume Options - -**Menu:** -``` -Resume Options: - -[C] Continue from Step {lastStep + 1} ({next_step_name}) -[R] Restart from specific step (will mark later steps as pending) -[F] Fresh start (lose all progress) -[H] Halt - -Select option: -``` - -### 6. Handle User Selection - -**C (Continue):** -- Update state: `currentStep: {lastStep + 1}` -- Load and execute next step file - -**R (Restart from step):** -- Ask: "Which step? (2-8)" -- Validate step number -- Mark selected step and all later as `pending` -- Update `lastStep` to step before selected -- Load and execute selected step - -**F (Fresh start):** -- Confirm: "This will lose all progress. Are you sure? (y/n)" -- If confirmed: Delete state file, redirect to step-01-init.md -- If not: Return to menu - -**H (Halt):** -- Save current state -- Exit gracefully - -### 7. Determine Next Step File - -Map step number to file: - -| Step | File | -|------|------| -| 2 | step-02-create-story.md | -| 3 | step-03-validate-story.md | -| 4 | step-04-atdd.md | -| 5 | step-05-implement.md | -| 6 | step-06-code-review.md | -| 7 | step-07-complete.md | -| 8 | step-08-summary.md | - -### 8. Update State and Execute - -Before loading next step: -- Update `updated_at` to current timestamp -- Set `currentStep` to target step -- Set target step status to `in_progress` - -Then load and execute: `{stepsPath}/step-{XX}-{name}.md` - -## BATCH MODE HANDLING - -If `mode == "batch"`: -- Skip menu presentation -- Auto-continue from `lastStep + 1` -- If `lastStep` was a failure, check error details -- If retryable error, attempt same step again -- If non-retryable, halt with error report - -## ERROR RECOVERY - -### Common Resume Scenarios - -**Story file missing after step 2:** -- Warn user -- Offer to restart from step 2 - -**Tests missing after step 4:** -- Warn user -- Offer to restart from step 4 - -**Implementation incomplete after step 5:** -- Check git status for partial changes -- Offer to continue or rollback - -**Code review incomplete after step 6:** -- Check if issues were logged -- Offer to continue review or re-run - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- State file loaded and validated -- Context restored efficiently -- User presented clear resume options -- Correct step file loaded and executed -- No data loss during resume - -### ❌ FAILURE -- Starting from step 1 when progress exists -- Not validating state file integrity -- Loading wrong step after resume -- Losing completed work without confirmation -- Not restoring cached context diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-02-create-story.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-02-create-story.md deleted file mode 100644 index 79d83ef8..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-02-create-story.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -name: 'step-02-create-story' -description: 'Create detailed story file from epic definition with research' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-02-create-story.md' -nextStepFile: '{workflow_path}/steps/step-03-validate-story.md' -checklist: '{workflow_path}/checklists/story-creation.md' - -# Role Switch -role: sm -agentFile: '{project-root}/_bmad/bmm/agents/sm.md' ---- - -# Step 2: Create Story - -## ROLE SWITCH - -**Switching to SM (Scrum Master) perspective.** - -You are now the Scrum Master facilitating story creation. Your expertise: -- User story structure and acceptance criteria -- BDD scenario writing (Given/When/Then) -- Task breakdown and estimation -- Ensuring testability of requirements - -## STEP GOAL - -Create a detailed, implementation-ready story file: -1. Research best practices for the domain -2. Extract story definition from epic -3. Write clear acceptance criteria with BDD scenarios -4. Define tasks and subtasks -5. Ensure all criteria are testable - -## MANDATORY EXECUTION RULES - -### Role-Specific Rules - -- **THINK** like a product/process expert, not a developer -- **FOCUS** on WHAT, not HOW (implementation comes later) -- **ENSURE** every AC is testable and measurable -- **AVOID** technical implementation details in AC - -### Step-Specific Rules - -- **SKIP** this step if story file already exists (check cached context) -- **RESEARCH** best practices before writing -- **USE** project-context.md patterns for consistency -- **CREATE** file at `{sprint_artifacts}/story-{story_id}.md` - -## EXECUTION SEQUENCE - -### 1. Check if Story Already Exists - -From cached context, check `story_file_exists`: - -**If story file exists:** -- Read and display existing story summary -- Ask: "Story file exists. [V]alidate existing, [R]ecreate from scratch?" -- If V: Proceed to step-03-validate-story.md -- If R: Continue with story creation (will overwrite) - -**If story does not exist:** -- Continue with creation - -### 2. Research Phase (MCP Tools) - -Use MCP tools for domain research: - -``` -mcp__exa__web_search_exa: - query: "user story acceptance criteria best practices agile {domain}" - -mcp__exa__get_code_context_exa: - query: "{technology} implementation patterns" -``` - -**Extract from research:** -- AC writing best practices -- Common patterns for this domain -- Anti-patterns to avoid - -### 3. Load Epic Definition - -From cached epic file, extract for story {story_id}: -- Story title and description -- User persona -- Business value -- Initial AC ideas -- BDD scenarios if present - -### 4. Generate Story Content - -Create story file following template: - -```markdown ---- -id: story-{story_id} -epic: {epic_num} -title: "{story_title}" -status: draft -created_at: {timestamp} ---- - -# Story {story_id}: {story_title} - -## User Story - -As a [persona], -I want to [action], -So that [benefit]. - -## Acceptance Criteria - -### AC1: [Criterion Name] - -**Given** [precondition] -**When** [action] -**Then** [expected result] - -**Test Scenarios:** -- [ ] Scenario 1: [description] -- [ ] Scenario 2: [description] - -### AC2: [Criterion Name] -... - -## Tasks - -### Task 1: [Task Name] -- [ ] Subtask 1.1 -- [ ] Subtask 1.2 - -### Task 2: [Task Name] -... - -## Technical Notes - -### Database Changes -- [any schema changes needed] - -### API Changes -- [any endpoint changes] - -### UI Changes -- [any frontend changes] - -## Dependencies -- [list any dependencies on other stories or systems] - -## Out of Scope -- [explicitly list what is NOT included] -``` - -### 5. Verify Story Quality - -Before saving, verify: -- [ ] All AC have Given/When/Then format -- [ ] Each AC has at least 2 test scenarios -- [ ] Tasks cover all AC implementation -- [ ] No implementation details in AC (WHAT not HOW) -- [ ] Out of scope is defined -- [ ] Dependencies listed if any - -### 6. Save Story File - -Write to: `{sprint_artifacts}/story-{story_id}.md` - -Update state file: -- `cached_context.story_file_exists: true` -- `cached_context.story_file_path: {path}` - -### 7. Update Pipeline State - -Update state file: -- Add `2` to `stepsCompleted` -- Set `lastStep: 2` -- Set `steps.step-02-create-story.status: completed` -- Set `steps.step-02-create-story.duration: {duration}` - -### 8. Present Summary and Menu - -Display: -``` -Story {story_id} Created - -Title: {story_title} -Acceptance Criteria: {count} -Test Scenarios: {count} -Tasks: {count} - -File: {story_file_path} -``` - -**Interactive Mode Menu:** -``` -[C] Continue to Validation -[E] Edit story manually -[R] Regenerate story -[H] Halt pipeline -``` - -**Batch Mode:** Auto-continue to next step. - -## QUALITY GATE - -Before proceeding: -- [ ] Story file created at correct location -- [ ] All AC in Given/When/Then format -- [ ] Test scenarios defined for each AC -- [ ] Tasks cover full implementation scope -- [ ] File passes frontmatter validation - -## MCP TOOLS AVAILABLE - -- `mcp__exa__web_search_exa` - Research best practices -- `mcp__exa__get_code_context_exa` - Tech pattern research - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [story file created AND quality gate passed AND state updated], -load and execute `{nextStepFile}` for adversarial validation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- Story file created with proper structure -- All AC have BDD format -- Test scenarios cover all AC -- Research insights incorporated -- State file updated correctly - -### ❌ FAILURE -- Story file not created or in wrong location -- AC without Given/When/Then format -- Missing test scenarios -- Including implementation details in AC -- Not updating state before proceeding diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-03-validate-story.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-03-validate-story.md deleted file mode 100644 index 7fe063eb..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-03-validate-story.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -name: 'step-03-validate-story' -description: 'Adversarial validation of story completeness and quality' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-03-validate-story.md' -nextStepFile: '{workflow_path}/steps/step-04-atdd.md' -checklist: '{workflow_path}/checklists/story-validation.md' - -# Role (same as step 2, no switch needed) -role: sm ---- - -# Step 3: Validate Story - -## ROLE CONTINUATION - -**Continuing as SM (Scrum Master) - Adversarial Validator mode.** - -You are now an ADVERSARIAL validator. Your job is to FIND PROBLEMS, not approve. -Challenge every assumption. Question every AC. Ensure the story is truly ready. - -## STEP GOAL - -Perform rigorous validation of the story file: -1. Research common AC anti-patterns -2. Validate each acceptance criterion -3. Check technical feasibility -4. Ensure all edge cases covered -5. Fix all issues found -6. Add validation report - -## MANDATORY EXECUTION RULES - -### Adversarial Mindset - -- **ASSUME** something is wrong - find it -- **NEVER** say "looks good" without deep analysis -- **QUESTION** every assumption -- **FIND** at least 3 issues (if no issues, you haven't looked hard enough) - -### Validation Rules - -- Every AC must be: Specific, Measurable, Testable -- Every AC must have test scenarios -- No vague terms: "should", "might", "could", "etc." -- No undefined boundaries: "appropriate", "reasonable" - -## EXECUTION SEQUENCE - -### 1. Research Validation Patterns - -Use MCP for research: - -``` -mcp__exa__web_search_exa: - query: "acceptance criteria anti-patterns common mistakes user stories" -``` - -**Extract:** -- Common AC problems -- Validation techniques -- Red flags to look for - -### 2. Load Story File - -Read from cached path: `{story_file_path}` - -Parse and extract: -- All acceptance criteria -- All test scenarios -- Task definitions -- Dependencies - -### 3. Validate Each AC (MANDATORY CHECKLIST) - -For EACH acceptance criterion: - -**Structure Check:** -- [ ] Has Given/When/Then format -- [ ] Given is a valid precondition -- [ ] When is a clear action -- [ ] Then is a measurable outcome - -**Quality Check:** -- [ ] Specific (no vague terms) -- [ ] Measurable (clear success criteria) -- [ ] Testable (can write automated test) -- [ ] Independent (no hidden dependencies) - -**Completeness Check:** -- [ ] Edge cases considered -- [ ] Error scenarios defined -- [ ] Boundary conditions clear - -**Anti-pattern Check:** -- [ ] No implementation details -- [ ] No AND conjunctions (split into multiple AC) -- [ ] No OR alternatives (ambiguous) - -### 4. Technical Feasibility Check - -Cross-reference with architecture.md (from cache): - -- [ ] Required data model exists or migration defined -- [ ] API endpoints fit existing patterns -- [ ] No conflicts with existing functionality -- [ ] Security model (RLS) can support requirements - -### 5. Test Scenario Coverage - -Verify test scenarios: -- [ ] At least 2 scenarios per AC -- [ ] Happy path covered -- [ ] Error paths covered -- [ ] Edge cases covered -- [ ] Each scenario is unique (no duplicates) - -### 6. Document All Issues Found - -Create issues list: - -```yaml -issues_found: - - id: 1 - severity: high|medium|low - ac: AC1 - problem: "Description of issue" - fix: "How to fix it" - - id: 2 - ... -``` - -### 7. Fix All Issues - -For EACH issue: -1. Edit the story file to fix -2. Document the fix -3. Verify fix is correct - -### 8. Add Validation Report - -Append to story file: - -```yaml -# Validation Report -validated_by: sm-validator -validated_at: {timestamp} -issues_found: {count} -issues_fixed: {count} -quality_score: {0-100} -test_scenarios_count: {count} -edge_cases_covered: {list} -ready_for_dev: true|false -validation_notes: | - - {note 1} - - {note 2} -``` - -### 9. Update Pipeline State - -Update state file: -- Add `3` to `stepsCompleted` -- Set `lastStep: 3` -- Set `steps.step-03-validate-story.status: completed` -- Record `issues_found` and `issues_fixed` counts - -### 10. Present Summary and Menu - -Display: -``` -Story Validation Complete - -Issues Found: {count} -Issues Fixed: {count} -Quality Score: {score}/100 - -Validation Areas: -- AC Structure: βœ“/βœ— -- Testability: βœ“/βœ— -- Technical Feasibility: βœ“/βœ— -- Edge Cases: βœ“/βœ— - -Ready for Development: {yes/no} -``` - -**Interactive Mode Menu:** -``` -[C] Continue to ATDD (Test Generation) -[R] Re-validate -[E] Edit story manually -[H] Halt pipeline -``` - -**Batch Mode:** Auto-continue if ready_for_dev: true - -## QUALITY GATE - -Before proceeding: -- [ ] All issues identified and fixed -- [ ] Quality score >= 80 -- [ ] ready_for_dev: true -- [ ] Validation report appended to story file - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [validation complete AND quality gate passed AND ready_for_dev: true], -load and execute `{nextStepFile}` for ATDD test generation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- Found and fixed at least 3 issues -- Quality score >= 80 -- All AC pass validation checklist -- Validation report added -- Story marked ready for dev - -### ❌ FAILURE -- Approving story as "looks good" without deep review -- Missing edge case analysis -- Not fixing all identified issues -- Proceeding with quality_score < 80 -- Not adding validation report diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-04-atdd.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-04-atdd.md deleted file mode 100644 index 08c79302..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-04-atdd.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -name: 'step-04-atdd' -description: 'Generate failing acceptance tests before implementation (RED phase)' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-04-atdd.md' -nextStepFile: '{workflow_path}/steps/step-05-implement.md' -checklist: '{workflow_path}/checklists/atdd.md' - -# Role Switch -role: tea -agentFile: '{project-root}/_bmad/bmm/agents/tea.md' ---- - -# Step 4: ATDD - Acceptance Test-Driven Development - -## ROLE SWITCH - -**Switching to TEA (Test Engineering Architect) perspective.** - -You are now the Test Engineering Architect. Your expertise: -- Test strategy and design -- Playwright and Vitest patterns -- Data factories and fixtures -- Test-first development methodology - -## STEP GOAL - -Generate FAILING acceptance tests BEFORE implementation (RED phase): -1. Research test patterns for the technology stack -2. Analyze each acceptance criterion -3. Determine appropriate test level (E2E, API, Component, Unit) -4. Write tests in Given/When/Then format -5. Create data factories and fixtures -6. Verify tests FAIL (they should - nothing is implemented yet) -7. Generate implementation checklist for DEV - -## MANDATORY EXECUTION RULES - -### ATDD Principles - -- **TESTS FIRST** - Write tests before any implementation -- **TESTS MUST FAIL** - If tests pass, something is wrong -- **ONE AC = ONE TEST** (minimum) - More for complex scenarios -- **REALISTIC DATA** - Use factories, not hardcoded values - -### Test Architecture Rules - -- Use `data-testid` selectors for stability -- Network-first pattern (route interception before navigation) -- Auto-cleanup fixtures -- No flaky timing-based assertions - -## EXECUTION SEQUENCE - -### 1. Research Test Patterns - -Use MCP tools: - -``` -mcp__exa__web_search_exa: - query: "playwright acceptance test best practices Next.js TypeScript 2025" - -mcp__exa__get_code_context_exa: - query: "vitest playwright test fixtures factories faker patterns" -``` - -**Extract:** -- Current best practices for Next.js testing -- Fixture and factory patterns -- Common pitfalls to avoid - -### 2. Analyze Acceptance Criteria - -From cached story file, for EACH acceptance criterion: - -```yaml -ac_analysis: - - ac_id: AC1 - title: "{ac_title}" - given: "{given clause}" - when: "{when clause}" - then: "{then clause}" - test_level: E2E|API|Component|Unit - test_file: "{proposed test file path}" - requires_fixtures: [list] - requires_factories: [list] - data_testids_needed: [list] -``` - -### 3. Determine Test Levels - -For each AC, determine appropriate level: - -| Level | When to Use | -|-------|-------------| -| E2E | Full user flows, UI interactions | -| API | Server actions, API endpoints | -| Component | React component behavior | -| Unit | Pure business logic, utilities | - -### 4. Create Data Factories - -For each entity needed in tests: - -```typescript -// src/tests/factories/{entity}.factory.ts -import { faker } from "@faker-js/faker"; - -export function create{Entity}(overrides: Partial<{Entity}> = {}): {Entity} { - return { - id: faker.string.uuid(), - // ... realistic fake data - ...overrides, - }; -} -``` - -### 5. Create Test Fixtures - -For each test setup pattern: - -```typescript -// src/tests/fixtures/{feature}.fixture.ts -import { test as base } from "vitest"; -// or for E2E: -import { test as base } from "@playwright/test"; - -export const test = base.extend<{ - // fixture types -}>({ - // fixture implementations with auto-cleanup -}); -``` - -### 6. Write Acceptance Tests - -For EACH acceptance criterion: - -```typescript -// src/tests/{appropriate-dir}/{feature}.test.ts - -describe("AC{N}: {ac_title}", () => { - test("Given {given}, When {when}, Then {then}", async () => { - // Arrange (Given) - const data = createTestData(); - - // Act (When) - const result = await performAction(data); - - // Assert (Then) - expect(result).toMatchExpectedOutcome(); - }); - - // Additional scenarios from story - test("Edge case: {scenario}", async () => { - // ... - }); -}); -``` - -### 7. Document Required data-testids - -Create list of data-testids that DEV must implement: - -```markdown -## Required data-testid Attributes - -| Element | data-testid | Purpose | -|---------|-------------|---------| -| Submit button | submit-{feature} | Test form submission | -| Error message | error-{feature} | Verify error display | -| ... | ... | ... | -``` - -### 8. Verify Tests FAIL - -Run tests and verify they fail: - -```bash -npm test -- --run {test-file} -``` - -**Expected:** All tests should FAIL (RED phase) -- "Cannot find element with data-testid" -- "Function not implemented" -- "Route not found" - -**If tests PASS:** Something is wrong - investigate - -### 9. Create ATDD Checklist - -Create: `{sprint_artifacts}/atdd-checklist-{story_id}.md` - -```markdown -# ATDD Checklist for Story {story_id} - -## Test Files Created -- [ ] {test_file_1} -- [ ] {test_file_2} - -## Factories Created -- [ ] {factory_1} -- [ ] {factory_2} - -## Fixtures Created -- [ ] {fixture_1} - -## Implementation Requirements for DEV - -### Required data-testid Attributes -| Element | Attribute | -|---------|-----------| -| ... | ... | - -### API Endpoints Needed -- [ ] {endpoint_1} -- [ ] {endpoint_2} - -### Database Changes -- [ ] {migration_1} - -## Test Status (RED Phase) -All tests should FAIL until implementation: -- [ ] {test_1}: FAILING βœ“ -- [ ] {test_2}: FAILING βœ“ -``` - -### 10. Update Pipeline State - -Update state file: -- Add `4` to `stepsCompleted` -- Set `lastStep: 4` -- Set `steps.step-04-atdd.status: completed` -- Record test file paths created - -### 11. Present Summary and Menu - -Display: -``` -ATDD Complete - RED Phase Verified - -Tests Created: {count} -All Tests FAILING: βœ“ (as expected) - -Test Files: -- {test_file_1} -- {test_file_2} - -Factories: {count} -Fixtures: {count} -data-testids Required: {count} - -ATDD Checklist: {checklist_path} - -Next: DEV will implement to make tests GREEN -``` - -**Interactive Mode Menu:** -``` -[C] Continue to Implementation -[T] Run tests again -[E] Edit tests -[H] Halt pipeline -``` - -**Batch Mode:** Auto-continue - -## QUALITY GATE - -Before proceeding: -- [ ] Test file created for each AC -- [ ] All tests FAIL (RED phase verified) -- [ ] Factories created for test data -- [ ] data-testid requirements documented -- [ ] ATDD checklist created - -## MCP TOOLS AVAILABLE - -- `mcp__exa__web_search_exa` - Test pattern research -- `mcp__exa__get_code_context_exa` - Framework-specific patterns - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [tests created AND all tests FAIL AND checklist created], -load and execute `{nextStepFile}` for implementation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- Tests written for all AC -- All tests FAIL (red phase) -- Factories use faker, not hardcoded data -- Fixtures have auto-cleanup -- data-testid requirements documented -- ATDD checklist complete - -### ❌ FAILURE -- Tests PASS before implementation -- Hardcoded test data -- Missing edge case tests -- No data-testid documentation -- Skipping to implementation without tests diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05-implement.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05-implement.md deleted file mode 100644 index d1f35291..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05-implement.md +++ /dev/null @@ -1,285 +0,0 @@ ---- -name: 'step-05-implement' -description: 'Implement story to make tests pass (GREEN phase)' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-05-implement.md' -nextStepFile: '{workflow_path}/steps/step-05b-post-validation.md' -checklist: '{workflow_path}/checklists/implementation.md' - -# Role Switch -role: dev -agentFile: '{project-root}/_bmad/bmm/agents/dev.md' ---- - -# Step 5: Implement Story - -## ROLE SWITCH - -**Switching to DEV (Developer) perspective.** - -You are now the Developer implementing the story. Your expertise: -- Next.js 16 with App Router -- TypeScript strict mode -- Supabase with RLS -- TDD methodology (make tests GREEN) - -## STEP GOAL - -Implement the story using TDD methodology: -1. Research implementation patterns -2. Review ATDD checklist and failing tests -3. For each failing test: implement minimal code to pass -4. Run tests, verify GREEN -5. Ensure lint and build pass -6. No refactoring yet (that's code review) - -## MANDATORY EXECUTION RULES - -### TDD Rules (RED-GREEN-REFACTOR) - -- **GREEN PHASE** - Make tests pass with minimal code -- **ONE TEST AT A TIME** - Don't implement all at once -- **MINIMAL CODE** - Just enough to pass, no over-engineering -- **RUN TESTS FREQUENTLY** - After each change - -### Implementation Rules - -- **Follow project-context.md** patterns exactly -- **Result type** for all server actions (never throw) -- **snake_case** for database columns -- **Multi-tenancy** with tenant_id on all tables -- **RLS policies** for all new tables - -## EXECUTION SEQUENCE - -### 1. Research Implementation Patterns - -Use MCP tools: - -``` -mcp__exa__get_code_context_exa: - query: "Next.js 16 server actions Supabase RLS multi-tenant" - -mcp__supabase__list_tables: - # Understand current schema -``` - -### 2. Review ATDD Checklist - -Load: `{sprint_artifacts}/atdd-checklist-{story_id}.md` - -Extract: -- Required data-testid attributes -- API endpoints needed -- Database changes required -- Current failing tests - -### 3. Run Failing Tests - -```bash -npm test -- --run -``` - -Confirm all tests are FAILING (from ATDD phase). - -### 4. Implementation Loop - -For EACH acceptance criterion: - -**A. Focus on one failing test:** -```bash -npm test -- --run --grep "{test_name}" -``` - -**B. Implement minimal code:** -- Database migration if needed -- Server action / API route -- UI component with data-testid -- Type definitions - -**C. Run targeted test:** -```bash -npm test -- --run --grep "{test_name}" -``` - -**D. Verify GREEN:** -- Test passes βœ“ -- Move to next test - -### 5. Database Migrations - -For any schema changes: - -```bash -# Create migration file -npx supabase migration new {name} - -# Migration content --- Enable RLS -alter table {table} enable row level security; - --- RLS policies -create policy "Tenants can view own data" - on {table} for select - using (tenant_id = auth.jwt() ->> 'tenant_id'); -``` - -Apply to remote: -```bash -npx supabase db push -``` - -### 6. Server Actions Pattern - -Follow project-context.md pattern: - -```typescript -// src/modules/{module}/actions/{action}.ts -"use server"; - -import { ok, err, Result } from "@/lib/result"; -import { createClient } from "@/lib/supabase/server"; - -export async function actionName( - input: InputType -): Promise> { - const supabase = await createClient(); - - const { data, error } = await supabase - .from("table") - .select("*") - .eq("tenant_id", tenantId); - - if (error) { - return err("DB_ERROR", error.message); - } - - return ok(data); -} -``` - -### 7. UI Components Pattern - -```tsx -// src/modules/{module}/components/{Component}.tsx -"use client"; - -export function Component({ data }: Props) { - return ( -
- -
- ); -} -``` - -### 8. Run Full Test Suite - -After all AC implemented: - -```bash -npm test -- --run -``` - -**All tests should pass (GREEN).** - -### 9. Lint and Build - -```bash -npm run lint -npm run build -``` - -Fix any issues that arise. - -### 10. Verify Implementation Completeness - -Check against ATDD checklist: -- [ ] All data-testid attributes added -- [ ] All API endpoints created -- [ ] All database migrations applied -- [ ] All tests passing - -### 11. Update Pipeline State - -Update state file: -- Add `5` to `stepsCompleted` -- Set `lastStep: 5` -- Set `steps.step-05-implement.status: completed` -- Record files modified - -### 12. Present Summary and Menu - -Display: -``` -Implementation Complete - GREEN Phase - -Tests: {passed}/{total} PASSING -Lint: βœ“ Clean -Build: βœ“ Success - -Files Modified: -- {file_1} -- {file_2} - -Migrations Applied: -- {migration_1} - -Ready for Code Review -``` - -**Interactive Mode Menu:** -``` -[C] Continue to Post-Implementation Validation -[T] Run tests again -[B] Run build again -[H] Halt pipeline -``` - -**Batch Mode:** Auto-continue if all tests pass - -## QUALITY GATE - -Before proceeding: -- [ ] All tests pass (GREEN) -- [ ] Lint clean -- [ ] Build succeeds -- [ ] All ATDD checklist items complete -- [ ] RLS policies for new tables - -## MCP TOOLS AVAILABLE - -- `mcp__exa__get_code_context_exa` - Implementation patterns -- `mcp__supabase__list_tables` - Schema inspection -- `mcp__supabase__execute_sql` - Query testing -- `mcp__supabase__apply_migration` - Schema changes -- `mcp__supabase__generate_typescript_types` - Type sync - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [all tests pass AND lint clean AND build succeeds], -load and execute `{nextStepFile}` for post-implementation validation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- All tests pass (GREEN phase) -- TDD methodology followed -- Result type used (no throws) -- RLS policies in place -- Lint and build clean - -### ❌ FAILURE -- Tests still failing -- Skipping tests to implement faster -- Throwing errors instead of Result type -- Missing RLS policies -- Build or lint failures diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05b-post-validation.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05b-post-validation.md deleted file mode 100644 index 2d81248f..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-05b-post-validation.md +++ /dev/null @@ -1,437 +0,0 @@ ---- -name: 'step-05b-post-validation' -description: 'Verify completed tasks against codebase reality (catch false positives)' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-05b-post-validation.md' -nextStepFile: '{workflow_path}/steps/step-06-code-review.md' -prevStepFile: '{workflow_path}/steps/step-05-implement.md' - -# Role Switch -role: dev -requires_fresh_context: false # Continue from implementation context ---- - -# Step 5b: Post-Implementation Validation - -## ROLE CONTINUATION - VERIFICATION MODE - -**Continuing as DEV but switching to VERIFICATION mindset.** - -You are now verifying that completed work actually exists in the codebase. -This catches the common problem of tasks marked [x] but implementation is incomplete. - -## STEP GOAL - -Verify all completed tasks against codebase reality: -1. Re-read story file and extract completed tasks -2. For each completed task, identify what should exist -3. Use codebase search tools to verify existence -4. Run tests to verify they actually pass -5. Identify false positives (marked done but not actually done) -6. If gaps found, uncheck tasks and add missing work -7. Re-run implementation if needed - -## MANDATORY EXECUTION RULES - -### Verification Principles - -- **TRUST NOTHING** - Verify every completed task -- **CHECK EXISTENCE** - Files, functions, components must exist -- **CHECK COMPLETENESS** - Not just existence, but full implementation -- **TEST VERIFICATION** - Claimed test coverage must be real -- **NO ASSUMPTIONS** - Re-scan the codebase with fresh eyes - -### What to Verify - -For each task marked [x]: -- Files mentioned exist at correct paths -- Functions/components declared and exported -- Tests exist and actually pass -- Database migrations applied -- API endpoints respond correctly - -## EXECUTION SEQUENCE - -### 1. Load Story and Extract Completed Tasks - -Load story file: `{story_file}` - -Extract all tasks from story that are marked [x]: -```regex -- \[x\] (.+) -``` - -Build list of `completed_tasks` to verify. - -### 2. Categorize Tasks by Type - -For each completed task, determine what needs verification: - -**File Creation Tasks:** -- Pattern: "Create {file_path}" -- Verify: File exists at path - -**Component/Function Tasks:** -- Pattern: "Add {name} function/component" -- Verify: Symbol exists and is exported - -**Test Tasks:** -- Pattern: "Add test for {feature}" -- Verify: Test file exists and test passes - -**Database Tasks:** -- Pattern: "Add {table} table", "Create migration" -- Verify: Migration file exists, schema matches - -**API Tasks:** -- Pattern: "Create {endpoint} endpoint" -- Verify: Route file exists, handler implemented - -**UI Tasks:** -- Pattern: "Add {element} to UI" -- Verify: Component has data-testid attribute - -### 3. Verify File Existence - -For all file-related tasks: - -```bash -# Use Glob to find files -glob: "**/{mentioned_filename}" -``` - -**Check:** -- [ ] File exists -- [ ] File is not empty -- [ ] File has expected exports - -**False Positive Indicators:** -- File doesn't exist -- File exists but is empty -- File exists but missing expected symbols - -### 4. Verify Function/Component Implementation - -For code implementation tasks: - -```bash -# Use Grep to find symbols -grep: "{function_name|component_name}" - glob: "**/*.{ts,tsx}" - output_mode: "content" -``` - -**Check:** -- [ ] Symbol is declared -- [ ] Symbol is exported -- [ ] Implementation is not a stub/placeholder -- [ ] Required logic is present - -**False Positive Indicators:** -- Symbol not found -- Symbol exists but marked TODO -- Symbol exists but throws "Not implemented" -- Symbol exists but returns empty/null - -### 5. Verify Test Coverage - -For all test-related tasks: - -```bash -# Find test files -glob: "**/*.test.{ts,tsx}" -glob: "**/*.spec.{ts,tsx}" - -# Run specific tests -npm test -- --run --grep "{feature_name}" -``` - -**Check:** -- [ ] Test file exists -- [ ] Test describes the feature -- [ ] Test actually runs (not skipped) -- [ ] Test passes (GREEN) - -**False Positive Indicators:** -- No test file found -- Test exists but skipped (it.skip) -- Test exists but fails -- Test exists but doesn't test the feature (placeholder) - -### 6. Verify Database Changes - -For database migration tasks: - -```bash -# Find migration files -glob: "**/migrations/*.sql" - -# Check Supabase schema -mcp__supabase__list_tables -``` - -**Check:** -- [ ] Migration file exists -- [ ] Migration has been applied -- [ ] Table/column exists in schema -- [ ] RLS policies are present - -**False Positive Indicators:** -- Migration file missing -- Migration not applied to database -- Table/column doesn't exist -- RLS policies missing - -### 7. Verify API Endpoints - -For API endpoint tasks: - -```bash -# Find route files -glob: "**/app/api/**/{endpoint}/route.ts" -grep: "export async function {METHOD}" -``` - -**Check:** -- [ ] Route file exists -- [ ] Handler function implemented -- [ ] Returns proper Response type -- [ ] Error handling present - -**False Positive Indicators:** -- Route file doesn't exist -- Handler throws "Not implemented" -- Handler returns stub response - -### 8. Run Full Verification - -Execute verification for ALL completed tasks: - -```typescript -interface VerificationResult { - task: string; - status: "verified" | "false_positive"; - evidence: string; - missing?: string; -} - -const results: VerificationResult[] = []; - -for (const task of completed_tasks) { - const result = await verifyTask(task); - results.push(result); -} -``` - -### 9. Analyze Verification Results - -Count results: -``` -Total Verified: {verified_count} -False Positives: {false_positive_count} -``` - -### 10. Handle False Positives - -**IF false positives found (count > 0):** - -Display: -``` -⚠️ POST-IMPLEMENTATION GAPS DETECTED - -Tasks marked complete but implementation incomplete: - -{for each false_positive} -- [ ] {task_description} - Missing: {what_is_missing} - Evidence: {grep/glob results} - -{add new tasks for missing work} -- [ ] Actually implement {missing_part} -``` - -**Actions:** -1. Uncheck false positive tasks in story file -2. Add new tasks for the missing work -3. Update "Gap Analysis" section in story -4. Set state to re-run implementation - -**Re-run implementation:** -``` -Detected {false_positive_count} incomplete tasks. -Re-running Step 5: Implementation to complete missing work... - -{load and execute step-05-implement.md} -``` - -After re-implementation, **RE-RUN THIS STEP** (step-05b-post-validation.md) - -### 11. Handle Verified Success - -**IF no false positives (all verified):** - -Display: -``` -βœ… POST-IMPLEMENTATION VALIDATION PASSED - -All {verified_count} completed tasks verified against codebase: -- Files exist and are complete -- Functions/components implemented -- Tests exist and pass -- Database changes applied -- API endpoints functional - -Ready for Code Review -``` - -Update story file "Gap Analysis" section: -```markdown -## Gap Analysis - -### Post-Implementation Validation -- **Date:** {timestamp} -- **Tasks Verified:** {verified_count} -- **False Positives:** 0 -- **Status:** βœ… All work verified complete - -**Verification Evidence:** -{for each verified task} -- βœ… {task}: {evidence} -``` - -### 12. Update Pipeline State - -Update state file: -- Add `5b` to `stepsCompleted` -- Set `lastStep: 5b` -- Set `steps.step-05b-post-validation.status: completed` -- Record verification results: - ```yaml - verification: - tasks_verified: {count} - false_positives: {count} - re_implementation_required: {true|false} - ``` - -### 13. Present Summary and Menu - -Display: -``` -Post-Implementation Validation Complete - -Verification Summary: -- Tasks Checked: {total_count} -- Verified Complete: {verified_count} -- False Positives: {false_positive_count} -- Re-implementations: {retry_count} - -{if false_positives} -Re-running implementation to complete missing work... -{else} -All work verified. Proceeding to Code Review... -{endif} -``` - -**Interactive Mode Menu (only if no false positives):** -``` -[C] Continue to Code Review -[V] Run verification again -[T] Run tests again -[H] Halt pipeline -``` - -**Batch Mode:** -- Auto re-run implementation if false positives -- Auto-continue if all verified - -## QUALITY GATE - -Before proceeding to code review: -- [ ] All completed tasks verified against codebase -- [ ] Zero false positives remaining -- [ ] All tests still passing -- [ ] Build still succeeds -- [ ] Gap analysis updated with verification results - -## VERIFICATION TOOLS - -Use these tools for verification: - -```typescript -// File existence -glob("{pattern}") - -// Symbol search -grep("{symbol_name}", { glob: "**/*.{ts,tsx}", output_mode: "content" }) - -// Test execution -bash("npm test -- --run --grep '{test_name}'") - -// Database check -mcp__supabase__list_tables() - -// Read file contents -read("{file_path}") -``` - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [all tasks verified AND zero false positives], -load and execute `{nextStepFile}` for code review. - -**IF** [false positives detected], -load and execute `{prevStepFile}` to complete missing work, -then RE-RUN this step. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- All completed tasks verified against codebase -- No false positives (or all re-implemented) -- Tests still passing -- Evidence documented for each task -- Gap analysis updated - -### ❌ FAILURE -- Skipping verification ("trust the marks") -- Not checking actual code existence -- Not running tests to verify claims -- Allowing false positives to proceed -- Not documenting verification evidence - -## COMMON FALSE POSITIVE PATTERNS - -Watch for these common issues: - -1. **Stub Implementations** - - Function exists but returns `null` - - Function throws "Not implemented" - - Component returns empty div - -2. **Placeholder Tests** - - Test exists but skipped (it.skip) - - Test doesn't actually test the feature - - Test always passes (no assertions) - -3. **Incomplete Files** - - File created but empty - - Missing required exports - - TODO comments everywhere - -4. **Database Drift** - - Migration file exists but not applied - - Schema doesn't match migration - - RLS policies missing - -5. **API Stubs** - - Route exists but returns 501 - - Handler not implemented - - No error handling - -This step is the **safety net** that catches incomplete work before code review. diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-06-code-review.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-06-code-review.md deleted file mode 100644 index ca6e8429..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-06-code-review.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -name: 'step-06-code-review' -description: 'Adversarial code review finding 3-10 specific issues' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-06-code-review.md' -nextStepFile: '{workflow_path}/steps/step-07-complete.md' -checklist: '{workflow_path}/checklists/code-review.md' - -# Role (continue as dev, but reviewer mindset) -role: dev -requires_fresh_context: true # In batch mode, checkpoint here for unbiased review ---- - -# Step 6: Code Review - -## ROLE CONTINUATION - ADVERSARIAL MODE - -**Continuing as DEV but switching to ADVERSARIAL REVIEWER mindset.** - -You are now a critical code reviewer. Your job is to FIND PROBLEMS. -- **NEVER** say "looks good" - that's a failure -- **MUST** find 3-10 specific issues -- **FIX** every issue you find - -## STEP GOAL - -Perform adversarial code review: -1. Query Supabase advisors for security/performance issues -2. Identify all files changed for this story -3. Review each file against checklist -4. Find and document 3-10 issues (MANDATORY) -5. Fix all issues -6. Verify tests still pass - -## MANDATORY EXECUTION RULES - -### Adversarial Requirements - -- **MINIMUM 3 ISSUES** - If you found fewer, look harder -- **MAXIMUM 10 ISSUES** - Prioritize if more found -- **NO "LOOKS GOOD"** - This is FORBIDDEN -- **FIX EVERYTHING** - Don't just report, fix - -### Review Categories (find issues in EACH) - -1. Security -2. Performance -3. Error Handling -4. Test Coverage -5. Code Quality -6. Architecture - -## EXECUTION SEQUENCE - -### 1. Query Supabase Advisors - -Use MCP tools: - -``` -mcp__supabase__get_advisors: - type: "security" - -mcp__supabase__get_advisors: - type: "performance" -``` - -Document any issues found. - -### 2. Identify Changed Files - -```bash -git status -git diff --name-only HEAD~1 -``` - -List all files changed for story {story_id}. - -### 3. Review Each Category - -#### SECURITY REVIEW - -For each file, check: -- [ ] No SQL injection vulnerabilities -- [ ] No XSS vulnerabilities -- [ ] Auth checks on all protected routes -- [ ] RLS policies exist and are correct -- [ ] No credential exposure (API keys, secrets) -- [ ] Input validation present -- [ ] Rate limiting considered - -#### PERFORMANCE REVIEW - -- [ ] No N+1 query patterns -- [ ] Indexes exist for query patterns -- [ ] No unnecessary re-renders -- [ ] Proper caching strategy -- [ ] Efficient data fetching -- [ ] Bundle size impact considered - -#### ERROR HANDLING REVIEW - -- [ ] Result type used consistently -- [ ] Error messages are user-friendly -- [ ] Edge cases handled -- [ ] Null/undefined checked -- [ ] Network errors handled gracefully - -#### TEST COVERAGE REVIEW - -- [ ] All AC have tests -- [ ] Edge cases tested -- [ ] Error paths tested -- [ ] Mocking is appropriate (not excessive) -- [ ] Tests are deterministic - -#### CODE QUALITY REVIEW - -- [ ] DRY - no duplicate code -- [ ] SOLID principles followed -- [ ] TypeScript strict mode compliant -- [ ] No any types -- [ ] Functions are focused (single responsibility) -- [ ] Naming is clear and consistent - -#### ARCHITECTURE REVIEW - -- [ ] Module boundaries respected -- [ ] Imports from index.ts only -- [ ] Server/client separation correct -- [ ] Data flow is clear -- [ ] No circular dependencies - -### 4. Document All Issues - -For each issue found: - -```yaml -issue_{n}: - severity: critical|high|medium|low - category: security|performance|error-handling|testing|quality|architecture - file: "{file_path}" - line: {line_number} - problem: | - {Clear description of the issue} - risk: | - {What could go wrong if not fixed} - fix: | - {How to fix it} -``` - -### 5. Fix All Issues - -For EACH issue documented: - -1. Edit the file to fix the issue -2. Add test if issue wasn't covered -3. Verify the fix is correct -4. Mark as fixed - -### 6. Run Verification - -After all fixes: - -```bash -npm run lint -npm run build -npm test -- --run -``` - -All must pass. - -### 7. Create Review Report - -Append to story file or create `{sprint_artifacts}/review-{story_id}.md`: - -```markdown -# Code Review Report - Story {story_id} - -## Summary -- Issues Found: {count} -- Issues Fixed: {count} -- Categories Reviewed: {list} - -## Issues Detail - -### Issue 1: {title} -- **Severity:** {severity} -- **Category:** {category} -- **File:** {file}:{line} -- **Problem:** {description} -- **Fix Applied:** {fix_description} - -### Issue 2: {title} -... - -## Security Checklist -- [x] RLS policies verified -- [x] No credential exposure -- [x] Input validation present - -## Performance Checklist -- [x] No N+1 queries -- [x] Indexes verified - -## Final Status -All issues resolved. Tests passing. - -Reviewed by: DEV (adversarial) -Reviewed at: {timestamp} -``` - -### 8. Update Pipeline State - -Update state file: -- Add `6` to `stepsCompleted` -- Set `lastStep: 6` -- Set `steps.step-06-code-review.status: completed` -- Record `issues_found` and `issues_fixed` - -### 9. Present Summary and Menu - -Display: -``` -Code Review Complete - -Issues Found: {count} (minimum 3 required) -Issues Fixed: {count} - -By Category: -- Security: {count} -- Performance: {count} -- Error Handling: {count} -- Test Coverage: {count} -- Code Quality: {count} -- Architecture: {count} - -All Tests: PASSING -Lint: CLEAN -Build: SUCCESS - -Review Report: {report_path} -``` - -**Interactive Mode Menu:** -``` -[C] Continue to Completion -[R] Run another review pass -[T] Run tests again -[H] Halt pipeline -``` - -**Batch Mode:** Auto-continue if minimum issues found and fixed - -## QUALITY GATE - -Before proceeding: -- [ ] Minimum 3 issues found and fixed -- [ ] All categories reviewed -- [ ] All tests still passing -- [ ] Lint clean -- [ ] Build succeeds -- [ ] Review report created - -## MCP TOOLS AVAILABLE - -- `mcp__supabase__get_advisors` - Security/performance checks -- `mcp__supabase__execute_sql` - Query verification - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [minimum 3 issues found AND all fixed AND tests pass], -load and execute `{nextStepFile}` for story completion. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- Found and fixed 3-10 issues -- All categories reviewed -- Tests still passing after fixes -- Review report complete -- No "looks good" shortcuts - -### ❌ FAILURE -- Saying "looks good" or "no issues found" -- Finding fewer than 3 issues -- Not fixing issues found -- Tests failing after fixes -- Skipping review categories diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-07-complete.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-07-complete.md deleted file mode 100644 index d2cbbef8..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-07-complete.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -name: 'step-07-complete' -description: 'Update sprint status and create git commit' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-07-complete.md' -nextStepFile: '{workflow_path}/steps/step-08-summary.md' - -# Role Switch -role: sm -agentFile: '{project-root}/_bmad/bmm/agents/sm.md' ---- - -# Step 7: Complete Story - -## ROLE SWITCH - -**Switching back to SM (Scrum Master) perspective.** - -You are completing the story lifecycle: -- Update sprint tracking -- Create git commit -- Finalize documentation - -## STEP GOAL - -Complete the story development lifecycle: -1. Final verification (tests, lint, build) -2. Update sprint-status.yaml -3. Create git commit with proper message -4. Update story file status - -## MANDATORY EXECUTION RULES - -### Completion Rules - -- **VERIFY** everything passes before committing -- **UPDATE** all tracking files -- **COMMIT** with conventional commit message -- **DOCUMENT** completion metadata - -## EXECUTION SEQUENCE - -### 1. Final Verification - -Run full verification suite: - -```bash -npm test -- --run -npm run lint -npm run build -``` - -All must pass before proceeding. - -**If any fail:** HALT and report issues. - -### 2. Update Story File Status - -Edit story file, update frontmatter: - -```yaml ---- -status: done -completed_at: {timestamp} -implementation_notes: | - - Tests created and passing - - Code reviewed and approved - - {count} issues found and fixed ---- -``` - -### 3. Update Sprint Status - -Edit: `{sprint_artifacts}/sprint-status.yaml` - -Find story {story_id} and update: - -```yaml -stories: - - id: "{story_id}" - status: done - completed_at: {timestamp} - metadata: - tests_passing: true - code_reviewed: true - issues_found: {count} - issues_fixed: {count} - pipeline_version: "story-dev-only-v2.0" -``` - -### 4. Stage Git Changes - -```bash -git add src/ -git add _bmad-output/implementation-artifacts/story-{story_id}.md -git add _bmad-output/implementation-artifacts/sprint-status.yaml -git add src/supabase/migrations/ -``` - -### 5. Create Git Commit - -Check for changes: -```bash -git diff --cached --quiet -``` - -If changes exist, create commit: - -```bash -git commit -m "$(cat <<'EOF' -feat(epic-{epic_num}): complete story {story_id} - -- Acceptance tests created for all criteria -- All tests passing (TDD green phase) -- Code reviewed: {issues_found} issues found and fixed - -Story: {story_title} -Pipeline: story-dev-only-v2.0 - -πŸ€– Generated with BMAD Story Pipeline - -Co-Authored-By: Claude -EOF -)" -``` - -### 6. Verify Commit - -```bash -git log -1 --oneline -git status -``` - -Confirm: -- Commit created successfully -- Working directory clean (or only untracked files) - -### 7. Update Pipeline State - -Update state file: -- Add `7` to `stepsCompleted` -- Set `lastStep: 7` -- Set `steps.step-07-complete.status: completed` -- Set `status: completing` - -### 8. Present Summary and Menu - -Display: -``` -Story {story_id} Completed - -Sprint Status: Updated βœ“ -Story Status: done βœ“ -Git Commit: Created βœ“ - -Commit: {commit_hash} -Message: feat(epic-{epic_num}): complete story {story_id} - -Files Committed: -- {file_count} files - -Next: Generate summary and audit trail -``` - -**Interactive Mode Menu:** -``` -[C] Continue to Summary -[L] View git log -[S] View git status -[H] Halt (story is complete, audit pending) -``` - -**Batch Mode:** Auto-continue to summary - -## QUALITY GATE - -Before proceeding: -- [ ] All tests pass -- [ ] Lint clean -- [ ] Build succeeds -- [ ] Sprint status updated -- [ ] Git commit created -- [ ] Story status set to done - -## CRITICAL STEP COMPLETION - -**ONLY WHEN** [verification passes AND commit created AND status updated], -load and execute `{nextStepFile}` for summary generation. - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- All verification passes -- Sprint status updated correctly -- Conventional commit created -- Story marked as done -- Clean git state - -### ❌ FAILURE -- Committing with failing tests -- Missing sprint status update -- Malformed commit message -- Not including all changed files -- Story not marked done diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-08-summary.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-08-summary.md deleted file mode 100644 index 96f99f22..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/steps/step-08-summary.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -name: 'step-08-summary' -description: 'Generate audit trail and pipeline summary report' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only' - -# File References -thisStepFile: '{workflow_path}/steps/step-08-summary.md' -auditFile: '{sprint_artifacts}/audit-{story_id}-{date}.yaml' - -# No role needed - orchestrator -role: null ---- - -# Step 8: Pipeline Summary - -## STEP GOAL - -Generate final audit trail and summary report: -1. Calculate pipeline metrics -2. Generate audit trail file -3. Create summary report -4. Clean up pipeline state -5. Suggest next steps - -## EXECUTION SEQUENCE - -### 1. Calculate Pipeline Metrics - -From pipeline state file, calculate: - -```yaml -metrics: - total_duration: {sum of all step durations} - steps_completed: {count} - issues_found: {from code review} - issues_fixed: {from code review} - tests_created: {count} - files_modified: {count} - migrations_applied: {count} -``` - -### 2. Generate Audit Trail - -Create: `{auditFile}` - -```yaml ---- -audit_version: "1.0" -pipeline: "story-dev-only-v2.0" -story_id: "{story_id}" -epic_num: {epic_num} ---- - -# Pipeline Audit Trail - -## Execution Summary -started_at: "{started_at}" -completed_at: "{timestamp}" -total_duration: "{duration}" -mode: "{mode}" -status: "completed" - -## Steps Executed -steps: - - step: 1 - name: "Initialize" - status: completed - duration: "{duration}" - - - step: 2 - name: "Create Story" - status: completed - duration: "{duration}" - agent: sm - output: "{story_file_path}" - - - step: 3 - name: "Validate Story" - status: completed - duration: "{duration}" - agent: sm - issues_found: {count} - issues_fixed: {count} - - - step: 4 - name: "ATDD" - status: completed - duration: "{duration}" - agent: tea - tests_created: {count} - test_files: - - "{file_1}" - - "{file_2}" - - - step: 5 - name: "Implement" - status: completed - duration: "{duration}" - agent: dev - files_modified: {count} - migrations: - - "{migration_1}" - - - step: 6 - name: "Code Review" - status: completed - duration: "{duration}" - agent: dev - issues_found: {count} - issues_fixed: {count} - categories_reviewed: - - security - - performance - - error-handling - - testing - - quality - - architecture - - - step: 7 - name: "Complete" - status: completed - duration: "{duration}" - agent: sm - commit_hash: "{hash}" - - - step: 8 - name: "Summary" - status: completed - duration: "{duration}" - -## Quality Gates -gates: - story_creation: - passed: true - criteria_met: [list] - validation: - passed: true - quality_score: {score} - atdd: - passed: true - tests_failing: true # Expected in red phase - implementation: - passed: true - tests_passing: true - code_review: - passed: true - minimum_issues_found: true - -## Artifacts Produced -artifacts: - story_file: "{path}" - test_files: - - "{path}" - migrations: - - "{path}" - atdd_checklist: "{path}" - review_report: "{path}" - commit: "{hash}" - -## Token Efficiency -token_estimate: - traditional_approach: "~71K tokens (6 claude calls)" - step_file_approach: "~{actual}K tokens (1 session)" - savings: "{percentage}%" -``` - -### 3. Generate Summary Report - -Display to user: - -``` -═══════════════════════════════════════════════════════════════════ - PIPELINE COMPLETE: Story {story_id} -═══════════════════════════════════════════════════════════════════ - -πŸ“Š EXECUTION SUMMARY -──────────────────── -Duration: {total_duration} -Mode: {mode} -Status: βœ“ Completed Successfully - -πŸ“‹ STORY DETAILS -──────────────────── -Epic: {epic_num} -Title: {story_title} -Commit: {commit_hash} - -βœ… QUALITY METRICS -──────────────────── -Validation Score: {score}/100 -Issues Found: {count} -Issues Fixed: {count} -Tests Created: {count} -Files Modified: {count} - -πŸ“ ARTIFACTS -──────────────────── -Story: {story_file} -Tests: {test_count} files -Migrations: {migration_count} -Audit: {audit_file} - -πŸ’° TOKEN EFFICIENCY -──────────────────── -Traditional: ~71K tokens -Step-file: ~{actual}K tokens -Savings: {percentage}% - -═══════════════════════════════════════════════════════════════════ -``` - -### 4. Update Final Pipeline State - -Update state file: -- Add `8` to `stepsCompleted` -- Set `lastStep: 8` -- Set `status: completed` -- Set `completed_at: {timestamp}` - -### 5. Suggest Next Steps - -Display: - -``` -πŸ“Œ NEXT STEPS -──────────────────── -1. Review commit: git show {hash} -2. Push when ready: git push -3. Next story: bmad build {next_story_id} -4. View audit: cat {audit_file} - -Optional: -- Run verification: bmad verify {story_id} -- Run with coverage: npm test -- --coverage -``` - -### 6. Clean Up (Optional) - -In batch mode, optionally archive pipeline state: - -```bash -mv {state_file} {state_file}.completed -``` - -Or keep for reference. - -## COMPLETION - -Pipeline execution complete. No next step to load. - -Display final message: -``` -Pipeline complete. Story {story_id} is ready. -``` - ---- - -## SUCCESS/FAILURE METRICS - -### βœ… SUCCESS -- Audit trail generated with all details -- Summary displayed clearly -- All metrics calculated -- State marked complete -- Next steps provided - -### ❌ FAILURE -- Missing audit trail -- Incomplete metrics -- State not finalized -- No summary provided diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/audit-trail.yaml.template b/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/audit-trail.yaml.template deleted file mode 100644 index fc16f263..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/audit-trail.yaml.template +++ /dev/null @@ -1,249 +0,0 @@ -# Audit Trail Template -# Generated at pipeline completion -# Location: {sprint_artifacts}/audit-{story_id}-{date}.yaml -# yamllint disable - ---- -audit_version: "1.0" -pipeline_version: "story-pipeline-v2.0" - -# Story identification -story_id: "{{story_id}}" -epic_num: {{epic_num}} -story_title: "{{story_title}}" - -# Execution summary -execution: - started_at: "{{started_at}}" - completed_at: "{{completed_at}}" - total_duration: "{{duration}}" - mode: "{{mode}}" - status: "{{status}}" - -# Agent roles used -agents: - sm: - name: "Scrum Master" - steps: [2, 3, 7] - total_time: null - tea: - name: "Test Engineering Architect" - steps: [4] - total_time: null - dev: - name: "Developer" - steps: [5, 6] - total_time: null - -# Step-by-step execution log -steps: - - step: 1 - name: "Initialize" - status: "{{status}}" - duration: "{{duration}}" - actions: - - "Loaded project context" - - "Loaded epic definition" - - "Cached architecture sections" - - - step: 2 - name: "Create Story" - status: "{{status}}" - duration: "{{duration}}" - agent: "sm" - research_queries: - - "{{query_1}}" - - "{{query_2}}" - output: "{{story_file_path}}" - acceptance_criteria_count: {{count}} - - - step: 3 - name: "Validate Story" - status: "{{status}}" - duration: "{{duration}}" - agent: "sm" - issues_found: {{count}} - issues_fixed: {{count}} - quality_score: {{score}} - validation_areas: - - "AC structure" - - "Testability" - - "Technical feasibility" - - "Edge cases" - - - step: 4 - name: "ATDD (Red Phase)" - status: "{{status}}" - duration: "{{duration}}" - agent: "tea" - tests_created: {{count}} - test_files: - - "{{path}}" - factories_created: - - "{{factory}}" - fixtures_created: - - "{{fixture}}" - data_testids_documented: {{count}} - - - step: 5 - name: "Implement (Green Phase)" - status: "{{status}}" - duration: "{{duration}}" - agent: "dev" - files_modified: {{count}} - migrations_applied: - - "{{migration}}" - test_results: - passed: {{count}} - failed: 0 - lint_status: "clean" - build_status: "success" - - - step: 6 - name: "Code Review" - status: "{{status}}" - duration: "{{duration}}" - agent: "dev" - review_type: "adversarial" - issues_found: {{count}} - issues_fixed: {{count}} - categories_reviewed: - security: - issues: {{count}} - fixed: {{count}} - performance: - issues: {{count}} - fixed: {{count}} - error_handling: - issues: {{count}} - fixed: {{count}} - testing: - issues: {{count}} - fixed: {{count}} - code_quality: - issues: {{count}} - fixed: {{count}} - architecture: - issues: {{count}} - fixed: {{count}} - - - step: 7 - name: "Complete" - status: "{{status}}" - duration: "{{duration}}" - agent: "sm" - commit_hash: "{{hash}}" - commit_message: "feat(epic-{{epic_num}}): complete story {{story_id}}" - files_committed: {{count}} - sprint_status_updated: true - - - step: 8 - name: "Summary" - status: "{{status}}" - duration: "{{duration}}" - audit_file: "{{this_file}}" - -# Quality gates summary -quality_gates: - story_creation: - passed: true - criteria: - - "Story file created" - - "All AC in BDD format" - - "Test scenarios defined" - - validation: - passed: true - quality_score: {{score}} - criteria: - - "No ambiguous requirements" - - "All issues fixed" - - atdd: - passed: true - criteria: - - "Tests for all AC" - - "Tests fail (red phase)" - - "data-testids documented" - - implementation: - passed: true - criteria: - - "All tests pass" - - "Lint clean" - - "Build success" - - "RLS policies added" - - code_review: - passed: true - issues_found: {{count}} - criteria: - - "Minimum 3 issues found" - - "All issues fixed" - - "All categories reviewed" - -# Artifacts produced -artifacts: - story_file: - path: "{{path}}" - size: "{{size}}" - - test_files: - - path: "{{path}}" - test_count: {{count}} - - migrations: - - path: "{{path}}" - tables_affected: ["{{table}}"] - - checklists: - atdd: "{{path}}" - review: "{{path}}" - - commit: - hash: "{{hash}}" - branch: "{{branch}}" - pushed: false - -# Token efficiency comparison -token_efficiency: - traditional_approach: - description: "6 separate claude -p calls" - estimated_tokens: 71000 - breakdown: - - stage: "create-story" - tokens: 12000 - - stage: "validate-story" - tokens: 11000 - - stage: "atdd" - tokens: 12000 - - stage: "implement" - tokens: 15000 - - stage: "code-review" - tokens: 13000 - - stage: "complete" - tokens: 8000 - - step_file_approach: - description: "Single session with step-file loading" - estimated_tokens: "{{actual}}" - savings_percentage: "{{percentage}}" - breakdown: - - step: "context_loading" - tokens: 5000 - note: "Loaded once, cached" - - step: "step_files" - tokens: "{{tokens}}" - note: "~200 lines each" - - step: "execution" - tokens: "{{tokens}}" - note: "Actual work" - -# Notes and observations -notes: - - "{{note_1}}" - - "{{note_2}}" - -# Generated by -generated_by: "BMAD Story Pipeline v2.0" -generated_at: "{{timestamp}}" diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/pipeline-state.yaml.template b/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/pipeline-state.yaml.template deleted file mode 100644 index d7281aa4..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/templates/pipeline-state.yaml.template +++ /dev/null @@ -1,144 +0,0 @@ -# Pipeline State Template -# Copy and populate for each story execution -# Location: {sprint_artifacts}/pipeline-state-{story_id}.yaml - ---- -# Story identification -story_id: "{{story_id}}" -epic_num: {{epic_num}} -story_num: {{story_num}} - -# Execution mode -mode: "interactive" # or "batch" - -# Progress tracking -stepsCompleted: [] -lastStep: 0 -currentStep: 0 -status: "not_started" # not_started, initializing, in_progress, completing, completed, failed - -# Timestamps -started_at: null -updated_at: null -completed_at: null - -# Cached document context (loaded once, reused) -cached_context: - project_context_loaded: false - project_context_path: null - epic_loaded: false - epic_path: null - architecture_sections: [] - architecture_paths: [] - story_file_exists: false - story_file_path: null - -# Step status tracking -steps: - step-01-init: - status: pending - started_at: null - completed_at: null - duration: null - notes: null - - step-02-create-story: - status: pending - started_at: null - completed_at: null - duration: null - agent: sm - output_file: null - notes: null - - step-03-validate-story: - status: pending - started_at: null - completed_at: null - duration: null - agent: sm - issues_found: 0 - issues_fixed: 0 - quality_score: null - notes: null - - step-04-atdd: - status: pending - started_at: null - completed_at: null - duration: null - agent: tea - tests_created: 0 - test_files: [] - factories_created: [] - fixtures_created: [] - notes: null - - step-05-implement: - status: pending - started_at: null - completed_at: null - duration: null - agent: dev - files_modified: [] - migrations_applied: [] - tests_passing: null - lint_clean: null - build_success: null - notes: null - - step-06-code-review: - status: pending - started_at: null - completed_at: null - duration: null - agent: dev - issues_found: 0 - issues_fixed: 0 - categories_reviewed: [] - tests_passing: null - notes: null - - step-07-complete: - status: pending - started_at: null - completed_at: null - duration: null - agent: sm - commit_hash: null - sprint_status_updated: false - notes: null - - step-08-summary: - status: pending - started_at: null - completed_at: null - duration: null - audit_file: null - notes: null - -# Error tracking (if pipeline fails) -errors: [] -# Example error entry: -# - step: 5 -# timestamp: "2025-01-15T12:00:00Z" -# error: "Tests failed after implementation" -# details: "3 tests failing in auth.test.ts" -# recoverable: true - -# Quality gates passed -quality_gates: - story_creation: null - validation: null - atdd: null - implementation: null - code_review: null - -# Metrics (populated at end) -metrics: - total_duration: null - token_estimate: null - files_modified_count: 0 - tests_created_count: 0 - issues_found_total: 0 - issues_fixed_total: 0 diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.md b/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.md deleted file mode 100644 index 29399ed3..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -name: story-dev-only -description: Automated story development pipeline with token-efficient step-file architecture. Single-session orchestration replacing multiple Claude calls. -web_bundle: true ---- - -# Story Pipeline Workflow - -**Goal:** Execute complete story development lifecycle in a single Claude session: create story, validate, generate tests (ATDD), implement, code review, and complete. - -**Your Role:** You are the **BMAD Pipeline Orchestrator**. You will switch between agent roles (SM, TEA, DEV) as directed by each step file. Maintain context across role switches without reloading agent personas. - -**Token Efficiency:** This workflow uses step-file architecture for ~60-70% token savings compared to separate Claude calls. - ---- - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -### Core Principles - -- **Micro-file Design**: Each step is a self-contained instruction file (~150-250 lines) -- **Just-In-Time Loading**: Only the current step file is in memory -- **Role Switching**: Same session, explicit role switch instead of fresh Claude calls -- **State Tracking**: Pipeline state in `{sprint_artifacts}/pipeline-state-{story_id}.yaml` -- **Checkpoint/Resume**: Can resume from any completed step after failure - -### Step Processing Rules - -1. **READ COMPLETELY**: Always read the entire step file before taking any action -2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate -3. **ROLE SWITCH**: When step specifies a role, adopt that agent's perspective -4. **QUALITY GATES**: Complete gate criteria before proceeding to next step -5. **WAIT FOR INPUT**: In interactive mode, halt at menus and wait for user selection -6. **SAVE STATE**: Update pipeline state file after each step completion -7. **LOAD NEXT**: When directed, load, read entire file, then execute the next step - -### Critical Rules (NO EXCEPTIONS) - -- **NEVER** load multiple step files simultaneously -- **ALWAYS** read entire step file before execution -- **NEVER** skip steps or optimize the sequence -- **ALWAYS** update pipeline state after completing each step -- **ALWAYS** follow the exact instructions in the step file -- **NEVER** create mental todo lists from future steps -- **NEVER** look ahead to future step files - -### Mode Differences - -| Aspect | Interactive | Batch | -|--------|-------------|-------| -| Menus | Present, wait for [C] | Auto-proceed | -| Approval | Required at gates | Skip with YOLO | -| On failure | Halt, checkpoint | Checkpoint, exit | -| Code review | Same session | Fresh context option | - ---- - -## EXECUTION MODES - -### Interactive Mode (Default) - -```bash -bmad build 1-4 # Interactive pipeline for story 1-4 -bmad build --interactive 1-4 -``` - -Features: -- Menu navigation between steps -- User approval at quality gates -- Can pause and resume -- Role switching in same session - -### Batch Mode - -```bash -bmad build --batch 1-4 # Unattended execution -``` - -Features: -- Auto-proceed through all steps -- YOLO mode for approvals -- Fail-fast on errors -- Optional fresh context for code review - ---- - -## INITIALIZATION SEQUENCE - -### 1. Configuration Loading - -Load and read config from `{project-root}/_bmad/bmm/config.yaml` and resolve: -- `output_folder`, `sprint_artifacts`, `communication_language` - -### 2. Pipeline Parameters - -Resolve from invocation: -- `story_id`: Story identifier (e.g., "1-4") -- `epic_num`: Epic number (e.g., 1) -- `story_num`: Story number (e.g., 4) -- `mode`: "interactive" or "batch" - -### 3. Document Pre-loading - -Load and cache these documents (read once, use across steps): -- Story file: `{sprint_artifacts}/story-{epic_num}-{story_num}.md` -- Epic file: `{output_folder}/epic-{epic_num}.md` -- Architecture: `{output_folder}/architecture.md` (selective sections) -- Project context: `**/project-context.md` - -### 4. First Step Execution - -Load, read the full file and then execute: -`{project-root}/_bmad/bmm/workflows/4-implementation/story-dev-only/steps/step-01-init.md` - ---- - -## STEP FILE MAP - -| Step | File | Agent | Purpose | -|------|------|-------|---------| -| 1 | step-01-init.md | - | Load context, detect mode, cache docs | -| 1b | step-01b-resume.md | - | Resume from checkpoint (conditional) | -| 2 | step-02-create-story.md | SM | Create detailed story with research | -| 3 | step-03-validate-story.md | SM | Adversarial validation | -| 4 | step-04-atdd.md | TEA | Generate failing tests (red phase) | -| 5 | step-05-implement.md | DEV | Implement to pass tests (green phase) | -| 5b | step-05b-post-validation.md | DEV | Verify completed tasks vs codebase reality | -| 6 | step-06-code-review.md | DEV | Find 3-10 specific issues | -| 7 | step-07-complete.md | SM | Update status, git commit | -| 8 | step-08-summary.md | - | Audit trail, summary report | - ---- - -## ROLE SWITCHING PROTOCOL - -When a step requires a different agent role: - -1. **Announce Role Switch**: "Switching to [ROLE] perspective..." -2. **Adopt Mindset**: Think from that role's expertise -3. **Apply Checklist**: Use role-specific checklist from `checklists/` -4. **Maintain Context**: Keep cached documents in memory -5. **Complete Step**: Finish all step requirements before switching - -Example role switches: -- Step 2-3: SM (story creation and validation) -- Step 4: SM β†’ TEA (switch to test mindset) -- Step 5-6: TEA β†’ DEV (switch to implementation mindset) -- Step 7: DEV β†’ SM (switch back for completion) - ---- - -## STATE MANAGEMENT - -### Pipeline State File - -Location: `{sprint_artifacts}/pipeline-state-{story_id}.yaml` - -```yaml -story_id: "1-4" -epic_num: 1 -story_num: 4 -mode: "interactive" -stepsCompleted: [1, 2, 3] -lastStep: 3 -currentStep: 4 -status: "in_progress" -started_at: "2025-01-15T10:00:00Z" -updated_at: "2025-01-15T11:30:00Z" -cached_context: - story_loaded: true - epic_loaded: true - architecture_sections: ["tech_stack", "data_model"] -steps: - step-01-init: { status: completed, duration: "0:02:15" } - step-02-create-story: { status: completed, duration: "0:15:30" } - step-03-validate-story: { status: completed, duration: "0:08:45" } - step-04-atdd: { status: in_progress } - step-05-implement: { status: pending } - step-06-code-review: { status: pending } - step-07-complete: { status: pending } - step-08-summary: { status: pending } -``` - -### Checkpoint/Resume - -To resume after failure: -```bash -bmad build --resume 1-4 -``` - -Resume logic: -1. Load state file for story 1-4 -2. Find `lastStep` completed -3. Load and execute step `lastStep + 1` -4. Continue from there - ---- - -## QUALITY GATES - -Each gate must pass before proceeding: - -### Story Creation Gate (Step 2) -- [ ] Story file created with proper frontmatter -- [ ] All acceptance criteria defined with Given/When/Then -- [ ] Technical context linked - -### Validation Gate (Step 3) -- [ ] Story passes adversarial review -- [ ] No ambiguous requirements -- [ ] Implementation path clear - -### ATDD Gate (Step 4) -- [ ] Tests exist for all acceptance criteria -- [ ] Tests fail (red phase verified) -- [ ] Test structure follows project patterns - -### Implementation Gate (Step 5) -- [ ] All tests pass (green phase) -- [ ] Code follows project patterns -- [ ] No TypeScript errors -- [ ] Lint passes - -### Post-Validation Gate (Step 5b) -- [ ] All completed tasks verified against codebase -- [ ] Zero false positives (or re-implementation complete) -- [ ] Files/functions/tests actually exist -- [ ] Tests actually pass (not just claimed) - -### Code Review Gate (Step 6) -- [ ] 3-10 specific issues identified (not "looks good") -- [ ] All issues resolved or documented -- [ ] Security review complete - ---- - -## SUCCESS METRICS - -### βœ… SUCCESS - -- Pipeline completes all 8 steps -- All quality gates passed -- Story status updated to "done" -- Git commit created -- Audit trail generated -- Token usage < 35K (target) - -### ❌ FAILURE - -- Step file instructions skipped or optimized -- Quality gate bypassed without approval -- Role not properly switched -- State file not updated -- Tests not verified to fail before implementation -- Code review accepts "looks good" - ---- - -## AUDIT TRAIL - -After completion, generate audit trail at: -`{sprint_artifacts}/audit-{story_id}-{date}.yaml` - -Contents: -- Pipeline execution timeline -- Step durations -- Quality gate results -- Issues found and resolved -- Files modified -- Token usage estimate diff --git a/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.yaml deleted file mode 100644 index be1e1a69..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-pipeline/workflow.yaml +++ /dev/null @@ -1,235 +0,0 @@ -name: story-pipeline -description: "Automated story development pipeline with token-efficient step-file architecture. Replaces separate Claude calls with single-session orchestration." -author: "BMad + digital-bridge" -version: "2.0.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{config_source}:sprint_artifacts" -communication_language: "{config_source}:communication_language" -date: system-generated - -# Workflow paths -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/story-pipeline" -steps_path: "{installed_path}/steps" -templates_path: "{installed_path}/templates" -checklists_path: "{installed_path}/checklists" - -# State management -state_file: "{sprint_artifacts}/pipeline-state-{{story_id}}.yaml" -audit_trail: "{sprint_artifacts}/audit-{{story_id}}-{{date}}.yaml" - -# Workflow modes -modes: - interactive: - description: "Human-in-the-loop with menu navigation between steps" - checkpoint_on_failure: true - requires_approval: true - fresh_context_for_review: false # Role switch instead - batch: - description: "Unattended execution with YOLO mode" - checkpoint_on_failure: true - requires_approval: false - fresh_context_for_review: true # Checkpoint before code review - fail_fast: true - -# Agent role definitions (loaded once, switched as needed) -agents: - sm: - name: "Scrum Master" - persona: "{project-root}/_bmad/bmm/agents/sm.md" - description: "Story creation, validation, sprint status" - used_in_steps: [2, 3, 7] - tea: - name: "Test Engineering Architect" - persona: "{project-root}/_bmad/bmm/agents/tea.md" - description: "ATDD test generation, red phase verification" - used_in_steps: [4] - dev: - name: "Developer" - persona: "{project-root}/_bmad/bmm/agents/dev.md" - description: "Implementation, post-validation, code review" - used_in_steps: [5, "5b", 6] - -# Step file definitions -steps: - - step: 1 - file: "{steps_path}/step-01-init.md" - name: "Initialize Pipeline" - description: "Load story context, detect mode, cache documents" - agent: null - quality_gate: false - - - step: "1b" - file: "{steps_path}/step-01b-resume.md" - name: "Resume from Checkpoint" - description: "Resume pipeline from last completed step" - agent: null - quality_gate: false - conditional: true # Only if resuming - - - step: 2 - file: "{steps_path}/step-02-create-story.md" - name: "Create Story" - description: "Generate detailed story from epic with research" - agent: sm - quality_gate: true - mcp_tools: [exa] - checklist: "{checklists_path}/story-creation.md" - - - step: 3 - file: "{steps_path}/step-03-validate-story.md" - name: "Validate Story" - description: "Adversarial validation of story completeness" - agent: sm - quality_gate: true - checklist: "{checklists_path}/story-validation.md" - - - step: 4 - file: "{steps_path}/step-04-atdd.md" - name: "ATDD Test Generation" - description: "Generate failing acceptance tests (red phase)" - agent: tea - quality_gate: true - checklist: "{checklists_path}/atdd.md" - - - step: 5 - file: "{steps_path}/step-05-implement.md" - name: "Implement Story" - description: "Implement code to pass tests (green phase)" - agent: dev - quality_gate: true - checklist: "{checklists_path}/implementation.md" - - - step: "5b" - file: "{steps_path}/step-05b-post-validation.md" - name: "Post-Implementation Validation" - description: "Verify completed tasks against codebase reality (catch false positives)" - agent: dev - quality_gate: true - iterative: true # May re-invoke step 5 if gaps found - - - step: 6 - file: "{steps_path}/step-06-code-review.md" - name: "Code Review" - description: "Adversarial code review finding 3-10 issues" - agent: dev - quality_gate: true - requires_fresh_context: true # In batch mode, checkpoint here - checklist: "{checklists_path}/code-review.md" - - - step: 7 - file: "{steps_path}/step-07-complete.md" - name: "Complete Story" - description: "Update sprint status, create git commit" - agent: sm - quality_gate: false - - - step: 8 - file: "{steps_path}/step-08-summary.md" - name: "Pipeline Summary" - description: "Generate audit trail and summary report" - agent: null - quality_gate: false - -# Document loading strategies (token optimization) -input_file_patterns: - story: - description: "Story file being developed" - pattern: "{sprint_artifacts}/story-{{epic_num}}-{{story_num}}.md" - load_strategy: "FULL_LOAD" - cache: true # Keep in memory across steps - - epics: - description: "Epic definitions with BDD scenarios" - whole: "{output_folder}/epic*.md" - sharded: "{output_folder}/epics/*.md" - load_strategy: "SELECTIVE_LOAD" # Only current epic - - architecture: - description: "Architecture decisions and constraints" - whole: "{output_folder}/architecture.md" - sharded: "{output_folder}/architecture/*.md" - load_strategy: "INDEX_GUIDED" # Use index for section selection - sections_needed: ["tech_stack", "data_model", "api_patterns"] - - prd: - description: "Product requirements" - whole: "{output_folder}/prd.md" - sharded: "{output_folder}/prd/*.md" - load_strategy: "SELECTIVE_LOAD" # Only relevant sections - - project_context: - description: "Critical rules and patterns" - pattern: "**/project-context.md" - load_strategy: "FULL_LOAD" - cache: true - -# MCP tool extensions -mcp_extensions: - exa: - description: "Web search for research during story creation" - used_in_steps: [2] - supabase: - description: "Database operations during implementation" - used_in_steps: [5] - -# Quality gates (must pass to proceed) -quality_gates: - story_creation: - step: 2 - criteria: - - "Story file created with proper frontmatter" - - "All acceptance criteria defined" - - "Technical context linked" - - story_validation: - step: 3 - criteria: - - "Story passes adversarial review" - - "No ambiguous requirements" - - "Implementation path clear" - - atdd: - step: 4 - criteria: - - "Tests exist for all acceptance criteria" - - "Tests fail (red phase verified)" - - "Test structure follows project patterns" - - implementation: - step: 5 - criteria: - - "All tests pass (green phase)" - - "Code follows project patterns" - - "No TypeScript errors" - - post_validation: - step: "5b" - criteria: - - "All completed tasks verified against codebase" - - "Zero false positives remaining" - - "Files/functions/tests actually exist" - - "Tests actually pass (not just claimed)" - - code_review: - step: 6 - criteria: - - "3-10 specific issues identified" - - "All issues resolved or documented" - - "Security review complete" - -# Audit trail configuration -audit: - enabled: true - output_file: "{audit_trail}" - include: - - timestamps - - step_durations - - quality_gate_results - - issues_found - - files_modified - - token_usage - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/README.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/README.md deleted file mode 100644 index 87046325..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/README.md +++ /dev/null @@ -1,135 +0,0 @@ -# Super-Dev-Pipeline v2.0 - GSDMAD Architecture - -**Multi-agent pipeline with independent validation and adversarial code review** - ---- - -## Quick Start - -```bash -# Use v2.0 for a story -/story-full-pipeline mode=multi_agent story_key=17-10 - -# Use v1.x (fallback) -/story-full-pipeline mode=single_agent story_key=17-10 -``` - ---- - -## What's New in v2.0 - -### Multi-Agent Validation -- **4 independent agents** instead of 1 -- Builder β†’ Inspector β†’ Reviewer β†’ Fixer -- Each agent has fresh context -- No conflict of interest - -### Honest Reporting -- Inspector verifies Builder's work (doesn't trust claims) -- Reviewer is adversarial (wants to find issues) -- Main orchestrator does final verification -- Can't fake completion - -### Wave-Based Execution -- Independent stories run in parallel -- Dependencies respected via waves -- 57% faster than sequential - ---- - -## Architecture - -See `workflow.md` for complete architecture details. - -**Agent Prompts:** -- `agents/builder.md` - Implementation agent -- `agents/inspector.md` - Validation agent -- `agents/reviewer.md` - Adversarial review agent -- `agents/fixer.md` - Issue resolution agent - -**Workflow Config:** -- `workflow.yaml` - Main configuration -- `workflow.md` - Complete documentation - ---- - -## Why v2.0? - -### The Problem with v1.x - -Single agent does ALL steps: -1. Implement code -2. Validate own work ← Conflict of interest -3. Review own code ← Even worse -4. Commit changes - -**Result:** Agent can lie, skip steps, fake completion - -### The Solution in v2.0 - -Separate agents for each phase: -1. Builder implements (no validation) -2. Inspector validates (fresh context, no knowledge of Builder) -3. Reviewer reviews (adversarial, wants to find issues) -4. Fixer fixes (addresses review findings) -5. Main orchestrator verifies (final quality gate) - -**Result:** Honest reporting, real validation, quality enforcement - ---- - -## Comparison - -| Metric | v1.x | v2.0 | -|--------|------|------| -| Agents | 1 | 4 | -| Context Fresh | No | Yes (each phase) | -| Validation | Self | Independent | -| Review | Self | Adversarial | -| Honesty | 60% | 95% | -| Completion Accuracy | Low | High | - ---- - -## Migration Guide - -**For new stories:** Use v2.0 by default -**For existing workflows:** Keep v1.x until tested - -**Testing v2.0:** -1. Run on 3-5 stories -2. Compare results with v1.x -3. Measure time and quality -4. Make v2.0 default after validation - ---- - -## Files in This Directory - -``` -story-full-pipeline/ -β”œβ”€β”€ README.md (this file) -β”œβ”€β”€ workflow.yaml (configuration) -β”œβ”€β”€ workflow.md (complete documentation) -β”œβ”€β”€ agents/ -β”‚ β”œβ”€β”€ builder.md (implementation agent prompt) -β”‚ β”œβ”€β”€ inspector.md (validation agent prompt) -β”‚ β”œβ”€β”€ reviewer.md (review agent prompt) -β”‚ └── fixer.md (fix agent prompt) -└── steps/ - └── (step files from v1.x, adapted for multi-agent) -``` - ---- - -## Next Steps - -1. **Test v2.0** on Epic 18 stories -2. **Measure improvements** (time, quality, honesty) -3. **Refine agent prompts** based on results -4. **Make v2.0 default** after validation -5. **Deprecate v1.x** in 6 months - ---- - -**Philosophy:** Trust but verify. Every agent's work is independently validated by a fresh agent with no conflict of interest. diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/builder.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/builder.md deleted file mode 100644 index cefa510a..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/builder.md +++ /dev/null @@ -1,166 +0,0 @@ -# Builder Agent - Implementation Phase - -**Role:** Implement story requirements (code + tests) -**Steps:** 1-4 (init, pre-gap, write-tests, implement) -**Trust Level:** LOW (assume will cut corners) - - -@patterns/hospital-grade.md -@patterns/tdd.md -@patterns/agent-completion.md - - ---- - -## Your Mission - -You are the **BUILDER** agent. Your job is to implement the story requirements by writing production code and tests. - -**DO:** -- Load and understand the story requirements -- Analyze what exists vs what's needed -- Write tests first (TDD approach) -- Implement production code to make tests pass -- Follow project patterns and conventions - -**DO NOT:** -- Validate your own work (Inspector agent will do this) -- Review your own code (Reviewer agent will do this) -- Update story checkboxes (Fixer agent will do this) -- Commit changes (Fixer agent will do this) -- Update sprint-status.yaml (Fixer agent will do this) - ---- - -## Steps to Execute - -### Step 1: Initialize -Load story file and cache context: -- Read story file: `{{story_file}}` -- Parse all sections (Business Context, Acceptance Criteria, Tasks, etc.) -- Determine greenfield vs brownfield -- Cache key information for later steps - -### Step 2: Pre-Gap Analysis -Validate tasks and detect batchable patterns: -- Scan codebase for existing implementations -- Identify which tasks are done vs todo -- Detect repetitive patterns (migrations, installs, etc.) -- Report gap analysis results - -### Step 3: Write Tests -TDD approach - tests before implementation: -- For greenfield: Write comprehensive test suite -- For brownfield: Add tests for new functionality -- Use project's test framework -- Aim for 90%+ coverage - -### Step 4: Implement -Write production code: -- Implement to make tests pass -- Follow existing patterns -- Handle edge cases -- Keep it simple (no over-engineering) - ---- - -## Output Requirements - -When complete, provide: - -1. **Files Created/Modified** - - List all files you touched - - Brief description of each change - -2. **Implementation Summary** - - What you built - - Key technical decisions - - Any assumptions made - -3. **Remaining Work** - - What still needs validation - - Any known issues or concerns - -4. **DO NOT CLAIM:** - - "Tests pass" (you didn't run them) - - "Code reviewed" (you didn't review it) - - "Story complete" (you didn't verify it) - ---- - -## Hospital-Grade Standards - -βš•οΈ **Quality >> Speed** - -- Take time to do it right -- Don't skip error handling -- Don't leave TODO comments -- Don't use `any` types - ---- - -## CRITICAL: Create Completion Artifact - -**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. - -This is how the orchestrator verifies your work was actually done. - -**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-builder.json` - -**Format:** -```json -{ - "story_key": "{{story_key}}", - "agent": "builder", - "status": "SUCCESS", - "tasks_completed": [ - "Create PaymentProcessor service", - "Add retry logic with exponential backoff", - "Implement idempotency checks" - ], - "files_created": [ - "lib/billing/payment-processor.ts", - "lib/billing/__tests__/payment-processor.test.ts" - ], - "files_modified": [ - "lib/billing/worker.ts" - ], - "tests": { - "files": 2, - "cases": 15 - }, - "timestamp": "2026-01-27T02:30:00Z" -} -``` - -**Use Write tool to create this file. No exceptions.** - ---- - -## When Complete, Return This Format - -```markdown -## AGENT COMPLETE - -**Agent:** builder -**Story:** {{story_key}} -**Status:** SUCCESS | FAILED - -### Completion Artifact -βœ… Created: docs/sprint-artifacts/completions/{{story_key}}-builder.json - -### Implementation Summary -Brief description of what was built and key decisions made. - -### Ready For -Inspector validation (next phase) -``` - -**Why this artifact?** -- File exists = work done (binary verification) -- Orchestrator parses JSON to update story file -- No complex reconciliation logic needed - ---- - -**Remember:** You are the BUILDER. Build it well, but don't validate or review your own work. Other agents will do that with fresh eyes. diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/fixer.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/fixer.md deleted file mode 100644 index b6941763..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/fixer.md +++ /dev/null @@ -1,252 +0,0 @@ -# Fixer Agent - Issue Resolution Phase - -**Role:** Fix issues identified by Reviewer -**Steps:** 8-9 (review-analysis, fix-issues) -**Trust Level:** MEDIUM (incentive to minimize work) - - -@patterns/hospital-grade.md -@patterns/agent-completion.md - - ---- - -## Your Mission - -You are the **FIXER** agent. Your job is to fix CRITICAL and HIGH issues from the code review. - -**PRIORITY:** -1. Fix ALL CRITICAL issues (no exceptions) -2. Fix ALL HIGH issues (must do) -3. Fix MEDIUM issues if time allows (nice to have) -4. Skip LOW issues (gold-plating) - -**DO:** -- Fix security vulnerabilities immediately -- Fix logic bugs and edge cases -- Re-run tests after each fix -- Commit code changes with descriptive message - -**DO NOT:** -- Skip CRITICAL issues -- Skip HIGH issues -- Spend time on LOW issues -- Make unnecessary changes -- Update story checkboxes (orchestrator does this) -- Update sprint-status.yaml (orchestrator does this) - ---- - -## Steps to Execute - -### Step 8: Review Analysis - -**Categorize Issues from Code Review:** - -```yaml -critical_issues: [#1, #2] # MUST fix (security, data loss) -high_issues: [#3, #4, #5] # MUST fix (production bugs) -medium_issues: [#6, #7, #8, #9] # SHOULD fix if time -low_issues: [#10, #11] # SKIP (gold-plating) -``` - -**Filter Out Gold-Plating:** -- Ignore "could be better" suggestions -- Ignore "nice to have" improvements -- Focus on real problems only - -### Step 9: Fix Issues - -**For Each CRITICAL and HIGH Issue:** - -1. **Understand the Problem:** - - Read reviewer's description - - Locate the code - - Understand the security/logic flaw - -2. **Implement Fix:** - - Write the fix - - Verify it addresses the issue - - Don't introduce new problems - -3. **Re-run Tests:** - ```bash - npm run type-check # Must pass - npm run lint # Must pass - npm test # Must pass - ``` - -4. **Verify Fix:** - - Check the specific issue is resolved - - Ensure no regressions - ---- - -## After Fixing Issues - -### Commit Changes - -```bash -git add . -git commit -m "fix: {{story_key}} - address code review findings - -Fixed issues: -- #1: SQL injection in agreement route (CRITICAL) -- #2: Missing authorization check (CRITICAL) -- #3: N+1 query pattern (HIGH) -- #4: Missing error handling (HIGH) -- #5: Unhandled edge case (HIGH) - -All tests passing, type check clean, lint clean." -``` - ---- - -## Output Requirements - -**Provide Fix Summary:** - -```markdown -## Issue Resolution Summary - -### Fixed Issues: - -**#1: SQL Injection (CRITICAL)** -- Location: api/occupant/agreement/route.ts:45 -- Fix: Changed to parameterized query using Prisma -- Verification: Security test added and passing - -**#2: Missing Auth Check (CRITICAL)** -- Location: api/admin/rentals/spaces/[id]/route.ts:23 -- Fix: Added organizationId validation -- Verification: Cross-tenant test added and passing - -**#3: N+1 Query (HIGH)** -- Location: lib/rentals/expiration-alerts.ts:67 -- Fix: Batch-loaded admins with Map lookup -- Verification: Performance test shows 10x improvement - -[Continue for all CRITICAL + HIGH issues] - -### Deferred Issues: - -**MEDIUM (4 issues):** Deferred to follow-up story -**LOW (2 issues):** Rejected as gold-plating - ---- - -**Quality Checks:** -- βœ… Type check: PASS (0 errors) -- βœ… Linter: PASS (0 warnings) -- βœ… Build: PASS -- βœ… Tests: 48/48 passing (96% coverage) - -**Git:** -- βœ… Commit created: a1b2c3d -``` - ---- - -## Fix Priority Matrix - -| Severity | Action | Reason | -|----------|--------|--------| -| CRITICAL | MUST FIX | Security / Data loss | -| HIGH | MUST FIX | Production bugs | -| MEDIUM | SHOULD FIX | Technical debt | -| LOW | SKIP | Gold-plating | - ---- - -## Hospital-Grade Standards - -βš•οΈ **Fix It Right** - -- Don't skip security fixes -- Don't rush fixes (might break things) -- Test after each fix -- Verify the issue is actually resolved - ---- - -## CRITICAL: Create Completion Artifact - -**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. - -This is the FINAL agent artifact. The orchestrator uses this to update the story file. - -**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-fixer.json` - -**Format:** -```json -{ - "story_key": "{{story_key}}", - "agent": "fixer", - "status": "SUCCESS", - "issues_fixed": { - "critical": 2, - "high": 3, - "total": 5 - }, - "fixes_applied": [ - "Fixed SQL injection in agreement route (CRITICAL)", - "Added authorization check in admin route (CRITICAL)", - "Fixed N+1 query pattern (HIGH)" - ], - "files_modified": [ - "api/occupant/agreement/route.ts", - "api/admin/rentals/spaces/[id]/route.ts", - "lib/rentals/expiration-alerts.ts" - ], - "quality_checks": { - "type_check": "PASS", - "lint": "PASS", - "build": "PASS" - }, - "tests": { - "passing": 48, - "failing": 0, - "total": 48, - "coverage": 96 - }, - "git_commit": "a1b2c3d4e5f", - "timestamp": "2026-01-27T02:50:00Z" -} -``` - -**Use Write tool to create this file. No exceptions.** - ---- - -## When Complete, Return This Format - -```markdown -## AGENT COMPLETE - -**Agent:** fixer -**Story:** {{story_key}} -**Status:** SUCCESS | PARTIAL | FAILED - -### Completion Artifact -βœ… Created: docs/sprint-artifacts/completions/{{story_key}}-fixer.json - -### Issues Fixed -- **CRITICAL:** X/Y fixed -- **HIGH:** X/Y fixed -- **Total:** X issues resolved - -### Quality Checks -All checks PASS - -### Git Commit -βœ… Committed: abc123 - -### Ready For -Orchestrator reconciliation (story file updates) -``` - -**Note:** Story checkboxes and sprint-status updates are done by the orchestrator, not you. - ---- - -**Remember:** You are the FIXER. Fix real problems, skip gold-plating, commit when done. diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/inspector.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/inspector.md deleted file mode 100644 index a2d58833..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/inspector.md +++ /dev/null @@ -1,219 +0,0 @@ -# Inspector Agent - Validation Phase - -**Role:** Independent verification of Builder's work -**Steps:** 5-6 (post-validation, quality-checks) -**Trust Level:** MEDIUM (no conflict of interest) - - -@patterns/verification.md -@patterns/hospital-grade.md -@patterns/agent-completion.md - - ---- - -## Your Mission - -You are the **INSPECTOR** agent. Your job is to verify that the Builder actually did what they claimed. - -**KEY PRINCIPLE: You have NO KNOWLEDGE of what the Builder did. You are starting fresh.** - -**DO:** -- Verify files actually exist -- Run tests yourself (don't trust claims) -- Run quality checks (type-check, lint, build) -- Give honest PASS/FAIL verdict - -**DO NOT:** -- Take the Builder's word for anything -- Skip verification steps -- Assume tests pass without running them -- Give PASS verdict if ANY check fails - ---- - -## Steps to Execute - -### Step 5: Post-Validation - -**Verify Implementation Against Story:** - -1. **Check Files Exist:** - ```bash - # For each file mentioned in story tasks - ls -la {{file_path}} - # FAIL if file missing or empty - ``` - -2. **Verify File Contents:** - - Open each file - - Check it has actual code (not just TODO/stub) - - Verify it matches story requirements - -3. **Check Tests Exist:** - ```bash - # Find test files - find . -name "*.test.ts" -o -name "__tests__" - # FAIL if no tests found for new code - ``` - -### Step 6: Quality Checks - -**Run All Quality Gates:** - -1. **Type Check:** - ```bash - npm run type-check - # FAIL if any errors - ``` - -2. **Linter:** - ```bash - npm run lint - # FAIL if any errors or warnings - ``` - -3. **Build:** - ```bash - npm run build - # FAIL if build fails - ``` - -4. **Tests:** - ```bash - npm test -- {{story_specific_tests}} - # FAIL if any tests fail - # FAIL if tests are skipped - # FAIL if coverage < 90% - ``` - -5. **Git Status:** - ```bash - git status - # Check for uncommitted files - # List what was changed - ``` - ---- - -## Output Requirements - -**Provide Evidence-Based Verdict:** - -### If PASS: -```markdown -βœ… VALIDATION PASSED - -Evidence: -- Files verified: [list files checked] -- Type check: PASS (0 errors) -- Linter: PASS (0 warnings) -- Build: PASS -- Tests: 45/45 passing (95% coverage) -- Git: 12 files modified, 3 new files - -Ready for code review. -``` - -### If FAIL: -```markdown -❌ VALIDATION FAILED - -Failures: -1. File missing: app/api/occupant/agreement/route.ts -2. Type check: 3 errors in lib/api/auth.ts -3. Tests: 2 failing (api/occupant tests) - -Cannot proceed to code review until these are fixed. -``` - ---- - -## Verification Checklist - -**Before giving PASS verdict, confirm:** - -- [ ] All story files exist and have content -- [ ] Type check returns 0 errors -- [ ] Linter returns 0 errors/warnings -- [ ] Build succeeds -- [ ] Tests run and pass (not skipped) -- [ ] Test coverage >= 90% -- [ ] Git status is clean or has expected changes - -**If ANY checkbox is unchecked β†’ FAIL verdict** - ---- - -## Hospital-Grade Standards - -βš•οΈ **Be Thorough** - -- Don't skip checks -- Run tests yourself (don't trust claims) -- Verify every file exists -- Give specific evidence - ---- - -## CRITICAL: Create Completion Artifact - -**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. - -**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-inspector.json` - -**Format:** -```json -{ - "story_key": "{{story_key}}", - "agent": "inspector", - "status": "PASS", - "quality_checks": { - "type_check": "PASS", - "lint": "PASS", - "build": "PASS" - }, - "tests": { - "passing": 45, - "failing": 0, - "total": 45, - "coverage": 95 - }, - "files_verified": [ - "lib/billing/payment-processor.ts", - "lib/billing/__tests__/payment-processor.test.ts" - ], - "timestamp": "2026-01-27T02:35:00Z" -} -``` - -**Use Write tool to create this file. No exceptions.** - ---- - -## When Complete, Return This Format - -```markdown -## AGENT COMPLETE - -**Agent:** inspector -**Story:** {{story_key}} -**Status:** PASS | FAIL - -### Completion Artifact -βœ… Created: docs/sprint-artifacts/completions/{{story_key}}-inspector.json - -### Evidence Summary -- Type Check: PASS/FAIL -- Lint: PASS/FAIL -- Build: PASS/FAIL -- Tests: X passing, Y failing - -### Ready For -- If PASS: Reviewer (next phase) -- If FAIL: Builder needs to fix before proceeding -``` - ---- - -**Remember:** You are the INSPECTOR. Your job is to find the truth, not rubber-stamp the Builder's work. If something is wrong, say so with evidence. diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reviewer.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reviewer.md deleted file mode 100644 index f8bc137d..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reviewer.md +++ /dev/null @@ -1,262 +0,0 @@ -# Reviewer Agent - Adversarial Code Review - -**Role:** Find problems with the implementation -**Steps:** 7 (code-review) -**Trust Level:** HIGH (wants to find issues) - - -@patterns/security-checklist.md -@patterns/hospital-grade.md -@patterns/agent-completion.md - - ---- - -## Your Mission - -You are the **ADVERSARIAL REVIEWER**. Your job is to find problems, not rubber-stamp code. - -**MINDSET: Be critical. Look for flaws. Find issues.** - -**DO:** -- Approach code with skepticism -- Look for security vulnerabilities -- Find performance problems -- Identify logic bugs -- Check architecture compliance - -**DO NOT:** -- Rubber-stamp code as "looks good" -- Skip areas because they seem simple -- Assume the Builder did it right -- Give generic feedback - ---- - -## Review Focuses - -### CRITICAL (Security/Data Loss): -- SQL injection vulnerabilities -- XSS vulnerabilities -- Authentication bypasses -- Authorization gaps -- Hardcoded secrets -- Data loss scenarios - -### HIGH (Production Bugs): -- Logic errors -- Edge cases not handled -- Off-by-one errors -- Race conditions -- N+1 query patterns - -### MEDIUM (Technical Debt): -- Missing error handling -- Tight coupling -- Pattern violations -- Missing indexes -- Inefficient algorithms - -### LOW (Nice-to-Have): -- Missing optimistic UI -- Code duplication -- Better naming -- Additional tests - ---- - -## Review Process - -### 1. Security Review -```bash -# Check for common vulnerabilities -grep -r "eval\|exec\|innerHTML" . -grep -r "hardcoded.*password\|api.*key" . -grep -r "SELECT.*\+\|INSERT.*\+" . # SQL injection -``` - -### 2. Performance Review -```bash -# Look for N+1 patterns -grep -A 5 "\.map\|\.forEach" . | grep "await\|prisma" -# Check for missing indexes -grep "@@index" prisma/schema.prisma -``` - -### 3. Logic Review -- Read each function -- Trace execution paths -- Check edge cases -- Verify error handling - -### 4. Architecture Review -- Check pattern compliance -- Verify separation of concerns -- Check dependency directions - ---- - -## Output Requirements - -**Provide Specific, Actionable Issues:** - -```markdown -## Code Review Findings - -### CRITICAL Issues (2): - -**Issue #1: SQL Injection Vulnerability** -- **Location:** `api/occupant/agreement/route.ts:45` -- **Problem:** User input concatenated into query -- **Code:** - ```typescript - const query = `SELECT * FROM agreements WHERE id = '${params.id}'` - ``` -- **Fix:** Use parameterized queries -- **Severity:** CRITICAL (data breach risk) - -**Issue #2: Missing Authorization Check** -- **Location:** `api/admin/rentals/spaces/[id]/route.ts:23` -- **Problem:** No check that user owns the space -- **Impact:** Cross-tenant data access -- **Fix:** Add organizationId check -- **Severity:** CRITICAL (security bypass) - -### HIGH Issues (3): -[List specific issues with code locations] - -### MEDIUM Issues (4): -[List specific issues with code locations] - -### LOW Issues (2): -[List specific issues with code locations] - ---- - -**Summary:** -- Total issues: 11 -- MUST FIX: 5 (CRITICAL + HIGH) -- SHOULD FIX: 4 (MEDIUM) -- NICE TO HAVE: 2 (LOW) -``` - ---- - -## Issue Rating Guidelines - -**CRITICAL:** Security vulnerability or data loss -- SQL injection -- Auth bypass -- Hardcoded secrets -- Data corruption risk - -**HIGH:** Will cause production bugs -- Logic errors -- Unhandled edge cases -- N+1 queries -- Missing indexes - -**MEDIUM:** Technical debt or maintainability -- Missing error handling -- Pattern violations -- Tight coupling - -**LOW:** Nice-to-have improvements -- Optimistic UI -- Better naming -- Code duplication - ---- - -## Review Checklist - -Before completing review, check: - -- [ ] Reviewed all new files -- [ ] Checked for security vulnerabilities -- [ ] Looked for performance problems -- [ ] Verified error handling -- [ ] Checked architecture compliance -- [ ] Provided specific code locations for each issue -- [ ] Rated each issue (CRITICAL/HIGH/MEDIUM/LOW) - ---- - -## Hospital-Grade Standards - -βš•οΈ **Be Thorough and Critical** - -- Don't let things slide -- Find real problems -- Be specific (not generic) -- Assume code has issues (it usually does) - ---- - -## CRITICAL: Create Completion Artifact - -**MANDATORY:** Before returning, you MUST create a completion artifact JSON file. - -**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-reviewer.json` - -**Format:** -```json -{ - "story_key": "{{story_key}}", - "agent": "reviewer", - "status": "ISSUES_FOUND", - "issues": { - "critical": 2, - "high": 3, - "medium": 4, - "low": 2, - "total": 11 - }, - "must_fix": [ - { - "severity": "CRITICAL", - "location": "api/occupant/agreement/route.ts:45", - "description": "SQL injection vulnerability - user input in query" - }, - { - "severity": "HIGH", - "location": "lib/rentals/expiration-alerts.ts:67", - "description": "N+1 query pattern causes performance issues" - } - ], - "files_reviewed": [ - "api/occupant/agreement/route.ts", - "lib/rentals/expiration-alerts.ts" - ], - "timestamp": "2026-01-27T02:40:00Z" -} -``` - -**Use Write tool to create this file. No exceptions.** - ---- - -## When Complete, Return This Format - -```markdown -## AGENT COMPLETE - -**Agent:** reviewer -**Story:** {{story_key}} -**Status:** ISSUES_FOUND | CLEAN - -### Completion Artifact -βœ… Created: docs/sprint-artifacts/completions/{{story_key}}-reviewer.json - -### Issue Summary -- **CRITICAL:** X issues -- **HIGH:** X issues -- **MUST FIX:** X total (CRITICAL + HIGH) - -### Ready For -Fixer agent to address CRITICAL and HIGH issues -``` - ---- - -**Remember:** You are the ADVERSARIAL REVIEWER. Your success is measured by finding legitimate issues. Don't be nice - be thorough. diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md deleted file mode 100644 index 8baf2a0b..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md +++ /dev/null @@ -1,215 +0,0 @@ -# Super-Dev-Pipeline v3.1 - Token-Efficient Multi-Agent Pipeline - - -Implement a story using parallel verification agents with Builder context reuse. -Each agent has single responsibility. Builder fixes issues in its own context (50-70% token savings). -Orchestrator handles bookkeeping (story file updates, verification). - - - -**Token-Efficient Multi-Agent Pipeline** - -- Builder implements (creative, context preserved) -- Inspector + Reviewers validate in parallel (verification, fresh context) -- Builder fixes issues (creative, reuses context - 50-70% token savings) -- Inspector re-checks (verification, quick check) -- Orchestrator reconciles story file (mechanical) - -**Key Innovation:** Resume Builder instead of spawning fresh Fixer. -Builder already knows the codebase - just needs to fix specific issues. - -Trust but verify. Fresh context for verification. Reuse context for fixes. - - - -name: story-full-pipeline -version: 3.1.0 -execution_mode: multi_agent - -phases: - phase_1: Builder (saves agent_id) - phase_2: [Inspector + N Reviewers] in parallel (N = 1/2/3 based on complexity) - phase_3: Resume Builder with all findings (reuses context) - phase_4: Inspector re-check (quick verification) - phase_5: Orchestrator reconciliation - -reviewer_counts: - micro: 1 reviewer (security only) - standard: 2 reviewers (security, performance) - complex: 3 reviewers (security, performance, code quality) - -token_efficiency: - - Phase 2 agents spawn in parallel (same cost, faster) - - Phase 3 resumes Builder (50-70% token savings vs fresh Fixer) - - Phase 4 Inspector only (no full re-review) - - - -@patterns/hospital-grade.md -@patterns/agent-completion.md - - - - - -Load and validate the story file. - -\`\`\`bash -STORY_FILE="docs/sprint-artifacts/{{story_key}}.md" -[ -f "$STORY_FILE" ] || { echo "ERROR: Story file not found"; exit 1; } -\`\`\` - -Use Read tool on the story file. Parse: -- Complexity level (micro/standard/complex) -- Task count -- Acceptance criteria count - -Determine which agents to spawn based on complexity routing. - - - -**Phase 1: Builder Agent (Steps 1-4)** - -\`\`\` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”¨ PHASE 1: BUILDER -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -\`\`\` - -Spawn Builder agent and save agent_id for later resume. - -**CRITICAL: Save Builder's agent_id for later resume** - -\`\`\` -BUILDER_AGENT_ID={{agent_id_from_task_result}} -echo "Builder agent: $BUILDER_AGENT_ID" -\`\`\` - -Wait for completion. Parse structured output. Verify files exist. - -If files missing or status FAILED: halt pipeline. - - - -**Phase 2: Parallel Verification (Inspector + Reviewers)** - -\`\`\` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” PHASE 2: PARALLEL VERIFICATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -\`\`\` - -**CRITICAL: Spawn ALL verification agents in ONE message (parallel execution)** - -Determine reviewer count based on complexity: -\`\`\` -if complexity == "micro": REVIEWER_COUNT = 1 -if complexity == "standard": REVIEWER_COUNT = 2 -if complexity == "complex": REVIEWER_COUNT = 3 -\`\`\` - -Spawn Inspector + N Reviewers in single message. Wait for ALL agents to complete. Collect findings. - -Aggregate all findings from Inspector + Reviewers. - - - -**Phase 3: Resume Builder with All Findings** - -\`\`\` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”§ PHASE 3: RESUME BUILDER (Fix Issues) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -\`\`\` - -**CRITICAL: Resume Builder agent (reuses context!)** - -Use Task tool with `resume: "{{BUILDER_AGENT_ID}}"` parameter. - -Builder receives all consolidated findings and fixes: -1. ALL CRITICAL issues (security, blockers) -2. ALL HIGH issues (bugs, logic errors) -3. MEDIUM if quick (<30 min total) -4. Skip LOW (gold-plating) -5. Commit with descriptive message - -Wait for completion. Parse commit hash and fix counts. - - - -**Phase 4: Quick Inspector Re-Check** - -\`\`\` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… PHASE 4: RE-VERIFICATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -\`\`\` - -Spawn Inspector only (not full review). Quick functional verification. - -If FAIL: Resume Builder again with new issues. -If PASS: Proceed to reconciliation. - - - -**Phase 5: Orchestrator Reconciliation** - -\`\`\` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”§ PHASE 5: RECONCILIATION (Orchestrator) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -\`\`\` - -**YOU (orchestrator) do this directly. No agent spawn.** - -1. Get what was built (git log, git diff) -2. Read story file -3. Check off completed tasks (Edit tool) -4. Fill Dev Agent Record with pipeline details -5. Verify updates (grep task checkboxes) -6. Update sprint-status.yaml to "done" - - - -**Final Quality Gate** - -Verify: -1. Git commit exists -2. Story tasks checked (count > 0) -3. Dev Agent Record filled -4. Sprint status updated - -If verification fails: fix using Edit, then re-verify. - - - - - -**Builder fails:** Don't spawn verification. Report failure and halt. -**Inspector fails (Phase 2):** Still run Reviewers in parallel, collect all findings together. -**Inspector fails (Phase 4):** Resume Builder again with new issues (iterative fix loop). -**Builder resume fails:** Report unfixed issues. Manual intervention needed. -**Reconciliation fails:** Fix using Edit tool. Re-verify checkboxes. - - - -| Complexity | Pipeline | Reviewers | Total Phase 2 Agents | -|------------|----------|-----------|---------------------| -| micro | Builder β†’ [Inspector + 1 Reviewer] β†’ Resume Builder β†’ Inspector recheck | 1 (security) | 2 agents | -| standard | Builder β†’ [Inspector + 2 Reviewers] β†’ Resume Builder β†’ Inspector recheck | 2 (security, performance) | 3 agents | -| complex | Builder β†’ [Inspector + 3 Reviewers] β†’ Resume Builder β†’ Inspector recheck | 3 (security, performance, quality) | 4 agents | - -**Key Improvement:** All verification agents spawn in parallel (single message, faster execution). -**Token Savings:** Builder resume in Phase 3 saves 50-70% tokens vs spawning fresh Fixer. - - - -- [ ] Builder spawned and agent_id saved -- [ ] All verification agents completed in parallel -- [ ] Builder resumed with consolidated findings -- [ ] Inspector recheck passed -- [ ] Git commit exists for story -- [ ] Story file has checked tasks (count > 0) -- [ ] Dev Agent Record filled with all phases -- [ ] Sprint status updated to "done" - diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml deleted file mode 100644 index 6ab01b6d..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml +++ /dev/null @@ -1,123 +0,0 @@ -name: super-dev-pipeline -description: "Multi-agent pipeline with wave-based execution, independent validation, and adversarial code review (GSDMAD)" -author: "BMAD Method + GSD" -version: "2.0.0" - -# Execution mode -execution_mode: "multi_agent" # multi_agent | single_agent (fallback) - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -sprint_artifacts: "{config_source}:sprint_artifacts" -communication_language: "{config_source}:communication_language" -date: system-generated - -# Workflow paths -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-pipeline" -agents_path: "{installed_path}/agents" -steps_path: "{installed_path}/steps" - -# Agent tracking (from GSD) -agent_history: "{sprint_artifacts}/agent-history.json" -current_agent_id: "{sprint_artifacts}/current-agent-id.txt" - -# State management -state_file: "{sprint_artifacts}/super-dev-state-{{story_id}}.yaml" -audit_trail: "{sprint_artifacts}/audit-super-dev-{{story_id}}-{{date}}.yaml" - -# Multi-agent configuration -agents: - builder: - description: "Implementation agent - writes code and tests" - steps: [1, 2, 3, 4] - subagent_type: "general-purpose" - prompt_file: "{agents_path}/builder.md" - trust_level: "low" # Assumes agent will cut corners - timeout: 3600 # 1 hour - - inspector: - description: "Validation agent - independent verification" - steps: [5, 6] - subagent_type: "general-purpose" - prompt_file: "{agents_path}/inspector.md" - fresh_context: true # No knowledge of builder agent - trust_level: "medium" # No conflict of interest - timeout: 1800 # 30 minutes - - reviewer: - description: "Adversarial code review - finds problems" - steps: [7] - subagent_type: "multi-agent-review" # Spawns multiple reviewers - prompt_file: "{agents_path}/reviewer.md" - fresh_context: true - adversarial: true # Goal: find issues - trust_level: "high" # Wants to find problems - timeout: 1800 # 30 minutes - review_agent_count: - micro: 2 - standard: 4 - complex: 6 - - fixer: - description: "Issue resolution - fixes critical/high issues" - steps: [8, 9] - subagent_type: "general-purpose" - prompt_file: "{agents_path}/fixer.md" - trust_level: "medium" # Incentive to minimize work - timeout: 2400 # 40 minutes - -# Reconciliation: orchestrator does this directly (see workflow.md Phase 5) - -# Complexity level (determines which steps to execute) -complexity_level: "standard" # micro | standard | complex - -# Complexity routing -complexity_routing: - micro: - skip_agents: ["reviewer"] # Skip code review for micro stories - description: "Lightweight path for low-risk stories" - examples: ["UI tweaks", "text changes", "simple CRUD"] - - standard: - skip_agents: [] # Full pipeline - description: "Balanced path for medium-risk stories" - examples: ["API endpoints", "business logic"] - - complex: - skip_agents: [] # Full pipeline + enhanced review - description: "Enhanced validation for high-risk stories" - examples: ["Auth", "payments", "security", "migrations"] - review_focus: ["security", "performance", "architecture"] - -# Final verification checklist (main orchestrator) -final_verification: - enabled: true - checks: - - name: "git_commits" - command: "git log --oneline -3 | grep {{story_key}}" - failure_message: "No commit found for {{story_key}}" - - - name: "story_checkboxes" - command: | - before=$(git show HEAD~1:{{story_file}} | grep -c '^- \[x\]') - after=$(grep -c '^- \[x\]' {{story_file}}) - [ $after -gt $before ] - failure_message: "Story checkboxes not updated" - - - name: "sprint_status" - command: "git diff HEAD~1 {{sprint_status}} | grep '{{story_key}}'" - failure_message: "Sprint status not updated" - - - name: "tests_passed" - # Parse agent output for test evidence - validation: "inspector_output must contain 'PASS' or test count" - failure_message: "No test evidence in validation output" - -# Backward compatibility -fallback_to_v1: - enabled: true - condition: "execution_mode == 'single_agent'" - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-pipeline" - -standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md deleted file mode 100644 index 20dcfea4..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md +++ /dev/null @@ -1,311 +0,0 @@ -# Super Dev Story v3.0 - Development with Quality Gates - - -Complete story development pipeline: dev-story β†’ validation β†’ code review β†’ push. -Automatically re-invokes dev-story if gaps or review issues found. -Ensures production-ready code before pushing. - - - -**Quality Over Speed** - -Don't just implementβ€”verify, review, fix. -- Run dev-story for implementation -- Validate with gap analysis -- Code review for quality -- Fix issues before pushing -- Only push when truly ready - - - -name: super-dev-story -version: 3.0.0 - -stages: - - dev-story: "Implement the story" - - validate: "Run gap analysis" - - review: "Code review" - - push: "Safe commit and push" - -defaults: - max_rework_loops: 3 - auto_push: false - review_depth: "standard" # quick | standard | deep - validation_depth: "quick" - -quality_gates: - validation_threshold: 90 # % tasks must be verified - review_threshold: "pass" # pass | pass_with_warnings - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Load story and prepare pipeline** - -```bash -STORY_FILE="{{story_file}}" -[ -f "$STORY_FILE" ] || { echo "❌ story_file required"; exit 1; } -``` - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸš€ SUPER DEV STORY PIPELINE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{story_key}} -Stages: dev-story β†’ validate β†’ review β†’ push - -Quality Gates: -- Validation: β‰₯{{validation_threshold}}% verified -- Review: {{review_threshold}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Initialize: -- rework_count = 0 -- stage = "dev-story" - - - -**Stage 1: Implement the story** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“ STAGE 1: DEV-STORY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Invoke dev-story workflow: -``` -/dev-story story_file={{story_file}} -``` - -Wait for completion. Capture: -- files_created -- files_modified -- tasks_completed - -``` -βœ… Dev-story complete -Files: {{file_count}} created/modified -Tasks: {{tasks_completed}}/{{total_tasks}} -``` - - - -**Stage 2: Validate implementation** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” STAGE 2: VALIDATION -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Invoke validation: -``` -/validate scope=story target={{story_file}} depth={{validation_depth}} -``` - -Capture results: -- verified_pct -- false_positives -- category - -**Check quality gate:** -``` -if verified_pct < validation_threshold: - REWORK_NEEDED = true - reason = "Validation below {{validation_threshold}}%" - -if false_positives > 0: - REWORK_NEEDED = true - reason = "{{false_positives}} tasks marked done but missing" -``` - -``` -{{#if REWORK_NEEDED}} -⚠️ Validation failed: {{reason}} -{{else}} -βœ… Validation passed: {{verified_pct}}% verified -{{/if}} -``` - - - -**Stage 3: Code review** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ STAGE 3: CODE REVIEW -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -Invoke code review: -``` -/multi-agent-review files={{files_modified}} depth={{review_depth}} -``` - -Capture results: -- verdict (PASS, PASS_WITH_WARNINGS, NEEDS_REWORK) -- issues - -**Check quality gate:** -``` -if verdict == "NEEDS_REWORK": - REWORK_NEEDED = true - reason = "Code review found blocking issues" - -if review_threshold == "pass" AND verdict == "PASS_WITH_WARNINGS": - REWORK_NEEDED = true - reason = "Warnings not allowed in strict mode" -``` - -``` -{{#if REWORK_NEEDED}} -⚠️ Review failed: {{reason}} -Issues: {{issues}} -{{else}} -βœ… Review passed: {{verdict}} -{{/if}} -``` - - - -**Handle rework loop** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”„ REWORK REQUIRED (Loop {{rework_count + 1}}/{{max_rework_loops}}) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Reason: {{reason}} - -{{#if validation_issues}} -Validation Issues: -{{#each validation_issues}} -- {{this}} -{{/each}} -{{/if}} - -{{#if review_issues}} -Review Issues: -{{#each review_issues}} -- {{this}} -{{/each}} -{{/if}} -``` - -**Check loop limit:** -``` -rework_count++ -if rework_count > max_rework_loops: - echo "❌ Max rework loops exceeded" - echo "Manual intervention required" - HALT -``` - -**Re-invoke dev-story with issues:** -``` -/dev-story story_file={{story_file}} fix_issues={{issues}} -``` - -After dev-story completes, return to validation stage. - - - -**Stage 4: Push changes** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“¦ STAGE 4: PUSH -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Generate commit message from story:** -``` -feat({{epic}}): {{story_title}} - -- Implemented {{task_count}} tasks -- Verified: {{verified_pct}}% -- Review: {{verdict}} - -Story: {{story_key}} -``` - -**If auto_push:** -``` -/push-all commit_message="{{message}}" auto_push=true -``` - -**Otherwise, ask:** -``` -Ready to push? - -[Y] Yes, push now -[N] No, keep local (can push later) -[R] Review changes first -``` - - - -**Display pipeline results** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -βœ… SUPER DEV STORY COMPLETE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Story: {{story_key}} - -Pipeline Results: -- Dev-Story: βœ… Complete -- Validation: βœ… {{verified_pct}}% verified -- Review: βœ… {{verdict}} -- Push: {{pushed ? "βœ… Pushed" : "⏸️ Local only"}} - -Rework Loops: {{rework_count}} -Files Changed: {{file_count}} -Commit: {{commit_hash}} - -{{#if pushed}} -Branch: {{branch}} -Ready for PR: gh pr create -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - - - -```bash -# Standard pipeline -/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md - -# With auto-push -/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md auto_push=true - -# Strict review mode -/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md review_threshold=pass -``` - - - -**Dev-story fails:** Report error, halt pipeline. -**Validation below threshold:** Enter rework loop. -**Review finds blocking issues:** Enter rework loop. -**Max rework loops exceeded:** Halt, require manual intervention. -**Push fails:** Report error, commit preserved locally. - - - -- [ ] Dev-story completed -- [ ] Validation β‰₯ threshold -- [ ] Review passed -- [ ] Changes committed -- [ ] Pushed (if requested) -- [ ] Story status updated - diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml deleted file mode 100644 index 7185b853..00000000 --- a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml +++ /dev/null @@ -1,37 +0,0 @@ -name: super-dev-story -description: "Enhanced story development with post-implementation validation and automated code review - ensures stories are truly complete before marking done" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -story_dir: "{config_source}:implementation_artifacts" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-story" -instructions: "{installed_path}/workflow.md" -validation: "{installed_path}/checklist.md" - -story_file: "" # Explicit story path; auto-discovered if empty -implementation_artifacts: "{config_source}:implementation_artifacts" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" -project_context: "**/project-context.md" - -# Super-dev specific settings -super_dev_settings: - post_dev_gap_analysis: true - auto_code_review: true - fail_on_critical_issues: true - max_fix_iterations: 3 - -# Autonomous mode settings (passed from parent workflow like batch-super-dev) -auto_accept_gap_analysis: false # When true, skip gap analysis approval prompt - -standalone: true - -web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/validate/workflow.md b/src/modules/bmm/workflows/4-implementation/validate/workflow.md deleted file mode 100644 index 0cd95571..00000000 --- a/src/modules/bmm/workflows/4-implementation/validate/workflow.md +++ /dev/null @@ -1,353 +0,0 @@ -# Validate v3.0 - Unified Story/Epic Validation - - -Single workflow for all validation needs. Validates stories against codebase, -detects false positives (checked but not implemented), and reports health scores. -Read-only by default - does not modify files. - - - -**Trust But Verify** - -- Quick mode: Checkbox counting, file existence, pattern matching -- Deep mode: Haiku agents read actual code, verify implementation quality -- Categorize: VERIFIED_COMPLETE, NEEDS_REWORK, FALSE_POSITIVE, IN_PROGRESS -- Report accuracy gaps between claimed and actual completion - - - -name: validate -version: 3.0.0 - -parameters: - scope: - story: "Single story file" - epic: "All stories in an epic" - all: "All stories in sprint" - - target: "story_file path OR epic_number (depends on scope)" - - depth: - quick: "Checkbox counting, file existence checks" - deep: "Haiku agents verify actual code implementation" - - fix_mode: false # If true, update checkboxes and sprint-status - -defaults: - scope: story - depth: quick - fix_mode: false - batch_size: 10 - model_for_deep: haiku - -categories: - VERIFIED_COMPLETE: {score: ">=95", false_positives: 0} - COMPLETE_WITH_ISSUES: {score: ">=80", false_positives: "<=2"} - FALSE_POSITIVE: {score: "<50", description: "Claimed done but missing code"} - NEEDS_REWORK: {false_positives: ">2"} - IN_PROGRESS: {description: "Accurately reflects partial completion"} - NOT_STARTED: {checked: 0} - - - -@patterns/verification.md -@patterns/hospital-grade.md - - - - - -**Determine what to validate based on scope** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ” VALIDATION: {{scope}} scope, {{depth}} depth -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**If scope == story:** -```bash -STORY_FILE="{{target}}" -[ -f "$STORY_FILE" ] || { echo "❌ Story file not found"; exit 1; } -``` -stories_to_validate = [target] - -**If scope == epic:** -```bash -EPIC_NUM="{{target}}" -# Get stories from sprint-status.yaml matching epic -grep "^${EPIC_NUM}-" docs/sprint-artifacts/sprint-status.yaml -``` -stories_to_validate = all stories starting with `{epic_num}-` - -**If scope == all:** -```bash -# Find all story files, exclude meta-documents -find docs/sprint-artifacts -name "*.md" | grep -v "EPIC-\|COMPLETION\|REPORT\|README" -``` -stories_to_validate = all story files - -Display: -``` -Stories to validate: {{count}} -Depth: {{depth}} -{{#if depth == deep}} -Estimated cost: ~${{count * 0.13}} (Haiku agents) -{{/if}} -``` - - - -**Quick validation: checkbox counting and file checks** - -For each story: - -1. **Read story file** - Extract tasks, ACs, DoD -2. **Count checkboxes:** - ``` - total_tasks = count of "- [ ]" and "- [x]" - checked_tasks = count of "- [x]" - completion_pct = checked / total Γ— 100 - ``` - -3. **Check file existence** (from Dev Agent Record): - ```bash - for file in $FILE_LIST; do - [ -f "$file" ] && echo "βœ… $file" || echo "❌ $file MISSING" - done - ``` - -4. **Basic stub detection:** - ```bash - grep -l "TODO\|FIXME\|Not implemented\|throw new Error" $FILE_LIST - ``` - -5. **Categorize:** - - β‰₯95% checked + files exist β†’ VERIFIED_COMPLETE - - β‰₯80% checked β†’ COMPLETE_WITH_ISSUES - - Files missing for checked tasks β†’ FALSE_POSITIVE - - <50% checked β†’ IN_PROGRESS - - 0% checked β†’ NOT_STARTED - -6. **Store result** with score and category - - - -**Deep validation: Haiku agents verify actual code** - -For each story (or batch): - -Spawn Haiku agent: -``` -Task({ - subagent_type: "general-purpose", - model: "haiku", - description: "Deep validate {{story_id}}", - prompt: ` -Verify ALL tasks for story {{story_id}} by reading actual code. - -**Tasks to Verify:** -{{#each tasks}} -{{@index}}. [{{checked}}] {{text}} -{{/each}} - -**Files from Dev Agent Record:** -{{file_list}} - -**For EACH task:** -1. Find relevant files (Glob) -2. Read the files (Read tool) -3. Verify: Is it real code or stubs? Tests exist? Error handling? -4. Judge: actually_complete = true/false - -**Return JSON:** -{ - "story_id": "{{story_id}}", - "tasks": [ - { - "task_number": 0, - "is_checked": true, - "actually_complete": false, - "confidence": "high", - "evidence": "File has TODO on line 45", - "issues": ["Stub implementation", "No tests"] - } - ] -} -` -}) -``` - -Parse results: -- **False positive:** checked=true, actually_complete=false -- **False negative:** checked=false, actually_complete=true -- **Correct:** checked matches actually_complete - -Calculate verification score: -``` -score = (correct_count / total_count) Γ— 100 -score -= (false_positive_count Γ— 5) # Penalty for false positives -``` - - - -**Assign categories based on scores** - -| Category | Criteria | Recommended Status | -|----------|----------|-------------------| -| VERIFIED_COMPLETE | score β‰₯95, FP=0 | done | -| COMPLETE_WITH_ISSUES | score β‰₯80, FP≀2 | review | -| FALSE_POSITIVE | score <50 OR FP>5 | in-progress | -| NEEDS_REWORK | FP>2 | in-progress | -| IN_PROGRESS | partial completion | in-progress | -| NOT_STARTED | 0 checked | backlog | - -For each story: -- Compare current_status vs recommended_status -- Flag if status is inaccurate - - - -**Generate batch summary** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“Š VALIDATION SUMMARY -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Scope: {{scope}} {{#if target}}({{target}}){{/if}} -Stories Validated: {{count}} -Depth: {{depth}} - -Overall Health Score: {{health_score}}/100 - -By Category: -- βœ… VERIFIED_COMPLETE: {{verified_count}} ({{verified_pct}}%) -- ⚠️ NEEDS_REWORK: {{rework_count}} ({{rework_pct}}%) -- ❌ FALSE_POSITIVE: {{fp_count}} ({{fp_pct}}%) -- πŸ”„ IN_PROGRESS: {{progress_count}} ({{progress_pct}}%) -- πŸ“‹ NOT_STARTED: {{not_started_count}} - -Task Accuracy: -- Total tasks: {{total_tasks}} -- False positives: {{fp_tasks}} (checked but not done) -- False negatives: {{fn_tasks}} (done but not checked) -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**If FALSE_POSITIVE stories found:** -``` -❌ FALSE POSITIVE STORIES (Claimed Done, Not Implemented): - -{{#each fp_stories}} -- {{story_id}}: Score {{score}}/100, {{fp_task_count}} tasks missing - Current: {{current_status}} β†’ Should be: in-progress -{{/each}} - -Action: These stories need implementation work! -``` - - - -**Show single story validation result** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ“‹ STORY VALIDATION: {{story_id}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Epic: {{epic_num}} -Current Status: {{current_status}} -Recommended Status: {{recommended_status}} - -Verification Score: {{score}}/100 -Category: {{category}} - -Tasks: {{checked}}/{{total}} checked -{{#if depth == deep}} -- Verified complete: {{verified_count}} -- False positives: {{fp_count}} (checked but code missing) -- False negatives: {{fn_count}} (code exists, not checked) -{{/if}} - -{{#if category == "VERIFIED_COMPLETE"}} -βœ… Story is production-ready -{{else if category == "FALSE_POSITIVE"}} -❌ Story claimed done but has {{fp_count}} missing tasks - Action: Update status to in-progress, implement missing code -{{else if category == "NEEDS_REWORK"}} -⚠️ Story needs rework: {{fp_count}} tasks with issues -{{else if category == "IN_PROGRESS"}} -πŸ”„ Story accurately reflects partial completion -{{/if}} - -{{#if fp_tasks}} -**False Positive Tasks (checked but not done):** -{{#each fp_tasks}} -- [ ] {{task}} β€” {{evidence}} -{{/each}} -{{/if}} -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - - - -**Auto-fix mode: update files based on validation** - -``` -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -πŸ”§ AUTO-FIX MODE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -``` - -**Fix false negatives** (code exists but unchecked): -Use Edit tool to change `- [ ]` to `- [x]` for verified tasks - -**Update sprint-status.yaml:** -Use Edit tool to change status for inaccurate entries - -**DO NOT auto-fix false positives** (requires implementation work) - -``` -βœ… Auto-fix complete: -- {{fn_fixed}} false negatives checked -- {{status_fixed}} statuses updated -- {{fp_count}} false positives flagged (need manual implementation) -``` - - - - - -```bash -# Validate single story (quick) -/validate scope=story target=docs/sprint-artifacts/2-5-auth.md - -# Validate single story (deep - uses Haiku) -/validate scope=story target=docs/sprint-artifacts/2-5-auth.md depth=deep - -# Validate all stories in epic 2 -/validate scope=epic target=2 - -# Validate all stories in epic 2 (deep) -/validate scope=epic target=2 depth=deep - -# Validate entire sprint -/validate scope=all - -# Validate and auto-fix false negatives -/validate scope=all fix_mode=true -``` - - - -**Story file not found:** Skip with warning, continue batch. -**Haiku agent fails:** Fall back to quick validation for that story. -**All stories fail:** Report systemic issue, halt. - - - -- [ ] All target stories validated -- [ ] Categories assigned based on scores -- [ ] False positives identified -- [ ] Report generated -- [ ] Fixes applied (if fix_mode=true) - diff --git a/src/modules/bmm/workflows/4-implementation/validate/workflow.yaml b/src/modules/bmm/workflows/4-implementation/validate/workflow.yaml deleted file mode 100644 index deccd777..00000000 --- a/src/modules/bmm/workflows/4-implementation/validate/workflow.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: validate -description: "Unified validation workflow. Validates stories against codebase, detects false positives, reports health scores. Replaces validate-story, validate-story-deep, validate-all-stories, validate-all-stories-deep, validate-epic-status, validate-all-epics." -author: "BMad" -version: "3.0.0" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -implementation_artifacts: "{config_source}:implementation_artifacts" -story_dir: "{implementation_artifacts}" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/validate" -instructions: "{installed_path}/workflow.md" - -# Input variables -variables: - scope: "story" # story | epic | all - target: "" # story_file path OR epic_number (depends on scope) - depth: "quick" # quick | deep (deep uses Haiku agents) - fix_mode: false # If true, auto-fix false negatives and update statuses - -# Deep validation settings -deep_validation: - model: "haiku" - batch_size: 10 - cost_per_story: 0.13 - -# Output -default_output_file: "{story_dir}/.validation-{scope}-{date}.md" - -standalone: true -web_bundle: false diff --git a/test/unit/core/dependency-resolver-advanced.test.js b/test/unit/core/dependency-resolver-advanced.test.js index 4ed9a0b4..e9e25fb8 100644 --- a/test/unit/core/dependency-resolver-advanced.test.js +++ b/test/unit/core/dependency-resolver-advanced.test.js @@ -14,9 +14,9 @@ describe('DependencyResolver - Advanced Scenarios', () => { await fs.ensureDir(path.join(bmadDir, 'core', 'agents')); await fs.ensureDir(path.join(bmadDir, 'core', 'tasks')); await fs.ensureDir(path.join(bmadDir, 'core', 'templates')); - await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'agents')); - await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'tasks')); - await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'templates')); + await fs.ensureDir(path.join(bmadDir, 'bmm', 'agents')); + await fs.ensureDir(path.join(bmadDir, 'bmm', 'tasks')); + await fs.ensureDir(path.join(bmadDir, 'bmm', 'templates')); }); afterEach(async () => { @@ -33,7 +33,7 @@ dependencies: ["{project-root}/bmad/bmm/tasks/analyze.md"] --- Agent`, ); - await createTestFile(bmadDir, 'modules/bmm/tasks/analyze.md', 'BMM Task'); + await createTestFile(bmadDir, 'bmm/tasks/analyze.md', 'BMM Task'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, []); @@ -51,8 +51,8 @@ dependencies: ["{project-root}/bmad/bmm/tasks/*.md"] --- Agent`, ); - await createTestFile(bmadDir, 'modules/bmm/tasks/task1.md', 'Task 1'); - await createTestFile(bmadDir, 'modules/bmm/tasks/task2.md', 'Task 2'); + await createTestFile(bmadDir, 'bmm/tasks/task1.md', 'Task 1'); + await createTestFile(bmadDir, 'bmm/tasks/task2.md', 'Task 2'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); // Include bmm module @@ -154,16 +154,16 @@ Task content`, }); it('should resolve template from module path', async () => { - await createTestFile(bmadDir, 'modules/bmm/agents/agent.md', 'BMM Agent'); + await createTestFile(bmadDir, 'bmm/agents/agent.md', 'BMM Agent'); await createTestFile( bmadDir, - 'modules/bmm/tasks/task.md', + 'bmm/tasks/task.md', `--- template: "{project-root}/bmad/bmm/templates/prd-template.yaml" --- Task`, ); - await createTestFile(bmadDir, 'modules/bmm/templates/prd-template.yaml', 'template'); + await createTestFile(bmadDir, 'bmm/templates/prd-template.yaml', 'template'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); @@ -215,7 +215,7 @@ Task`, `, ); - await createTestFile(bmadDir, 'modules/bmm/tasks/create-prd.md', 'PRD Task'); + await createTestFile(bmadDir, 'bmm/tasks/create-prd.md', 'PRD Task'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, []); @@ -249,7 +249,7 @@ Task`, Use @task-custom-task `, ); - await createTestFile(bmadDir, 'modules/bmm/tasks/custom-task.md', 'Custom Task'); + await createTestFile(bmadDir, 'bmm/tasks/custom-task.md', 'Custom Task'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); @@ -265,7 +265,7 @@ Use @task-custom-task Use @agent-pm `, ); - await createTestFile(bmadDir, 'modules/bmm/agents/pm.md', 'PM'); + await createTestFile(bmadDir, 'bmm/agents/pm.md', 'PM'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); diff --git a/test/unit/core/dependency-resolver.test.js b/test/unit/core/dependency-resolver.test.js index 657390fa..5fe27376 100644 --- a/test/unit/core/dependency-resolver.test.js +++ b/test/unit/core/dependency-resolver.test.js @@ -585,7 +585,7 @@ Finally check bmad/core/tasks/review describe('module organization', () => { it('should organize files by module correctly', async () => { await createTestFile(bmadDir, 'core/agents/core-agent.md', 'Core'); - await createTestFile(bmadDir, 'modules/bmm/agents/bmm-agent.md', 'BMM'); + await createTestFile(bmadDir, 'bmm/agents/bmm-agent.md', 'BMM'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); @@ -638,9 +638,9 @@ Finally check bmad/core/tasks/review expect(module).toBe('core'); }); - it('should extract module from src/modules/bmm path', () => { + it('should extract module from src/bmm path', () => { const resolver = new DependencyResolver(); - const filePath = path.join(bmadDir, 'modules/bmm/agents/pm.md'); + const filePath = path.join(bmadDir, 'bmm/agents/pm.md'); const module = resolver.getModuleFromPath(bmadDir, filePath); @@ -651,12 +651,12 @@ Finally check bmad/core/tasks/review // Create installed structure (no src/ prefix) const installedDir = path.join(tmpDir, 'installed'); await fs.ensureDir(path.join(installedDir, 'core/agents')); - await fs.ensureDir(path.join(installedDir, 'modules/bmm/agents')); + await fs.ensureDir(path.join(installedDir, 'bmm/agents')); const resolver = new DependencyResolver(); const coreFile = path.join(installedDir, 'core/agents/agent.md'); - const moduleFile = path.join(installedDir, 'modules/bmm/agents/pm.md'); + const moduleFile = path.join(installedDir, 'bmm/agents/pm.md'); expect(resolver.getModuleFromPath(installedDir, coreFile)).toBe('core'); expect(resolver.getModuleFromPath(installedDir, moduleFile)).toBe('bmm'); @@ -764,7 +764,7 @@ dependencies: [] await createTestFile(bmadDir, 'core/agents/core-agent.md', 'Core'); await createTestFile( bmadDir, - 'modules/bmm/agents/bmm-agent.md', + 'bmm/agents/bmm-agent.md', `--- dependencies: ["{project-root}/bmad/core/tasks/shared-task.md"] --- @@ -783,8 +783,8 @@ dependencies: ["{project-root}/bmad/core/tasks/shared-task.md"] it('should resolve module tasks', async () => { await createTestFile(bmadDir, 'core/agents/core-agent.md', 'Core'); - await createTestFile(bmadDir, 'modules/bmm/agents/pm.md', 'PM'); - await createTestFile(bmadDir, 'modules/bmm/tasks/create-prd.md', 'Create PRD task'); + await createTestFile(bmadDir, 'bmm/agents/pm.md', 'PM'); + await createTestFile(bmadDir, 'bmm/tasks/create-prd.md', 'Create PRD task'); const resolver = new DependencyResolver(); const result = await resolver.resolve(bmadDir, ['bmm']); diff --git a/tools/build-docs.js b/tools/build-docs.js index 38bb379e..8946d70b 100644 --- a/tools/build-docs.js +++ b/tools/build-docs.js @@ -153,18 +153,18 @@ function generateLlmsTxt(outputDir) { '', '## Quick Start', '', - `- **[Quick Start](${SITE_URL}/docs/modules/bmm/quick-start)** - Get started with BMAD Method`, + `- **[Quick Start](${SITE_URL}/docs/bmm/quick-start)** - Get started with BMAD Method`, `- **[Installation](${SITE_URL}/docs/getting-started/installation)** - Installation guide`, '', '## Core Concepts', '', - `- **[Scale Adaptive System](${SITE_URL}/docs/modules/bmm/scale-adaptive-system)** - Understand BMAD scaling`, - `- **[Quick Flow](${SITE_URL}/docs/modules/bmm/bmad-quick-flow)** - Fast development workflow`, - `- **[Party Mode](${SITE_URL}/docs/modules/bmm/party-mode)** - Multi-agent collaboration`, + `- **[Scale Adaptive System](${SITE_URL}/docs/bmm/scale-adaptive-system)** - Understand BMAD scaling`, + `- **[Quick Flow](${SITE_URL}/docs/bmm/bmad-quick-flow)** - Fast development workflow`, + `- **[Party Mode](${SITE_URL}/docs/bmm/party-mode)** - Multi-agent collaboration`, '', '## Modules', '', - `- **[BMM - Method](${SITE_URL}/docs/modules/bmm/quick-start)** - Core methodology module`, + `- **[BMM - Method](${SITE_URL}/docs/bmm/quick-start)** - Core methodology module`, `- **[BMB - Builder](${SITE_URL}/docs/modules/bmb/)** - Agent and workflow builder`, `- **[BMGD - Game Dev](${SITE_URL}/docs/modules/bmgd/quick-start)** - Game development module`, '', diff --git a/tools/cli/installers/lib/core/dependency-resolver.js b/tools/cli/installers/lib/core/dependency-resolver.js index 5fe60120..ad857ac0 100644 --- a/tools/cli/installers/lib/core/dependency-resolver.js +++ b/tools/cli/installers/lib/core/dependency-resolver.js @@ -83,28 +83,38 @@ class DependencyResolver { // or if it contains a src subdirectory (production scenario) const hasSrcSubdir = await fs.pathExists(path.join(bmadDir, 'src')); const hasModulesSubdir = await fs.pathExists(path.join(bmadDir, 'modules')); + const hasCoreDir = await fs.pathExists(path.join(bmadDir, 'core')); + const hasBmmDir = await fs.pathExists(path.join(bmadDir, 'bmm')); if (hasModulesSubdir) { - // bmadDir is already the src directory (e.g., /path/to/src) - // Structure: bmadDir/core or bmadDir/modules/bmm + // bmadDir is already the src directory with modules/ subdirectory (legacy structure) + // Structure: bmadDir/core or bmadDir/bmm or bmadDir/modules/other if (module === 'core') { moduleDir = path.join(bmadDir, 'core'); } else if (module === 'bmm') { - moduleDir = path.join(bmadDir, 'modules', 'bmm'); + moduleDir = path.join(bmadDir, 'bmm'); } else { moduleDir = path.join(bmadDir, 'modules', module); } } else if (hasSrcSubdir) { // bmadDir is the parent of src directory (e.g., /path/to/BMAD-METHOD) - // Structure: bmadDir/src/core or bmadDir/src/modules/bmm + // Structure: bmadDir/src/core or bmadDir/src/bmm const srcDir = path.join(bmadDir, 'src'); if (module === 'core') { moduleDir = path.join(srcDir, 'core'); } else if (module === 'bmm') { - moduleDir = path.join(srcDir, 'modules', 'bmm'); + moduleDir = path.join(srcDir, 'bmm'); } else { moduleDir = path.join(srcDir, 'modules', module); } + } else if (hasCoreDir || hasBmmDir) { + // bmadDir IS the src directory without modules/ subdirectory (new structure) + // Structure: bmadDir/core or bmadDir/bmm + if (module === 'core') { + moduleDir = path.join(bmadDir, 'core'); + } else if (module === 'bmm') { + moduleDir = path.join(bmadDir, 'bmm'); + } } if (!moduleDir || !(await fs.pathExists(moduleDir))) { diff --git a/tools/cli/lib/yaml-xml-builder.js b/tools/cli/lib/yaml-xml-builder.js index ac140814..9e986bd6 100644 --- a/tools/cli/lib/yaml-xml-builder.js +++ b/tools/cli/lib/yaml-xml-builder.js @@ -510,7 +510,7 @@ class YamlXmlBuilder { const sourceHash = await this.calculateFileHash(agentYamlPath); const customizeHash = customizeYamlPath ? await this.calculateFileHash(customizeYamlPath) : null; - // Extract module from path (e.g., /path/to/modules/bmm/agents/pm.yaml -> bmm) + // Extract module from path (e.g., /path/to/bmm/agents/pm.yaml -> bmm) // or /path/to/bmad/bmm/agents/pm.yaml -> bmm // or /path/to/src/bmm/agents/pm.yaml -> bmm let module = 'core'; // default to core