flow-cc 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.5.0] - 2026-02-13
+
+### Added
+- Multi-PRD support — PRDs now live at `.planning/prds/{version-slug}.md` instead of a single root `PRD.md`
+- 5-step PRD resolution logic across all skills: user argument → STATE.md Active PRD → slug derivation → legacy fallback → not found
+- `**Milestone:**` header field in PRDs for ROADMAP correlation
+- `Active PRD` field in STATE.md tracking the current milestone's PRD path
+- Milestone Targeting in `/flow:spec` — pass a milestone name to pre-spec future milestones in parallel
+- PRD inventory display in `/flow:status` showing active/ready tags per PRD file
+- `/flow:setup` now creates `.planning/prds/` directory during project scaffolding
+
+### Changed
+- `/flow:spec` writes PRDs to `.planning/prds/{version-slug}.md` (was root `PRD.md`)
+- `/flow:go` resolves PRDs via 5-step resolution instead of hardcoded `PRD.md`
+- `/flow:done` archives PRDs from `.planning/prds/` to `.planning/archive/PRD-{slug}.md`
+- `/flow:status` lists all PRDs in `.planning/prds/` with active/ready status
+- `/flow:task` reads active PRD from `.planning/prds/` via STATE.md
+- All templates and docs updated to reflect new PRD paths
+- Legacy root `PRD.md` still consumed transparently — migration happens organically
+
 ## [0.4.3] - 2026-02-12
 
 ### Changed

package/README.md

@@ -19,17 +19,22 @@ npx flow-cc
 
 One command. Installs skills, hooks, templates, and configures your statusLine. Works on Mac, Linux, and Windows.
 
+---
+
 ## Why Flow?
 
 Claude Code is powerful but unstructured. Without a system, you lose context between sessions, repeat mistakes, and waste tokens re-explaining what you've already decided.
 
-Flow fixes this by giving Claude Code a **memory system and execution framework**:
+Flow gives Claude Code a **memory system and execution framework**:
 
 - **Spec interviews** extract decisions upfront so agents execute instead of guessing
-- **PRDs become execution contracts** that agent teams follow phase-by-phase
-- **Session handoffs** preserve context across fresh sessions — no more "where was I?"
+- **Per-milestone PRDs** in `.planning/prds/` become execution contracts — spec future milestones in parallel
+- **Wave-based agent teams** execute phases autonomously with built-in verification
+- **Session handoffs** preserve full 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:
@@ -48,38 +53,101 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 
 Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap up. Next session, paste the handoff prompt and keep going.
 
+---
+
+## Multi-PRD: Parallel Milestone Planning
+
+<table>
+<tr>
+<td width="50%">
+
+**Before (single PRD)**
+```
+project/
+└── PRD.md          ← one at a time
+```
+Finish or archive the current milestone before speccing the next. Serial bottleneck on large roadmaps.
+
+</td>
+<td width="50%">
+
+**Now (per-milestone PRDs)**
+```
+.planning/prds/
+├── v1-user-auth.md       ← active
+├── v2-dashboard.md       ← pre-specced
+└── v3-payments.md        ← pre-specced
+```
+Spec any milestone at any time. Execute the current one while planning ahead.
+
+</td>
+</tr>
+</table>
+
+**How it works:**
+
+- `/flow:spec` writes PRDs to `.planning/prds/{version-slug}.md` — one file per milestone
+- `/flow:spec v3: Payments` targets a specific future milestone without changing your current position
+- STATE.md tracks the **Active PRD** field so `/flow:go` always knows which spec to execute
+- Smart resolution: user argument > STATE.md > slug derivation > legacy fallback
+- Existing `PRD.md` at root? Still works — legacy files are consumed transparently and migrated on archive
+
+---
+
 ## Commands
 
-**The build cycle:**
+### The Build Cycle
+
+| Command | When | What it does |
+|---|---|---|
+| `/flow:setup` | Once per project | Creates `.planning/`, CLAUDE.md, templates, full roadmap |
+| `/flow:spec` | Once per milestone | Interview that produces an executable PRD in `.planning/prds/` |
+| `/flow:go` | Once per phase | Executes the next phase with wave-based agent teams |
+| `/flow:done` | End of session | Updates docs, captures lessons, generates handoff prompt |
+
+### Standalone
+
+| Command | When | What it does |
+|---|---|---|
+| `/flow:task` | Anytime | Bug fixes, cleanup, small features — no PRD needed |
+| `/flow:milestone` | Anytime | Add new milestones to the roadmap |
+
+### Utility
 
-| 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 |
+| Command | When | What it does |
+|---|---|---|
+| `/flow:intro` | First time | Walkthrough of the entire system |
+| `/flow:status` | Anytime | Where am I? What's next? Shows PRD inventory |
+| `/flow:update` | Anytime | Update Flow to the latest version |
 
-**Standalone:**
+---
+
+## Project Structure
 
-| Command | When to use |
-|---|---|
-| `/flow:task` | Anytime — bug fixes, cleanup, small features (no PRD needed) |
-| `/flow:milestone` | Anytime — add new milestones to the roadmap |
+Every Flow project gets this structure via `/flow:setup`:
 
-**Utility:**
+```
+your-project/
+├── CLAUDE.md                    # Execution rules + learned rules
+├── .planning/
+│   ├── STATE.md                 # Session GPS — current status, active PRD, next actions
+│   ├── ROADMAP.md               # Milestone phases and progress tracking
+│   ├── prds/                    # Per-milestone PRD specs
+│   │   ├── v1-user-auth.md      #   One file per milestone
+│   │   └── v2-dashboard.md      #   Pre-spec future milestones anytime
+│   └── archive/                 # Completed milestones and archived PRDs
+└── tasks/
+    └── lessons.md               # Active lessons (max 10) → promoted to CLAUDE.md
+```
 
-| 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-setup.md         # 9 skill files
+│   ├── flow-setup.md            # 9 skill files
 │   ├── flow-milestone.md
 │   ├── flow-spec.md
 │   ├── flow-go.md
@@ -89,32 +157,18 @@ Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap u
 │   ├── flow-intro.md
 │   ├── flow-update.md
 │   ├── VERSION
-│   └── templates/            # Project scaffolding templates
+│   └── templates/               # Project scaffolding templates
 │       ├── CLAUDE.md.template
 │       ├── STATE.md.template
 │       ├── ROADMAP.md.template
 │       └── lessons.md.template
 ├── hooks/
-│   ├── flow-check-update.js  # Notifies when updates are available
-│   └── flow-statusline.js    # Shows project context in statusLine
-└── settings.json             # statusLine configured automatically
+│   ├── flow-check-update.js     # Notifies when updates are available
+│   └── flow-statusline.js       # Shows project context in statusLine
+└── settings.json                # statusLine configured automatically
 ```
 
-## Project Structure
-
-Every Flow project gets this structure via `/flow:setup`:
-
-```
-your-project/
-├── CLAUDE.md              # Project-specific execution rules
-├── PRD.md                 # Current milestone spec (created by /flow:spec)
-├── .planning/
-│   ├── STATE.md           # Session GPS — current status, next actions
-│   ├── ROADMAP.md         # Milestone phases and progress
-│   └── archive/           # Completed milestones and old PRDs
-└── tasks/
-    └── lessons.md         # Active lessons (max 10 one-liners) → promoted to CLAUDE.md
-```
+---
 
 ## The Lessons System
 
@@ -125,9 +179,13 @@ Flow's knowledge compounding is what makes it get better over time:
 
 Hard caps prevent context bloat. Total worst-case: ~30 lines of lessons context per session.
 
+---
+
 ## Compatible With GSD
 
-Flow uses the same `.planning/` directory structure as [GSD](https://github.com/gsd-framework/gsd). You can use `/gsd:debug`, `/gsd:map-codebase`, and other GSD commands alongside Flow.
+Flow uses the same `.planning/` directory structure as [GSD](https://github.com/gsd-framework/gsd). You can use `/gsd:debug`, `/gsd:map-codebase`, and other GSD commands alongside Flow without conflict.
+
+---
 
 ## Requirements
 

package/VERSION

@@ -1 +1 @@
-0.4.3
+0.5.0

package/package.json

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

@@ -19,7 +19,7 @@ Read these files (in parallel where possible):
 - `.planning/ROADMAP.md` — milestone/phase progress
 - `tasks/lessons.md` — active lessons (max 10)
 - `CLAUDE.md` — project rules
-- `PRD.md` — current spec (if exists)
+- Active PRD from `.planning/prds/` (resolve via STATE.md "Active PRD" field, or fall back to legacy `PRD.md` at root)
 
 Also gather:
 - Run `git log --oneline -20` to see commits this session
@@ -38,6 +38,7 @@ Structure:
 - **Milestone:** [name] (vX)
 - **Phase:** [current phase status]
 - **Branch:** [current branch]
+- **Active PRD:** [path to active PRD, or "None" if milestone complete]
 - **Last Session:** [today's date]
 
 ## Milestone Progress
@@ -69,7 +70,8 @@ Structure:
   - Create `.planning/archive/` if it doesn't already exist (use `mkdir -p` or equivalent)
   - Move milestone phase details to `.planning/archive/milestones-vX.md`
   - Keep only the summary row in the ROADMAP milestone table
-  - Move `PRD.md` to `.planning/archive/PRD-vX.md`
+  - Archive the milestone's PRD: move `.planning/prds/{slug}.md` to `.planning/archive/PRD-{slug}.md`. If using legacy root `PRD.md`, move it to `.planning/archive/PRD-vX.md` instead.
+  - Clear STATE.md "Active PRD" field (set to "None")
   - 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.
@@ -104,7 +106,7 @@ 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).
+  Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md (US-X).
   [One sentence of context]. [One sentence of what NOT to do if relevant].
   ```
 - If milestone is complete AND a next milestone was transitioned to (from Step 3):

package/skills/flow-go.md

@@ -10,24 +10,36 @@ You are executing the `/flow:go` skill. This reads the PRD, identifies the next
 
 **Core principle:** The PRD is the execution contract. You execute what it specifies. Do not freelance.
 
-**Plan mode warning:** Do NOT use this skill with plan mode enabled. `/flow:go` is execution — plan mode's read-only constraint prevents it from creating files, running agents, and committing work. The PRD IS your plan; run `/flow:go` in normal mode.
+**Plan mode warning:** Do NOT use this skill with plan mode enabled. `/flow:go` is execution — plan mode's read-only constraint prevents it from creating files, running agents, and committing work. The PRD is your plan; run `/flow:go` in normal mode.
 
 ## Step 1 — Orient
 
 Read these files (in parallel):
 - `.planning/STATE.md` — current position
 - `.planning/ROADMAP.md` — phase progress
-- `PRD.md` — the execution spec
+- The active PRD (see PRD Resolution below)
 - `tasks/lessons.md` — active lessons (max 10 one-liners)
 - `CLAUDE.md` — execution rules and verification commands
 
+### PRD Resolution
+
+Resolve the PRD file to use, in this order:
+
+1. **User argument:** If the user passed an argument to `/flow:go` (e.g., `/flow:go v3-payments`), match it against files in `.planning/prds/` (by slug or milestone name from the `**Milestone:**` header field).
+2. **STATE.md Active PRD:** Read the "Active PRD" field from STATE.md's Current Position section. If it points to a valid file, use it.
+3. **Slug derivation:** Derive a slug from STATE.md's current milestone name — version-prefix + lowercase name, spaces/special chars → hyphens, collapse consecutive hyphens (e.g., "v2: Dashboard Analytics" → `v2-dashboard-analytics`). Check `.planning/prds/{slug}.md`.
+4. **Legacy fallback:** If `.planning/prds/` is empty or missing but `PRD.md` exists at the project root, use it. Print: "Using legacy PRD.md at project root. Future specs will use `.planning/prds/`."
+5. **Not found:** "No PRD found for [current milestone name]. Available PRDs: [list files in `.planning/prds/`]. Run `/flow:spec` first."
+
+**Milestone match check:** After resolving the PRD, read its `**Milestone:**` header field. If it doesn't match STATE.md's current milestone, warn: "PRD milestone ([PRD milestone]) doesn't match current milestone ([STATE milestone]). Continuing, but verify you're executing the right spec."
+
 **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."
+1. **PRD resolved?** If PRD Resolution (above) reached step 5 (not found): stop with the "No PRD found" message and available PRD list.
 2. **Phase detailed enough?** The phase section in the PRD must have:
    - Wave structure with agent assignments
    - Explicit file lists per agent
@@ -146,6 +158,7 @@ Create an atomic commit for this phase:
 - Files created/modified (count + key names)
 - Commit SHA
 - Phase completion note
+- Keep "Active PRD" field pointing to the resolved PRD path
 
 **ROADMAP.md:** Mark this phase as "Complete ([today's date])"
 

package/skills/flow-intro.md

@@ -24,6 +24,8 @@ Flow is 6 commands that turn your specs into shipped code through agent teams. E
   full roadmap)  |     auto-transitions to          |
                  +---- next planned milestone ------+
 
+/flow:spec ← can pre-spec future milestones (each gets its own PRD in .planning/prds/)
+
 /flow:milestone ← add milestones to roadmap anytime
 /flow:task      ← standalone path for bug fixes, cleanup, small features (no PRD needed)
 ```
@@ -50,8 +52,9 @@ Flow is 6 commands that turn your specs into shipped code through agent teams. E
 **`/flow:spec`** — Run once per milestone
 - Interviews you about scope, user stories, technical design, trade-offs, and phasing
 - You can say "done" or "that's enough" anytime to cut the interview short
-- Produces `PRD.md` — the execution contract with wave-based phases, file lists, and acceptance criteria
-- Updates ROADMAP and STATE to reflect the plan
+- Produces `.planning/prds/{milestone}.md` — the execution contract with wave-based phases, file lists, and acceptance criteria
+- Can pre-spec future milestones in parallel terminal windows (each milestone gets its own PRD file)
+- Updates ROADMAP and STATE to reflect the plan (for the current milestone; future milestone specs skip STATE updates)
 
 **`/flow:go`** — Run once per phase (this is where the work happens)
 - Reads the PRD, finds the next pending phase

package/skills/flow-setup.md

@@ -81,6 +81,7 @@ Create these 5 files (create directories as needed):
 - **Milestone:** [first milestone name] (v1)
 - **Phase:** Not started — run `/flow:spec` to build PRD
 - **Branch:** main
+- **Active PRD:** None — run `/flow:spec` to create
 - **Last Session:** [today's date]
 
 ## Milestone Progress
@@ -145,10 +146,10 @@ Note: The first milestone gets status "Pending — needs `/flow:spec`". All subs
 1. Read this file (CLAUDE.md)
 2. Read `.planning/STATE.md` for current status
 3. Read `.planning/ROADMAP.md` for milestone progress
-4. Read `PRD.md` for current execution spec (if one exists)
+4. Read active PRD from `.planning/prds/` for current milestone (if one exists)
 
 ## Execution Rules
-- **Plan before building.** For non-trivial work, read the PRD phase section before touching anything.
+- **Plan before building.** For non-trivial work, read the milestone's PRD in `.planning/prds/` before touching anything.
 - **Delegate immediately.** If a task touches 3+ files, spawn an agent team within your first 2 tool calls.
 - **Verify everything.** Run [verification commands from user] after agent work lands. Nothing is done until proven.
 
@@ -176,6 +177,8 @@ One-liner format: `- **[topic]** The rule`
 <!-- EXAMPLE: - **[agent context]** Always tell agents exactly which functions/lines to read — never "read file.ts", say "read file.ts lines 50-120" -->
 ```
 
+**`.planning/prds/`** — Create this empty directory (use `mkdir -p` via Bash). PRDs are stored here per-milestone.
+
 **`.planning/archive/`** — Create this empty directory (use `mkdir -p` via Bash).
 
 ## Step 4: Print Completion Message
@@ -186,6 +189,7 @@ Project initialized:
 - .planning/STATE.md — session GPS
 - .planning/ROADMAP.md — milestone tracker
 - tasks/lessons.md — active lessons (max 10)
+- .planning/prds/ — per-milestone PRD specs
 - .planning/archive/ — for completed milestones
 
 Run `/flow:spec` to plan your first milestone.

package/skills/flow-spec.md

@@ -10,13 +10,16 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 
 **Interview mode:** Always thorough by default. The user can say "done", "finalize", "that's enough", or "move on" at ANY time to wrap up early. Respect their signal and finalize with whatever depth has been achieved.
 
-**Plan mode warning:** Do NOT use this skill with plan mode enabled. Plan mode's read-only constraint prevents PRD.md from being written during the interview. `/flow:spec` IS the planning phase — plan mode on top of it is redundant and breaks the workflow.
+**Plan mode warning:** Do NOT use this skill with plan mode enabled. Plan mode's read-only constraint prevents the PRD from being written during the interview. `/flow:spec` IS the planning phase — plan mode on top of it is redundant and breaks the workflow.
 
 ## Phase 1 — Context Gathering (automatic, no user input needed)
 
 1. Read `.planning/STATE.md` and `.planning/ROADMAP.md` — understand current milestone and what's done
 2. Read `CLAUDE.md` — understand project rules and tech stack
-3. Read `PRD.md` if it exists — check for existing spec to build on
+3. Check for existing PRD:
+   - List `.planning/prds/` directory (if it exists) for existing PRD files
+   - Also check for legacy `PRD.md` at project root (backward compat)
+   - If a PRD exists for the target milestone, note it for resume/extend flow
 4. **Codebase scan** (brownfield projects) — spawn **3 parallel Explore subagents** via the Task tool to scan the codebase without consuming main context:
 
    | Agent | Focus | Looks For |
@@ -34,6 +37,25 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 
 5. **Assemble summaries:** Collect the 3 agent summaries into a brief context block (~45 lines total). Print to user: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
 
+## Milestone Targeting
+
+Before starting the interview, determine which milestone this PRD targets:
+
+1. **If the user passed an argument** (e.g., `/flow:spec v3: Payments`) — match against ROADMAP.md milestones. If no match, print available milestones and ask which one.
+
+2. **If no argument** — read ROADMAP.md and list all incomplete milestones. Use AskUserQuestion to let the user pick which milestone to spec. Pre-select the current milestone from STATE.md as the first option (marked as "current"). If only one incomplete milestone exists, skip the prompt and use it directly.
+
+3. **Derive the PRD slug:** Take the milestone's version prefix and name (e.g., "v3: Dashboard Analytics"), lowercase it, replace spaces and special characters with hyphens, collapse consecutive hyphens. Result: `v3-dashboard-analytics`. The PRD path is `.planning/prds/{slug}.md`.
+
+4. **Check for existing PRD at that path:**
+   - **If PRD exists** → Use AskUserQuestion: "A PRD already exists for this milestone at `.planning/prds/{slug}.md`. What would you like to do?"
+     - "Resume editing" — load the existing PRD and continue the interview from where it left off
+     - "Start fresh" — delete the existing PRD and start a new interview
+     - "Pick a different milestone" — show available milestones
+   - **If no PRD exists** → Proceed with a fresh interview
+
+5. **Future milestone detection:** If the target milestone is NOT the current milestone in STATE.md, note this — the PRD will be written but STATE.md's "Active PRD" field will NOT be updated (it stays pointing at the current milestone's PRD). Print: "Speccing future milestone [name]. STATE.md will not be updated — this PRD will be available when you reach this milestone."
+
 ## Phase 2 — Adaptive Interview
 
 ### CRITICAL RULES (follow these exactly)
@@ -50,7 +72,7 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 
 3. **CONTINUE UNTIL THE USER SAYS STOP.** Do NOT stop after covering all 7 areas once. After each answer, immediately ask the next question. Keep going deeper until the user says "done", "finalize", "that's enough", "ship it", or similar. A thorough interview is 15-30 questions, not 5.
 
-4. **MAINTAIN A RUNNING DRAFT.** Every 2-3 questions, update PRD.md with what you've learned so far. Print: "Updated PRD draft — added [brief summary]." The user should see the spec taking shape in real-time, not all at the end.
+4. **MAINTAIN A RUNNING DRAFT.** Every 2-3 questions, update `.planning/prds/{slug}.md` with what you've learned so far (create `.planning/prds/` directory if it doesn't exist). Print: "Updated PRD draft — added [brief summary]." The user should see the spec taking shape in real-time, not all at the end.
 
 5. **BE ADAPTIVE.** Base your next question on the previous answer. If the user reveals something surprising, probe deeper on THAT — don't robotically move to the next category. The best specs come from following interesting threads.
 
@@ -140,11 +162,12 @@ If any check fails, print what's missing and use AskUserQuestion:
 
 ### Write PRD
 
-Write `PRD.md` to the project root with this EXACT structure:
+Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory first if it doesn't exist) with this EXACT structure:
 
 ```markdown
 # [Milestone Name] — Specification
 
+**Milestone:** [full milestone name, e.g., "v3: Dashboard Analytics"]
 **Status:** Ready for execution
 **Branch:** feat/[milestone-slug]
 **Created:** [today's date]
@@ -233,21 +256,25 @@ Write `PRD.md` to the project root with this EXACT structure:
 
 ## Phase 4 — Post-PRD Updates
 
-After writing PRD.md:
+After writing the PRD to `.planning/prds/{slug}.md`:
 
 1. **Update ROADMAP.md:** Add phase breakdown under the current milestone section. Each phase gets a row in the progress table with status "Pending".
 
-2. **Update STATE.md:** Set current phase to "Phase 1 — ready for `/flow:go`". Update "Next Actions" to reference the first phase.
+2. **Update STATE.md** (current milestone only):
+   - Set current phase to "Phase 1 — ready for `/flow:go`"
+   - Set "Active PRD" to `.planning/prds/{slug}.md`
+   - Update "Next Actions" to reference the first phase
+   - **Skip this step if speccing a future milestone** — STATE.md stays pointing at the current milestone. Print: "PRD written to `.planning/prds/{slug}.md`. STATE.md not updated (future milestone)."
 
 3. **Generate Phase 1 handoff prompt:**
    ```
-   Phase 1: [Name] — [short description]. Read STATE.md, ROADMAP.md, and PRD.md.
+   Phase 1: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md.
    [One sentence of context about what Phase 1 builds].
    ```
 
 4. Print the handoff prompt in a fenced code block.
 
-5. Print: "PRD ready. Run `/flow:go` to execute Phase 1, or review PRD.md first."
+5. Print: "PRD ready at `.planning/prds/{slug}.md`. Run `/flow:go` to execute Phase 1, or review the PRD first."
 
 ## Quality Gates
 
@@ -256,6 +283,7 @@ Before finalizing, self-check the PRD:
 - [ ] Every user story has checkbox acceptance criteria that are testable
 - [ ] Every phase has verification commands
 - [ ] "Key Existing Code" section references actual files/functions found in the codebase scan
+- [ ] PRD is written to `.planning/prds/{slug}.md`, NOT to root `PRD.md`
 - [ ] No phase has more than 5 agents in a single wave (too many = coordination overhead)
 - [ ] Sacred code section is populated (even if empty with "None identified")
 

package/skills/flow-status.md

@@ -13,7 +13,9 @@ You are executing the `/flow:status` skill. This is a READ-ONLY operation. Do NO
 Read ALL of the following in parallel:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
-- `PRD.md` (if exists)
+- List `.planning/prds/` directory for all PRD files (if directory exists)
+- Also check for legacy `PRD.md` at project root (backward compat)
+- Read the active PRD (from STATE.md "Active PRD" field) to get phase details
 - Count lessons in `tasks/lessons.md` (if exists)
 
 IF both STATE.md AND ROADMAP.md are missing:
@@ -36,12 +38,12 @@ RULE: Determine the next action from ROADMAP.md phase statuses, NOT from STATE.m
 
 Use this explicit decision tree:
 
-**IF pending phases exist in ROADMAP AND PRD.md exists:**
+**IF pending phases exist in ROADMAP AND a PRD exists for the current milestone (in `.planning/prds/` or legacy root):**
 → Primary: `/flow:go` to execute Phase [N]: [name]
 → Alt: `/flow:done` if wrapping up the session
 → Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
 
-**IF pending phases exist in ROADMAP BUT PRD.md is missing:**
+**IF pending phases exist in ROADMAP BUT no PRD exists for the current milestone:**
 → Primary: `/flow:spec` to create the execution plan
 → Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
 
@@ -66,9 +68,18 @@ Last session: [date] — [what was built]
 Next: Phase [N] — [name] ([short description])
 Lessons: [N]/10 active
 
+PRDs:
+  * {slug}.md (active — current milestone)
+  [For each additional PRD in .planning/prds/:]
+  * {slug}.md (ready — future milestone)
+  [If legacy PRD.md at root:]
+  * PRD.md (legacy — at project root)
+
 [routing recommendations from Step 3]
 ```
 
+The PRDs section shows all PRD files found. Mark the one matching STATE.md's "Active PRD" as "(active — current milestone)". Mark others as "(ready — future milestone)". If a legacy root `PRD.md` exists, show it as "(legacy — at project root)". Omit the PRDs section entirely if no PRD files exist anywhere.
+
 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

@@ -20,7 +20,7 @@ Read ALL of the following in parallel. If any file is missing, skip it gracefull
 - `.planning/ROADMAP.md`
 - `CLAUDE.md`
 - `tasks/lessons.md`
-- `PRD.md`
+- Active PRD from `.planning/prds/` (if STATE.md "Active PRD" field exists, use that path; else check for legacy `PRD.md` at root)
 
 If no `.planning/` directory exists, print:
 > No `.planning/` directory found — running standalone. Task will still be executed, verified, and committed.
@@ -98,7 +98,7 @@ IF `.planning/STATE.md` exists:
 
 RULES:
 - DO NOT update ROADMAP.md — tasks are not milestone phases.
-- DO NOT update PRD.md — tasks are not part of the spec.
+- DO NOT update any PRD files in `.planning/prds/` — tasks are not part of the spec.
 - DO NOT create `.planning/` if it doesn't exist.
 
 Quick lessons prompt via AskUserQuestion:

package/templates/CLAUDE.md.template

@@ -9,10 +9,10 @@
 1. Read this file (CLAUDE.md)
 2. Read `.planning/STATE.md` for current status
 3. Read `.planning/ROADMAP.md` for milestone progress
-4. Read `PRD.md` for current execution spec (if one exists)
+4. Read active PRD from `.planning/prds/` for current milestone (if one exists)
 
 ## Execution Rules
-- **Plan before building.** For non-trivial work, read the PRD phase section before touching anything.
+- **Plan before building.** For non-trivial work, read the milestone's PRD in `.planning/prds/` before touching anything.
 - **Delegate immediately.** If a task touches 3+ files, spawn an agent team within your first 2 tool calls.
 - **Verify everything.** Run {{VERIFY_COMMANDS}} after agent work lands. Nothing is done until proven.
 

package/templates/STATE.md.template

@@ -4,6 +4,7 @@
 - **Milestone:** {{FIRST_MILESTONE}} (v1)
 - **Phase:** Not started — run `/flow:spec` to build PRD
 - **Branch:** main
+- **Active PRD:** None — run `/flow:spec` to create
 - **Last Session:** {{DATE}}
 
 ## Milestone Progress