buildflow-dev 1.0.7 → 4.0.2

package/templates/commands/build.md

@@ -1,105 +1,276 @@
 ---
 name: buildflow-build
-description: Execute the plan with parallel Builder agents, auto-test and auto-fix each wave
+description: Spec-traced wave execution with pattern-matched Builders, auto-test, auto-fix, and PR-ready commits
 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. Each Builder receives a precise context packet — task spec, AC refs, before/after contract, and the closest existing example to follow. Every wave auto-tests, auto-fixes until green, and produces a PR-ready commit. The next wave never starts until the current wave is fully passing.
 
 ## Usage
-- `/buildflow-build` — execute current phase plan (all waves, auto-test each)
-- `/buildflow-build wave-2` — execute and test a specific wave
-- `/buildflow-build <task>` — build and test a single task
+- `/buildflow-build` — execute all waves
+- `/buildflow-build wave-2` — execute a specific wave
+- `/buildflow-build <task>` — build a single task
 
-## Step 1: Load Plan
+## Context Packet for this command (load only these)
+- `.buildflow/phases/[N]/PLAN.md`
+- `.buildflow/codebase/PATTERNS.md` (if exists)
+- `.buildflow/memory/light.md` (app_name, framework, style_fingerprint only)
+
+Do NOT load: full specs, full codebase, research, retros, old phases.
+
+---
+
+## Step 1: Load & Confirm Plan
 Read `.buildflow/phases/[N]/PLAN.md`.
-Load `.buildflow/memory/light.md` for style preferences.
-If existing project: load `.buildflow/codebase/PATTERNS.md`.
+Report: "Phase [N] — [N] waves, [N] tasks, [N] ACs. Est: [total]. Starting Wave [N]."
+
+Check external dependency checklist if present. If unchecked items: "Verify these before building: [list]"
+
+---
+
+## Step 2: Detect Test Framework (runs once before any wave)
+
+Before writing a single test line, identify what testing infrastructure exists.
+
+### Detection checklist:
+
+**JavaScript / TypeScript:**
+```bash
+# Check package.json for test deps
+cat package.json | grep -E "jest|vitest|mocha|jasmine|@testing-library|supertest|cypress|playwright"
+# Check for config files
+ls jest.config.* vitest.config.* .mocharc.* 2>/dev/null
+# Check for existing test files
+find . -name "*.test.ts" -o -name "*.test.js" -o -name "*.spec.ts" -o -name "*.spec.js" | head -5
+find . -type d -name "__tests__" | head -3
+```
+
+**Python:**
+```bash
+cat requirements.txt pyproject.toml setup.cfg 2>/dev/null | grep -E "pytest|unittest|nose"
+find . -name "test_*.py" -o -name "*_test.py" | head -5
+```
+
+**Go:**
+```bash
+find . -name "*_test.go" | head -5
+```
+
+**Rust:**
+```bash
+grep -n "#\[test\]\|#\[cfg(test)\]" src/**/*.rs | head -5
+```
+
+### Framework Resolution:
+
+| Result | Action |
+|--------|--------|
+| Framework found + config exists + test files exist | Use it. Infer conventions from existing test files. |
+| Framework in package.json but no test files yet | Use it. Write tests following framework docs conventions. |
+| No framework found, greenfield project | Ask: "No test framework detected. Recommend installing [Jest/Vitest for TS, pytest for Python, built-in for Go/Rust]. Set it up now? (yes / skip / I'll do it later)" |
+| No framework, existing project with no tests | Warn: "⚠ No test framework found. Tests cannot be written until one is installed. Proceeding without tests — recommend adding [framework] before shipping." Log to `security/DEBT.md`: "No test framework — zero coverage." |
+
+### If framework found — capture test profile:
+```
+Test Framework Profile
+──────────────────────
+Framework:     Jest 29 / Vitest 1.x / pytest 7.x / go test / cargo test
+Config file:   jest.config.ts / vitest.config.ts / pytest.ini / N/A
+Test location: co-located (*.test.ts) / __tests__/ / tests/
+Naming:        describe/it / test() / def test_ / #[test]
+Mocking:       jest.mock / vi.mock / pytest fixtures / mockall
+Coverage tool: --coverage / --cov / go test -cover / cargo tarpaulin
+Existing tests: [N] files, [N] total cases
+```
+
+This profile is passed to every Builder as part of their context packet.
+
+---
+
+## Step 3: Establish Style Fingerprint
+If `PATTERNS.md` exists: extract the 5 most important conventions and hold them in scope.
+If not: read 2 existing source files and infer:
+- Naming convention
+- Import order
+- Error handling pattern
+- Async style
+- Test naming pattern (from test profile above)
+
+This fingerprint applies to every Builder in every wave.
+
+---
 
-## Step 2: Style Fingerprint
-Before writing any code, confirm:
-- Naming conventions (camelCase, PascalCase, snake_case)
-- Import organization
-- Error handling style
-- Test file location and naming
+## Step 3: Wave Execution Loop
 
-## Step 3: Execute Wave
+Repeat for each wave:
 
-Repeat this block for each wave in the plan:
+### 3a — Build Context Packets
+For each task in this wave, assemble a minimal context packet:
+
+```
+Task: [name]
+Goal: [one sentence — what this task makes true]
+AC refs: [AC-001, AC-003]
+Before: [what currently exists — "file doesn't exist" or "function X does Y"]
+After:  [what must be true when this task is done]
+
+Files to create/modify: [explicit list — max 5]
+Closest existing example: [path/to/similar/file.ts — "follow this structure"]
+Key pattern to follow: [specific convention from PATTERNS.md]
+Definition of done: [linked ACs that must pass]
+```
+
+The "closest existing example" is the most important field. Builders replicate proven patterns — they don't invent new ones unless the task explicitly requires it. Find the nearest analog in the codebase.
+
+### 3b — Parallel Build
+Spawn one Builder per task. Each Builder receives ONLY its context packet.
 
-### 3a — Build
-Spawn Builder agents in parallel for all tasks in this wave.
 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
-
-### 3b — Review
-Reviewer checks each output:
-- Does it meet the task spec?
-- Does it match codebase style?
+- Writes code that satisfies the Before → After contract
+- Follows the closest existing example's structure
+- Covers the referenced ACs
+- **Writes tests as part of the same task — not after, not later, not optional**
+- Adds `LEARN:` comment only for patterns not present elsewhere in the codebase
+
+#### Mandatory Test Writing Rules (enforced per Builder)
+
+**Prerequisite:** Test Framework Profile from Step 2 must exist. If no framework was found and user chose to skip, mark this task's test output as SKIPPED and log to `security/DEBT.md`.
+
+**For every new source file created:**
+- Create a corresponding test file using the detected framework and location convention:
+  - Jest/Vitest co-located: `auth.service.ts` → `auth.service.test.ts`
+  - `__tests__` folder: `src/auth/auth.service.ts` → `src/auth/__tests__/auth.service.test.ts`
+  - pytest: `src/auth/service.py` → `tests/auth/test_service.py`
+  - Go: `auth/service.go` → `auth/service_test.go` (same package)
+  - Rust: add `#[cfg(test)] mod tests { }` block inside same file
+- Test file must cover: each exported function/method, each AC referenced by this task
+- Minimum: 1 happy path + 1 error/edge case per exported function
+
+**For every modified source file:**
+- Locate the existing test file using the detected convention
+- Add new test cases for every function whose behavior changed
+- Update existing test cases if the function's contract or signature changed
+- Do NOT delete passing test cases unless the behavior they test was explicitly removed
+
+**Test structure — follow detected framework exactly:**
+
+Jest / Vitest:
+```typescript
+describe('AuthService', () => {
+  describe('login', () => {
+    it('returns token when credentials are valid', async () => { ... })
+    it('throws UnauthorizedError when password is wrong', async () => { ... })
+  })
+})
+```
+pytest:
+```python
+def test_login_returns_token_with_valid_credentials():  ...
+def test_login_raises_unauthorized_with_wrong_password(): ...
+```
+Go:
+```go
+func TestLogin_ReturnsToken_WithValidCredentials(t *testing.T) { ... }
+func TestLogin_ReturnsError_WithWrongPassword(t *testing.T) { ... }
+```
+
+Builder reports back:
+```
+Task: [name] — COMPLETE
+Files created:  [list]
+Files modified: [list]
+Test files written/updated: [list with case count]
+  auth.service.test.ts — 6 cases (4 new, 2 updated)
+ACs addressed: [AC-001 ✓, AC-003 ✓]
+Pattern followed: [example file used]
+```
+
+### 3c — Reviewer Check
+Reviewer reads each Builder's output:
+- Does the implementation satisfy the referenced ACs?
+- Does it match the style fingerprint and closest example?
+- Are tests present for non-trivial logic?
 - Any security concerns?
-- Are tests written for new logic?
+- Did the Builder follow the Before → After contract?
+
+Flag any deviation from existing patterns — Builders should blend in, not stand out.
 
-### 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)
+If frontend changed: verify dev server renders without errors, core flow works.
+Check: no regressions in previously passing tests.
 
-### 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
+**On test failure:**
+1. Read the exact error — file, line, message
+2. Trace root cause (not just symptom)
+3. Apply minimal fix
+4. Re-run tests
+5. Repeat until green
 
-**Do not move to the next wave until this wave is fully green.**
+Max 5 fix attempts. After 5: stop, report what's unresolved, ask how to proceed.
 
-Maximum fix attempts per wave: 5.
-If still failing after 5 attempts: stop, report the unresolved failure, and ask the user how to proceed.
+Fix log per attempt:
+```
+Fix [X]/5  Wave [N]
+Error:      [message at file:line]
+Root cause: [why it's failing]
+Fix:        [exactly what changed]
+Result:     PASS / still failing
+```
 
-Fix attempt log format:
+### 3e — Wave Commit
+When all tests pass, commit this wave atomically:
+```bash
+git add [changed files — explicit list, not -A]
+git commit -m "[type](scope): [what changed]
+
+[Body: why this change, which ACs it satisfies]
+[AC refs: AC-001, AC-003]
+[Wave: N of M]"
 ```
-Wave [N] — Fix attempt [X]/5
-Error: [error message]
-Root cause: [explanation]
-Fix applied: [what changed]
-Result: [pass / still failing]
+
+Commit types: `feat` / `fix` / `test` / `refactor` / `chore`
+
+Example:
 ```
+feat(auth): add JWT middleware and login route
 
-## 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)
+Implements token validation for all protected routes.
+Satisfies: AC-001 (valid login), AC-002 (invalid password rejection), AC-003 (expired token)
+Wave: 2 of 4
+```
+
+Mark wave complete in `phases/[N]/PLAN.md`. Proceed to next wave.
+
+---
 
-## Step 5: 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
+## Step 4: Final Integration Check
+After all waves:
+- Run full test suite one last time
+- Verify all AC-referenced behaviors work end-to-end
+- Check imports across wave boundaries (no dangling references)
 
-## Step 6: Update Memory
+---
+
+## Step 5: Update Memory (lean — prune old build fields)
 ```yaml
 last_build_date: [today]
-phase: [N]
-tasks_completed: [list]
-files_changed: [list]
+plan_status: built
+test_status: passing
 waves_completed: [N]
-test_status: all passing
 ```
+Remove from `light.md`: per-task details from previous builds.
+
+---
 
-## Token Budget: ~50K per wave (build + test + fix loop)
+## Token Budget: ~50K per wave (context packets keep individual Builder costs low)

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,119 @@
+---
+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 4b: Write Regression Test (always — even in hotfix mode)
+
+### First: check if a test framework exists
+```bash
+cat package.json | grep -E "jest|vitest|mocha" 2>/dev/null
+find . -name "*.test.ts" -o -name "*.test.js" -o -name "test_*.py" | head -3
+```
+
+- **Framework found:** write the regression test using it
+- **No framework found:** warn — "No test framework detected. Regression test skipped. This bug may recur." Log to `security/DEBT.md`: "Hotfix [description] shipped without regression test — no framework available."
+- Do not block the hotfix for a missing framework, but always log the gap.
+
+For the specific behavior being fixed:
+1. Write a test that reproduces the bug before applying the fix
+2. Run it — confirm it fails
+3. Apply the fix (Step 4)
+4. Run it again — confirm it passes
+
+Name it after the exact bug:
+```
+it('should not crash when user has no profile photo')
+it('should return 401 when session token is expired')
+```
+
+If a test file already exists for the changed file: add the case there.
+If not: create a minimal test file covering this function only. Do not skip — a hotfix without a regression test will regress again.
+
+## Step 5: Test
+Run the full 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.
+
+## 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