flow-cc 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-02-11
+
+### Added
+- `/flow:setup` command — replaces `/flow:init` for project scaffolding only. Adds overwrite protection (stops if project already initialized).
+- `/flow:milestone` command — extracted from `/flow:init` for milestone transitions. Adds guard for pending phases before archiving.
+- Codebase scan exclusions in `/flow:spec` — explicitly excludes `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`. Uses targeted glob patterns instead of bare `**/*`.
+- Minimum viable PRD check in `/flow:spec` — validates at least 3 user stories, 1 phase, and 1 verification command before finalizing.
+- Agent timeout + progress indicators in `/flow:go` — prints wave spawn/completion status, checks stuck agents after 10 minutes.
+- Max retry limit (3 attempts) for verification in `/flow:go` — stops after 3 failures with user options instead of looping forever.
+- Wave failure handling in `/flow:go` — detects all-failed vs partial-failed waves, asks user how to proceed.
+
+### Changed
+- `/flow:init` split into `/flow:setup` (project scaffolding) and `/flow:milestone` (milestone transitions)
+- Skill count: 9 skills (was 8 — setup replaces init, milestone is new)
+- All cross-references updated: intro, done, status, go, task, README, install.js, DESIGN.md, templates
+
+### Removed
+- `/flow:init` command — replaced by `/flow:setup` and `/flow:milestone`
+
+## [0.2.0] - 2026-02-11
+
+### Added
+- `CHANGELOG.md` in Keep a Changelog format
+- `CONTRIBUTING.md` with skill file format docs and testing expectations
+- Example lesson in `templates/lessons.md.template` showing PATTERN/CAUSE/FIX/RULE format
+- Node.js version check (requires >= 18) with clear error message
+- Write permission check before install starts
+- Rollback on install failure — tracks created files and cleans up
+- Post-install verification — checks key files exist after copy
+- `--verify` flag for install health check without modifying anything
+- `engines` field in package.json (`node >= 18`)
+- Error logging for hooks — writes to `~/.claude/hooks/flow-error.log` (capped at 50KB)
+- Context size limits in `/flow:spec` — caps codebase scan at 50 files, focused mode for 500+ file repos
+
+### Fixed
+- `.gitignore` now has proper Node.js entries (was just `nul`)
+- `/flow:done` archive step now creates `.planning/archive/` if missing and skips gracefully when no `.planning/` exists
+- `/flow:update` now shows changelog for the new version before confirming update
+
+## [0.1.1] - 2025-05-01
+
+### Changed
+- Updated package.json metadata (description, keywords, repository links)
+- Polished README with badges and install instructions
+- Added MIT license file
+
+## [0.1.0] - 2025-05-01
+
+### Added
+- Initial release of Flow plugin for Claude Code
+- 8 skills: init, spec, go, done, status, task, intro, update
+- 2 hooks: statusline display, background update checker
+- 4 templates: CLAUDE.md, STATE.md, ROADMAP.md, lessons.md
+- One-command installer via `npx flow-cc`
+- Automatic statusLine configuration
+- Uninstall support via `npx flow-cc --uninstall`

package/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to Flow
+
+Thanks for your interest in contributing! Flow is a structured workflow system for Claude Code, and contributions are welcome.
+
+## Reporting Bugs
+
+Open an issue at [github.com/troyhoffman-oss/flow-plugin/issues](https://github.com/troyhoffman-oss/flow-plugin/issues) with:
+
+- Steps to reproduce
+- Expected vs. actual behavior
+- Your OS and Node.js version
+- Claude Code version (if relevant)
+
+## Suggesting Features
+
+Open an issue with the `enhancement` label. Describe:
+
+- The problem you're trying to solve
+- Your proposed solution
+- Any alternatives you've considered
+
+## Submitting Pull Requests
+
+1. Fork the repo and create a branch from `master`
+2. Make your changes
+3. Test the installer: `node bin/install.js` from the repo root
+4. Verify skills load in Claude Code (run `/flow:intro`)
+5. Open a PR with a clear description of what changed and why
+
+### Skill File Format
+
+Skills live in `skills/` as Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: flow:example
+description: One-line description
+user_invocable: true
+---
+
+# /flow:example — Title
+
+Instructions for Claude Code to follow when this skill is invoked.
+```
+
+### Testing Expectations
+
+- Run `node bin/install.js` and verify all files land in `~/.claude/`
+- Run `node bin/install.js --uninstall` and verify clean removal
+- Run `node bin/install.js --verify` to check install health
+- Test on both Windows and macOS/Linux if possible
+
+## Architecture
+
+See [DESIGN.md](DESIGN.md) for architecture decisions and system design.
+
+## Code of Conduct
+
+Be kind, constructive, and respectful. We're all here to build better tools.

package/README.md

@@ -35,7 +35,8 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 | Command | What it does |
 |---|---|
 | `/flow:intro` | Walkthrough of the system — **start here** |
-| `/flow:init` | Initialize a project with `.planning/` scaffolding, CLAUDE.md, templates |
+| `/flow:setup` | Set up a new project with `.planning/` scaffolding, CLAUDE.md, templates |
+| `/flow:milestone` | Archive completed milestone and start a new one |
 | `/flow:spec` | Spec interview that produces an executable PRD with phased execution plan |
 | `/flow:go` | Execute the next phase from the PRD using wave-based agent teams |
 | `/flow:task` | Bug fixes, cleanup, small features — no PRD needed |
@@ -46,16 +47,18 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 ## How It Works
 
 ```
-/flow:init → /flow:spec → /flow:go (repeat per phase) → /flow:done
-                                                            ↓
-                                              handoff prompt for next session
+/flow:setup → /flow:spec → /flow:go (repeat per phase) → /flow:done
+                                                             ↓
+                                               handoff prompt for next session
+                                                             ↓
+                                               /flow:milestone → next cycle
 
 /flow:task  ← standalone path for bug fixes and small features
 ```
 
 **The lifecycle in practice:**
 
-1. **`/flow:init`** — Creates `.planning/` directory, CLAUDE.md, STATE.md, ROADMAP.md, lessons.md
+1. **`/flow:setup`** — Creates `.planning/` directory, CLAUDE.md, STATE.md, ROADMAP.md, lessons.md
 2. **`/flow:spec`** — Interviews you about the milestone. Produces a PRD with wave-based phases, acceptance criteria, and agent-team structure
 3. **`/flow:go`** — Reads the PRD, spawns parallel agent teams per wave, builds, verifies, commits
 4. **`/flow:done`** — Updates all planning docs, captures lessons, generates a one-line handoff prompt so the next session starts instantly
@@ -66,7 +69,8 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 ```
 ~/.claude/
 ├── commands/flow/
-│   ├── flow-init.md          # 8 skill files
+│   ├── flow-setup.md         # 9 skill files
+│   ├── flow-milestone.md
 │   ├── flow-spec.md
 │   ├── flow-go.md
 │   ├── flow-task.md
@@ -88,7 +92,7 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 
 ## Project Structure
 
-Every Flow project gets this structure via `/flow:init`:
+Every Flow project gets this structure via `/flow:setup`:
 
 ```
 your-project/
@@ -121,6 +125,12 @@ Flow uses the same `.planning/` directory structure as [GSD](https://github.com/
 
 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI with skills support.
 
+## Links
+
+- [Changelog](CHANGELOG.md) — what changed in each version
+- [Contributing](CONTRIBUTING.md) — how to report bugs, suggest features, submit PRs
+- [Design](DESIGN.md) — architecture decisions and system design
+
 ## License
 
 MIT

package/VERSION

@@ -1 +1 @@
-0.1.1
+0.3.0

package/bin/install.js

@@ -1,11 +1,18 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // Flow plugin installer for Claude Code
-// Usage: npx flow-cc [--uninstall]
+// Usage: npx flow-cc [--uninstall] [--verify]
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+// ---------- Node.js version check ----------
+const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeMajor < 18) {
+  console.error('Flow requires Node.js 18 or later. You have ' + process.version);
+  process.exit(1);
+}
+
 const homeDir = os.homedir();
 const claudeDir = path.join(homeDir, '.claude');
 const commandsDir = path.join(claudeDir, 'commands', 'flow');
@@ -21,6 +28,93 @@ const templatesDir = path.join(pkgRoot, 'templates');
 const versionFile = path.join(pkgRoot, 'VERSION');
 
 const uninstall = process.argv.includes('--uninstall') || process.argv.includes('-u');
+const verify = process.argv.includes('--verify') || process.argv.includes('-v');
+
+// ---------- Verify ----------
+if (verify) {
+  console.log('Flow install health check:\n');
+
+  let passed = 0;
+  const total = 5;
+
+  // 1. Skills installed
+  try {
+    const files = fs.existsSync(commandsDir)
+      ? fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'))
+      : [];
+    if (files.length > 0) {
+      console.log(`  \u2713 Skills installed (${files.length} files)`);
+      passed++;
+    } else {
+      console.log('  \u2717 Skills not installed (0 .md files in commands/flow/)');
+    }
+  } catch (e) {
+    console.log('  \u2717 Skills not installed (cannot read commands/flow/)');
+  }
+
+  // 2. Hooks installed
+  try {
+    const hookFiles = ['flow-check-update.js', 'flow-statusline.js'];
+    const found = hookFiles.filter(h => fs.existsSync(path.join(hooksDir, h)));
+    if (found.length === 2) {
+      console.log('  \u2713 Hooks installed (2 files)');
+      passed++;
+    } else {
+      console.log(`  \u2717 Hooks incomplete (${found.length}/2 files)`);
+    }
+  } catch (e) {
+    console.log('  \u2717 Hooks not installed');
+  }
+
+  // 3. VERSION file
+  try {
+    const vPath = path.join(commandsDir, 'VERSION');
+    if (fs.existsSync(vPath)) {
+      const ver = fs.readFileSync(vPath, 'utf8').trim();
+      console.log(`  \u2713 VERSION file present (${ver})`);
+      passed++;
+    } else {
+      console.log('  \u2717 VERSION file missing');
+    }
+  } catch (e) {
+    console.log('  \u2717 VERSION file missing');
+  }
+
+  // 4. Templates installed
+  try {
+    const tDir = path.join(commandsDir, 'templates');
+    const files = fs.existsSync(tDir) ? fs.readdirSync(tDir) : [];
+    if (files.length > 0) {
+      console.log(`  \u2713 Templates installed (${files.length} files)`);
+      passed++;
+    } else {
+      console.log('  \u2717 Templates not installed (0 files)');
+    }
+  } catch (e) {
+    console.log('  \u2717 Templates not installed');
+  }
+
+  // 5. StatusLine configured
+  try {
+    if (fs.existsSync(settingsPath)) {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (settings.statusLine && typeof settings.statusLine.command === 'string' &&
+          settings.statusLine.command.includes('flow-statusline')) {
+        console.log('  \u2713 StatusLine configured');
+        passed++;
+      } else {
+        console.log('  \u2717 StatusLine not configured');
+      }
+    } else {
+      console.log('  \u2717 StatusLine not configured (no settings.json)');
+    }
+  } catch (e) {
+    console.log('  \u2717 StatusLine not configured');
+  }
+
+  console.log(`\nResult: ${passed}/${total} checks passed`);
+  process.exit(passed === total ? 0 : 1);
+}
 
 // ---------- Uninstall ----------
 if (uninstall) {
@@ -60,7 +154,7 @@ if (uninstall) {
         console.log('  Removed statusLine from ~/.claude/settings.json');
       }
     } catch (e) {
-      // settings.json parse error — leave it alone
+      // settings.json parse error -- leave it alone
     }
   }
 
@@ -71,79 +165,176 @@ if (uninstall) {
 // ---------- Install ----------
 console.log('Installing Flow plugin...\n');
 
-// 1. Create directories
-for (const dir of [commandsDir, hooksDir, cacheDir]) {
-  fs.mkdirSync(dir, { recursive: true });
+// ---------- Write permission check ----------
+const permTestDir = fs.existsSync(claudeDir) ? claudeDir : path.dirname(claudeDir);
+const permTestFile = path.join(permTestDir, '.flow-perm-test-' + process.pid);
+try {
+  fs.writeFileSync(permTestFile, 'test');
+  fs.unlinkSync(permTestFile);
+} catch (e) {
+  console.error('Cannot write to ' + claudeDir + ' \u2014 check permissions.');
+  process.exit(1);
 }
 
-// 2. Copy skills: skills/flow-*.md → commands/flow/*.md (strip "flow-" prefix)
-const skillFiles = fs.readdirSync(skillsDir).filter(f => f.startsWith('flow-') && f.endsWith('.md'));
-for (const file of skillFiles) {
-  const dest = file.replace(/^flow-/, '');
-  fs.copyFileSync(path.join(skillsDir, file), path.join(commandsDir, dest));
+// ---------- Rollback tracking ----------
+const created = []; // paths created during install (files and dirs we created fresh)
+
+function trackFile(filePath) {
+  created.push({ type: 'file', path: filePath });
 }
-console.log(`  Installed ${skillFiles.length} skills → ~/.claude/commands/flow/`);
 
-// 3. Copy hooks
-const hookFiles = ['flow-check-update.js', 'flow-statusline.js'];
-for (const hook of hookFiles) {
-  const src = path.join(srcHooksDir, hook);
-  if (fs.existsSync(src)) {
-    fs.copyFileSync(src, path.join(hooksDir, hook));
+function trackDir(dirPath) {
+  // Only track if we actually created it (didn't exist before)
+  if (!fs.existsSync(dirPath)) {
+    created.push({ type: 'dir', path: dirPath });
   }
 }
-console.log('  Installed hooks → ~/.claude/hooks/');
 
-// 4. Copy VERSION
-fs.copyFileSync(versionFile, path.join(commandsDir, 'VERSION'));
-console.log('  Installed VERSION → ~/.claude/commands/flow/VERSION');
-
-// 5. Copy templates
-const destTemplatesDir = path.join(commandsDir, 'templates');
-fs.mkdirSync(destTemplatesDir, { recursive: true });
-if (fs.existsSync(templatesDir)) {
-  const templateFiles = fs.readdirSync(templatesDir);
-  for (const file of templateFiles) {
-    fs.copyFileSync(path.join(templatesDir, file), path.join(destTemplatesDir, file));
+function rollback() {
+  console.error('\nRolling back partial install...');
+  for (let i = created.length - 1; i >= 0; i--) {
+    const item = created[i];
+    try {
+      if (item.type === 'file' && fs.existsSync(item.path)) {
+        fs.unlinkSync(item.path);
+      } else if (item.type === 'dir' && fs.existsSync(item.path)) {
+        fs.rmSync(item.path, { recursive: true });
+      }
+    } catch (e) {
+      // Best-effort cleanup
+    }
   }
-  console.log(`  Installed ${templateFiles.length} templates → ~/.claude/commands/flow/templates/`);
+  console.error('Rollback complete.');
 }
 
-// 6. Merge statusLine into settings.json
-let settings = {};
-if (fs.existsSync(settingsPath)) {
-  try {
-    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-  } catch (e) {
-    // Corrupted settings — start fresh but warn
-    console.log('  Warning: could not parse existing settings.json, preserving as backup');
-    fs.copyFileSync(settingsPath, settingsPath + '.bak');
+try {
+  // 1. Create directories
+  for (const dir of [commandsDir, hooksDir, cacheDir]) {
+    trackDir(dir);
+    fs.mkdirSync(dir, { recursive: true });
   }
-}
-settings.statusLine = {
-  type: 'command',
-  command: `node "${path.join(hooksDir, 'flow-statusline.js')}"`
-};
-fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-console.log('  Configured statusLine in ~/.claude/settings.json');
-
-// 7. Write .source breadcrumb (for dev/setup.sh compat)
-fs.writeFileSync(path.join(commandsDir, '.source'), pkgRoot + '\n');
-
-// Done
-const version = fs.readFileSync(versionFile, 'utf8').trim();
-console.log(`
+
+  // 2. Copy skills: skills/flow-*.md -> commands/flow/*.md (strip "flow-" prefix)
+  const skillFiles = fs.readdirSync(skillsDir).filter(f => f.startsWith('flow-') && f.endsWith('.md'));
+  for (const file of skillFiles) {
+    const dest = file.replace(/^flow-/, '');
+    const destPath = path.join(commandsDir, dest);
+    fs.copyFileSync(path.join(skillsDir, file), destPath);
+    trackFile(destPath);
+  }
+  console.log(`  Installed ${skillFiles.length} skills \u2192 ~/.claude/commands/flow/`);
+
+  // 3. Copy hooks
+  const hookFiles = ['flow-check-update.js', 'flow-statusline.js'];
+  for (const hook of hookFiles) {
+    const src = path.join(srcHooksDir, hook);
+    if (fs.existsSync(src)) {
+      const destPath = path.join(hooksDir, hook);
+      fs.copyFileSync(src, destPath);
+      trackFile(destPath);
+    }
+  }
+  console.log('  Installed hooks \u2192 ~/.claude/hooks/');
+
+  // 4. Copy VERSION
+  const versionDest = path.join(commandsDir, 'VERSION');
+  fs.copyFileSync(versionFile, versionDest);
+  trackFile(versionDest);
+  console.log('  Installed VERSION \u2192 ~/.claude/commands/flow/VERSION');
+
+  // 5. Copy templates
+  const destTemplatesDir = path.join(commandsDir, 'templates');
+  trackDir(destTemplatesDir);
+  fs.mkdirSync(destTemplatesDir, { recursive: true });
+  if (fs.existsSync(templatesDir)) {
+    const templateFiles = fs.readdirSync(templatesDir);
+    for (const file of templateFiles) {
+      const destPath = path.join(destTemplatesDir, file);
+      fs.copyFileSync(path.join(templatesDir, file), destPath);
+      trackFile(destPath);
+    }
+    console.log(`  Installed ${templateFiles.length} templates \u2192 ~/.claude/commands/flow/templates/`);
+  }
+
+  // 6. Merge statusLine into settings.json
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      // Corrupted settings -- start fresh but warn
+      console.log('  Warning: could not parse existing settings.json, preserving as backup');
+      fs.copyFileSync(settingsPath, settingsPath + '.bak');
+    }
+  }
+  settings.statusLine = {
+    type: 'command',
+    command: `node "${path.join(hooksDir, 'flow-statusline.js')}"`
+  };
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  trackFile(settingsPath);
+  console.log('  Configured statusLine in ~/.claude/settings.json');
+
+  // 7. Write .source breadcrumb (for dev/setup.sh compat)
+  const sourcePath = path.join(commandsDir, '.source');
+  fs.writeFileSync(sourcePath, pkgRoot + '\n');
+  trackFile(sourcePath);
+
+  // ---------- Post-install verification ----------
+  let warnings = 0;
+
+  // Check: at least 1 file in commandsDir
+  const installedSkills = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+  if (installedSkills.length === 0) {
+    console.log('  Warning: no skill files found in commands/flow/');
+    warnings++;
+  }
+
+  // Check: both hook files
+  const installedHooks = hookFiles.filter(h => fs.existsSync(path.join(hooksDir, h)));
+  if (installedHooks.length < 2) {
+    console.log(`  Warning: only ${installedHooks.length}/2 hook files installed`);
+    warnings++;
+  }
+
+  // Check: VERSION file
+  if (!fs.existsSync(path.join(commandsDir, 'VERSION'))) {
+    console.log('  Warning: VERSION file not found after install');
+    warnings++;
+  }
+
+  // Check: templates directory with at least 1 file
+  const tplDir = path.join(commandsDir, 'templates');
+  const tplFiles = fs.existsSync(tplDir) ? fs.readdirSync(tplDir) : [];
+  if (tplFiles.length === 0) {
+    console.log('  Warning: no template files found after install');
+    warnings++;
+  }
+
+  if (warnings > 0) {
+    console.log(`  (${warnings} verification warning${warnings > 1 ? 's' : ''} — install may be incomplete)`);
+  }
+
+  // Done
+  const version = fs.readFileSync(versionFile, 'utf8').trim();
+  console.log(`
 Flow v${version} installed successfully!
 
 Commands available:
-  /flow:intro   — Learn the Flow workflow
-  /flow:init    — Start a new project or milestone
-  /flow:spec    — Spec interview → executable PRD
-  /flow:go      — Execute next phase with agent teams
-  /flow:done    — Session-end documentation
-  /flow:status  — Quick orientation
-  /flow:task    — Lightweight task execution
-  /flow:update  — Update Flow to latest version
+  /flow:intro      \u2014 Learn the Flow workflow
+  /flow:setup      \u2014 Set up a new project
+  /flow:milestone  \u2014 Start a new milestone
+  /flow:spec       \u2014 Spec interview \u2192 executable PRD
+  /flow:go         \u2014 Execute next phase with agent teams
+  /flow:done       \u2014 Session-end documentation
+  /flow:status     \u2014 Quick orientation
+  /flow:task       \u2014 Lightweight task execution
+  /flow:update     \u2014 Update Flow to latest version
 
 Get started: run /flow:intro in any Claude Code session.
 `);
+} catch (err) {
+  rollback();
+  console.error('\nInstall failed: ' + err.message);
+  process.exit(1);
+}

package/hooks/flow-check-update.js

@@ -11,43 +11,90 @@ const homeDir = os.homedir();
 const cacheDir = path.join(homeDir, '.claude', 'cache');
 const cacheFile = path.join(cacheDir, 'flow-update-check.json');
 const versionFile = path.join(homeDir, '.claude', 'commands', 'flow', 'VERSION');
+const errorLog = path.join(homeDir, '.claude', 'hooks', 'flow-error.log');
 
-// Ensure cache directory exists
-if (!fs.existsSync(cacheDir)) {
-  fs.mkdirSync(cacheDir, { recursive: true });
+function logError(context, err) {
+  try {
+    const line = `[${new Date().toISOString()}] flow-check-update: ${context}: ${err.message || err}\n`;
+    // Cap log at 50KB — truncate oldest entries
+    if (fs.existsSync(errorLog)) {
+      const stat = fs.statSync(errorLog);
+      if (stat.size > 50 * 1024) {
+        const content = fs.readFileSync(errorLog, 'utf8');
+        const lines = content.split('\n');
+        fs.writeFileSync(errorLog, lines.slice(Math.floor(lines.length / 2)).join('\n'));
+      }
+    }
+    fs.appendFileSync(errorLog, line);
+  } catch (_) {
+    // Logging must never throw
+  }
 }
 
-// Run check in background (spawn detached process, windowsHide prevents console flash)
-const child = spawn(process.execPath, ['-e', `
-  const fs = require('fs');
-  const { execSync } = require('child_process');
+try {
+  // Ensure cache directory exists
+  if (!fs.existsSync(cacheDir)) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  }
 
-  const cacheFile = ${JSON.stringify(cacheFile)};
-  const versionFile = ${JSON.stringify(versionFile)};
+  // Run check in background (spawn detached process, windowsHide prevents console flash)
+  const child = spawn(process.execPath, ['-e', `
+    const fs = require('fs');
+    const { execSync } = require('child_process');
 
-  let installed = '0.0.0';
-  try {
-    if (fs.existsSync(versionFile)) {
-      installed = fs.readFileSync(versionFile, 'utf8').trim();
+    const cacheFile = ${JSON.stringify(cacheFile)};
+    const versionFile = ${JSON.stringify(versionFile)};
+    const errorLog = ${JSON.stringify(errorLog)};
+
+    function logError(context, err) {
+      try {
+        const line = '[' + new Date().toISOString() + '] flow-check-update(child): ' + context + ': ' + (err.message || err) + '\\n';
+        if (fs.existsSync(errorLog)) {
+          const stat = fs.statSync(errorLog);
+          if (stat.size > 50 * 1024) {
+            const content = fs.readFileSync(errorLog, 'utf8');
+            const lines = content.split('\\n');
+            fs.writeFileSync(errorLog, lines.slice(Math.floor(lines.length / 2)).join('\\n'));
+          }
+        }
+        fs.appendFileSync(errorLog, line);
+      } catch (_) {}
     }
-  } catch (e) {}
 
-  let latest = null;
-  try {
-    latest = execSync('npm view flow-cc version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
-  } catch (e) {}
-
-  const result = {
-    update_available: latest && installed !== latest,
-    installed,
-    latest: latest || 'unknown',
-    checked: Math.floor(Date.now() / 1000)
-  };
-
-  fs.writeFileSync(cacheFile, JSON.stringify(result));
-`], {
-  stdio: 'ignore',
-  windowsHide: true
-});
-
-child.unref();
+    try {
+      let installed = '0.0.0';
+      try {
+        if (fs.existsSync(versionFile)) {
+          installed = fs.readFileSync(versionFile, 'utf8').trim();
+        }
+      } catch (e) {
+        logError('read-version', e);
+      }
+
+      let latest = null;
+      try {
+        latest = execSync('npm view flow-cc version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+      } catch (e) {
+        logError('npm-view', e);
+      }
+
+      const result = {
+        update_available: latest && installed !== latest,
+        installed,
+        latest: latest || 'unknown',
+        checked: Math.floor(Date.now() / 1000)
+      };
+
+      fs.writeFileSync(cacheFile, JSON.stringify(result));
+    } catch (e) {
+      logError('main', e);
+    }
+  `], {
+    stdio: 'ignore',
+    windowsHide: true
+  });
+
+  child.unref();
+} catch (e) {
+  logError('spawn', e);
+}

package/hooks/flow-statusline.js

@@ -7,6 +7,25 @@ const path = require('path');
 const os = require('os');
 
 const homeDir = os.homedir();
+const errorLog = path.join(homeDir, '.claude', 'hooks', 'flow-error.log');
+
+function logError(context, err) {
+  try {
+    const line = `[${new Date().toISOString()}] flow-statusline: ${context}: ${err.message || err}\n`;
+    // Cap log at 50KB — truncate oldest entries
+    if (fs.existsSync(errorLog)) {
+      const stat = fs.statSync(errorLog);
+      if (stat.size > 50 * 1024) {
+        const content = fs.readFileSync(errorLog, 'utf8');
+        const lines = content.split('\n');
+        fs.writeFileSync(errorLog, lines.slice(Math.floor(lines.length / 2)).join('\n'));
+      }
+    }
+    fs.appendFileSync(errorLog, line);
+  } catch (_) {
+    // Logging must never throw
+  }
+}
 
 // Read JSON from stdin (Claude Code statusline protocol)
 let input = '';
@@ -56,9 +75,13 @@ process.stdin.on('end', () => {
             const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
             const inProgress = todos.find(t => t.status === 'in_progress');
             if (inProgress) task = inProgress.activeForm || '';
-          } catch (e) {}
+          } catch (e) {
+            logError('parse-todos', e);
+          }
         }
-      } catch (e) {}
+      } catch (e) {
+        logError('read-todos', e);
+      }
     }
 
     // --- Flow update notification ---
@@ -78,6 +101,7 @@ process.stdin.on('end', () => {
           shouldCheck = true;
         }
       } catch (e) {
+        logError('parse-cache', e);
         shouldCheck = true;
       }
     } else {
@@ -96,7 +120,9 @@ process.stdin.on('end', () => {
           });
           child.unref();
         }
-      } catch (e) {}
+      } catch (e) {
+        logError('spawn-update-check', e);
+      }
     }
 
     // --- Output ---
@@ -107,6 +133,7 @@ process.stdin.on('end', () => {
       process.stdout.write(`${flowUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
     }
   } catch (e) {
+    logError('main', e);
     // Silent fail — statusline must never crash
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Structured workflow system for Claude Code — spec interviews, agent-team execution, session handoffs, compounding knowledge",
   "author": "Troy Hoffman",
   "license": "MIT",
@@ -25,11 +25,16 @@
   "bin": {
     "flow-cc": "bin/install.js"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "bin",
     "skills",
     "hooks",
     "templates",
-    "VERSION"
+    "VERSION",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
   ]
 }

package/skills/flow-done.md

@@ -65,6 +65,8 @@ Structure:
 - Mark completed phases with completion date
 - Ensure pending phases have enough detail that the next session can start with a one-line prompt
 - **Archive check:** If the current milestone is fully complete:
+  - If `.planning/` does not exist, skip archiving entirely — there's nothing to archive
+  - Create `.planning/archive/` if it doesn't already exist (use `mkdir -p` or equivalent)
   - Move milestone phase details to `.planning/archive/milestones-vX.md`
   - Keep only the summary row in the ROADMAP milestone table
   - Move `PRD.md` to `.planning/archive/PRD-vX.md`
@@ -98,7 +100,7 @@ Determine the next action and generate a copyable handoff prompt:
   ```
 - If milestone is complete:
   ```
-  Milestone [name] complete. Run /flow:init to start the next milestone.
+  Milestone [name] complete. Run /flow:milestone to start the next milestone.
   ```
 
 Print the handoff prompt in a fenced code block so the user can copy it.

package/skills/flow-go.md

@@ -32,7 +32,7 @@ Run these checks before executing. If any fail, stop and tell the user what to d
    - Verification commands
    - If missing: "PRD phase section is too vague. Add wave structure + file lists, or run `/flow:spec`."
 3. **Branch check:** Verify you're on the correct feature branch (from PRD header). If not, warn the user.
-4. **All phases done?** If no pending phases remain: "All phases complete! Run `/flow:done` to wrap up, or `/flow:init` for the next milestone."
+4. **All phases done?** If no pending phases remain: "All phases complete! Run `/flow:done` to wrap up, or `/flow:milestone` for the next milestone."
 
 ## Step 3 — Staleness Check
 
@@ -82,22 +82,54 @@ so agents have it in their context without needing to search.]
 
 - Use TeamCreate or Task tool to spawn all agents in the wave simultaneously
 - Each agent runs with `mode: "bypassPermissions"` for autonomous execution
-- Wait for all agents in the wave to complete before moving to the next wave
+- Print: **"Wave N: Spawned X agents — [agent-1-task], [agent-2-task], ..."**
+- As each agent completes, print: **"Wave N: agent-name completed (X/Y)"**
+- Set a reasonable timeout for each agent. If an agent hasn't completed after 10 minutes, check on it. If it's stuck, stop it and note the failure.
+- Wait for all agents in the wave to complete (or timeout) before moving to the next wave
 
-### 4c. Between Waves
+### 4c. Wave Failure Handling
 
-After each wave completes:
+After a wave completes, check results:
+
+**If ALL agents in a wave failed:**
+- Print: **"Wave N failed — all X agents errored."**
+- Show error summaries from each agent
+- Use AskUserQuestion: "Wave N failed completely. How to proceed?"
+  - "Retry this wave"
+  - "Skip to next wave"
+  - "Abort phase"
+
+**If SOME agents failed but others succeeded:**
+- Print: **"Wave N: X/Y agents succeeded, Z failed."**
+- Show failed agent error summaries
+- Use AskUserQuestion: "Some agents failed. How to proceed?"
+  - "Retry failed agents"
+  - "Continue without them"
+  - "Abort phase"
+
+When a wave completes successfully (all agents or user chose to continue), print: **"Wave N complete. Proceeding to Wave N+1."**
+
+### 4d. Between Waves
+
+After each wave completes (and failure handling is resolved):
 1. Run verification commands from CLAUDE.md (e.g., `npx tsc --noEmit`, `npx biome check`)
 2. Check for integration issues between agents' output
 3. Fix any issues before proceeding to the next wave
 4. If verification fails and you can fix it quickly (< 2 minutes of work), fix it. Otherwise, stop and report.
 
-### 4d. Final Verification
+### 4e. Final Verification
 
 After ALL waves complete:
 1. Run full verification suite
 2. Check all acceptance criteria for this phase's user stories
-3. If anything fails, fix it or report to the user
+3. If verification fails, attempt to fix (max **3 attempts**):
+   - After attempt 1 fails: Print **"Verification failed. Attempting fix (1/3)..."**
+   - After attempt 2 fails: Print **"Verification failed. Attempting fix (2/3)..."**
+   - After attempt 3 fails: Print **"Verification failed after 3 attempts. STOP."** Print the errors and use AskUserQuestion:
+     - "Skip verification and continue"
+     - "Fix manually and retry"
+     - "Abort this phase"
+   - Do NOT loop further beyond 3 attempts.
 
 ## Step 5 — Commit
 

package/skills/flow-intro.md

@@ -14,28 +14,35 @@ Print this:
 
 ## Flow — Your Workflow System
 
-Flow is 5 commands that turn your specs into shipped code through agent teams. Each command feeds the next.
+Flow is 6 commands that turn your specs into shipped code through agent teams. Each command feeds the next.
 
 ### The Lifecycle
 
 ```
-/flow:init → /flow:spec → /flow:go (repeat) → /flow:done
+/flow:setup → /flow:spec → /flow:go (repeat) → /flow:done
                                                     ↓
                                         handoff prompt for next session
+                                                    ↓
+                                        /flow:milestone → next cycle
 
 /flow:task ← standalone path for bug fixes, cleanup, small features (no PRD needed)
 ```
 
 ### Command by Command
 
-**`/flow:init`** — Run once per project (or once per new milestone)
-- New project: asks you 4-5 questions (what is it, tech stack, verify commands, first milestone)
+**`/flow:setup`** — Run once per project
+- Asks you 4-5 questions (what is it, tech stack, verify commands, first milestone)
 - Creates the scaffolding: `CLAUDE.md`, `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`
-- Existing project: archives the old milestone + PRD, sets up the next one
+- If project already set up, tells you to use `/flow:milestone` or `/flow:spec` instead
+
+**`/flow:milestone`** — Run when starting a new milestone
+- Archives the completed milestone + PRD
+- Sets up fresh planning docs for the next milestone
+- Guards against archiving milestones with incomplete phases
 
 **`/flow:task`** — Run anytime for small work
 - Bug fixes, cleanup, one-off features — anything that doesn't need a full PRD
-- Works standalone without `/flow:init` — lowest friction entry to Flow
+- Works standalone without `/flow:setup` — lowest friction entry to Flow
 - Executes, verifies, commits, and logs to STATE.md (if it exists)
 - Scope guard recommends `/flow:spec` if the task grows beyond 5 files or 3 layers
 
@@ -80,7 +87,7 @@ Flow is 5 commands that turn your specs into shipped code through agent teams. E
 ### Starting a Brand New Project
 
 ```
-1. /flow:init        ← scaffolds everything
+1. /flow:setup       ← scaffolds everything
 2. /flow:spec        ← interview → PRD
 3. /flow:go          ← phase 1
 4. /flow:done        ← wrap up

package/skills/flow-milestone.md

@@ -0,0 +1,67 @@
+---
+name: flow:milestone
+description: Archive completed milestone and start a new one
+user_invocable: true
+---
+
+# /flow:milestone — Start New Milestone
+
+You are executing the `/flow:milestone` skill. This archives the current milestone and sets up a new one.
+
+## Guard: Project Must Exist
+
+Check if `.planning/STATE.md` exists:
+- **If it does NOT exist** → Print: "No project found. Run `/flow:setup` first." and **STOP.**
+- **If it exists** → Continue.
+
+## Step 1: Read Context
+
+Read `.planning/STATE.md` and `.planning/ROADMAP.md` to understand:
+- What milestone just completed (or is completing)
+- What version number to use next
+- Current state of the project
+
+## Step 2: Check for Pending Phases
+
+Parse ROADMAP.md for the current milestone's phases:
+- If any phases have status "Pending" or "In Progress" (not complete):
+  - Print: "Warning: The current milestone has incomplete phases:"
+  - List the pending/in-progress phases
+  - Use AskUserQuestion: "Archive this milestone anyway?" with options:
+    - "Yes — archive and move on"
+    - "No — finish current phases first"
+  - If the user says No → Print: "Run `/flow:go` to continue the current milestone." and **STOP.**
+
+## Step 3: Ask Milestone Question
+
+Use AskUserQuestion:
+- "What's the goal of this new milestone?" (free text)
+- "What should it be called?" (free text, or suggest a name based on context)
+
+## Step 4: Archive Completed Milestone
+
+1. Read current ROADMAP.md phase details for the completed milestone
+2. Write them to `.planning/archive/milestones-vX.md` (where X is the completed version)
+3. If `PRD.md` exists, move it to `.planning/archive/PRD-vX.md` (read it, write to archive, delete original)
+4. In ROADMAP.md, replace the completed milestone's phase details with just the summary row (mark as "Complete")
+
+## Step 5: Update Planning Docs
+
+**ROADMAP.md:**
+- Add new milestone row to the table
+- Add new milestone section with goal and "Run `/flow:spec` to define phases"
+
+**STATE.md:**
+- Replace with fresh state for the new milestone
+- Reset phase progress table
+- Note the milestone transition in "What Was Built"
+
+## Step 6: Print Completion Message
+
+```
+Milestone [name] (v[X]) initialized.
+- Archived: previous milestone details + PRD
+- Updated: ROADMAP.md, STATE.md
+
+Run `/flow:spec` to build the PRD for this milestone.
+```

package/skills/{flow-init.md → flow-setup.md}

@@ -1,24 +1,22 @@
 ---
-name: flow:init
-description: Initialize a new project or start a new milestone with planning scaffolding
+name: flow:setup
+description: Set up a new project with Flow planning scaffolding
 user_invocable: true
 ---
 
-# /flow:init — Initialize Project or Milestone
+# /flow:setup — Set Up New Project
 
-You are executing the `/flow:init` skill. This sets up the planning scaffolding for a new project or a new milestone within an existing project.
+You are executing the `/flow:setup` skill. This sets up the planning scaffolding for a new project.
 
-## Mode Detection
+## Guard: Already Initialized
 
-Check if `.planning/STATE.md` exists:
-- **If it does NOT exist** → New Project Mode
-- **If it exists** → New Milestone Mode
+Check if `.planning/STATE.md` already exists:
+- **If it exists** → Print: "This project is already set up. Run `/flow:milestone` to start a new milestone, or `/flow:spec` to spec the current one." and **STOP. Do not overwrite.**
+- **If it does NOT exist** → Continue with setup below.
 
 ---
 
-## New Project Mode
-
-### Step 1: Ask Setup Questions
+## Step 1: Ask Setup Questions
 
 Use AskUserQuestion to gather project info. Ask these questions (you may combine into 2-3 AskUserQuestion calls):
 
@@ -47,7 +45,7 @@ Use AskUserQuestion to gather project info. Ask these questions (you may combine
   - "Yes — scan and catalog existing code"
   - "No — greenfield project"
 
-### Step 2: Brownfield Scan (if requested)
+## Step 2: Brownfield Scan (if requested)
 
 If the user said yes to scanning:
 1. Use Glob to find key directories: `src/`, `app/`, `lib/`, `components/`, `api/`, `pages/`, `utils/`, `types/`
@@ -55,7 +53,7 @@ If the user said yes to scanning:
 3. Build a brief catalog of what exists (key components, patterns, data layer)
 4. Include this in the CLAUDE.md Quick Context section
 
-### Step 3: Create Project Files
+## Step 3: Create Project Files
 
 Create these 5 files (create directories as needed):
 
@@ -76,7 +74,7 @@ Create these 5 files (create directories as needed):
 | — | Run `/flow:spec` to define phases | — |
 
 ## What Was Built (This Session)
-- Project initialized with `/flow:init`
+- Project initialized with `/flow:setup`
 - Created: CLAUDE.md, STATE.md, ROADMAP.md, tasks/lessons.md
 
 ## Key Decisions
@@ -159,7 +157,7 @@ Format: PATTERN → CAUSE → FIX → RULE
 
 **`.planning/archive/`** — Create this empty directory (use `mkdir -p` via Bash).
 
-### Step 4: Print Completion Message
+## Step 4: Print Completion Message
 
 ```
 Project initialized:
@@ -171,48 +169,3 @@ Project initialized:
 
 Run `/flow:spec` to plan your first milestone.
 ```
-
----
-
-## New Milestone Mode
-
-### Step 1: Read Context
-
-Read `.planning/STATE.md` and `.planning/ROADMAP.md` to understand:
-- What milestone just completed (or is completing)
-- What version number to use next
-- Current state of the project
-
-### Step 2: Ask Milestone Question
-
-Use AskUserQuestion:
-- "What's the goal of this new milestone?" (free text)
-- "What should it be called?" (free text, or suggest a name based on context)
-
-### Step 3: Archive Completed Milestone
-
-1. Read current ROADMAP.md phase details for the completed milestone
-2. Write them to `.planning/archive/milestones-vX.md` (where X is the completed version)
-3. If `PRD.md` exists, move it to `.planning/archive/PRD-vX.md` (read it, write to archive, delete original)
-4. In ROADMAP.md, replace the completed milestone's phase details with just the summary row (mark as "Complete")
-
-### Step 4: Update Planning Docs
-
-**ROADMAP.md:**
-- Add new milestone row to the table
-- Add new milestone section with goal and "Run `/flow:spec` to define phases"
-
-**STATE.md:**
-- Replace with fresh state for the new milestone
-- Reset phase progress table
-- Note the milestone transition in "What Was Built"
-
-### Step 5: Print Completion Message
-
-```
-Milestone [name] (v[X]) initialized.
-- Archived: previous milestone details + PRD
-- Updated: ROADMAP.md, STATE.md
-
-Run `/flow:spec` to build the PRD for this milestone.
-```

package/skills/flow-spec.md

@@ -16,8 +16,10 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 2. Read `CLAUDE.md` — understand project rules and tech stack
 3. Read `PRD.md` if it exists — check for existing spec to build on
 4. **Codebase scan** (brownfield projects):
-   - Use Glob to find: components, pages/routes, API endpoints, types, utilities, config files, database models
-   - Use Grep for: export patterns, route definitions, key function signatures
+   - **Exclusions:** NEVER scan these directories/files: `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`. Use Glob with patterns like `src/**/*`, `app/**/*`, `lib/**/*` — never use bare `**/*` which includes generated files.
+   - **Size check first:** Use Glob with `src/**/*`, `app/**/*`, `lib/**/*`, `components/**/*` (excluding the above) to estimate relevant file count. If > 500 files, switch to focused mode (see below).
+   - **Standard mode (≤ 500 files):** Use Glob to find components, pages/routes, API endpoints, types, utilities, config files, database models. Use Grep for export patterns, route definitions, key function signatures. **Cap at 50 files sampled** — prioritize entry points, config, and type definitions.
+   - **Focused mode (> 500 files):** Scan ONLY: package.json/config files, entry points (index.ts, main.ts, app.ts), route definitions, database schema/models, and type definition files. Skip component trees, test files, and generated code entirely.
    - Build internal summary: "Here's what exists that we can reuse"
 5. Print a brief context summary to the user: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
 
@@ -113,6 +115,20 @@ Cover these areas thoroughly. There are no "rounds" — move fluidly between are
 
 ## Phase 3 — PRD Generation
 
+### Minimum Viable PRD Check
+
+Before generating the final PRD, validate:
+- At least **3 user stories** with acceptance criteria have been discussed
+- At least **1 implementation phase** has been defined
+- At least **1 verification command** has been specified
+
+If any check fails, print what's missing and use AskUserQuestion:
+- "The PRD is thin — [missing items]. Want to continue the interview to flesh it out, or finalize as-is?"
+  - "Continue interview" — return to Phase 2 and probe the missing areas
+  - "Finalize as-is" — proceed with what we have
+
+### Write PRD
+
 Write `PRD.md` to the project root with this EXACT structure:
 
 ```markdown

package/skills/flow-status.md

@@ -17,7 +17,7 @@ Read ALL of the following in parallel:
 - Count lessons in `tasks/lessons.md` (if exists)
 
 IF both STATE.md AND ROADMAP.md are missing:
-- Print: "No flow project found. Run `/flow:init` to set up, or `/flow:task` for a quick standalone fix."
+- Print: "No flow project found. Run `/flow:setup` to set up, or `/flow:task` for a quick standalone fix."
 - STOP here.
 
 IF only one file exists, continue with what's available.
@@ -47,7 +47,7 @@ Use this explicit decision tree:
 
 **IF all phases are complete:**
 → Primary: `/flow:done` to finalize this milestone
-→ Then: `/flow:init` to start the next milestone
+→ Then: `/flow:milestone` to start the next milestone
 → Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
 
 **IF no phases exist in ROADMAP (milestone defined but not planned):**
@@ -65,7 +65,7 @@ Lessons: [N] rules
 [routing recommendations from Step 3]
 ```
 
-Adapt the block based on available information. If STATE.md is missing, omit "Last session". If ROADMAP.md is missing, omit phase counts and say "Run /flow:init to set up tracking."
+Adapt the block based on available information. If STATE.md is missing, omit "Last session". If ROADMAP.md is missing, omit phase counts and say "Run /flow:setup to set up tracking."
 
 ## Step 5 — No File Writes
 

package/skills/flow-task.md

@@ -11,7 +11,7 @@ You are executing the `/flow:task` skill. This is for small, focused work — bu
 RULES:
 - NO AGENT TEAMS. NO PRD. Single execution context.
 - Exception: ONE Task agent for an isolated subtask to prevent context bloat.
-- This skill MUST work without `/flow:init`. Missing planning files are fine.
+- This skill MUST work without `/flow:setup`. Missing planning files are fine.
 
 ## Step 1 — Context Load
 

package/skills/flow-update.md

@@ -46,14 +46,23 @@ If installed version equals latest version, print this and stop:
 Flow is up to date (v<version>)
 ```
 
-## Step 4: Confirm update
+## Step 4: Show what's new
 
-Print the available update and ask the user to confirm:
+Fetch the CHANGELOG.md from the Flow repo to show the user what changed:
+
+1. Run: `npx -y -p flow-cc@<latest> node -e "const fs=require('fs'),p=require('path');try{console.log(fs.readFileSync(p.join(require.resolve('flow-cc/package.json'),'..','CHANGELOG.md'),'utf8'))}catch(e){console.log('CHANGELOG not available')}"`
+2. Parse the output and extract only the section for `v<latest>` (from the `## [<latest>]` heading to the next `## [` heading or end of file)
+3. Print:
 
 ```
 Update available: v<installed> → v<latest>
+
+Here's what's new in v<latest>:
+<extracted changelog section>
 ```
 
+If the CHANGELOG fetch fails, just print the version line without the changelog section. Don't let a missing changelog block the update.
+
 Wait for user confirmation before proceeding.
 
 ## Step 5: Run update

package/templates/STATE.md.template

@@ -13,7 +13,7 @@
 | — | Run `/flow:spec` to define phases | — |
 
 ## What Was Built (This Session)
-- Project initialized with `/flow:init`
+- Project initialized with `/flow:setup`
 - Created: CLAUDE.md, STATE.md, ROADMAP.md, tasks/lessons.md
 
 ## Key Decisions

package/templates/lessons.md.template

@@ -5,6 +5,16 @@ Format: PATTERN → CAUSE → FIX → RULE
 ## Execution Patterns
 <!-- Lessons about workflow, delegation, verification -->
 
+<!-- EXAMPLE (replace with real lessons as you work):
+
+### Agent context overflow on large files
+- **PATTERN:** Spawned agent tried to read a 2000-line file and ran out of context before finishing its task
+- **CAUSE:** Agent prompt didn't specify which lines/functions to read — it read the whole file
+- **FIX:** Added explicit line ranges and function names to the agent prompt
+- **RULE:** Always tell agents exactly which functions/sections to read. Never say "read file.ts" — say "read file.ts lines 50-120 (the handleSubmit function)"
+
+END EXAMPLE -->
+
 ## Domain Knowledge
 <!-- Lessons about business logic, data models, user behavior -->