buildflow-dev 4.0.1 → 4.0.2

package/templates/commands/modify.md

@@ -1,65 +1,239 @@
 ---
 name: buildflow-modify
-description: Safely modify existing code with the Surgeon agent
+description: Surgical code change with transitive impact analysis, risk scoring, and test coverage verification
 allowed-tools: Read, Write, Grep, Glob, Bash
 agent: surgeon
 ---
 
 # /buildflow-modify
 
-Make precise, safe changes to existing code. The Surgeon agent minimizes blast radius.
+Precise, safe changes to existing code. The Surgeon runs a full transitive impact analysis — not just "what files change" but the full chain of consequences — scores risk per affected file, verifies test coverage, and applies the minimum effective change.
+
+Works for features and bugfixes equally.
 
 ## Usage
-- `/buildflow-modify "Add dark mode toggle to settings page"`
-- `/buildflow-modify src/auth/login.ts "Add rate limiting"`
+- `/buildflow-modify "Add rate limiting to /api/auth/login"`
+- `/buildflow-modify "Fix null pointer crash when user has no profile photo"`
+- `/buildflow-modify src/auth/login.ts "Add input validation"`
 - `/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."
+## Context Packet
+- `.buildflow/codebase/MAP.md`
+- `.buildflow/codebase/GRAPH.md` (import dependency graph — essential for impact analysis)
+- `.buildflow/codebase/HOTSPOTS.md`
+- `.buildflow/codebase/PATTERNS.md`
+- Target file(s) if named in command
+
+If not onboarded: "Run `/buildflow-onboard` first — impact analysis requires the dependency graph."
+
+---
+
+## Step 1: Understand the Change
+Parse the description. Identify:
+- **What** must change (behavior, data, interface)
+- **Where** the change originates (file, function, module)
+- **What must NOT change** (caller contracts, existing behavior outside scope)
+- Is this a feature (new capability) or a bugfix (restoring expected behavior)?
+
+If ambiguous: ask ONE clarifying question only.
+
+---
+
+## Step 2: Transitive Impact Analysis
+Using `GRAPH.md`, trace the full impact chain from the target file outward:
+
+```
+Level 0 — Direct change:
+  src/auth/login.ts  ← file being modified
+
+Level 1 — Direct dependents (imports Level 0):
+  src/routes/auth.routes.ts   fan-in to login.ts
+  src/tests/auth.test.ts      fan-in to login.ts
+
+Level 2 — Transitive dependents (imports Level 1):
+  src/app.ts                  imports auth.routes.ts
+  src/middleware/session.ts   imports auth.routes.ts
+
+Level 3 — Entry point:
+  main.ts                     imports app.ts
+```
+
+For each affected file, annotate:
+- **Risk score** (from HOTSPOTS.md, or calculate: fan-in + size + test coverage)
+- **Test coverage**: does a test file cover this file?
+- **Contract sensitivity**: does this file export a public API? If yes, callers may break.
+- **Module boundary**: does this change cross a module boundary?
+
+**Impact Summary:**
+```
+Impact Analysis: "Add rate limiting to /api/auth/login"
+────────────────────────────────────────────────────────
+Direct:
+  src/auth/login.ts            risk: 4.2  tests: YES  contract: INTERNAL
+
+Level 1 — will be affected:
+  src/routes/auth.routes.ts    risk: 3.1  tests: YES  contract: PUBLIC ← caller may need update
+  src/tests/auth.test.ts       risk: 1.0  tests: N/A  contract: NONE   ← will need new test case
+
+Level 2 — may be affected:
+  src/app.ts                   risk: 3.8  tests: partial  contract: ENTRY
+  src/middleware/session.ts    risk: 2.5  tests: YES      contract: INTERNAL ← verify no conflict
+
+Blast radius: 4 files modified, 1 file needing new test, 0 public API breaks expected
+Highest risk file touched: src/auth/login.ts (4.2)
+```
+
+If any Level 2+ file has risk ≥ 4.0: flag as "Caution — high-risk transitive impact. Consider splitting this change."
+
+---
+
+## Step 3: API Contract Check
+If the change modifies a function/method signature or REST endpoint:
+
+**Before (current contract):**
+```
+loginUser(email: string, password: string): Promise<AuthToken>
+POST /api/auth/login  →  { token: string, expiresAt: number }
+```
 
-## 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)?
+**After (new contract):**
+```
+loginUser(email: string, password: string, options?: RateLimitOptions): Promise<AuthToken>
+POST /api/auth/login  →  { token: string, expiresAt: number }  [+ 429 Too Many Requests]
+```
 
-## 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
+List all callers that pass through this contract and verify they still compile/run with the new signature. If any caller will break: add fixing those callers to the task list.
 
-Show impact summary and ask for confirmation.
+---
+
+## Step 4: Test Coverage Map
+For each file in the impact chain, verify:
+- Does a test file exist that imports or calls it?
+- Do those tests cover the behavior being changed?
+- After the change, which tests will need updating?
+
+```
+Test Coverage for this change:
+  login.ts        → src/tests/auth.test.ts (covers: login flow, invalid password)
+                    MISSING: rate limit behavior — must add
+  auth.routes.ts  → src/tests/routes.test.ts (covers: route registration)
+                    OK: no change needed
+  session.ts      → NO TESTS FOUND ← flag: untested file in impact chain
+```
 
-## Step 4: Create Restore Point
+Flag any untested file in the impact chain as a risk.
+
+---
+
+## Step 5: Confirmation
+Show the impact summary, contract change, and test coverage map. Ask:
+
+> "This change touches [N] files with blast radius [N]. Highest-risk: [file] ([score]).
+> Proceed, narrow scope, or investigate further?"
+
+Only proceed on explicit confirmation.
+
+---
+
+## Step 6: Restore Point
 ```bash
-git stash  # or commit current state
-# Log: "restore point before /buildflow-modify: [description]"
+git stash push -m "pre-modify: [description]"
+# or if nothing to stash:
+git tag "pre-modify-$(date +%Y%m%d-%H%M)"
 ```
 
-## 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 7: Surgical Implementation
+Make the minimum effective change:
+- Change only what the impact analysis identified
+- Follow existing code style (PATTERNS.md)
+- Add `LEARN:` comment ONLY if introducing a pattern not present elsewhere
+- Do NOT refactor, rename, or clean up surrounding code
+
+For each file modified: confirm it matches the Before → After contract.
+
+---
+
+## Step 7b: Write / Update Tests (mandatory — part of the change, not optional)
 
-## Step 6: Verify
-- Run existing tests
-- Check that unchanged code still works
-- Diff review: does it match the spec?
+### First: detect test framework (if not already known from onboarding)
+```bash
+# JS/TS
+cat package.json | grep -E "jest|vitest|mocha|jasmine|supertest"
+ls jest.config.* vitest.config.* 2>/dev/null
+find . -name "*.test.ts" -o -name "*.spec.ts" | head -3
+
+# Python
+cat requirements.txt pyproject.toml 2>/dev/null | grep pytest
+
+# Go: look for *_test.go files
+# Rust: look for #[cfg(test)] blocks
+```
 
-## Step 7: Update Memory
+| Framework status | Action |
+|-----------------|--------|
+| Found + test files exist | Follow existing conventions exactly |
+| Found + no test files yet | Use framework, create first test file |
+| Not found | Warn user: "No test framework detected. Tests skipped. Add [recommended framework] and re-run." Log gap to `security/DEBT.md`. |
+
+For each source file touched in Step 7:
+
+**If a test file already exists for this file:**
+- Open it
+- Add test cases for every function whose behavior changed
+- If the function's signature changed: update the callers in the test
+- If the bug was in a specific code path: add a regression test that names the exact scenario
+
+**If no test file exists:**
+- Create one following the project test convention (from PATTERNS.md):
+  - Co-located: `auth.service.ts` → `auth.service.test.ts`
+  - Or in test folder: match existing structure
+- Cover: each function touched in this change + the specific behavior the change introduces
+
+**For bugfixes specifically:**
+1. Write the regression test BEFORE applying the fix
+2. Run it — confirm it fails (proves the bug exists)
+3. Apply the fix
+4. Run again — confirm it passes (proves the fix works)
+5. Name the test after the exact bug: `should not return null when profile photo is missing`
+
+**Test coverage report after this step:**
+```
+Test changes for this modify
+─────────────────────────────
+auth.service.ts      → auth.service.test.ts   +3 cases (rate limit happy path, 429 response, reset after window)
+auth.routes.ts       → auth.routes.test.ts    +1 case (rate limit header present)
+session.ts           → session.test.ts        CREATED — 4 cases (was untested, now covered)
+```
+
+Do not proceed to Step 8 until every touched source file has corresponding test coverage.
+
+---
+
+## Step 8: Test + Verify
+Run full test suite. On failure: fix and retest (max 3 attempts).
+
+Also verify:
+- All files in the impact chain still compile
+- Callers of changed contracts still function
+- The regression test (for bugfixes) now passes
+- No previously passing tests were broken
+
+---
+
+## Step 9: Update Memory
 ```yaml
 last_modify: [today]
-change: [brief description]
-files_changed: [list]
+change: [description]
+files_changed: [N]
+impact_level: [direct/level1/level2]
 ```
 
+---
+
 ## --dry-run Flag
-Shows what WOULD change without modifying files.
+Runs Steps 1–5 only. Shows full impact analysis and contract changes without modifying any file.
+Use this before a risky change to understand blast radius first.
 
-## Token Budget: ~30K
+## Token Budget: ~30K (more if impact chain is deep)

package/templates/commands/onboard.md

@@ -1,78 +1,272 @@
 ---
 name: buildflow-onboard
-description: Analyze existing codebase and create knowledge maps
+description: Deep codebase analysis — import graph, module boundaries, load-bearing files, risk scores
 allowed-tools: Read, Bash, Glob, Grep
 agent: cartographer
 ---
 
 # /buildflow-onboard
 
-ONE-TIME analysis of your existing codebase. Creates knowledge maps for all other agents.
+Deep one-time analysis of an existing codebase. Goes beyond folder structure — maps import graphs, identifies load-bearing modules, scores file risk, and establishes module boundaries. All other agents reference these outputs.
 
 ## When to Run
-- First time using BuildFlow on existing project
-- After major refactor
-- After framework upgrade
-- Use --update flag to refresh incrementally
+- First time using BuildFlow on an existing project
+- After a major refactor or framework migration
+- `--update` flag for incremental refresh after significant changes
 
-## Step 1: Check Prior State
-If `.buildflow/codebase/MAP.md` exists, ask: "Re-onboard (full) or update (incremental)?"
+## Usage
+- `/buildflow-onboard` — full analysis
+- `/buildflow-onboard --update` — refresh changed files only
+- `/buildflow-onboard --depth imports` — focus on dependency graph only
+
+---
+
+## Step 1: Prior State Check
+If `.buildflow/codebase/MAP.md` exists:
+- `--update` flag: skip to Step 6 (incremental refresh)
+- Otherwise ask: "Full re-onboard or incremental update?"
+
+---
 
 ## Step 2: Structural Analysis
-- Read folder structure
-- Find entry points (package.json, main.py, Cargo.toml, go.mod)
-- Map src/ organization
-- Note configuration files
-
-## Step 3: Technology Detection
-Parse dependency files. Detect:
-- Language(s)
-- Framework(s)
-- Major libraries
-- Build tools
-- Test setup
-
-## Step 4: Pattern Recognition
-Read 5-10 representative source files. Document:
-- Component structure conventions
-- Naming patterns (PascalCase, camelCase, snake_case)
-- Import organization order
-- Comment style
-- Error handling approach
-- Test file conventions
-
-## Step 5: Complexity Assessment
-- Identify large files (>300 lines)
-- Find deeply nested code
-- Note files with many imports (high coupling)
-- Mark as HOTSPOTS for Surgeon agent
-
-## Step 6: Generate Knowledge Files
-
-Write these files:
+```bash
+# Entry points
+find . -name "main.*" -o -name "index.*" -o -name "app.*" | grep -v node_modules
+# File count by type
+find src/ -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
+```
+
+Map:
+- Entry points (where execution begins)
+- Top-level folder responsibilities (what each `src/` subdirectory owns)
+- Configuration files and what they control
+- Build/bundler setup
+
+---
+
+## Step 3: Technology & Dependency Detection
+Parse `package.json` / `requirements.txt` / `Cargo.toml` / `go.mod`. For each major dependency:
+- Purpose (what problem it solves)
+- Criticality: CORE (app breaks without) / UTIL (convenience) / DEV (build-time only)
+- Security status: check for known CVE patterns in version
+
+### Test Framework Detection (captured here so all agents can reuse it)
+```bash
+# JS/TS — check deps and config
+cat package.json | grep -E "jest|vitest|mocha|jasmine|@testing-library|supertest|cypress|playwright"
+ls jest.config.* vitest.config.* .mocharc.* 2>/dev/null
+find . -name "*.test.ts" -o -name "*.test.js" -o -name "*.spec.ts" -o -name "*.spec.js" | head -5
+find . -type d -name "__tests__" | head -3
+
+# Python
+cat requirements.txt pyproject.toml setup.cfg 2>/dev/null | grep -E "pytest|unittest|nose"
+find . -name "test_*.py" -o -name "*_test.py" | head -5
+
+# Go — test files use same package
+find . -name "*_test.go" | head -5
+
+# Rust — tests are inline
+grep -rn "#\[cfg(test)\]" src/ | head -5
+```
+
+Record the **Test Profile** in `PATTERNS.md` under a `## Testing` section:
+```
+Framework:     [Jest / Vitest / pytest / go test / cargo test / NONE]
+Config:        [jest.config.ts / vitest.config.ts / pytest.ini / N/A]
+Test location: [co-located *.test.ts / __tests__/ / tests/ / inline]
+Naming:        [describe/it / test() / def test_ / #[test]]
+Mock library:  [jest.mock / vi.mock / pytest fixtures / mockall / NONE]
+Coverage:      [jest --coverage / pytest-cov / go test -cover / NONE]
+Existing tests:[N files, N cases]
+Has tests:     [YES / NO — no framework detected]
+```
+
+If `Has tests: NO`: note in summary — "⚠ No test framework found. Tests cannot be written until one is installed."
+
+---
+
+## Step 4: Import Graph Analysis (repo awareness core)
+For each source file, trace its imports and exports:
+
+```bash
+# JS/TS: find all import statements
+grep -rn "^import\|^const.*require" src/ --include="*.ts" --include="*.js"
+# Python
+grep -rn "^import\|^from" src/ --include="*.py"
+```
+
+Build a dependency map:
+```
+file-a.ts  imports  [auth.service.ts, db.client.ts, types.ts]
+auth.service.ts  imports  [db.client.ts, crypto.ts, config.ts]
+db.client.ts  imports  [config.ts]
+```
+
+From this graph, calculate for each file:
+- **Fan-in** (how many files import THIS file) — high = load-bearing
+- **Fan-out** (how many files THIS file imports) — high = coupled
+- **Depth** (longest import chain to reach this file from entry point)
+
+---
+
+## Step 5: Load-Bearing Module Identification
+Files with fan-in ≥ 5 are **load-bearing** — changes ripple widely.
+
+```
+Load-Bearing Modules
+────────────────────
+db.client.ts     fan-in: 12   ← CRITICAL — 12 files depend on this
+auth.service.ts  fan-in: 8    ← HIGH
+config.ts        fan-in: 15   ← CRITICAL
+types.ts         fan-in: 20   ← CRITICAL (type-only, lower risk)
+```
+
+---
+
+## Step 6: Module Boundary Mapping
+Identify **bounded contexts** — groups of files that form a logical subsystem:
+
+```
+Module: Auth
+  Owns:  src/auth/*.ts
+  Exports: AuthService, AuthMiddleware, JWTUtil
+  Depends on: Database, Config
+  Depended on by: API routes, WebSocket handlers
+
+Module: Database
+  Owns:  src/db/*.ts
+  Exports: DBClient, QueryBuilder, Migrations
+  Depends on: Config
+  Depended on by: Auth, Users, Orders (everything)
+
+Module: API
+  Owns:  src/routes/*.ts
+  Exports: Router
+  Depends on: Auth, Users, Orders
+  Depended on by: main.ts (entry point only)
+```
+
+Flag **boundary violations**: files that import across module lines without going through the module's public export.
+
+---
+
+## Step 7: Pattern Recognition
+Read 2–3 representative files per module. Document:
+- Component/class structure conventions
+- Naming patterns (PascalCase, camelCase, snake_case, kebab-case)
+- Import organization order (stdlib → 3rd party → internal)
+- Error handling approach (throw vs return, error types used)
+- Async pattern (async/await, Promise chains, callbacks)
+- Test file conventions (co-located vs `__tests__/`, naming)
+- Comment style (JSDoc, inline, none)
+
+---
+
+## Step 8: Risk Scoring
+Score each file on a 1–5 risk scale:
+
+| Factor | Low (1) | High (5) |
+|--------|---------|---------|
+| Fan-in | 0–1 dependents | 10+ dependents |
+| File size | < 100 lines | > 500 lines |
+| Test coverage | Tests exist | No tests found |
+| Complexity | Simple logic | Deep nesting, many branches |
+| Change frequency | Rarely changed | Frequently changed |
+
+Final risk score = average of applicable factors.
+
+```
+File Risk Map
+─────────────
+db.client.ts      risk: 4.8  ← touch with extreme care
+auth.service.ts   risk: 4.2  ← high-impact changes
+config.ts         risk: 4.0  ← high fan-in, usually stable
+UserController.ts risk: 2.1  ← isolated, well-tested
+utils/format.ts   risk: 1.0  ← pure functions, low coupling
+```
+
+---
+
+## Step 9: Write Knowledge Files
 
 ### `.buildflow/codebase/MAP.md`
-Architecture overview, folder structure, entry points, key patterns, top dependencies.
+```markdown
+# Codebase Map
+**Project:** [name]  **Onboarded:** [date]  **Files analyzed:** [N]
+
+## Entry Points
+- [file]: [purpose]
+
+## Module Boundaries
+[module table from Step 6]
+
+## Load-Bearing Modules
+[critical file list from Step 5]
+
+## Folder Structure
+[annotated tree — one line per folder explaining its role]
+
+## Key Patterns
+- [pattern name]: [brief description]
+```
+
+### `.buildflow/codebase/GRAPH.md`
+Full import dependency graph output from Step 4.
+Includes fan-in / fan-out counts per file.
+This is what impact analysis reads during `/buildflow-modify`.
 
 ### `.buildflow/codebase/PATTERNS.md`
-Code conventions: naming, component structure, imports, comments, error handling, testing.
+All conventions from Step 7. Used by Builder and Surgeon agents to match style.
+Each pattern has an example extracted from the actual codebase.
 
 ### `.buildflow/codebase/DEPENDENCIES.md`
-Top 10-15 dependencies with purpose, criticality, and security status.
+All dependencies from Step 3 with purpose, criticality, and security status.
 
 ### `.buildflow/codebase/HOTSPOTS.md`
-Files to handle carefully: high complexity, frequently changed, low test coverage.
+```markdown
+# Hotspots — Handle With Care
+Files scored 3.5+ risk. Review before any modification.
+
+| File | Risk | Fan-in | Size | Tests | Notes |
+|------|------|--------|------|-------|-------|
+| db.client.ts | 4.8 | 12 | 380L | partial | Central DB abstraction |
+```
+
+---
 
-## Step 7: Update Memory
+## Step 10: Update Memory
 ```yaml
-.buildflow/memory/light.md:
-  onboarded: true
-  onboarded_date: [today]
-  codebase_summary: [3-line summary]
+onboarded: true
+onboarded_date: [today]
+file_count: [N]
+module_count: [N]
+load_bearing_files: [N]
+hotspot_count: [N]
+codebase_summary: [2-line summary]
 ```
 
-## Step 8: Summary
-Show: framework, file count, test coverage estimate, complexity summary.
-Suggest: /buildflow-modify, /buildflow-refactor, or /buildflow-think.
+---
+
+## Step 11: Onboarding Summary
+Report:
+```
+Onboarding Complete
+───────────────────
+Files analyzed:      [N]
+Modules identified:  [N]
+Load-bearing files:  [N]  (fan-in ≥ 5)
+High-risk hotspots:  [N]  (risk score ≥ 3.5)
+Boundary violations: [N]  (files importing across module lines)
+Test coverage est.:  [N]% (files with co-located tests)
+Patterns captured:   [N]
+
+⚠ Caution zones: [top 3 highest-risk files]
+✓ Safe to modify:  [modules with low risk scores]
+
+Next steps:
+  /buildflow-modify  — make targeted changes
+  /buildflow-spec    — define a new phase
+  /buildflow-refactor — improve code quality
+```
 
-## Token Budget: 30-40K (one-time cost, pays back immediately)
+## Token Budget: ~40K (one-time — pays back on every subsequent session)