buildflow-dev 1.0.6 → 4.0.1

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)

package/templates/commands/spec.md

@@ -0,0 +1,147 @@
+---
+name: buildflow-spec
+description: Generate formal PRD, Technical Design, and Acceptance Criteria before planning
+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.
+
+Run this after `/buildflow-start` and before `/buildflow-plan`.
+
+## Usage
+- `/buildflow-spec` — generate 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
+
+## Context Packet (load only these — nothing else)
+- `.buildflow/core/vision.md`
+- `.buildflow/memory/light.md` (summary fields only: app_name, framework, phase)
+- `.buildflow/specs/` (existing specs if regenerating)
+
+## Step 1: Validate Vision Exists
+Read `.buildflow/core/vision.md`.
+If empty or missing: "Run /buildflow-start first to capture the project vision."
+
+## 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?
+
+Ask all questions at once. Do not ask one at a time.
+Maximum 5 questions. Skip any already answered in vision.md.
+
+## Step 3: Generate PRD
+Write `.buildflow/specs/PRD.md`:
+
+```markdown
+# Product Requirements Document
+**App:** [name]  **Phase:** [N]  **Date:** [today]
+
+## Problem Statement
+[One paragraph: what problem exists, who has it, why current solutions fail]
+
+## Users
+| User Type | Goal | Key Pain Point |
+|-----------|------|----------------|
+| [type] | [goal] | [pain] |
+
+## Features — In Scope
+| ID | Feature | Priority | Success Metric |
+|----|---------|----------|----------------|
+| F-01 | [name] | Must-have / Should-have / Nice-to-have | [measurable] |
+
+## Out of Scope
+- [what we are explicitly NOT building this phase]
+
+## Constraints
+- [tech, timeline, team, budget constraints]
+
+## Success Criteria
+Phase is complete when:
+- [ ] [measurable outcome 1]
+- [ ] [measurable outcome 2]
+```
+
+## Step 4: Generate Technical Design Doc
+Write `.buildflow/specs/TDD.md`:
+
+```markdown
+# Technical Design Document
+**App:** [name]  **Phase:** [N]  **Date:** [today]
+
+## Architecture Overview
+[Brief description of the system architecture]
+
+## Components
+| Component | Responsibility | Interface |
+|-----------|---------------|-----------|
+| [name] | [what it does] | [API / function / event] |
+
+## Data Model
+[Key entities and their relationships — use simple table or diagram]
+
+## API Contracts
+| Endpoint / Function | Input | Output | Auth Required |
+|--------------------|-------|--------|---------------|
+| [name] | [type] | [type] | yes/no |
+
+## Technology Decisions
+| Decision | Choice | Reason | Alternatives Rejected |
+|----------|--------|--------|----------------------|
+| [area] | [choice] | [why] | [what else was considered] |
+
+## Known Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| [risk] | low/med/high | low/med/high | [how to mitigate] |
+```
+
+## 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"
+
+```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-02 name]
+- AC-003: Given [context], when [action], then [outcome]
+
+## Non-Functional
+- AC-NF-001: [performance/security/accessibility requirement]
+```
+
+## 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])"
+
+- If yes: lock specs. Update `light.md`:
+  ```yaml
+  spec_status: locked
+  spec_phase: [N]
+  ac_count: [N]
+  ```
+- If revise: ask what's wrong, update the relevant section, repeat Step 6.
+
+Do not proceed until the user approves.
+
+## Step 7: Next Step
+"Specs locked. Run `/buildflow-plan` — the Architect will map tasks to your acceptance criteria."
+
+## Token Budget: ~18K

package/templates/commands/start.md

@@ -9,31 +9,61 @@ agent: strategist
 
 Begin your project. Works for both greenfield and existing codebases.
 
+## Context Packet (load only these)
+- `.buildflow/memory/light.md`
+- `.buildflow/you/preferences.md`
+
+Do NOT load: specs, phases, codebase files — this is vision only.
+
 ## Step 1: Load Memory
 Read `.buildflow/memory/light.md` and `.buildflow/you/preferences.md`.
+If `light.md` is over 3K tokens: prune it now (see pruning rules below).
 
 ## Step 2: Detect Mode
 
-**Greenfield (no src/ code):**
+**Greenfield (no src/ code yet):**
 Ask vision questions one at a time:
 1. What are you building?
 2. Who is it for?
 3. What problem does it solve?
 4. What's the simplest useful version?
-5. Timeline, team size, budget?
+5. Timeline, team size, constraints?
 6. Confidence in the idea (1-5)?
 
 **Existing codebase (src/ exists):**
 Check if `.buildflow/codebase/MAP.md` exists.
-- If NO: "Run /buildflow-onboard first to analyze your codebase."
-- If YES: Load MAP.md. Ask about goals for this work session.
+- If NO: "Run `/buildflow-onboard` first to analyze your codebase."
+- If YES: Load MAP.md summary only (not full file). Ask about goals for this session.
 
 ## Step 3: Save Vision
-Write to `.buildflow/core/vision.md` and update `.buildflow/core/state.md`.
+Write to `.buildflow/core/vision.md`.
+Initialize `light.md` with:
+```yaml
+app_name: [name]
+framework: [detected or stated]
+language: [detected or stated]
+phase: 0
+spec_status: none
+plan_status: none
+onboard_status: [yes/no]
+last_session: [today]
+```
 
 ## Step 4: Recommend Next Step
-- High confidence (4-5) + greenfield: "Run /buildflow-think"
-- Low confidence: "Let's research first with /buildflow-think"
-- Existing project, onboarded: "Ready! Try /buildflow-modify or /buildflow-think"
+
+| Situation | Next command |
+|-----------|-------------|
+| Greenfield, confidence 4–5 | `/buildflow-spec` — define what to build formally |
+| Greenfield, confidence 1–3 | `/buildflow-think [topic]` — research first |
+| Existing project, not onboarded | `/buildflow-onboard` — map codebase first |
+| Existing project, onboarded | `/buildflow-spec` or `/buildflow-modify` |
+| Emergency fix needed | `/buildflow-hotfix "description"` |
+
+## light.md Pruning Rules
+If `light.md` exceeds 3K tokens on session start:
+- Remove: completed phase task lists, wave details, build timestamps older than last phase
+- Archive these to the most recent `phases/[N]/retro.md`
+- Keep: app_name, framework, language, current_phase, spec_status, style_fingerprint, last 2 decisions
+- After pruning: report "Context pruned: light.md reduced from [X] → [Y] tokens"
 
 ## Token Budget: ~8K

package/templates/commands/test.md

@@ -0,0 +1,82 @@
+---
+name: buildflow-test
+description: Run tests, verify UI flow, and auto-fix failures until all pass
+allowed-tools: Read, Write, Bash, Grep, Glob
+agent: reviewer
+---
+
+# /buildflow-test
+
+Standalone test + fix loop. Runs the test suite, checks UI flow and functionality, and automatically fixes failures — repeats until everything passes or the fix limit is reached.
+
+Use this when:
+- You want to re-verify a wave that was already built
+- You made a manual code change and want to test it
+- `/buildflow-build` stopped and you want to resume testing from where it left off
+
+For automated testing during builds, this loop is already built into `/buildflow-build` — you don't need to run `/buildflow-test` separately after each wave unless you want to re-check.
+
+## Usage
+- `/buildflow-test` — test current wave/phase output
+- `/buildflow-test wave-2` — test a specific wave
+- `/buildflow-test ui` — focus on UI alignment and flow only
+- `/buildflow-test --full` — run full suite including integration and e2e
+
+## Step 1: Load Context
+Read `.buildflow/phases/[N]/PLAN.md` to know what this wave was supposed to deliver.
+Read `.buildflow/memory/light.md` for framework and test setup.
+
+## Step 2: Detect Test Setup
+Identify:
+- Test framework (Jest, Vitest, Pytest, Go test, Cargo, etc.)
+- Test command (`npm test`, `pytest`, `go test ./...`, etc.)
+- E2E framework if present (Playwright, Cypress, etc.)
+- Dev server command if UI is involved
+
+## Step 3: Run Tests
+```bash
+npm test        # or pytest / go test etc.
+```
+
+Also check:
+- If frontend code changed: start dev server, verify UI renders and flows work, no console errors
+- No import errors or missing modules
+- Previously passing tests still pass (no regressions)
+
+## Step 4: Fix Loop (runs automatically on failure)
+
+If any test fails:
+1. Identify root cause (trace error → file → line → why)
+2. Apply minimal fix — only change what broke, do not refactor surrounding code
+3. Re-run the full test suite
+4. Repeat until all tests pass
+
+Maximum fix attempts: 5.
+If still failing after 5 attempts: stop, report what's unresolved, and ask the user how to proceed.
+
+Fix attempt log format:
+```
+Fix attempt [X]/5
+Error: [error message]
+Root cause: [explanation]
+Fix applied: [what changed]
+Result: [pass / still failing]
+```
+
+## Step 5: Report
+
+```
+Test Results
+────────────
+✓ PASS  Tests: 24/24 passing
+✓ PASS  Functional: signup flow works end-to-end
+✓ PASS  UI: form renders correctly, validation messages shown
+⚠ WARN  No test for empty email edge case (non-blocking)
+```
+
+## Step 6: Decision
+- All pass: "Ready to continue to next wave or /buildflow-ship."
+- Warnings only: "Non-blocking. Proceed or address first — your call."
+- Unresolved after 5 attempts: "Manual intervention needed. Use /buildflow-debug for deeper analysis."
+
+## Token Budget: ~25K (more if fix loop runs multiple iterations)