flow-cc 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.1] - 2026-02-14
+
+### Changed
+- All 8 active skill files compressed in-place — 67.5KB → 46KB total (-31.7%)
+- `flow-spec.md` reduced 49% (17.4KB → 8.9KB) — condensed PRD template, coverage areas, codebase scan table
+- `flow-go.md` reduced 37% (11.2KB → 7.0KB) — merged wave failure blocks, compressed agent prompt template
+- `flow-done.md` reduced 26% (10.1KB → 7.5KB) — tightened STATE template, PR body, review polling
+- `flow-setup.md` reduced 25% (6.4KB → 4.9KB) — compressed templates and question descriptions
+- `flow-task.md` reduced 29% (6.1KB → 4.3KB) — compressed scope guard, verification, session template
+- `flow-status.md` reduced 28% (5.1KB → 3.6KB) — condensed routing decision tree, status block
+- `flow-intro.md` reduced 14% (4.7KB → 4.0KB) — removed GSD compat line, trimmed command descriptions
+- `flow-triage.md` reduced 16% (4.5KB → 3.8KB) — fewer example rows, general tightening
+- Skill boundary warning standardized to 1 line across all files
+- Plan mode + skill boundary merged into single `**Constraints:**` line in flow-spec and flow-go
+
+### Fixed
+- Deleted stray `nul` file (Windows artifact) from repo root
+
+## [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

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.1
+0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-cc",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "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,187 +1,190 @@
 ---
 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. Handles project-complete PR creation, automated review, and Linear status management.
 user_invocable: true
 ---
 
 # /flow:done — Session End + Handoff
 
-You are executing the `/flow:done` skill. This finalizes the current session by updating all planning documents and generating a handoff prompt for the next session.
+You are executing the `/flow:done` skill. This finalizes the current session by updating all planning documents and routing to the next action.
 
 **This is the most important skill for sustainability.** Without proper session-end docs, the next session starts blind.
 
-**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.
 
 ## Steps
 
 ### 1. Gather Context
 
-Read these files (in parallel where possible):
-- `.planning/STATE.md` — current state
-- `.planning/ROADMAP.md` — milestone/phase 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)
-- `.claude/memory/session.md` (if exists) — personal session state
+Read in parallel:
+- `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`, `CLAUDE.md`
+- Active PRD from `.planning/prds/` (resolve via STATE.md "Active PRD" field, or legacy root `PRD.md`)
+- `.claude/memory/session.md` (if exists)
 
-Also gather:
-- Run `git log --oneline -20` to see commits this session
-- Run `git diff --stat` to check for uncommitted changes
-- Run `git config user.name` to get developer identity
-- If uncommitted changes exist, warn the user before proceeding
+Also run:
+- `git log --oneline -20` — commits this session
+- `git diff --stat` — uncommitted changes (warn user if any exist)
+- `git config user.name` — developer identity
 
-### 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.
+Check ROADMAP.md progress and commits to determine if a project completed this session.
 
-**IF milestone completed this session** — REPLACE the entire file (do NOT append). Keep under 80 lines.
+**IF project completed** — 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 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 |
-| 4 | [name] | Pending |
+| 2 | [name] | In Progress |
 
 ## What Was Built (This Session)
-- [Bullet list of what was accomplished]
-- [Include file counts, key components, commit SHAs]
+- [Bullet list — file counts, key components, commit SHAs]
 
 ## Key Decisions
-- [Any architectural or design decisions made]
+- [Architectural or design decisions made]
 
 ## Next Actions
-1. [Specific next step — usually "Run /flow:go for Phase N"]
+1. [Specific next step]
 ```
 
-**IF normal session (no milestone completed)** — SKIP STATE.md entirely. Print: "Normal session — STATE.md skipped (milestone boundaries only)."
+**IF normal session** — SKIP STATE.md. 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.
-
-Create `.claude/memory/` directory if it doesn't exist.
-
-Write `.claude/memory/session.md` with the following content:
+Always runs. Create `.claude/memory/` if needed. Write `.claude/memory/session.md`:
 
 ```
 # Session State
-
-**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"]
-**Status:** [what was accomplished this session — bullet list of key items]
-**Next:** [what to pick up next session]
+**Date:** [today]
+**Developer:** [git config user.name]
+**Branch:** [current branch]
+**Working On:** [Linear issue ID + desc, or PRD milestone, or "standalone task"]
+**Status:** [bullet list of accomplishments]
+**Next:** [what to pick up next]
 **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:**
+- Mark completed milestones with dates
+- Ensure pending milestones have enough detail for a one-line-prompt start
+- **Archive check** (if project fully complete):
+  - Skip if `.planning/` doesn't exist
+  - Create `.planning/archive/` if needed (`mkdir -p`)
+  - Move milestone details to `.planning/archive/project-{slug}.md`
+  - Keep only summary row in ROADMAP table
+  - Archive PRD: move `.planning/prds/{slug}.md` (or legacy root `PRD.md`) to `.planning/archive/PRD-{slug}.md`
+  - Clear STATE.md "Active PRD" → "None"; mark project "Complete" in ROADMAP
+  - **Project transition:** Check for next "Planned" project:
+    - If exists: update to "Pending — needs `/flow:spec`", update STATE.md current project
+    - If none: no transition needed
 
-- 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:
-  - 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.
-  - 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.
-
-**IF normal session (no milestone completed)** — SKIP ROADMAP.md entirely. Print: "Normal session — ROADMAP.md skipped (milestone boundaries only)."
+**IF normal session** — SKIP ROADMAP.md. Print: "Normal session — ROADMAP.md skipped (project boundaries only)."
 
 ### 4. Update lessons.md
 
-- Review the session for mistakes, corrections, or discovered issues
-- Auto-suggest lessons based on errors encountered (if any)
-- Ask the user: "Any lessons from this session?" using AskUserQuestion with options:
-  - "No new lessons"
-  - "Yes, let me add some" (user types them)
-  - "Use your suggestions" (if you auto-suggested any)
-- Add new lessons as one-liners: `- **[topic]** The rule`
-- **Hard cap enforcement (max 10 active):**
-  - If lessons.md already has 10 items and a new one needs to be added:
-    1. Identify the most battle-tested/internalized lesson
-    2. Promote it to `CLAUDE.md ## Learned Rules` section
-    3. Delete it from lessons.md
-    4. Add the new lesson
-  - If `CLAUDE.md ## Learned Rules` hits 15 items, delete the most obvious/internalized rule to make room
+- Review session for mistakes, corrections, or discovered issues
+- Auto-suggest lessons from errors encountered
+- AskUserQuestion: "Any lessons from this session?" with options: "No new lessons" / "Yes, let me add some" / "Use your suggestions"
+- Format: `- **[topic]** The rule`
+- **Hard cap (max 10):** If at 10, promote the most battle-tested to `CLAUDE.md ## Learned Rules`, delete from lessons.md, then add new. If Learned Rules hits 15, delete the most obvious rule to make room.
 
 ### 5. Commit Doc Updates
 
-**Normal session (no milestone 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:**
-- 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
-
-### 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:
-  ```
-  [Developer Name] — Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md (US-X).
-  [One sentence of context]. [One sentence of what NOT to do if relevant].
-  ```
-- If milestone is complete AND a next milestone was transitioned to (from Step 3):
-  ```
-  [Developer Name] — Milestone [name] complete. Next: [next milestone name]. Run /flow:spec to plan it.
-  ```
-- If milestone is complete AND no next milestone exists:
-  ```
-  [Developer Name] — All milestones 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.
+**Normal session:** Only stage `tasks/lessons.md` if changed. Skip STATE.md/ROADMAP.md. Never stage `.claude/memory/session.md` (gitignored). If no shared doc changes, print "No shared doc changes to commit." Otherwise: `docs: session-end updates — [brief summary]`
+
+**Project boundary session:** Stage STATE.md, ROADMAP.md, lessons.md, archived files. Never stage session.md. Commit: `docs: session-end updates — [brief summary]`
+
+Do NOT push unless user asks.
+
+### 5.25. Auto-Create PR (Project Complete Only)
+
+- Check if ALL milestones in PRD are "Complete" in ROADMAP.md
+- If all complete AND no open PR for branch (`gh pr list --head [branch] --state open`):
+  - Parse PRD for all Linear issue IDs
+  - Push branch: `git push -u origin [branch]`
+  - Auto-generate PR body:
+    ```
+    ## Summary
+    [Project name] — [one-line from PRD]
+    ## Milestones Completed
+    - Milestone 1: [Name] (completed [date])
+    ## Linear Issues
+    Closes MSIG-34, Closes MSIG-35, ...
+    ## Verification
+    - `npx tsc --noEmit` — passed
+    - `npx biome check` — passed
+    ```
+  - `gh pr create --title "[project name]" --body "[body]"`
+  - Print: "PR created: [URL]" and "Linear: [N] issues will auto-close on merge"
+- If milestones remain OR PR exists: skip silently
+
+### 5.3. Await Automated Review (Project Complete Only)
+
+Runs when 5.25 created a PR (or one already exists for this branch).
+
+1. Get PR number from `gh pr create` output or `gh pr list --head [branch]`
+2. Parse repo owner/name from `git remote get-url origin`
+3. Poll every 2 min, up to 10 min (5 checks max):
+   - `gh api repos/{owner}/{repo}/pulls/{N}/reviews` — non-empty reviews
+   - `gh api repos/{owner}/{repo}/pulls/{N}/comments` — bot/review comments
+4. **Reviews arrive:** Read all, address each, push fixes. Print: "Automated review: [N] comments addressed, fixes pushed."
+5. **No reviews after 10 min:** Print: "No comments after 10 min. Proceeding." Write "Automated review pending" in session.md Blockers.
+6. **Pre-existing PR:** Check for unaddressed review comments from prior sessions; address before proceeding.
+
+### 5.5. Linear Status Update + Progress Comment
+
+- Check if Linear MCP tools are available; skip silently if not
+- Parse active PRD for `**Linear Project:**` field
+- If found and open PR exists (`gh pr list --head [branch] --state open`):
+  - Move all "In Progress" issues to "In Review" via `mcp__linear__update_issue`
+  - 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
+
+### 6. Route Next Action
+
+**Mid-project (milestones remain):**
+```
+Next steps:
+→ /flow:go — execute Milestone [N+1]: [Name]
+→ /clear + /flow:go — if context is heavy
+```
+
+**Project complete + next project exists:**
+```
+Project complete! → Review + merge PR #[N] → /flow:spec — plan [next project]
+```
+
+**Project complete + no next project:**
+```
+All projects complete! → Review + merge PR #[N] → /flow:triage — plan what's next
+```
 
 ### 7. Print Summary
 
 ```
 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]
+- PR: [created #N | skipped (milestones remain)]
+- Review: [N comments addressed | pending | skipped]
+- Linear: [N issues → In Review | skipped]
 
-Handoff prompt:
-[the prompt in a code block]
+Next: [routing from Step 6]
 ```