flow-cc 0.3.0 → 0.4.0

package/CHANGELOG.md

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

package/README.md

@@ -30,39 +30,49 @@ 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: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 |
-| `/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:setup → /flow:spec → /flow:go (repeat per phase) → /flow:done
-                                                             ↓
-                                               handoff prompt for next session
-                                                             ↓
-                                               /flow:milestone → next cycle
+**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: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
-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
 

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

package/bin/install.js

@@ -322,8 +322,8 @@ Flow v${version} installed successfully!
 
 Commands available:
   /flow:intro      \u2014 Learn the Flow workflow
-  /flow:setup      \u2014 Set up a new project
-  /flow:milestone  \u2014 Start a new milestone
+  /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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.3.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:milestone 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-intro.md

@@ -20,25 +20,26 @@ Flow is 6 commands that turn your specs into shipped code through agent teams. E
 
 ```
 /flow:setup → /flow:spec → /flow:go (repeat) → /flow:done
-                                                    ↓
-                                        handoff prompt for next session
-                                                    ↓
-                                        /flow:milestone → next cycle
+  (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:setup`** — Run once per project
-- Asks you 4-5 questions (what is it, tech stack, verify commands, first milestone)
+- 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`
 - 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: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
@@ -62,6 +63,7 @@ Flow is 6 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

package/skills/flow-milestone.md

@@ -1,12 +1,12 @@
 ---
 name: flow:milestone
-description: Archive completed milestone and start a new one
+description: Add new milestones to the roadmap
 user_invocable: true
 ---
 
-# /flow:milestone — Start New Milestone
+# /flow:milestone — Add New Milestones
 
-You are executing the `/flow:milestone` skill. This archives the current milestone and sets up a new one.
+You are executing the `/flow:milestone` skill. This adds new milestones to the project roadmap.
 
 ## Guard: Project Must Exist
 
@@ -17,51 +17,62 @@ Check if `.planning/STATE.md` exists:
 ## 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
+- Current milestone status (what's active, what's complete, what's planned)
+- What version numbers are already used
 
-## Step 2: Check for Pending Phases
+## Step 2: Show Current Status
 
-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.**
+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: Ask Milestone Question
+## Step 3: Check for Active Work
 
-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)
+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: Archive Completed Milestone
+## Step 4: Gather New Milestones
 
-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")
+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:**
-- Add new milestone row to the table
-- Add new milestone section with goal and "Run `/flow:spec` to define phases"
+- 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."
 
-**STATE.md:**
-- Replace with fresh state for the new milestone
-- Reset phase progress table
-- Note the milestone transition in "What Was Built"
+**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
 
 ```
-Milestone [name] (v[X]) initialized.
-- Archived: previous milestone details + PRD
-- Updated: ROADMAP.md, STATE.md
+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.
 
-Run `/flow:spec` to build the PRD for this milestone.
+[If milestones were just queued:]
+These will activate in order as you complete current milestones.
 ```

package/skills/flow-setup.md

@@ -37,8 +37,24 @@ 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:
@@ -93,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 |
 
 ---
 
@@ -101,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

package/skills/flow-status.md

@@ -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:milestone` 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):**

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