flow-cc 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.8.0] - 2026-02-14
+
+### Changed
+- **BREAKING:** Terminology aligned with Linear hierarchy — "Milestone" → "Project", "Phase" → "Milestone" across all skills, templates, and docs
+- `/flow:go` adds Step 2.5: automatically moves Linear issues to "In Progress" when starting a milestone
+- `/flow:go` Step 7: detects final milestone and routes to `/flow:done` for PR creation
+- `/flow:done` adds Step 5.25: auto-creates PR with `Closes MSIG-XX` body when project is complete
+- `/flow:done` Step 5.5: moves completed issues to "In Review" when PR is detected
+- `/flow:spec` creates Linear **milestones** (not issues) for implementation stages, issues for tasks
+- All templates updated: STATE.md uses "Project:", ROADMAP.md uses "Projects" table
+- DESIGN.md and README.md updated to reflect new terminology
+
+## [0.7.1] - 2026-02-14
+
+### Fixed
+- Installer now cleans stale skill files from previous versions (e.g., `milestone.md`, `init.md` left behind after removal)
+
 ## [0.7.0] - 2026-02-14
 
 ### Changed

package/README.md

@@ -28,8 +28,8 @@ Claude Code is powerful but unstructured. Without a system, you lose context bet
 Flow gives Claude Code a **memory system and execution framework**:
 
 - **Spec interviews** extract decisions upfront so agents execute instead of guessing
-- **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
+- **Per-project PRDs** in `.planning/prds/` become execution contracts — spec future projects in parallel
+- **Wave-based agent teams** execute milestones 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
 
@@ -45,15 +45,15 @@ Flow gives 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
-3. **`/flow:go`** — Spawns parallel agent teams to build the next phase, verifies, commits
+2. **`/flow:spec`** — Interviews you, then writes an executable PRD with milestones, acceptance criteria, and agent-team structure
+3. **`/flow:go`** — Spawns parallel agent teams to build the next milestone, verifies, commits
 4. **`/flow:done`** — Updates docs, captures lessons, generates a handoff prompt so the next session starts instantly
 
-Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap up. Next session, paste the handoff prompt and keep going.
+Run `/flow:go` repeatedly until all milestones are done, then `/flow:done` to wrap up. Next session, paste the handoff prompt and keep going.
 
 ---
 
-## Multi-PRD: Parallel Milestone Planning
+## Multi-PRD: Parallel Project Planning
 
 <table>
 <tr>
@@ -64,19 +64,19 @@ Run `/flow:go` repeatedly until all phases are done, then `/flow:done` to wrap u
 project/
 └── PRD.md          ← one at a time
 ```
-Finish or archive the current milestone before speccing the next. Serial bottleneck on large roadmaps.
+Finish or archive the current project before speccing the next. Serial bottleneck on large roadmaps.
 
 </td>
 <td width="50%">
 
-**Now (per-milestone PRDs)**
+**Now (per-project PRDs)**
 ```
 .planning/prds/
 ├── user-auth.md          ← active
 ├── dashboard.md          ← pre-specced
 └── payments.md           ← pre-specced
 ```
-Spec any milestone at any time. Execute the current one while planning ahead.
+Spec any project at any time. Execute the current one while planning ahead.
 
 </td>
 </tr>
@@ -84,8 +84,8 @@ Spec any milestone at any time. Execute the current one while planning ahead.
 
 **How it works:**
 
-- `/flow:spec` writes PRDs to `.planning/prds/{slug}.md` — one file per milestone
-- `/flow:spec Payments` targets a specific future milestone without changing your current position
+- `/flow:spec` writes PRDs to `.planning/prds/{slug}.md` — one file per project
+- `/flow:spec Payments` targets a specific future project 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
@@ -99,8 +99,8 @@ Spec any milestone at any time. Execute the current one while planning ahead.
 | 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:spec` | Once per project | Interview that produces an executable PRD in `.planning/prds/` |
+| `/flow:go` | Once per milestone | Executes the next milestone with wave-based agent teams |
 | `/flow:done` | End of session | Updates docs, captures lessons, generates handoff prompt |
 
 ### Standalone
@@ -132,11 +132,11 @@ your-project/
 │       └── session.md           # Per-developer session state (gitignored)
 ├── .planning/
 │   ├── STATE.md                 # Project-level GPS — shared across developers
-│   ├── ROADMAP.md               # Milestone phases and progress tracking
-│   ├── prds/                    # Per-milestone PRD specs
-│   │   ├── user-auth.md         #   One file per milestone
-│   │   └── dashboard.md         #   Pre-spec future milestones anytime
-│   └── archive/                 # Completed milestones and archived PRDs
+│   ├── ROADMAP.md               # Project milestones and progress tracking
+│   ├── prds/                    # Per-project PRD specs
+│   │   ├── user-auth.md         #   One file per project
+│   │   └── dashboard.md         #   Pre-spec future projects anytime
+│   └── archive/                 # Completed projects and archived PRDs
 └── tasks/
     └── lessons.md               # Active lessons (max 10) → promoted to CLAUDE.md
 ```
@@ -188,7 +188,7 @@ Hard caps prevent context bloat. Total worst-case: ~30 lines of lessons context
 Flow supports multiple developers on the same repo without conflicts:
 
 - **`session.md`** — Per-developer session state, stored in `.claude/memory/session.md` (gitignored). Each developer has their own session GPS that never conflicts.
-- **`STATE.md`** — Shared project-level state in `.planning/STATE.md`. Updated at milestone boundaries only (not every session), so conflicts are rare.
+- **`STATE.md`** — Shared project-level state in `.planning/STATE.md`. Updated at project boundaries only (not every session), so conflicts are rare.
 - **Developer identity** — `/flow:spec` and `/flow:go` track who is working on what. PRDs can be assigned to specific developers (advisory, not blocking).
 - **Template provided** — `session.md.template` scaffolds the per-developer file on first use.
 
@@ -198,7 +198,7 @@ Flow supports multiple developers on the same repo without conflicts:
 
 Flow optionally integrates with Linear via MCP for issue tracking:
 
-- **`/flow:spec`** can create Linear issues automatically from PRD phases
+- **`/flow:spec`** can create Linear issues automatically from PRD milestones
 - **`/flow:done`** can post progress comments to Linear issues
 - **`/flow:triage`** sorts unstructured brain dumps into categorized Linear issues, ROADMAP entries, and lessons
 - **Branch convention** `feat/msig-{issue#}-desc` auto-links PRs to Linear issues

package/VERSION

@@ -1 +1 @@
-0.7.0
+0.8.0

package/bin/install.js

@@ -227,7 +227,18 @@ try {
   }
 
   // 2. Copy skills: skills/flow-*.md -> commands/flow/*.md (strip "flow-" prefix)
+  //    Clean stale skill files first (from previous versions that removed skills)
   const skillFiles = fs.readdirSync(skillsDir).filter(f => f.startsWith('flow-') && f.endsWith('.md'));
+  const expectedSkills = new Set(skillFiles.map(f => f.replace(/^flow-/, '')));
+  if (fs.existsSync(commandsDir)) {
+    const existing = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+    for (const file of existing) {
+      if (!expectedSkills.has(file)) {
+        fs.unlinkSync(path.join(commandsDir, file));
+        console.log(`  Removed stale skill: ${file}`);
+      }
+    }
+  }
   for (const file of skillFiles) {
     const dest = file.replace(/^flow-/, '');
     const destPath = path.join(commandsDir, dest);

package/package.json

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

@@ -1,6 +1,6 @@
 ---
 name: flow:done
-description: Session-end documentation — updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
+description: Session-end documentation — updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt. Handles project-complete PR creation and Linear status management.
 user_invocable: true
 ---
 
@@ -18,7 +18,7 @@ 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
+- `.planning/ROADMAP.md` — project/milestone progress
 - `tasks/lessons.md` — active lessons (max 10)
 - `CLAUDE.md` — project rules
 - Active PRD from `.planning/prds/` (resolve via STATE.md "Active PRD" field, or fall back to legacy `PRD.md` at root)
@@ -30,27 +30,27 @@ Also gather:
 - Run `git config user.name` to get developer identity
 - If uncommitted changes exist, warn the user before proceeding
 
-### 2. Update STATE.md (Milestone Boundaries Only)
+### 2. Update STATE.md (Project Boundaries Only)
 
-**Determine if a milestone was completed this session** by checking ROADMAP.md progress and commits.
+**Determine if a project was completed this session** by checking ROADMAP.md progress and commits.
 
-**IF milestone completed this session** — REPLACE the entire file (do NOT append). Keep under 80 lines.
+**IF project completed this session** — REPLACE the entire file (do NOT append). Keep under 80 lines.
 
 Structure:
 ```
 # [Project Name] — Project State
 
 ## Current Position
-- **Milestone:** [name]
-- **Phase:** [current phase status]
+- **Project:** [name]
+- **Milestone:** [current milestone status]
 - **Branch:** [current branch]
-- **Active PRD:** [path to active PRD, or "None" if milestone complete]
+- **Active PRD:** [path to active PRD, or "None" if project complete]
 - **Last Session:** [today's date]
 
 ## Milestone Progress
 
-| Phase | Name | Status |
-|-------|------|--------|
+| Milestone | Name | Status |
+|-----------|------|--------|
 | 1 | [name] | Complete (date) |
 | 2 | [name] | Complete (date) |
 | 3 | [name] | In Progress |
@@ -64,14 +64,14 @@ Structure:
 - [Any architectural or design decisions made]
 
 ## Next Actions
-1. [Specific next step — usually "Run /flow:go for Phase N"]
+1. [Specific next step — usually "Run /flow:go for Milestone N"]
 ```
 
-**IF normal session (no milestone completed)** — SKIP STATE.md entirely. Print: "Normal session — STATE.md skipped (milestone boundaries only)."
+**IF normal session (no project completed)** — SKIP STATE.md entirely. Print: "Normal session — STATE.md skipped (project boundaries only)."
 
 ### 2.5. Write session.md (Every Session)
 
-This step ALWAYS runs, regardless of whether a milestone was completed.
+This step ALWAYS runs, regardless of whether a project was completed.
 
 Create `.claude/memory/` directory if it doesn't exist.
 
@@ -83,31 +83,31 @@ Write `.claude/memory/session.md` with the following content:
 **Date:** [today's date]
 **Developer:** [git config user.name result]
 **Branch:** [current git branch]
-**Working On:** [Linear issue ID + description if detectable from branch name, or PRD phase, or "standalone task"]
+**Working On:** [Linear issue ID + description if detectable from branch name, or PRD milestone, or "standalone task"]
 **Status:** [what was accomplished this session — bullet list of key items]
 **Next:** [what to pick up next session]
 **Blockers:** [any blockers, or "None"]
 ```
 
-### 3. Update ROADMAP.md (Milestone Boundaries Only)
+### 3. Update ROADMAP.md (Project Boundaries Only)
 
-**IF milestone completed this session:**
+**IF project completed this session:**
 
-- Mark completed phases with completion date
-- Ensure pending phases have enough detail that the next session can start with a one-line prompt
-- **Archive check:** If the current milestone is fully complete:
+- Mark completed milestones with completion date
+- Ensure pending milestones have enough detail that the next session can start with a one-line prompt
+- **Archive check:** If the current project is fully complete:
   - If `.planning/` does not exist, skip archiving entirely — there's nothing to archive
   - Create `.planning/archive/` if it doesn't already exist (use `mkdir -p` or equivalent)
-  - Move milestone phase details to `.planning/archive/milestones-{slug}.md`
-  - Keep only the summary row in the ROADMAP milestone table
-  - 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-{slug}.md` instead.
+  - Move project milestone details to `.planning/archive/project-{slug}.md`
+  - Keep only the summary row in the ROADMAP project table
+  - Archive the project'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-{slug}.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.
-    - **If no next milestone exists:** No transition needed — all planned milestones are done.
+  - Mark the project as "Complete" in the ROADMAP table
+  - **Project transition:** Check ROADMAP.md for the NEXT project with status "Planned":
+    - **If a next project exists:** Update its status from "Planned" to "Pending — needs `/flow:spec`". Update STATE.md current project to point to the new project.
+    - **If no next project exists:** No transition needed — all planned projects are done.
 
-**IF normal session (no milestone completed)** — SKIP ROADMAP.md entirely. Print: "Normal session — ROADMAP.md skipped (milestone boundaries only)."
+**IF normal session (no project completed)** — SKIP ROADMAP.md entirely. Print: "Normal session — ROADMAP.md skipped (project boundaries only)."
 
 ### 4. Update lessons.md
 
@@ -128,46 +128,80 @@ Write `.claude/memory/session.md` with the following content:
 
 ### 5. Commit Doc Updates
 
-**Normal session (no milestone completed):**
+**Normal session (no project completed):**
 - Only stage `tasks/lessons.md` if it changed
 - Skip STATE.md and ROADMAP.md (they were not modified)
 - Do NOT stage `.claude/memory/session.md` (it is gitignored)
 - If nothing needs staging (no changes to shared docs), skip the commit. Print: "No shared doc changes to commit."
 - Otherwise commit with message: `docs: session-end updates — [brief summary]`
 
-**Milestone boundary session:**
+**Project boundary session:**
 - Stage STATE.md, ROADMAP.md, lessons.md, and any archived files
 - Do NOT stage `.claude/memory/session.md` (it is gitignored)
 - Commit with message: `docs: session-end updates — [brief summary]`
 
 - Do NOT push unless the user asks
 
-### 5.5. Linear Progress Comment
-
-- Check if the current branch name contains a Linear issue identifier pattern (e.g., `msig-45` in `feat/msig-45-rate-modeling`)
-- Extract the identifier (the `msig-45` part)
-- If found:
-  - Attempt to call `mcp__linear__list_issues` with `query` matching the identifier
-  - If Linear MCP is available AND an issue is found: post a progress comment with `mcp__linear__create_comment` summarizing: developer name (from Step 1), what was done, what's next, any blockers
-  - If Linear MCP is not available OR no issue found: skip silently (no error, no output)
-- If no identifier in branch name: skip silently
+### 5.25. Auto-Create PR (Project Complete Only)
+
+- Check if ALL milestones in the PRD are marked "Complete" in ROADMAP.md
+- If all complete AND no PR exists for this branch (`gh pr list --head [branch] --state open` returns empty):
+  - Parse the PRD for all Linear issue IDs (e.g., MSIG-34, MSIG-35, ...)
+  - Push the branch: `git push -u origin [branch]`
+  - Auto-generate PR body:
+    ```
+    ## Summary
+    [Project name] — [one-line description from PRD overview]
+
+    ## Milestones Completed
+    - Milestone 1: [Name] (completed [date])
+    - Milestone 2: [Name] (completed [date])
+    ...
+
+    ## Linear Issues
+    Closes MSIG-34, Closes MSIG-35, Closes MSIG-36, ...
+    [one "Closes MSIG-XX" per issue found in PRD]
+
+    ## Verification
+    - `npx tsc --noEmit` — passed
+    - `npx biome check` — passed
+    ```
+  - Create PR: `gh pr create --title "[project name]" --body "[auto-generated body]"`
+  - Print: "PR created: [PR URL]"
+  - Print: "Linear: [N] issues will auto-close on merge"
+- If milestones remain OR PR already exists: skip silently
+
+### 5.5. Linear Status Update + Progress Comment
+
+- Check if Linear MCP tools are available
+- If available:
+  - Parse the active PRD for `**Linear Project:**` field
+  - If found:
+    - Check for open PR: `gh pr list --head [branch] --state open`
+    - If PR exists:
+      - Find all issues in the Linear project that are "In Progress"
+      - Move them to "In Review": `mcp__linear__update_issue` with `state: "In Review"`
+      - Print: "Linear: [N] issues → In Review (PR open)"
+    - If no PR: issues stay In Progress (normal mid-project session end)
+  - Post progress comment on any branch-linked Linear issue (existing behavior)
+- If not available: skip silently
 
 ### 6. Generate Handoff Prompt
 
 Determine the next action and generate a copyable handoff prompt. Include the developer name in the prompt.
 
-- If next phase exists in PRD:
+- If next milestone exists in PRD:
   ```
-  [Developer Name] — Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md (US-X).
+  [Developer Name] — Milestone [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):
+- If project is complete AND a next project was transitioned to (from Step 3):
   ```
-  [Developer Name] — Milestone [name] complete. Next: [next milestone name]. Run /flow:spec to plan it.
+  [Developer Name] — Project [name] complete. Next: [next project name]. Run /flow:spec to plan it.
   ```
-- If milestone is complete AND no next milestone exists:
+- If project is complete AND no next project exists:
   ```
-  [Developer Name] — All milestones complete! Run /flow:triage to plan what's next, or enjoy the win.
+  [Developer Name] — All projects complete! Run /flow:triage to plan what's next, or enjoy the win.
   ```
 
 Print the handoff prompt in a fenced code block so the user can copy it.
@@ -177,7 +211,7 @@ Print the handoff prompt in a fenced code block so the user can copy it.
 ```
 Session complete.
 - STATE.md: [updated | skipped (normal session)]
-- ROADMAP.md: [N phases marked complete | skipped (normal session)]
+- ROADMAP.md: [N milestones marked complete | skipped (normal session)]
 - session.md: updated
 - lessons.md: [N]/10 active, [N] promoted to CLAUDE.md
 - Committed: [SHA | nothing to commit]

package/skills/flow-go.md

@@ -1,12 +1,12 @@
 ---
 name: flow:go
-description: Execute the next phase from PRD using wave-based agent teams
+description: Execute the next milestone from PRD using wave-based agent teams
 user_invocable: true
 ---
 
-# /flow:go — Execute Next Phase
+# /flow:go — Execute Next Milestone
 
-You are executing the `/flow:go` skill. This reads the PRD, identifies the next unstarted phase, and executes it using wave-based agent teams.
+You are executing the `/flow:go` skill. This reads the PRD, identifies the next unstarted milestone, and executes it using wave-based agent teams.
 
 **Core principle:** The PRD is the execution contract. You execute what it specifies. Do not freelance.
 
@@ -18,7 +18,7 @@ You are executing the `/flow:go` skill. This reads the PRD, identifies the next
 
 Read these files (in parallel):
 - `.planning/STATE.md` — current position
-- `.planning/ROADMAP.md` — phase progress
+- `.planning/ROADMAP.md` — milestone progress
 - `tasks/lessons.md` — active lessons (max 10 one-liners)
 - `CLAUDE.md` — execution rules and verification commands
 - `.claude/memory/session.md` (if exists) — personal session state
@@ -29,50 +29,62 @@ Run `git config user.name` to get developer identity.
 
 The user must always select which PRD to execute. No silent auto-resolution.
 
-1. **If the user passed an argument** (e.g., `/flow:go v3-payments`) — match it against files in `.planning/prds/` by slug or by the `**Milestone:**` header field. If an exact match is found, use it directly. If no match, show available PRDs and ask.
+1. **If the user passed an argument** (e.g., `/flow:go v3-payments`) — match it against files in `.planning/prds/` by slug or by the `**Project:**` header field. If an exact match is found, use it directly. If no match, show available PRDs and ask.
 
-2. **If no argument** — list all PRD files in `.planning/prds/`. For each PRD, read its `**Status:**` and `**Milestone:**` header fields. Use AskUserQuestion to let the user pick which PRD to execute. Pre-select the first PRD with status "Ready for execution" as the first option. Always show the picker, even if only one PRD exists — the user may want to confirm or run `/flow:spec` instead. Also check for legacy `PRD.md` at root (backward compat) and include it in the list if found.
+2. **If no argument** — list all PRD files in `.planning/prds/`. For each PRD, read its `**Status:**` and `**Project:**` header fields. Use AskUserQuestion to let the user pick which PRD to execute. Pre-select the first PRD with status "Ready for execution" as the first option. Always show the picker, even if only one PRD exists — the user may want to confirm or run `/flow:spec` instead. Also check for legacy `PRD.md` at root (backward compat) and include it in the list if found.
 
 3. **No PRDs found** — "No PRDs found in `.planning/prds/`. Run `/flow:spec` first." Stop here.
 
-**After selection:** Read the chosen PRD. If its `**Milestone:**` 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."
+**After selection:** Read the chosen PRD. If its `**Project:**` doesn't match STATE.md's current project, warn: "PRD project ([PRD project]) doesn't match current project ([STATE project]). Continuing, but verify you're executing the right spec."
 
-**Assignment check:** After reading the PRD, check the current phase section for an `**Assigned To:**` field. If present, compare against the developer identity from `git config user.name`. If assigned to a different developer, print: "⚠ This phase is assigned to [other dev]. Proceeding anyway — override if intentional." Do NOT block execution — this is advisory only.
+**Assignment check:** After reading the PRD, check the current milestone section for an `**Assigned To:**` field. If present, compare against the developer identity from `git config user.name`. If assigned to a different developer, print: "⚠ This milestone is assigned to [other dev]. Proceeding anyway — override if intentional." Do NOT block execution — this is advisory only.
 
-**Identify the next phase:** Find the first phase in ROADMAP.md with status "Pending" or the first unstarted phase in the PRD.
+**Identify the next milestone:** Find the first milestone in ROADMAP.md with status "Pending" or the first unstarted milestone 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 selected?** If PRD Selection (above) reached step 3 (no PRDs found): stop with the "No PRDs found" message.
-2. **Phase detailed enough?** The phase section in the PRD must have:
+2. **Milestone detailed enough?** The milestone section in the PRD must have:
    - Wave structure with agent assignments
    - Explicit file lists per agent
    - Verification commands
-   - If missing: "PRD phase section is too vague. Add wave structure + file lists, or run `/flow:spec`."
+   - If missing: "PRD milestone section is too vague. Add wave structure + file lists, or run `/flow:spec`."
 3. **Branch check:** Verify you're on the correct feature branch (from PRD header). If not, warn the user.
-4. **All phases done?** If no pending phases remain: "All phases complete! Run `/flow:done` to wrap up, or `/flow:milestone` for the next milestone."
+4. **All milestones done?** If no pending milestones remain: "All milestones complete! Run `/flow:done` to wrap up."
+
+## Step 2.5 — Linear Status: In Progress
+
+- Read the PRD header for `**Linear Project:**` field (name or URL)
+- If present and Linear MCP tools are available:
+  - Find the Linear project: `mcp__linear__get_project` with query matching project name
+  - List milestones: `mcp__linear__list_milestones` for that project
+  - Match current milestone name (e.g., "Milestone 2: Infrastructure Fixes") against Linear milestones
+  - Find issues assigned to that milestone: `mcp__linear__list_issues` with project + milestone filter
+  - For each issue in Backlog or Todo: `mcp__linear__update_issue` with `state: "In Progress"`
+  - Print: "Linear: [N] issues → In Progress ([milestone name])"
+- If no Linear Project in PRD header, or MCP not available: skip silently
 
 ## Step 3 — Staleness Check
 
-Compare this phase's PRD section against the actual codebase:
+Compare this milestone's PRD section against the actual codebase:
 - Do the files it references still exist / have the expected structure?
-- Were files created/deleted/significantly changed by prior phases that affect this phase?
+- Were files created/deleted/significantly changed by prior milestones that affect this milestone?
 - If stale references found: fix them in the PRD (update file paths, note structural changes) before proceeding. Print what you corrected.
 
-Do NOT rewrite the phase — just fix stale references so agents get accurate context.
+Do NOT rewrite the milestone — just fix stale references so agents get accurate context.
 
 ## Step 4 — Execute Waves
 
-For each wave defined in the PRD phase section:
+For each wave defined in the PRD milestone section:
 
 ### 4a. Prepare Agent Prompts
 
 For each agent in the wave, build a prompt containing:
 
 ```
-You are [agent-name] working on Phase [N]: [Phase Name].
+You are [agent-name] working on Milestone [N]: [Milestone Name].
 
 ## Your Task
 [Task description from PRD wave structure]
@@ -81,7 +93,7 @@ You are [agent-name] working on Phase [N]: [Phase Name].
 [Exact file list from PRD — absolute paths]
 
 ## Acceptance Criteria
-[Relevant criteria from the user stories this phase covers]
+[Relevant criteria from the user stories this milestone covers]
 
 ## Existing Code to Reuse
 [Inline the actual code/types/signatures from the "Key Existing Code" PRD section.
@@ -117,7 +129,7 @@ After a wave completes, check results:
 - Use AskUserQuestion: "Wave N failed completely. How to proceed?"
   - "Retry this wave"
   - "Skip to next wave"
-  - "Abort phase"
+  - "Abort milestone"
 
 **If SOME agents failed but others succeeded:**
 - Print: **"Wave N: X/Y agents succeeded, Z failed."**
@@ -125,7 +137,7 @@ After a wave completes, check results:
 - Use AskUserQuestion: "Some agents failed. How to proceed?"
   - "Retry failed agents"
   - "Continue without them"
-  - "Abort phase"
+  - "Abort milestone"
 
 When a wave completes successfully (all agents or user chose to continue), print: **"Wave N complete. Proceeding to Wave N+1."**
 
@@ -141,21 +153,21 @@ After each wave completes (and failure handling is resolved):
 
 After ALL waves complete:
 1. Run full verification suite
-2. Check all acceptance criteria for this phase's user stories
+2. Check all acceptance criteria for this milestone's user stories
 3. If verification fails, attempt to fix (max **3 attempts**):
    - After attempt 1 fails: Print **"Verification failed. Attempting fix (1/3)..."**
    - After attempt 2 fails: Print **"Verification failed. Attempting fix (2/3)..."**
    - After attempt 3 fails: Print **"Verification failed after 3 attempts. STOP."** Print the errors and use AskUserQuestion:
      - "Skip verification and continue"
      - "Fix manually and retry"
-     - "Abort this phase"
+     - "Abort this milestone"
    - Do NOT loop further beyond 3 attempts.
 
 ## Step 5 — Commit
 
-Create an atomic commit for this phase:
-- Stage only the files created/modified by this phase's agents
-- Commit message: `feat: [phase description] (Phase N)`
+Create an atomic commit for this milestone:
+- Stage only the files created/modified by this milestone's agents
+- Commit message: `feat: [milestone description] (Milestone N)`
 - Do NOT push unless the user asks
 
 ## Step 6 — Update Docs
@@ -166,21 +178,21 @@ Create an atomic commit for this phase:
 **Date:** [today]
 **Developer:** [git config user.name]
 **Branch:** [current branch]
-**Working On:** Phase [N]: [Name] from [PRD name]
-**Status:** Phase [N] complete. [brief description of what was built]
-**Next:** [Phase N+1 name, or "/flow:done to finalize milestone"]
+**Working On:** Milestone [N]: [Name] from [PRD name]
+**Status:** Milestone [N] complete. [brief description of what was built]
+**Next:** [Milestone N+1 name, or "/flow:done to finalize project"]
 **Blockers:** [any, or "None"]
 ```
 
-**ROADMAP.md (ALWAYS):** Mark this phase as "Complete ([today's date])"
+**ROADMAP.md (ALWAYS):** Mark this milestone as "Complete ([today's date])"
 
-**STATE.md (LAST PHASE ONLY):** Update STATE.md only if this was the LAST phase in the PRD (milestone complete). Update "What Was Built" section with:
+**STATE.md (LAST MILESTONE ONLY):** Update STATE.md only if this was the LAST milestone in the PRD (project complete). Update "What Was Built" section with:
 - Files created/modified (count + key names)
 - Commit SHA
-- Phase completion note
+- Milestone completion note
 - Keep "Active PRD" field pointing to the resolved PRD path
 
-For non-final phases, skip STATE.md updates.
+For non-final milestones, skip STATE.md updates.
 
 ## Step 7 — Route Next Action (MANDATORY — FINAL STEP)
 
@@ -190,27 +202,28 @@ For non-final phases, skip STATE.md updates.
 - Run additional cleanup or refactoring
 - Do any work beyond printing this summary
 
-Any post-phase work belongs in a SEPARATE `/flow:go` invocation or `/flow:task`.
+Any post-milestone work belongs in a SEPARATE `/flow:go` invocation or `/flow:task`.
 
 Print this EXACT structure (fill in values):
 
 ```
-Phase [N]: [Name] — Complete ✓
+Milestone [N]: [Name] — Complete ✓
 - [X] files created, [Y] modified
 - Commit: [SHA]
 - Verification: [passed/failed]
 
 Next flow command:
-→ /flow:go — execute Phase [N+1]: [Next Phase Name]
+→ /flow:go — execute Milestone [N+1]: [Next Milestone Name]
 → /flow:done — end session, update docs, generate handoff prompt
 ```
 
-If this was the last phase, replace the flow commands block with:
+If this was the LAST milestone in the PRD (no more pending milestones remain), replace the ENTIRE "Next flow command" block with:
 
 ```
-All phases complete — milestone done!
-
-→ /flow:done — finalize session (REQUIRED before ending)
+All milestones complete — project done!
+→ /flow:done — finalize project, auto-create PR, move issues to In Review (REQUIRED)
 ```
 
-**CRITICAL:** The `→ /flow:done` line MUST appear in EVERY phase completion output, whether or not more phases remain. This is non-negotiable. `/flow:done` is how session-end documentation happens.
+Do NOT suggest `/flow:go` when there are no remaining milestones — there is nothing left to execute.
+
+**CRITICAL:** The `→ /flow:done` line MUST appear in EVERY milestone completion output, whether or not more milestones remain. This is non-negotiable. `/flow:done` is how session-end documentation happens.