buildflow-dev 1.0.6 → 1.0.7

package/README.md

@@ -15,6 +15,7 @@
 - [Supported AI Tools](#supported-ai-tools)
 - [AI Slash Commands](#ai-slash-commands)
 - [CLI Commands](#cli-commands)
+- [Example: Full Greenfield Flow](#example-full-greenfield-flow-phases--waves)
 - [How It Works](#how-it-works)
 - [Package Source Structure](#package-source-structure)
 - [The .buildflow/ Scaffold](#the-buildflow-scaffold)
@@ -91,7 +92,8 @@ These are installed into your AI tool and triggered by typing `/` (or `@` / `$`
 | `/buildflow-start` | Strategist | Begin project: asks vision questions, detects mode, saves to `core/vision.md` | ~8K |
 | `/buildflow-think [topic]` | Researcher × 3 + Synthesizer | Parallel web research on a topic, synthesized into a recommendation | ~30K |
 | `/buildflow-plan [phase]` | Architect | Maps task dependencies, groups into parallel waves, writes `phases/N/PLAN.md` | ~20K |
-| `/buildflow-build [wave]` | Builder × N + Reviewer | Executes the plan wave-by-wave with parallel Builders, style-matched to your codebase | ~50K/wave |
+| `/buildflow-build [wave]` | Builder × N + Reviewer | Executes the plan wave-by-wave — each wave auto-tests, auto-fixes failures, and only advances when fully green | ~50K/wave |
+| `/buildflow-test [wave]` | Reviewer | Standalone test + fix loop — re-verify a wave or test a manual change outside of `/buildflow-build` | ~25K |
 | `/buildflow-check` | Reviewer × 3 | Three parallel reviewers check correctness, quality, and security | ~20K |
 | `/buildflow-ship` | Strategist + Security Auditor | Pre-ship security gate → retrospective → git tag | ~22K |
 
@@ -100,9 +102,37 @@ These are installed into your AI tool and triggered by typing `/` (or `@` / `$`
 | Command | Agent | Purpose | Token Cost |
 |---------|-------|---------|-----------|
 | `/buildflow-onboard` | Cartographer | One-time analysis: writes `MAP.md`, `PATTERNS.md`, `DEPENDENCIES.md`, `HOTSPOTS.md` | ~35K |
-| `/buildflow-modify "description"` | Surgeon | Surgical change with blast-radius analysis and restore point | ~30K |
+| `/buildflow-modify "description"` | Surgeon | Surgical change with blast-radius analysis and restore point — use for features **and bugfixes** | ~30K |
 | `/buildflow-refactor [scope]` | Surgeon + Reviewer | Improve code quality without changing behavior | ~40K |
 
+**`/buildflow-modify` works for both features and bugs.** Pass a plain-English description either way:
+
+```
+# Feature
+/buildflow-modify "Add pagination to the GET /users endpoint"
+
+# Bugfix
+/buildflow-modify "Fix null pointer crash when user has no profile photo"
+/buildflow-modify "Fix login redirect loop when session expires"
+```
+
+The Surgeon always runs a blast-radius analysis first (what files are affected, what calls them) and creates a git restore point before touching anything — making it especially safe for bugfixes where a wrong change can cause regressions.
+
+If you're not sure where the bug is yet, use `/buildflow-help` first — it's a diagnostic mode that helps you locate the problem before you try to fix it.
+
+| Situation | Command |
+|-----------|---------|
+| Know what needs to change | `/buildflow-modify "fix description"` |
+| Don't know where the bug is | `/buildflow-help` first, then `/buildflow-modify` |
+| Tests failing after a change | `/buildflow-debug` |
+
+### Debugging & Deployment
+
+| Command | Agent | Purpose | Token Cost |
+|---------|-------|---------|-----------|
+| `/buildflow-debug ["error"]` | Surgeon | Root-cause analysis for failing tests or broken behavior — traces error to source, applies minimal fix | ~20K |
+| `/buildflow-deploy [env]` | Strategist | Pre-flight checks then deploy to staging or production | ~15K |
+
 ### Security
 
 | Command | Agent | Purpose | Token Cost |
@@ -149,6 +179,126 @@ buildflow update --check            # Check current version without updating
 
 ---
 
+## Example: Full Greenfield Flow (Phases & Waves)
+
+Here's what a complete new project looks like end-to-end, showing how phases and waves are **auto-generated** by BuildFlow — you never define them manually.
+
+### 1. Init and start
+
+```bash
+mkdir my-app && cd my-app
+npx buildflow-dev init
+```
+
+```
+/buildflow-start
+```
+> Strategist asks 4–5 questions. Writes answers to `.buildflow/core/vision.md`.
+
+---
+
+### 2. Research (optional)
+
+```
+/buildflow-think auth-strategy
+```
+> 3 Researcher agents run in parallel. Synthesizer combines results.  
+> Output → `.buildflow/research/auth-strategy.md`
+
+---
+
+### 3. Plan — Architect auto-generates phases and waves
+
+```
+/buildflow-plan
+```
+
+The Architect reads `vision.md` and produces `.buildflow/phases/01/PLAN.md`:
+
+```
+Phase 1 — Foundation
+
+Wave 1 (parallel — no dependencies):
+  • Create database schema
+  • Create project config files
+  • Set up folder structure
+
+Wave 2 (depends on Wave 1):
+  • Create data models
+  • Create auth middleware
+
+Wave 3 (depends on Wave 2):
+  • Create API routes
+  • Create service layer
+
+Wave 4 (depends on Wave 3):
+  • Create UI components
+  • Write integration tests
+```
+
+You didn't write any of this — the Architect derived it from your vision.
+
+---
+
+### 4. Build — testing is automatic inside every wave
+
+```
+/buildflow-build
+```
+
+Testing is **built into every wave** — you don't run `/buildflow-test` manually. For each wave, the cycle is:
+
+```
+Build wave tasks (parallel Builders)
+        ↓
+Review output (Reviewer)
+        ↓
+Run tests automatically
+        ↓
+  ┌─ Tests pass? ──────────────────────── Move to next wave
+  └─ Tests fail? → Fix → Re-test → loop until green (max 5 attempts)
+```
+
+So `Wave 1` is fully green before `Wave 2` starts. `Wave 2` is fully green before `Wave 3` starts. And so on.
+
+If a wave can't be fixed within 5 attempts, the build stops and reports exactly what failed — then you can use `/buildflow-debug` for deeper investigation.
+
+```
+/buildflow-debug "auth middleware not rejecting expired tokens"
+```
+
+**`/buildflow-test` standalone** is available if you want to re-verify a wave you already built, or test after a manual code change outside of `/buildflow-build`.
+
+---
+
+### 5. Check, ship, and deploy
+
+```
+/buildflow-check
+```
+> 3 Reviewers in parallel: correctness / quality / security
+
+```
+/buildflow-ship
+```
+> Security gate → retrospective written to `phases/01/retro.md` → git tag
+
+```
+/buildflow-deploy staging
+```
+> Pre-flight checks → deploy to staging → smoke test
+
+```
+/buildflow-deploy production
+```
+> Stricter gate (all tests + audit must pass) → deploy to production
+
+---
+
+**Key point:** `[phase]` and `[wave]` arguments are optional escape hatches for resuming or re-running specific parts. In a normal flow you just type `/buildflow-plan` and `/buildflow-build` with no arguments.
+
+---
+
 ## How It Works
 
 ### The install flow
@@ -266,7 +416,7 @@ buildflow-dev/
 │   │                         all available /buildflow-* commands.
 │   │                         {{APP_NAME}} is replaced with the detected project name.
 │   │
-│   └── commands/             14 markdown files — one per slash command.
+│   └── commands/             17 markdown files — one per slash command.
 │       │                     Each file is the full instruction set for that command.
 │       │                     The AI reads and executes these when you trigger the command.
 │       │                     Format: YAML frontmatter (name, description, agent, tools)
@@ -276,12 +426,15 @@ buildflow-dev/
 │       ├── think.md          Parallel research with up to 3 Researcher agents
 │       ├── plan.md           Dependency mapping → wave-based execution plan
 │       ├── build.md          Wave-by-wave parallel Builder execution
+│       ├── test.md           Run tests + UI verification after each wave
 │       ├── check.md          3-reviewer parallel quality check
 │       ├── ship.md           Pre-ship security gate → retro → git tag
 │       ├── onboard.md        One-time codebase analysis → MAP/PATTERNS/DEPENDENCIES/HOTSPOTS
 │       ├── modify.md         Surgical code change with blast-radius analysis
 │       ├── refactor.md       Quality improvement without behavior change
 │       ├── audit.md          OWASP Top 10 AI-powered scan
+│       ├── debug.md          Root-cause analysis for failing tests or broken behavior
+│       ├── deploy.md         Pre-flight checks → deploy to staging or production
 │       ├── status.md         Current phase and recommended next action
 │       ├── explain.md        Plain-language explanation of code, concepts, errors
 │       ├── back.md           Undo to git restore point, update state
@@ -576,11 +729,23 @@ Everything else (`.claude/`, `node_modules/`, `.gitignore`, etc.) is excluded.
 
 ## Roadmap
 
+### New AI Tools
 - [ ] `buildflow install --tool windsurf` — Windsurf IDE support
 - [ ] `buildflow install --tool aider` — Aider CLI support
 - [ ] `buildflow install --tool zed` — Zed editor support
-- [ ] GitHub Actions workflow: `buildflow audit` in CI
+
+### New Slash Commands
+- [ ] `/buildflow-perf` — performance profiling: detect slow queries, bundle size issues, render bottlenecks
+- [ ] `/buildflow-docs` — auto-generate or update README, API docs, and inline comments from code
+- [ ] `/buildflow-migrate` — guided database migration: generate migration files, verify rollback safety
+- [ ] `/buildflow-seed` — generate realistic test data for the current schema
+
+### CLI Improvements
+- [ ] `buildflow audit` in GitHub Actions — CI-friendly exit codes already work, needs workflow template
 - [ ] `buildflow fix --auto` — non-interactive mode for CI
+- [ ] `buildflow test` — terminal wrapper that runs the project's test suite with BuildFlow context
+
+### Platform
 - [ ] Web dashboard for project status visualization
 - [ ] Custom agent creation: `buildflow agent create`
 - [ ] Team sync: shared `.buildflow/` across teammates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildflow-dev",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Adaptive AI-powered development orchestration. Works with Claude Code, Gemini CLI, Codex CLI, Cursor, and more.",
   "keywords": [
     "ai",

package/src/commands/install.js

@@ -620,8 +620,9 @@ function loadCommandTemplates() {
   const templatesDir = join(__dirname, '../../templates/commands')
   const commands = {}
   const commandNames = [
-    'start', 'think', 'plan', 'build', 'check', 'ship',
+    'start', 'think', 'plan', 'build', 'test', 'check', 'ship',
     'onboard', 'modify', 'refactor', 'audit',
+    'debug', 'deploy',
     'status', 'explain', 'back', 'help',
   ]
   for (const name of commandNames) {

package/templates/CLAUDE.md

@@ -29,9 +29,13 @@ Type `/` in Claude Code to see available commands:
 - `/buildflow-think` — research and discuss
 - `/buildflow-plan` — create execution plan
 - `/buildflow-build` — implement the plan
-- `/buildflow-check` — verify quality
+- `/buildflow-test` — run tests and verify UI/functionality after each wave
+- `/buildflow-check` — verify quality with 3 parallel reviewers
+- `/buildflow-debug` — root-cause analysis when tests fail or something breaks
 - `/buildflow-ship` — finalize with security gate
+- `/buildflow-deploy` — pre-flight checks then deploy to staging or production
 - `/buildflow-audit` — run security scan
+- `/buildflow-modify` — surgical change or bugfix to existing code
 - `/buildflow-status` — see where you are
 - `/buildflow-help` — get help or recover from issues
 

package/templates/commands/build.md

@@ -1,18 +1,18 @@
 ---
 name: buildflow-build
-description: Execute the plan with parallel Builder agents
-allowed-tools: Read, Write, Bash
+description: Execute the plan with parallel Builder agents, auto-test and auto-fix each wave
+allowed-tools: Read, Write, Bash, Grep, Glob
 agents: builder, reviewer
 ---
 
 # /buildflow-build
 
-Execute the current phase plan. Spawns parallel Builder agents per wave, then Reviewer checks quality.
+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.
 
 ## Usage
-- `/buildflow-build` — execute current phase plan
-- `/buildflow-build wave-2` — execute a specific wave
-- `/buildflow-build <task>` — build a single task
+- `/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
 
 ## Step 1: Load Plan
 Read `.buildflow/phases/[N]/PLAN.md`.
@@ -20,42 +20,86 @@ Load `.buildflow/memory/light.md` for style preferences.
 If existing project: load `.buildflow/codebase/PATTERNS.md`.
 
 ## Step 2: Style Fingerprint
-Before writing code, confirm:
+Before writing any code, confirm:
 - Naming conventions (camelCase, PascalCase, snake_case)
 - Import organization
 - Error handling style
-- Comment style
 - Test file location and naming
 
-## Step 3: Execute Wave 1
-Spawn Builder agents in parallel for Wave 1 tasks.
-Each Builder agent:
+## Step 3: Execute Wave
+
+Repeat this block for each wave in the plan:
+
+### 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 detected style
+- Writes code matching the detected style
 - Adds LEARN: comments for non-obvious patterns
 - Reports back: files created/modified, decisions made
 
-## Step 4: Review Wave 1
-Reviewer agent checks each output:
+### 3b — Review
+Reviewer checks each output:
 - Does it meet the task spec?
-- Does it match the codebase style?
+- Does it match codebase style?
 - Any security concerns?
-- Tests present if needed?
+- Are tests written for new logic?
+
+### 3c — Test (automatic, runs after every wave)
+Detect and run the test suite:
+```bash
+npm test        # Node / JS / TS projects
+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
+
+**Do not move to the next wave until this wave is fully 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.
+
+Fix attempt log format:
+```
+Wave [N] — Fix attempt [X]/5
+Error: [error message]
+Root cause: [explanation]
+Fix applied: [what changed]
+Result: [pass / still failing]
+```
 
-## Step 5: Continue Waves
-Repeat for Wave 2, Wave 3, etc.
-Each wave waits for the previous to complete and pass review.
+## 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)
 
-## Step 6: Integration Check
-After all waves: verify the pieces connect correctly.
-Run existing tests if available.
+## 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 7: Update Memory
+## Step 6: Update Memory
 ```yaml
 last_build_date: [today]
 phase: [N]
 tasks_completed: [list]
 files_changed: [list]
+waves_completed: [N]
+test_status: all passing
 ```
 
-## Token Budget: ~50K per wave (parallel)
+## Token Budget: ~50K per wave (build + test + fix loop)

package/templates/commands/debug.md

@@ -0,0 +1,68 @@
+---
+name: buildflow-debug
+description: Systematic debugging when a test fails or something breaks
+allowed-tools: Read, Write, Bash, Grep, Glob
+agent: surgeon
+---
+
+# /buildflow-debug
+
+Systematic root-cause analysis for failing tests, broken builds, or unexpected behavior. The Surgeon reads the error, traces it to the source, and fixes it with minimal footprint.
+
+## Usage
+- `/buildflow-debug` — debug the most recent failure
+- `/buildflow-debug "error message or description"`
+- `/buildflow-debug src/auth/login.ts` — debug a specific file
+- `/buildflow-debug --trace` — full stack trace analysis
+
+## Step 1: Collect the Error
+If a description was passed, use it.
+Otherwise check for recent failure context:
+- Last test run output
+- Browser console errors
+- Terminal error logs
+- `.buildflow/phases/[N]/PLAN.md` for what was expected
+
+## Step 2: Reproduce the Failure
+- Run the failing test or trigger the failing flow
+- Confirm the error is reproducible before investigating
+- Note: exact error message, file, line number, stack trace
+
+## Step 3: Trace to Root Cause
+Work backwards from the symptom:
+1. What line threw the error?
+2. What called that line?
+3. What data was passed in?
+4. Where does that data come from?
+5. What assumption is violated?
+
+Distinguish:
+- **Symptom** — where the error surfaces
+- **Root cause** — where the actual problem is
+
+## Step 4: Impact Check
+Before fixing:
+- How many places does this root cause affect?
+- Is this a one-off bug or a systemic pattern?
+- Will fixing this break anything else?
+
+## Step 5: Create Restore Point
+```bash
+git stash  # safe fallback before making changes
+```
+
+## Step 6: Apply Fix
+- Fix only the root cause, not the symptom
+- Minimum footprint — do not refactor surrounding code
+- Match existing code style (PATTERNS.md)
+
+## Step 7: Verify Fix
+- Re-run the failing test — confirm it passes
+- Run full test suite — confirm no regressions
+- If UI bug: verify the flow works end-to-end
+
+## Step 8: Prevent Recurrence
+- Add a test that would have caught this bug
+- Note the fix in `.buildflow/learnings/decisions.md` if it reveals a systemic issue
+
+## Token Budget: ~20K

package/templates/commands/deploy.md

@@ -0,0 +1,80 @@
+---
+name: buildflow-deploy
+description: Deploy to staging or production with pre-flight checks
+allowed-tools: Read, Write, Bash, Grep, Glob
+agent: strategist
+---
+
+# /buildflow-deploy
+
+Pre-flight checks and deployment orchestration. Ensures the build is safe to deploy before pushing to any environment.
+
+## Usage
+- `/buildflow-deploy` — deploy to default environment
+- `/buildflow-deploy staging` — deploy to staging
+- `/buildflow-deploy production` — deploy to production (stricter gate)
+- `/buildflow-deploy --dry-run` — show what would happen without deploying
+
+## Step 1: Load Context
+Read `.buildflow/core/state.md` for current phase and status.
+Read `.buildflow/memory/light.md` for project framework and deploy config.
+
+## Step 2: Pre-flight Gate
+
+**Always required:**
+- [ ] `/buildflow-test` passed (or confirm manually)
+- [ ] `/buildflow-audit --pre-ship` passed (no critical secrets or vulnerabilities)
+- [ ] No uncommitted changes (`git status` clean)
+- [ ] On correct branch (not committing directly to main unless intentional)
+
+**Production only (additional):**
+- [ ] `/buildflow-check` passed
+- [ ] All tests passing including integration
+- [ ] Environment variables verified for target environment
+- [ ] Database migrations reviewed if schema changed
+
+If any gate fails: stop and report what needs to be resolved.
+
+## Step 3: Detect Deploy Setup
+Check for:
+- `package.json` scripts: `deploy`, `deploy:staging`, `deploy:prod`
+- Deployment config files: `vercel.json`, `netlify.toml`, `fly.toml`, `railway.json`, `Dockerfile`
+- CI/CD config: `.github/workflows/`, `.gitlab-ci.yml`
+- Cloud CLI tools: `vercel`, `netlify`, `flyctl`, `railway`, `heroku`
+
+## Step 4: Environment Confirmation
+Show:
+- Target environment (staging / production)
+- Deploy method detected
+- What will change (git diff summary)
+
+Ask for explicit confirmation before proceeding, especially for production.
+
+## Step 5: Deploy
+Run the detected deploy command or guide the user through manual steps if no automation is detected.
+
+```bash
+# Examples depending on detected setup:
+vercel --prod
+netlify deploy --prod
+flyctl deploy
+railway up
+```
+
+## Step 6: Post-Deploy Verification
+- Confirm deploy succeeded (exit code, deploy URL)
+- Run a smoke test if possible (ping health endpoint, load the app URL)
+- Check for errors in deploy logs
+
+## Step 7: Update State
+```yaml
+last_deploy: [today]
+environment: [staging/production]
+deployed_phase: [N]
+deploy_url: [url if available]
+```
+
+## --dry-run Flag
+Shows the pre-flight checklist results and what deploy command would run — without deploying.
+
+## Token Budget: ~15K

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)