flow-cc 0.7.1 → 0.8.1

package/skills/flow-go.md

@@ -1,216 +1,168 @@
 ---
 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.
+**Core principle:** The PRD is the execution contract. Execute what it specifies. Do not freelance.
 
-**Plan mode warning:** Do NOT use this skill with plan mode enabled. `/flow:go` is execution — plan mode's read-only constraint prevents it from creating files, running agents, and committing work. The PRD is your plan; run `/flow:go` in normal mode.
-
-**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.
 
 ## Step 1 — Orient
 
-Read these files (in parallel):
-- `.planning/STATE.md` — current position
-- `.planning/ROADMAP.md` — phase 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
+Read in parallel: `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`, `CLAUDE.md`, `.claude/memory/session.md` (if exists).
 
 Run `git config user.name` to get developer identity.
 
 ### PRD Selection
 
-The user must always select which PRD to execute. No silent auto-resolution.
+The user must always select which PRD to execute.
 
-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 argument provided** (e.g., `/flow:go v3-payments`) — match against `.planning/prds/` by slug or `**Project:**` header. 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 PRDs in `.planning/prds/`, read each `**Status:**` and `**Project:**` header. AskUserQuestion to pick. Pre-select first "Ready for execution" PRD. Always show picker. Include legacy root `PRD.md` if found.
 
-3. **No PRDs found** — "No PRDs found in `.planning/prds/`. Run `/flow:spec` first." Stop here.
+3. **No PRDs found** — "No PRDs found in `.planning/prds/`. Run `/flow:spec` first." Stop.
 
-**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 chosen PRD. If its project doesn't match STATE.md current project, warn: "PRD project doesn't match current project. 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:** Check milestone's `**Assigned To:**` against `git config user.name`. If different, print advisory warning. Do NOT block execution.
 
-**Identify the next phase:** Find the first phase in ROADMAP.md with status "Pending" or the first unstarted phase in the PRD.
+**Identify next milestone:** First "Pending" milestone in ROADMAP.md or first unstarted in the PRD.
 
 ## Step 2 — Pre-flight Checks
 
-Run these checks before executing. If any fail, stop and tell the user what to do:
+If any fail, stop and tell the user:
 
-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:
-   - 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`."
-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."
+1. **PRD selected?** If no PRDs found, stop.
+2. **Milestone detailed enough?** Must have wave structure, file lists, verification commands. If missing: "PRD milestone too vague. Add wave structure + file lists, or run `/flow:spec`."
+3. **Branch check:** Verify correct feature branch (from PRD header). Warn if wrong.
+4. **All done?** If no pending milestones: "All milestones complete! Run `/flow:done` to wrap up."
 
-## Step 3 — Staleness Check
+## Step 2.5 — Linear Status: In Progress
+
+- Read PRD header for `**Linear Project:**` field
+- If present and Linear MCP available:
+  - Find project (`mcp__linear__get_project`), list milestones, match current milestone name
+  - Find issues in that milestone: `mcp__linear__list_issues`
+  - Move Backlog/Todo issues to In Progress: `mcp__linear__update_issue`
+  - Print: "Linear: [N] issues → In Progress ([milestone name])"
+- If no Linear Project or MCP unavailable: skip silently
 
-Compare this phase'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?
-- If stale references found: fix them in the PRD (update file paths, note structural changes) before proceeding. Print what you corrected.
+## Step 3 — Staleness Check
 
-Do NOT rewrite the phase — just fix stale references so agents get accurate context.
+Compare milestone's PRD section against actual codebase: do referenced files still exist with expected structure? Were files changed by prior milestones? If stale, fix references in the PRD before proceeding. Print corrections. Do NOT rewrite the milestone.
 
 ## Step 4 — Execute Waves
 
-For each wave defined in the PRD phase section:
+For each wave in the PRD milestone:
 
-### 4a. Prepare Agent Prompts
+### 4a. Agent Prompts
 
-For each agent in the wave, build a prompt containing:
+Build each agent's prompt:
 
 ```
-You are [agent-name] working on Phase [N]: [Phase Name].
+You are [agent-name] working on Milestone [N]: [Name].
 
-## Your Task
-[Task description from PRD wave structure]
+## Task
+[From PRD wave structure]
 
 ## Files to Create/Modify
-[Exact file list from PRD — absolute paths]
+[Absolute paths from PRD]
 
 ## Acceptance Criteria
-[Relevant criteria from the user stories this phase covers]
+[From user stories this milestone covers]
 
 ## Existing Code to Reuse
-[Inline the actual code/types/signatures from the "Key Existing Code" PRD section.
-Do NOT just reference file paths — READ the files and INLINE the relevant code
-so agents have it in their context without needing to search.]
+[INLINE actual code/types/signatures from "Key Existing Code" — do NOT just list paths]
 
 ## Rules
-- Only modify files in your list. Do not touch anything else.
-- Run verification after your work: [commands from CLAUDE.md]
-- Stage only your files when committing (never `git add .` or `git add -A`)
-- If you need output from another agent that isn't available yet, create a temporary stub and continue. Delete the stub before your final commit.
+- Only modify files in your list
+- Run verification: [commands from CLAUDE.md]
+- Stage only your files (never `git add .`)
 
-## Lessons (Rules to Follow)
-[Relevant lessons from tasks/lessons.md — filter to lessons that apply to this agent's work]
+## Lessons
+[Relevant items from tasks/lessons.md]
 ```
 
 ### 4b. Spawn Wave
 
-- Use TeamCreate or Task tool to spawn all agents in the wave simultaneously
-- Each agent runs with `mode: "bypassPermissions"` for autonomous execution
-- Print: **"Wave N: Spawned X agents — [agent-1-task], [agent-2-task], ..."**
-- As each agent completes, print: **"Wave N: agent-name completed (X/Y)"**
-- Set a reasonable timeout for each agent. If an agent hasn't completed after 10 minutes, check on it. If it's stuck, stop it and note the failure.
-- Wait for all agents in the wave to complete (or timeout) before moving to the next wave
+- Spawn all agents simultaneously via TeamCreate/Task with `mode: "bypassPermissions"`
+- Print: **"Wave N: Spawned X agents — [tasks]"**
+- As each completes: **"Wave N: agent-name completed (X/Y)"**
+- 10-minute timeout per agent — check if stuck, stop and note failure
+- Wait for all agents before next wave
 
 ### 4c. Wave Failure Handling
 
-After a wave completes, check results:
-
-**If ALL agents in a wave failed:**
-- Print: **"Wave N failed — all X agents errored."**
-- Show error summaries from each agent
-- Use AskUserQuestion: "Wave N failed completely. How to proceed?"
-  - "Retry this wave"
-  - "Skip to next wave"
-  - "Abort phase"
+**ALL agents failed:**
+- Print: **"Wave N failed — all X agents errored."** Show error summaries.
+- AskUserQuestion: "Retry this wave" / "Skip to next wave" / "Abort milestone"
 
-**If SOME agents failed but others succeeded:**
-- Print: **"Wave N: X/Y agents succeeded, Z failed."**
-- Show failed agent error summaries
-- Use AskUserQuestion: "Some agents failed. How to proceed?"
-  - "Retry failed agents"
-  - "Continue without them"
-  - "Abort phase"
+**SOME agents failed:**
+- Print: **"Wave N: X/Y succeeded, Z failed."** Show failed agent errors.
+- AskUserQuestion: "Retry failed agents" / "Continue without them" / "Abort milestone"
 
-When a wave completes successfully (all agents or user chose to continue), print: **"Wave N complete. Proceeding to Wave N+1."**
+On success: **"Wave N complete. Proceeding to Wave N+1."**
 
 ### 4d. Between Waves
 
-After each wave completes (and failure handling is resolved):
-1. Run verification commands from CLAUDE.md (e.g., `npx tsc --noEmit`, `npx biome check`)
-2. Check for integration issues between agents' output
-3. Fix any issues before proceeding to the next wave
-4. If verification fails and you can fix it quickly (< 2 minutes of work), fix it. Otherwise, stop and report.
+1. Run verification commands from CLAUDE.md
+2. Check integration issues between agents' output
+3. Fix issues before next wave
+4. If verification fails and fixable in <2 minutes, fix it. Otherwise stop and report.
 
 ### 4e. Final Verification
 
-After ALL waves complete:
+After ALL waves:
 1. Run full verification suite
-2. Check all acceptance criteria for this phase'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"
-   - Do NOT loop further beyond 3 attempts.
+2. Check all acceptance criteria for this milestone
+3. If verification fails, attempt fix (max **3 attempts**):
+   - Attempts 1-2: Print "Verification failed. Attempting fix (N/3)..."
+   - After attempt 3: Print "Verification failed after 3 attempts. STOP." Show errors. AskUserQuestion: "Skip verification and continue" / "Fix manually and retry" / "Abort this milestone"
+   - Do NOT loop 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)`
-- Do NOT push unless the user asks
+Atomic commit for this milestone. Stage only files from this milestone's agents. Message: `feat: [milestone description] (Milestone N)`. Do NOT push unless asked.
 
 ## Step 6 — Update Docs
 
-**Session state (ALWAYS):** Write `.claude/memory/session.md` (create `.claude/memory/` directory if needed):
-```
-# Session State
-**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"]
-**Blockers:** [any, or "None"]
-```
-
-**ROADMAP.md (ALWAYS):** Mark this phase as "Complete ([today's date])"
+**Session state (ALWAYS):** Write `.claude/memory/session.md` (create dir if needed):
+`Date | Developer | Branch | Working On: Milestone N: [Name] from [PRD] | Status: complete — [what was built] | Next: [Milestone N+1 or /flow:done] | Blockers: [any or None]`
 
-**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:
-- Files created/modified (count + key names)
-- Commit SHA
-- Phase completion note
-- Keep "Active PRD" field pointing to the resolved PRD path
+**ROADMAP.md (ALWAYS):** Mark milestone as "Complete ([date])"
 
-For non-final phases, skip STATE.md updates.
+**STATE.md (LAST MILESTONE ONLY):** Update only if this was the LAST milestone (project complete): files created/modified count, commit SHA, milestone completion note. Keep "Active PRD" pointing to resolved path. Skip STATE.md for non-final milestones.
 
 ## Step 7 — Route Next Action (MANDATORY — FINAL STEP)
 
-**STOP RULE:** This is the LAST thing you do. After printing the output below, STOP IMMEDIATELY. Do NOT:
-- Review or resolve code review comments
-- Create or update pull requests
-- 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`.
+**STOP RULE:** After printing the output below, STOP IMMEDIATELY. Do NOT review comments, create PRs, run cleanup, or do any additional work. Post-milestone work belongs in a separate `/flow:go` or `/flow:task`.
 
-Print this EXACT structure (fill in values):
+Print this EXACT structure:
 
 ```
-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 (no pending remain), replace "Next flow command" 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 no milestones remain.
+
+**CRITICAL:** The `/flow:done` line MUST appear in EVERY milestone completion output. Non-negotiable.

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,59 +33,54 @@ 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)
-- 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
+- Asks 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 scaffolding: `CLAUDE.md`, `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`
 
 **`/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
 - Linear issues created automatically (if Linear MCP available)
-- This is the single intake command — use it to add milestones, capture ideas, or file bugs
+- 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
+- Bug fixes, cleanup, one-off features — no PRD needed
 - 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
-
-**`/flow:spec`** — Run once per milestone
-- Interviews you about scope, user stories, technical design, trade-offs, and phasing
-- You can say "done" or "that's enough" anytime to cut the interview short
-- Produces `.planning/prds/{milestone}.md` — the execution contract with wave-based phases, file lists, and acceptance criteria
-- Can pre-spec future milestones in parallel terminal windows (each milestone gets its own PRD file)
-- Updates ROADMAP and STATE to reflect the plan (for the current milestone; future milestone specs skip STATE updates)
-
-**`/flow:go`** — Run once per phase (this is where the work happens)
-- Reads the PRD, finds the next pending phase
-- Checks for staleness (did prior phases change things this phase references?)
+- Scope guard recommends `/flow:spec` if task grows beyond 5 files or 3 layers
+
+**`/flow:spec`** — Run once per project
+- Interviews you about scope, user stories, technical design, trade-offs, and milestoning
+- Say "done" or "that's enough" anytime to cut the interview short
+- Produces `.planning/prds/{project}.md` — the execution contract with wave-based milestones
+- Can pre-spec future projects in parallel terminal windows
+- Updates ROADMAP and STATE to reflect the plan
+
+**`/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"
 
 **`/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
-- 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
+- Updates ROADMAP.md with milestone completions
+- Auto-transitions to the next planned project when current one completes
+- Captures lessons as one-liners, enforces 10-item cap
+- Generates a handoff prompt for 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
-- No need to remember where you cloned the repo — it finds it automatically
 
 ### Typical Session
 
 ```
 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,11 +91,10 @@ 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
 ```
 
 ### Learn More
 
 - Full design doc: see `DESIGN.md` in the flow-plugin repo
-- Compatible with GSD: `/gsd:debug` and `/gsd:map-codebase` still work alongside Flow