flow-cc 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Troy Hoffman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,66 +1,132 @@
-# Flow Plugin
+<p align="center">
+  <h1 align="center">Flow</h1>
+  <p align="center">A structured workflow system for Claude Code.<br/>Spec interviews. Agent-team execution. Session handoffs. Compounding knowledge.</p>
+</p>
 
-**Formalized workflow skills for Claude Code. Turns a proven spec-interview, agent-team-execution, session-handoff pattern into reusable `/flow:*` commands.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/flow-cc"><img src="https://img.shields.io/npm/v/flow-cc.svg" alt="npm version"></a>
+  <a href="https://github.com/troyhoffman-oss/flow-plugin/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/flow-cc.svg" alt="license"></a>
+  <a href="https://www.npmjs.com/package/flow-cc"><img src="https://img.shields.io/npm/dm/flow-cc.svg" alt="downloads"></a>
+</p>
 
-## What It Does
+---
 
-- `/flow:intro` -- Walkthrough of the system — **start here**
-- `/flow:init` -- Initialize a new project or milestone with planning scaffolding
-- `/flow:spec` -- Run a spec interview that produces an executable PRD with wave-based phases
-- `/flow:task` -- Lightweight task execution — bug fixes, cleanup, small features without a PRD
-- `/flow:go` -- Execute the next phase from the PRD using agent teams
-- `/flow:done` -- Session-end docs, lessons refinement, and handoff prompt generation
-- `/flow:status` -- Quick "where am I?" orientation
-- `/flow:update` -- Pull latest and re-install skills from any session
-
-## Installation
+## Install
 
 ```bash
-# Mac/Linux
-git clone https://github.com/troyhoffman/flow-plugin.git && cd flow-plugin && bash setup.sh
-
-# Windows (PowerShell)
-git clone https://github.com/troyhoffman/flow-plugin.git; cd flow-plugin; .\setup.ps1
+npx flow-cc
 ```
 
-**Update:** Run `/flow:update` in any Claude Code session
+One command. Installs skills, hooks, templates, and configures your statusLine. Works on Mac, Linux, and Windows.
+
+## Why Flow?
+
+Claude Code is powerful but unstructured. Without a system, you lose context between sessions, repeat mistakes, and waste tokens re-explaining what you've already decided.
+
+Flow fixes this by giving Claude Code a **memory system and execution framework**:
 
-## Getting Started
+- **Spec interviews** extract decisions upfront so agents execute instead of guessing
+- **PRDs become execution contracts** that agent teams follow phase-by-phase
+- **Session handoffs** preserve context across fresh sessions — no more "where was I?"
+- **Lessons compound** — mistakes get captured, refined, and promoted into permanent rules
 
-After installing, run `/flow:intro` in any Claude Code session. It explains the full lifecycle, what each command does, and typical usage patterns.
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/flow:intro` | Walkthrough of the system — **start here** |
+| `/flow:init` | Initialize a project with `.planning/` scaffolding, CLAUDE.md, templates |
+| `/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 |
+| `/flow:done` | Session-end documentation, lessons refinement, handoff prompt |
+| `/flow:status` | Quick orientation — current milestone, phase progress, next actions |
+| `/flow:update` | Update Flow to the latest version |
 
 ## How It Works
 
-Skills install to `~/.claude/commands/flow/` and are immediately available in any Claude Code session. The workflow:
+```
+/flow:init → /flow:spec → /flow:go (repeat per phase) → /flow:done
+                                                            ↓
+                                              handoff prompt for next session
+
+/flow:task  ← standalone path for bug fixes and small features
+```
+
+**The lifecycle in practice:**
 
-1. `/flow:init` -- Creates `.planning/` directory structure, CLAUDE.md, and initial docs
-2. `/flow:spec` -- Interviews you about the milestone, produces PRD.md with wave-based phases
-3. `/flow:go` -- Reads PRD, spawns agent teams per wave structure, verifies, commits
-4. `/flow:task` -- Quick fixes and small features — executes, verifies, commits (no PRD needed)
-5. `/flow:done` -- Updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
-6. `/flow:status` -- Read-only orientation check
+1. **`/flow:init`** — 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
+5. **Repeat** — Next session picks up from the handoff. Context lives in the repo, not the conversation.
 
-## Lifecycle
+## What Gets Installed
 
 ```
-/flow:init -> /flow:spec -> /flow:go (repeat per phase) -> /flow:done
-                                                               |
-                                                handoff prompt for next session
+~/.claude/
+├── commands/flow/
+│   ├── flow-init.md          # 8 skill files
+│   ├── flow-spec.md
+│   ├── flow-go.md
+│   ├── flow-task.md
+│   ├── flow-done.md
+│   ├── flow-status.md
+│   ├── flow-intro.md
+│   ├── flow-update.md
+│   ├── VERSION
+│   └── templates/            # Project scaffolding templates
+│       ├── CLAUDE.md.template
+│       ├── STATE.md.template
+│       ├── ROADMAP.md.template
+│       └── lessons.md.template
+├── hooks/
+│   ├── flow-check-update.js  # Notifies when updates are available
+│   └── flow-statusline.js    # Shows project context in statusLine
+└── settings.json             # statusLine configured automatically
+```
+
+## Project Structure
+
+Every Flow project gets this structure via `/flow:init`:
 
-/flow:task  ← standalone path for bug fixes, cleanup, small features (no PRD needed)
 ```
+your-project/
+├── CLAUDE.md              # Project-specific execution rules
+├── PRD.md                 # Current milestone spec (created by /flow:spec)
+├── .planning/
+│   ├── STATE.md           # Session GPS — current status, next actions
+│   ├── ROADMAP.md         # Milestone phases and progress
+│   └── archive/           # Completed milestones and old PRDs
+└── tasks/
+    └── lessons.md         # Mistake catalog → refined into permanent rules
+```
+
+## The Lessons System
 
-## Compatible with GSD
+Flow's knowledge compounding is what makes it get better over time:
 
-Uses the same `.planning/` directory structure. You can still use `/gsd:debug`, `/gsd:map-codebase`, etc. alongside Flow commands.
+1. **Capture** — Mistake happens, lesson written to `tasks/lessons.md`
+2. **Refine** — Each `/flow:done` merges duplicates, sharpens rules, removes obvious ones
+3. **Promote** — Universal lessons move to `~/.claude/lessons.md` (all projects)
+4. **Permanence** — Recurring patterns become rules in `CLAUDE.md`
 
-## Philosophy
+The goal: fewer, sharper lessons over time — not an ever-growing list.
 
-- Front-load decisions into the spec interview, making execution simple
-- Knowledge compounds through lessons.md to CLAUDE.md promotion lifecycle
-- Fresh context per session; memory lives in the repo, not the conversation
-- PRD is the execution contract -- agents execute what was specified
+## Compatible With GSD
+
+Flow uses the same `.planning/` directory structure as [GSD](https://github.com/gsd-framework/gsd). You can use `/gsd:debug`, `/gsd:map-codebase`, and other GSD commands alongside Flow.
 
 ## Requirements
 
-Claude Code CLI with skills support.
+[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.0
+0.2.0

package/bin/install.js

@@ -1,11 +1,18 @@
 #!/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,175 @@ 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:init    \u2014 Start a new project or 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,15 +1,40 @@
 {
   "name": "flow-cc",
-  "version": "0.1.0",
-  "description": "Flow workflow plugin for Claude Code",
+  "version": "0.2.0",
+  "description": "Structured workflow system for Claude Code — spec interviews, agent-team execution, session handoffs, compounding knowledge",
+  "author": "Troy Hoffman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/troyhoffman-oss/flow-plugin.git"
+  },
+  "homepage": "https://github.com/troyhoffman-oss/flow-plugin",
+  "bugs": {
+    "url": "https://github.com/troyhoffman-oss/flow-plugin/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "workflow",
+    "ai-agents",
+    "developer-tools",
+    "cli",
+    "skills",
+    "anthropic"
+  ],
   "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`

package/skills/flow-spec.md

@@ -16,8 +16,9 @@ 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
+   - **Size check first:** Use Glob with `**/*` to estimate total 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."
 

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/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 -->