buildflow-dev 1.0.7 → 4.0.2

package/templates/commands/plan.md

@@ -1,60 +1,228 @@
 ---
 name: buildflow-plan
-description: Create a dependency-aware execution plan with the Architect agent
+description: Spec-traced, dependency-reasoned, risk-sequenced execution plan with engineering review
 allowed-tools: Read, Write
 agent: architect
 ---
 
 # /buildflow-plan
 
-Create a detailed, phased execution plan. The Architect agent maps dependencies before sequencing work.
+Creates a precise, dependency-reasoned execution plan. Every task traces to an Acceptance Criterion. Dependencies are explained, not just listed. Tasks are risk-sequenced and effort-estimated. An Engineering Review catches design problems before a single line of code is written.
+
+Run after `/buildflow-spec`. Refuses to plan without locked specs.
 
 ## Usage
 - `/buildflow-plan` — plan the next phase
-- `/buildflow-plan phase-2` — plan a specific phase
-- `/buildflow-plan <feature>` — plan a specific feature
+- `/buildflow-plan phase-2` — plan a specific named phase
+- `/buildflow-plan --scaffold-first` — Wave 0 creates all file stubs before implementation begins
+- `/buildflow-plan --risk-first` — orders risky/uncertain tasks to the front of each wave (fail fast)
+
+## Context Packet
+- `.buildflow/specs/PRD.md`
+- `.buildflow/specs/TDD.md`
+- `.buildflow/specs/acceptance.md`
+- `.buildflow/codebase/MAP.md` (if exists)
+- `.buildflow/codebase/GRAPH.md` (if exists — for dependency chain reasoning)
+- `.buildflow/memory/light.md` (phase, framework, spec_status only)
+
+Do NOT load: full codebase, old phase plans, research files, retros.
+
+---
+
+## Step 1: Validate Specs
+Check `spec_status: locked` in `light.md` and that `acceptance.md` exists.
+If not: "Run `/buildflow-spec` first. No spec, no plan."
+
+Read all ACs. Count: [N] features, [N] user stories, [N] ACs total.
+Confirm: "Planning to satisfy [N] ACs across [N] features."
+
+---
+
+## Step 2: Component & Task Derivation
+For each feature in PRD, derive the implementation tasks needed to satisfy its ACs:
 
-## Step 1: Load Context
-Read `.buildflow/core/vision.md`, `.buildflow/memory/light.md`.
-If existing project: read `.buildflow/codebase/MAP.md` and `DEPENDENCIES.md`.
+For each task ask:
+1. What code needs to exist that doesn't exist yet?
+2. What existing code needs to change?
+3. What tests must be written to verify the linked ACs?
+
+Map each task to its AC refs:
+```
+Task: Create JWT auth middleware
+AC refs: AC-001, AC-002, AC-003
+Files: src/middleware/auth.ts (new), src/routes/index.ts (modify)
+Type: NEW / MODIFY / TEST
+```
 
-## Step 2: Scope Confirmation
-Ask: "What are we building in this phase? What's the definition of done?"
-Confirm scope before planning.
+---
 
-## Step 3: Dependency Mapping
-List all components/features needed. For each:
-- What does it depend on?
-- What depends on it?
-- Can it be built in parallel?
+## Step 3: Dependency Reasoning
+For each task, identify dependencies and explain WHY they exist:
 
-## Step 4: Task Breakdown
-For each task:
 ```
-Task: [name]
-Description: [what it does]
-Depends on: [prerequisite tasks]
-Parallelizable: yes/no
-Estimated complexity: low/medium/high
-Files affected: [list]
+Task: Create login API route
+Depends on: "Create auth middleware" — HARD dependency
+Reason: Route cannot be registered until middleware exists; calling undefined throws at startup
+
+Task: Write login integration tests
+Depends on: "Create login API route" — HARD dependency
+Reason: Tests call the live route; no route = test suite errors on import
+
+Task: Create UI login form
+Depends on: "Create login API route" — SOFT dependency
+Reason: Form can be scaffolded independently; only needs real API for E2E tests
+Can proceed in parallel if mocked: YES
 ```
 
+Dependency types:
+- **HARD** — code fails to compile/run without the prerequisite
+- **SOFT** — can proceed with a mock/stub; full integration requires prerequisite
+- **EXTERNAL** — depends on env var, database, third-party API (flag for setup checklist)
+
+Detect circular dependencies: if A → B → A exists, flag immediately and resolve before proceeding.
+
+External dependency checklist (generated if any EXTERNAL deps found):
+```
+Before building, verify these exist:
+- [ ] DATABASE_URL env var set
+- [ ] [service] API key configured
+- [ ] [schema] migration run
+```
+
+---
+
+## Step 4: Effort Estimation
+Estimate each task:
+| Size | Meaning |
+|------|---------|
+| XS | < 30 min — config, type, single function |
+| S | 30–90 min — single component or endpoint |
+| M | 2–4 hrs — feature with tests |
+| L | 4–8 hrs — complex feature, multiple components |
+| XL | > 1 day — requires research or architectural decision |
+
+Flag XL tasks: "This task is XL — consider splitting or running `/buildflow-think` first."
+
+---
+
 ## Step 5: Wave Planning
-Group tasks into parallel waves:
+
+Group tasks into parallel waves based on HARD dependencies only (SOFT deps don't block):
+
 ```
-Wave 1 (parallel): [tasks with no dependencies]
-Wave 2 (parallel): [tasks depending only on Wave 1]
-Wave 3: [tasks depending on Wave 2]
+Wave 0 — Scaffolding (if --scaffold-first)
+  Create empty file stubs for all new files
+  Purpose: Builders know what exists; no "file not found" errors mid-wave
+
+Wave 1 — Foundation (parallel, no hard dependencies)
+  • Task A  [AC-001]  S   NEW
+  • Task B  [AC-NF-001]  M   NEW
+
+Wave 2 — Core (parallel, hard-depends on Wave 1)
+  • Task C  [AC-001, AC-002]  M   MODIFY
+  • Task D  [AC-003]  S   NEW
+
+Wave 3 — Integration (depends on Wave 2)
+  • Task E  [AC-001–AC-003]  M   TEST
+  • Task F  [AC-004]  L   NEW
+
+Wave 4 — UI / E2E (depends on Wave 3)
+  • Task G  [AC-005, AC-006]  M   NEW
+  • Task H  [all ACs]  L   TEST
+```
+
+If `--risk-first`: within each wave, sort tasks by uncertainty/novelty (most uncertain first). This surfaces problems early before other wave tasks build on broken assumptions.
+
+---
+
+## Step 6: AC Coverage Verification
+Every AC must be covered by at least one task. Report:
+
+```
+AC Coverage
+───────────
+AC-001 ✓  Task C, Task E
+AC-002 ✓  Task C
+AC-003 ✓  Task D, Task E
+AC-004 ✓  Task F
+AC-005 ✓  Task G
+AC-006 ✓  Task G
+AC-NF-001 ✓  Task B, Task H
+Uncovered: NONE
+```
+
+If any AC is uncovered: stop. "AC-[X] has no task. Add a task or explicitly mark it out of scope."
+
+---
+
+## Step 7: Engineering Review
+Before writing the plan file, review the plan as an Engineering Lead:
+
+**Over-engineering check:**
+- Is any task adding abstraction layers not required by the ACs?
+- Are there tasks that implement features "for future use" not in specs?
+- Flag and remove.
+
+**Under-engineering check:**
+- Are there ACs that will be technically impossible to satisfy with the planned approach?
+- Are there missing error handling tasks?
+- Are tests planned for every non-trivial AC?
+
+**Architecture smell check:**
+- Does the plan introduce new patterns that conflict with `PATTERNS.md`?
+- Does any task modify a HOTSPOT file? If yes, flag with: "⚠ This task touches [file] (risk: [N]) — verify test coverage before proceeding."
+- Are there tasks that cross module boundaries inappropriately?
+
+**Engineering Review Report:**
+```
+Engineering Review
+──────────────────
+Over-engineering:  [list or NONE]
+Under-engineering: [list or NONE]
+Architecture:      [conflicts or NONE]
+Hotspot warnings:  [files or NONE]
+Verdict: APPROVED / NEEDS REVISION
 ```
 
-## Step 6: Risk Check
-Identify:
-- Tasks with high complexity
-- Tasks touching security-sensitive code
-- Tasks requiring external APIs or services
+If NEEDS REVISION: apply fixes, re-run review, then proceed.
+
+---
+
+## Step 8: Write Plan
+Write `.buildflow/phases/[N]/PLAN.md`:
+
+```markdown
+# Phase [N] Plan
+**Goal:** [one sentence — what the user can DO after this phase that they can't do now]
+**ACs:** [N]  **Tasks:** [N]  **Waves:** [N]  **Est. total:** [sum of estimates]
+**Engineering Review:** APPROVED
 
-## Step 7: Save Plan
-Write to `.buildflow/phases/[N]/PLAN.md`
-Update state.md with current phase number.
+## External Dependencies Checklist
+- [ ] [item] — [how to verify]
+
+## Waves
+
+### Wave 1 — [theme]
+| Task | ACs | Est | Type | Files |
+|------|-----|-----|------|-------|
+| [name] | AC-001 | S | NEW | src/... |
+
+### Wave 2 — [theme]
+...
+
+## AC → Task Traceability
+| AC | Task(s) |
+|----|---------|
+| AC-001 | Task C, Task E |
+```
+
+Update `light.md`:
+```yaml
+current_phase: [N]
+plan_status: ready
+wave_count: [N]
+task_count: [N]
+est_total: [size]
+```
 
-## Token Budget: ~20K
+## Token Budget: ~22K

package/templates/commands/ship.md

@@ -1,56 +1,91 @@
 ---
 name: buildflow-ship
-description: Finalize phase with mandatory pre-ship security gate
+description: Finalize phase with spec gate, security gate, and context pruning
 allowed-tools: Read, Write, Bash
 agents: strategist, security-auditor
 ---
 
 # /buildflow-ship
 
-Finalize current phase. Security gate runs automatically before shipping.
+Finalize current phase. Three gates run before shipping: spec compliance, security scan, and test pass. After shipping, session context is pruned so the next phase starts clean.
 
-## MANDATORY Step 0: Pre-Ship Security Gate
+## Context Packet (load only these)
+- `.buildflow/specs/acceptance.md`
+- `.buildflow/core/state.md`
+- `.buildflow/memory/light.md`
+- Git diff of changed files (not full codebase)
+
+## MANDATORY Gate 0: Spec Compliance Check
+
+Read `.buildflow/specs/acceptance.md`. Verify every AC is satisfied.
+
+```
+Spec Gate
+─────────
+AC-001 ✓
+AC-002 ✓
+AC-003 ✗  FAIL — password reset not implemented
+```
+
+**If any AC is ✗ FAIL → BLOCK:**
+```
+🔴 SHIP BLOCKED — Spec Not Complete
+
+These acceptance criteria are not satisfied:
+[AC-003] password reset not implemented
+
+Fix them with /buildflow-build or /buildflow-modify, then re-run /buildflow-ship.
+Override (skips spec gate only): /buildflow-ship --skip-spec
+```
+
+**If all ACs pass → proceed to Gate 1.**
+
+---
+
+## MANDATORY Gate 1: Pre-Ship Security Scan
 
 Spawn Security Auditor in `--pre-ship` mode:
-- Scan only changed files (git diff since last commit)
+- Scan changed files only (git diff since last commit)
 - Check for secrets
 - Check critical injection patterns
 - Check auth bypass risks
 - Check critical dependency CVEs
-- Token cost: ~10K
-
-### Gate Outcomes
 
 **Critical found → BLOCK:**
 ```
 🔴 SHIP BLOCKED — Critical Security Issues
 
-Fix these before shipping:
-[C1] [Issue] at [file:line]
+[C1] [issue] at [file:line]
      Fix: [specific action]
 
 Run /buildflow-modify for surgical fixes.
 Override (not recommended): /buildflow-ship --force
 ```
 
-**High found → WARN:**
+**High found → WARN (non-blocking):**
 ```
-⚠️  Security Warnings (non-blocking)
-[H1] [Issue]
-     Risk: [...]
-     Fix later: /buildflow-audit for details
+⚠️  Security Warnings
+[H1] [issue] — fix in next phase
 ```
 
-**Clean → proceed:**
-```
-✅ Security gate passed. No critical issues.
-```
+**Clean → proceed.**
+
+---
+
+## MANDATORY Gate 2: Tests Pass
+
+Run the test suite one final time.
+If any test fails: BLOCK. "Fix test failures before shipping."
+
+---
 
-## Step 1: Pre-Ship Checklist
-- [ ] All acceptance criteria met
-- [ ] /buildflow-check passed
-- [ ] Tests pass
-- [ ] Security gate passed (above)
+## Step 1: Pre-Ship Checklist (summary)
+- [ ] All ACs satisfied (Gate 0)
+- [ ] Security gate passed (Gate 1)
+- [ ] All tests passing (Gate 2)
+- [ ] `/buildflow-check` run and reviewed
+
+---
 
 ## Step 2: Retrospective
 Ask:
@@ -61,37 +96,64 @@ Ask:
 
 Save to `.buildflow/phases/[N]/retro.md`
 
-## Step 3: Update Docs
-- README if needed
-- vision.md if pivots occurred
-- state.md: Phase X → Shipped
+---
+
+## Step 3: Context Pruning (token efficiency)
+
+After a successful ship, prune `light.md` to stay lean for the next phase:
+
+**Archive** these from `light.md` to `phases/[N]/retro.md`:
+- Phase-specific task lists
+- Wave completion details
+- Build timestamps
+- Hotfix history older than current phase
 
-## Step 4: Update Codebase Map (existing projects)
-If patterns changed, new hotspots added, or dependencies updated:
-- Update PATTERNS.md
-- Update HOTSPOTS.md
-- Update DEPENDENCIES.md
+**Keep** in `light.md`:
+- app_name, framework, language
+- current_phase (update to N+1 or "complete")
+- spec_status (reset to "none" for next phase)
+- style_fingerprint
+- last 2 architectural decisions
+- onboard_status
+
+**Target:** `light.md` must be under 3K tokens after pruning.
+
+Update `light.md`:
+```yaml
+current_phase: [N+1 or complete]
+last_ship_date: [today]
+spec_status: none
+plan_status: none
+context_pruned: [today]
+```
+
+---
+
+## Step 4: Update Docs
+- README if public-facing features shipped
+- `vision.md` if pivots occurred during the phase
+
+---
 
 ## Step 5: Tag Release
 ```bash
 git add .
-git commit -m "buildflow: phase X shipped"
-git tag "buildflow-phase-X-complete"
+git commit -m "ship: phase [N] complete"
+git tag "phase-[N]-complete"
 ```
 
-## Step 6: Update Memory
-```yaml
-last_ship_date: [today]
-phase: X
-security_gate: passed|passed-with-warnings|overridden
-```
+---
+
+## Step 6: Next Phase
+Suggest next phase based on remaining roadmap items.
+"Phase [N] shipped. Run `/buildflow-spec` to define the next phase."
+
+---
 
-## Step 7: Next Phase
-Suggest next phase based on roadmap.
+## Override Flags
+- `--skip-spec` — skips spec gate only. Logs to `security/DEBT.md`: "Spec gate skipped — [reason]"
+- `--force` — skips security gate. Requires typed confirmation. Logged with timestamp.
 
-## --force Override
-If used, adds to `.buildflow/security/DEBT.md` and requires:
-- Typed confirmation: "I understand the risk"
-- Logged with timestamp
+Neither flag skips the test gate.
 
-## Token Budget: ~22K (including pre-ship audit)
+## Token Budget: ~22K (including gates)