flow-cc 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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

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.3
+0.9.0

package/package.json

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

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,7 +133,7 @@ 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])"

package/skills/flow-spec.md

@@ -145,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:

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}}