buildflow-dev 1.0.7 → 4.0.1

package/templates/commands/build.md

@@ -1,105 +1,116 @@
 ---
 name: buildflow-build
-description: Execute the plan with parallel Builder agents, auto-test and auto-fix each wave
+description: Execute the spec-traced plan wave-by-wave with auto-test and auto-fix per wave
 allowed-tools: Read, Write, Bash, Grep, Glob
 agents: builder, reviewer
 ---
 
 # /buildflow-build
 
-Execute the current phase plan. Spawns parallel Builder agents per wave. After every wave, automatically runs tests and fixes failures — the next wave does not start until the current wave passes all tests.
+Execute the current phase plan. Spawns parallel Builder agents per wave. Each wave auto-tests and auto-fixes until green. The next wave does not start until the current wave fully passes.
+
+Every task is traced to an acceptance criterion. Builders reference specs — not opinions.
 
 ## Usage
-- `/buildflow-build` — execute current phase plan (all waves, auto-test each)
-- `/buildflow-build wave-2` — execute and test a specific wave
+- `/buildflow-build` — execute all waves in the current plan
+- `/buildflow-build wave-2` — execute a specific wave
 - `/buildflow-build <task>` — build and test a single task
 
+## Context Packet for this command (load only these)
+- `.buildflow/phases/[N]/PLAN.md`
+- `.buildflow/memory/light.md` (app_name, framework, style_fingerprint fields only)
+- `.buildflow/codebase/PATTERNS.md` (if exists)
+- Do NOT load: full codebase, specs, research, retros, old phases
+
 ## Step 1: Load Plan
 Read `.buildflow/phases/[N]/PLAN.md`.
-Load `.buildflow/memory/light.md` for style preferences.
-If existing project: load `.buildflow/codebase/PATTERNS.md`.
+Confirm: "Phase [N] — [N] waves, [N] tasks, [N] ACs covered. Starting Wave 1."
 
 ## Step 2: Style Fingerprint
-Before writing any code, confirm:
+Before writing any code:
 - Naming conventions (camelCase, PascalCase, snake_case)
-- Import organization
+- Import organization pattern
 - Error handling style
 - Test file location and naming
+- Comment style
+
+---
+
+## Step 3: Wave Execution Loop
 
-## Step 3: Execute Wave
+Repeat this block for each wave:
 
-Repeat this block for each wave in the plan:
+### 3a — Prepare Builder Context Packets
+For each task in this wave, prepare a minimal context packet:
+```
+Task spec (from PLAN.md)
+AC refs: [which ACs this task satisfies]
+Relevant files: [max 5 files this task touches — not full codebase]
+Style rules: [3-5 key conventions from PATTERNS.md]
+```
+Builders receive ONLY this packet — not full project state.
+This is what keeps token usage low and context clean.
 
-### 3a — Build
-Spawn Builder agents in parallel for all tasks in this wave.
+### 3b — Build (parallel)
+Spawn Builder agents in parallel, one per task.
 Each Builder:
-- Gets the task spec and relevant context files
-- Writes code matching the detected style
-- Adds LEARN: comments for non-obvious patterns
-- Reports back: files created/modified, decisions made
+- Receives its context packet only
+- Writes code that satisfies the referenced ACs
+- Adds LEARN: comment for non-obvious patterns
+- Reports back: files created/modified, AC coverage confirmed
 
-### 3b — Review
+### 3c — Review
 Reviewer checks each output:
-- Does it meet the task spec?
-- Does it match codebase style?
+- Does it satisfy the referenced ACs?
+- Does it match PATTERNS.md style?
 - Any security concerns?
-- Are tests written for new logic?
+- Tests written for new logic?
 
-### 3c — Test (automatic, runs after every wave)
-Detect and run the test suite:
+### 3d — Test + Fix Loop
+Run the full test suite:
 ```bash
-npm test        # Node / JS / TS projects
+npm test        # Node / TS / JS
 pytest          # Python
 go test ./...   # Go
 cargo test      # Rust
-# etc. based on detected framework
 ```
 
-Also check:
-- If frontend code changed: start dev server and verify UI renders, flows work, no console errors
-- No import errors, missing modules, or broken references
-- All previously passing tests still pass (no regressions)
-
-### 3d — Fix loop (runs only if tests fail)
-If any test fails:
-1. Identify root cause (trace error → file → line → why)
-2. Apply minimal fix — change only what broke, do not refactor surrounding code
-3. Re-run the full test suite
-4. Repeat until all tests pass
+If frontend code changed: verify dev server renders without errors, core UI flow works.
 
-**Do not move to the next wave until this wave is fully green.**
+**If tests fail:**
+1. Identify root cause (error → file → line → why)
+2. Apply minimal fix (change only what broke)
+3. Re-run full test suite
+4. Repeat until green
 
-Maximum fix attempts per wave: 5.
-If still failing after 5 attempts: stop, report the unresolved failure, and ask the user how to proceed.
+Max 5 fix attempts per wave.
+If still failing after 5: stop, report unresolved failures, ask user how to proceed.
 
-Fix attempt log format:
+Fix log:
 ```
-Wave [N] — Fix attempt [X]/5
-Error: [error message]
-Root cause: [explanation]
-Fix applied: [what changed]
-Result: [pass / still failing]
+Wave [N] Fix [X]/5: [error] → [root cause] → [fix applied] → [result]
 ```
 
-## Step 4: Wave Complete
-Only after a wave is fully tested and passing:
-- Log the wave as complete in `.buildflow/phases/[N]/PLAN.md`
-- Continue to the next wave (back to Step 3)
+### 3e — Wave Complete
+Only after all tests pass:
+- Mark wave as complete in `phases/[N]/PLAN.md`
+- Continue to next wave
+
+---
 
-## Step 5: Integration Check
+## Step 4: Integration Check
 After all waves pass:
-- Run the full test suite one final time
-- Verify all pieces connect correctly end-to-end
-- Check for any import/dependency issues across wave boundaries
+- Run full test suite one final time
+- Verify pieces connect correctly across wave boundaries
+- Check for import errors or missing dependencies
 
-## Step 6: Update Memory
+## Step 5: Update Memory (minimal — prune stale fields)
 ```yaml
 last_build_date: [today]
-phase: [N]
-tasks_completed: [list]
-files_changed: [list]
-waves_completed: [N]
-test_status: all passing
+current_phase: [N]
+plan_status: built
+test_status: passing
 ```
+Remove from light.md: any per-wave task details from previous builds (keep it lean).
 
-## Token Budget: ~50K per wave (build + test + fix loop)
+## Token Budget: ~50K per wave (build + context packets + test-fix loop)

package/templates/commands/check.md

@@ -1,62 +1,97 @@
 ---
 name: buildflow-check
-description: Verify quality with parallel Reviewer agents
+description: Verify quality and spec compliance with parallel Reviewer agents
 allowed-tools: Read, Bash, Grep, Glob
 agent: reviewer
 ---
 
 # /buildflow-check
 
-Quality verification. Parallel Reviewers check code against acceptance criteria.
+Quality and spec-compliance verification. Four parallel Reviewers check code correctness, quality, security, and — most importantly — whether every acceptance criterion is actually satisfied.
 
 ## Usage
-- `/buildflow-check` — check current phase
+- `/buildflow-check` — full check: spec + code + security
 - `/buildflow-check <file>` — check a specific file
-- `/buildflow-check tests` — verify test coverage
-- `/buildflow-check acceptance` — verify acceptance criteria only
+- `/buildflow-check acceptance` — spec compliance only
+- `/buildflow-check tests` — test coverage only
+
+## Context Packet (load only these)
+- `.buildflow/specs/acceptance.md` — the source of truth for what must be true
+- `.buildflow/phases/[N]/PLAN.md` — what was supposed to be built
+- Changed files only (git diff since last commit) — NOT the full codebase
+- `.buildflow/codebase/PATTERNS.md` (if exists)
+
+Do NOT load: PRD, TDD, old phases, research files, retros.
 
 ## Step 1: Load Acceptance Criteria
-Read `.buildflow/phases/[N]/PLAN.md` for definition of done.
+Read every AC from `.buildflow/specs/acceptance.md`.
+This is the primary verification target — all other checks are secondary.
+
+## Step 2: Parallel Review (4 reviewers)
+
+**Reviewer A — Spec Compliance (most important):**
+For each acceptance criterion:
+- AC-001: Given [context], when [action], then [outcome] — does the code make this true?
+- AC-002: ... etc.
 
-## Step 2: Parallel Review (3 reviewers)
+Score each:
+```
+AC-001 ✓  PASS  — [brief evidence]
+AC-002 ✓  PASS  — [brief evidence]
+AC-003 ✗  FAIL  — [what's missing or wrong]
+AC-NF-001 ⚠ PARTIAL — [what works, what doesn't]
+```
 
-**Reviewer A — Correctness:**
+**Reviewer B — Correctness:**
 - Does the code do what was specified?
 - Are edge cases handled?
 - Are there logical errors?
 
-**Reviewer B — Quality:**
+**Reviewer C — Code Quality:**
 - Is the code readable?
 - Are there unnecessary duplications?
 - Does it match `.buildflow/codebase/PATTERNS.md`?
 - Are functions appropriately sized?
 
-**Reviewer C — Security:**
+**Reviewer D — Security:**
 - No hardcoded secrets?
 - No obvious injection risks?
 - No sensitive data in logs?
-- Dependencies up to date?
+- Relevant ACs for auth/security satisfied?
 
 ## Step 3: Test Check
-- Do existing tests pass?
+- Do all tests pass?
 - Are new tests written for new code?
-- Is critical logic tested?
+- Is each AC covered by at least one test?
 
 ## Step 4: Synthesize Findings
 
-Report format:
 ```
-✓ PASS  — criterion
-⚠ WARN  — issue (non-blocking)
-✗ FAIL  — issue (must fix before /buildflow-ship)
+Spec Compliance
+───────────────
+AC-001 ✓  login with valid credentials redirects to dashboard
+AC-002 ✓  login with wrong password shows error message
+AC-003 ✗  FAIL — password reset email not implemented
+AC-NF-001 ⚠ login endpoint has no rate limiting
+
+Code Quality
+────────────
+✓ PASS  naming conventions match PATTERNS.md
+⚠ WARN  AuthService is 340 lines — consider splitting
+✗ FAIL  SQL query in getUserById is not parameterized (injection risk)
 ```
 
-## Step 5: Confidence Check
-Ask: "How confident are you in this code? (1-5)"
+## Step 5: Ship Readiness
+
+| Condition | Status |
+|-----------|--------|
+| All ACs passing | ✓ / ✗ |
+| No FAIL-level code issues | ✓ / ✗ |
+| Tests passing | ✓ / ✗ |
+| Security gate clear | ✓ / ✗ |
 
-## Step 6: Next Steps
-- All pass: "Ready for /buildflow-ship"
-- Warnings: "Warnings noted. Run /buildflow-ship or fix first."
-- Failures: "Fix these issues, then re-run /buildflow-check"
+- **All green:** "Ready for `/buildflow-ship`"
+- **AC failures:** "Spec not complete. Fix AC failures before shipping — they represent unfinished features, not code style."
+- **Code failures only:** "Spec satisfied. Fix code issues or proceed with caution."
 
-## Token Budget: ~20K
+## Token Budget: ~22K

package/templates/commands/hotfix.md

@@ -0,0 +1,94 @@
+---
+name: buildflow-hotfix
+description: Fast-path fix for production incidents and small patches — no planning, no waves
+allowed-tools: Read, Write, Bash, Grep, Glob
+agent: surgeon
+---
+
+# /buildflow-hotfix
+
+Emergency and small-patch path. Skips all planning, spec, and wave orchestration. Goes directly: understand → restore point → fix → test → ship.
+
+Use this for:
+- Production incidents
+- One-liner bug fixes
+- Small patches that don't justify a full plan
+- Dependency version bumps
+- Config changes
+
+Do NOT use for: new features, refactors, or anything that touches more than ~5 files. Use `/buildflow-plan` + `/buildflow-build` for those.
+
+## Usage
+- `/buildflow-hotfix "fix login crash on empty password"`
+- `/buildflow-hotfix "bump lodash to 4.17.21"`
+- `/buildflow-hotfix src/api/auth.ts "rate limiting not applying to /refresh"`
+
+## Context Packet (minimal — load only what's needed)
+- `.buildflow/memory/light.md` (app_name, framework fields only)
+- Target file(s) if specified
+- Do NOT load: specs, phases, codebase MAP, PATTERNS — keep it fast
+
+## Step 1: Understand the Fix
+Parse the description. Identify:
+- What is broken?
+- What file(s) are likely involved?
+- What is the expected behavior after the fix?
+
+If the description is ambiguous, ask ONE clarifying question only.
+
+## Step 2: Scope Check
+Count files that need to change.
+- 1–5 files: proceed
+- 6+ files: warn — "This looks larger than a hotfix. Consider /buildflow-plan instead."
+  - Ask: "Proceed as hotfix anyway? (yes/no)"
+
+## Step 3: Create Restore Point
+```bash
+git stash push -m "hotfix restore point: [description]"
+# or if clean working tree:
+git tag "pre-hotfix-[timestamp]"
+```
+
+## Step 4: Apply Fix
+Make the minimal change:
+- Fix only the root cause
+- Do not refactor, rename, or clean up surrounding code
+- Match existing code style
+
+## Step 5: Test
+Run the test suite:
+```bash
+npm test        # or pytest / go test etc.
+```
+
+If tests fail: fix and re-test. Max 3 attempts before stopping and asking the user.
+
+If no tests exist for the changed area: flag it after shipping.
+
+## Step 6: Ship
+```bash
+git add [changed files only]
+git commit -m "hotfix: [description]"
+```
+
+Do not create a phase, do not update state.md phase number.
+Update `light.md`:
+```yaml
+last_hotfix: [today]
+last_hotfix_desc: [description]
+```
+
+## Step 7: Report
+```
+Hotfix complete
+───────────────
+Fix: [what changed]
+Files: [list]
+Tests: passing
+Commit: [hash]
+Time: fast-path (no planning)
+```
+
+If no test coverage existed: "⚠ No test covers this area. Consider adding one."
+
+## Token Budget: ~10K

package/templates/commands/plan.md

@@ -1,60 +1,102 @@
 ---
 name: buildflow-plan
-description: Create a dependency-aware execution plan with the Architect agent
+description: Create a spec-traced, dependency-aware execution plan with the Architect agent
 allowed-tools: Read, Write
 agent: architect
 ---
 
 # /buildflow-plan
 
-Create a detailed, phased execution plan. The Architect agent maps dependencies before sequencing work.
+Create a detailed, phased execution plan. Every task traces back to an acceptance criterion. The Architect reads specs, maps dependencies, and groups work into parallel waves.
+
+Run after `/buildflow-spec`. If specs don't exist, the Architect will ask you to create them first.
 
 ## Usage
 - `/buildflow-plan` — plan the next phase
 - `/buildflow-plan phase-2` — plan a specific phase
 - `/buildflow-plan <feature>` — plan a specific feature
 
-## Step 1: Load Context
-Read `.buildflow/core/vision.md`, `.buildflow/memory/light.md`.
-If existing project: read `.buildflow/codebase/MAP.md` and `DEPENDENCIES.md`.
+## Context Packet (load only these)
+- `.buildflow/specs/PRD.md`
+- `.buildflow/specs/TDD.md`
+- `.buildflow/specs/acceptance.md`
+- `.buildflow/memory/light.md` (phase, framework, spec_status fields only)
+- `.buildflow/codebase/MAP.md` (if exists — existing projects only)
+- `.buildflow/codebase/DEPENDENCIES.md` (if exists — existing projects only)
+
+Do NOT load: full codebase, old phase plans, research files, retros.
+
+## Step 1: Validate Specs
+Check `.buildflow/specs/acceptance.md` exists and `spec_status: locked` in light.md.
+If missing: "Run `/buildflow-spec` first to define acceptance criteria before planning."
 
 ## Step 2: Scope Confirmation
-Ask: "What are we building in this phase? What's the definition of done?"
-Confirm scope before planning.
+Read all acceptance criteria (AC-001, AC-002, ...).
+Confirm: "I'll plan tasks to satisfy [N] acceptance criteria. Correct?"
 
 ## Step 3: Dependency Mapping
-List all components/features needed. For each:
+For each AC, identify all components/tasks needed. For each task:
 - What does it depend on?
 - What depends on it?
-- Can it be built in parallel?
+- Can it be built in parallel with other tasks?
 
 ## Step 4: Task Breakdown
 For each task:
 ```
 Task: [name]
+AC refs: [AC-001, AC-003]   ← which acceptance criteria this satisfies
 Description: [what it does]
-Depends on: [prerequisite tasks]
+Depends on: [prerequisite tasks or "none"]
 Parallelizable: yes/no
-Estimated complexity: low/medium/high
+Complexity: low / medium / high
 Files affected: [list]
 ```
 
+Every AC must be covered by at least one task. Flag uncovered ACs before proceeding.
+
 ## Step 5: Wave Planning
 Group tasks into parallel waves:
 ```
-Wave 1 (parallel): [tasks with no dependencies]
-Wave 2 (parallel): [tasks depending only on Wave 1]
-Wave 3: [tasks depending on Wave 2]
+Wave 1 (parallel — no dependencies):
+  • Task A  [AC-001]
+  • Task B  [AC-002]
+
+Wave 2 (parallel — depends on Wave 1):
+  • Task C  [AC-001, AC-003]
+  • Task D  [AC-004]
+
+Wave 3 (depends on Wave 2):
+  • Task E  [AC-005]
 ```
 
-## Step 6: Risk Check
-Identify:
-- Tasks with high complexity
-- Tasks touching security-sensitive code
-- Tasks requiring external APIs or services
+## Step 6: AC Coverage Check
+Verify every acceptance criterion from `acceptance.md` is referenced in at least one task.
+Report:
+```
+AC Coverage
+───────────
+AC-001 ✓  covered by Task A, Task C
+AC-002 ✓  covered by Task B
+AC-003 ✗  NOT COVERED — add a task or flag as out of scope
+```
+
+Do not write the plan if any AC is uncovered without explicit user confirmation to skip it.
 
-## Step 7: Save Plan
-Write to `.buildflow/phases/[N]/PLAN.md`
-Update state.md with current phase number.
+## Step 7: Risk Check
+Flag tasks that are:
+- High complexity
+- Touching security-sensitive code
+- Requiring external APIs or services
+- Not covered by existing tests
+
+## Step 8: Save Plan
+Write to `.buildflow/phases/[N]/PLAN.md`.
+Update `state.md` with current phase number.
+Update `light.md`:
+```yaml
+current_phase: [N]
+ac_count: [N]
+plan_status: ready
+```
 
 ## Token Budget: ~20K