flow-cc 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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
+- Lessons system refactored to 2-stage with hard caps — `tasks/lessons.md` max 10 active one-liners, `CLAUDE.md ## Learned Rules` max 15 permanent one-liners
+- Replaced verbose PATTERN/CAUSE/FIX/RULE format with compact one-liner format: `- **[topic]** The rule`
+- Removed 4-stage lifecycle (Capture → Refine → Promote Global → Promote CLAUDE.md), replaced with 2-stage (Capture → Promote to CLAUDE.md when full)
+- Removed all references to `~/.claude/lessons.md` global lessons file
+- `/flow:done` now enforces cap: promotes most battle-tested lesson to CLAUDE.md when lessons.md hits 10
+- `/flow:status` shows `[N]/10 active` instead of `[N] rules`
+- Agent prompts section renamed from "Anti-Patterns to Avoid" to "Lessons (Rules to Follow)"
+- CLAUDE.md template now includes `## Learned Rules` placeholder section
+- Updated DESIGN.md, README.md, and all skill files to reflect 2-stage system
+
 ## [0.4.2] - 2026-02-11
 
 ### Fixed

package/README.md

@@ -26,7 +26,7 @@ Claude Code is powerful but unstructured. Without a system, you lose context bet
 Flow fixes this by giving 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
+- **PRDs become per-milestone execution contracts** in `.planning/prds/` — spec future milestones in parallel
 - **Session handoffs** preserve context across fresh sessions — no more "where was I?"
 - **Lessons compound** — mistakes get captured, refined, and promoted into permanent rules
 
@@ -42,7 +42,7 @@ Flow fixes this by giving Claude Code a **memory system and execution framework*
 ```
 
 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
+2. **`/flow:spec`** — Interviews you, then writes an executable PRD to `.planning/prds/` with phases, acceptance criteria, and agent-team structure. Can pre-spec future milestones.
 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
 
@@ -55,7 +55,7 @@ Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap u
 | 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:spec` | Once per milestone — interview that produces the PRD. Can pre-spec future milestones |
 | `/flow:go` | Once per phase — executes the next phase with agent teams |
 | `/flow:done` | End of session — updates docs, generates handoff prompt |
 
@@ -107,25 +107,23 @@ 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
+│   ├── prds/              # Per-milestone PRD specs (one file per milestone)
 │   └── archive/           # Completed milestones and old PRDs
 └── tasks/
-    └── lessons.md         # Mistake catalog → refined into permanent rules
+    └── lessons.md         # Active lessons (max 10 one-liners) → promoted to CLAUDE.md
 ```
 
 ## The Lessons System
 
 Flow's knowledge compounding is what makes it get better over time:
 
-1. **Capture** — Mistake happens, lesson written to `tasks/lessons.md`
-2. **Refine** — Each `/flow:done` merges duplicates, sharpens rules, removes obvious ones
-3. **Promote** — Universal lessons move to `~/.claude/lessons.md` (all projects)
-4. **Permanence** — Recurring patterns become rules in `CLAUDE.md`
+1. **Capture** — Mistake happens, one-liner written to `tasks/lessons.md` (max 10 active)
+2. **Promote** — When full, most battle-tested lesson moves to `CLAUDE.md ## Learned Rules` (max 15 permanent)
 
-The goal: fewer, sharper lessons over time — not an ever-growing list.
+Hard caps prevent context bloat. Total worst-case: ~30 lines of lessons context per session.
 
 ## Compatible With GSD
 

package/VERSION

@@ -1 +1 @@
-0.4.2
+0.5.0

package/package.json

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

@@ -17,9 +17,9 @@ You are executing the `/flow:done` skill. This finalizes the current session by
 Read these files (in parallel where possible):
 - `.planning/STATE.md` — current state
 - `.planning/ROADMAP.md` — milestone/phase progress
-- `tasks/lessons.md` — existing lessons
+- `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.
@@ -83,9 +85,14 @@ Structure:
   - "No new lessons"
   - "Yes, let me add some" (user types them)
   - "Use your suggestions" (if you auto-suggested any)
-- Add new lessons in PATTERN/CAUSE/FIX/RULE format
-- **Refine existing lessons:** merge duplicates, sharpen vague rules, delete obvious ones
-- **Promote check:** For lessons that seem universal (not project-specific), ask: "This lesson seems universal. Promote to global lessons (~/.claude/lessons.md)?"
+- Add new lessons as one-liners: `- **[topic]** The rule`
+- **Hard cap enforcement (max 10 active):**
+  - If lessons.md already has 10 items and a new one needs to be added:
+    1. Identify the most battle-tested/internalized lesson
+    2. Promote it to `CLAUDE.md ## Learned Rules` section
+    3. Delete it from lessons.md
+    4. Add the new lesson
+  - If `CLAUDE.md ## Learned Rules` hits 15 items, delete the most obvious/internalized rule to make room
 
 ### 5. Commit Doc Updates
 
@@ -99,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):
@@ -119,7 +126,7 @@ Print the handoff prompt in a fenced code block so the user can copy it.
 Session complete.
 - STATE.md: updated
 - ROADMAP.md: [N] phases marked complete
-- lessons.md: [N] lessons added, [N] refined
+- lessons.md: [N]/10 active, [N] promoted to CLAUDE.md
 - Committed: [SHA]
 
 Handoff prompt:

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
-- `tasks/lessons.md` — anti-patterns to avoid
+- 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
@@ -76,7 +88,7 @@ so agents have it in their context without needing to search.]
 - Stage only your files when committing (never `git add .` or `git add -A`)
 - If you need output from another agent that isn't available yet, create a temporary stub and continue. Delete the stub before your final commit.
 
-## Anti-Patterns to Avoid
+## Lessons (Rules to Follow)
 [Relevant lessons from tasks/lessons.md — filter to lessons that apply to this agent's work]
 ```
 
@@ -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
@@ -64,7 +67,7 @@ Flow is 6 commands that turn your specs into shipped code through agent teams. E
 - 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
+- Captures lessons as one-liners, enforces 10-item cap (promotes to CLAUDE.md when full)
 - Commits doc updates
 - Generates a handoff prompt you copy-paste to start the next session
 

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.
 
@@ -169,20 +170,15 @@ Note: The first milestone gets status "Pending — needs `/flow:spec`". All subs
 
 **`tasks/lessons.md`:**
 ```
-# [Project Name] — Lessons Learned
+# [Project Name] — Lessons (max 10 active)
 
-Format: PATTERN → CAUSE → FIX → RULE
+One-liner format: `- **[topic]** The rule`
 
-## Execution Patterns
-<!-- Lessons about workflow, delegation, verification -->
-
-## Domain Knowledge
-<!-- Lessons about business logic, data models, user behavior -->
-
-## Technical Patterns
-<!-- Lessons about the tech stack, libraries, deployment -->
+<!-- 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
@@ -192,7 +188,8 @@ Project initialized:
 - CLAUDE.md — project execution rules
 - .planning/STATE.md — session GPS
 - .planning/ROADMAP.md — milestone tracker
-- tasks/lessons.md — anti-pattern catalog
+- 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** — default to the current milestone from STATE.md "Milestone" field.
+
+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]
@@ -222,7 +245,7 @@ Write `PRD.md` to the project root with this EXACT structure:
 2. Verify after every phase: [verification commands from CLAUDE.md]
 3. Atomic commits after each agent's work lands
 4. Never `git add .` — stage specific files only
-5. Read `tasks/lessons.md` before spawning agents — inject relevant anti-patterns
+5. Read `tasks/lessons.md` before spawning agents — inject relevant lessons into agent prompts
 
 ## Definition of Done
 - [ ] All user story acceptance criteria pass
@@ -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)
 
@@ -64,11 +66,20 @@ Use this explicit decision tree:
 Milestone: [name] ([X/Y] phases complete)
 Last session: [date] — [what was built]
 Next: Phase [N] — [name] ([short description])
-Lessons: [N] rules
+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,15 +98,16 @@ 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:
 - "Any lessons from this task worth capturing?"
   - Option 1: "No, nothing new" — Skip lessons.
-  - Option 2: "Yes, let me describe it" — Capture to `tasks/lessons.md` in PATTERN/CAUSE/FIX/RULE format.
+  - Option 2: "Yes, let me describe it" — Capture to `tasks/lessons.md` as a one-liner: `- **[topic]** The rule`
 
 If `tasks/lessons.md` doesn't exist, skip the lessons prompt.
+If lessons.md already has 10 items, promote the most battle-tested to `CLAUDE.md ## Learned Rules` before adding the new one.
 
 ## Step 9 — Summary
 

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.
 
@@ -23,9 +23,12 @@
 ## Session-End Docs (MANDATORY)
 1. `.planning/STATE.md` — replace session notes (don't append), keep <80 lines
 2. `.planning/ROADMAP.md` — update phase progress
-3. `tasks/lessons.md` — add new lessons, refine existing ones
+3. `tasks/lessons.md` — add new one-liner lessons, enforce max 10 cap (promote to Learned Rules when full)
 4. Commit doc updates to feature branch
 
+## Learned Rules
+<!-- Max 15 permanent one-liners promoted from tasks/lessons.md -->
+
 ## Critical Rules
 - No assumptions — ask if requirements unclear
 - Fight entropy — leave code better than you found it

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

package/templates/lessons.md.template

@@ -1,22 +1,5 @@
-# {{PROJECT_NAME}} — Lessons Learned
+# {{PROJECT_NAME}} — Lessons (max 10 active)
 
-Format: PATTERN → CAUSE → FIX → RULE
+One-liner format: `- **[topic]** The rule`
 
-## Execution Patterns
-<!-- Lessons about workflow, delegation, verification -->
-
-<!-- EXAMPLE (replace with real lessons as you work):
-
-### Agent context overflow on large files
-- **PATTERN:** Spawned agent tried to read a 2000-line file and ran out of context before finishing its task
-- **CAUSE:** Agent prompt didn't specify which lines/functions to read — it read the whole file
-- **FIX:** Added explicit line ranges and function names to the agent prompt
-- **RULE:** Always tell agents exactly which functions/sections to read. Never say "read file.ts" — say "read file.ts lines 50-120 (the handleSubmit function)"
-
-END EXAMPLE -->
-
-## Domain Knowledge
-<!-- Lessons about business logic, data models, user behavior -->
-
-## Technical Patterns
-<!-- Lessons about the tech stack, libraries, deployment -->
+<!-- EXAMPLE: - **[agent context]** Always tell agents exactly which functions/lines to read — never "read file.ts", say "read file.ts lines 50-120" -->