flow-cc 0.7.1 → 0.8.1

package/skills/flow-spec.md

@@ -1,198 +1,116 @@
 ---
 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.
 
-**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.
-
-**Skill boundary:** You are inside the `/flow:*` workflow. NEVER invoke, suggest, or reference skills from other workflow systems (`/lisa:*`, `/gsd:*`, `/superpowers:*`, etc.). Only suggest `/flow:*` commands as next steps. Do NOT use the Skill tool to call any non-flow skill. If the user needs a different workflow, they will invoke it themselves.
+**Constraints:** Do NOT use with plan mode (prevents file writes). Only use `/flow:*` commands — never invoke `/lisa:*`, `/gsd:*`, `/superpowers:*` or other skills.
 
 ## Phase 1 — Context Gathering
 
-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. 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:
-
-   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. Read `.planning/STATE.md`, `.planning/ROADMAP.md`, `CLAUDE.md`
+2. Check for existing PRD in `.planning/prds/` (or legacy root `PRD.md`)
+3. **Project Targeting:**
 
-   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.
+   1. **If argument provided** (e.g., `/flow:spec v3: Payments`) — match against ROADMAP.md projects. If no match, print available projects and ask.
 
-   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`.
+   2. **If no argument** — list incomplete projects from ROADMAP.md. Use AskUserQuestion to let the user pick. Pre-select the next unspecced project. Always show the picker.
 
-   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
+   3. **Derive PRD slug:** Lowercase project name, replace spaces/special chars with hyphens, collapse consecutive hyphens. PRD path: `.planning/prds/{slug}.md`.
 
-   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."
+   4. **If PRD exists at that path** → AskUserQuestion: "A PRD already exists at `.planning/prds/{slug}.md`. What would you like to do?" Options: "Resume editing", "Start fresh", "Pick a different project".
+      **If no PRD** → fresh interview.
 
-5. **Codebase scan** (brownfield projects) — spawn **3 parallel Explore subagents** via the Task tool to scan the codebase without consuming main context:
+   5. **Future project detection:** If target project != STATE.md current project, note it — STATE.md won't be updated. Print: "Speccing future project [name]. STATE.md will not be updated."
 
-   | Agent | Focus | Looks For |
-   |-------|-------|-----------|
-   | **Structure & Config** | Project skeleton, build tooling | `package.json`, `tsconfig`, config files, entry points, CI/CD, env setup |
-   | **UI, Pages & Routes** | Components, pages, routing | `components/`, `pages/`, `app/`, route definitions, layouts, navigation |
-   | **Data Layer & APIs** | Database, APIs, types | `api/`, `models/`, `types/`, `schemas/`, ORM definitions, query functions |
+4. **Codebase scan** (brownfield) — spawn **3 parallel Explore subagents** via Task tool:
+   - **Structure & Config** — project skeleton, build tooling, entry points, CI/CD
+   - **UI, Pages & Routes** — components, pages, routing, layouts, navigation
+   - **Data Layer & APIs** — database, APIs, types, schemas, ORM, queries
 
-   **Each subagent prompt MUST include:**
-   - **Exclusions:** NEVER scan `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`
-   - **Size-adaptive scanning:** If the agent's domain has >200 files, switch to focused mode (entry points, config, and type definitions only)
-   - **20-file sample cap per agent** (60 total across all 3)
-   - **15-line summary max** — structured as: key files found, patterns observed, reusable code/components, notes
-   - **Explicit instruction:** Do NOT return raw file contents — return only structured summaries
+   All agents: exclude `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `*.min.js`, `*.map`, `*.lock`. If domain has >200 files, switch to focused mode (entry points, config, types only). 20-file cap per agent. Return 15-line structured summary only — no raw file contents.
 
-6. **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."
+5. **Assemble summaries:** Collect 3 agent summaries (~45 lines total). Print: "Here's what I found in the codebase: [key components, patterns, data layer]. Starting the spec interview."
 
 ## Phase 2 — Adaptive Interview
 
-### CRITICAL RULES (follow these exactly)
+### Critical Rules
+
+1. **USE AskUserQuestion FOR ALL QUESTIONS.** Provide 2-4 concrete options per question based on Phase 1 context.
+2. **ASK NON-OBVIOUS QUESTIONS.** Probe deeper — edge cases, failure modes, downstream effects, minimum viable versions. Don't ask what you can infer from the codebase.
+3. **CONTINUE UNTIL THE USER SAYS STOP.** A thorough interview is 15-30 questions. After each answer, immediately ask the next question.
+4. **MAINTAIN A RUNNING DRAFT.** Every 2-3 questions, update `.planning/prds/{slug}.md` with what you've learned (create dir if needed). Print: "Updated PRD draft — added [brief summary]."
+5. **BE ADAPTIVE.** Base next question on previous answer. Follow interesting threads rather than robotically moving through categories.
+
+### First-Principles Mode (optional)
 
-1. **USE AskUserQuestion FOR ALL QUESTIONS.** Never just print questions as text. Always use the AskUserQuestion tool so the user gets structured prompts with selectable options. Provide 2-4 concrete options per question based on what you learned in Phase 1.
+Trigger: user says "challenge this", "first principles", or "push back". Ask 3-5 challenges first: Why build this? Simpler 80% alternative? What assumptions might be wrong? Then proceed to coverage areas.
 
-2. **ASK NON-OBVIOUS QUESTIONS.** Don't just ask "what features do you want?" — you already read the codebase. Ask questions that PROBE deeper:
-   - "I see you have [existing pattern]. Should we extend that or build a new approach?"
-   - "What happens when [edge case] occurs?"
-   - "You mentioned [X] — does that mean [Y] is also needed, or is that separate?"
-   - "What's the failure mode here? What does the user see when things go wrong?"
-   - "Who else touches this data/workflow? Any downstream effects?"
-   - "What's the minimum version of this that would be useful?"
+### Coverage Areas
 
-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.
+Cover these fluidly — no rigid rounds. Circle back when later answers reveal new info.
 
-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.
+**1. Scope Definition** — What's in/out of scope? MVP vs full vision? Sacred code?
 
-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.
+**2. User Stories (CRITICAL — most time here)** — Walk through key workflows step by step.
+- **Story-splitting:** If a story has >3-4 acceptance criteria, split it. Each story independently deliverable.
+- **Anti-vagueness:** BAD: "Works correctly", "Is fast". GOOD: "Returns 200 with JSON body", "Page renders in <200ms on 3G". Push back on vague criteria: "How would you specifically test that?"
+- **Verification per story:** Each must have at least one concrete verification step.
 
-### First-Principles Mode (optional)
+**3. Technical Design** — DB changes, API endpoints, new/modified files, reusable code, data flow, parallelization opportunities.
 
-If the user says "challenge this", "first principles", or "push back" — start with 3-5 challenge questions before detailed spec gathering:
-- "Why build this at all? What's the cost of NOT building it?"
-- "Is there a simpler way to achieve 80% of this value?"
-- "What assumptions are we making that might be wrong?"
-- "Who is this really for, and have they asked for it?"
-- "What would you cut if you had half the time?"
+**4. User Experience** — Key flows, edge cases (empty/error/loading states), accessibility, responsive behavior.
 
-Then proceed to the coverage areas below.
+**5. Trade-offs & Constraints** — Performance vs simplicity, security, third-party deps, acceptable tech debt.
 
-### Coverage Areas
+**6. Implementation Milestones** — Sequential breakdown, parallelization within milestones, critical path, cuttable milestones.
+- **Assignability check:** Probe which milestones could go to a second developer. Evaluate dependency chains, domain independence, context requirements. Add assignability notes per milestone.
 
-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?
-- 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)?
-
-**2. User Stories (CRITICAL — spend the most time here)**
-- What does the user actually DO? Walk through the key workflows step by step.
-- What should they see at each step? What feedback do they get?
-- Frame as: "As [role], I want [action], so that [outcome]"
-- **Story-splitting:** If a story has more than 3-4 acceptance criteria, split it into smaller stories. Each story should be independently deliverable.
-- **Anti-vagueness enforcement:**
-  - BAD acceptance criteria: "Works correctly", "Is fast", "Handles errors well", "Looks good"
-  - GOOD acceptance criteria: "Returns 200 with JSON body for valid input", "Shows error toast with message for invalid email format", "Page renders in < 200ms on 3G", "Matches Figma comp within 4px"
-  - If the user gives vague criteria, push back: "How would you specifically test that? What would you check?"
-- **Verification per story:** Each story must have at least one concrete verification step (a command to run, a page to visit, a state to check)
-
-**3. Technical Design**
-- What database changes are needed? (new tables, columns, indexes, migrations)
-- What API endpoints? (method, path, request/response shape, auth requirements)
-- What new files need to be created? What existing files get modified?
-- What existing utilities/components/DAL queries should be reused (not rebuilt)?
-- What's the data flow? Where does data originate, transform, and render?
-- Any wave-parallelization opportunities? (independent agents building separate files)
-
-**4. User Experience**
-- What are the key user flows? Walk through click-by-click.
-- What edge cases exist? (empty states, error states, loading states, partial data)
-- Accessibility requirements? (keyboard navigation, screen readers, ARIA labels)
-- Mobile/responsive behavior? (breakpoints, touch targets, layout shifts)
-- What does the user see while waiting? (loading spinners, skeletons, optimistic updates)
-
-**5. Trade-offs & Constraints**
-- Performance vs. simplicity? What's good enough for v1?
-- Any security considerations? (auth, data access, input validation)
-- Any third-party dependencies or integrations?
-- 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)
-- 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"
-
-**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?
-- Are there integration points that need end-to-end testing?
-- What should we check after each phase 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.
+**7. Verification & Feedback Loops** — Build verification commands, per-milestone "done" criteria, integration testing, monitoring.
+
+**User signals done:** If user says "done"/"finalize"/"ship it" — immediately go to Phase 3.
 
 ## Phase 3 — PRD Generation
 
 ### Minimum Viable PRD Check
 
-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 verification command** has been specified
-
-If any check fails, print what's missing and use AskUserQuestion:
-- "The PRD is thin — [missing items]. Want to continue the interview to flesh it out, or finalize as-is?"
-  - "Continue interview" — return to Phase 2 and probe the missing areas
-  - "Finalize as-is" — proceed with what we have
+Validate: at least **3 user stories** with acceptance criteria, **1 milestone**, **1 verification command**. If missing, AskUserQuestion: "Continue interview" or "Finalize as-is".
 
 ### Write PRD
 
-Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory first if it doesn't exist) with this EXACT structure:
+Write to `.planning/prds/{slug}.md` (create dir if needed) with this structure:
 
 ```markdown
-# [Milestone Name] — Specification
+# [Project Name] — Specification
 
-**Milestone:** [full milestone name, e.g., "Dashboard Analytics"]
+**Project:** [name]
 **Status:** Ready for execution
-**Branch:** feat/{milestone-slug}
-**Created:** [today's date]
-**Assigned To:** [developer name or "unassigned"]
+**Branch:** feat/{project-slug}
+**Created:** [date]
+**Assigned To:** [developer or "unassigned"]
 
 ## Overview
-[One paragraph summary of the milestone]
+[One paragraph summary]
 
 ## Problem Statement
-[Why this work exists — what problem does it solve?]
+[Why this work exists]
 
 ## Scope
 
 ### In Scope
-- [Bullet list of what ships in this milestone]
+- [items]
 
 ### Out of Scope
-- [Explicitly deferred items]
+- [deferred items]
 
 ### Sacred / Do NOT Touch
-- [Code paths that must not be modified, with reasons]
+- [protected code paths with reasons]
 
 ## User Stories
 
@@ -200,106 +118,67 @@ Write the PRD to `.planning/prds/{slug}.md` (create `.planning/prds/` directory
 **Description:** As [role], I want [action], so that [outcome].
 **Acceptance Criteria:**
 - [ ] Specific, testable requirement (names actual functions/components)
-- [ ] Another requirement
 - [ ] [Verification command] passes
 
-### US-2: [Feature Name]
-...
+(Continue US-2, US-3, etc.)
 
 ## Technical Design
 
-### New Database Tables
-[SQL DDL or schema description, with indexes]
+Subsections: New Database Tables, New API Endpoints, New Files to Create (grouped by milestone), Existing Files to Modify, Key Existing Code (DO NOT recreate — use as-is).
 
-### New API Endpoints
-[Method + path + request/response shape for each]
+## Implementation Milestones
 
-### New Files to Create
-[Grouped by phase. Absolute paths with one-line descriptions]
-
-### Existing Files to Modify
-[Paths + what changes in each]
+### Milestone 1: [Name]
+**Assigned To:** [developer or "unassigned"]
+**Goal:** [One sentence]
 
-### Key Existing Code (DO NOT recreate — use as-is)
-[Functions, utilities, DAL queries, components that agents should import/reuse]
+**Wave 1 — [Theme] (N agents parallel):**
+1. agent-name: Creates/modifies files — [what it does]
+2. agent-name: Creates/modifies files — [what changes]
 
-## Implementation Phases
+(Continue waves as needed)
 
-### Phase 1: [Name]
-**Assigned To:** [developer name or "unassigned"]
-**Goal:** [One sentence]
+**Verification:** [Exact commands]
+**Acceptance:** [Which US criteria this covers]
 
-**Wave 1 — [Theme] (N agents parallel):**
-1. agent-name: Creates file1.ts, file2.ts — [what it does]
-2. agent-name: Modifies file3.ts — [what changes]
-
-**Wave 2 — [Theme] (N agents parallel):**
-3. agent-name: Creates file4.ts — [what it does]
-4. agent-name: Wires component into page — [specifics]
-
-**Wave 3 — Integration:**
-5. Integration check, responsive verification, cleanup
-
-**Verification:** [Exact commands to run]
-**Acceptance:** US-1 criteria [list which], US-2 criteria [list which]
-
-### Phase 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]
-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]
-- [ ] Branch pushed and PR opened
-- [ ] STATE.md and ROADMAP.md updated
+(Continue Milestone 2, etc.)
 ```
 
 ## Phase 4 — Post-PRD Updates
 
-After writing the PRD to `.planning/prds/{slug}.md`:
+After writing the PRD:
 
-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 project section. Each milestone gets status "Pending".
 
-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)."
+2. **Update STATE.md** (current project only): Set milestone to "Milestone 1 — ready for `/flow:go`", set "Active PRD" path, update "Next Actions". **Skip if speccing a future project** — print: "PRD written. 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] — [description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md.
+   [One sentence of context].
    ```
 
-4. **Linear Issue Creation (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)
+4. **Linear Integration (optional):**
+   - Check if Linear MCP tools are available (`mcp__linear__list_teams`)
+   - If available: search for matching Linear project (`mcp__linear__list_projects`)
+     - Found: create one **Linear milestone** per implementation milestone, one **Linear issue** per user story/task (not per milestone)
+     - Not found: AskUserQuestion to pick project or skip
+   - If MCP unavailable: skip silently
+   - Print: "[N] milestones + [M] issues created under project [name]"
 
-5. Print the handoff prompt in a fenced code block.
+5. Print 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
+Before finalizing, self-check:
+- [ ] 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
-- [ ] "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")
+- [ ] Every milestone has verification commands
+- [ ] "Key Existing Code" references actual files/functions from the codebase scan
+- [ ] PRD written to `.planning/prds/{slug}.md`, NOT root `PRD.md`
+- [ ] No milestone has >5 agents in a single wave
+- [ ] Sacred code section is populated (even if "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
 ---
 
@@ -8,19 +8,18 @@ user_invocable: true
 
 You are executing the `/flow:status` skill. This is a READ-ONLY operation. Do NOT modify any files.
 
-**Skill boundary:** You are inside the `/flow:*` workflow. NEVER invoke, suggest, or reference skills from other workflow systems (`/lisa:*`, `/gsd:*`, `/superpowers:*`, etc.). Only suggest `/flow:*` commands as next steps. Do NOT use the Skill tool to call any non-flow skill.
+**Skill boundary:** Only use `/flow:*` commands. Never invoke or suggest `/lisa:*`, `/gsd:*`, `/superpowers:*` or any non-flow skill.
 
 ## Step 1 — Read Context Files
 
-Read ALL of the following in parallel:
+Read ALL in parallel:
 - `.planning/STATE.md`
 - `.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
+- List `.planning/prds/` for all PRD files (or legacy root `PRD.md`)
+- Read the active PRD (from STATE.md "Active PRD" field) for 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
+- `.claude/memory/session.md` (if exists)
+- Run `git config user.name` for developer identity
 
 IF both STATE.md AND ROADMAP.md are missing:
 - Print: "No flow project found. Run `/flow:setup` to set up, or `/flow:task` for a quick standalone fix."
@@ -28,76 +27,61 @@ 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, complete (`Done`/`Complete`/`[x]`/`✓`), and pending/in-progress milestones
+- Identify the FIRST incomplete milestone — 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 next action from ROADMAP.md milestone statuses, NOT from STATE.md "Next Actions" text. STATE.md may be stale. ROADMAP.md is the source of truth.
 
 ## Step 3 — Determine Routing
 
-Use this explicit decision tree:
+**IF pending milestones exist AND a PRD exists (in `.planning/prds/` or legacy root):**
+→ Primary: `/flow:go` to execute Milestone [N]: [name]
+→ Alt: `/flow:done` if wrapping up
+→ Alt: `/flow:task` for quick fixes (no PRD needed)
 
-**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 milestones exist BUT no PRD exists:**
+→ `/flow:spec` — select a project and build its execution plan
+→ `/flow:task` — for quick fixes (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
-→ `/flow:task` — for quick fixes or cleanup (no PRD needed)
+**IF all milestones complete AND a "Planned" project exists in ROADMAP.md:**
+→ Primary: `/flow:done` to finalize (will auto-transition to next project)
+→ Alt: `/flow:task` for quick fixes (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)
-→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+**IF all milestones complete AND no next project:**
+→ Primary: `/flow:done` to finalize
+→ Then: `/flow:triage` to add the next project
+→ Alt: `/flow:task` for quick fixes (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
-→ Alt: `/flow:task` for quick fixes or cleanup (no PRD needed)
+**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 (no PRD needed)
 
-**IF no phases exist in ROADMAP (milestone defined but not planned):**
-→ `/flow:spec` — select a milestone 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
-```
-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.
+When suggesting /flow:spec, do NOT append a project name — the project picker inside /flow:spec handles selection.
 
 ## 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"]
+Session: [session.md "Working On" field if 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)
-  [For each additional PRD in .planning/prds/:]
-  * {slug}.md (ready — future milestone)
-  [If legacy PRD.md at root:]
+  * {slug}.md (active — current project)
+  * {slug}.md (ready — future project)
   * 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.
-
-When listing PRDs, if a PRD has `**Assigned To:**` fields in its phase sections, show assignment status in the PRD listing, e.g.:
-```
-  * {slug}.md (active — Phase 3 assigned to Matt, Phase 4 unassigned)
-```
+The PRDs section shows all PRD files found. Mark the one matching STATE.md "Active PRD" as "(active — current project)". Mark others as "(ready — future project)". Legacy root `PRD.md` shows as "(legacy — at project root)". Omit PRDs section if no PRD files exist.
 
-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