317 lines
9.3 KiB
Markdown
317 lines
9.3 KiB
Markdown
# Fork Changes: @jonahschulte/bmad-method
|
||
|
||
This document describes the customizations and enhancements in this fork compared to the [upstream BMAD-METHOD repository](https://github.com/bmad-code-org/BMAD-METHOD).
|
||
|
||
## Overview
|
||
|
||
This fork extends the official BMAD Method with **production automation workflows** focused on:
|
||
|
||
- **Quality assurance automation** - Multi-stage validation pipelines
|
||
- **Token efficiency** - 50-70% reduction through complexity-based routing
|
||
- **Autonomous processing** - Unattended epic completion
|
||
- **Anti-vibe-coding enforcement** - Mandatory gap analysis and code review
|
||
- **Smart routing** - Micro stories skip unnecessary quality gates
|
||
|
||
**Stats:** ~26,000+ lines of additions across 122 files
|
||
|
||
---
|
||
|
||
## Key Features Added
|
||
|
||
### 1. Super-Dev Pipeline (`/super-dev-pipeline`)
|
||
|
||
A comprehensive quality workflow that ensures stories are **truly complete** before marking done:
|
||
|
||
```
|
||
Pre-validation → Development → Post-validation → Code Review → Fixes → Done ✅
|
||
```
|
||
|
||
**What it solves:**
|
||
- Prevents premature task completion ("stupid-dev" syndrome)
|
||
- Catches partial implementations
|
||
- Finds missed edge cases automatically
|
||
- Runs adversarial code review before human review
|
||
|
||
**Complexity-Based Routing (v1.3.0):**
|
||
- **MICRO stories** automatically skip steps 2 (pre-gap analysis) and 5 (code review)
|
||
- **STANDARD/COMPLEX stories** use full 7-step pipeline
|
||
- Early bailout checks prevent processing already-complete or invalid stories
|
||
- Token savings: 50-70% for micro stories, 90% for early bailouts
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/super-dev-pipeline/`
|
||
|
||
---
|
||
|
||
### 2. Story Pipeline v2.0 (`/story-pipeline`)
|
||
|
||
Single-session step-file architecture with **60-70% token savings**:
|
||
|
||
| Mode | Token Usage | Savings vs Legacy |
|
||
|------|-------------|-------------------|
|
||
| Interactive | ~25K | 65% |
|
||
| Batch (YOLO) | ~30K | 58% |
|
||
|
||
**How it works:**
|
||
- Replaces 6 separate Claude CLI calls with 1 session
|
||
- Just-in-time step loading
|
||
- Checkpoint/resume capability
|
||
- Role switching within session (SM → TEA → DEV → SM)
|
||
|
||
**Automated steps:**
|
||
1. Initialize & load context
|
||
2. Create story (SM role)
|
||
3. Validate story (adversarial - must find 3-10 issues)
|
||
4. ATDD test generation (TEA role)
|
||
5. Implementation (DEV role)
|
||
6. Code review (adversarial)
|
||
7. Complete & commit
|
||
8. Generate audit trail
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/story-pipeline/`
|
||
|
||
---
|
||
|
||
### 3. Batch Super-Dev (`/batch-super-dev`) ⭐ Primary
|
||
|
||
Interactive batch workflow for processing multiple stories with full quality gates:
|
||
|
||
```bash
|
||
/batch-super-dev
|
||
|
||
→ Select stories: 1-3,5,7 (or "all")
|
||
→ Validates story files (creates missing, regenerates invalid)
|
||
→ Scores complexity for each story (micro/standard/complex)
|
||
→ Routes to appropriate pipeline (lightweight vs full)
|
||
→ Processes each with super-dev-pipeline
|
||
→ Reconciles story status after each
|
||
→ All stories complete! ✅
|
||
```
|
||
|
||
**Features (v1.3.0):**
|
||
- **Complexity-Based Routing** ⭐ NEW - Smart pipeline selection
|
||
- **MICRO** (≤3 tasks, low risk): Lightweight path, skips gap analysis + code review (50-70% token savings)
|
||
- **STANDARD** (4-15 tasks): Full pipeline with all quality gates
|
||
- **COMPLEX** (≥16 tasks or high-risk): Enhanced validation, suggest splitting
|
||
- **Smart Story Validation** - Checks 12 required BMAD sections
|
||
- **Auto-Creation** - Creates missing story files with codebase gap analysis
|
||
- **Auto-Regeneration** - Regenerates invalid/incomplete stories
|
||
- **Sequential or Parallel** execution modes
|
||
- **Story Reconciliation** - Verifies checkboxes match implementation
|
||
- **Epic filtering** - Process only specific epic's stories
|
||
|
||
**Complexity Scoring Algorithm:**
|
||
```
|
||
complexity_score = task_count + (high_risk_keywords × 5) + (medium_risk_keywords × 2)
|
||
|
||
MICRO: task_count ≤ 3 AND score ≤ 5 AND file_count ≤ 5 AND no HIGH risk keywords
|
||
COMPLEX: task_count ≥ 16 OR score ≥ 20 OR has HIGH risk keywords (auth, security, payment, etc.)
|
||
STANDARD: everything else
|
||
```
|
||
|
||
**Risk Keywords:**
|
||
- **HIGH** (5 points): auth, security, payment, encryption, migration, database, schema
|
||
- **MEDIUM** (2 points): api, integration, external, third-party, cache
|
||
- **LOW** (0 points): ui, style, config, docs, test
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/batch-super-dev/`
|
||
|
||
---
|
||
|
||
### 4. Gap Analysis (`/gap-analysis`)
|
||
|
||
Dev-time codebase validation that solves the **batch planning staleness problem**:
|
||
|
||
**The Problem:** Stories planned days ago become stale as the codebase evolves.
|
||
|
||
**The Solution:** Mandatory gap analysis before development:
|
||
1. Scans current codebase
|
||
2. Validates DRAFT tasks against reality
|
||
3. Proposes refinements (add/modify/remove tasks)
|
||
4. User approves with 6 options: Y/A/n/e/s/r
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/gap-analysis/`
|
||
|
||
---
|
||
|
||
### 5. Push-All Workflow (`/push-all`)
|
||
|
||
Safe automated git operations with comprehensive safety checks:
|
||
|
||
- Secret detection (API keys, credentials)
|
||
- Large file warnings
|
||
- Build artifact detection
|
||
- Smart commit message generation
|
||
- Auto-push with error handling
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/push-all/`
|
||
|
||
---
|
||
|
||
### 7. Story Validation System
|
||
|
||
Multi-level story validation with LLM-powered verification:
|
||
|
||
| Workflow | Purpose |
|
||
|----------|---------|
|
||
| `/validate-story` | Single story validation |
|
||
| `/validate-story-deep` | Comprehensive deep validation |
|
||
| `/validate-all-stories` | Batch validation for epic |
|
||
| `/validate-all-stories-deep` | Deep validation for all stories |
|
||
| `/validate-epic-status` | Epic status reconciliation |
|
||
| `/validate-all-epics` | Full sprint validation |
|
||
|
||
**Location:** `src/modules/bmm/workflows/4-implementation/validate-*/`
|
||
|
||
---
|
||
|
||
### 8. Sprint Status Management Scripts
|
||
|
||
Python/TypeScript utilities for sprint tracking:
|
||
|
||
| Script | Purpose |
|
||
|--------|---------|
|
||
| `sprint-status-updater.py` | Update story statuses across epics |
|
||
| `task-verification-engine.py` | LLM-powered task completion verification |
|
||
| `llm-task-verifier.py` | Haiku-based task validation |
|
||
| `validation-progress-tracker.py` | Track validation progress |
|
||
| `add-status-fields.py` | Add status fields to story files |
|
||
|
||
**Features:**
|
||
- Bedrock/Claude API clients with rate limiting
|
||
- File utilities for story parsing
|
||
- Resumable validation runs
|
||
|
||
**Location:** `scripts/lib/`
|
||
|
||
---
|
||
|
||
### 9. BMAD Guide Skill
|
||
|
||
Automatic Claude Code skill for BMAD navigation:
|
||
|
||
```bash
|
||
# Auto-installed with BMAD
|
||
# Provides workflow selection guidance
|
||
```
|
||
|
||
**What it does:**
|
||
- Phase detection (where am I?)
|
||
- Project level routing
|
||
- Workflow decision tree
|
||
- Critical rules enforcement
|
||
|
||
**Location:** `resources/skills/bmad-guide.md`
|
||
|
||
---
|
||
|
||
### 10. Claude Code Commands
|
||
|
||
Pre-configured Claude CLI commands:
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `batch-super-dev` | Run batch super-dev pipeline |
|
||
| `story-pipeline` | Execute story pipeline |
|
||
| `super-dev-pipeline` | Run super-dev with quality gates |
|
||
| `validate-epic-status` | Validate epic status |
|
||
| `validate-all-epics` | Validate all epics |
|
||
|
||
**Location:** `.claude-commands/`
|
||
|
||
---
|
||
|
||
## Package Changes
|
||
|
||
```json
|
||
{
|
||
"name": "@jonahschulte/bmad-method",
|
||
"description": "...Enhanced with super-dev-pipeline and smart batching"
|
||
}
|
||
```
|
||
|
||
This fork is published to npm under the `@jonahschulte` scope for independent installation.
|
||
|
||
---
|
||
|
||
## Modules Modified
|
||
|
||
### BMM (BMAD Main Method)
|
||
- Enhanced `dev.agent.yaml` with new workflow menu items
|
||
- Enhanced `sm.agent.yaml` with new workflow menu items
|
||
- Modified `create-story` workflow for requirements-focused planning
|
||
- Enhanced `dev-story` workflow with gap analysis integration
|
||
|
||
### BMGD (BMAD Game Dev)
|
||
- Added parallel workflows for game development context
|
||
- Enhanced `game-dev.agent.yaml` and `game-scrum-master.agent.yaml`
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
This fork can be installed via:
|
||
|
||
```bash
|
||
npm install @jonahschulte/bmad-method
|
||
```
|
||
|
||
Or used directly by cloning this repository.
|
||
|
||
---
|
||
|
||
## Documentation Added
|
||
|
||
| Document | Purpose |
|
||
|----------|---------|
|
||
| `docs/super-dev-mode.md` | Super-dev workflow guide |
|
||
| `docs/autonomous-epic-processing.md` | Auto-epic documentation |
|
||
| `docs/gap-analysis.md` | Gap analysis user guide |
|
||
| `docs/gap-analysis-migration.md` | Migration from legacy |
|
||
| `docs/workflows/SPRINT-STATUS-SYNC-GUIDE.md` | Sprint status management |
|
||
| `docs/HOW-TO-VALIDATE-SPRINT-STATUS.md` | Validation how-to |
|
||
| `FEATURE-SUMMARY.md` | Complete feature overview |
|
||
| `INTEGRATION-NOTES.md` | Integration documentation |
|
||
| `TESTING-GUIDE.md` | Testing procedures |
|
||
|
||
---
|
||
|
||
## Compatibility
|
||
|
||
- **Backwards compatible** with upstream BMAD
|
||
- **No breaking changes** to existing workflows
|
||
- Users can opt-in to new features
|
||
- All schema validation passing
|
||
- All linting/formatting passing
|
||
- All tests passing
|
||
|
||
---
|
||
|
||
## Contributing Back
|
||
|
||
These features are candidates for upstream contribution:
|
||
|
||
1. **Gap Analysis** - Solves a real problem with batch planning
|
||
2. **Story Pipeline v2.0** - Significant token savings
|
||
3. **Super-Dev Mode** - Quality enforcement
|
||
|
||
See `PR-DESCRIPTION.md` and `PR-STORY-PIPELINE.md` for prepared PR descriptions.
|
||
|
||
---
|
||
|
||
## Last Sync with Upstream
|
||
|
||
**Date:** 2026-01-07
|
||
**Upstream Commit:** `5c766577` (Add CNAME file)
|
||
**Merge Commit:** `9df79392`
|
||
|
||
**Latest Fork Changes:**
|
||
- **Date:** 2026-01-07
|
||
- **Commit:** `9bdf4894` (Critical complexity routing fixes)
|
||
- **Features:** Complexity-based routing v1.3.0, multi-agent review integration
|
||
|
||
To sync with upstream:
|
||
```bash
|
||
git fetch upstream
|
||
git merge upstream/main
|
||
```
|