flow-cc 0.7.1 → 0.8.0

package/skills/flow-intro.md

@@ -23,9 +23,9 @@ Flow is a structured workflow for Claude Code. Four core commands that turn your
   (intake)       (plan)       (build)              (wrap)
                     ↑                                 |
                     |     auto-transitions to          |
-                    +---- next planned milestone ------+
+                    +---- next planned project --------+
 
-/flow:spec ← can pre-spec future milestones (each gets its own PRD in .planning/prds/)
+/flow:spec ← can pre-spec future projects (each gets its own PRD in .planning/prds/)
 
 /flow:task ← standalone path for bug fixes, cleanup, small features (no PRD needed)
 ```
@@ -33,48 +33,48 @@ Flow is a structured workflow for Claude Code. Four core commands that turn your
 ### Command by Command
 
 **`/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)
+- Asks you 4-5 questions (what is it, tech stack, verify commands, roadmap/projects)
+- Captures your full roadmap upfront (paste a list or build one project 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:triage` or `/flow:spec` instead
 
 **`/flow:triage`** — Sort a brain dump into action
 - Takes unstructured text (bullets, stream of consciousness, whatever)
-- Categorizes each item: Linear Issue, ROADMAP Entry, Milestone, Lesson, or Discard
-- Milestones get added to ROADMAP.md with status "Planned"
+- Categorizes each item: Linear Issue, ROADMAP Entry, Project, Lesson, or Discard
+- Projects get added to ROADMAP.md with status "Planned"
 - Linear issues created automatically (if Linear MCP available)
-- This is the single intake command — use it to add milestones, capture ideas, or file bugs
+- This is the single intake command — use it to add projects, capture ideas, or file bugs
 
 **`/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: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
+- Scope guard recommends `/flow:spec` if the task grows beyond 5 files or 3 layers (promotes to a project)
 
-**`/flow:spec`** — Run once per milestone
-- Interviews you about scope, user stories, technical design, trade-offs, and phasing
+**`/flow:spec`** — Run once per project
+- Interviews you about scope, user stories, technical design, trade-offs, and milestoning
 - You can say "done" or "that's enough" anytime to cut the interview short
-- 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)
+- Produces `.planning/prds/{project}.md` — the execution contract with wave-based milestones, file lists, and acceptance criteria
+- Can pre-spec future projects in parallel terminal windows (each project gets its own PRD file)
+- Updates ROADMAP and STATE to reflect the plan (for the current project; future project specs skip STATE updates)
 
-**`/flow:go`** — Run once per phase (this is where the work happens)
-- Reads the PRD, finds the next pending phase
-- Checks for staleness (did prior phases change things this phase references?)
+**`/flow:go`** — Run once per milestone (this is where the work happens)
+- Reads the PRD, finds the next pending milestone
+- Checks for staleness (did prior milestones change things this milestone references?)
 - Spawns agent teams per the wave structure in the PRD
 - Verifies after each wave, commits when done
-- Updates docs and prints "run `/flow:go` again for the next phase"
+- Updates docs and prints "run `/flow:go` again for the next milestone"
 
 **`/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
+- Updates ROADMAP.md with milestone completions
+- Auto-transitions to the next planned project when the current one completes
 - 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
 
 **`/flow:status`** — Run anytime, read-only
-- Quick "where am I?" — milestone, phase progress, next step, lesson count
+- Quick "where am I?" — project, milestone progress, next step, lesson count
 
 **`/flow:update`** — Run anytime to update Flow
 - Pulls latest changes from the flow-plugin repo and re-installs all skills
@@ -84,8 +84,8 @@ Flow is a structured workflow for Claude Code. Four core commands that turn your
 
 ```
 1. Paste the handoff prompt from last session (or /flow:status to orient)
-2. /flow:go          ← executes the next phase
-3. /flow:go          ← executes the phase after that (if time permits)
+2. /flow:go          ← executes the next milestone
+3. /flow:go          ← executes the milestone after that (if time permits)
 4. /flow:done        ← wraps up, gives you the handoff prompt for tomorrow
 ```
 
@@ -96,7 +96,7 @@ Flow is a structured workflow for Claude Code. Four core commands that turn your
 ```
 1. /flow:setup       ← scaffolds everything
 2. /flow:spec        ← interview → PRD
-3. /flow:go          ← phase 1
+3. /flow:go          ← milestone 1
 4. /flow:done        ← wrap up
 ```
 

package/skills/flow-setup.md

@@ -11,7 +11,7 @@ You are executing the `/flow:setup` skill. This sets up the planning scaffolding
 ## Guard: Already Initialized
 
 Check if `.planning/STATE.md` already exists:
-- **If it exists** → Print: "This project is already set up. Run `/flow:triage` to add milestones, or `/flow:spec` to spec the current one." and **STOP. Do not overwrite.**
+- **If it exists** → Print: "This project is already set up. Run `/flow:triage` to add projects, or `/flow:spec` to spec the current one." and **STOP. Do not overwrite.**
 - **If it does NOT exist** → Continue with setup below.
 
 ---
@@ -38,22 +38,22 @@ Use AskUserQuestion to gather project info. Ask these questions (you may combine
   - (Other — user types custom)
 
 **Question 4 — Roadmap:**
-- "Do you already have a roadmap or list of milestones?" with options:
+- "Do you already have a roadmap or list of projects?" 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
+- Parse into projects, each with a name + brief goal
 - Print back: "Here's what I got:" followed by the parsed list (e.g., "Auth — user registration and login", "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:triage`." with options:
-  - "I have more to add" (user enters additional milestones)
+- Ask: "What's the first project?" (name + one-sentence goal)
+- Then: "Any more projects you can see right now? List them, or skip to add them later with `/flow:triage`." with options:
+  - "I have more to add" (user enters additional projects)
   - "That's it for now"
 
 **Question 5 — Brownfield scan:**
@@ -78,17 +78,17 @@ Create these 5 files (create directories as needed):
 # [Project Name] — Project State
 
 ## Current Position
-- **Milestone:** [first milestone name]
-- **Phase:** Not started — run `/flow:spec` to build PRD
+- **Project:** [first project name]
+- **Milestone:** 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
 
-| Phase | Name | Status |
-|-------|------|--------|
-| — | Run `/flow:spec` to define phases | — |
+| Milestone | Name | Status |
+|-----------|------|--------|
+| — | Run `/flow:spec` to define milestones | — |
 
 ## What Was Built (This Session)
 - Project initialized with `/flow:setup`
@@ -98,39 +98,39 @@ Create these 5 files (create directories as needed):
 - (none yet)
 
 ## Next Actions
-1. Run `/flow:spec` to interview and generate PRD for [first milestone]
+1. Run `/flow:spec` to interview and generate PRD for [first project]
 ```
 
 **`.planning/ROADMAP.md`:**
 ```
 # [Project Name] — Roadmap
 
-## Milestones
+## Projects
 
-| Milestone | Status | Phases |
-|-----------|--------|--------|
-| [first milestone] | Pending — needs `/flow:spec` | TBD |
-[For each additional milestone:]
-| [milestone name] | Planned | TBD |
+| Project | Status | Milestones |
+|---------|--------|------------|
+| [first project] | Pending — needs `/flow:spec` | TBD |
+[For each additional project:]
+| [project name] | Planned | TBD |
 
 ---
 
-## [first milestone]
+## [first project]
 
-**Goal:** [milestone goal from user]
+**Goal:** [project goal from user]
 
-**Phases:** Run `/flow:spec` to define implementation phases.
+**Milestones:** Run `/flow:spec` to define implementation milestones.
 
-[For each additional milestone:]
+[For each additional project:]
 
-## [milestone name]
+## [project name]
 
-**Goal:** [milestone goal]
+**Goal:** [project goal]
 
-**Phases:** Run `/flow:spec` when this milestone is active.
+**Milestones:** Run `/flow:spec` when this project 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.
+Note: The first project gets status "Pending — needs `/flow:spec`". All subsequent projects get status "Planned". Each project gets its own section with its goal.
 
 **`CLAUDE.md`:**
 ```
@@ -145,11 +145,11 @@ Note: The first milestone gets status "Pending — needs `/flow:spec`". All subs
 ### START (Every Session)
 1. Read this file (CLAUDE.md)
 2. Read `.planning/STATE.md` for current status
-3. Read `.planning/ROADMAP.md` for milestone progress
-4. Read active PRD from `.planning/prds/` for current milestone (if one exists)
+3. Read `.planning/ROADMAP.md` for project progress
+4. Read active PRD from `.planning/prds/` for current project (if one exists)
 
 ## Execution Rules
-- **Plan before building.** For non-trivial work, read the milestone's PRD in `.planning/prds/` before touching anything.
+- **Plan before building.** For non-trivial work, read the project'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.
 
@@ -159,7 +159,7 @@ Note: The first milestone gets status "Pending — needs `/flow:spec`". All subs
 
 ## Session-End Docs (MANDATORY)
 1. `.planning/STATE.md` — replace session notes (don't append), keep <80 lines
-2. `.planning/ROADMAP.md` — update phase progress
+2. `.planning/ROADMAP.md` — update milestone progress
 3. `tasks/lessons.md` — add new lessons, refine existing ones
 4. Commit doc updates to feature branch
 
@@ -177,7 +177,7 @@ 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/prds/`** — Create this empty directory (use `mkdir -p` via Bash). PRDs are stored here per-project.
 
 **`.planning/archive/`** — Create this empty directory (use `mkdir -p` via Bash).
 
@@ -187,10 +187,10 @@ One-liner format: `- **[topic]** The rule`
 Project initialized:
 - CLAUDE.md — project execution rules
 - .planning/STATE.md — session GPS
-- .planning/ROADMAP.md — milestone tracker
+- .planning/ROADMAP.md — project tracker
 - tasks/lessons.md — active lessons (max 10)
-- .planning/prds/ — per-milestone PRD specs
-- .planning/archive/ — for completed milestones
+- .planning/prds/ — per-project PRD specs
+- .planning/archive/ — for completed projects
 
-Run `/flow:spec` to plan your first milestone.
+Run `/flow:spec` to plan your first project.
 ```

package/skills/flow-spec.md

@@ -1,12 +1,12 @@
 ---
 name: flow:spec
-description: Spec interview that produces an executable PRD with wave-based phases and testable acceptance criteria
+description: Spec interview that produces an executable PRD with wave-based milestones and testable acceptance criteria
 user_invocable: true
 ---
 
 # /flow:spec — Spec Interview → Executable PRD
 
-You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow system. You will interview the user about their milestone, then produce a detailed PRD that agents can execute without ambiguity.
+You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow system. You will interview the user about their project, then produce a detailed PRD that agents can execute without ambiguity.
 
 **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.
 
@@ -16,28 +16,28 @@ You are executing the `/flow:spec` skill. This is the KEYSTONE skill of the flow
 
 ## Phase 1 — Context Gathering
 
-1. Read `.planning/STATE.md` and `.planning/ROADMAP.md` — understand current milestone and what's done
+1. Read `.planning/STATE.md` and `.planning/ROADMAP.md` — understand current project and what's done
 2. Read `CLAUDE.md` — understand project rules and tech stack
 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. **Milestone Targeting** — determine which milestone this PRD targets before scanning the codebase:
+   - If a PRD exists for the target project, note it for resume/extend flow
+4. **Project Targeting** — determine which project this PRD targets before scanning the codebase:
 
-   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.
+   1. **If the user passed an argument** (e.g., `/flow:spec v3: Payments`) — match against ROADMAP.md projects. If no match, print available projects 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 next unspecced milestone as the first option. Always show the picker, even if only one milestone is listed — the user may want to confirm or choose "Other" to define a new milestone first.
+   2. **If no argument** — read ROADMAP.md and list all incomplete projects. Use AskUserQuestion to let the user pick which project to spec. Pre-select the next unspecced project as the first option. Always show the picker, even if only one project is listed — the user may want to confirm or choose "Other" to define a new project first.
 
-   3. **Derive the PRD slug:** Take the milestone name (e.g., "Dashboard Analytics"), lowercase it, replace spaces and special characters with hyphens, collapse consecutive hyphens. Result: `dashboard-analytics`. The PRD path is `.planning/prds/{slug}.md`.
+   3. **Derive the PRD slug:** Take the project name (e.g., "Dashboard Analytics"), lowercase it, replace spaces and special characters with hyphens, collapse consecutive hyphens. Result: `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?"
+      - **If PRD exists** → Use AskUserQuestion: "A PRD already exists for this project 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
+        - "Pick a different project" — show available projects
       - **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."
+   5. **Future project detection:** If the target project is NOT the current project 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 project's PRD). Print: "Speccing future project [name]. STATE.md will not be updated — this PRD will be available when you reach this project."
 
 5. **Codebase scan** (brownfield projects) — spawn **3 parallel Explore subagents** via the Task tool to scan the codebase without consuming main context:
 
@@ -92,8 +92,8 @@ Then proceed to the coverage areas below.
 Cover these areas thoroughly. There are no "rounds" — move fluidly between areas based on the conversation. Circle back to earlier areas when later answers reveal new information.
 
 **1. Scope Definition**
-- What features are IN scope for this milestone? What's the MVP vs. the full vision?
-- What is explicitly OUT of scope / deferred to a future milestone?
+- What features are IN scope for this project? What's the MVP vs. the full vision?
+- What is explicitly OUT of scope / deferred to a future project?
 - Is there any code that is sacred (must NOT be touched)? Why?
 - What existing code/features should we ignore entirely (not break, not improve, not touch)?
 
@@ -130,22 +130,22 @@ Cover these areas thoroughly. There are no "rounds" — move fluidly between are
 - What technical debt is acceptable for now vs. must be done right?
 - Any browser/device support requirements?
 
-**6. Implementation Phases**
-- How should this break into sequential phases?
-- What can be parallelized within each phase? (wave-based agent structure)
+**6. Implementation Milestones**
+- How should this break into sequential milestones?
+- What can be parallelized within each milestone? (wave-based agent structure)
 - What's the critical path — what must be built first?
-- What's the minimum viable first phase? (what gives us something testable fastest?)
-- Any phases that could be cut if time runs short?
-- **Assignability check:** After defining phases, probe which are independent enough for a different developer:
-  - "Which of these phases could a second developer work on independently?"
-  - Evaluate each phase for: dependency chains (does it need output from another phase?), domain independence (is it a separate concern?), context requirements (does it need deep codebase familiarity?), onboarding suitability (could a newer dev handle it?)
-  - Add assignability notes to each phase, e.g., "Phase 3 is independent — good for either dev" or "Phase 2 depends on Phase 1 — same dev"
+- What's the minimum viable first milestone? (what gives us something testable fastest?)
+- Any milestones that could be cut if time runs short?
+- **Assignability check:** After defining milestones, probe which are independent enough for a different developer:
+  - "Which of these milestones could a second developer work on independently?"
+  - Evaluate each milestone for: dependency chains (does it need output from another milestone?), domain independence (is it a separate concern?), context requirements (does it need deep codebase familiarity?), onboarding suitability (could a newer dev handle it?)
+  - Add assignability notes to each milestone, e.g., "Milestone 3 is independent — good for either dev" or "Milestone 2 depends on Milestone 1 — same dev"
 
 **7. Verification & Feedback Loops**
 - What commands verify the build works? (`tsc`, `biome`, test suite)
-- What does "done" look like for each phase? How do we know it worked?
+- What does "done" look like for each milestone? How do we know it worked?
 - Are there integration points that need end-to-end testing?
-- What should we check after each phase before moving to the next?
+- What should we check after each milestone before moving to the next?
 - Any monitoring or logging needed to confirm production behavior?
 
 **User signals done:** If the user says "done", "finalize", "that's enough", "ship it", or similar — immediately stop interviewing and go to Phase 3. Finalize the PRD with whatever depth has been achieved.
@@ -156,7 +156,7 @@ Cover these areas thoroughly. There are no "rounds" — move fluidly between are
 
 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 implementation milestone** has been defined
 - At least **1 verification command** has been specified
 
 If any check fails, print what's missing and use AskUserQuestion:
@@ -169,16 +169,16 @@ If any check fails, print what's missing and use AskUserQuestion:
 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
+# [Project Name] — Specification
 
-**Milestone:** [full milestone name, e.g., "Dashboard Analytics"]
+**Project:** [full project name, e.g., "Dashboard Analytics"]
 **Status:** Ready for execution
-**Branch:** feat/{milestone-slug}
+**Branch:** feat/{project-slug}
 **Created:** [today's date]
 **Assigned To:** [developer name or "unassigned"]
 
 ## Overview
-[One paragraph summary of the milestone]
+[One paragraph summary of the project]
 
 ## Problem Statement
 [Why this work exists — what problem does it solve?]
@@ -186,7 +186,7 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 ## Scope
 
 ### In Scope
-- [Bullet list of what ships in this milestone]
+- [Bullet list of what ships in this project]
 
 ### Out of Scope
 - [Explicitly deferred items]
@@ -215,7 +215,7 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 [Method + path + request/response shape for each]
 
 ### New Files to Create
-[Grouped by phase. Absolute paths with one-line descriptions]
+[Grouped by milestone. Absolute paths with one-line descriptions]
 
 ### Existing Files to Modify
 [Paths + what changes in each]
@@ -223,9 +223,9 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 ### Key Existing Code (DO NOT recreate — use as-is)
 [Functions, utilities, DAL queries, components that agents should import/reuse]
 
-## Implementation Phases
+## Implementation Milestones
 
-### Phase 1: [Name]
+### Milestone 1: [Name]
 **Assigned To:** [developer name or "unassigned"]
 **Goal:** [One sentence]
 
@@ -243,20 +243,20 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 **Verification:** [Exact commands to run]
 **Acceptance:** US-1 criteria [list which], US-2 criteria [list which]
 
-### Phase 2: [Name]
+### Milestone 2: [Name]
 **Assigned To:** [developer name or "unassigned"]
 ...
 
 ## Execution Rules
 1. DELEGATE EVERYTHING. Lead context is sacred — do not read implementation files into it.
-2. Verify after every phase: [verification commands from CLAUDE.md]
+2. Verify after every milestone: [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 lessons into agent prompts
 
 ## Definition of Done
 - [ ] All user story acceptance criteria pass
-- [ ] All phases verified with [verification commands]
+- [ ] All milestones verified with [verification commands]
 - [ ] Branch pushed and PR opened
 - [ ] STATE.md and ROADMAP.md updated
 ```
@@ -265,41 +265,45 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 
 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".
+1. **Update ROADMAP.md:** Add milestone breakdown under the current project section. Each milestone gets a row in the progress table with status "Pending".
 
-2. **Update STATE.md** (current milestone only):
-   - Set current phase to "Phase 1 — ready for `/flow:go`"
+2. **Update STATE.md** (current project only):
+   - Set current milestone to "Milestone 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)."
+   - Update "Next Actions" to reference the first milestone
+   - **Skip this step if speccing a future project** — STATE.md stays pointing at the current project. Print: "PRD written to `.planning/prds/{slug}.md`. STATE.md not updated (future project)."
 
-3. **Generate Phase 1 handoff prompt:**
+3. **Generate Milestone 1 handoff prompt:**
    ```
-   Phase 1: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md.
-   [One sentence of context about what Phase 1 builds].
+   Milestone 1: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md.
+   [One sentence of context about what Milestone 1 builds].
    ```
 
-4. **Linear Issue Creation (optional):**
+4. **Linear Integration (optional):**
    - Check if Linear MCP tools are available (try `mcp__linear__list_teams`)
-   - If available: search for a Linear project matching the milestone name (`mcp__linear__list_projects` with query)
-     - If found: create one Linear issue per phase under that project using `mcp__linear__create_issue`, with title "Phase N: [Name]" and description from PRD phase section. Set team to "Monument Square".
-     - If not found: use AskUserQuestion to ask user to pick a project or skip Linear integration
-   - If Linear MCP not available: skip silently (no error message)
-   - Print count: "[N] Linear issues created under project [name]" (or "Linear integration skipped" if not available)
+   - If available: search for a Linear project matching the project name (`mcp__linear__list_projects` with query)
+     - If found:
+       - Create one **Linear milestone** per implementation milestone:
+         `mcp__linear__create_milestone` with project, name "Milestone N: [Name]"
+       - Create one **Linear issue** per user story or task (NOT per milestone):
+         `mcp__linear__create_issue` assigned to the appropriate milestone
+     - If not found: use AskUserQuestion to ask user to pick a project or skip
+   - If Linear MCP not available: skip silently
+   - Print: "[N] milestones + [M] issues created under project [name]"
 
 5. Print the handoff prompt in a fenced code block.
 
-6. Print: "PRD ready at `.planning/prds/{slug}.md`. Run `/flow:go` to execute Phase 1, or review the PRD first."
+6. Print: "PRD ready at `.planning/prds/{slug}.md`. Run `/flow:go` to execute Milestone 1, or review the PRD first."
 
 ## Quality Gates
 
 Before finalizing, self-check the PRD:
-- [ ] Every phase has wave-based agent assignments with explicit file lists
+- [ ] Every milestone has wave-based agent assignments with explicit file lists
 - [ ] Every user story has checkbox acceptance criteria that are testable
-- [ ] Every phase has verification commands
+- [ ] Every milestone 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)
+- [ ] No milestone has more than 5 agents in a single wave (too many = coordination overhead)
 - [ ] Sacred code section is populated (even if empty with "None identified")
 
 If any gate fails, fix the PRD before presenting it.

package/skills/flow-status.md

@@ -1,6 +1,6 @@
 ---
 name: flow:status
-description: Quick orientation — shows current milestone, phase progress, and next actions
+description: Quick orientation — shows current project, milestone progress, and next actions
 user_invocable: true
 ---
 
@@ -17,7 +17,7 @@ Read ALL of the following in parallel:
 - `.planning/ROADMAP.md`
 - 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
+- Read the active PRD (from STATE.md "Active PRD" field) to get milestone details
 - Count lessons in `tasks/lessons.md` (if exists)
 - `.claude/memory/session.md` (if exists) — personal session state
 - Run `git config user.name` to get developer identity
@@ -28,76 +28,76 @@ IF both STATE.md AND ROADMAP.md are missing:
 
 IF only one file exists, continue with what's available.
 
-## Step 2 — Analyze Phase Status
+## Step 2 — Analyze Milestone Status
 
-Parse ROADMAP.md to determine phase progress:
-- Count total phases
-- Count phases marked "Complete", "Done", or containing a completion date (e.g., `✓`, `[x]`, `completed`)
-- Count phases marked "Pending", "In Progress", or not yet started
-- Identify the FIRST phase that is NOT complete — this is the **next phase**
+Parse ROADMAP.md to determine milestone progress:
+- Count total milestones
+- Count milestones marked "Complete", "Done", or containing a completion date (e.g., `✓`, `[x]`, `completed`)
+- Count milestones marked "Pending", "In Progress", or not yet started
+- Identify the FIRST milestone that is NOT complete — this is the **next milestone**
 
-RULE: Determine the next action from ROADMAP.md phase statuses, NOT from STATE.md "Next Actions" text. STATE.md may be stale from a previous session. ROADMAP.md is the source of truth for phase progress.
+RULE: Determine the next action from ROADMAP.md milestone statuses, NOT from STATE.md "Next Actions" text. STATE.md may be stale from a previous session. ROADMAP.md is the source of truth for milestone progress.
 
 ## Step 3 — Determine Routing
 
 Use this explicit decision tree:
 
-**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]
+**IF pending milestones exist in ROADMAP AND a PRD exists for the current project (in `.planning/prds/` or legacy root):**
+→ Primary: `/flow:go` to execute Milestone [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 no PRD exists for the current milestone:**
-→ `/flow:spec` — select a milestone and build its execution plan
+**IF pending milestones exist in ROADMAP BUT no PRD exists for the current project:**
+→ `/flow:spec` — select a project and build its execution plan
 → `/flow:task` — for quick fixes or cleanup (no PRD needed)
 
-**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)
+**IF all milestones are complete AND a next project with status "Planned" exists in ROADMAP.md:**
+→ Primary: `/flow:done` to finalize this project (will auto-transition to next project)
 → 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:triage` to add the next milestone
+**IF all milestones are complete AND no next project exists:**
+→ Primary: `/flow:done` to finalize this project
+→ Then: `/flow:triage` to add the next project
 → Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
 
-**IF no phases exist in ROADMAP (milestone defined but not planned):**
-→ `/flow:spec` — select a milestone and build its execution plan
+**IF no milestones exist in ROADMAP (project defined but not planned):**
+→ `/flow:spec` — select a project and build its execution plan
 → `/flow:task` — for quick fixes or cleanup (no PRD needed)
 
 **CRITICAL — `/flow:spec` suggestion format:** When printing routing recommendations, output EXACTLY this text for /flow:spec suggestions:
 ```
-→ /flow:spec — select a milestone and build its execution plan
+→ /flow:spec — select a project and build its execution plan
 ```
-Do NOT append a milestone name, do NOT say "for v16" or "to plan v16" or any variation. The milestone picker inside /flow:spec handles selection. Adding a name here confuses users who may have multiple milestones in flight across terminals. Print the line EXACTLY as shown above — no modifications.
+Do NOT append a project name, do NOT say "for v16" or "to plan v16" or any variation. The project picker inside /flow:spec handles selection. Adding a name here confuses users who may have multiple projects in flight across terminals. Print the line EXACTLY as shown above — no modifications.
 
 ## Step 4 — Print Status Block
 
 ```
-Milestone: [name] ([X/Y] phases complete)
+Project: [name] ([X/Y] milestones complete)
 Developer: [git config user.name]
 Session: [session.md "Working On" field if session.md exists, or "No active session"]
 Last session: [date] — [what was built]
-Next: Phase [N] — [name] ([short description])
+Next: Milestone [N] — [name] ([short description])
 Lessons: [N]/10 active
 
 PRDs:
-  * {slug}.md (active — current milestone)
+  * {slug}.md (active — current project)
   [For each additional PRD in .planning/prds/:]
-  * {slug}.md (ready — future milestone)
+  * {slug}.md (ready — future project)
   [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.
+The PRDs section shows all PRD files found. Mark the one matching STATE.md's "Active PRD" as "(active — current project)". Mark others as "(ready — future project)". 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.
 
-When listing PRDs, if a PRD has `**Assigned To:**` fields in its phase sections, show assignment status in the PRD listing, e.g.:
+When listing PRDs, if a PRD has `**Assigned To:**` fields in its milestone sections, show assignment status in the PRD listing, e.g.:
 ```
-  * {slug}.md (active — Phase 3 assigned to Matt, Phase 4 unassigned)
+  * {slug}.md (active — Milestone 3 assigned to Matt, Milestone 4 unassigned)
 ```
 
-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."
+Adapt the block based on available information. If STATE.md is missing, omit "Last session". If ROADMAP.md is missing, omit milestone counts and say "Run /flow:setup to set up tracking."
 
 ## Step 5 — No File Writes