flow-cc 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# Flow Plugin
+
+**Formalized workflow skills for Claude Code. Turns a proven spec-interview, agent-team-execution, session-handoff pattern into reusable `/flow:*` commands.**
+
+## 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
+
+```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
+```
+
+**Update:** Run `/flow:update` in any Claude Code session
+
+## Getting Started
+
+After installing, run `/flow:intro` in any Claude Code session. It explains the full lifecycle, what each command does, and typical usage patterns.
+
+## How It Works
+
+Skills install to `~/.claude/commands/flow/` and are immediately available in any Claude Code session. The workflow:
+
+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
+
+## Lifecycle
+
+```
+/flow:init -> /flow:spec -> /flow:go (repeat per phase) -> /flow:done
+                                                               |
+                                                handoff prompt for next session
+
+/flow:task  ← standalone path for bug fixes, cleanup, small features (no PRD needed)
+```
+
+## Compatible with GSD
+
+Uses the same `.planning/` directory structure. You can still use `/gsd:debug`, `/gsd:map-codebase`, etc. alongside Flow commands.
+
+## Philosophy
+
+- 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
+
+## Requirements
+
+Claude Code CLI with skills support.

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/bin/install.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Flow plugin installer for Claude Code
+// Usage: npx flow-cc [--uninstall]
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const homeDir = os.homedir();
+const claudeDir = path.join(homeDir, '.claude');
+const commandsDir = path.join(claudeDir, 'commands', 'flow');
+const hooksDir = path.join(claudeDir, 'hooks');
+const cacheDir = path.join(claudeDir, 'cache');
+const settingsPath = path.join(claudeDir, 'settings.json');
+
+// Source directories (relative to package root, one level up from bin/)
+const pkgRoot = path.resolve(__dirname, '..');
+const skillsDir = path.join(pkgRoot, 'skills');
+const srcHooksDir = path.join(pkgRoot, 'hooks');
+const templatesDir = path.join(pkgRoot, 'templates');
+const versionFile = path.join(pkgRoot, 'VERSION');
+
+const uninstall = process.argv.includes('--uninstall') || process.argv.includes('-u');
+
+// ---------- Uninstall ----------
+if (uninstall) {
+  console.log('Uninstalling Flow plugin...\n');
+
+  // Remove flow commands directory
+  if (fs.existsSync(commandsDir)) {
+    fs.rmSync(commandsDir, { recursive: true });
+    console.log('  Removed ~/.claude/commands/flow/');
+  }
+
+  // Remove flow hooks
+  const hookFiles = ['flow-check-update.js', 'flow-statusline.js'];
+  for (const hook of hookFiles) {
+    const hookPath = path.join(hooksDir, hook);
+    if (fs.existsSync(hookPath)) {
+      fs.unlinkSync(hookPath);
+      console.log(`  Removed ~/.claude/hooks/${hook}`);
+    }
+  }
+
+  // Remove update cache
+  const cacheFile = path.join(cacheDir, 'flow-update-check.json');
+  if (fs.existsSync(cacheFile)) {
+    fs.unlinkSync(cacheFile);
+    console.log('  Removed ~/.claude/cache/flow-update-check.json');
+  }
+
+  // Remove statusLine from settings.json if it points to flow
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (settings.statusLine && typeof settings.statusLine.command === 'string' &&
+          settings.statusLine.command.includes('flow-statusline')) {
+        delete settings.statusLine;
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        console.log('  Removed statusLine from ~/.claude/settings.json');
+      }
+    } catch (e) {
+      // settings.json parse error — leave it alone
+    }
+  }
+
+  console.log('\nFlow plugin uninstalled.');
+  process.exit(0);
+}
+
+// ---------- Install ----------
+console.log('Installing Flow plugin...\n');
+
+// 1. Create directories
+for (const dir of [commandsDir, hooksDir, cacheDir]) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// 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));
+}
+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));
+  }
+}
+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));
+  }
+  console.log(`  Installed ${templateFiles.length} templates → ~/.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');
+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(`
+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
+
+Get started: run /flow:intro in any Claude Code session.
+`);

package/hooks/flow-check-update.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Check for Flow updates in background, write result to cache
+// Called by flow-statusline.js when cache is stale or missing
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+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');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// 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');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const versionFile = ${JSON.stringify(versionFile)};
+
+  let installed = '0.0.0';
+  try {
+    if (fs.existsSync(versionFile)) {
+      installed = fs.readFileSync(versionFile, 'utf8').trim();
+    }
+  } 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();

package/hooks/flow-statusline.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Claude Code Statusline — Flow Edition
+// Shows: [update notification] | model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const homeDir = os.homedir();
+
+// Read JSON from stdin (Claude Code statusline protocol)
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // --- Context window bar (scaled to 80% limit) ---
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const rawUsed = Math.max(0, Math.min(100, 100 - rem));
+      const used = Math.min(100, Math.round((rawUsed / 80) * 100));
+
+      const filled = Math.floor(used / 10);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+
+      if (used < 63) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 81) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 95) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\uD83D\uDC80 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // --- Current task from todos ---
+    let task = '';
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            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) {}
+    }
+
+    // --- Flow update notification ---
+    let flowUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'flow-update-check.json');
+    let shouldCheck = false;
+
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          flowUpdate = '\x1b[33m\u2B06 /flow:update\x1b[0m \u2502 ';
+        }
+        // Trigger background re-check if cache is older than 6 hours
+        const sixHours = 6 * 60 * 60;
+        if (!cache.checked || (Math.floor(Date.now() / 1000) - cache.checked) > sixHours) {
+          shouldCheck = true;
+        }
+      } catch (e) {
+        shouldCheck = true;
+      }
+    } else {
+      shouldCheck = true;
+    }
+
+    // Spawn background update check if needed
+    if (shouldCheck) {
+      try {
+        const checkScript = path.join(homeDir, '.claude', 'hooks', 'flow-check-update.js');
+        if (fs.existsSync(checkScript)) {
+          const { spawn } = require('child_process');
+          const child = spawn(process.execPath, [checkScript], {
+            stdio: 'ignore',
+            windowsHide: true
+          });
+          child.unref();
+        }
+      } catch (e) {}
+    }
+
+    // --- Output ---
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${flowUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${flowUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail — statusline must never crash
+  }
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "flow-cc",
+  "version": "0.1.0",
+  "description": "Flow workflow plugin for Claude Code",
+  "bin": {
+    "flow-cc": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "hooks",
+    "templates",
+    "VERSION"
+  ]
+}

package/skills/flow-done.md

@@ -0,0 +1,117 @@
+---
+name: flow:done
+description: Session-end documentation — updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
+user_invocable: true
+---
+
+# /flow:done — Session End + Handoff
+
+You are executing the `/flow:done` skill. This finalizes the current session by updating all planning documents and generating a handoff prompt for the next session.
+
+**This is the most important skill for sustainability.** Without proper session-end docs, the next session starts blind.
+
+## Steps
+
+### 1. Gather Context
+
+Read these files (in parallel where possible):
+- `.planning/STATE.md` — current state
+- `.planning/ROADMAP.md` — milestone/phase progress
+- `tasks/lessons.md` — existing lessons
+- `CLAUDE.md` — project rules
+- `PRD.md` — current spec (if exists)
+
+Also gather:
+- Run `git log --oneline -20` to see commits this session
+- Run `git diff --stat` to check for uncommitted changes
+- If uncommitted changes exist, warn the user before proceeding
+
+### 2. Update STATE.md
+
+**REPLACE the entire file** (do NOT append). Keep under 80 lines.
+
+Structure:
+```
+# [Project Name] — Project State
+
+## Current Position
+- **Milestone:** [name] (vX)
+- **Phase:** [current phase status]
+- **Branch:** [current branch]
+- **Last Session:** [today's date]
+
+## Milestone Progress
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [name] | Complete (date) |
+| 2 | [name] | Complete (date) |
+| 3 | [name] | In Progress |
+| 4 | [name] | Pending |
+
+## What Was Built (This Session)
+- [Bullet list of what was accomplished]
+- [Include file counts, key components, commit SHAs]
+
+## Key Decisions
+- [Any architectural or design decisions made]
+
+## Next Actions
+1. [Specific next step — usually "Run /flow:go for Phase N"]
+```
+
+### 3. Update ROADMAP.md
+
+- 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:
+  - 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`
+
+### 4. Update lessons.md
+
+- Review the session for mistakes, corrections, or discovered issues
+- Auto-suggest lessons based on errors encountered (if any)
+- Ask the user: "Any lessons from this session?" using AskUserQuestion with options:
+  - "No new lessons"
+  - "Yes, let me add some" (user types them)
+  - "Use your suggestions" (if you auto-suggested any)
+- Add new lessons in PATTERN/CAUSE/FIX/RULE format
+- **Refine existing lessons:** merge duplicates, sharpen vague rules, delete obvious ones
+- **Promote check:** For lessons that seem universal (not project-specific), ask: "This lesson seems universal. Promote to global lessons (~/.claude/lessons.md)?"
+
+### 5. Commit Doc Updates
+
+- Stage only the planning docs: STATE.md, ROADMAP.md, lessons.md, and any archived files
+- Commit with message: `docs: session-end updates — [brief summary]`
+- Do NOT push unless the user asks
+
+### 6. Generate Handoff Prompt
+
+Determine the next action and generate a copyable handoff prompt:
+
+- If next phase exists in PRD:
+  ```
+  Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and PRD.md (US-X).
+  [One sentence of context]. [One sentence of what NOT to do if relevant].
+  ```
+- If milestone is complete:
+  ```
+  Milestone [name] complete. Run /flow:init to start the next milestone.
+  ```
+
+Print the handoff prompt in a fenced code block so the user can copy it.
+
+### 7. Print Summary
+
+```
+Session complete.
+- STATE.md: updated
+- ROADMAP.md: [N] phases marked complete
+- lessons.md: [N] lessons added, [N] refined
+- Committed: [SHA]
+
+Handoff prompt:
+[the prompt in a code block]
+```

package/skills/flow-go.md

@@ -0,0 +1,132 @@
+---
+name: flow:go
+description: Execute the next phase from PRD using wave-based agent teams
+user_invocable: true
+---
+
+# /flow:go — Execute Next Phase
+
+You are executing the `/flow:go` skill. This reads the PRD, identifies the next unstarted phase, and executes it using wave-based agent teams.
+
+**Core principle:** The PRD is the execution contract. You execute what it specifies. Do not freelance.
+
+## Step 1 — Orient
+
+Read these files (in parallel):
+- `.planning/STATE.md` — current position
+- `.planning/ROADMAP.md` — phase progress
+- `PRD.md` — the execution spec
+- `tasks/lessons.md` — anti-patterns to avoid
+- `CLAUDE.md` — execution rules and verification commands
+
+**Identify the next phase:** Find the first phase in ROADMAP.md with status "Pending" or the first unstarted phase in the PRD.
+
+## Step 2 — Pre-flight Checks
+
+Run these checks before executing. If any fail, stop and tell the user what to do:
+
+1. **PRD exists?** If `PRD.md` is missing: "No PRD found. Run `/flow:spec` first."
+2. **Phase detailed enough?** The phase section in the PRD must have:
+   - Wave structure with agent assignments
+   - Explicit file lists per agent
+   - 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."
+
+## Step 3 — Staleness Check
+
+Compare this phase's PRD section against the actual codebase:
+- Do the files it references still exist / have the expected structure?
+- Were files created/deleted/significantly changed by prior phases that affect this phase?
+- If stale references found: fix them in the PRD (update file paths, note structural changes) before proceeding. Print what you corrected.
+
+Do NOT rewrite the phase — just fix stale references so agents get accurate context.
+
+## Step 4 — Execute Waves
+
+For each wave defined in the PRD phase section:
+
+### 4a. Prepare Agent Prompts
+
+For each agent in the wave, build a prompt containing:
+
+```
+You are [agent-name] working on Phase [N]: [Phase Name].
+
+## Your Task
+[Task description from PRD wave structure]
+
+## Files to Create/Modify
+[Exact file list from PRD — absolute paths]
+
+## Acceptance Criteria
+[Relevant criteria from the user stories this phase covers]
+
+## Existing Code to Reuse
+[Inline the actual code/types/signatures from the "Key Existing Code" PRD section.
+Do NOT just reference file paths — READ the files and INLINE the relevant code
+so agents have it in their context without needing to search.]
+
+## Rules
+- Only modify files in your list. Do not touch anything else.
+- Run verification after your work: [commands from CLAUDE.md]
+- Stage only your files when committing (never `git add .` or `git add -A`)
+- If you need output from another agent that isn't available yet, create a temporary stub and continue. Delete the stub before your final commit.
+
+## Anti-Patterns to Avoid
+[Relevant lessons from tasks/lessons.md — filter to lessons that apply to this agent's work]
+```
+
+### 4b. Spawn Wave
+
+- 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
+
+### 4c. Between Waves
+
+After each wave completes:
+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
+
+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
+
+## Step 5 — Commit
+
+Create an atomic commit for this phase:
+- Stage only the files created/modified by this phase's agents
+- Commit message: `feat: [phase description] (Phase N)`
+- Do NOT push unless the user asks
+
+## Step 6 — Update Docs
+
+**STATE.md:** Update "What Was Built" section with:
+- Files created/modified (count + key names)
+- Commit SHA
+- Phase completion note
+
+**ROADMAP.md:** Mark this phase as "Complete ([today's date])"
+
+## Step 7 — Route Next Action
+
+Print phase summary:
+```
+Phase [N]: [Name] — Complete
+- [X] files created, [Y] modified
+- Commit: [SHA]
+- Verification: passed
+
+Next:
+- /flow:go for Phase [N+1]: [Next Phase Name]
+- /flow:done to end session
+```
+
+If this was the last phase: "All phases complete! Run `/flow:done` to finalize."