buildflow-dev 1.0.0

package/src/utils/welcome.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+export async function showWelcome() {
+  const isInitialized = existsSync(join(process.cwd(), '.buildflow'))
+
+  console.log('\n' + chalk.bold.white('  BuildFlow v3.0'))
+  console.log(chalk.dim('  Adaptive AI-powered development orchestration\n'))
+
+  console.log(
+    chalk.dim('  Works with: ') +
+    chalk.hex('#8B5CF6')('Claude Code') + '  ' +
+    chalk.hex('#4285F4')('Gemini CLI') + '  ' +
+    chalk.hex('#10A37F')('Codex CLI') + '  ' +
+    chalk.white('Cursor') + '  ' +
+    chalk.hex('#007AFF')('Cline') + '  ' +
+    chalk.hex('#F59E0B')('Continue')
+  )
+  console.log('')
+
+  if (isInitialized) {
+    let state = {}
+    try {
+      const statePath = join(process.cwd(), '.buildflow', 'core', 'state.md')
+      const raw = readFileSync(statePath, 'utf8')
+      state = {
+        app:   raw.match(/Project:\s*(.+)/)?.[1]?.trim() ?? '?',
+        type:  raw.match(/Type:\s*(.+)/)?.[1]?.trim() ?? '?',
+        phase: raw.match(/Phase:\s*(.+)/)?.[1]?.trim() ?? '0',
+      }
+    } catch {}
+
+    console.log(chalk.green('  ✓ BuildFlow active') + chalk.dim(` — ${state.app} (${state.type})`))
+    console.log('')
+    console.log(chalk.bold('  Commands:'))
+    console.log('')
+
+    if (state.type?.includes('existing')) {
+      console.log(chalk.cyan('    /buildflow-onboard ') + chalk.dim('  Map your codebase (run once)'))
+      console.log(chalk.cyan('    /buildflow-modify  ') + chalk.dim('  Change existing code safely'))
+      console.log(chalk.cyan('    /buildflow-refactor') + chalk.dim('  Improve existing code'))
+    } else {
+      console.log(chalk.cyan('    /buildflow-start  ') + chalk.dim('  Begin your project'))
+      console.log(chalk.cyan('    /buildflow-think  ') + chalk.dim('  Discuss & research'))
+      console.log(chalk.cyan('    /buildflow-plan   ') + chalk.dim('  Create execution plan'))
+    }
+
+    console.log(chalk.cyan('    /buildflow-build  ') + chalk.dim('  Execute the plan'))
+    console.log(chalk.cyan('    /buildflow-check  ') + chalk.dim('  Verify quality'))
+    console.log(chalk.cyan('    /buildflow-ship   ') + chalk.dim('  Finalize (runs security gate)'))
+    console.log(chalk.cyan('    /buildflow-audit  ') + chalk.dim('  Run security audit'))
+    console.log(chalk.cyan('    /buildflow-status ') + chalk.dim('  Where am I?'))
+    console.log('')
+    console.log(chalk.dim('  CLI commands:'))
+    console.log(chalk.white('    buildflow status  ') + chalk.dim('  Show project status'))
+    console.log(chalk.white('    buildflow audit   ') + chalk.dim('  Run security audit from terminal'))
+    console.log(chalk.white('    buildflow update  ') + chalk.dim('  Update BuildFlow commands'))
+  } else {
+    console.log(chalk.yellow('  Not initialized in this directory.\n'))
+    console.log(chalk.bold('  Get started:\n'))
+    console.log(
+      '    ' + chalk.bgCyan.black(' npx buildflow-dev init ') +
+      chalk.dim('  ← Set up BuildFlow + install slash commands')
+    )
+    console.log('')
+    console.log(chalk.dim('  What this does:'))
+    console.log(chalk.dim('    1. Detects your project (framework, language, existing code)'))
+    console.log(chalk.dim('    2. Sets up .buildflow/ with agents, memory, security rules'))
+    console.log(chalk.dim('    3. Detects Claude Code, Gemini CLI, Codex CLI, Cursor, etc.'))
+    console.log(chalk.dim('    4. Installs /buildflow-* slash commands into each detected tool'))
+    console.log(chalk.dim('    5. Type "/" in your AI tool to start'))
+    console.log('')
+    console.log(chalk.bold('  Or install directly into a specific tool:\n'))
+    console.log(chalk.white('    buildflow install --tool claude'))
+    console.log(chalk.white('    buildflow install --tool gemini'))
+    console.log(chalk.white('    buildflow install --tool codex'))
+    console.log(chalk.white('    buildflow install --tool cursor'))
+    console.log(chalk.white('    buildflow install --tool all'))
+  }
+
+  console.log('')
+}

package/templates/CLAUDE.md

@@ -0,0 +1,75 @@
+# {{APP_NAME}} — Claude Code Configuration
+
+This project uses **BuildFlow v3.0** for adaptive AI-powered development orchestration.
+
+## Quick Start
+
+Type `/` in Claude Code to see available commands:
+
+- `/buildflow-start` — begin or continue the project
+- `/buildflow-onboard` — analyze existing codebase (run once for existing projects)
+- `/buildflow-think` — research and discuss
+- `/buildflow-plan` — create execution plan
+- `/buildflow-build` — implement the plan
+- `/buildflow-check` — verify quality
+- `/buildflow-ship` — finalize with security gate
+- `/buildflow-audit` — run security scan
+- `/buildflow-status` — see where you are
+- `/buildflow-help` — get help or recover from issues
+
+## Always Do at Session Start
+
+1. Read `.buildflow/memory/light.md` for project context
+2. Read `.buildflow/core/state.md` for current phase and status
+3. If onboarded: load `.buildflow/codebase/MAP.md`
+
+## Core Rules
+
+- Ask confidence (1-5) before locking major decisions
+- Show alternatives before making architectural choices
+- Add `LEARN:` comments when introducing unfamiliar patterns
+- Create git restore points before destructive operations
+- Run `/buildflow-audit` before every `/buildflow-ship`
+- Cite research sources with trust scores (1-5)
+- Keep `.buildflow/memory/light.md` under 5K tokens
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| Strategist | Vision, decisions, direction |
+| Researcher | Parallel web research with sources |
+| Synthesizer | Combines research findings |
+| Architect | Dependency-aware planning |
+| Builder | Code matching project style |
+| Reviewer | Quality checks |
+| Cartographer | Maps existing codebases |
+| Surgeon | Precise modifications to existing code |
+| Security Auditor | OWASP Top 10 scanning |
+
+Each agent gets a **fresh context window** — no context rot.
+
+## Project Structure
+
+```
+.buildflow/
+├── core/
+│   ├── vision.md       ← What we're building
+│   └── state.md        ← Current phase and status
+├── you/
+│   └── preferences.md  ← Experience level, style prefs
+├── memory/
+│   └── light.md        ← Persistent context (≤5K tokens)
+├── codebase/           ← Generated by /buildflow-onboard
+│   ├── MAP.md
+│   ├── PATTERNS.md
+│   ├── DEPENDENCIES.md
+│   └── HOTSPOTS.md
+├── security/
+│   ├── DEBT.md
+│   └── reports/
+├── phases/             ← Per-phase work and retros
+└── learnings/
+    ├── glossary.md
+    └── decisions.md
+```

package/templates/commands/audit.md

@@ -0,0 +1,119 @@
+---
+name: buildflow-audit
+description: Comprehensive OWASP Top 10 security audit
+allowed-tools: Read, Bash, Grep, Glob
+agent: security-auditor
+---
+
+# /buildflow-audit
+
+Full security audit. The Security Auditor agent scans for OWASP Top 10 vulnerabilities.
+
+## Flags
+- `--quick` : Only recently changed files (~15K tokens)
+- `--target <path>` : Specific file or directory
+- `--category <A01-A10>` : Single OWASP category
+- `--pre-ship` : Lightweight secrets + critical patterns (~10K)
+
+## Phase 1: Secrets Scan
+Search for:
+- API keys (sk-, pk-, AKIA patterns)
+- Hardcoded passwords/credentials
+- Private keys (-----BEGIN)
+- Database URLs with embedded credentials
+- Env variables exposed to client (NEXT_PUBLIC_*SECRET etc.)
+
+Skip: node_modules, test files, .env.example
+
+## Phase 2: OWASP Top 10
+
+### A01: Broken Access Control
+- API routes without auth middleware
+- Direct object references without ownership check
+- Missing role verification on admin routes
+- Overly permissive CORS (Access-Control-Allow-Origin: *)
+
+### A02: Cryptographic Failures
+- Hardcoded secrets in source code
+- Weak hashing (MD5, SHA1 for passwords)
+- Sensitive data in localStorage or console.log
+- Missing httpOnly/secure flags on cookies
+
+### A03: Injection
+- SQL concatenation without parameterization
+- eval() with user input
+- exec()/spawn() with user-controlled values
+
+### A04: Insecure Design
+- Login endpoints without rate limiting
+- File uploads without type/size validation
+- Missing CSRF protection
+
+### A05: Security Misconfiguration
+- Missing security headers (CSP, HSTS, X-Frame-Options)
+- Debug mode enabled
+- Error handlers exposing stack traces
+
+### A06: Vulnerable Components
+- npm audit findings (if package.json present)
+- Known CVE packages
+
+### A07: Auth Failures
+- Math.random() for tokens (not cryptographically secure)
+- Session IDs in URLs
+- Missing account lockout
+
+### A08: Data Integrity
+- Missing package-lock.json / yarn.lock
+
+### A09: Security Logging
+- No audit logging for auth failures
+- PII in logs
+
+### A10: SSRF
+- Server-side URL fetching with user-controlled URLs
+
+## Phase 3: Generate Report
+
+Write to `.buildflow/security/reports/audit-[date].md`:
+
+```
+# Security Audit Report
+
+## Summary
+🔴 Critical: X  🟡 High: Y  🟠 Medium: Z  🔵 Low: N
+
+Ship Recommendation: [Safe / Fix Critical First / Do Not Ship]
+
+## Critical Findings
+### [C1] [Issue] - [file:line]
+OWASP: [category]
+Risk: [what could happen]
+Fix: [concrete code change]
+
+## [Other severities...]
+
+## Positive Practices Found
+[What's done well]
+
+## Dependencies
+[CVE status]
+```
+
+## Phase 4: Update Memory
+```yaml
+last_audit_date: [today]
+critical_findings: X
+ship_safe: true/false
+```
+
+## Severity Definitions
+- 🔴 Critical: Direct path to breach, fix immediately
+- 🟡 High: Significant risk, fix this week
+- 🟠 Medium: Moderate risk, fix this sprint
+- 🔵 Low: Minor, fix when nearby
+
+## Token Budget
+- Full audit: ~30-40K
+- Quick audit: ~15K
+- Pre-ship: ~10K

package/templates/commands/back.md

@@ -0,0 +1,59 @@
+---
+name: buildflow-back
+description: Undo recent changes and restore to a safe state
+allowed-tools: Read, Write, Bash
+agent: strategist
+---
+
+# /buildflow-back
+
+Undo recent changes and restore to a known-good state.
+
+## Usage
+- `/buildflow-back` — undo last action
+- `/buildflow-back 3` — undo last 3 actions
+- `/buildflow-back --list` — show available restore points
+- `/buildflow-back phase-1-complete` — restore to named checkpoint
+
+## Step 1: List Restore Points
+
+Check available options in order:
+1. Git commits (most reliable)
+2. Named BuildFlow checkpoints in `.buildflow/phases/`
+3. Git stash entries
+
+Show numbered list with timestamps and descriptions.
+
+## Step 2: Confirm Intent
+Ask: "Which restore point do you want to go back to?"
+Show what will be LOST if they go back.
+
+## Step 3: Safety Check
+If there are uncommitted changes:
+```
+⚠️  You have uncommitted changes.
+    These will be lost: [list files]
+    Type "yes, discard changes" to continue.
+```
+
+## Step 4: Restore
+
+For git restore:
+```bash
+git reset --hard [commit-hash]
+```
+
+For named checkpoint:
+```bash
+git checkout [checkpoint-tag]
+```
+
+## Step 5: Update State
+Update `.buildflow/core/state.md` to reflect restored phase.
+Update `.buildflow/memory/light.md` to match.
+
+## Step 6: Confirm
+Show: "Restored to: [checkpoint name] from [date]"
+Suggest next action: "Run /buildflow-status to see current state."
+
+## Token Budget: ~3K

package/templates/commands/build.md

@@ -0,0 +1,61 @@
+---
+name: buildflow-build
+description: Execute the plan with parallel Builder agents
+allowed-tools: Read, Write, Bash
+agents: builder, reviewer
+---
+
+# /buildflow-build
+
+Execute the current phase plan. Spawns parallel Builder agents per wave, then Reviewer checks quality.
+
+## Usage
+- `/buildflow-build` — execute current phase plan
+- `/buildflow-build wave-2` — execute a specific wave
+- `/buildflow-build <task>` — build a single task
+
+## Step 1: Load Plan
+Read `.buildflow/phases/[N]/PLAN.md`.
+Load `.buildflow/memory/light.md` for style preferences.
+If existing project: load `.buildflow/codebase/PATTERNS.md`.
+
+## Step 2: Style Fingerprint
+Before writing 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:
+- Gets the task spec and relevant context files
+- Writes code matching 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:
+- Does it meet the task spec?
+- Does it match the codebase style?
+- Any security concerns?
+- Tests present if needed?
+
+## Step 5: Continue Waves
+Repeat for Wave 2, Wave 3, etc.
+Each wave waits for the previous to complete and pass review.
+
+## Step 6: Integration Check
+After all waves: verify the pieces connect correctly.
+Run existing tests if available.
+
+## Step 7: Update Memory
+```yaml
+last_build_date: [today]
+phase: [N]
+tasks_completed: [list]
+files_changed: [list]
+```
+
+## Token Budget: ~50K per wave (parallel)

package/templates/commands/check.md

@@ -0,0 +1,62 @@
+---
+name: buildflow-check
+description: Verify quality with parallel Reviewer agents
+allowed-tools: Read, Bash, Grep, Glob
+agent: reviewer
+---
+
+# /buildflow-check
+
+Quality verification. Parallel Reviewers check code against acceptance criteria.
+
+## Usage
+- `/buildflow-check` — check current phase
+- `/buildflow-check <file>` — check a specific file
+- `/buildflow-check tests` — verify test coverage
+- `/buildflow-check acceptance` — verify acceptance criteria only
+
+## Step 1: Load Acceptance Criteria
+Read `.buildflow/phases/[N]/PLAN.md` for definition of done.
+
+## Step 2: Parallel Review (3 reviewers)
+
+**Reviewer A — Correctness:**
+- Does the code do what was specified?
+- Are edge cases handled?
+- Are there logical errors?
+
+**Reviewer B — Quality:**
+- Is the code readable?
+- Are there unnecessary duplications?
+- Does it match `.buildflow/codebase/PATTERNS.md`?
+- Are functions appropriately sized?
+
+**Reviewer C — Security:**
+- No hardcoded secrets?
+- No obvious injection risks?
+- No sensitive data in logs?
+- Dependencies up to date?
+
+## Step 3: Test Check
+- Do existing tests pass?
+- Are new tests written for new code?
+- Is critical logic tested?
+
+## Step 4: Synthesize Findings
+
+Report format:
+```
+✓ PASS  — criterion
+⚠ WARN  — issue (non-blocking)
+✗ FAIL  — issue (must fix before /buildflow-ship)
+```
+
+## Step 5: Confidence Check
+Ask: "How confident are you in this code? (1-5)"
+
+## Step 6: Next Steps
+- All pass: "Ready for /buildflow-ship"
+- Warnings: "Warnings noted. Run /buildflow-ship or fix first."
+- Failures: "Fix these issues, then re-run /buildflow-check"
+
+## Token Budget: ~20K

package/templates/commands/explain.md

@@ -0,0 +1,53 @@
+---
+name: buildflow-explain
+description: Explain code, concepts, or terms in plain language
+allowed-tools: Read, WebSearch
+agent: strategist
+---
+
+# /buildflow-explain
+
+Plain-language explanations for code, concepts, jargon, or files.
+
+## Usage
+- `/buildflow-explain src/auth/middleware.ts`
+- `/buildflow-explain JWT`
+- `/buildflow-explain "What does this error mean: ECONNREFUSED"`
+- `/buildflow-explain "How does the payment flow work?"`
+
+## Step 1: Detect Type
+What is being explained?
+- **File/Code**: Read the file, explain what it does and why
+- **Term/Concept**: Define it in context of this project
+- **Error**: Diagnose the error and suggest fixes
+- **Flow**: Trace the data/control flow end-to-end
+
+## Step 2: Adapt to Experience Level
+Read `.buildflow/you/preferences.md` for experience level.
+- Junior: Use analogies, avoid jargon, explain the why
+- Senior: Be concise, assume fundamentals, focus on nuance
+- Unknown: Start at an intermediate level
+
+## Step 3: Explain
+
+**For files:**
+1. Purpose — what problem does this solve?
+2. How it works — key logic in plain English
+3. How it connects — what calls this, what does it call?
+4. Gotchas — anything non-obvious to watch out for
+
+**For concepts/terms:**
+1. One-sentence definition
+2. How it applies to THIS project
+3. Example in context
+4. Further reading (if helpful)
+
+**For errors:**
+1. What the error means
+2. Most likely cause in this codebase
+3. How to fix it
+
+## Step 4: Add to Glossary
+If explaining a new term, append to `.buildflow/learnings/glossary.md`.
+
+## Token Budget: ~2K

package/templates/commands/help.md

@@ -0,0 +1,84 @@
+---
+name: buildflow-help
+description: Diagnostic help and recovery guide
+allowed-tools: Read, Bash
+agent: strategist
+---
+
+# /buildflow-help
+
+Diagnostic mode. Use when stuck, confused, or when something isn't working.
+
+## Usage
+- `/buildflow-help` — general help and orientation
+- `/buildflow-help stuck` — help getting unstuck
+- `/buildflow-help reset` — reset BuildFlow state
+- `/buildflow-help <error message>` — diagnose a specific error
+
+## Step 1: Load Current State
+Read `.buildflow/core/state.md` and `.buildflow/memory/light.md`.
+Check if `.buildflow/` exists and is properly structured.
+
+## Step 2: Diagnose
+
+**If .buildflow/ is missing:**
+"BuildFlow isn't initialized here. Run: `npx buildflow-dev init`"
+
+**If state.md is corrupted:**
+Re-detect project and recreate state.md from scratch.
+
+**If stuck in a phase:**
+Show what the current phase plan says and where progress stopped.
+Suggest: continue from last completed task, or start over.
+
+**If error message provided:**
+Analyze the error:
+- Is it a BuildFlow config issue?
+- Is it a project code issue?
+- Is it an AI tool integration issue?
+
+## Step 3: Recovery Options
+
+Based on the situation, offer:
+1. **Continue** — pick up where you left off
+2. **Re-run** — redo the last command from scratch
+3. **Skip** — skip the problematic step with a note
+4. **Reset phase** — restart current phase from the beginning
+5. **Full reset** — clear `.buildflow/` and start fresh (asks for confirmation)
+
+## Step 4: All Commands Reference
+
+### Workflow (greenfield)
+- `/buildflow-start` — begin project
+- `/buildflow-think [topic]` — research and discuss
+- `/buildflow-plan [phase]` — create execution plan
+- `/buildflow-build [wave]` — execute the plan
+- `/buildflow-check` — verify quality
+- `/buildflow-ship` — finalize with security gate
+
+### Existing codebase
+- `/buildflow-onboard` — map codebase (one-time)
+- `/buildflow-modify "description"` — surgical code change
+- `/buildflow-refactor [scope]` — improve code quality
+
+### Security
+- `/buildflow-audit` — full OWASP scan
+- `/buildflow-audit --quick` — recent changes only
+- `/buildflow-audit --pre-ship` — lightweight pre-ship check
+
+### Utility
+- `/buildflow-status` — where am I?
+- `/buildflow-explain <term/file>` — get explanation
+- `/buildflow-back [n]` — undo recent changes
+- `/buildflow-help` — this command
+
+### CLI (terminal)
+```
+buildflow init
+buildflow install [--tool <name>]
+buildflow audit [--quick] [--target <path>]
+buildflow status [--verbose]
+buildflow update [--check]
+```
+
+## Token Budget: ~15K (full diagnostic)

package/templates/commands/modify.md

@@ -0,0 +1,65 @@
+---
+name: buildflow-modify
+description: Safely modify existing code with the Surgeon agent
+allowed-tools: Read, Write, Grep, Glob, Bash
+agent: surgeon
+---
+
+# /buildflow-modify
+
+Make precise, safe changes to existing code. The Surgeon agent minimizes blast radius.
+
+## Usage
+- `/buildflow-modify "Add dark mode toggle to settings page"`
+- `/buildflow-modify src/auth/login.ts "Add rate limiting"`
+- `/buildflow-modify --dry-run "Rename getUserById to fetchUserById"`
+
+## Step 1: Load Codebase Context
+Read `.buildflow/codebase/MAP.md` and `PATTERNS.md`.
+If not onboarded: "Run /buildflow-onboard first."
+
+## Step 2: Understand the Change
+Ask:
+1. What exactly needs to change?
+2. What should NOT change (blast radius constraints)?
+3. Are there tests that must keep passing?
+4. Confidence in understanding the request (1-5)?
+
+## Step 3: Impact Analysis
+Before touching any code:
+- List all files that will be modified
+- List all files that call or import changed code
+- Identify test files that cover this area
+- Flag any security-sensitive areas
+
+Show impact summary and ask for confirmation.
+
+## Step 4: Create Restore Point
+```bash
+git stash  # or commit current state
+# Log: "restore point before /buildflow-modify: [description]"
+```
+
+## Step 5: Surgical Modification
+Make changes with minimum footprint:
+- Change only what is necessary
+- Match existing code style exactly (from PATTERNS.md)
+- Add LEARN: comments for non-obvious changes
+- Do NOT refactor unrelated code
+
+## Step 6: Verify
+- Run existing tests
+- Check that unchanged code still works
+- Diff review: does it match the spec?
+
+## Step 7: Update Memory
+```yaml
+last_modify: [today]
+change: [brief description]
+files_changed: [list]
+```
+
+## --dry-run Flag
+Shows what WOULD change without modifying files.
+
+## Token Budget: ~30K