flow-cc 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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

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/

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

package/bin/install.js

@@ -321,14 +321,15 @@ try {
 Flow v${version} installed successfully!
 
 Commands available:
-  /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
+  /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.
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.2.0",
+  "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",

package/skills/flow-done.md

@@ -100,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,7 +16,8 @@ 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):
-   - **Size check first:** Use Glob with `**/*` to estimate total file count. If > 500 files, switch to focused mode (see below).
+   - **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"
@@ -114,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/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