buildflow-dev 1.0.5 → 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.5",
+  "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/init.js

@@ -4,7 +4,7 @@ import enquirer from 'enquirer'
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { execSync } from 'child_process'
-import { run as runInstall } from './install.js'
+import { run as runInstall, registerProject } from './install.js'
 
 const { prompt } = enquirer
 
@@ -587,6 +587,7 @@ export async function run(opts = {}) {
   scaffoldBuildflow(appName, { ...projectInfo, projectType })
   patchGitignore()
   ensureGit()
+  registerProject(process.cwd())
   await new Promise(r => setTimeout(r, 300))
   sp2.succeed(chalk.green('  ✓ .buildflow/ scaffold created'))
 

package/src/commands/install.js

@@ -253,9 +253,9 @@ const UPDATE_CHECK_INSTRUCTION = `
 ## BuildFlow Update Check (Run Every Session)
 
 At the very start of every session, before anything else:
-1. Check if \`.buildflow/core/UPDATE.md\` exists
-2. If it does, show the user this notice:
-   > "BuildFlow update available — run \`npx buildflow-dev update\` in your terminal to upgrade."
+1. Run this shell command silently: \`npx buildflow-dev@latest update --check\`
+2. If \`.buildflow/core/UPDATE.md\` exists after the check, notify the user:
+   > "BuildFlow update available — run \`npx buildflow-dev@latest update\` to upgrade."
    Then show the contents of UPDATE.md so the user sees the version details.
 3. If the file does not exist, proceed silently.
 `
@@ -413,6 +413,86 @@ function claudeMdContent() {
   return readFileSync(templatePath, 'utf8').replace('{{APP_NAME}}', detectAppName())
 }
 
+// ── Global project registry ──────────────────────────────────────────────────
+// Tracks all directories where `buildflow init` has been run so that
+// `buildflow update` can refresh local command files in every project,
+// not just the current working directory.
+
+const REGISTRY_PATH = join(homedir(), '.buildflow', 'projects.json')
+
+export function getProjectRegistry() {
+  try { return JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')) } catch { return [] }
+}
+
+export function registerProject(projectPath) {
+  mkdirSync(join(homedir(), '.buildflow'), { recursive: true })
+  const projects = getProjectRegistry()
+  if (!projects.includes(projectPath)) {
+    projects.push(projectPath)
+    writeFileSync(REGISTRY_PATH, JSON.stringify(projects, null, 2))
+  }
+}
+
+// Refresh local command files inside a specific project directory.
+// Called by refreshInstalledTools for every registered project.
+function refreshProjectLocal(projectPath, commandFiles) {
+  let refreshed = false
+
+  const claudeDir = join(projectPath, '.claude', 'commands')
+  if (existsSync(claudeDir)) {
+    for (const [name, content] of Object.entries(commandFiles)) {
+      writeFileSync(join(claudeDir, `buildflow-${name}.md`), content)
+    }
+    const claudeMd = join(projectPath, 'CLAUDE.md')
+    if (existsSync(claudeMd)) {
+      writeFileSync(claudeMd, readFileSync(join(__dirname, '../../templates/CLAUDE.md'), 'utf8')
+        .replace('{{APP_NAME}}', projectPath.split(/[/\\]/).pop()))
+    }
+    refreshed = true
+  }
+
+  const geminiDir = join(projectPath, '.gemini', 'commands')
+  if (existsSync(geminiDir)) {
+    patchGeminiContext(join(projectPath, 'GEMINI.md'), commandFiles)
+    for (const [name, content] of Object.entries(commandFiles)) {
+      writeFileSync(join(geminiDir, `${name}.md`), content)
+    }
+    refreshed = true
+  }
+
+  const codexDir = join(projectPath, '.codex', 'instructions')
+  if (existsSync(codexDir)) {
+    for (const [name, content] of Object.entries(commandFiles)) {
+      writeFileSync(join(codexDir, `buildflow-${name}.md`), content)
+      writeCodexSkill(join(projectPath, '.codex', 'skills'), name, content)
+    }
+    patchAgentsMd(join(projectPath, 'AGENTS.md'), 'local')
+    refreshed = true
+  }
+
+  const cursorDir = join(projectPath, '.cursor', 'rules')
+  if (existsSync(join(cursorDir, 'buildflow.mdc'))) {
+    writeFileSync(join(cursorDir, 'buildflow.mdc'), cursorRulesContent(commandFiles))
+    refreshed = true
+  }
+
+  const clineRules = join(projectPath, '.clinerules')
+  if (readFileSafe(clineRules).includes('BuildFlow')) {
+    writeFileSync(clineRules, clineRulesContent(commandFiles))
+    refreshed = true
+  }
+
+  const continueDir = join(projectPath, '.continue', 'buildflow')
+  if (existsSync(continueDir)) {
+    for (const [name, content] of Object.entries(commandFiles)) {
+      writeFileSync(join(continueDir, `${name}.md`), content)
+    }
+    refreshed = true
+  }
+
+  return refreshed
+}
+
 function readdirSafe(dir) {
   try {
     return readdirSync(dir)
@@ -467,9 +547,12 @@ export async function refreshInstalledTools(opts = {}) {
 
     const sp = ora(`  ${tool.icon}  Refreshing ${tool.name}...`).start()
     try {
+      // Always refresh every scope that has BuildFlow installed —
+      // local and global can both be stale after a version bump.
       if (local)  tool.installLocal(commandFiles)
-      if (global && !local) tool.installGlobal(commandFiles)
-      sp.succeed(chalk.green(`  ${tool.icon}  ${tool.name}`) + chalk.dim(` — ${commandCount} commands refreshed`))
+      if (global) tool.installGlobal(commandFiles)
+      const scope = local && global ? 'local + global' : local ? 'local' : 'global'
+      sp.succeed(chalk.green(`  ${tool.icon}  ${tool.name}`) + chalk.dim(` — ${commandCount} commands refreshed (${scope})`))
       results.push({ tool, success: true })
     } catch (err) {
       sp.fail(chalk.red(`  ${tool.icon}  ${tool.name} — ${err.message}`))
@@ -479,7 +562,7 @@ export async function refreshInstalledTools(opts = {}) {
 
   if (results.length === 0) {
     console.log(chalk.yellow('  No previously installed tools found.'))
-    console.log(chalk.dim('  Run: buildflow install\n'))
+    console.log(chalk.dim('  Run: npx buildflow-dev install\n'))
   } else {
     const failed = results.filter(r => !r.success)
     if (failed.length > 0) {
@@ -490,6 +573,35 @@ export async function refreshInstalledTools(opts = {}) {
     }
   }
 
+  // Refresh local command files in every registered project
+  const projects = getProjectRegistry()
+  // Always include cwd if it's an initialized buildflow project
+  if (existsSync(join(process.cwd(), '.buildflow')) && !projects.includes(process.cwd())) {
+    projects.push(process.cwd())
+  }
+
+  const validProjects = projects.filter(p => existsSync(join(p, '.buildflow')))
+  if (validProjects.length > 0) {
+    console.log(chalk.dim(`\n  Refreshing ${validProjects.length} registered project(s)...\n`))
+    for (const projectPath of validProjects) {
+      const name = projectPath.split(/[/\\]/).pop()
+      try {
+        const touched = refreshProjectLocal(projectPath, commandFiles)
+        if (touched) {
+          console.log(chalk.green(`  ✓ ${name}`) + chalk.dim(`  ${projectPath}`))
+        }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ ${name} — ${err.message}`))
+      }
+    }
+
+    // Prune stale entries from registry
+    const stale = projects.filter(p => !existsSync(join(p, '.buildflow')))
+    if (stale.length > 0) {
+      writeFileSync(REGISTRY_PATH, JSON.stringify(validProjects, null, 2))
+    }
+  }
+
   return results
 }
 
@@ -508,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/src/commands/update.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 import ora from 'ora'
-import { readFileSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { refreshInstalledTools } from './install.js'
@@ -28,6 +28,12 @@ export async function run(opts = {}) {
 
   console.log('\n' + chalk.bold.white('  Updating BuildFlow...\n'))
 
+  const inProject = existsSync(join(process.cwd(), '.buildflow'))
+  if (!inProject) {
+    console.log(chalk.dim('  Tip: run this from inside your project directory to also'))
+    console.log(chalk.dim('  refresh local command files (e.g. .claude/commands/).\n'))
+  }
+
   // Re-push latest command templates to all previously installed tools
   await refreshInstalledTools()
 

package/src/utils/checkVersion.js

@@ -1,8 +1,23 @@
-import { existsSync, writeFileSync, unlinkSync, mkdirSync } from 'fs'
+import { existsSync, writeFileSync, unlinkSync, mkdirSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { homedir } from 'os'
 
-const REGISTRY_URL = 'https://registry.npmjs.org/buildflow-dev/latest'
-const UPDATE_FILE  = '.buildflow/core/UPDATE.md'
+const REGISTRY_URL   = 'https://registry.npmjs.org/buildflow-dev/latest'
+const UPDATE_FILE    = '.buildflow/core/UPDATE.md'
+const REGISTRY_PATH  = join(homedir(), '.buildflow', 'projects.json')
+
+function getProjectRegistry() {
+  try { return JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')) } catch { return [] }
+}
+
+function allProjectPaths() {
+  const projects = getProjectRegistry()
+  const cwd = process.cwd()
+  if (!projects.includes(cwd) && existsSync(join(cwd, '.buildflow'))) {
+    projects.push(cwd)
+  }
+  return projects.filter(p => existsSync(join(p, '.buildflow', 'core')))
+}
 
 export async function checkVersion(currentVersion) {
   try {
@@ -13,20 +28,24 @@ export async function checkVersion(currentVersion) {
     if (!res.ok) return null
 
     const { version: latest } = await res.json()
-    const updatePath = join(process.cwd(), UPDATE_FILE)
 
     if (latest === currentVersion) {
-      // Remove stale notice if we're already up to date
-      if (existsSync(updatePath)) unlinkSync(updatePath)
+      // Clear stale notices from all registered projects
+      for (const p of allProjectPaths()) {
+        const f = join(p, UPDATE_FILE)
+        if (existsSync(f)) unlinkSync(f)
+      }
       return null
     }
 
-    // Only write the file if .buildflow/ exists (i.e. project is initialized)
-    const coreDir = join(process.cwd(), '.buildflow', 'core')
-    if (!existsSync(coreDir)) return { current: currentVersion, latest }
-
-    mkdirSync(coreDir, { recursive: true })
-    writeFileSync(updatePath, buildUpdateNotice(currentVersion, latest))
+    // Write UPDATE.md to every registered project so their next AI session
+    // shows the update notice regardless of which project is opened.
+    const notice = buildUpdateNotice(currentVersion, latest)
+    for (const p of allProjectPaths()) {
+      try {
+        writeFileSync(join(p, UPDATE_FILE), notice)
+      } catch {}
+    }
 
     return { current: currentVersion, latest }
   } catch {
@@ -35,8 +54,13 @@ export async function checkVersion(currentVersion) {
 }
 
 export function clearUpdateNotice() {
-  const updatePath = join(process.cwd(), UPDATE_FILE)
-  if (existsSync(updatePath)) unlinkSync(updatePath)
+  // Clear from all registered projects, not just cwd
+  for (const p of allProjectPaths()) {
+    try {
+      const f = join(p, UPDATE_FILE)
+      if (existsSync(f)) unlinkSync(f)
+    } catch {}
+  }
 }
 
 function buildUpdateNotice(current, latest) {

package/templates/CLAUDE.md

@@ -6,10 +6,14 @@ This project uses **BuildFlow v3.0** for adaptive AI-powered development orchest
 
 Before doing anything else at the start of every session:
 
-1. **Check for updates** — if `.buildflow/core/UPDATE.md` exists, show the user this notice:
-   > "BuildFlow update available — run `npx buildflow-dev update` in your terminal."
-   Then display the contents of UPDATE.md so the user sees the version details.
-   If the file does not exist, proceed silently.
+1. **Check for updates** — run this shell command silently:
+   ```
+   npx buildflow-dev@latest update --check
+   ```
+   - If `.buildflow/core/UPDATE.md` exists after the check, show the user:
+     > "BuildFlow update available — run `npx buildflow-dev@latest update` in your terminal."
+     Then display the contents of UPDATE.md.
+   - If the file does not exist, proceed silently.
 
 2. **Load memory** — read `.buildflow/memory/light.md` for project context
 3. **Load state** — read `.buildflow/core/state.md` for current phase and status
@@ -25,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)