flow-cc 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.9.0] - 2026-02-15
+
+### Changed
+- Session files are now branch-scoped: `.claude/memory/session-{branch}.md` — multiple terminals no longer overwrite each other
+- PRD resolution now matches current git branch against PRD `**Branch:**` headers (STATE.md "Active PRD" is fallback)
+- `/flow:status` shows all active sessions across branches when multiple exist
+- Removed STATE.md project mismatch warning from `/flow:go` — PRD picker is authoritative
+
+### Fixed
+- Two terminals on different branches no longer corrupt each other's session state
+- PRD resolution no longer depends on STATE.md singleton — correct PRD found per-branch
+- `/flow:go` no longer warns falsely when STATE.md was updated by another terminal
+
+## [0.8.3] - 2026-02-15
+
+### Fixed
+- `/flow:spec` now writes `**Linear Project:**` field to PRD header — downstream skills (`flow:go`, `flow:done`) depend on it
+- `/flow:spec` now sets `projectMilestoneId` on every Linear issue — fixes milestone progress showing 0% despite issues existing
+- `/flow:spec` PRD template includes `**Linear Project:**` field (was missing, causing silent Linear skips)
+- `/flow:go` Step 6 now moves completed milestone issues to "Done" in Linear (were stuck at "In Progress" forever)
+- `/flow:done` Step 5.5 now handles interim milestone completion — moves completed milestone issues to "Done" before checking PR/project status
+
 ## [0.8.2] - 2026-02-14
 
 ### Fixed

package/README.md

@@ -86,7 +86,7 @@ Spec any project at any time. Execute the current one while planning ahead.
 
 - `/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
+- PRD resolution matches the current git branch against each PRD's `**Branch:**` header — STATE.md "Active PRD" is fallback
 - 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
 
@@ -129,7 +129,7 @@ your-project/
 ├── CLAUDE.md                    # Execution rules + learned rules
 ├── .claude/
 │   └── memory/
-│       └── session.md           # Per-developer session state (gitignored)
+│       └── session-{branch}.md  # Per-branch session state (gitignored)
 ├── .planning/
 │   ├── STATE.md                 # Project-level GPS — shared across developers
 │   ├── ROADMAP.md               # Project milestones and progress tracking
@@ -187,10 +187,10 @@ 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.
+- **Branch-scoped sessions** — Each branch gets its own session file at `.claude/memory/session-{branch-slug}.md` (gitignored). Multiple terminals on different branches never conflict. Same-branch conflicts are prevented by Linear assignment (one dev per issue/branch).
+- **Branch-based PRD resolution** — Skills match the current git branch against each PRD's `**Branch:**` header to find the active PRD. STATE.md "Active PRD" is fallback.
+- **Cross-developer awareness** — `/flow:status` shows all active sessions across branches. `/flow:go` warns if another developer was recently active on the same branch.
 - **`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.
 
 ---
 

package/VERSION

@@ -1 +1 @@
-0.8.2
+0.9.0

package/package.json

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

@@ -18,8 +18,8 @@ You are executing the `/flow:done` skill. This finalizes the current session by
 
 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)
+- Active PRD: (1) `git branch --show-current` (2) read first 10 lines of each `.planning/prds/*.md` for `**Branch:**` header (3) match current branch → active PRD (4) no match: fall back to STATE.md "Active PRD" (5) still none: check legacy root `PRD.md` (6) nothing: no active PRD
+- `.claude/memory/session-{branch-slug}.md` (if exists). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 
 Also run:
 - `git log --oneline -20` — commits this session
@@ -62,7 +62,7 @@ Check ROADMAP.md progress and commits to determine if a project completed this s
 
 ### 2.5. Write session.md (Every Session)
 
-Always runs. Create `.claude/memory/` if needed. Write `.claude/memory/session.md`:
+Always runs. Create `.claude/memory/` if needed. Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`. Write `.claude/memory/session-{branch-slug}.md`:
 
 ```
 # Session State
@@ -103,9 +103,9 @@ Always runs. Create `.claude/memory/` if needed. Write `.claude/memory/session.m
 
 ### 5. Commit Doc Updates
 
-**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]`
+**Normal session:** Only stage `tasks/lessons.md` if changed. Skip STATE.md/ROADMAP.md. Never stage files in `.claude/memory/` (all 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]`
+**Project boundary session:** Stage STATE.md, ROADMAP.md, lessons.md, archived files. Never stage files in `.claude/memory/` (all gitignored). Commit: `docs: session-end updates — [brief summary]`
 
 Do NOT push unless user asks.
 
@@ -148,14 +148,18 @@ Runs when 5.25 created a PR (or one already exists for this branch).
 
 - 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)
-- **If project complete** (all milestones done):
-  - Find project via `mcp__linear__list_projects`, match by name from PRD `**Linear Project:**` field
-  - Move project to Completed: `mcp__linear__update_project` with `state: "Completed"`
-  - Print: "Linear: project → Completed"
+- If found:
+  - Find project, list milestones via `mcp__linear__list_milestones`
+  - Cross-reference ROADMAP.md: for each milestone marked "Complete", find matching Linear milestone
+  - For each completed milestone: list its issues, move non-Done issues to "Done" via `mcp__linear__update_issue`
+  - Print: "Linear: [N] issues → Done ([milestone name])" per milestone; if 0 issues: "Linear: [milestone name] — no issues to update"
+  - If open PR exists (`gh pr list --head [branch] --state open`):
+    - Move remaining "In Progress" issues to "In Review" via `mcp__linear__update_issue`
+    - Print: "Linear: [N] issues → In Review (PR open)"
+  - If no PR: remaining in-progress issues stay (normal mid-project session end)
+  - **If project complete** (all milestones done):
+    - Move project to Completed: `mcp__linear__update_project` with `state: "Completed"`
+    - Print: "Linear: project → Completed"
 - Post progress comment on any branch-linked Linear issue
 
 ### 6. Route Next Action
@@ -188,7 +192,7 @@ Session complete.
 - Committed: [SHA | nothing to commit]
 - PR: [created #N | skipped (milestones remain)]
 - Review: [N comments addressed | pending | skipped]
-- Linear: [N issues → In Review, project → Completed | N issues → In Review | skipped]
+- Linear: [N issues → Done (milestone) | N → In Review (PR) | project → Completed | skipped]
 
 Next: [routing from Step 6]
 ```

package/skills/flow-go.md

@@ -14,7 +14,7 @@ You are executing the `/flow:go` skill. This reads the PRD, identifies the next
 
 ## Step 1 — Orient
 
-Read in parallel: `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`, `CLAUDE.md`, `.claude/memory/session.md` (if exists).
+Read in parallel: `.planning/STATE.md`, `.planning/ROADMAP.md`, `tasks/lessons.md`, `CLAUDE.md`, `.claude/memory/session-{branch-slug}.md` (if exists). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 
 Run `git config user.name` to get developer identity.
 
@@ -28,7 +28,7 @@ The user must always select which PRD to execute.
 
 3. **No PRDs found** — "No PRDs found in `.planning/prds/`. Run `/flow:spec` first." Stop.
 
-**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."
+**After selection:** Read the chosen PRD fully.
 
 **Assignment check:** Check milestone's `**Assigned To:**` against `git config user.name`. If different, print advisory warning. Do NOT block execution.
 
@@ -41,7 +41,8 @@ If any fail, stop and tell the user:
 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."
+4. **Session overlap check:** If `session-{branch-slug}.md` exists, read its `**Developer:**` field. If it names a different developer than `git config user.name`, print advisory: "[Developer] was last active on this branch ([date]). Check Linear assignment before proceeding." Non-blocking — do not stop execution.
+5. **All done?** If no pending milestones: "All milestones complete! Run `/flow:done` to wrap up."
 
 ## Step 2.5 — Linear Status: In Progress
 
@@ -132,11 +133,13 @@ Atomic commit for this milestone. Stage only files from this milestone's agents.
 
 ## Step 6 — Update Docs
 
-**Session state (ALWAYS):** Write `.claude/memory/session.md` (create dir if needed):
+**Session state (ALWAYS):** Write `.claude/memory/session-{branch-slug}.md` (create dir if needed). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 `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]`
 
 **ROADMAP.md (ALWAYS):** Mark milestone as "Complete ([date])"
 
+**Linear milestone (ALWAYS):** If `**Linear Project:**` in PRD and Linear MCP available: find completed milestone in Linear via `mcp__linear__list_milestones`, list its issues, move non-Done issues to "Done" via `mcp__linear__update_issue`. Print: "Linear: [N] issues → Done ([milestone name])". If 0 issues: print "Linear: [milestone name] — no issues to update". Skip silently if no Linear Project or MCP unavailable.
+
 **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)

package/skills/flow-spec.md

@@ -94,6 +94,7 @@ Write to `.planning/prds/{slug}.md` (create dir if needed) with this structure:
 **Branch:** feat/{project-slug}
 **Created:** [date]
 **Assigned To:** [developer or "unassigned"]
+**Linear Project:** [Linear project name if linked, or blank]
 
 ## Overview
 [One paragraph summary]
@@ -144,6 +145,8 @@ Subsections: New Database Tables, New API Endpoints, New Files to Create (groupe
 (Continue Milestone 2, etc.)
 ```
 
+> The `**Branch:**` field is the primary key for PRD resolution. Downstream skills match the current git branch against this field to find the active PRD.
+
 ## Phase 4 — Post-PRD Updates
 
 After writing the PRD:
@@ -161,10 +164,13 @@ After writing the PRD:
 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
+     - Found: use it. Not found: AskUserQuestion to pick existing project or skip Linear
+   - Add `**Linear Project:** [project name]` to the PRD header (after `**Assigned To:**`)
+   - For each implementation milestone: create a **Linear milestone** (`mcp__linear__create_milestone`) under the project
+   - For each user story: create a **Linear issue** (`mcp__linear__create_issue`) with BOTH `projectId` AND `projectMilestoneId` set — assign to the milestone whose `**Acceptance:**` field references that story. Title: "US-N: [story name]"
+   - **Critical:** Every issue MUST have `projectMilestoneId` set. Issues without milestone assignment break downstream status tracking.
    - If MCP unavailable: skip silently
-   - Print: "[N] milestones + [M] issues created under project [name]"
+   - Print: "[N] milestones + [M] issues created under [project name]"
 
 5. Print handoff prompt in a fenced code block.
 

package/skills/flow-status.md

@@ -16,10 +16,11 @@ Read ALL in parallel:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
 - 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
+- Active PRD: (1) `git branch --show-current` (2) read first 10 lines of each `.planning/prds/*.md` for `**Branch:**` header (3) match current branch → active PRD (4) no match: fall back to STATE.md "Active PRD" (5) still none: check legacy root `PRD.md` (6) nothing: no active PRD
 - Count lessons in `tasks/lessons.md` (if exists)
-- `.claude/memory/session.md` (if exists)
+- `.claude/memory/session-{branch-slug}.md` (if exists). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 - Run `git config user.name` for developer identity
+- List all `session-*.md` files in `.claude/memory/`. For each, read `**Date:**`, `**Developer:**`, `**Branch:**`, and `**Working On:**` fields.
 
 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."
@@ -66,7 +67,7 @@ When suggesting /flow:spec, do NOT append a project name — the project picker
 ```
 Project: [name] ([X/Y] milestones complete)
 Developer: [git config user.name]
-Session: [session.md "Working On" field if exists, or "No active session"]
+Session: [session-{branch-slug}.md "Working On" field if exists, or "No active session"]
 Last session: [date] — [what was built]
 Next: Milestone [N] — [name] ([short description])
 Lessons: [N]/10 active
@@ -76,10 +77,16 @@ PRDs:
   * {slug}.md (ready — future project)
   * PRD.md (legacy — at project root)
 
+Sessions:
+  {branch} — {Developer}: {Working On} ({date})
+  {branch} — {Developer}: {Working On} ({date}, stale — branch deleted)
+
 [routing recommendations from Step 3]
 ```
 
-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.
+Show Sessions section only if 2+ session files exist. Mark sessions as `stale` if their branch no longer exists locally (`git branch --list`).
+
+The PRDs section shows all PRD files found. Mark the one whose `**Branch:**` header matches the current git branch as "(active — current project)". If no branch match, fall back to STATE.md "Active PRD". 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 milestone counts and say "Run /flow:setup to set up tracking."
 

package/skills/flow-task.md

@@ -19,8 +19,8 @@ RULES:
 
 Read ALL in parallel (skip missing files gracefully):
 - `.planning/STATE.md`, `.planning/ROADMAP.md`, `CLAUDE.md`, `tasks/lessons.md`
-- Active PRD from `.planning/prds/` via STATE.md "Active PRD" field (or legacy root `PRD.md`)
-- `.claude/memory/session.md` (if exists)
+- Active PRD: (1) `git branch --show-current` (2) read first 10 lines of each `.planning/prds/*.md` for `**Branch:**` header (3) match current branch → active PRD (4) no match: fall back to STATE.md "Active PRD" (5) still none: check legacy root `PRD.md` (6) nothing: no active PRD
+- `.claude/memory/session-{branch-slug}.md` (if exists). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 
 Run `git config user.name` for developer identity.
 
@@ -83,7 +83,7 @@ IF `.planning/STATE.md` exists, append to "What Was Built":
 
 RULES: Do NOT update ROADMAP.md, PRDs, or create `.planning/` if missing.
 
-**Session state:** Write `.claude/memory/session.md` (create dir if needed):
+**Session state:** Write `.claude/memory/session-{branch-slug}.md` (create dir if needed). Branch slug: `git branch --show-current`, replace `/` with `-`, lowercase. Detached HEAD fallback: `session.md`.
 `# Session State` with Date, Developer, Branch, Working On (`/flow:task — [desc]`), Status, Next, Blockers fields.
 
 Lessons prompt via AskUserQuestion: "Any lessons worth capturing?" — "No" / "Yes, let me describe it" → capture to `tasks/lessons.md` as one-liner. Skip if lessons.md doesn't exist. If at 10, promote most battle-tested to `CLAUDE.md ## Learned Rules` first.

package/templates/session.md.template

@@ -1,3 +1,4 @@
+<!-- Filename: session-{branch-slug}.md — branch slug derived from git branch, / replaced with -, lowercased -->
 # Session State
 
 **Date:** {{DATE}}