flow-cc 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.4.0] - 2026-02-11
+
+### Added
+- Multi-milestone roadmap input in `/flow:setup` — capture your full roadmap upfront (paste a list or build one at a time)
+- Auto-transition between milestones in `/flow:done` — when a milestone completes and the next is planned, it transitions automatically
+- Two-path milestone input (paste/describe or guided) in both `/flow:setup` and `/flow:milestone`
+
+### Changed
+- `/flow:milestone` purpose shifted from "archive + start next" to "add new milestones to the roadmap" — archive logic moved to `/flow:done`
+- `/flow:done` handoff prompt now has three cases: next phase, next milestone (auto-transitioned), or all milestones complete
+- `/flow:status` routing updated — recommends `/flow:done` (not `/flow:milestone`) when next milestone exists, since transition is automatic
+- `/flow:setup` Question 4 changed from "first milestone" to full roadmap input
+- ROADMAP.md template supports multiple milestones with `{{ADDITIONAL_MILESTONES_TABLE}}` and `{{ADDITIONAL_MILESTONES_SECTIONS}}` placeholders
+- Updated lifecycle diagrams in README and `/flow:intro` to show pre-planned milestone flow
+- Updated command descriptions across intro, README, and install.js
+
+## [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

@@ -30,43 +30,57 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 - **Session handoffs** preserve context across fresh sessions — no more "where was I?"
 - **Lessons compound** — mistakes get captured, refined, and promoted into permanent rules
 
+## How It Works
+
+**One-time setup**, then a repeating build cycle:
+
+```
+/flow:setup  →  /flow:spec  →  /flow:go  →  /flow:done
+  (once,          (once per      (once per     (end of session,
+  captures        milestone)      phase)        auto-transitions
+  full roadmap)                                 between milestones)
+```
+
+1. **`/flow:setup`** — Scaffolds your project with planning docs and execution rules
+2. **`/flow:spec`** — Interviews you, then writes an executable PRD with phases, acceptance criteria, and agent-team structure
+3. **`/flow:go`** — Spawns parallel agent teams to build the next phase, verifies, commits
+4. **`/flow:done`** — Updates docs, captures lessons, generates a handoff prompt so the next session starts instantly
+
+Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap up. Next session, paste the handoff prompt and keep going.
+
 ## 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 |
+**The build cycle:**
 
-## How It Works
+| Command | When to use |
+|---|---|
+| `/flow:setup` | Once per project — creates `.planning/`, CLAUDE.md, templates |
+| `/flow:spec` | Once per milestone — interview that produces the PRD |
+| `/flow:go` | Once per phase — executes the next phase with agent teams |
+| `/flow:done` | End of session — updates docs, generates handoff prompt |
 
-```
-/flow:init → /flow:spec → /flow:go (repeat per phase) → /flow:done
-                                                            ↓
-                                              handoff prompt for next session
+**Standalone:**
 
-/flow:task  ← standalone path for bug fixes and small features
-```
+| Command | When to use |
+|---|---|
+| `/flow:task` | Anytime — bug fixes, cleanup, small features (no PRD needed) |
+| `/flow:milestone` | Anytime — add new milestones to the roadmap |
 
-**The lifecycle in practice:**
+**Utility:**
 
-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.
+| Command | When to use |
+|---|---|
+| `/flow:intro` | First time — walkthrough of the system |
+| `/flow:status` | Anytime — where am I? What's next? |
+| `/flow:update` | Anytime — update Flow to the latest version |
 
 ## What Gets Installed
 
 ```
 ~/.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 +102,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.4.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 with full roadmap
+  /flow:milestone  \u2014 Add new milestones to the roadmap
+  /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.4.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

@@ -70,6 +70,10 @@ Structure:
   - 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`
+  - Mark the milestone as "Complete" in the ROADMAP table
+  - **Milestone transition:** Check ROADMAP.md for the NEXT milestone with status "Planned":
+    - **If a next milestone exists:** Update its status from "Planned" to "Pending — needs `/flow:spec`". Update STATE.md current milestone to point to the new milestone.
+    - **If no next milestone exists:** No transition needed — all planned milestones are done.
 
 ### 4. Update lessons.md
 
@@ -98,9 +102,13 @@ Determine the next action and generate a copyable handoff prompt:
   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:
+- If milestone is complete AND a next milestone was transitioned to (from Step 3):
   ```
-  Milestone [name] complete. Run /flow:init to start the next milestone.
+  Milestone [name] complete. Next: v[X] [next milestone name]. Run /flow:spec to plan it.
+  ```
+- If milestone is complete AND no next milestone exists:
+  ```
+  All milestones complete! Run /flow:milestone to plan what's next, or enjoy the win.
   ```
 
 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,36 @@ 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
-                                                    ↓
-                                        handoff prompt for next session
+/flow:setup → /flow:spec → /flow:go (repeat) → /flow:done
+  (captures      ↑                                  |
+  full roadmap)  |     auto-transitions to          |
+                 +---- next planned milestone ------+
 
-/flow:task ← standalone path for bug fixes, cleanup, small features (no PRD needed)
+/flow:milestone ← add milestones to roadmap anytime
+/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, roadmap/milestones)
+- Captures your full roadmap upfront (paste a list or build one milestone at a time)
 - 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`** — Add milestones to the roadmap
+- Adds new milestones to the project roadmap (paste a list or one at a time)
+- Shows current roadmap status before adding
+- If no milestone is active, activates the first new one
 
 **`/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
 
@@ -55,6 +63,7 @@ Flow is 5 commands that turn your specs into shipped code through agent teams. E
 **`/flow:done`** — Run at end of every session
 - Replaces STATE.md with current status
 - Updates ROADMAP.md with phase completions
+- Auto-transitions to the next planned milestone when the current one completes
 - Asks about lessons, refines existing ones
 - Commits doc updates
 - Generates a handoff prompt you copy-paste to start the next session
@@ -80,7 +89,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,78 @@
+---
+name: flow:milestone
+description: Add new milestones to the roadmap
+user_invocable: true
+---
+
+# /flow:milestone — Add New Milestones
+
+You are executing the `/flow:milestone` skill. This adds new milestones to the project roadmap.
+
+## 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:
+- Current milestone status (what's active, what's complete, what's planned)
+- What version numbers are already used
+
+## Step 2: Show Current Status
+
+Print a summary of the roadmap:
+- List all milestones with their status (Complete, Pending, Planned, In Progress)
+- Highlight the currently active milestone (if any)
+
+## Step 3: Check for Active Work
+
+If there is a milestone with status "Pending" or with incomplete phases (In Progress):
+- Print: "Note: [milestone name] is currently active. New milestones will be added after existing planned milestones."
+
+## Step 4: Gather New Milestones
+
+Use AskUserQuestion:
+- "How would you like to add milestones?" with options:
+  - "I'll paste or describe them"
+  - "One at a time (guided)"
+
+**If paste/describe:**
+- Accept free text (bullet list, paragraph, pasted doc — any format)
+- Parse into milestones, each with a name + brief goal
+- Print back: "Here's what I got:" followed by the parsed list
+- Use AskUserQuestion to confirm: "Does this look right?" with options:
+  - "Yes — looks good"
+  - "Let me adjust" (user re-enters)
+
+**If guided:**
+- Ask: "What's this milestone called?" (name) and "What's the goal?" (one-sentence description)
+- Then: "Add another milestone?" with options:
+  - "Yes — add another"
+  - "That's all"
+- Repeat until user says that's all
+
+## Step 5: Update Planning Docs
+
+**ROADMAP.md:**
+- Determine the next available version number (after existing milestones)
+- Add new milestone rows to the table with status "Planned"
+- Add new milestone sections with goals and "Run `/flow:spec` when this milestone is active."
+
+**If no active milestone** (all existing milestones are "Complete" or there are none):
+- Set the first new milestone's status to "Pending — needs `/flow:spec`"
+- Update STATE.md to point to the new milestone as current
+
+## Step 6: Print Completion Message
+
+```
+Added [N] milestone(s) to the roadmap:
+[list of added milestones with version numbers]
+
+[If a milestone was activated:]
+v[X] [name] is now active. Run /flow:spec to plan it.
+
+[If milestones were just queued:]
+These will activate in order as you complete current milestones.
+```

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):
 
@@ -39,15 +37,31 @@ Use AskUserQuestion to gather project info. Ask these questions (you may combine
   - "cargo build && cargo test"
   - (Other — user types custom)
 
-**Question 4 — First milestone:**
-- "What's the first milestone?" (name + one-sentence goal)
+**Question 4 — Roadmap:**
+- "Do you already have a roadmap or list of milestones?" with options:
+  - "Yes — I'll paste or describe them"
+  - "No — let's figure it out together"
+
+**If user selects "Yes":**
+- Accept free text (bullet list, paragraph, pasted doc — any format)
+- Parse into milestones, each with a name + brief goal
+- Print back: "Here's what I got:" followed by the parsed list (e.g., "v1: Auth — user registration and login", "v2: Dashboard — analytics and settings")
+- Use AskUserQuestion to confirm: "Does this look right?" with options:
+  - "Yes — looks good"
+  - "Let me adjust" (user re-enters)
+
+**If user selects "No" (guided):**
+- Ask: "What's the first milestone?" (name + one-sentence goal)
+- Then: "Any more milestones you can see right now? List them, or skip to add them later with `/flow:milestone`." with options:
+  - "I have more to add" (user enters additional milestones)
+  - "That's it for now"
 
 **Question 5 — Brownfield scan:**
 - "Is this an existing codebase I should scan?" with options:
   - "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 +69,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 +90,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
@@ -95,6 +109,8 @@ Create these 5 files (create directories as needed):
 | Version | Milestone | Status | Phases |
 |---------|-----------|--------|--------|
 | v1 | [first milestone] | Pending — needs `/flow:spec` | TBD |
+[For each additional milestone:]
+| v[N] | [milestone name] | Planned | TBD |
 
 ---
 
@@ -103,8 +119,18 @@ Create these 5 files (create directories as needed):
 **Goal:** [milestone goal from user]
 
 **Phases:** Run `/flow:spec` to define implementation phases.
+
+[For each additional milestone:]
+
+## v[N]: [milestone name]
+
+**Goal:** [milestone goal]
+
+**Phases:** Run `/flow:spec` when this milestone is active.
 ```
 
+Note: The first milestone gets status "Pending — needs `/flow:spec`". All subsequent milestones get status "Planned". Each milestone gets its own section with its goal.
+
 **`CLAUDE.md`:**
 ```
 # [Project Name] — Claude Code Instructions
@@ -159,7 +185,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 +197,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.
@@ -45,9 +45,13 @@ Use this explicit decision tree:
 → Primary: `/flow:spec` to create the execution plan
 → Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
 
-**IF all phases are complete:**
+**IF all phases are complete AND a next milestone with status "Planned" exists in ROADMAP.md:**
+→ Primary: `/flow:done` to finalize this milestone (will auto-transition to next milestone)
+→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+
+**IF all phases are complete AND no next milestone exists:**
 → Primary: `/flow:done` to finalize this milestone
-→ Then: `/flow:init` to start the next milestone
+→ Then: `/flow:milestone` to add 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 +69,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/ROADMAP.md.template

@@ -5,6 +5,7 @@
 | Version | Milestone | Status | Phases |
 |---------|-----------|--------|--------|
 | v1 | {{FIRST_MILESTONE}} | Pending — needs `/flow:spec` | TBD |
+{{ADDITIONAL_MILESTONES_TABLE}}
 
 ---
 
@@ -13,3 +14,5 @@
 **Goal:** {{MILESTONE_GOAL}}
 
 **Phases:** Run `/flow:spec` to define implementation phases.
+
+{{ADDITIONAL_MILESTONES_SECTIONS}}

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