buildflow-dev 4.0.1 → 4.0.2

package/templates/commands/plan.md

@@ -1,102 +1,228 @@
 ---
 name: buildflow-plan
-description: Create a spec-traced, 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. Every task traces back to an acceptance criterion. The Architect reads specs, maps dependencies, and groups work into parallel waves.
+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`. If specs don't exist, the Architect will ask you to create them first.
+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 (load only these)
+## Context Packet
 - `.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)
+- `.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 `.buildflow/specs/acceptance.md` exists and `spec_status: locked` in light.md.
-If missing: "Run `/buildflow-spec` first to define acceptance criteria before planning."
+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:
+
+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
-Read all acceptance criteria (AC-001, AC-002, ...).
-Confirm: "I'll plan tasks to satisfy [N] acceptance criteria. Correct?"
+## Step 3: Dependency Reasoning
+For each task, identify dependencies and explain WHY they exist:
 
-## Step 3: Dependency Mapping
-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 with other tasks?
+```
+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)
 
-## Step 4: Task Breakdown
-For each task:
+Detect circular dependencies: if A → B → A exists, flag immediately and resolve before proceeding.
+
+External dependency checklist (generated if any EXTERNAL deps found):
 ```
-Task: [name]
-AC refs: [AC-001, AC-003]   ← which acceptance criteria this satisfies
-Description: [what it does]
-Depends on: [prerequisite tasks or "none"]
-Parallelizable: yes/no
-Complexity: low / medium / high
-Files affected: [list]
+Before building, verify these exist:
+- [ ] DATABASE_URL env var set
+- [ ] [service] API key configured
+- [ ] [schema] migration run
 ```
 
-Every AC must be covered by at least one task. Flag uncovered ACs before proceeding.
+---
+
+## 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 — no dependencies):
-  • Task A  [AC-001]
-  • Task B  [AC-002]
+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 (parallel — depends on Wave 1):
-  • Task C  [AC-001, AC-003]
-  • Task D  [AC-004]
+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 (depends on Wave 2):
-  • Task E  [AC-005]
+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
 ```
 
-## Step 6: AC Coverage Check
-Verify every acceptance criterion from `acceptance.md` is referenced in at least one task.
-Report:
+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 ✓  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
+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
 ```
 
-Do not write the plan if any AC is uncovered without explicit user confirmation to skip it.
+If NEEDS REVISION: apply fixes, re-run review, then proceed.
+
+---
+
+## Step 8: Write Plan
+Write `.buildflow/phases/[N]/PLAN.md`:
 
-## Step 7: Risk Check
-Flag tasks that are:
-- High complexity
-- Touching security-sensitive code
-- Requiring external APIs or services
-- Not covered by existing tests
+```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
+
+## 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 |
+```
 
-## 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
+wave_count: [N]
+task_count: [N]
+est_total: [size]
 ```
 
-## Token Budget: ~20K
+## Token Budget: ~22K

package/templates/commands/spec.md

@@ -1,147 +1,251 @@
 ---
 name: buildflow-spec
-description: Generate formal PRD, Technical Design, and Acceptance Criteria before planning
+description: Generate user-story-backed PRD, Technical Design, and Acceptance Criteria with self-critique pass
 allowed-tools: Read, Write, WebSearch
 agent: strategist
 ---
 
 # /buildflow-spec
 
-Spec-Driven Development layer. Produces three locked spec artifacts before any code is planned or written. The Architect, Builder, and Reviewer agents all reference these during execution.
+Spec-Driven Development layer. Produces formally structured, self-critiqued spec artifacts before any code is planned or written. Every plan task, every build output, and every ship gate references these docs.
 
-Run this after `/buildflow-start` and before `/buildflow-plan`.
+Run after `/buildflow-start`, before `/buildflow-plan`.
 
 ## Usage
-- `/buildflow-spec` — generate full spec from vision
+- `/buildflow-spec` — full spec from vision
 - `/buildflow-spec prd` — regenerate PRD only
-- `/buildflow-spec tdd` — regenerate Technical Design only
-- `/buildflow-spec acceptance` — regenerate acceptance criteria only
-- `/buildflow-spec --review` — re-read and review existing specs without regenerating
+- `/buildflow-spec tdd` — regenerate TDD only
+- `/buildflow-spec acceptance` — regenerate ACs only
+- `/buildflow-spec --fast` — minimal spec for small features (single screen / endpoint)
+- `/buildflow-spec --review` — critique existing specs without regenerating
 
-## Context Packet (load only these — nothing else)
+## Context Packet
 - `.buildflow/core/vision.md`
-- `.buildflow/memory/light.md` (summary fields only: app_name, framework, phase)
-- `.buildflow/specs/` (existing specs if regenerating)
+- `.buildflow/codebase/PATTERNS.md` (if exists — align spec with existing architecture)
+- `.buildflow/memory/light.md` (app_name, framework, phase only)
+- `.buildflow/specs/` (if regenerating)
 
-## Step 1: Validate Vision Exists
+---
+
+## Step 1: Validate Vision
 Read `.buildflow/core/vision.md`.
-If empty or missing: "Run /buildflow-start first to capture the project vision."
+If empty: "Run `/buildflow-start` first."
 
-## Step 2: Clarify Ambiguities
-Before writing specs, ask only questions that are unanswered in vision.md:
-- What does success look like for the user? (measurable outcome, not a feature)
-- What is explicitly OUT of scope for this phase?
-- Are there known constraints? (tech stack lock-in, deadline, budget, team size)
-- Any third-party integrations required?
+If `PATTERNS.md` exists: note the existing architectural style (component structure, naming, API patterns).
+The TDD must align with these — don't invent new patterns unless explicitly asked.
 
-Ask all questions at once. Do not ask one at a time.
-Maximum 5 questions. Skip any already answered in vision.md.
+---
+
+## Step 2: Clarify (one round, all questions at once)
+Ask only what vision.md left unanswered. Max 5 questions:
+- What does success look like for the **user** — as a measurable outcome, not a feature list?
+- What is explicitly **out of scope** this phase?
+- Any **hard constraints**: tech stack, deadline, team size, compliance?
+- Any **third-party integrations** required?
+- If `--fast`: "Describe the single feature in one sentence."
+
+---
 
 ## Step 3: Generate PRD
 Write `.buildflow/specs/PRD.md`:
 
 ```markdown
 # Product Requirements Document
-**App:** [name]  **Phase:** [N]  **Date:** [today]
+**App:** [name]  **Phase:** [N]  **Date:** [today]  **Status:** DRAFT
 
 ## Problem Statement
-[One paragraph: what problem exists, who has it, why current solutions fail]
+[One paragraph. Must answer: what exists today that's broken/missing, who suffers, why current solutions fail.]
 
-## Users
-| User Type | Goal | Key Pain Point |
-|-----------|------|----------------|
-| [type] | [goal] | [pain] |
+## Users & Goals
+| User Type | Job-to-be-Done | Current Pain |
+|-----------|----------------|--------------|
+| [type] | [goal — verb phrase] | [specific friction today] |
+
+## User Stories
+| ID | Story | Acceptance Signal |
+|----|-------|------------------|
+| US-01 | As a [user], I want [goal] so that [outcome] | [one-line measurable signal] |
+| US-02 | ... | ... |
 
 ## Features — In Scope
-| ID | Feature | Priority | Success Metric |
-|----|---------|----------|----------------|
-| F-01 | [name] | Must-have / Should-have / Nice-to-have | [measurable] |
+| ID | Feature | Linked Stories | Priority | Success Metric |
+|----|---------|---------------|----------|----------------|
+| F-01 | [name] | US-01, US-02 | Must / Should / Could | [number or binary] |
 
-## Out of Scope
-- [what we are explicitly NOT building this phase]
+## Explicitly Out of Scope
+- [item] — reason: [why excluded this phase]
 
 ## Constraints
-- [tech, timeline, team, budget constraints]
-
-## Success Criteria
-Phase is complete when:
-- [ ] [measurable outcome 1]
-- [ ] [measurable outcome 2]
+| Type | Constraint |
+|------|-----------|
+| Tech | [stack lock-in, version requirements] |
+| Timeline | [deadline if any] |
+| Compliance | [GDPR, HIPAA, accessibility level, etc.] |
+| Team | [size, skills] |
+
+## Phase Complete When
+- [ ] [measurable outcome — must map to a Success Metric above]
 ```
 
-## Step 4: Generate Technical Design Doc
+---
+
+## Step 4: Generate TDD
 Write `.buildflow/specs/TDD.md`:
 
+If `PATTERNS.md` exists: components and API shapes must follow existing conventions.
+
 ```markdown
 # Technical Design Document
-**App:** [name]  **Phase:** [N]  **Date:** [today]
+**App:** [name]  **Phase:** [N]  **Date:** [today]  **Status:** DRAFT
 
 ## Architecture Overview
-[Brief description of the system architecture]
+[2–3 sentences. What components exist, how they communicate, what changes this phase.]
 
-## Components
-| Component | Responsibility | Interface |
-|-----------|---------------|-----------|
-| [name] | [what it does] | [API / function / event] |
+## Component Map
+| Component | Responsibility | Linked Feature | Interface Type |
+|-----------|---------------|----------------|----------------|
+| [name] | [single responsibility] | F-01 | REST / gRPC / event / function |
 
-## Data Model
-[Key entities and their relationships — use simple table or diagram]
+## Data Model Changes
+| Entity | Fields Added/Changed | Reason |
+|--------|---------------------|--------|
+| [entity] | [field: type] | [F-01] |
 
 ## API Contracts
-| Endpoint / Function | Input | Output | Auth Required |
-|--------------------|-------|--------|---------------|
-| [name] | [type] | [type] | yes/no |
+| Endpoint / Function | Method | Request Shape | Response Shape | Status Codes | Auth |
+|--------------------|--------|---------------|----------------|-------------|------|
+| /api/[path] | POST | `{ field: type }` | `{ field: type }` | 200, 400, 401, 500 | yes/no |
+
+## Error Response Format
+All errors follow:
+```json
+{ "error": { "code": "ERROR_CODE", "message": "human readable", "field": "optional" } }
+```
 
 ## Technology Decisions
-| Decision | Choice | Reason | Alternatives Rejected |
-|----------|--------|--------|----------------------|
-| [area] | [choice] | [why] | [what else was considered] |
+| Decision | Choice | Rationale | Alternatives Rejected | Reversibility |
+|----------|--------|-----------|----------------------|--------------|
+| [area] | [choice] | [why — cite constraint or principle] | [what else, why not] | easy / hard |
+
+## Non-Functional Requirements
+| Type | Requirement | Measurement Method |
+|------|------------|-------------------|
+| Performance | [endpoint] responds in < [Nms] at [N] rps | Load test / APM |
+| Security | [specific requirement — not "secure"] | Audit / pen test |
+| Accessibility | WCAG [2.1 AA / 2.1 AAA] | Automated + manual |
+| Availability | [N]% uptime | Monitoring |
+| Data retention | [N] days | Automated policy |
 
 ## Known Risks
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|-----------|
-| [risk] | low/med/high | low/med/high | [how to mitigate] |
+| Risk | Likelihood | Impact | Mitigation | Owner |
+|------|-----------|--------|-----------|-------|
+| [risk] | low/med/high | low/med/high | [concrete action] | dev / PM / ops |
 ```
 
+---
+
 ## Step 5: Generate Acceptance Criteria
 Write `.buildflow/specs/acceptance.md`:
 
-Each AC must be:
-- **Testable** — a human or automated test can verify it
-- **Binary** — pass or fail, no partial credit
-- **Specific** — no vague terms like "works correctly"
+**Rules for every AC:**
+- Binary — pass or fail only, no partial credit
+- Testable — an automated test or explicit manual step can verify it
+- Specific — no vague words (see Critic pass below)
+- Covers both happy path AND at least one failure/edge case per feature
 
 ```markdown
 # Acceptance Criteria
 **App:** [name]  **Phase:** [N]  **Date:** [today]
 
-## [Feature F-01 name]
-- AC-001: Given [context], when [action], then [outcome]
-- AC-002: Given [context], when [action], then [outcome]
+## [Feature F-01: name]  →  US-01, US-02
+**Happy path:**
+- AC-001: Given [setup state], when [user/system action], then [exact observable outcome]
+- AC-002: Given [...], when [...], then [...]
 
-## [Feature F-02 name]
-- AC-003: Given [context], when [action], then [outcome]
+**Failure / edge cases (required — minimum 1 per feature):**
+- AC-003: Given [invalid/boundary/error input], when [...], then [specific error behavior]
+- AC-004: Given [concurrent/race/timeout scenario], when [...], then [...]
+
+## [Feature F-02: name]  →  US-03
+- AC-005: Given [...], when [...], then [...]
+- AC-006 (edge): Given [...], when [...], then [...]
 
 ## Non-Functional
-- AC-NF-001: [performance/security/accessibility requirement]
+- AC-NF-001: [endpoint] under [N] concurrent users responds within [Nms] (p95)
+- AC-NF-002: [page/flow] achieves WCAG 2.1 AA with zero automated violations
+- AC-NF-003: No secrets present in committed code (automated scan passes)
 ```
 
-## Step 6: Spec Review Gate
-Show a summary of all three specs. Ask:
+---
 
-> "Do these specs accurately capture what you want to build? (yes / revise [area])"
+## Step 6: Spec Critic Pass (automatic — runs before showing user)
 
-- If yes: lock specs. Update `light.md`:
+Before presenting specs to the user, self-review all three docs as a Spec Critic:
+
+### Vague Language Scan
+Search every AC for these banned words. Flag any found:
+`correctly` `properly` `works` `fast` `quickly` `slow` `good` `bad` `easy` `easily`
+`should` `appropriate` `reasonable` `nice` `clean` `simple` `obvious` `intuitive`
+
+For each flagged word: replace with a specific, measurable alternative or mark `[NEEDS SPECIFICITY]`.
+
+### Coverage Check
+- Every feature in PRD has at least 2 ACs (1 happy + 1 error/edge) — flag if not
+- Every user story US-XX is referenced in at least one AC's feature section — flag orphans
+- Every component in TDD maps to at least one PRD feature — flag orphans
+- Every NFR in TDD has a corresponding AC-NF — flag gaps
+
+### Testability Check
+For each AC, verify it can be answered as a pass/fail automated test or explicit manual step.
+Flag any AC that requires human judgment to evaluate.
+
+### Consistency Check
+- API contracts in TDD match any referenced endpoints in ACs
+- Data model changes in TDD are sufficient to support all AC outcomes
+- Technology decisions don't contradict any constraints in PRD
+
+### Critic Report
+Show the user:
+```
+Spec Critic Report
+──────────────────
+Vague language:   [N found — fixed N, flagged N]
+Coverage gaps:    [list any orphaned features/stories/components]
+Testability:      [list any ACs needing rework]
+Consistency:      [any TDD/PRD conflicts]
+Overall quality:  STRONG / NEEDS REVISION
+```
+
+---
+
+## Step 7: User Review Gate
+Show summary of all three specs + Critic Report. Ask:
+
+> "Specs ready for review. Critic score: [STRONG / NEEDS REVISION]
+> Approve to lock, or tell me what to revise."
+
+- **Approve:** lock specs. Update `light.md`:
   ```yaml
   spec_status: locked
   spec_phase: [N]
   ac_count: [N]
+  us_count: [N]
+  spec_critic: strong/revised
   ```
-- If revise: ask what's wrong, update the relevant section, repeat Step 6.
+- **Revise:** apply changes to the named section, re-run Critic pass, repeat Step 7.
 
-Do not proceed until the user approves.
+Do not proceed until user approves.
 
-## Step 7: Next Step
-"Specs locked. Run `/buildflow-plan` — the Architect will map tasks to your acceptance criteria."
+---
+
+## --fast Mode
+For single-feature additions:
+- Skip User Stories table (inline in feature row)
+- Skip Technology Decisions (use existing stack)
+- Generate 3 ACs minimum: 1 happy + 1 error + 1 NFR
+- Skip Critic coverage check (only vague language scan)
+- Token budget: ~8K
+
+---
 
-## Token Budget: ~18K
+## Token Budget: ~20K (full) / ~8K (--fast)