diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c59150b..f283fd7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "session-continuity", - "version": "0.21.1", - "description": "Cross-session memory for Claude Code projects via four in-repo docs: SESSION_PRIMER.md (current state), PROJECT_CONTEXT.md (stable repo context), OUTSTANDING_ITEMS.md (deferred follow-ups), and LEARNINGS.md (hard-won bugs).", + "version": "0.22.0", + "description": "Cross-session memory for Claude Code projects via five in-repo docs: SESSION_PRIMER.md (current state), PROJECT_CONTEXT.md (stable repo context), BACKLOG.md (deferred follow-ups), ROADMAP.md (strategic direction), and LEARNINGS.md (hard-won bugs).", "author": { "name": "Tal Golan" }, diff --git a/.session-continuity/OUTSTANDING_ITEMS.md b/.session-continuity/BACKLOG.md similarity index 96% rename from .session-continuity/OUTSTANDING_ITEMS.md rename to .session-continuity/BACKLOG.md index 0a09ab6..cbea869 100644 --- a/.session-continuity/OUTSTANDING_ITEMS.md +++ b/.session-continuity/BACKLOG.md @@ -1,6 +1,6 @@ -# Outstanding Items — session-continuity +# Backlog — session-continuity -Backlog of explicitly deferred follow-ups and decisions — not bugs (those +Explicitly deferred follow-ups and decisions — not bugs (those go in `.session-continuity/LEARNINGS.md`), not current state (that's `.session-continuity/SESSION_PRIMER.md`). An item lives here from the moment it's flagged until the moment the code proves it resolved, then diff --git a/.session-continuity/ROADMAP.md b/.session-continuity/ROADMAP.md new file mode 100644 index 0000000..60786a3 --- /dev/null +++ b/.session-continuity/ROADMAP.md @@ -0,0 +1,19 @@ +# Roadmap — session-continuity + +Strategic direction — where this project is headed, not the tactical +queue (that's `.session-continuity/BACKLOG.md`). Freeform: no numbering, +no permanence rules, no length cap. Rewrite sections wholesale as +direction changes; this file's history lives in git, not in careful +edits. + +## Now + +TBD + +## Next + +TBD + +## Later + +TBD diff --git a/.session-continuity/SESSION_PRIMER.md b/.session-continuity/SESSION_PRIMER.md index 062273a..7b4d138 100644 --- a/.session-continuity/SESSION_PRIMER.md +++ b/.session-continuity/SESSION_PRIMER.md @@ -20,6 +20,9 @@ rarely. ## Current state +- **v0.22.0 in progress** — renamed OUTSTANDING_ITEMS.md to BACKLOG.md, + added ROADMAP.md, added /session-continuity:help. Branch + feature/backlog-roadmap-help, not yet merged. - **v0.19.0 released** — commit `460f507` pushed to `main`, tag `v0.19.0` pushed, GitHub Actions `release.yml` ran clean (12s), [GitHub Release](https://github.com/talgolan/session-continuity/releases/tag/v0.19.0) @@ -401,17 +404,17 @@ rarely. - Three slash commands are stable (`primer`, `learning`, `end-session`). - `hooks/hooks.json` uses `if: "Bash(git commit *)"` to scope the `PreToolUse` hook; it does not fire on every Bash call. - `.claude-plugin/marketplace.json` present so the repo is installable via `/plugin marketplace add talgolan/session-continuity`. -- `.session-continuity/` holds `SESSION_PRIMER.md`, `PROJECT_CONTEXT.md` (new in v0.13.0), `OUTSTANDING_ITEMS.md` (new in v0.18.0), and `LEARNINGS.md`. Dev artifacts (marketplace-submission notes, specs, plans, recommendation docs) live under `meta/`. +- `.session-continuity/` holds `SESSION_PRIMER.md`, `PROJECT_CONTEXT.md` (new in v0.13.0), `BACKLOG.md` (new in v0.18.0 as `OUTSTANDING_ITEMS.md`, renamed in v0.22.0), `ROADMAP.md` (new in v0.22.0), and `LEARNINGS.md`. Dev artifacts (marketplace-submission notes, specs, plans, recommendation docs) live under `meta/`. - No known open bugs; outstanding items are feature-level. **Current `git log --oneline -5` (primary branch):** ``` -5fa6c59 chore: bump to 0.21.0 — /session-continuity:update command -001b1f3 feat: add /session-continuity:update command -38b94e0 chore: bump to 0.20.0 — end-session prompt-wait/compute-only split -fef4935 docs: update session continuity -c14cdd9 feat(end-session): separate human-response wait from ritual compute time +db15d1a docs: README documents BACKLOG.md, ROADMAP.md, and /help +70600f6 chore: bump to 0.22.0 — BACKLOG.md rename, ROADMAP.md, /help command +a6fe12e docs: template pointers reference BACKLOG.md and ROADMAP.md +2232eae docs: REFERENCE.md documents BACKLOG.md and ROADMAP.md +20194a1 docs: SKILL.md documents BACKLOG.md, ROADMAP.md, and /help ``` Regenerate this block whenever you commit — see diff --git a/CHANGELOG.md b/CHANGELOG.md index e29de91..442f1f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.22.0] — 2026-08-31 + +### Added +- **New `.session-continuity/ROADMAP.md` file** — strategic direction (Now/Next/Later), freeform, no numbering. `/session-continuity:primer` creates it on Init mode and stubs it in for existing installs during the BACKLOG.md migration below. +- **New `/session-continuity:help` command** — explains what the plugin does, why, and what each of the five `.session-continuity/` files is for. Zero args, read-only. + +### Changed +- **`.session-continuity/OUTSTANDING_ITEMS.md` renamed to `BACKLOG.md`.** Same semantics (permanent numbering, delete-on-close, title + 1-3 sentence cap) — rename only. `/session-continuity:primer` migrates existing installs automatically (new Step 3c): detects `OUTSTANDING_ITEMS.md` without a `BACKLOG.md` alongside it, `git mv`s the file, and stubs in `ROADMAP.md` in the same step. `hooks/session-start.sh` nudges any install still on the old filename to run `/session-continuity:primer`. + ## [0.21.1] — 2026-08-31 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e56ba7e..8fac89e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,12 @@ Thanks for thinking about contributing. This is a small, opinionated project wit ## Scope first -This skill ships a specific pattern: three in-repo Markdown files (`.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, and `.session-continuity/LEARNINGS.md`) with slash commands and hooks that make the habit of using them cheap. That's the whole scope. +This skill ships a specific pattern: five in-repo Markdown files (`.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/BACKLOG.md`, `.session-continuity/ROADMAP.md`, and `.session-continuity/LEARNINGS.md`) with slash commands and hooks that make the habit of using them cheap. That's the whole scope. **PRs that fit the existing shape move quickly.** Bug fixes, prose improvements to existing commands, small behavior refinements that sharpen the existing tools — all welcome. **PRs that expand scope will be declined or redirected.** Examples of scope expansion: -- A fourth in-repo doc (e.g. `.session-continuity/DECISIONS.md`, `.session-continuity/ROADMAP.md`). The three-file split is load-bearing; see the README's "Why three files" section. +- A sixth in-repo doc (e.g. `.session-continuity/DECISIONS.md`, `.session-continuity/DECISIONS_LOG.md`). The five-file split is load-bearing; see the README's "Why five files" section. - Integration with a specific memory server, vector database, or external storage. The point is plain files in git. - A plugin architecture, extension API, or configuration system. The slash commands and hooks are the interface. - Auto-commit, auto-push, or "just do it all for me" modes. Deliberate capture is a design choice, not an oversight. @@ -22,7 +22,7 @@ If you're unsure whether your idea fits, open an issue first and describe what y 2. Read `.session-continuity/SESSION_PRIMER.md` — it's the current-state snapshot for this very repo, maintained by the plugin's own commands. 3. Skim `.session-continuity/PROJECT_CONTEXT.md` — stable repo layout and conventions for this repo. 4. Skim `.session-continuity/LEARNINGS.md` — real bugs we've hit, grouped by layer. Useful context for hook/command work. -5. Skim the most recent spec + plan in `meta/superpowers/` to see how changes are shaped before they become code. (`.session-continuity/` in this repo is intentionally limited to the three files the plugin ships — primer, PROJECT_CONTEXT, and LEARNINGS. Dev artifacts like specs, plans, and marketplace paperwork live under `meta/` so they don't pollute the plugin's public surface.) +5. Skim the most recent spec + plan in `meta/superpowers/` to see how changes are shaped before they become code. (`.session-continuity/` in this repo is intentionally limited to the five files the plugin ships — primer, PROJECT_CONTEXT, BACKLOG, ROADMAP, and LEARNINGS. Dev artifacts like specs, plans, and marketplace paperwork live under `meta/` so they don't pollute the plugin's public surface.) ## Local development @@ -100,7 +100,8 @@ session-continuity/ │ └── templates/ │ ├── SESSION_PRIMER.md │ ├── PROJECT_CONTEXT.md -│ ├── OUTSTANDING_ITEMS.md +│ ├── BACKLOG.md +│ ├── ROADMAP.md │ └── LEARNINGS.md ├── commands/ │ ├── primer.md # /session-continuity:primer @@ -108,7 +109,8 @@ session-continuity/ │ ├── end-session.md # /session-continuity:end-session │ ├── spike-check.md # /session-continuity:spike-check │ ├── doctor.md # /session-continuity:doctor -│ └── update.md # /session-continuity:update +│ ├── update.md # /session-continuity:update +│ └── help.md # /session-continuity:help ├── hooks/ │ ├── hooks.json # hook registration │ ├── session-start.sh # SessionStart event @@ -142,7 +144,7 @@ session-continuity/ └── LICENSE ``` -The marketplace catalog that lets users `/plugin marketplace add` this plugin no longer lives in this repo — it moved to the separate `talgolan/claude-plugins` repo (see the README's "Install" section). `.session-continuity/` here is intentionally limited to the three files the plugin ships — primer, PROJECT_CONTEXT, and LEARNINGS — so it mirrors what users see in their own projects. Repo-specific dev artifacts (design specs, implementation plans, submission paperwork) live under `meta/` so they don't pollute the plugin's public surface. +The marketplace catalog that lets users `/plugin marketplace add` this plugin no longer lives in this repo — it moved to the separate `talgolan/claude-plugins` repo (see the README's "Install" section). `.session-continuity/` here is intentionally limited to the five files the plugin ships — primer, PROJECT_CONTEXT, BACKLOG, ROADMAP, and LEARNINGS — so it mirrors what users see in their own projects. Repo-specific dev artifacts (design specs, implementation plans, submission paperwork) live under `meta/` so they don't pollute the plugin's public surface. Files that change together live together. If you're adding a new slash command, you'll likely touch `commands/.md`, the commands paragraph in `skills/session-continuity/SKILL.md`, `README.md`, `PRIVACY.md`, and `CHANGELOG.md`. If you're modifying a hook, you'll likely only touch `hooks/.sh`. diff --git a/PRIVACY.md b/PRIVACY.md index 642e00b..1499688 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -10,11 +10,11 @@ This plugin does not collect, transmit, or store personal data about you. All da ## What data the plugin handles -- **File contents in your own repositories.** The slash commands `/session-continuity:primer`, `/session-continuity:learning`, and `/session-continuity:end-session` read and write `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/OUTSTANDING_ITEMS.md`, and `.session-continuity/LEARNINGS.md` in the current git repository. These are ordinary files in your repo; the plugin stores nothing elsewhere. `/session-continuity:spike-check`, `/session-continuity:doctor`, and `/session-continuity:update` touch no files at all — they print a checklist/report/instructions and (for spike-check) ask questions in-conversation. -- **Git metadata.** The commands invoke `git log`, `git status`, `git diff --cached`, and similar read-only commands to populate the primer and checklist. This metadata is processed locally and written into the same four files; it is never transmitted. +- **File contents in your own repositories.** The slash commands `/session-continuity:primer`, `/session-continuity:learning`, and `/session-continuity:end-session` read and write `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/BACKLOG.md`, `.session-continuity/ROADMAP.md`, and `.session-continuity/LEARNINGS.md` in the current git repository. These are ordinary files in your repo; the plugin stores nothing elsewhere. `/session-continuity:spike-check`, `/session-continuity:doctor`, `/session-continuity:update`, and `/session-continuity:help` touch no files at all — they print a checklist/report/instructions and (for spike-check) ask questions in-conversation. +- **Git metadata.** The commands invoke `git log`, `git status`, `git diff --cached`, and similar read-only commands to populate the primer and checklist. This metadata is processed locally and written into the same five files; it is never transmitted. - **Hook payloads.** Claude Code passes the hook scripts a JSON payload containing the current working directory and, depending on the hook, the Bash command about to run or the file path + content about to be written/edited. The scripts read these values locally to decide whether to emit a reminder or block the action. Nothing from the payload is transmitted or persisted outside the running session. -**The plugin does not touch:** environment variables, shell history, editor state, other files in your repo, any file outside the current working directory, your clipboard, or anything on disk outside the four documented files plus the update-check cache described below. +**The plugin does not touch:** environment variables, shell history, editor state, other files in your repo, any file outside the current working directory, your clipboard, or anything on disk outside the five documented files plus the update-check cache described below. ## External network calls diff --git a/README.md b/README.md index c68b11d..1658904 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,33 @@ # session-continuity -Cross-session memory for Claude Code projects. A skill Claude loads on its own, four plain-Markdown docs committed to your repo, six slash commands, and a set of session hooks that surface the right knowledge at the right moment. +Cross-session memory for Claude Code projects. A skill Claude loads on its own, five plain-Markdown docs committed to your repo, seven slash commands, and a set of session hooks that surface the right knowledge at the right moment. ## Why this exists LLMs start every session cold. Claude doesn't remember yesterday's debugging, last week's refactor, or the three-hour bug you eventually cornered. The usual fixes reach for clever infrastructure: vector databases, MCP memory servers, auto-generated notes stored in vendor-specific ways that hide the knowledge outside the repo, away from human eyes and tangled with whichever tool happens to be installed. -This plugin takes a different route: plain Markdown files, committed to git, alongside the code they describe. Four files hold the memory, four slash commands keep them honest, and a handful of hooks nudge or gate when the habit slips. That's the whole system. +This plugin takes a different route: plain Markdown files, committed to git, alongside the code they describe. Five files hold the memory, seven slash commands keep them honest, and a handful of hooks nudge or gate when the habit slips. That's the whole system. The choice buys three properties most AI memory systems lack. Humans and Claude read the same files, so there's no opaque layer between you and what's remembered. Every change is a git commit, so history is auditable and every edit has an author. The storage is plain text, so it's portable: any tool that reads Markdown can use it, including future LLMs that don't exist yet. -There's a second reason, less obvious than the first: **shorter Claude Code sessions are better sessions**. Less accumulated context means lower cost per turn, better accuracy, and less context rot. Retrieval accuracy at large context sizes varies sharply by model, and every model degrades as the window fills. A workflow that lets you end a session and start a fresh one without losing context isn't just convenient; it's how you keep Claude sharp across a long-running project. That's what `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/OUTSTANDING_ITEMS.md`, and `.session-continuity/LEARNINGS.md` buy you: the ability to close the laptop at any point, come back cold, and have a new session up to speed in four file reads instead of rebuilding context by re-prompting. +There's a second reason, less obvious than the first: **shorter Claude Code sessions are better sessions**. Less accumulated context means lower cost per turn, better accuracy, and less context rot. Retrieval accuracy at large context sizes varies sharply by model, and every model degrades as the window fills. A workflow that lets you end a session and start a fresh one without losing context isn't just convenient; it's how you keep Claude sharp across a long-running project. That's what `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/BACKLOG.md`, `.session-continuity/ROADMAP.md`, and `.session-continuity/LEARNINGS.md` buy you: the ability to close the laptop at any point, come back cold, and have a new session up to speed in five file reads instead of rebuilding context by re-prompting. ## What's in the box | Component | What it does | |---|---| -| **`session-continuity` skill** | Claude loads it automatically based on the task. It teaches Claude the four-file pattern, the maintenance rules, and the decision tree for what belongs where, even before you run any command. | +| **`session-continuity` skill** | Claude loads it automatically based on the task. It teaches Claude the five-file pattern, the maintenance rules, and the decision tree for what belongs where, even before you run any command. | | **`.session-continuity/SESSION_PRIMER.md`** | The current-state snapshot. What's true about the project right now. | | **`.session-continuity/PROJECT_CONTEXT.md`** | Stable repo context — layout, conventions, module table. Changes rarely, only when the project's shape itself changes. | -| **`.session-continuity/OUTSTANDING_ITEMS.md`** | Backlog of explicitly deferred follow-ups and decisions. Permanent numbering, delete-on-close, title + 1-3 sentence cap per item. | +| **`.session-continuity/BACKLOG.md`** | Explicitly deferred follow-ups and decisions. Permanent numbering, delete-on-close, title + 1-3 sentence cap per item. | +| **`.session-continuity/ROADMAP.md`** | Strategic direction — Now/Next/Later. Freeform, no numbering, rewritten wholesale as direction changes. | | **`.session-continuity/LEARNINGS.md`** | Append-only wisdom. A numbered graveyard of bugs that were painful enough to never want to rediscover. | | **`/session-continuity:primer`** | Init, split, refresh, or check the primer. State-dispatching. | | **`/session-continuity:learning`** | Append a new LEARNINGS entry interactively, with stable numbering. | | **`/session-continuity:end-session`** | Close-out ritual: refresh the primer, mine this session for new learnings, and print a state checklist. | -| **`/session-continuity:doctor`** | Read-only diagnostic: is the install actually wired up — hooks registered, all four files present and not stale, plugin root resolved and not a stale cache, gate scripts executable. | +| **`/session-continuity:doctor`** | Read-only diagnostic: is the install actually wired up — hooks registered, all five files present and not stale, plugin root resolved and not a stale cache, gate scripts executable. | | **`/session-continuity:update`** | Print the commands to pull and activate this plugin's latest published version. | +| **`/session-continuity:help`** | Explain what the plugin does, why, and what each of the five files is for. | | **`/session-continuity:spike-check`** | Emit the stand-in spike checklist before a spike, so it's designed to hit the real binary + auth/lifecycle/fixed-port path. | | **Session hooks** | A SessionStart reminder, a non-blocking commit nudge, an action-keyed retrieval gate, a smoke-task gate for plan files, a proven-claim gate for specs/plans, an occurrence-counter gate for LEARNINGS, an evidence-preservation gate for smoke design, a flaky-claim gate, a multi-backend-parity gate, and a weekly freshness check. | @@ -42,36 +44,42 @@ From inside Claude Code, add the `talgolan` catalog as a plugin marketplace, the Run `/reload-plugins` once the install finishes. Once the plugin is live on the official Anthropic marketplace (`claude-plugins-official`), you'll also be able to discover it via `/plugin` → **Discover**; until then, the two-step sequence above works on any recent Claude Code install. -## The four files +## The five files -Everything else is machinery around these four documents. Each has a different update contract. +Everything else is machinery around these five documents. Each has a different update contract. **`.session-continuity/SESSION_PRIMER.md`** is the high-churn current-state snapshot: latest commits, working state. It's the fastest path for a fresh session to get productive. Refresh it alongside substantive commits so it always reflects what's true right now. It's meant to be overwritten freely and short enough to re-read on every session start. **`.session-continuity/PROJECT_CONTEXT.md`** is stable reference material: repo layout, module table, workflow conventions, test expectations, "where to look for what." It changes rarely — only when the project's shape itself changes — so a fresh session skims it once and doesn't need to re-check it every turn. -**`.session-continuity/OUTSTANDING_ITEMS.md`** is the backlog: explicitly +**`.session-continuity/BACKLOG.md`** is the tactical queue: explicitly deferred decisions and follow-ups, not bugs and not current state. Item numbers are permanent — a closed item is deleted outright, never renumbered — so a cross-reference to "item 4" stays valid for as long as item 4 exists. Each item is capped at a title plus 1-3 sentences; anything longer belongs in a linked spec, not inlined here. +**`.session-continuity/ROADMAP.md`** is strategic direction, independent +of the tactical queue — Now/Next/Later, freeform. No numbering, no +permanence rules, no length cap; rewrite it wholesale as direction +changes rather than editing around old entries. + **`.session-continuity/LEARNINGS.md`** is the opposite of the rest: append-only, numbered, preserved. Each entry is a bug that took 15+ minutes to diagnose, written as a recipe (the trap, the symptom, the fix, an optional diagnostic signal). Numbers are stable so cross-references never rot. New entries go to the top of their section but take the next available number. -All four files ship as templates, so you start from a real structure instead of a blank page. +All five files ship as templates, so you start from a real structure instead of a blank page. ## The commands ### `/session-continuity:primer` -One command, five behaviors, dispatched on the repo's current state: +One command, six behaviors, dispatched on the repo's current state: -- **No primer yet** → copies the templates into `.session-continuity/`, fills every placeholder it can derive (project name, latest commits, working directory, test command), asks you for the rest, and stages all four files. Any field you skip becomes `TBD` rather than a leftover `{{PLACEHOLDER}}`. +- **No primer yet** → copies the templates into `.session-continuity/`, fills every placeholder it can derive (project name, latest commits, working directory, test command), asks you for the rest, and stages all five files. Any field you skip becomes `TBD` rather than a leftover `{{PLACEHOLDER}}`. - **Primer exists but not yet split** → partitions its stable sections (layout, conventions, module table, "where to look for what") into a new `.session-continuity/PROJECT_CONTEXT.md`, leaving the primer with only the volatile shortlist. One-time content move, no file move. -- **Primer has an inline Outstanding items section, no OUTSTANDING_ITEMS.md yet** → extracts that section verbatim into the new file, preserving item numbers as permanent IDs, and removes it from the primer. Runs immediately on detection — this plugin has one consumer today, so migration is pushed, not offered indefinitely. -- **Primer exists but drifted** → regenerates the `git log --oneline -5` block, re-runs the primer's test commands (retrying flaky suites up to three times so a single bad sample doesn't cry wolf), surfaces every commit since the last refresh as a candidate, and prompts you for outstanding-items changes before staging. -- **Primer current** → reports a four-line status (HEAD, last refresh, outstanding-item count, learnings count) and exits without touching anything. +- **Primer has an inline Outstanding items section, no BACKLOG.md yet** → extracts that section verbatim into the new file, preserving item numbers as permanent IDs, and removes it from the primer. Runs immediately on detection — this plugin has one consumer today, so migration is pushed, not offered indefinitely. +- **Project has the old `OUTSTANDING_ITEMS.md` file, no `BACKLOG.md` yet** → renames it to `BACKLOG.md` (numbers and content unchanged) and stubs in `ROADMAP.md` if it doesn't already exist. Runs immediately on detection, same push-not-offer policy as the bullet above. +- **Primer exists but drifted** → regenerates the `git log --oneline -5` block, re-runs the primer's test commands (retrying flaky suites up to three times so a single bad sample doesn't cry wolf), surfaces every commit since the last refresh as a candidate, and prompts you for backlog changes before staging. +- **Primer current** → reports a four-line status (HEAD, last refresh, backlog count, learnings count) and exits without touching anything. Drift is detected by diffing the stored `git log` block against reality, not by file mtime, because formatters and save-on-blur bump mtime without changing content. @@ -83,7 +91,7 @@ Appends a properly formatted entry. It prompts for the recipe fields, lets you p The close-out ritual, bounded to at most two prompts in the common case: -1. **Refresh the primer**, but only if it actually drifted. If the `git log` block already matches reality, this step checks whether any outstanding item now looks resolved (verified against actual code, never guessed) — if so, it offers a lightweight prompt to close it; otherwise it's a silent no-op. +1. **Refresh the primer**, but only if it actually drifted. If the `git log` block already matches reality, this step checks whether any backlog item now looks resolved (verified against actual code, never guessed) — if so, it offers a lightweight prompt to close it; otherwise it's a silent no-op. 2. **Mine the session for learnings.** It reads the session transcript (falling back to the live context window when the transcript isn't reachable) and runs four deterministic detectors: a *retry burst* (the same command run three or more times), a *revert/reset* (hard reset, checkout, revert, or `rm -rf` on a tracked file), an *error recurrence* (the same normalized error three or more times across 15+ minutes), and a *fix burst* (a `fix:` commit preceded by a long investigation). Candidates are pre-drafted into full LEARNINGS entries and presented in one batch for a single confirm. 3. **Print a state checklist.** Staged, unstaged, untracked, and unpushed are each enumerated file by file, with a suggested commit message and a terminal sign-off so you know the ritual is done. @@ -91,7 +99,7 @@ It never commits and never pushes. The checklist flags what's outstanding; you d ### `/session-continuity:doctor` -Read-only, zero-arg diagnostic: is the install actually wired up? Five ✓/⚠️ rows — install mode (plugin vs. vendored), hooks registered, all four `.session-continuity/` files present with the primer's staleness re-checked, `CLAUDE_PLUGIN_ROOT` resolves and isn't a stale plugin-cache dir, gate scripts executable. Never mutates anything; every fix is a printed command you run yourself. +Read-only, zero-arg diagnostic: is the install actually wired up? Five ✓/⚠️ rows — install mode (plugin vs. vendored), hooks registered, all five `.session-continuity/` files present with the primer's staleness re-checked, `CLAUDE_PLUGIN_ROOT` resolves and isn't a stale plugin-cache dir, gate scripts executable. Never mutates anything; every fix is a printed command you run yourself. ### `/session-continuity:spike-check` @@ -101,6 +109,10 @@ Emits a five-question stand-in checklist *before* a spike is built, so the spike Prints the three commands to pull this plugin's latest published version and activate it in the current session — nothing more. There's no tool that lets the assistant invoke `/plugin` or `/reload-plugins` on your behalf, so this command doesn't try; it's a static reminder, not automation. +### `/session-continuity:help` + +Zero-arg, read-only: explains what the plugin is for, why it exists, and what each of the five `.session-continuity/` files is responsible for, plus a live command list built from every command's own frontmatter `description` — not hand-duplicated prose, so the list can't drift out of sync with the commands themselves. + ## The hooks The hooks are bash scripts wired through `hooks/hooks.json`. They split into two philosophies. @@ -137,7 +149,7 @@ The hooks are bash scripts wired through `hooks/hooks.json`. They split into two /session-continuity:primer ``` -Detects no primer exists, copies templates into `.session-continuity/`, fills derivable placeholders, asks you for the rest, and stages all four files. +Detects no primer exists, copies templates into `.session-continuity/`, fills derivable placeholders, asks you for the rest, and stages all five files. **Before a commit:** @@ -145,7 +157,7 @@ Detects no primer exists, copies templates into `.session-continuity/`, fills de /session-continuity:primer ``` -Detects drift, regenerates the `git log` block, prompts for outstanding-items updates, and stages the refreshed primer. Commit it alongside your substantive change, not in a primer-only commit. +Detects drift, regenerates the `git log` block, prompts for backlog updates, and stages the refreshed primer. Commit it alongside your substantive change, not in a primer-only commit. **After a painful bug (15+ min to diagnose):** @@ -174,7 +186,8 @@ The SessionStart hook reminds Claude to read `.session-continuity/SESSION_PRIMER | Observation | Where | |---|---| | "The latest commit is X" | `.session-continuity/SESSION_PRIMER.md` → Current state | -| "We should follow up on X" | `.session-continuity/OUTSTANDING_ITEMS.md` → new numbered entry | +| "We should follow up on X" | `.session-continuity/BACKLOG.md` → new numbered entry | +| "Where is this headed next quarter" | `.session-continuity/ROADMAP.md` → Now/Next/Later | | "How is this repo laid out" | `.session-continuity/PROJECT_CONTEXT.md` → Repo layout | | "What are our workflow conventions" | `.session-continuity/PROJECT_CONTEXT.md` → Workflow conventions | | "Bun replaces the CA trust store" | `.session-continuity/LEARNINGS.md` → new numbered entry | @@ -183,19 +196,21 @@ The SessionStart hook reminds Claude to read `.session-continuity/SESSION_PRIMER **Do not put in these files:** secrets (ever — use ``), information trivially rederivable from code, narrative fluff. -## Why four files +## Why five files -Most memory systems lump everything together: notes, decisions, observations, bug reports, all blended in a searchable soup. That fails in a specific way for software projects, because current state, stable context, deferred decisions, and accumulated wisdom have four different update contracts. +Most memory systems lump everything together: notes, decisions, observations, bug reports, all blended in a searchable soup. That fails in a specific way for software projects, because current state, stable context, deferred decisions, strategic direction, and accumulated wisdom have five different update contracts. The **primer** is high-churn. Yesterday's commit is already out of date; next week's priorities will look different again. It needs to be overwritten freely, refreshed with every substantive change, and short enough to re-read on every session start. A primer that accumulates forever becomes a scroll tomb. **PROJECT_CONTEXT** is low-churn. Repo layout, module boundaries, and workflow conventions don't change every commit — they change when the project's shape itself changes. It's still overwritten (not append-only) when it does change, but a fresh session only needs to skim it once, not re-check it every turn like the primer. -**LEARNINGS** is the outlier of the four: append-only, numbered, preserved. Each entry is hard-won knowledge that would cost the same hours again if lost. It needs stable numbering so cross-references don't rot, and preservation exactly as written when the author's memory was sharpest. A LEARNINGS file that gets rewritten loses the point. +**LEARNINGS** is the outlier of the five: append-only, numbered, preserved. Each entry is hard-won knowledge that would cost the same hours again if lost. It needs stable numbering so cross-references don't rot, and preservation exactly as written when the author's memory was sharpest. A LEARNINGS file that gets rewritten loses the point. + +**BACKLOG** shares PROJECT_CONTEXT's slow pace, but not its permanence: unlike LEARNINGS' append-only history, closed items are deleted outright, so the file only ever holds the live backlog, never a full record of everything ever deferred. -**OUTSTANDING_ITEMS** shares PROJECT_CONTEXT's slow pace, but not its permanence: unlike LEARNINGS' append-only history, closed items are deleted outright, so the file only ever holds the live backlog, never a full record of everything ever deferred. +**ROADMAP** is the newest of the five and the least ceremonious: no numbering, no permanence, no length cap. It exists because "what's the tactical backlog" and "what's the strategic direction" are different questions with different lifespans — a backlog item resolves in days or weeks; a roadmap entry describes a horizon that outlives any single item. -Blending any of these forces bad tradeoffs. Current-state notes drown stable context or accumulated wisdom; wisdom gets edited away when someone trims "stale" entries. Keeping them in separate files with separate update contracts means the primer answers "what is true right now," PROJECT_CONTEXT answers "what is true about this project generally," OUTSTANDING_ITEMS answers "what have we deliberately deferred," and LEARNINGS answers "what should I know to avoid rediscovering pain" — and none of the four pretends to answer another's question. +Blending any of these forces bad tradeoffs. Current-state notes drown stable context or accumulated wisdom; wisdom gets edited away when someone trims "stale" entries. Keeping them in separate files with separate update contracts means the primer answers "what is true right now," PROJECT_CONTEXT answers "what is true about this project generally," BACKLOG answers "what have we deliberately deferred," ROADMAP answers "where is this headed," and LEARNINGS answers "what should I know to avoid rediscovering pain" — and none of the five pretends to answer another's question. ## What it is not @@ -203,15 +218,15 @@ Understanding what this plugin deliberately avoids is as useful as understanding **Not automatic.** The slash commands require you to invoke them. The hooks nudge or gate; they don't write files themselves. Automatic memory capture sounds appealing but has a predictable failure mode: noise, contradictions, and stale state that Claude confidently believes is current. A memory system is only useful if its contents can be trusted, and trust comes from deliberate capture. -**Not a framework.** There's no extension API, no plugin architecture, no abstraction layer waiting for you to subclass it. The surface is one skill, six commands, and a handful of hooks, and that's the whole product. The surface stays deliberately small — a new command needs a concrete failure mode behind it (like `/session-continuity:doctor`'s "a mechanism silently never fired and nobody could ask why"), not speculative convenience. PRs that add surface without one will be declined. +**Not a framework.** There's no extension API, no plugin architecture, no abstraction layer waiting for you to subclass it. The surface is one skill, seven commands, and a handful of hooks, and that's the whole product. The surface stays deliberately small — a new command needs a concrete failure mode behind it (like `/session-continuity:doctor`'s "a mechanism silently never fired and nobody could ask why"), not speculative convenience. PRs that add surface without one will be declined. -**Not a replacement for `CLAUDE.md`, vector search, or MCP memory servers.** Each solves a different problem. `CLAUDE.md` is for durable project conventions ("always use Bun, never commit to main"). Vector search is for semantic retrieval across large unstructured corpora. MCP memory servers are for cross-project context that needs rich querying. This plugin is for *the four specific questions above*, in *a single project's repo*, with *plain text in git* as the storage. When one of the other tools fits your need better, use it instead. +**Not a replacement for `CLAUDE.md`, vector search, or MCP memory servers.** Each solves a different problem. `CLAUDE.md` is for durable project conventions ("always use Bun, never commit to main"). Vector search is for semantic retrieval across large unstructured corpora. MCP memory servers are for cross-project context that needs rich querying. This plugin is for *the five specific questions above*, in *a single project's repo*, with *plain text in git* as the storage. When one of the other tools fits your need better, use it instead. **Not an LLM-only tool.** Every file is human-readable and human-editable. You can open `.session-continuity/LEARNINGS.md` in any editor, add an entry by hand, and Claude will see it on the next session. The slash commands are conveniences, not gates. ## Team-wide use -All four files are checked-in artifacts, not gitignored. Commit them under `.session-continuity/` and the whole team benefits: +All five files are checked-in artifacts, not gitignored. Commit them under `.session-continuity/` and the whole team benefits: - Add a line to the project's `CLAUDE.md` pointing every session at the primer and the maintenance rules. - LEARNINGS doubles as a living post-mortem log for human teammates, not just Claude. @@ -234,7 +249,7 @@ The weekly freshness check in SessionStart will nudge you inside Claude when a n ## Contributing -Issues and PRs welcome at [github.com/talgolan/session-continuity](https://github.com/talgolan/session-continuity). See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide: scope policy, local development, authoring conventions for commands and hooks, and the release process. TL;DR: this plugin ships a four-file pattern, not a framework. PRs that fit the existing shape will move quickly; PRs that expand scope will be declined or redirected. +Issues and PRs welcome at [github.com/talgolan/session-continuity](https://github.com/talgolan/session-continuity). See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide: scope policy, local development, authoring conventions for commands and hooks, and the release process. TL;DR: this plugin ships a five-file pattern, not a framework. PRs that fit the existing shape will move quickly; PRs that expand scope will be declined or redirected. ## Privacy diff --git a/commands/doctor.md b/commands/doctor.md index fe2174b..5a74476 100644 --- a/commands/doctor.md +++ b/commands/doctor.md @@ -1,5 +1,5 @@ --- -description: Diagnose whether session-continuity is actually wired up in this project — hooks registered, all four files present and not stale, plugin root resolves and isn't a stale cache, gate scripts executable. Zero args, read-only. +description: Diagnose whether session-continuity is actually wired up in this project — hooks registered, all five files present and not stale, plugin root resolves and isn't a stale cache, gate scripts executable. Zero args, read-only. --- # /session-continuity:doctor @@ -40,7 +40,7 @@ echo "--- vendored-mode check (only matters if ROOT_EXISTS=0 above) ---" [ -f .claude/settings.json ] && cat .claude/settings.json || echo "NO_PROJECT_SETTINGS" echo "--- .session-continuity/ files ---" -for f in SESSION_PRIMER.md OUTSTANDING_ITEMS.md PROJECT_CONTEXT.md LEARNINGS.md; do +for f in SESSION_PRIMER.md BACKLOG.md ROADMAP.md PROJECT_CONTEXT.md LEARNINGS.md; do [ -f ".session-continuity/$f" ] && echo "$f=EXISTS" || echo "$f=MISSING" done @@ -64,7 +64,7 @@ Work through the five rows below using the output above. Never invent a result f - Plugin mode: ✓ if `HOOKS_JSON_EXISTS=1` (Claude Code auto-wires this when the plugin is enabled — this is a sanity check that the install isn't partial/corrupted, not proof the user configured anything). ⚠️ if `HOOKS_JSON_EXISTS=0` — the plugin directory is missing `hooks/hooks.json`; reinstalling the plugin is the fix. - Vendored mode: grep the `.claude/settings.json` content captured above for the hook script names (`session-start.sh`, `learnings-surface.sh`, etc.). ✓ if at least `session-start.sh` and `learnings-surface.sh` appear (the two hooks a vendored install needs most — the primer reminder and the retrieval hook). ⚠️ listing which expected hook names are absent, with a pointer to `SKILL.md`'s hooks section for the entries to copy in. -3. **Four `.session-continuity/` files exist; primer not stale.** ✓/⚠️ per file from the `EXISTS`/`MISSING` lines. For `SESSION_PRIMER.md` specifically, if it exists, also compare its own `git log --oneline -5` block (read the file) against the `git log --oneline -5` output captured above — mismatch means ⚠️ stale, "run `/session-continuity:primer` to refresh." This is the only file with an objective staleness signal in this repo; the other three don't get a staleness check here, only an existence check. +3. **Five `.session-continuity/` files exist; primer not stale.** ✓/⚠️ per file from the `EXISTS`/`MISSING` lines. For `SESSION_PRIMER.md` specifically, if it exists, also compare its own `git log --oneline -5` block (read the file) against the `git log --oneline -5` output captured above — mismatch means ⚠️ stale, "run `/session-continuity:primer` to refresh." This is the only file with an objective staleness signal in this repo; the other four don't get a staleness check here, only an existence check. 4. **`CLAUDE_PLUGIN_ROOT` resolves and isn't stale.** Skip this row entirely in vendored mode (nothing to check). In plugin mode: ✓ if `ROOT_EXISTS=1`. Then check staleness — from the `ls "$CACHE_PARENT"` output, if it lists sibling version directories, compare the resolved version (parsed from `plugin.json` above) against the highest version number listed. If a newer one exists: ⚠️ "resolved root is v``, but v`` is already installed in the cache — this session started before the update landed; restart the session to pick it up." If they match, or the cache-parent listing wasn't available (different install layout), ✓ with a note that the check was skipped when applicable — don't fail the row over a probe that simply didn't apply. @@ -78,7 +78,7 @@ Emit the report as a table, same convention as `/session-continuity:end-session` |---|---|---| | Install mode | ✓ | "Plugin vX.Y.Z at ``" OR "Vendored (CLAUDE_PLUGIN_ROOT unresolved)" | | Hooks registered | ✓ / ⚠️ | plugin: "hooks.json present" OR "⚠️ hooks/hooks.json missing — reinstall the plugin" · vendored: "session-start.sh + learnings-surface.sh found in .claude/settings.json" OR "⚠️ missing: `` — see SKILL.md's hooks section" | -| .session-continuity/ files | ✓ / ⚠️ | "All four present, primer current" OR "⚠️ missing: ``" OR "⚠️ primer stale — run /session-continuity:primer" | +| .session-continuity/ files | ✓ / ⚠️ | "All five present, primer current" OR "⚠️ missing: ``" OR "⚠️ primer stale — run /session-continuity:primer" | | CLAUDE_PLUGIN_ROOT | ✓ / ⚠️ / (skipped) | "vX.Y.Z, matches latest cached" OR "⚠️ resolved to vX.Y.Z, but vX.Y.Z+1 is cached — restart the session" OR "skipped (vendored mode)" | | Gate scripts executable | ✓ / ⚠️ / (skipped) | "All N gate scripts executable" OR "⚠️ not executable: `chmod +x `, `chmod +x `" OR "skipped (vendored mode)" | diff --git a/commands/end-session.md b/commands/end-session.md index c5d06ef..a04d8d7 100644 --- a/commands/end-session.md +++ b/commands/end-session.md @@ -47,16 +47,16 @@ bash "${CLAUDE_PLUGIN_ROOT}/hooks/lib/perf-log.sh" record --source=command --nam If `git status --porcelain` is empty AND `` equals `HEAD` (no commits have landed since the primer was last touched), skip the -rest of Step 1 entirely — no drift check, no outstanding-items verification, +rest of Step 1 entirely — no drift check, no backlog verification, no git-log recomputation. Nothing in the repo has changed since the last close-out, so no per-item re-check could turn up anything new. Step 3's Primer refresh row reads ✓ "Primer already current (no-op)"; the -Outstanding-items row reads ✓ "N tracked — not re-verified this session (no +Backlog row reads ✓ "N tracked — not re-verified this session (no repo changes since last close-out)". Skip straight to Step 2. Otherwise — something changed — proceed with the checks below. -### Outstanding-items verification (gated by commit-subject overlap) +### Backlog verification (gated by commit-subject overlap) Verify the primer's outstanding items against actual repo state. Runs whenever the fast path above didn't fire. Compute each verdict once here; @@ -68,29 +68,29 @@ from the fast-path check above). This same list feeds both this section's overlap gate below and the Refresh flow's overlay further down — compute it here, don't recompute it there. -**Data source.** Read `.session-continuity/OUTSTANDING_ITEMS.md`, not a +**Data source.** Read `.session-continuity/BACKLOG.md`, not a heading inside the primer — the backlog lives in its own file now. **Skip conditions.** -- If `.session-continuity/OUTSTANDING_ITEMS.md` doesn't exist AND the +- If `.session-continuity/BACKLOG.md` doesn't exist AND the primer has no leftover inline outstanding-items heading from before the split either: skip verification silently (fresh/already-flat project). - Step 3's row reads `Outstanding items: none tracked`. -- If `.session-continuity/OUTSTANDING_ITEMS.md` doesn't exist BUT the + Step 3's row reads `Backlog: none tracked`. +- If `.session-continuity/BACKLOG.md` doesn't exist BUT the primer still has the inline heading: this is an unmigrated project. - Skip only the outstanding-items verification sub-flow (this whole + Skip only the backlog verification sub-flow (this whole section) — everything else in Step 1 (fast path, drift check, git-log regeneration, test-count rerun) proceeds normally, independent of this - condition. Tell the user once: "This project's outstanding items - haven't migrated to `.session-continuity/OUTSTANDING_ITEMS.md` yet — + condition. Tell the user once: "This project's backlog hasn't + migrated to `.session-continuity/BACKLOG.md` yet — run `/session-continuity:primer` first (it migrates automatically), then re-run `/session-continuity:end-session`." Step 3's row reads - `Outstanding items: not migrated — run /session-continuity:primer`. -- If `.session-continuity/OUTSTANDING_ITEMS.md` exists but is empty + `Backlog: not migrated — run /session-continuity:primer`. +- If `.session-continuity/BACKLOG.md` exists but is empty (no `### N.` entries): skip verification, Step 3's row reads `none tracked`, same as the fresh-project case. -**For each `### N.` entry** in `.session-continuity/OUTSTANDING_ITEMS.md` +**For each `### N.` entry** in `.session-continuity/BACKLOG.md` (scope the item exactly as the overlay does: the heading line plus every line until the next `### N.` heading or end of file; sub-bullets roll up to their parent): @@ -155,7 +155,7 @@ gate the plugin enforces on "proven" claims elsewhere. auto-removed**. - **When the drift check below enters the refresh flow** (drift detected): - append every `appears-DONE` item to the existing outstanding-items overlay + append every `appears-DONE` item to the existing backlog overlay candidate list, so it surfaces at Step 1's single combined prompt. One reply closes it. Cite the evidence beside the candidate. - **When the primer is drift-clean** (refresh flow skipped): if at least one @@ -171,7 +171,7 @@ mutates the primer on its own. Read `.session-continuity/SESSION_PRIMER.md` and compare its `git log --oneline -5` block to the actual output of `git log --oneline -5` against the primary branch. Two outcomes: -- **Block matches.** Treat the primer as current — no git-log regeneration, no test-count re-check, no refresh flow. Then check the Outstanding-items verification results computed above: +- **Block matches.** Treat the primer as current — no git-log regeneration, no test-count re-check, no refresh flow. Then check the Backlog verification results computed above: - **Zero `appears-DONE` items.** Skip the rest of Step 1. In Step 3's checklist, record the Primer refresh row as ✓ "Primer already current (no-op)". - **≥1 `appears-DONE` item.** Run the drift-clean close-candidate prompt below instead of skipping Step 1. - **Block differs** (any line differs — subjects, hashes, or ordering). Enter the refresh flow below. @@ -220,7 +220,7 @@ A lighter-weight alternative to the refresh flow below — no git-log regenerati Then ask a close-only question, scoped narrower than the refresh flow's combined prompt since there are no commit subjects or free-form drift to fold in: - > "Outstanding items — N appears-DONE (see list). Close any, or leave as-is?" + > "Backlog — N appears-DONE (see list). Close any, or leave as-is?" 3. **Wait for the answer before continuing.** Same refusal rule as the refresh flow: never close an item without explicit confirmation. Once the answer arrives, log the wait duration: ```bash @@ -237,8 +237,8 @@ A lighter-weight alternative to the refresh flow below — no git-log regenerati bash "${CLAUDE_PLUGIN_ROOT}/hooks/lib/perf-log.sh" record --source=command --name=end-session --step=step-1-prompt-wait --duration="$(( now_epoch - prior_epoch )).000" fi ``` -4. If the user closes any items, edit only `.session-continuity/OUTSTANDING_ITEMS.md` (the drift check already confirmed the primer's `git log --oneline -5` block is current and untouched, so the primer itself needs no edit here) and stage that file: `git diff --quiet .session-continuity/OUTSTANDING_ITEMS.md 2>/dev/null || git add .session-continuity/OUTSTANDING_ITEMS.md`. Step 3's Primer refresh row reads ✓ "Primer updated (outstanding item(s) closed)". -5. If the user declines, skip the rest of Step 1. Step 3's Primer refresh row reads ✓ "Primer already current (no-op)", and the still-open `appears-DONE` item(s) surface again as a ⚠️ in the Outstanding items row (same standing-reminder behavior as before — it'll be offered again next session). +4. If the user closes any items, edit only `.session-continuity/BACKLOG.md` (the drift check already confirmed the primer's `git log --oneline -5` block is current and untouched, so the primer itself needs no edit here) and stage that file: `git diff --quiet .session-continuity/BACKLOG.md 2>/dev/null || git add .session-continuity/BACKLOG.md`. Step 3's Primer refresh row reads ✓ "Primer updated (outstanding item(s) closed)". +5. If the user declines, skip the rest of Step 1. Step 3's Primer refresh row reads ✓ "Primer already current (no-op)", and the still-open `appears-DONE` item(s) surface again as a ⚠️ in the Backlog row (same standing-reminder behavior as before — it'll be offered again next session). ### Refresh flow (runs only when drift was detected) @@ -246,12 +246,12 @@ Follow the logic in **Step 5 of `commands/primer.md`** (refresh mode): 1. Regenerate the `git log --oneline -5` block with current output. 2. If the primer has a test-counts section and the counts changed (after the 3× retry), update them to match current output. -3. **Surface commits since the last primer refresh, with outstanding-items overlay.** Reuse the commit list already computed in the Outstanding-items verification section above (`git log ..HEAD --oneline`) — do not recompute it. Present the subject list as candidate prompts. +3. **Surface commits since the last primer refresh, with backlog overlay.** Reuse the commit list already computed in the Backlog verification section above (`git log ..HEAD --oneline`) — do not recompute it. Present the subject list as candidate prompts. - Then compute an **outstanding-items overlay** for each subject: + Then compute a **backlog overlay** for each subject: - Tokenize the subject: lowercase, split on non-alphanumeric, drop tokens of length <3, drop the stopword list below. - - For each `### N.` entry in `.session-continuity/OUTSTANDING_ITEMS.md`: tokenize the item text the same way, capped at the first 200 characters of the item (the heading line through everything up to the next `### N.` heading or end of file; sub-bullets roll up to their parent item). + - For each `### N.` entry in `.session-continuity/BACKLOG.md`: tokenize the item text the same way, capped at the first 200 characters of the item (the heading line through everything up to the next `### N.` heading or end of file; sub-bullets roll up to their parent item). - Match if the intersection of subject tokens and item tokens has cardinality ≥ 3. **Stopwords** (extend per project as needed): @@ -262,7 +262,7 @@ Follow the logic in **Step 5 of `commands/primer.md`** (refresh mode): **Presentation.** Render the "May close outstanding items" block when EITHER token-overlap matches from commit subjects OR `appears-DONE` items from the - Outstanding-items verification sub-block above exist. **Render candidates as + Backlog verification sub-block above exist. **Render candidates as a markdown ordered list, one item per line, using the item's own primer number as the list ordinal** (e.g. `4. — `) so the numbering the user sees matches the numbering in the primer — never a @@ -276,7 +276,7 @@ Follow the logic in **Step 5 of `commands/primer.md`** (refresh mode): **Refusal.** Never close an outstanding item without explicit user confirmation. The overlay is a candidate list, not an auto-close. - **Skip conditions.** If `.session-continuity/OUTSTANDING_ITEMS.md` doesn't exist (unmigrated project, or the file was deleted), skip the overlay silently — the raw subject list still appears. + **Skip conditions.** If `.session-continuity/BACKLOG.md` doesn't exist (unmigrated project, or the file was deleted), skip the overlay silently — the raw subject list still appears. 4. **Single combined prompt.** After printing the subject list (and overlay block if any), log a prompt-shown marker (same mechanism as the drift-clean prompt above — isolates human-response wait from ritual compute time, see Step 4): ```bash @@ -285,7 +285,7 @@ Follow the logic in **Step 5 of `commands/primer.md`** (refresh mode): Then ask the user one question covering both close-candidates and free-form edits: - > "Outstanding items — close any from the overlay, add new follow-ups, or no changes?" + > "Backlog — close any from the overlay, add new follow-ups, or no changes?" **Wait for the answer before continuing.** Do not preemptively edit the list, clear items you interpret as "stale," or proceed based on your own reading. Do not split this into two sequential prompts — one prompt covers the same answer space. Once the answer arrives, log the wait duration: @@ -304,14 +304,14 @@ Follow the logic in **Step 5 of `commands/primer.md`** (refresh mode): fi ``` 5. Apply the edits the user specified. If the user replied "no changes" (or similar), skip this step. -6. Stage the updated primer and `OUTSTANDING_ITEMS.md` (if the user closed or +6. Stage the updated primer and `BACKLOG.md` (if the user closed or edited any items in step 5 above), and `PROJECT_CONTEXT.md` too if it has unstaged changes (e.g. the session edited repo layout / conventions): ```bash git add .session-continuity/SESSION_PRIMER.md git diff --quiet .session-continuity/PROJECT_CONTEXT.md 2>/dev/null || git add .session-continuity/PROJECT_CONTEXT.md - git diff --quiet .session-continuity/OUTSTANDING_ITEMS.md 2>/dev/null || git add .session-continuity/OUTSTANDING_ITEMS.md + git diff --quiet .session-continuity/BACKLOG.md 2>/dev/null || git add .session-continuity/BACKLOG.md ``` **Do not** commit. Staging only. @@ -674,8 +674,8 @@ _PERF_DURATION=$(awk -v a="$_PERF_START" -v b="$_PERF_END" 'BEGIN{printf "%.3f", bash "${CLAUDE_PLUGIN_ROOT}/hooks/lib/perf-log.sh" record --source=command --name=end-session --step=step-3-gather-facts --duration="$_PERF_DURATION" ``` -- **Outstanding-items verdicts** — reuse the per-item verdicts from Step 1's - verification sub-block; re-read `.session-continuity/OUTSTANDING_ITEMS.md` to +- **Backlog verdicts** — reuse the per-item verdicts from Step 1's + verification sub-block; re-read `.session-continuity/BACKLOG.md` to get the post-edit item set. No new git command — the evidence was already gathered in Step 1. @@ -695,17 +695,17 @@ Output using this structure. Use ✓ (green), ⚠️ (yellow), or → (suggestio |---|---|---| | Primer refresh | ✓ | "Primer refreshed and staged" OR "Primer updated (outstanding item(s) closed)" OR "Primer already current (no-op)" | | New learnings | ✓ | "N LEARNINGS entry/entries captured (#X, \"\" …)" OR "No new learnings" | -| Outstanding items | checkmark if none stale, else warning | "N tracked — <k> appears-DONE (#X, evidence), <m> still-open (#…), <j> manual (#…)" OR "none tracked" | +| Backlog | checkmark if none stale, else warning | "N tracked — <k> appears-DONE (#X, evidence), <m> still-open (#…), <j> manual (#…)" OR "none tracked" | | Staged files | ✓ | "Staged: <file1>, <file2>, …" OR "Nothing staged" | | Unstaged modifications | ✓ if none, else ⚠️ | "No unstaged modifications" OR "⚠️ Unstaged: <file1>, <file2>, …" | | Untracked files | ✓ if none, else ⚠️ | "No untracked files" OR "⚠️ N untracked: <file1>, <file2>, … — ignore, add, or delete?" | | Unpushed commits | ✓ / ⚠️ | "Up to date with origin/<branch>" OR "⚠️ Branch <name> is N commits ahead of origin — push before closing?" OR the detached-HEAD / no-upstream variants | | Suggested commit | → | Derived from staged files + captured learnings. Omit row entirely if nothing is staged. | -**Outstanding-items row — re-derive, do not cache.** Step 3 re-reads -`.session-continuity/OUTSTANDING_ITEMS.md` AFTER any Step 1 closures the +**Backlog row — re-derive, do not cache.** Step 3 re-reads +`.session-continuity/BACKLOG.md` AFTER any Step 1 closures the user confirmed. The *set* of items and the counts are recomputed against the -post-edit `.session-continuity/OUTSTANDING_ITEMS.md`; only the per-item +post-edit `.session-continuity/BACKLOG.md`; only the per-item verdicts (`still-open` / `appears-DONE` / `manual`) computed in Step 1 are reused. If the user closed an item at the Step 1 prompt, it is gone from the file and absent from this row. Marker: ✓ if @@ -733,7 +733,7 @@ Prefix with `→ Suggested:` and wrap in a fenced code block so the user can cop ``` ✓ Primer refreshed and staged ✓ 1 LEARNINGS entry captured (#7, "awk range collapse on single-version CHANGELOG") -⚠️ Outstanding items: 5 tracked — 1 appears-DONE (#4, "add bats test harness": found test/end_to_end.bats → 0 hits before, now present), 1 still-open (#3), 3 manual (#1, #2, #5) +⚠️ Backlog: 5 tracked — 1 appears-DONE (#4, "add bats test harness": found test/end_to_end.bats → 0 hits before, now present), 1 still-open (#3), 3 manual (#1, #2, #5) ✓ Staged: .session-continuity/SESSION_PRIMER.md, .session-continuity/LEARNINGS.md, .github/workflows/release.yml ✓ No unstaged modifications ⚠️ 2 untracked files: scratch.md, tmp/debug.log — ignore, add, or delete? @@ -742,7 +742,7 @@ Prefix with `→ Suggested:` and wrap in a fenced code block so the user can cop git commit -m "fix(ci): extract CHANGELOG section with proper awk range" ``` -*(Illustrative only — the real Outstanding-items row reflects the current primer's actual item set and verdicts.)* +*(Illustrative only — the real Backlog row reflects the current primer's actual item set and verdicts.)* ## Step 4 — Terminal sign-off (always) @@ -822,7 +822,7 @@ fi - **Zero arguments.** If the user passed text after `/session-continuity:end-session`, ignore it — session reflection provides all context needed. - **Bound the prompt count.** The whole ritual must fit ≤2 user prompts in the common case: one Step 1 prompt (the full combined prompt when drift exists, or the lighter drift-clean close-candidate prompt when drift is clean but `appears-DONE` items exist), one batch confirm in Step 2 (only when candidates surface). Drift-clean + zero candidates = zero prompts; drift-clean + ≥1 candidate = exactly one (lightweight) prompt. Never split Step 1's prompt into two sequential asks. Never loop one-prompt-per-candidate in Step 2. - **Always sign off.** Step 4's terminal line is non-negotiable — the user invoked an explicit close-out and must not be left ambiguous about whether the ritual is done. -- **Outstanding-items verdicts never mutate the primer.** The verification in +- **Backlog verdicts never mutate the primer.** The verification in Step 1 only classifies and reports; an `appears-DONE` item is removed only if the user confirms it at a Step 1 prompt (full combined prompt or the drift-clean close-candidate prompt). Declining either prompt leaves the item diff --git a/commands/help.md b/commands/help.md new file mode 100644 index 0000000..0a7275d --- /dev/null +++ b/commands/help.md @@ -0,0 +1,70 @@ +--- +description: Explain what this plugin does, why, and what each `.session-continuity/` file is for. Zero args, read-only, no state mutation. +--- + +# /session-continuity:help + +You are responding to the `/session-continuity:help` slash command. + +**Your job: answer "what is this plugin and why should I care" directly, without sending the user to read `SKILL.md` end to end.** Read-only — never edits, stages, or commits anything. + +## Step 1 — Get the installed version + +```bash +grep -m1 '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || echo "version unknown (vendored install)" +``` + +## Step 2 — Report + +Print the following, substituting the parsed version into the first line. This is fixed reference text — do not re-derive it from `SKILL.md` per invocation, and do not omit any of the five files or any command. + +``` +session-continuity v<X.Y.Z> + +WHAT THIS IS +Cross-session memory for Claude Code projects, via five in-repo Markdown +docs. A fresh Claude session (or a fresh terminal, or tomorrow) starts +cold — these files are how it gets caught up without you re-explaining +the project. + +WHY +Claude doesn't remember yesterday's debugging, last week's refactor, or +the bug you spent three hours cornering. These files are a low-tech fix: +plain Markdown, committed to git alongside the code, readable by humans +and Claude alike. Every change is an auditable commit; no vendor-specific +storage, no opaque memory layer. + +THE FIVE FILES +- SESSION_PRIMER.md — volatile. Current state, latest commits. Refresh + alongside every substantive commit. +- PROJECT_CONTEXT.md — stable. Repo layout, conventions, module table. + Changes rarely — only when the project's shape + changes. +- BACKLOG.md — tactical. Explicitly deferred follow-ups and + decisions. Permanently numbered; closed items + are deleted, never renumbered. +- ROADMAP.md — strategic. Now/Next/Later direction. Freeform, + no numbering, rewritten wholesale as direction + changes. +- LEARNINGS.md — durable wisdom. Append-only, numbered. One entry + per bug that took 15+ minutes to diagnose. + +COMMANDS +``` + +Then list every `/session-continuity:*` command by reading each file's own frontmatter `description` field — do not hand-copy descriptions into this command file, since that duplicates a source of truth that will drift. Gather them in one Bash call: + +```bash +for f in "${CLAUDE_PLUGIN_ROOT}"/commands/*.md; do + name="$(basename "$f" .md)" + desc="$(grep -m1 '^description:' "$f" | sed -E 's/^description:[[:space:]]*//')" + echo "/session-continuity:$name — $desc" +done +``` + +Render each line under the `COMMANDS` heading above, one per command, in the order the `for` loop produced them. + +## Notes + +- **Never mutates anything.** No file writes, no `git add`, no `chmod` — matches `/session-continuity:doctor`'s same rule. +- **Never invent a command description.** If a command file has no `description:` frontmatter line, print `(no description found)` for that line rather than guessing. diff --git a/commands/primer.md b/commands/primer.md index 9eb967c..e43ec81 100644 --- a/commands/primer.md +++ b/commands/primer.md @@ -19,6 +19,8 @@ _PERF_START=$(date +%s.%N 2>/dev/null || echo "$SECONDS") [ -f .session-continuity/PROJECT_CONTEXT.md ] && echo "PROJECT_CONTEXT_EXISTS=1" || echo "PROJECT_CONTEXT_EXISTS=0" [ -f .session-continuity/OUTSTANDING_ITEMS.md ] && echo "OUTSTANDING_ITEMS_EXISTS=1" || echo "OUTSTANDING_ITEMS_EXISTS=0" grep -q '^## Outstanding items' .session-continuity/SESSION_PRIMER.md 2>/dev/null && echo "PRIMER_HAS_INLINE_OUTSTANDING=1" || echo "PRIMER_HAS_INLINE_OUTSTANDING=0" +[ -f .session-continuity/BACKLOG.md ] && echo "BACKLOG_EXISTS=1" || echo "BACKLOG_EXISTS=0" +[ -f .session-continuity/ROADMAP.md ] && echo "ROADMAP_EXISTS=1" || echo "ROADMAP_EXISTS=0" git log --oneline -5 git diff --cached --name-only _PERF_END=$(date +%s.%N 2>/dev/null || echo "$SECONDS") @@ -49,14 +51,23 @@ primer, as two sequential edits — not simultaneous partitioning. The two splits touch disjoint sections of the primer (stable-context headings vs. the Outstanding items heading), so sequencing avoids any edit conflict. +If `OUTSTANDING_ITEMS_EXISTS=1` AND `BACKLOG_EXISTS=0`, a file-rename +migration is needed — run it (Step 3c below) in addition to whichever of +the four states above applies. **Sequencing:** if Step 3b also fired this +run (inline heading present, no file yet), run Step 3b to completion +first — it still writes `OUTSTANDING_ITEMS.md` under the old name — then +run Step 3c against that result. Step 3c is strictly the one-level-up +file rename; it never inspects primer content. + ## Step 2 — Init mode 1. Create `.session-continuity/` if it doesn't exist. 2. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/SESSION_PRIMER.md` to `.session-continuity/SESSION_PRIMER.md`. 3. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/LEARNINGS.md` to `.session-continuity/LEARNINGS.md`. 4. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/PROJECT_CONTEXT.md` to `.session-continuity/PROJECT_CONTEXT.md`. -5. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/OUTSTANDING_ITEMS.md` to `.session-continuity/OUTSTANDING_ITEMS.md`. -6. Fill in placeholders Claude can derive automatically. Gather the raw +5. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/BACKLOG.md` to `.session-continuity/BACKLOG.md`. +6. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/ROADMAP.md` to `.session-continuity/ROADMAP.md`. +7. Fill in placeholders Claude can derive automatically. Gather the raw data in **one Bash call**, timed: ```bash @@ -98,22 +109,22 @@ the Outstanding items heading), so sequencing avoids any edit conflict. - `{{TEST_COMMAND_SUMMARY}}` — if `TEST_RUN_EXIT=0` and the captured output contains a recognizable count (`N pass`, `N passed`, `test result: ok. N passed`, etc.), seed this as "`<TEST_CMD>` — N pass / M fail" from that single run. If `TEST_CMD` was empty, the run timed out (`TEST_RUN_EXIT=124`), or the output has no parseable count, fall back to the bare `scripts.test` string (or `TBD`) — never invent a count. - `{{REPO_LAYOUT_SUMMARY}}` — from the `find` output above, plus a one-line description Claude infers from the file extensions present. - `{{MODULES_TABLE}}` — if the `@module` grep above found matches, build one table row per file: Component = file path, Purpose = the `@module` value (plus the docblock's one-line description if present), Notes = the adjacent `Exports:` line if present. If it found nothing, leave `TBD` as before — don't invent structure that isn't there. - - `{{WORKFLOW_CONVENTIONS}} (draft)` — if `CLAUDE.md` exists (cat output above), draft this field by quoting its relevant conventions (runtime choice, commit style, workflow/never-do rules) under a "Conventions inherited from CLAUDE.md" sub-heading, instead of leaving it blank for the user to retype. Present the draft in Step 7 for confirmation rather than asking cold. -7. Ask the user for the blanks that can't be derived: `{{GROUND_RULES}}`, `{{WHERE_TO_LOOK_ROWS}}`, `{{STUCK_ESCALATION_STEPS}}`, `{{OUTSTANDING_ITEMS}}`, and `{{WORKFLOW_CONVENTIONS}}` only if no `CLAUDE.md` draft was produced above. If a draft was produced, show it and ask the user to confirm or amend it rather than asking a blank question. **Wait for their answer.** Do not proceed to Step 9 until the user responds. + - `{{WORKFLOW_CONVENTIONS}} (draft)` — if `CLAUDE.md` exists (cat output above), draft this field by quoting its relevant conventions (runtime choice, commit style, workflow/never-do rules) under a "Conventions inherited from CLAUDE.md" sub-heading, instead of leaving it blank for the user to retype. Present the draft in Step 8 for confirmation rather than asking cold. +8. Ask the user for the blanks that can't be derived: `{{GROUND_RULES}}`, `{{WHERE_TO_LOOK_ROWS}}`, `{{STUCK_ESCALATION_STEPS}}`, `{{BACKLOG}}`, and `{{WORKFLOW_CONVENTIONS}}` only if no `CLAUDE.md` draft was produced above. If a draft was produced, show it and ask the user to confirm or amend it rather than asking a blank question. **Wait for their answer.** Do not proceed to Step 10 until the user responds. - **Outstanding-items conversion rule.** The user's answer for - `{{OUTSTANDING_ITEMS}}` is free-form prose — a list, a paragraph, however + **Backlog conversion rule.** The user's answer for + `{{BACKLOG}}` is free-form prose — a list, a paragraph, however they typed it. Convert it into one `### N.` entry per distinct item in - `.session-continuity/OUTSTANDING_ITEMS.md`, numbered sequentially + `.session-continuity/BACKLOG.md`, numbered sequentially starting at 1, trimming each to a title plus 1-3 sentences (the same length cap every item in that file follows). Never paste the raw answer in as a single unstructured blob. If the user said "none" or skipped the - question, leave the file's `{{OUTSTANDING_ITEMS}}` placeholder area empty + question, leave the file's `{{BACKLOG}}` placeholder area empty (substituted per the existing placeholder-cleanup step below, same as any other skipped field). -8. **Replace any remaining `{{PLACEHOLDER}}` tokens with `TBD` before staging.** If the user skipped a field, declined to answer, or asked you to stage/commit without filling everything in, substitute `TBD` (with an empty body line where the template had prose). Never leave `{{...}}` syntax in a file you are about to stage — `grep -n '{{' .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/OUTSTANDING_ITEMS.md` must return nothing after this step. -9. Stage all four files: `git add .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/OUTSTANDING_ITEMS.md`. -10. Tell the user: "Primer, PROJECT_CONTEXT, OUTSTANDING_ITEMS, and LEARNINGS staged. Review and commit with `git commit -m 'docs: initialize session continuity'` when ready." Include a one-line note listing any fields that were set to `TBD` so the user knows what to fill in later. +9. **Replace any remaining `{{PLACEHOLDER}}` tokens with `TBD` before staging.** If the user skipped a field, declined to answer, or asked you to stage/commit without filling everything in, substitute `TBD` (with an empty body line where the template had prose). Never leave `{{...}}` syntax in a file you are about to stage — `grep -n '{{' .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md` must return nothing after this step. +10. Stage all five files: `git add .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md`. +11. Tell the user: "Primer, PROJECT_CONTEXT, BACKLOG, ROADMAP, and LEARNINGS staged. Review and commit with `git commit -m 'docs: initialize session continuity'` when ready." Include a one-line note listing any fields that were set to `TBD` so the user knows what to fill in later. **Do not commit automatically.** The user commits when ready. @@ -193,6 +204,47 @@ they currently have, and those become the first permanent IDs. **Do not commit automatically.** Staging only, same as every other split. +## Step 3c — Backlog rename migration + +Runs whenever `BACKLOG_EXISTS=0` AND `OUTSTANDING_ITEMS_EXISTS=1` (see +Step 1). This is strictly the `OUTSTANDING_ITEMS.md` → `BACKLOG.md` +rename, one level up from Step 3b (which may have just created +`OUTSTANDING_ITEMS.md` under its old name this same run — Step 3c runs +after it, per the sequencing note in Step 1). + +1. `git mv .session-continuity/OUTSTANDING_ITEMS.md .session-continuity/BACKLOG.md`. +2. Rewrite the moved file's first heading line from `# Outstanding Items + — <project>` to `# Backlog — <project>`. Also rewrite line 3 (after + the blank line 2) — the body's opening sentence, currently starting + "Backlog of explicitly deferred follow-ups..." — to "Explicitly + deferred follow-ups..." (drop the leading "Backlog of"), so the file + doesn't read "# Backlog" immediately followed by "Backlog of..." + (same redundancy Task 1 avoids in the fresh-install template). + Content and item numbers are otherwise untouched. +3. Grep `.session-continuity/SESSION_PRIMER.md` for any remaining literal + reference to `OUTSTANDING_ITEMS.md` (a leftover pointer sentence from + before Step 3b/3c ran) and rewrite each to `BACKLOG.md`. +4. If `.session-continuity/ROADMAP.md` doesn't exist, create it from + `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/ROADMAP.md` + with `{{PROJECT_NAME}}` filled from the primer's own project name and + `{{ROADMAP_NOW}}`/`{{ROADMAP_NEXT}}`/`{{ROADMAP_LATER}}` all set to + `TBD` — no interactive prompt. Bundled into this same step so the + rename and the stub land as one migration event/commit, not two. +5. Stage the touched/new files: + `git add .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md` + and, only if Step 3 above actually changed it, + `git add .session-continuity/SESSION_PRIMER.md`. +6. Tell the user: "Migrated `.session-continuity/OUTSTANDING_ITEMS.md` → + `BACKLOG.md` (N items, numbers preserved) and stubbed in + `.session-continuity/ROADMAP.md`. Both staged — review before + committing." +7. Fall through to whichever of refresh mode (Step 4) or check mode + (Step 5) applies against the now-migrated primer, same fall-through + convention as Steps 3 and 3b. + +**Do not commit automatically.** Staging only — same rule as every other +split/migration step in this command. + ## Step 4 — Refresh mode 1. Read the current `.session-continuity/SESSION_PRIMER.md`. @@ -235,7 +287,7 @@ they currently have, and those become the first permanent IDs. bash "${CLAUDE_PLUGIN_ROOT}/hooks/lib/perf-log.sh" record --source=command --name=primer --step=step-4-activity-surface --duration="$_PERF_DURATION" ``` - Read `.session-continuity/OUTSTANDING_ITEMS.md` for the current item + Read `.session-continuity/BACKLOG.md` for the current item list (not the primer — the backlog lives in the dedicated file now). Present the subject list from the `git log` output above to the user as candidate prompts: @@ -245,8 +297,8 @@ they currently have, and those become the first permanent IDs. > > Any of these resolve outstanding items, or warrant a new LEARNINGS entry?" This is a candidate list, not an auto-close. Do not modify outstanding items based on subject heuristics — wait for the user's answer. -5. Ask the user: "Outstanding items — anything to remove (finished) or add (new follow-ups flagged)?" -6. Apply the edits to `.session-continuity/OUTSTANDING_ITEMS.md` (not the +5. Ask the user: "Backlog — anything to remove (finished) or add (new follow-ups flagged)?" +6. Apply the edits to `.session-continuity/BACKLOG.md` (not the primer). **Before removing any item as DONE, verify it against the actual code** — one grep or read per load-bearing claim, even if the user confirms it from memory or a commit subject matched the item's @@ -256,12 +308,12 @@ they currently have, and those become the first permanent IDs. one the candidate list surfaced. **Before deleting a closed item, grep the whole repo for references to its number** (e.g. `\bitem #?N\b`) — a hit means fix the referencing text first, per the numbering rule in - `.session-continuity/OUTSTANDING_ITEMS.md`'s own intro block. New + `.session-continuity/BACKLOG.md`'s own intro block. New items take the next unused number across the whole file, never a reused or renumbered one. 7. Stage the updated primer and, if outstanding items changed, the items file too: `git add .session-continuity/SESSION_PRIMER.md` and (only - when Step 6 touched it) `git add .session-continuity/OUTSTANDING_ITEMS.md`. + when Step 6 touched it) `git add .session-continuity/BACKLOG.md`. 8. Tell the user: "Primer refreshed and staged. Include it in your next commit (same commit as the substantive change — do not primer-commit alone)." ## Step 5 — Check mode @@ -272,7 +324,7 @@ Gather the report data in **one Bash call**, timed: _PERF_START=$(date +%s.%N 2>/dev/null || echo "$SECONDS") git rev-parse --short HEAD stat -f '%Sm' .session-continuity/SESSION_PRIMER.md 2>/dev/null || stat -c '%y' .session-continuity/SESSION_PRIMER.md -grep -cE '^### [0-9]+\.' .session-continuity/OUTSTANDING_ITEMS.md 2>/dev/null || echo 0 +grep -cE '^### [0-9]+\.' .session-continuity/BACKLOG.md 2>/dev/null || echo 0 grep -c '^### [0-9]\+\.' .session-continuity/LEARNINGS.md 2>/dev/null || echo 0 _PERF_END=$(date +%s.%N 2>/dev/null || echo "$SECONDS") _PERF_DURATION=$(awk -v a="$_PERF_START" -v b="$_PERF_END" 'BEGIN{printf "%.3f", b-a}' 2>/dev/null || echo "$(( _PERF_END - _PERF_START ))") @@ -284,7 +336,7 @@ Report: ``` .session-continuity/SESSION_PRIMER.md: up to date against HEAD (<short-sha>) Last refresh: <primer mtime> -Outstanding items: <count from OUTSTANDING_ITEMS.md> +Backlog: <count from BACKLOG.md> Learnings: <count from .session-continuity/LEARNINGS.md> ``` diff --git a/hooks/session-start.sh b/hooks/session-start.sh index e5d92ed..5449164 100755 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -64,26 +64,30 @@ status_sha="$(cd "$cwd" 2>/dev/null && git rev-parse --short HEAD 2>/dev/null || status_mtime="$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$cwd/$primer_path" 2>/dev/null \ || stat -c '%y' "$cwd/$primer_path" 2>/dev/null \ || echo '?')" -outstanding_path="$cwd/.session-continuity/OUTSTANDING_ITEMS.md" +outstanding_path="$cwd/.session-continuity/BACKLOG.md" status_learnings="$(grep -cE '^### [0-9]+\.' "$cwd/$learnings_path" 2>/dev/null || true)" status_learnings="${status_learnings:-0}" # Migration check: an old-format project has the inline heading in the -# primer but no OUTSTANDING_ITEMS.md yet. Only one project consumes this -# plugin today, so we push migration instead of tolerating both formats — -# no awk range-scan against the primer survives this change. +# primer but no BACKLOG.md yet, OR has OUTSTANDING_ITEMS.md under its old +# name. Only one project consumes this plugin today, so we push migration +# instead of tolerating multiple formats — no awk range-scan against the +# primer survives this change. if [ -f "$outstanding_path" ]; then status_outstanding="$(grep -cE '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" status_outstanding="${status_outstanding:-0}" outstanding_items="$(grep -E '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" if [ -n "$outstanding_items" ]; then - outstanding_block=$'\nOutstanding items:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' + outstanding_block=$'\nBacklog:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' else outstanding_block="" fi elif grep -q '^## Outstanding items' "$cwd/$primer_path" 2>/dev/null; then status_outstanding="?" - outstanding_block=$'\n⚠️ Outstanding items haven\'t migrated to .session-continuity/OUTSTANDING_ITEMS.md yet — run /session-continuity:primer now to migrate before continuing.\n' + outstanding_block=$'\n⚠️ Outstanding items haven\'t migrated to .session-continuity/BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' +elif [ -f "$cwd/.session-continuity/OUTSTANDING_ITEMS.md" ]; then + status_outstanding="?" + outstanding_block=$'\n⚠️ .session-continuity/OUTSTANDING_ITEMS.md hasn\'t migrated to BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' else status_outstanding="0" outstanding_block="" @@ -99,7 +103,7 @@ This project has $primer_path. Read it before any work — it's the fastest path Primer status (auto): - HEAD: $status_sha - Last primer change: $status_mtime -- Outstanding items: $status_outstanding +- Backlog: $status_outstanding - Learnings: $status_learnings ${outstanding_block}</system-reminder> EOF diff --git a/meta/superpowers/plans/2026-08-31-backlog-roadmap-help.md b/meta/superpowers/plans/2026-08-31-backlog-roadmap-help.md new file mode 100644 index 0000000..41423bb --- /dev/null +++ b/meta/superpowers/plans/2026-08-31-backlog-roadmap-help.md @@ -0,0 +1,1411 @@ +# BACKLOG/ROADMAP rename + /session-continuity:help Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rename `.session-continuity/OUTSTANDING_ITEMS.md` to `BACKLOG.md` everywhere in this plugin, add a new `ROADMAP.md` stub file, add a `/session-continuity:help` command, and migrate existing installs (including this repo) automatically. + +**Architecture:** No code, no runtime — this plugin is Markdown command/skill instructions plus two Bash hook scripts. Every task is either (a) a literal-string rename across prompt/doc files, (b) a new template/command file, or (c) new dispatch logic inside `commands/primer.md` and `hooks/session-start.sh`. There is no compiler and no test runner; "tests" in this plan are `grep`/`diff` invariant checks run by hand after each edit. + +**Tech Stack:** Bash (hook scripts), Markdown (commands/skill/templates), git. + +**Spec:** `meta/superpowers/specs/2026-08-31-backlog-roadmap-help-design.md` + +## Global Constraints + +- No automated test harness exists in this repo (confirmed: no `*.bats`, no `test/` dir). Every task's verification step is a `grep`/`diff` check run via Bash, not a test-runner invocation. +- Never commit automatically inside any command's own logic (`primer.md`, `doctor.md`, `end-session.md`) — staging only. This plan's own git commits (one per task, made by the implementer) are a different thing and are expected. +- Every `OUTSTANDING_ITEMS.md` / `OUTSTANDING_ITEMS` / "Outstanding items" / "Outstanding Items" string that refers to the **live, current** file or its heading gets renamed to `BACKLOG.md` / `BACKLOG` / "Backlog". Strings inside `CHANGELOG.md` describing **already-shipped past versions**, and one historical narrative bullet inside this repo's own `.session-continuity/SESSION_PRIMER.md` (identified in Task 13), are **not** rewritten — they describe what was true at the time and stay as history. +- Branch: work happens on `feature/backlog-roadmap-help` (already created, spec already committed there as `06247c2`/`2928c65`). +- Version: bump `.claude-plugin/plugin.json` `version` from `0.21.1` to `0.22.0` in Task 11. + +--- + +### Task 1: Rename template `OUTSTANDING_ITEMS.md` → `BACKLOG.md` + +**Files:** +- Create: `skills/session-continuity/templates/BACKLOG.md` +- Delete: `skills/session-continuity/templates/OUTSTANDING_ITEMS.md` + +**Interfaces:** +- Produces: the placeholder token `{{BACKLOG}}` (renamed from `{{OUTSTANDING_ITEMS}}`), which Task 5 (`primer.md` Step 2/7/8) must reference by this exact name. + +- [ ] **Step 1: git mv and edit content** + +```bash +git mv skills/session-continuity/templates/OUTSTANDING_ITEMS.md skills/session-continuity/templates/BACKLOG.md +``` + +Then edit the moved file's first two lines from: + +```markdown +# Outstanding Items — {{PROJECT_NAME}} + +Backlog of explicitly deferred follow-ups and decisions — not bugs (those +``` + +to: + +```markdown +# Backlog — {{PROJECT_NAME}} + +Explicitly deferred follow-ups and decisions — not bugs (those +``` + +And the placeholder line (currently `{{OUTSTANDING_ITEMS}}` on its own line, near the bottom, just above the `<!-- Example:` block) to `{{BACKLOG}}`. + +- [ ] **Step 2: Verify no old name remains in the new file, placeholder renamed** + +```bash +grep -c "OUTSTANDING_ITEMS" skills/session-continuity/templates/BACKLOG.md +``` + +Expected: command exits non-zero / prints nothing matching (grep with no matches on `-c` prints `0`) — confirm output is exactly `0`. + +```bash +grep -c "{{BACKLOG}}" skills/session-continuity/templates/BACKLOG.md +``` + +Expected: `1`. + +- [ ] **Step 3: Commit** + +```bash +git add skills/session-continuity/templates/BACKLOG.md +git commit -m "feat: rename OUTSTANDING_ITEMS.md template to BACKLOG.md" +``` + +--- + +### Task 2: New template `ROADMAP.md` + +**Files:** +- Create: `skills/session-continuity/templates/ROADMAP.md` + +**Interfaces:** +- Produces: placeholders `{{ROADMAP_NOW}}`, `{{ROADMAP_NEXT}}`, `{{ROADMAP_LATER}}`, which Task 5 (`primer.md` Step 2 and Step 3c) fill with `TBD` when not user-supplied. + +- [ ] **Step 1: Write the template** + +```markdown +# Roadmap — {{PROJECT_NAME}} + +Strategic direction — where this project is headed, not the tactical +queue (that's `.session-continuity/BACKLOG.md`). Freeform: no numbering, +no permanence rules, no length cap. Rewrite sections wholesale as +direction changes; this file's history lives in git, not in careful +edits. + +## Now + +{{ROADMAP_NOW}} + +## Next + +{{ROADMAP_NEXT}} + +## Later + +{{ROADMAP_LATER}} +``` + +- [ ] **Step 2: Verify placeholders present** + +```bash +grep -Ec '\{\{ROADMAP_NOW\}\}|\{\{ROADMAP_NEXT\}\}|\{\{ROADMAP_LATER\}\}' skills/session-continuity/templates/ROADMAP.md +``` + +Expected: `3`. + +- [ ] **Step 3: Commit** + +```bash +git add skills/session-continuity/templates/ROADMAP.md +git commit -m "feat: add ROADMAP.md template" +``` + +--- + +### Task 3: New command `/session-continuity:help` + +**Files:** +- Create: `commands/help.md` + +**Interfaces:** +- Consumes: nothing from earlier tasks (this task can run independently of 1/2, though it references BACKLOG/ROADMAP by name in its static prose). +- Produces: nothing other tasks depend on — this is a leaf. + +- [ ] **Step 1: Write the command file** + +The whole block below (through the closing ` ```` ` at the end of this step) is the entire, literal content of `commands/help.md` — write it as one file. It uses a 4-backtick outer fence here only because the file's own content contains 3-backtick code fences; do not include the outer 4-backtick markers in the actual file. + +```` markdown +--- +description: Explain what this plugin does, why, and what each `.session-continuity/` file is for. Zero args, read-only, no state mutation. +--- + +# /session-continuity:help + +You are responding to the `/session-continuity:help` slash command. + +**Your job: answer "what is this plugin and why should I care" directly, without sending the user to read `SKILL.md` end to end.** Read-only — never edits, stages, or commits anything. + +## Step 1 — Get the installed version + +```bash +grep -m1 '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || echo "version unknown (vendored install)" +``` + +## Step 2 — Report + +Print the following, substituting the parsed version into the first line. This is fixed reference text — do not re-derive it from `SKILL.md` per invocation, and do not omit any of the five files or any command. + +``` +session-continuity v<X.Y.Z> + +WHAT THIS IS +Cross-session memory for Claude Code projects, via five in-repo Markdown +docs. A fresh Claude session (or a fresh terminal, or tomorrow) starts +cold — these files are how it gets caught up without you re-explaining +the project. + +WHY +Claude doesn't remember yesterday's debugging, last week's refactor, or +the bug you spent three hours cornering. These files are a low-tech fix: +plain Markdown, committed to git alongside the code, readable by humans +and Claude alike. Every change is an auditable commit; no vendor-specific +storage, no opaque memory layer. + +THE FIVE FILES +- SESSION_PRIMER.md — volatile. Current state, latest commits. Refresh + alongside every substantive commit. +- PROJECT_CONTEXT.md — stable. Repo layout, conventions, module table. + Changes rarely — only when the project's shape + changes. +- BACKLOG.md — tactical. Explicitly deferred follow-ups and + decisions. Permanently numbered; closed items + are deleted, never renumbered. +- ROADMAP.md — strategic. Now/Next/Later direction. Freeform, + no numbering, rewritten wholesale as direction + changes. +- LEARNINGS.md — durable wisdom. Append-only, numbered. One entry + per bug that took 15+ minutes to diagnose. + +COMMANDS +``` + +Then list every `/session-continuity:*` command by reading each file's own frontmatter `description` field — do not hand-copy descriptions into this command file, since that duplicates a source of truth that will drift. Gather them in one Bash call: + +```bash +for f in "${CLAUDE_PLUGIN_ROOT}"/commands/*.md; do + name="$(basename "$f" .md)" + desc="$(grep -m1 '^description:' "$f" | sed -E 's/^description:[[:space:]]*//')" + echo "/session-continuity:$name — $desc" +done +``` + +Render each line under the `COMMANDS` heading above, one per command, in the order the `for` loop produced them. + +## Notes + +- **Never mutates anything.** No file writes, no `git add`, no `chmod` — matches `/session-continuity:doctor`'s same rule. +- **Never invent a command description.** If a command file has no `description:` frontmatter line, print `(no description found)` for that line rather than guessing. +```` + +- [ ] **Step 2: Verify frontmatter is well-formed** + +```bash +head -5 commands/help.md +``` + +Expected: starts with `---`, has a `description:` line, closes with `---` before the `# /session-continuity:help` heading — same shape as `commands/doctor.md`. + +- [ ] **Step 3: Commit** + +```bash +git add commands/help.md +git commit -m "feat: add /session-continuity:help command" +``` + +--- + +### Task 4: `hooks/session-start.sh` — rename + migration-nudge branch + +**Files:** +- Modify: `hooks/session-start.sh` + +**Interfaces:** +- Consumes: nothing from earlier tasks (this is the runtime hook; it doesn't read the templates). +- Produces: the reminder text convention ("Backlog:" line) that Task 8 (SKILL.md) and Task 12 (README.md) describe in prose. + +- [ ] **Step 1: Rename the path variable and reminder label** + +Change: +```bash +outstanding_path="$cwd/.session-continuity/OUTSTANDING_ITEMS.md" +``` +to: +```bash +outstanding_path="$cwd/.session-continuity/BACKLOG.md" +``` + +Change the comment above it: +```bash +# Migration check: an old-format project has the inline heading in the +# primer but no OUTSTANDING_ITEMS.md yet. Only one project consumes this +# plugin today, so we push migration instead of tolerating both formats — +# no awk range-scan against the primer survives this change. +``` +to: +```bash +# Migration check: an old-format project has the inline heading in the +# primer but no BACKLOG.md yet, OR has OUTSTANDING_ITEMS.md under its old +# name. Only one project consumes this plugin today, so we push migration +# instead of tolerating multiple formats — no awk range-scan against the +# primer survives this change. +``` + +Change the reminder text: +```bash + outstanding_block=$'\nOutstanding items:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' +``` +to: +```bash + outstanding_block=$'\nBacklog:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' +``` + +And the final status line: +```bash +- Outstanding items: $status_outstanding +``` +to: +```bash +- Backlog: $status_outstanding +``` + +- [ ] **Step 2: Add the new elif branch for the OUTSTANDING_ITEMS.md → BACKLOG.md migration** + +Current chain (after Step 1's rename, `outstanding_path` now points at `BACKLOG.md`): +```bash +if [ -f "$outstanding_path" ]; then + status_outstanding="$(grep -cE '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" + status_outstanding="${status_outstanding:-0}" + outstanding_items="$(grep -E '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" + if [ -n "$outstanding_items" ]; then + outstanding_block=$'\nBacklog:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' + else + outstanding_block="" + fi +elif grep -q '^## Outstanding items' "$cwd/$primer_path" 2>/dev/null; then + status_outstanding="?" + outstanding_block=$'\n⚠️ Outstanding items haven\'t migrated to .session-continuity/BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' +else + status_outstanding="0" + outstanding_block="" +fi +``` + +Insert a new branch between the `elif grep -q '^## Outstanding items'` branch and the final `else`, so a project with the old `OUTSTANDING_ITEMS.md` file (but no `BACKLOG.md` yet) also gets a nudge instead of silently reporting zero: + +```bash +elif [ -f "$cwd/.session-continuity/OUTSTANDING_ITEMS.md" ]; then + status_outstanding="?" + outstanding_block=$'\n⚠️ .session-continuity/OUTSTANDING_ITEMS.md hasn\'t migrated to BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' +``` + +Full resulting chain (for reference — the `if`/two-`elif`/`else` shape): +```bash +if [ -f "$outstanding_path" ]; then + status_outstanding="$(grep -cE '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" + status_outstanding="${status_outstanding:-0}" + outstanding_items="$(grep -E '^### [0-9]+\.' "$outstanding_path" 2>/dev/null || true)" + if [ -n "$outstanding_items" ]; then + outstanding_block=$'\nBacklog:\n'"$outstanding_items"$'\n\nPresent these to the user as a numbered list, numbered starting at 1 (never 0), keeping the numbers above even in a short reply, and ask which of these (if any) they want to tackle this session.\n' + else + outstanding_block="" + fi +elif grep -q '^## Outstanding items' "$cwd/$primer_path" 2>/dev/null; then + status_outstanding="?" + outstanding_block=$'\n⚠️ Outstanding items haven\'t migrated to .session-continuity/BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' +elif [ -f "$cwd/.session-continuity/OUTSTANDING_ITEMS.md" ]; then + status_outstanding="?" + outstanding_block=$'\n⚠️ .session-continuity/OUTSTANDING_ITEMS.md hasn\'t migrated to BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.\n' +else + status_outstanding="0" + outstanding_block="" +fi +``` + +- [ ] **Step 3: Shellcheck and manual smoke test** + +```bash +shellcheck hooks/session-start.sh +``` + +Expected: no new warnings versus the pre-edit baseline (run `git stash` + `shellcheck` first if unsure of the baseline, then `git stash pop`). + +Manual smoke test — simulate the new elif branch by faking an old-format `.session-continuity/` in a scratch dir: + +```bash +tmpdir="$(mktemp -d)" +cd "$tmpdir" && git init -q +mkdir .session-continuity +cat > .session-continuity/SESSION_PRIMER.md <<'EOF' +# Session Primer — scratch + +## Current state +placeholder +EOF +cat > .session-continuity/LEARNINGS.md <<'EOF' +# Learnings +EOF +cat > .session-continuity/OUTSTANDING_ITEMS.md <<'EOF' +# Outstanding Items — scratch + +### 1. Example item +EOF +git add -A && git commit -q -m "scratch" +echo "{\"cwd\": \"$tmpdir\"}" | bash /Users/tal.golan/active_development/TG/session-continuity-plugin/hooks/session-start.sh +cd - && rm -rf "$tmpdir" +``` + +Expected: output includes `⚠️ .session-continuity/OUTSTANDING_ITEMS.md hasn't migrated to BACKLOG.md yet — run /session-continuity:primer now to migrate before continuing.` and `- Backlog: ?`. + +- [ ] **Step 4: Commit** + +```bash +git add hooks/session-start.sh +git commit -m "feat: session-start.sh recognizes BACKLOG.md, nudges old OUTSTANDING_ITEMS.md installs" +``` + +--- + +### Task 5: `commands/primer.md` — detection, init mode, migration Step 3c, placeholder rename + +**Files:** +- Modify: `commands/primer.md` + +**Interfaces:** +- Consumes: `{{BACKLOG}}` placeholder name from Task 1, `skills/session-continuity/templates/BACKLOG.md` and `skills/session-continuity/templates/ROADMAP.md` paths from Tasks 1–2. +- Produces: the Step 3c migration behavior that Task 13 (this repo's own dogfood migration) exercises manually. + +- [ ] **Step 1: Step 1 (Detect state) — add BACKLOG/ROADMAP existence probes** + +In the Step 1 gather block, after the `PRIMER_HAS_INLINE_OUTSTANDING` line, add: +```bash +[ -f .session-continuity/BACKLOG.md ] && echo "BACKLOG_EXISTS=1" || echo "BACKLOG_EXISTS=0" +[ -f .session-continuity/ROADMAP.md ] && echo "ROADMAP_EXISTS=1" || echo "ROADMAP_EXISTS=0" +``` +(The existing `OUTSTANDING_ITEMS_EXISTS` line stays — Step 3c's trigger condition needs it.) + +After the existing sequencing paragraph for Step 3b, add a second paragraph: + +```markdown +If `OUTSTANDING_ITEMS_EXISTS=1` AND `BACKLOG_EXISTS=0`, a file-rename +migration is needed — run it (Step 3c below) in addition to whichever of +the four states above applies. **Sequencing:** if Step 3b also fired this +run (inline heading present, no file yet), run Step 3b to completion +first — it still writes `OUTSTANDING_ITEMS.md` under the old name — then +run Step 3c against that result. Step 3c is strictly the one-level-up +file rename; it never inspects primer content. +``` + +- [ ] **Step 2: Step 2 (Init mode) — copy BACKLOG.md and ROADMAP.md instead of OUTSTANDING_ITEMS.md** + +Change item 5: +```markdown +5. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/OUTSTANDING_ITEMS.md` to `.session-continuity/OUTSTANDING_ITEMS.md`. +``` +to: +```markdown +5. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/BACKLOG.md` to `.session-continuity/BACKLOG.md`. +6. Copy the template from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/ROADMAP.md` to `.session-continuity/ROADMAP.md`. +``` +(renumber every subsequent item in Step 2 by +1 — old item 6 "Fill in placeholders..." becomes item 7, old item 7 "Ask the user..." becomes item 8, old item 8 "Replace any remaining..." becomes item 9, old item 9 "Stage all four files" becomes item 10, old item 10 "Tell the user" becomes item 11). + +In renumbered item 8 (was 7 — "Ask the user for the blanks"), change: +```markdown +7. Ask the user for the blanks that can't be derived: `{{GROUND_RULES}}`, `{{WHERE_TO_LOOK_ROWS}}`, `{{STUCK_ESCALATION_STEPS}}`, `{{OUTSTANDING_ITEMS}}`, and `{{WORKFLOW_CONVENTIONS}}` only if no `CLAUDE.md` draft was produced above. +``` +to: +```markdown +8. Ask the user for the blanks that can't be derived: `{{GROUND_RULES}}`, `{{WHERE_TO_LOOK_ROWS}}`, `{{STUCK_ESCALATION_STEPS}}`, `{{BACKLOG}}`, and `{{WORKFLOW_CONVENTIONS}}` only if no `CLAUDE.md` draft was produced above. +``` +Rest of that item's sentence: keep "**Wait for their answer.**" as-is, and update the step-number reference from "Do not proceed to Step 9 until the user responds" to **"Do not proceed to Step 10 until the user responds"** — item 10 is the renumbered staging step, which is what this sentence gates on. + +Change the sub-heading "**Outstanding-items conversion rule.**" paragraph — rename every `{{OUTSTANDING_ITEMS}}` in it to `{{BACKLOG}}`, and rename `.session-continuity/OUTSTANDING_ITEMS.md` to `.session-continuity/BACKLOG.md`: +```markdown +**Outstanding-items conversion rule.** The user's answer for +`{{OUTSTANDING_ITEMS}}` is free-form prose — a list, a paragraph, however +they typed it. Convert it into one `### N.` entry per distinct item in +`.session-continuity/OUTSTANDING_ITEMS.md`, numbered sequentially +starting at 1, trimming each to a title plus 1-3 sentences (the same +length cap every item in that file follows). Never paste the raw answer +in as a single unstructured blob. If the user said "none" or skipped the +question, leave the file's `{{OUTSTANDING_ITEMS}}` placeholder area empty +(substituted per the existing placeholder-cleanup step below, same as any +other skipped field). +``` +becomes: +```markdown +**Backlog conversion rule.** The user's answer for +`{{BACKLOG}}` is free-form prose — a list, a paragraph, however +they typed it. Convert it into one `### N.` entry per distinct item in +`.session-continuity/BACKLOG.md`, numbered sequentially +starting at 1, trimming each to a title plus 1-3 sentences (the same +length cap every item in that file follows). Never paste the raw answer +in as a single unstructured blob. If the user said "none" or skipped the +question, leave the file's `{{BACKLOG}}` placeholder area empty +(substituted per the existing placeholder-cleanup step below, same as any +other skipped field). +``` + +Renumbered item 9 (was 8 — placeholder cleanup), change: +```markdown +8. **Replace any remaining `{{PLACEHOLDER}}` tokens with `TBD` before staging.** ... `grep -n '{{' .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/OUTSTANDING_ITEMS.md` must return nothing after this step. +``` +to: +```markdown +9. **Replace any remaining `{{PLACEHOLDER}}` tokens with `TBD` before staging.** If the user skipped a field, declined to answer, or asked you to stage/commit without filling everything in, substitute `TBD` (with an empty body line where the template had prose). Never leave `{{...}}` syntax in a file you are about to stage — `grep -n '{{' .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md` must return nothing after this step. +``` + +Renumbered item 10 (was 9 — stage), change: +```markdown +9. Stage all four files: `git add .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/OUTSTANDING_ITEMS.md`. +``` +to: +```markdown +10. Stage all five files: `git add .session-continuity/SESSION_PRIMER.md .session-continuity/PROJECT_CONTEXT.md .session-continuity/LEARNINGS.md .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md`. +``` + +Renumbered item 11 (was 10 — tell the user), change: +```markdown +10. Tell the user: "Primer, PROJECT_CONTEXT, OUTSTANDING_ITEMS, and LEARNINGS staged. Review and commit with `git commit -m 'docs: initialize session continuity'` when ready." Include a one-line note listing any fields that were set to `TBD` so the user knows what to fill in later. +``` +to: +```markdown +11. Tell the user: "Primer, PROJECT_CONTEXT, BACKLOG, ROADMAP, and LEARNINGS staged. Review and commit with `git commit -m 'docs: initialize session continuity'` when ready." Include a one-line note listing any fields that were set to `TBD` so the user knows what to fill in later. +``` + +- [ ] **Step 3: Insert new Step 3c section, after the existing Step 3b section** + +Insert this whole section directly after Step 3b's closing `**Do not commit automatically.** Staging only, same as every other split.` line, before the `## Step 4 — Refresh mode` heading: + +```markdown +## Step 3c — Backlog rename migration + +Runs whenever `BACKLOG_EXISTS=0` AND `OUTSTANDING_ITEMS_EXISTS=1` (see +Step 1). This is strictly the `OUTSTANDING_ITEMS.md` → `BACKLOG.md` +rename, one level up from Step 3b (which may have just created +`OUTSTANDING_ITEMS.md` under its old name this same run — Step 3c runs +after it, per the sequencing note in Step 1). + +1. `git mv .session-continuity/OUTSTANDING_ITEMS.md .session-continuity/BACKLOG.md`. +2. Rewrite the moved file's first heading line from `# Outstanding Items + — <project>` to `# Backlog — <project>`. Also rewrite line 3 (after + the blank line 2) — the body's opening sentence, currently starting + "Backlog of explicitly deferred follow-ups..." — to "Explicitly + deferred follow-ups..." (drop the leading "Backlog of"), so the file + doesn't read "# Backlog" immediately followed by "Backlog of..." + (same redundancy Task 1 avoids in the fresh-install template). + Content and item numbers are otherwise untouched. +3. Grep `.session-continuity/SESSION_PRIMER.md` for any remaining literal + reference to `OUTSTANDING_ITEMS.md` (a leftover pointer sentence from + before Step 3b/3c ran) and rewrite each to `BACKLOG.md`. +4. If `.session-continuity/ROADMAP.md` doesn't exist, create it from + `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/ROADMAP.md` + with `{{PROJECT_NAME}}` filled from the primer's own project name and + `{{ROADMAP_NOW}}`/`{{ROADMAP_NEXT}}`/`{{ROADMAP_LATER}}` all set to + `TBD` — no interactive prompt. Bundled into this same step so the + rename and the stub land as one migration event/commit, not two. +5. Stage the touched/new files: + `git add .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md` + and, only if Step 3 above actually changed it, + `git add .session-continuity/SESSION_PRIMER.md`. +6. Tell the user: "Migrated `.session-continuity/OUTSTANDING_ITEMS.md` → + `BACKLOG.md` (N items, numbers preserved) and stubbed in + `.session-continuity/ROADMAP.md`. Both staged — review before + committing." +7. Fall through to whichever of refresh mode (Step 4) or check mode + (Step 5) applies against the now-migrated primer, same fall-through + convention as Steps 3 and 3b. + +**Do not commit automatically.** Staging only — same rule as every other +split/migration step in this command. +``` + +- [ ] **Step 4: Update Step 4 (Refresh mode) and Step 5 (Check mode) body references** + +In Step 4, change every occurrence of `.session-continuity/OUTSTANDING_ITEMS.md` to `.session-continuity/BACKLOG.md` (appears in item 4's "Read `.session-continuity/OUTSTANDING_ITEMS.md`..." sentence, item 6's two sentences, and item 7's `git add` line). Change "Outstanding items" prose label to "Backlog" everywhere it appears as a user-facing label (item 5's question: `"Outstanding items — anything to remove...?"` → `"Backlog — anything to remove...?"`; item 8's confirmation message stays about "the primer", no rename needed there). + +In Step 5's gather block, change: +```bash +grep -cE '^### [0-9]+\.' .session-continuity/OUTSTANDING_ITEMS.md 2>/dev/null || echo 0 +``` +to: +```bash +grep -cE '^### [0-9]+\.' .session-continuity/BACKLOG.md 2>/dev/null || echo 0 +``` +And in the report block, change: +``` +Outstanding items: <count from OUTSTANDING_ITEMS.md> +``` +to: +``` +Backlog: <count from BACKLOG.md> +``` + +- [ ] **Step 5: Update the Notes section** + +Change: +```markdown +- **Respect the primer-only-commit rule.** If the user asks you to commit only the primer, warn them per `skills/session-continuity/SKILL.md` and proceed only if they confirm it's a catch-up. +``` +Leave unchanged (no rename needed). No other Notes-section changes required. + +- [ ] **Step 6: Verify — grep sweep of the file** + +```bash +grep -n "OUTSTANDING_ITEMS" commands/primer.md +``` + +Expected: every remaining hit is inside Step 3b (untouched, by design — it still targets the old filename for the inline-heading case) or inside Step 3c/Step 1 where it names the *trigger condition* (`OUTSTANDING_ITEMS_EXISTS`, or the literal old filename being migrated *from*). No hit should be a "current file to read/write" reference outside those two contexts. Read the full grep output and manually confirm each line before proceeding. + +- [ ] **Step 7: Commit** + +```bash +git add commands/primer.md +git commit -m "feat: primer.md inits BACKLOG.md+ROADMAP.md, migrates old OUTSTANDING_ITEMS.md installs" +``` + +--- + +### Task 6: `commands/doctor.md` — track BACKLOG.md and ROADMAP.md + +**Files:** +- Modify: `commands/doctor.md` + +**Interfaces:** +- Consumes: nothing new — same probe pattern as before, extended to 5 files. + +- [ ] **Step 1: Edit the file-existence loop** + +Change: +```bash +for f in SESSION_PRIMER.md OUTSTANDING_ITEMS.md PROJECT_CONTEXT.md LEARNINGS.md; do +``` +to: +```bash +for f in SESSION_PRIMER.md BACKLOG.md ROADMAP.md PROJECT_CONTEXT.md LEARNINGS.md; do +``` + +- [ ] **Step 2: Edit row 3's description and the report table** + +Change: +```markdown +3. **Four `.session-continuity/` files exist; primer not stale.** +``` +to: +```markdown +3. **Five `.session-continuity/` files exist; primer not stale.** +``` + +In the report table, change: +```markdown +| .session-continuity/ files | ✓ / ⚠️ | "All four present, primer current" OR "⚠️ missing: `<names>`" OR "⚠️ primer stale — run /session-continuity:primer" | +``` +to: +```markdown +| .session-continuity/ files | ✓ / ⚠️ | "All five present, primer current" OR "⚠️ missing: `<names>`" OR "⚠️ primer stale — run /session-continuity:primer" | +``` + +- [ ] **Step 3: Verify** + +```bash +grep -En "OUTSTANDING_ITEMS|four \`.session-continuity" commands/doctor.md +``` + +Expected: no output. + +- [ ] **Step 4: Commit** + +```bash +git add commands/doctor.md +git commit -m "feat: doctor.md tracks BACKLOG.md and ROADMAP.md" +``` + +--- + +### Task 7: `commands/end-session.md` — rename throughout + +**Files:** +- Modify: `commands/end-session.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: Global literal-string rename** + +Every occurrence of `.session-continuity/OUTSTANDING_ITEMS.md` → `.session-continuity/BACKLOG.md`, and `OUTSTANDING_ITEMS.md` (bare) → `BACKLOG.md`. This affects (line numbers from the pre-edit file, re-verify after each edit since line numbers shift): + +- Step 1's "Outstanding-items verification" sub-heading and its "Data source" line, "Skip conditions" bullets (3 occurrences), and the "For each `### N.` entry in..." line. +- The "Routing `appears-DONE` candidates" prose (no direct filename mention — skip). +- The drift-clean prompt's step 4: `git diff --quiet .session-continuity/OUTSTANDING_ITEMS.md ... git add .session-continuity/OUTSTANDING_ITEMS.md`. +- The Refresh flow's step 3's overlay bullet: `For each \`### N.\` entry in \`.session-continuity/OUTSTANDING_ITEMS.md\``. +- The Refresh flow's step 6: `git diff --quiet .session-continuity/OUTSTANDING_ITEMS.md ... git add .session-continuity/OUTSTANDING_ITEMS.md`. +- Step 3's "Outstanding-items verdicts" bullet: `re-read \`.session-continuity/OUTSTANDING_ITEMS.md\``. +- Step 3's "Outstanding-items row — re-derive, do not cache" paragraph: two occurrences of `.session-continuity/OUTSTANDING_ITEMS.md`. + +Do this with `sd` (or `sed`) across the whole file rather than editing each site by hand, then manually re-check every remaining `OUTSTANDING` hit: + +```bash +sd '\.session-continuity/OUTSTANDING_ITEMS\.md' '.session-continuity/BACKLOG.md' commands/end-session.md +sd '`OUTSTANDING_ITEMS\.md`' '`BACKLOG.md`' commands/end-session.md +``` + +- [ ] **Step 2: Rename the user-facing "Outstanding items" label** + +The checklist row header and the two user-facing prompt strings say "Outstanding items". Rename all of them to "Backlog": + +- Row header in Step 3's table: `| Outstanding items | checkmark if none stale, else warning | ...` → `| Backlog | checkmark if none stale, else warning | ...`. +- Prompt in the drift-clean close-candidate flow: `"Outstanding items — N appears-DONE (see list). Close any, or leave as-is?"` → `"Backlog — N appears-DONE (see list). Close any, or leave as-is?"`. +- Prompt in the Refresh flow: `"Outstanding items — close any from the overlay, add new follow-ups, or no changes?"` → `"Backlog — close any from the overlay, add new follow-ups, or no changes?"`. +- Migration-nudge message: `"This project's outstanding items haven't migrated to \`.session-continuity/OUTSTANDING_ITEMS.md\` yet — run \`/session-continuity:primer\` first (it migrates automatically), then re-run \`/session-continuity:end-session\`."` → `"This project's backlog hasn't migrated to \`.session-continuity/BACKLOG.md\` yet — run \`/session-continuity:primer\` first (it migrates automatically), then re-run \`/session-continuity:end-session\`."` (this message now also covers the OUTSTANDING_ITEMS.md-old-name case, not just the inline-heading case — leave the surrounding skip-condition prose as-is, it already says "unmigrated project" generically). +- Example output block's row: `⚠️ Outstanding items: 5 tracked — ...` → `⚠️ Backlog: 5 tracked — ...`. + +- [ ] **Step 3: Verify** + +```bash +grep -En "OUTSTANDING_ITEMS|Outstanding items" commands/end-session.md +``` + +Expected: no output. + +- [ ] **Step 4: Commit** + +```bash +git add commands/end-session.md +git commit -m "feat: end-session.md reads/reports BACKLOG.md instead of OUTSTANDING_ITEMS.md" +``` + +--- + +### Task 8: `skills/session-continuity/SKILL.md` — rename, five files, add help command + +**Files:** +- Modify: `skills/session-continuity/SKILL.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: Frontmatter description (line 3)** + +Change: +```markdown +description: Establish and maintain cross-session memory for a project via four in-repo docs — .session-continuity/SESSION_PRIMER.md (current state, refreshed alongside substantive commits), .session-continuity/OUTSTANDING_ITEMS.md (explicitly deferred work), .session-continuity/PROJECT_CONTEXT.md (stable repo context, changes rarely), and .session-continuity/LEARNINGS.md (append-only wisdom for 15+ min bugs). Use when starting, before commits, or after hard-won bugs. +``` +to: +```markdown +description: Establish and maintain cross-session memory for a project via five in-repo docs — .session-continuity/SESSION_PRIMER.md (current state, refreshed alongside substantive commits), .session-continuity/BACKLOG.md (explicitly deferred work), .session-continuity/ROADMAP.md (strategic direction), .session-continuity/PROJECT_CONTEXT.md (stable repo context, changes rarely), and .session-continuity/LEARNINGS.md (append-only wisdom for 15+ min bugs). Use when starting, before commits, or after hard-won bugs. +``` + +- [ ] **Step 2: Intro bullet list (lines 8-15)** + +Change the intro line "Four in-repo files act as a handoff..." to "Five in-repo files act as a handoff...". + +Change the `OUTSTANDING_ITEMS.md` bullet: +```markdown +- **`.session-continuity/OUTSTANDING_ITEMS.md`** — backlog of explicitly deferred follow-ups and decisions (not bugs, not current state). Permanent numbering (delete-on-close, never renumber, never reuse a number), title + 1-3 sentence length cap per item — anything longer moves to a linked file under `meta/superpowers/`. +``` +to: +```markdown +- **`.session-continuity/BACKLOG.md`** — explicitly deferred follow-ups and decisions (not bugs, not current state). Permanent numbering (delete-on-close, never renumber, never reuse a number), title + 1-3 sentence length cap per item — anything longer moves to a linked file under `meta/superpowers/`. +- **`.session-continuity/ROADMAP.md`** — strategic direction: Now/Next/Later. Freeform — no numbering, no permanence rules, no length cap. Rewritten wholesale as direction changes. +``` + +Change the paragraph after the bullets: +```markdown +The four files are complementary: primer is volatile current-state, OUTSTANDING_ITEMS captures explicitly deferred work, PROJECT_CONTEXT is stable reference, LEARNINGS is durable wisdom. A fresh session reads the primer first to get oriented, skims PROJECT_CONTEXT once per session for the shape of the repo, consults OUTSTANDING_ITEMS for the decision backlog, then consults LEARNINGS when something surprising happens. +``` +to: +```markdown +The five files are complementary: primer is volatile current-state, BACKLOG captures explicitly deferred work, ROADMAP captures strategic direction, PROJECT_CONTEXT is stable reference, LEARNINGS is durable wisdom. A fresh session reads the primer first to get oriented, skims PROJECT_CONTEXT once per session for the shape of the repo, consults BACKLOG for the decision backlog, then consults LEARNINGS when something surprising happens. +``` + +- [ ] **Step 3: Command list (line 17)** + +Change: +```markdown +If installed as a plugin, six commands are available: `/session-continuity:primer` (init/split/refresh/check the primer), `/session-continuity:learning` (append a new LEARNINGS entry interactively), `/session-continuity:end-session` (close-out ritual — refresh the primer, capture any new learnings from this session, and report a ✓/⚠️ checklist before you close the laptop), `/session-continuity:spike-check` (force a spike to be designed against the real load-bearing path before it's built), `/session-continuity:doctor` (read-only diagnostic — is the install actually wired up: hooks registered, all four files present and not stale, plugin root resolved and not a stale cache, gate scripts executable), and `/session-continuity:update` (print the commands to pull and activate the plugin's latest published version). +``` +to: +```markdown +If installed as a plugin, seven commands are available: `/session-continuity:primer` (init/split/refresh/check the primer), `/session-continuity:learning` (append a new LEARNINGS entry interactively), `/session-continuity:end-session` (close-out ritual — refresh the primer, capture any new learnings from this session, and report a ✓/⚠️ checklist before you close the laptop), `/session-continuity:spike-check` (force a spike to be designed against the real load-bearing path before it's built), `/session-continuity:doctor` (read-only diagnostic — is the install actually wired up: hooks registered, all five files present and not stale, plugin root resolved and not a stale cache, gate scripts executable), `/session-continuity:update` (print the commands to pull and activate the plugin's latest published version), and `/session-continuity:help` (explain what the plugin does and what each file is for). +``` + +- [ ] **Step 4: Quick-start (new project) section (line 58)** + +Change: +```markdown +Run `/session-continuity:primer`. The command detects that no primer exists, copies all four templates from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/` into the project's `.session-continuity/`, fills in every placeholder it can derive automatically (project name, latest commits, working directory, test command), prompts the user for anything left blank, and stages all four files. It does not commit. +``` +to: +```markdown +Run `/session-continuity:primer`. The command detects that no primer exists, copies all five templates from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/` into the project's `.session-continuity/`, fills in every placeholder it can derive automatically (project name, latest commits, working directory, test command), prompts the user for anything left blank, and stages all five files. It does not commit. +``` + +Change the second paragraph: +```markdown +After the user commits, remind them of the two maintenance rules: refresh the primer alongside substantive commits (stage the refresh in the same commit as the real change — do not commit the primer by itself), and add a LEARNINGS entry for every bug that took 15+ minutes to diagnose. +``` +Leave unchanged (no rename needed). + +Change the fallback sentence: +```markdown +If the `/session-continuity:primer` command is not installed (e.g. this skill was vendored manually, not installed as a plugin), fall back to copying the templates by hand from [`templates/SESSION_PRIMER.md`](templates/SESSION_PRIMER.md), [`templates/OUTSTANDING_ITEMS.md`](templates/OUTSTANDING_ITEMS.md), [`templates/PROJECT_CONTEXT.md`](templates/PROJECT_CONTEXT.md), and [`templates/LEARNINGS.md`](templates/LEARNINGS.md) into the project's `.session-continuity/`, filling placeholders, and committing the set. +``` +to: +```markdown +If the `/session-continuity:primer` command is not installed (e.g. this skill was vendored manually, not installed as a plugin), fall back to copying the templates by hand from [`templates/SESSION_PRIMER.md`](templates/SESSION_PRIMER.md), [`templates/BACKLOG.md`](templates/BACKLOG.md), [`templates/ROADMAP.md`](templates/ROADMAP.md), [`templates/PROJECT_CONTEXT.md`](templates/PROJECT_CONTEXT.md), and [`templates/LEARNINGS.md`](templates/LEARNINGS.md) into the project's `.session-continuity/`, filling placeholders, and committing the set. +``` + +- [ ] **Step 5: Maintenance-rules section (lines 95-110)** + +Change: +```markdown +Alongside the primer, also update the separate file +`.session-continuity/OUTSTANDING_ITEMS.md`: remove things you just +finished, add newly-flagged follow-ups from code review or user +feedback. +``` +to: +```markdown +Alongside the primer, also update the separate file +`.session-continuity/BACKLOG.md`: remove things you just +finished, add newly-flagged follow-ups from code review or user +feedback. +``` + +Change: +```markdown +**Numbering convention for OUTSTANDING_ITEMS.md — mirrors LEARNINGS.** +``` +to: +```markdown +**Numbering convention for BACKLOG.md — mirrors LEARNINGS.** +``` + +- [ ] **Step 6: Verify** + +```bash +grep -En "OUTSTANDING_ITEMS|four in-repo|four files|four templates" skills/session-continuity/SKILL.md +``` + +Expected: no output. + +- [ ] **Step 7: Commit** + +```bash +git add skills/session-continuity/SKILL.md +git commit -m "docs: SKILL.md documents BACKLOG.md, ROADMAP.md, and /help" +``` + +--- + +### Task 9: `skills/session-continuity/REFERENCE.md` — rename + +**Files:** +- Modify: `skills/session-continuity/REFERENCE.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: Rename each hit** + +``` +L12: "...injects the outstanding-items shortlist. **Standing rule: whenever you discuss or echo outstanding items to the user — in this reminder, in `/session-continuity:end-session`'s prompts, or in free-form chat when directly asked — render them as a numbered list matching OUTSTANDING_ITEMS.md's own item numbers..." +``` +Rename `OUTSTANDING_ITEMS.md` → `BACKLOG.md` in that sentence (keep "outstanding items"/"outstanding-items" prose as lowercase generic English if it reads naturally, but since Goal 1 renames the *concept* label too, replace "outstanding-items shortlist" → "backlog shortlist" and "outstanding items" → "backlog" in that sentence and in "render them as a numbered list matching"). + +``` +L54: | "We should follow up on X" | `.session-continuity/OUTSTANDING_ITEMS.md` → new numbered entry | +``` +→ `.session-continuity/BACKLOG.md`. + +``` +L75: - **"Outstanding items" section.** Use your own taxonomy: "blocked", "deferred", "needs decision". Keep it actionable. +``` +→ `- **"Backlog" section.**` (rest unchanged). + +``` +L104: - OUTSTANDING_ITEMS: "What has been **explicitly deferred** (decisions, follow-ups, follow-ons) that we should not forget?" +``` +→ `- BACKLOG: "What has been **explicitly deferred**...` (add a new line directly after it: `- ROADMAP: "Where is this headed, independent of what's in the tactical queue?"`) + +``` +L108: Together they compress the cost of session handoff from "re-explain everything" to "read a couple of files." The primer stays short (a shortlist, not a snapshot); OUTSTANDING_ITEMS accumulates deferred work; PROJECT_CONTEXT and LEARNINGS both grow organically but at different rates — one when the project's shape changes, the other with every hard-won bug. All four outlive any single session. +``` +→ +```markdown +Together they compress the cost of session handoff from "re-explain everything" to "read a couple of files." The primer stays short (a shortlist, not a snapshot); BACKLOG accumulates deferred work; ROADMAP holds direction independent of the tactical queue; PROJECT_CONTEXT and LEARNINGS both grow organically but at different rates — one when the project's shape changes, the other with every hard-won bug. All five outlive any single session. +``` + +- [ ] **Step 2: Verify** + +```bash +grep -En "OUTSTANDING_ITEMS|All four" skills/session-continuity/REFERENCE.md +``` + +Expected: no output. + +- [ ] **Step 3: Commit** + +```bash +git add skills/session-continuity/REFERENCE.md +git commit -m "docs: REFERENCE.md documents BACKLOG.md and ROADMAP.md" +``` + +--- + +### Task 10: Templates `CLAUDE_MD_SNIPPET.md` and `SESSION_PRIMER.md` — rename + add ROADMAP + +**Files:** +- Modify: `skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md` +- Modify: `skills/session-continuity/templates/SESSION_PRIMER.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: `CLAUDE_MD_SNIPPET.md`** + +Change: +```markdown +Before touching anything, read `.session-continuity/SESSION_PRIMER.md` +(current state) and `.session-continuity/LEARNINGS.md` (bugs that were +expensive to diagnose — grep it when something surprises you). Read +`.session-continuity/PROJECT_CONTEXT.md` once per session for stable repo +shape, and `.session-continuity/OUTSTANDING_ITEMS.md` for the backlog of +deferred decisions and follow-ups; both change rarely. +``` +to: +```markdown +Before touching anything, read `.session-continuity/SESSION_PRIMER.md` +(current state) and `.session-continuity/LEARNINGS.md` (bugs that were +expensive to diagnose — grep it when something surprises you). Read +`.session-continuity/PROJECT_CONTEXT.md` once per session for stable repo +shape, `.session-continuity/BACKLOG.md` for deferred decisions and +follow-ups, and `.session-continuity/ROADMAP.md` for strategic direction; +all three change rarely. +``` + +Change: +```markdown +**Before marking any outstanding item DONE, verify it against the actual +code** +``` +to: +```markdown +**Before marking any backlog item DONE, verify it against the actual +code** +``` +(rest of that paragraph unchanged — no filename in it). + +- [ ] **Step 2: `SESSION_PRIMER.md` template** + +Change: +```markdown +You are picking up work on {{PROJECT_NAME}} from a previous session. This +file is the shortest path to what changed recently. For stable repo +context (layout, conventions, modules), read +`.session-continuity/PROJECT_CONTEXT.md` once per session — it changes +rarely. For the backlog of deferred decisions and follow-ups, read +`.session-continuity/OUTSTANDING_ITEMS.md`. +``` +to: +```markdown +You are picking up work on {{PROJECT_NAME}} from a previous session. This +file is the shortest path to what changed recently. For stable repo +context (layout, conventions, modules), read +`.session-continuity/PROJECT_CONTEXT.md` once per session — it changes +rarely. For the backlog of deferred decisions and follow-ups, read +`.session-continuity/BACKLOG.md`; for strategic direction, read +`.session-continuity/ROADMAP.md`. +``` + +- [ ] **Step 3: Verify** + +```bash +grep -n "OUTSTANDING_ITEMS" skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md skills/session-continuity/templates/SESSION_PRIMER.md +``` + +Expected: no output. + +- [ ] **Step 4: Commit** + +```bash +git add skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md skills/session-continuity/templates/SESSION_PRIMER.md +git commit -m "docs: template pointers reference BACKLOG.md and ROADMAP.md" +``` + +--- + +### Task 11: `plugin.json` version bump, `PRIVACY.md`, `CONTRIBUTING.md`, `CHANGELOG.md` + +**Files:** +- Modify: `.claude-plugin/plugin.json` +- Modify: `PRIVACY.md` +- Modify: `CONTRIBUTING.md` +- Modify: `CHANGELOG.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: `plugin.json`** + +Change: +```json + "version": "0.21.1", + "description": "Cross-session memory for Claude Code projects via four in-repo docs: SESSION_PRIMER.md (current state), PROJECT_CONTEXT.md (stable repo context), OUTSTANDING_ITEMS.md (deferred follow-ups), and LEARNINGS.md (hard-won bugs).", +``` +to: +```json + "version": "0.22.0", + "description": "Cross-session memory for Claude Code projects via five in-repo docs: SESSION_PRIMER.md (current state), PROJECT_CONTEXT.md (stable repo context), BACKLOG.md (deferred follow-ups), ROADMAP.md (strategic direction), and LEARNINGS.md (hard-won bugs).", +``` + +- [ ] **Step 2: `PRIVACY.md`** + +Change: +```markdown +- **File contents in your own repositories.** The slash commands `/session-continuity:primer`, `/session-continuity:learning`, and `/session-continuity:end-session` read and write `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/OUTSTANDING_ITEMS.md`, and `.session-continuity/LEARNINGS.md` in the current git repository. These are ordinary files in your repo; the plugin stores nothing elsewhere. `/session-continuity:spike-check`, `/session-continuity:doctor`, and `/session-continuity:update` touch no files at all — they print a checklist/report/instructions and (for spike-check) ask questions in-conversation. +``` +to: +```markdown +- **File contents in your own repositories.** The slash commands `/session-continuity:primer`, `/session-continuity:learning`, and `/session-continuity:end-session` read and write `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/BACKLOG.md`, `.session-continuity/ROADMAP.md`, and `.session-continuity/LEARNINGS.md` in the current git repository. These are ordinary files in your repo; the plugin stores nothing elsewhere. `/session-continuity:spike-check`, `/session-continuity:doctor`, `/session-continuity:update`, and `/session-continuity:help` touch no files at all — they print a checklist/report/instructions and (for spike-check) ask questions in-conversation. +``` + +- [ ] **Step 3: `CONTRIBUTING.md`** + +Change the directory-tree listing: +``` +│ └── templates/ +│ ├── SESSION_PRIMER.md +│ ├── PROJECT_CONTEXT.md +│ ├── OUTSTANDING_ITEMS.md +│ └── LEARNINGS.md +``` +to: +``` +│ └── templates/ +│ ├── SESSION_PRIMER.md +│ ├── PROJECT_CONTEXT.md +│ ├── BACKLOG.md +│ ├── ROADMAP.md +│ └── LEARNINGS.md +``` + +And the commands listing: +``` +├── commands/ +│ ├── primer.md # /session-continuity:primer +│ ├── learning.md # /session-continuity:learning +│ ├── end-session.md # /session-continuity:end-session +│ ├── spike-check.md # /session-continuity:spike-check +│ ├── doctor.md # /session-continuity:doctor +│ └── update.md # /session-continuity:update +``` +to: +``` +├── commands/ +│ ├── primer.md # /session-continuity:primer +│ ├── learning.md # /session-continuity:learning +│ ├── end-session.md # /session-continuity:end-session +│ ├── spike-check.md # /session-continuity:spike-check +│ ├── doctor.md # /session-continuity:doctor +│ ├── update.md # /session-continuity:update +│ └── help.md # /session-continuity:help +``` + +(Verify the exact current `update.md` line's trailing comment/tree-connector characters via `git show HEAD:CONTRIBUTING.md | sed -n '95,112p'` before editing, since the ASCII tree connectors — `├──` vs `└──` — must stay consistent after `update.md` stops being the last entry.) + +- [ ] **Step 4: `CHANGELOG.md` — new entry** + +Insert a new top entry directly below the `# Changelog` header/intro paragraph, above the existing `## [0.21.1] — 2026-08-31` entry: + +```markdown +## [0.22.0] — 2026-08-31 + +### Added +- **New `.session-continuity/ROADMAP.md` file** — strategic direction (Now/Next/Later), freeform, no numbering. `/session-continuity:primer` creates it on Init mode and stubs it in for existing installs during the BACKLOG.md migration below. +- **New `/session-continuity:help` command** — explains what the plugin does, why, and what each of the five `.session-continuity/` files is for. Zero args, read-only. + +### Changed +- **`.session-continuity/OUTSTANDING_ITEMS.md` renamed to `BACKLOG.md`.** Same semantics (permanent numbering, delete-on-close, title + 1-3 sentence cap) — rename only. `/session-continuity:primer` migrates existing installs automatically (new Step 3c): detects `OUTSTANDING_ITEMS.md` without a `BACKLOG.md` alongside it, `git mv`s the file, and stubs in `ROADMAP.md` in the same step. `hooks/session-start.sh` nudges any install still on the old filename to run `/session-continuity:primer`. +``` + +Use today's date if this task lands on a different day than assumed above — check `date +%Y-%m-%d` and use the actual date, not a hardcoded one. + +- [ ] **Step 5: Verify** + +```bash +grep -n "OUTSTANDING_ITEMS" .claude-plugin/plugin.json PRIVACY.md CONTRIBUTING.md +``` + +Expected: no output (CHANGELOG.md is intentionally excluded from this check — its historical entries below the new one still say `OUTSTANDING_ITEMS.md` on purpose). + +```bash +grep -m1 '"version"' .claude-plugin/plugin.json +``` + +Expected: `"version": "0.22.0",`. + +- [ ] **Step 6: Commit** + +```bash +git add .claude-plugin/plugin.json PRIVACY.md CONTRIBUTING.md CHANGELOG.md +git commit -m "chore: bump to 0.22.0 — BACKLOG.md rename, ROADMAP.md, /help command" +``` + +--- + +### Task 12: `README.md` — full rename + five-file language + help command + +**Files:** +- Modify: `README.md` + +**Interfaces:** +- Consumes: nothing new. + +- [ ] **Step 1: Top summary line (line 3)** + +Change: +```markdown +Cross-session memory for Claude Code projects. A skill Claude loads on its own, four plain-Markdown docs committed to your repo, six slash commands, and a set of session hooks that surface the right knowledge at the right moment. +``` +to: +```markdown +Cross-session memory for Claude Code projects. A skill Claude loads on its own, five plain-Markdown docs committed to your repo, seven slash commands, and a set of session hooks that surface the right knowledge at the right moment. +``` + +- [ ] **Step 2: "Why this exists" section (line ~9)** + +Change "Four files hold the memory, four slash commands keep them honest" → "Five files hold the memory, seven slash commands keep them honest". + +Change: +```markdown +That's what `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/OUTSTANDING_ITEMS.md`, and `.session-continuity/LEARNINGS.md` buy you: the ability to close the laptop at any point, come back cold, and have a new session up to speed in four file reads instead of rebuilding context by re-prompting. +``` +to: +```markdown +That's what `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, `.session-continuity/BACKLOG.md`, `.session-continuity/ROADMAP.md`, and `.session-continuity/LEARNINGS.md` buy you: the ability to close the laptop at any point, come back cold, and have a new session up to speed in five file reads instead of rebuilding context by re-prompting. +``` + +- [ ] **Step 3: "What's in the box" table** + +Change: +```markdown +| **`session-continuity` skill** | Claude loads it automatically based on the task. It teaches Claude the four-file pattern, the maintenance rules, and the decision tree for what belongs where, even before you run any command. | +``` +to: +```markdown +| **`session-continuity` skill** | Claude loads it automatically based on the task. It teaches Claude the five-file pattern, the maintenance rules, and the decision tree for what belongs where, even before you run any command. | +``` + +Change the `OUTSTANDING_ITEMS.md` row: +```markdown +| **`.session-continuity/OUTSTANDING_ITEMS.md`** | Backlog of explicitly deferred follow-ups and decisions. Permanent numbering, delete-on-close, title + 1-3 sentence cap per item. | +``` +to: +```markdown +| **`.session-continuity/BACKLOG.md`** | Explicitly deferred follow-ups and decisions. Permanent numbering, delete-on-close, title + 1-3 sentence cap per item. | +| **`.session-continuity/ROADMAP.md`** | Strategic direction — Now/Next/Later. Freeform, no numbering, rewritten wholesale as direction changes. | +``` + +Change the `/session-continuity:doctor` row: +```markdown +| **`/session-continuity:doctor`** | Read-only diagnostic: is the install actually wired up — hooks registered, all four files present and not stale, plugin root resolved and not a stale cache, gate scripts executable. | +``` +to: +```markdown +| **`/session-continuity:doctor`** | Read-only diagnostic: is the install actually wired up — hooks registered, all five files present and not stale, plugin root resolved and not a stale cache, gate scripts executable. | +``` + +Add a new row directly after the `/session-continuity:update` row: +```markdown +| **`/session-continuity:help`** | Explain what the plugin does, why, and what each of the five files is for. | +``` + +- [ ] **Step 4: "The four files" section → "The five files"** + +Change the heading `## The four files` to `## The five files`. + +Change: +```markdown +**`.session-continuity/OUTSTANDING_ITEMS.md`** is the backlog: explicitly +deferred decisions and follow-ups, not bugs and not current state. Item +numbers are permanent — a closed item is deleted outright, never +renumbered — so a cross-reference to "item 4" stays valid for as long as +item 4 exists. Each item is capped at a title plus 1-3 sentences; anything +longer belongs in a linked spec, not inlined here. +``` +to: +```markdown +**`.session-continuity/BACKLOG.md`** is the tactical queue: explicitly +deferred decisions and follow-ups, not bugs and not current state. Item +numbers are permanent — a closed item is deleted outright, never +renumbered — so a cross-reference to "item 4" stays valid for as long as +item 4 exists. Each item is capped at a title plus 1-3 sentences; anything +longer belongs in a linked spec, not inlined here. + +**`.session-continuity/ROADMAP.md`** is strategic direction, independent +of the tactical queue — Now/Next/Later, freeform. No numbering, no +permanence rules, no length cap; rewrite it wholesale as direction +changes rather than editing around old entries. +``` + +Change: +```markdown +All four files ship as templates, so you start from a real structure instead of a blank page. +``` +to: +```markdown +All five files ship as templates, so you start from a real structure instead of a blank page. +``` + +- [ ] **Step 5: "The commands" section — primer's five behaviors → six** + +Change: +```markdown +One command, five behaviors, dispatched on the repo's current state: +``` +to: +```markdown +One command, six behaviors, dispatched on the repo's current state: +``` + +Change: +```markdown +- **Primer has an inline Outstanding items section, no OUTSTANDING_ITEMS.md yet** → extracts that section verbatim into the new file, preserving item numbers as permanent IDs, and removes it from the primer. Runs immediately on detection — this plugin has one consumer today, so migration is pushed, not offered indefinitely. +``` +to (keep as-is, then add a new bullet directly after it): +```markdown +- **Primer has an inline Outstanding items section, no BACKLOG.md yet** → extracts that section verbatim into the new file, preserving item numbers as permanent IDs, and removes it from the primer. Runs immediately on detection — this plugin has one consumer today, so migration is pushed, not offered indefinitely. +- **Project has the old `OUTSTANDING_ITEMS.md` file, no `BACKLOG.md` yet** → renames it to `BACKLOG.md` (numbers and content unchanged) and stubs in `ROADMAP.md` if it doesn't already exist. Runs immediately on detection, same push-not-offer policy as the bullet above. +``` + +Change: +```markdown +- **Primer current** → reports a four-line status (HEAD, last refresh, outstanding-item count, learnings count) and exits without touching anything. +``` +to: +```markdown +- **Primer current** → reports a four-line status (HEAD, last refresh, backlog count, learnings count) and exits without touching anything. +``` + +- [ ] **Step 6: "What goes where" table and "Why four files" → "Why five files" section** + +Change: +```markdown +| "We should follow up on X" | `.session-continuity/OUTSTANDING_ITEMS.md` → new numbered entry | +``` +to: +```markdown +| "We should follow up on X" | `.session-continuity/BACKLOG.md` → new numbered entry | +| "Where is this headed next quarter" | `.session-continuity/ROADMAP.md` → Now/Next/Later | +``` + +Change the heading `## Why four files` to `## Why five files`. + +Change: +```markdown +**OUTSTANDING_ITEMS** shares PROJECT_CONTEXT's slow pace, but not its permanence: unlike LEARNINGS' append-only history, closed items are deleted outright, so the file only ever holds the live backlog, never a full record of everything ever deferred. +``` +to: +```markdown +**BACKLOG** shares PROJECT_CONTEXT's slow pace, but not its permanence: unlike LEARNINGS' append-only history, closed items are deleted outright, so the file only ever holds the live backlog, never a full record of everything ever deferred. + +**ROADMAP** is the newest of the five and the least ceremonious: no numbering, no permanence, no length cap. It exists because "what's the tactical backlog" and "what's the strategic direction" are different questions with different lifespans — a backlog item resolves in days or weeks; a roadmap entry describes a horizon that outlives any single item. +``` + +Change: +```markdown +Blending any of these forces bad tradeoffs. Current-state notes drown stable context or accumulated wisdom; wisdom gets edited away when someone trims "stale" entries. Keeping them in separate files with separate update contracts means the primer answers "what is true right now," PROJECT_CONTEXT answers "what is true about this project generally," OUTSTANDING_ITEMS answers "what have we deliberately deferred," and LEARNINGS answers "what should I know to avoid rediscovering pain" — and none of the four pretends to answer another's question. +``` +to: +```markdown +Blending any of these forces bad tradeoffs. Current-state notes drown stable context or accumulated wisdom; wisdom gets edited away when someone trims "stale" entries. Keeping them in separate files with separate update contracts means the primer answers "what is true right now," PROJECT_CONTEXT answers "what is true about this project generally," BACKLOG answers "what have we deliberately deferred," ROADMAP answers "where is this headed," and LEARNINGS answers "what should I know to avoid rediscovering pain" — and none of the five pretends to answer another's question. +``` + +- [ ] **Step 7: Verify** + +```bash +grep -En "OUTSTANDING_ITEMS|four plain-Markdown|six slash commands|four-file pattern|four files|four file reads|All four files|five behaviors|Why four files|none of the four" README.md +``` + +Expected: no output. (Run this, read every hit, fix, re-run — README.md is the largest single-file diff in this plan and the most likely place to miss one.) + +- [ ] **Step 8: Commit** + +```bash +git add README.md +git commit -m "docs: README documents BACKLOG.md, ROADMAP.md, and /help" +``` + +--- + +### Task 13: Dogfood — migrate this repo's own `.session-continuity/` instance + +**Files:** +- Modify: `.session-continuity/OUTSTANDING_ITEMS.md` → `.session-continuity/BACKLOG.md` (rename) +- Create: `.session-continuity/ROADMAP.md` +- Modify: `.session-continuity/SESSION_PRIMER.md` + +**Interfaces:** +- Consumes: Task 5's Step 3c logic (executed manually here, by hand, since running the actual `/session-continuity:primer` command from inside its own repo mid-implementation is circular — this task performs the same operations Step 3c specifies, verifying the spec's migration steps are correct by executing them for real). + +- [ ] **Step 1: Rename** + +```bash +git mv .session-continuity/OUTSTANDING_ITEMS.md .session-continuity/BACKLOG.md +``` + +Edit the moved file's first line from `# Outstanding Items — session-continuity` to `# Backlog — session-continuity`, and line 3 (after the blank line 2 — the body's opening sentence) from "Backlog of explicitly deferred follow-ups and decisions — not bugs (those" to "Explicitly deferred follow-ups and decisions — not bugs (those" — same redundancy fix as Task 5's Step 3c. Leave the four numbered items (1–4) and all other prose unchanged. + +- [ ] **Step 2: Stub `ROADMAP.md`** + +```markdown +# Roadmap — session-continuity + +Strategic direction — where this project is headed, not the tactical +queue (that's `.session-continuity/BACKLOG.md`). Freeform: no numbering, +no permanence rules, no length cap. Rewrite sections wholesale as +direction changes; this file's history lives in git, not in careful +edits. + +## Now + +TBD + +## Next + +TBD + +## Later + +TBD +``` + +- [ ] **Step 3: Update `.session-continuity/SESSION_PRIMER.md`'s live repo-layout line** + +Change (this is a live description of current repo layout, not historical narrative — it must be updated): +```markdown +- `.session-continuity/` holds `SESSION_PRIMER.md`, `PROJECT_CONTEXT.md` (new in v0.13.0), `OUTSTANDING_ITEMS.md` (new in v0.18.0), and `LEARNINGS.md`. Dev artifacts (marketplace-submission notes, specs, plans, recommendation docs) live under `meta/`. +``` +to: +```markdown +- `.session-continuity/` holds `SESSION_PRIMER.md`, `PROJECT_CONTEXT.md` (new in v0.13.0), `BACKLOG.md` (new in v0.18.0 as `OUTSTANDING_ITEMS.md`, renamed in v0.22.0), `ROADMAP.md` (new in v0.22.0), and `LEARNINGS.md`. Dev artifacts (marketplace-submission notes, specs, plans, recommendation docs) live under `meta/`. +``` + +**Leave the other hit (the "v0.12.3 shipped" historical bullet describing the SessionStart hook's original inline-heading behavior, containing the phrase `extracts the "Outstanding items" section`) unchanged** — it's a historical record of what v0.12.3 did, predating even the old `OUTSTANDING_ITEMS.md` file's existence, and rewriting it would misrepresent history. Confirm this is the only other hit before moving on: + +```bash +grep -En "OUTSTANDING|Outstanding" .session-continuity/SESSION_PRIMER.md +``` + +Expected: exactly one hit, the "v0.12.3 shipped" historical bullet. + +- [ ] **Step 4: Regenerate the primer's `git log --oneline -5` block and add a current-state note** + +```bash +git log --oneline -5 +``` + +Update `.session-continuity/SESSION_PRIMER.md`'s `git log --oneline -5` block to match, and prepend a one-line note to the "Current state" narrative: `- **v0.22.0 in progress** — renamed OUTSTANDING_ITEMS.md to BACKLOG.md, added ROADMAP.md, added /session-continuity:help. Branch feature/backlog-roadmap-help, not yet merged.` This follows this repo's own maintenance rule (refresh the primer alongside substantive commits) — Task 14 will update this note once more to say "shipped" after the PR merges, per this repo's own primer-maintenance convention for release bullets. + +- [ ] **Step 5: Verify** + +```bash +grep -c "^### [0-9]\+\." .session-continuity/BACKLOG.md +``` + +Expected: `4` (all four existing items preserved, numbers unchanged). + +```bash +diff <(git show HEAD:.session-continuity/OUTSTANDING_ITEMS.md | tail -n +4) <(tail -n +4 .session-continuity/BACKLOG.md) +``` + +Expected: no output (lines 1-3 — title, blank, reworded opening sentence — are excluded by `tail -n +4`; everything from line 4 onward, including all four numbered items, must be byte-identical). + +- [ ] **Step 6: Commit** + +```bash +git add .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md .session-continuity/SESSION_PRIMER.md +git commit -m "docs: migrate this repo's own OUTSTANDING_ITEMS.md to BACKLOG.md, add ROADMAP.md" +``` + +--- + +### Task 14: Final full-repo verification and PR + +**Files:** none (verification + PR only). + +**Interfaces:** +- Consumes: the completed state of all prior tasks. + +- [ ] **Step 1: Full-repo grep sweep** + +```bash +grep -rn "OUTSTANDING_ITEMS" --include="*.md" --include="*.sh" --include="*.json" . 2>/dev/null | grep -v node_modules +``` + +Expected: every remaining hit is one of: +- `CHANGELOG.md` — historical entries below the new `[0.22.0]` entry (intentional, per Global Constraints). +- `commands/primer.md` — Step 1's `OUTSTANDING_ITEMS_EXISTS` variable name and Step 3b/3c's references to the *old filename being migrated from* (intentional, per Task 5). +- `hooks/session-start.sh` — the new elif branch's literal old-filename check and its warning message (intentional, per Task 4). +- `meta/superpowers/plans/*`, `meta/superpowers/specs/*`, `meta/superpowers/recommendations/*`, `meta/superpowers/validation/*` — historical design docs from before this change (out of scope — these describe decisions made under the old name; not rewritten). + +If any hit doesn't fit one of the four buckets above, go back and fix the file it's in. + +- [ ] **Step 2: Confirm no leftover template placeholder syntax** + +```bash +grep -rn "{{OUTSTANDING_ITEMS}}" . +``` + +Expected: no output. + +- [ ] **Step 3: Shellcheck the modified hook** + +```bash +shellcheck hooks/session-start.sh +``` + +Expected: no warnings (already checked in Task 4, re-confirming after all edits landed). + +- [ ] **Step 4: Manually exercise `/session-continuity:doctor` against this repo** + +Since there's no automated harness, manually run the Bash block from `commands/doctor.md`'s Step 1 against this repo's own working tree and confirm the five-file loop reports `BACKLOG.md=EXISTS`, `ROADMAP.md=EXISTS`, `SESSION_PRIMER.md=EXISTS`, `PROJECT_CONTEXT.md=EXISTS`, `LEARNINGS.md=EXISTS`. + +- [ ] **Step 5: Push and open the PR** + +```bash +git push -u origin feature/backlog-roadmap-help +gh pr create --title "Rename OUTSTANDING_ITEMS.md to BACKLOG.md, add ROADMAP.md and /help" --body "$(cat <<'EOF' +## Summary +- Renames `.session-continuity/OUTSTANDING_ITEMS.md` to `BACKLOG.md` everywhere (template, commands, hooks, skill docs), with an automatic migration path (`primer.md` Step 3c) for existing installs. +- Adds a new `.session-continuity/ROADMAP.md` stub file for strategic direction (Now/Next/Later), separate from the tactical BACKLOG. +- Adds `/session-continuity:help` — explains the plugin's purpose and what each of the five files is for. +- Migrates this repo's own `.session-continuity/` instance as proof the migration path works. +- Bumps `0.21.1` → `0.22.0`. + +## Test plan +- [x] Manual grep-invariant checks after every file edit (see plan tasks 1–13's verify steps) +- [x] `shellcheck hooks/session-start.sh` clean +- [x] Manual smoke test of the new `session-start.sh` elif branch against a scratch repo +- [x] Manual dry-run of `commands/doctor.md`'s file-existence loop against this repo +- [x] Full-repo grep sweep confirms no unintentional leftover `OUTSTANDING_ITEMS` reference + +Spec: `meta/superpowers/specs/2026-08-31-backlog-roadmap-help-design.md` +Plan: `meta/superpowers/plans/2026-08-31-backlog-roadmap-help.md` +EOF +)" +``` diff --git a/meta/superpowers/specs/2026-08-31-backlog-roadmap-help-design.md b/meta/superpowers/specs/2026-08-31-backlog-roadmap-help-design.md new file mode 100644 index 0000000..cf6c069 --- /dev/null +++ b/meta/superpowers/specs/2026-08-31-backlog-roadmap-help-design.md @@ -0,0 +1,232 @@ +# Design: BACKLOG.md rename, ROADMAP.md, and /session-continuity:help + +Date: 2026-08-31 +Status: approved for planning + +## Problem + +`.session-continuity/OUTSTANDING_ITEMS.md` is the wrong name for what the +file actually holds — a backlog of deferred work, not "items outstanding" +(which reads like open bugs/debt). Separately, the plugin has no file for +strategic direction (near/mid/long-term intent) distinct from tactical +backlog, and no single command that explains what the plugin is for and +what each file is responsible for — a new user has to read `SKILL.md` end +to end to get that picture. + +## Goals + +1. Rename `OUTSTANDING_ITEMS.md` → `BACKLOG.md` everywhere (template, + commands, hooks, skill docs, this repo's own instance), with the same + semantics (permanent numbering, delete-on-close, title + 1-3-sentence + cap). +2. Add a new stub file, `ROADMAP.md`, for strategic direction — Now / Next + / Later sections, no version numbers, no numbering/permanence rules. +3. Add `/session-continuity:help` — zero-arg, read-only — explaining the + plugin's purpose, why it exists, and the intent of each of the five + `.session-continuity/` files plus the command list. +4. Migrate existing installs (including this repo) automatically via + `/session-continuity:primer`, rather than leaving a manual rename step + for every consuming project. + +## Non-goals + +- No change to BACKLOG's numbering/closing rules — pure rename. +- No auto-population of ROADMAP.md content — stub only, user fills it in. +- No new hook behavior beyond updating existing path references and adding + one migration branch to the existing elif chain in `session-start.sh`. + +## File inventory (every touchpoint) + +Renamed / content-updated: + +- `skills/session-continuity/templates/OUTSTANDING_ITEMS.md` → renamed to + `skills/session-continuity/templates/BACKLOG.md` (heading "Outstanding + Items" → "Backlog", `{{OUTSTANDING_ITEMS}}` placeholder → `{{BACKLOG}}`, + prose otherwise unchanged). +- `hooks/session-start.sh` — `outstanding_path` var, reminder text + ("Outstanding items:" → "Backlog:"), migration elif chain (see below). +- `commands/primer.md` — Step 1 detection vars; new Step 3c (see Migration + below); Steps 4 and 5 prose/paths; Step 7's "Outstanding-items conversion + rule" paragraph and its `{{OUTSTANDING_ITEMS}}` placeholder name (rename + to `{{BACKLOG}}`); Step 8's placeholder-cleanup grep, which hardcodes + `.session-continuity/OUTSTANDING_ITEMS.md` (rename to `BACKLOG.md`, add + `ROADMAP.md` to the same grep). **Step 3b itself is unchanged** — it + still detects the inline-heading case and still writes + `OUTSTANDING_ITEMS.md` (old name); the new Step 3c is solely responsible + for the `OUTSTANDING_ITEMS.md` → `BACKLOG.md` rename, one level up, per + the sequencing rule below. Init mode (Step 2) always writes `BACKLOG.md` + directly for brand-new projects — Step 3b's old-name output only exists + on the migration path for projects that predate this change. +- `commands/doctor.md` — file-existence loop (`OUTSTANDING_ITEMS.md` → + `BACKLOG.md`, add `ROADMAP.md` as a fifth tracked file — SESSION_PRIMER, + PROJECT_CONTEXT, BACKLOG, ROADMAP, LEARNINGS), report row text. +- `commands/end-session.md` — checklist row referencing the file. +- `skills/session-continuity/SKILL.md` — file list (intro bullets, "four + in-repo files" → "five in-repo files"), numbering-convention section, + maintenance-rules section, quick-start sections, command list (add + `/session-continuity:help`). +- `skills/session-continuity/REFERENCE.md` — decision tree, "what goes + where," any other mentions. +- `skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md` — file list + the snippet tells consuming projects to add to their own CLAUDE.md: + rename the `OUTSTANDING_ITEMS.md` line to `BACKLOG.md` and add a new + line for `ROADMAP.md`. +- `.claude-plugin/plugin.json` — `description` field (four docs → five). + Commands are not enumerated in this file today, so no command-surface + change needed here. +- `README.md` — file list / command list sections. +- `CHANGELOG.md` — new entry for this version. +- `.session-continuity/OUTSTANDING_ITEMS.md` (this repo's own instance) — + migrated via the same primer.md logic (dogfooding — see Rollout). + +New: + +- `skills/session-continuity/templates/ROADMAP.md` — new stub template. +- `commands/help.md` — new command. + +## BACKLOG.md — rename details + +Content is a straight carry-over from `OUTSTANDING_ITEMS.md`: same rules +(permanent numbering, delete-on-close, grep-before-delete, title + 1-3 +sentence cap, link-out for anything longer). Only the heading ("Outstanding +Items — {{PROJECT_NAME}}" → "Backlog — {{PROJECT_NAME}}"), the placeholder +token (`{{OUTSTANDING_ITEMS}}` → `{{BACKLOG}}`), and the "not bugs... not +current state" framing sentence (unchanged in substance, just renamed) +change. + +## ROADMAP.md — new stub template + +```markdown +# Roadmap — {{PROJECT_NAME}} + +Strategic direction — where this project is headed, not the tactical +queue (that's `.session-continuity/BACKLOG.md`). Freeform: no numbering, +no permanence rules, no length cap. Rewrite sections wholesale as +direction changes; this file's history lives in git, not in careful +edits. + +## Now + +{{ROADMAP_NOW}} + +## Next + +{{ROADMAP_NEXT}} + +## Later + +{{ROADMAP_LATER}} +``` + +Init mode (`/session-continuity:primer`, Step 2) creates this file +alongside the other four, same placeholder-to-`TBD` fallback rule as every +other template field. Not required reading every session — `SKILL.md`'s +"quick start" sequence stays primer → project_context → backlog → +learnings; roadmap is consulted when direction, not day-to-day state, is +in question. + +## Migration — primer.md Step 3c (new) + +Runs whenever `BACKLOG.md` doesn't exist AND `OUTSTANDING_ITEMS.md` does +(the existing Step 3b migration — inline-heading-to-file — has already +happened or doesn't apply; Step 3c is strictly the file-rename, one level +up). Detection added to primer.md's Step 1 gather block: + +```bash +[ -f .session-continuity/BACKLOG.md ] && echo "BACKLOG_EXISTS=1" || echo "BACKLOG_EXISTS=0" +[ -f .session-continuity/ROADMAP.md ] && echo "ROADMAP_EXISTS=1" || echo "ROADMAP_EXISTS=0" +``` + +Sequencing rule (mirrors Step 3b's own sequencing note): if the primer is +also unsplit or has inline outstanding items, run Steps 3/3b to completion +first, then 3c — the migrations touch content that must exist in its +final (post-3b) shape before the straight rename happens. + +Step 3c body: + +1. `git mv .session-continuity/OUTSTANDING_ITEMS.md .session-continuity/BACKLOG.md`. +2. Rewrite the moved file's heading (`# Outstanding Items — X` → `# Backlog + — X`) and the "not bugs... not current state" framing sentence's file + reference — content and item numbers otherwise untouched. +3. Rewrite every reference to `OUTSTANDING_ITEMS.md` inside + `.session-continuity/SESSION_PRIMER.md` (if any remain post-3b) to + `BACKLOG.md`. +4. If `.session-continuity/ROADMAP.md` doesn't exist, create it from the + template with `{{ROADMAP_NOW/NEXT/LATER}}` set to `TBD` (no interactive + prompt — stub only. Bundled into this same step so the rename and the + stub land as one migration event/commit, not two separate ones). +5. Stage all touched/new files: + `git add .session-continuity/BACKLOG.md .session-continuity/ROADMAP.md .session-continuity/SESSION_PRIMER.md` + (only add SESSION_PRIMER.md if step 3 actually changed it). +6. Tell the user: "Migrated `.session-continuity/OUTSTANDING_ITEMS.md` → + `BACKLOG.md` (N items, numbers preserved) and stubbed in + `.session-continuity/ROADMAP.md`. Both staged — review before + committing." +7. Fall through to whichever of refresh mode or check mode applies next, + same fall-through convention as Steps 3 and 3b. + +**Do not commit automatically.** Staging only — same rule as every other +split/migration step in this command. + +### session-start.sh — new elif branch + +Add a branch to the existing `if/elif/else` chain (currently: BACKLOG-file +path exists → read counts; elif old inline heading present → warn to +migrate; else → zero/empty) so a project with `OUTSTANDING_ITEMS.md` but +no `BACKLOG.md` yet gets the same "migrate now" nudge the inline-heading +case already gets, rather than silently reporting zero backlog items. + +## /session-continuity:help — command design + +`commands/help.md`, frontmatter description: "Explain what this plugin +does, why, and what each `.session-continuity/` file is for. Zero args, +read-only, no state mutation." + +Structure: + +1. **One Bash line** (parse installed version): + ```bash + grep -m1 '"version"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || echo "version unknown (vendored install)" + ``` +2. **Static prose**, assembled by Claude from the command file's own + content (not re-derived per run — this is fixed reference text, unlike + doctor's live probes): + - **What this is** — one paragraph, from `plugin.json`'s description + line, expanded slightly: cross-session memory for Claude Code + projects via five in-repo docs. + - **Why** — the handoff problem: a fresh session (or a fresh Claude + instance) has no memory of prior sessions; these files are the + mechanism that survives a `/clear`, a new terminal, a new day. + - **The five files**, one paragraph each: `SESSION_PRIMER.md` + (volatile, current state, refreshed alongside substantive commits), + `PROJECT_CONTEXT.md` (stable, changes rarely), `BACKLOG.md` (tactical, + deferred work, permanently numbered), `ROADMAP.md` (strategic + direction, freeform, no numbering), `LEARNINGS.md` (durable wisdom, + append-only, numbered). + - **Commands** — list of all six (soon seven) `/session-continuity:*` + commands with a one-line purpose each, pulled from each command's own + frontmatter `description` rather than hand-duplicated prose (reduces + drift risk — if a command's description changes, help's list is + regenerated from source, not maintained by hand in two places). +3. No file writes, no git operations. Matches doctor's "never mutates + anything" note verbatim. + +## Rollout + +- Branch: `feature/backlog-roadmap-help` off `main`. +- Version bump: 0.21.1 → 0.22.0 (minor — new command + new file type is a + visible behavior addition, not a patch). +- `CHANGELOG.md` entry under the new version. +- This repo's own `.session-continuity/OUTSTANDING_ITEMS.md` is migrated + by running the updated `/session-continuity:primer` against this repo as + part of the same PR — proves the migration path works before it ships to + any other consumer, and leaves this repo in the same five-file shape it + will tell other projects to adopt. +- PR against `main` once tests/docs pass and the primer/backlog/roadmap + files in this repo reflect the change. + +## Open questions + +None — all three decision points (migration behavior, ROADMAP shape, +help command staticness) were resolved during brainstorming; recommended +options accepted in each case. diff --git a/skills/session-continuity/REFERENCE.md b/skills/session-continuity/REFERENCE.md index b343e39..6a2d319 100644 --- a/skills/session-continuity/REFERENCE.md +++ b/skills/session-continuity/REFERENCE.md @@ -2,14 +2,14 @@ Detail split out of `SKILL.md` to keep the skill itself a short operational quick-ref. Read this when you need gate internals, customization guidance, -the full decision tree, or the philosophy behind the four-file pattern — +the full decision tree, or the philosophy behind the five-file pattern — not on every session. ## Hooks and content gates `hooks/hooks.json` wires up several non-blocking and blocking hooks: -- **`session-start.sh`** (SessionStart) — reminds Claude to read the primer, and injects the outstanding-items shortlist. **Standing rule: whenever you discuss or echo outstanding items to the user — in this reminder, in `/session-continuity:end-session`'s prompts, or in free-form chat when directly asked — render them as a numbered list matching OUTSTANDING_ITEMS.md's own item numbers, always starting at 1, never 0.** Paraphrasing the list into unnumbered prose (e.g. "same question stand: X or Y") drops the numbering the user relies on to reply with a bare number. This applies even to a one-line summary reply — number it, don't collapse it, and don't zero-index it. +- **`session-start.sh`** (SessionStart) — reminds Claude to read the primer, and injects the backlog shortlist. **Standing rule: whenever you discuss or echo backlog to the user — in this reminder, in `/session-continuity:end-session`'s prompts, or in free-form chat when directly asked — render them as a numbered list matching BACKLOG.md's own item numbers, always starting at 1, never 0.** Paraphrasing the list into unnumbered prose (e.g. "same question stand: X or Y") drops the numbering the user relies on to reply with a bare number. This applies even to a one-line summary reply — number it, don't collapse it, and don't zero-index it. - **`pre-commit-check.sh`** (PreToolUse, before `git commit`) — non-blocking nudge when code is staged without a primer refresh. - **`learnings-surface.sh`** (PreToolUse, before Bash/Write/Edit) — the retrieval hook: surfaces any LEARNINGS entry carrying a `Trigger: <tool> /<regex>/` line when the imminent action matches, so the lesson lands *before* the mistake instead of after. @@ -51,7 +51,7 @@ say so instead of asserting it. | Observation | Where it goes | |---|---| | "The latest commit is X" | `.session-continuity/SESSION_PRIMER.md` → Current state | -| "We should follow up on X" | `.session-continuity/OUTSTANDING_ITEMS.md` → new numbered entry | +| "We should follow up on X" | `.session-continuity/BACKLOG.md` → new numbered entry | | "How is this repo laid out" | `.session-continuity/PROJECT_CONTEXT.md` → Repo layout | | "What are our workflow conventions" | `.session-continuity/PROJECT_CONTEXT.md` → Workflow conventions | | "Bun replaces the CA trust store" | `.session-continuity/LEARNINGS.md` → new numbered entry | @@ -72,15 +72,15 @@ Different projects have different shapes, but the core file pattern adapts well: - **Test counts in the primer.** If you have one package, one line. If you have three packages (like SF_Tunnel: relay, tunnel, web), show three. If counts are unstable (integration tests that depend on external services), drop the exact count and document the green command instead. - **"Workflow conventions" section.** Replace with whatever this project's disciplines are: commit message format, branch naming, code review process, required CI checks. -- **"Outstanding items" section.** Use your own taxonomy: "blocked", "deferred", "needs decision". Keep it actionable. +- **"Backlog" section.** Use your own taxonomy: "blocked", "deferred", "needs decision". Keep it actionable. - **LEARNINGS section headings.** Replace "Bun", "SvelteKit", etc. with the actual layers of the project. Stack varies, structure is universal. ## For team-wide use If multiple people are working on the same project and should all benefit from this: -1. All four files are **checked-in** artifacts, not gitignored. Commit them in the project repo under `.session-continuity/`. -2. Copy [`templates/CLAUDE_MD_SNIPPET.md`](templates/CLAUDE_MD_SNIPPET.md) into the project's `CLAUDE.md` verbatim. It covers the read-first pointer, the primer-refresh-alongside-commits rule, the outstanding-item verify-before-close rule, and the gate-chain-commit trap — the things a project otherwise has to rediscover and hand-write for itself (as architect-workbench did before this snippet existed). +1. All five files are **checked-in** artifacts, not gitignored. Commit them in the project repo under `.session-continuity/`. +2. Copy [`templates/CLAUDE_MD_SNIPPET.md`](templates/CLAUDE_MD_SNIPPET.md) into the project's `CLAUDE.md` verbatim. It covers the read-first pointer, the primer-refresh-alongside-commits rule, the backlog-item verify-before-close rule, and the gate-chain-commit trap — the things a project otherwise has to rediscover and hand-write for itself (as architect-workbench did before this snippet existed). 3. Document the maintenance rules in the primer itself (last section). Templates include this. 4. Human teammates benefit too — LEARNINGS.md doubles as a living post-mortem log, and the primer is a great onboarding handoff. @@ -98,11 +98,12 @@ If multiple people are working on the same project and should all benefit from t ## Philosophy -The four files answer four different questions: +The five files answer five different questions: - Primer: "What is true about this project **right now**?" -- OUTSTANDING_ITEMS: "What has been **explicitly deferred** (decisions, follow-ups, follow-ons) that we should not forget?" +- BACKLOG: "What has been **explicitly deferred** (decisions, follow-ups, follow-ons) that we should not forget?" +- ROADMAP: "Where is this headed, independent of what's in the tactical queue?" - PROJECT_CONTEXT: "What is true about this project **generally**, and rarely changes?" - LEARNINGS: "What should I know to avoid rediscovering something painful?" -Together they compress the cost of session handoff from "re-explain everything" to "read a couple of files." The primer stays short (a shortlist, not a snapshot); OUTSTANDING_ITEMS accumulates deferred work; PROJECT_CONTEXT and LEARNINGS both grow organically but at different rates — one when the project's shape changes, the other with every hard-won bug. All four outlive any single session. +Together they compress the cost of session handoff from "re-explain everything" to "read a couple of files." The primer stays short (a shortlist, not a snapshot); BACKLOG accumulates deferred work; ROADMAP holds direction independent of the tactical queue; PROJECT_CONTEXT and LEARNINGS both grow organically but at different rates — one when the project's shape changes, the other with every hard-won bug. All five outlive any single session. diff --git a/skills/session-continuity/SKILL.md b/skills/session-continuity/SKILL.md index 5ac74e8..ee04acb 100644 --- a/skills/session-continuity/SKILL.md +++ b/skills/session-continuity/SKILL.md @@ -1,20 +1,21 @@ --- name: session-continuity -description: Establish and maintain cross-session memory for a project via four in-repo docs — .session-continuity/SESSION_PRIMER.md (current state, refreshed alongside substantive commits), .session-continuity/OUTSTANDING_ITEMS.md (explicitly deferred work), .session-continuity/PROJECT_CONTEXT.md (stable repo context, changes rarely), and .session-continuity/LEARNINGS.md (append-only wisdom for 15+ min bugs). Use when starting, before commits, or after hard-won bugs. +description: Establish and maintain cross-session memory for a project via five in-repo docs — .session-continuity/SESSION_PRIMER.md (current state, refreshed alongside substantive commits), .session-continuity/BACKLOG.md (explicitly deferred work), .session-continuity/ROADMAP.md (strategic direction), .session-continuity/PROJECT_CONTEXT.md (stable repo context, changes rarely), and .session-continuity/LEARNINGS.md (append-only wisdom for 15+ min bugs). Use when starting, before commits, or after hard-won bugs. --- # Session Continuity -Four in-repo files act as a handoff between Claude sessions on the same project: +Five in-repo files act as a handoff between Claude sessions on the same project: - **`.session-continuity/SESSION_PRIMER.md`** — current-state snapshot (latest commits, working state). **Refresh alongside substantive commits** (stage the update in the same commit as the real change). Always reflects "what's true right now." -- **`.session-continuity/OUTSTANDING_ITEMS.md`** — backlog of explicitly deferred follow-ups and decisions (not bugs, not current state). Permanent numbering (delete-on-close, never renumber, never reuse a number), title + 1-3 sentence length cap per item — anything longer moves to a linked file under `meta/superpowers/`. +- **`.session-continuity/BACKLOG.md`** — explicitly deferred follow-ups and decisions (not bugs, not current state). Permanent numbering (delete-on-close, never renumber, never reuse a number), title + 1-3 sentence length cap per item — anything longer moves to a linked file under `meta/superpowers/`. +- **`.session-continuity/ROADMAP.md`** — strategic direction: Now/Next/Later. Freeform — no numbering, no permanence rules, no length cap. Rewritten wholesale as direction changes. - **`.session-continuity/PROJECT_CONTEXT.md`** — stable repo context (layout, module table, workflow conventions, test expectations, "where to look for what"). Changes rarely — only when the project's shape itself changes. - **`.session-continuity/LEARNINGS.md`** — accumulated wisdom (numbered entries, grouped by layer). Append-only log of bugs that were painful enough to not want to rediscover. **Update when a bug takes 15+ minutes to diagnose.** -The four files are complementary: primer is volatile current-state, OUTSTANDING_ITEMS captures explicitly deferred work, PROJECT_CONTEXT is stable reference, LEARNINGS is durable wisdom. A fresh session reads the primer first to get oriented, skims PROJECT_CONTEXT once per session for the shape of the repo, consults OUTSTANDING_ITEMS for the decision backlog, then consults LEARNINGS when something surprising happens. +The five files are complementary: primer is volatile current-state, BACKLOG captures explicitly deferred work, ROADMAP captures strategic direction, PROJECT_CONTEXT is stable reference, LEARNINGS is durable wisdom. A fresh session reads the primer first to get oriented, skims PROJECT_CONTEXT once per session for the shape of the repo, consults BACKLOG for the decision backlog, then consults LEARNINGS when something surprising happens. -If installed as a plugin, six commands are available: `/session-continuity:primer` (init/split/refresh/check the primer), `/session-continuity:learning` (append a new LEARNINGS entry interactively), `/session-continuity:end-session` (close-out ritual — refresh the primer, capture any new learnings from this session, and report a ✓/⚠️ checklist before you close the laptop), `/session-continuity:spike-check` (force a spike to be designed against the real load-bearing path before it's built), `/session-continuity:doctor` (read-only diagnostic — is the install actually wired up: hooks registered, all four files present and not stale, plugin root resolved and not a stale cache, gate scripts executable), and `/session-continuity:update` (print the commands to pull and activate the plugin's latest published version). +If installed as a plugin, seven commands are available: `/session-continuity:primer` (init/split/refresh/check the primer), `/session-continuity:learning` (append a new LEARNINGS entry interactively), `/session-continuity:end-session` (close-out ritual — refresh the primer, capture any new learnings from this session, and report a ✓/⚠️ checklist before you close the laptop), `/session-continuity:spike-check` (force a spike to be designed against the real load-bearing path before it's built), `/session-continuity:doctor` (read-only diagnostic — is the install actually wired up: hooks registered, all five files present and not stale, plugin root resolved and not a stale cache, gate scripts executable), `/session-continuity:update` (print the commands to pull and activate the plugin's latest published version), and `/session-continuity:help` (explain what the plugin does and what each file is for). `hooks/hooks.json` also wires up several non-blocking and blocking hooks — a SessionStart reminder that injects the outstanding-items shortlist, @@ -48,18 +49,18 @@ first time a chained add+commit gets denied. Invoke when: - Starting work on a project that does not yet have `.session-continuity/SESSION_PRIMER.md`, `.session-continuity/PROJECT_CONTEXT.md`, and `.session-continuity/LEARNINGS.md` — initialize from the templates. -- About to commit code changes — refresh the primer's "Current state" section and `.session-continuity/OUTSTANDING_ITEMS.md` so the next session sees the truth. +- About to commit code changes — refresh the primer's "Current state" section and `.session-continuity/BACKLOG.md` so the next session sees the truth. - A bug has just been resolved after significant effort (15+ min, or required reading unfamiliar code, or surprised you) — add a LEARNINGS entry. - The user says something like "help me preserve session memory," "how do I hand this off to the next session," "create a primer," or "add this to learnings." - Picking up work on a project that already has these files — read them as the first step, before touching anything else. ## Quick start (new project) -Run `/session-continuity:primer`. The command detects that no primer exists, copies all four templates from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/` into the project's `.session-continuity/`, fills in every placeholder it can derive automatically (project name, latest commits, working directory, test command), prompts the user for anything left blank, and stages all four files. It does not commit. +Run `/session-continuity:primer`. The command detects that no primer exists, copies all five templates from `${CLAUDE_PLUGIN_ROOT}/skills/session-continuity/templates/` into the project's `.session-continuity/`, fills in every placeholder it can derive automatically (project name, latest commits, working directory, test command), prompts the user for anything left blank, and stages all five files. It does not commit. After the user commits, remind them of the two maintenance rules: refresh the primer alongside substantive commits (stage the refresh in the same commit as the real change — do not commit the primer by itself), and add a LEARNINGS entry for every bug that took 15+ minutes to diagnose. -If the `/session-continuity:primer` command is not installed (e.g. this skill was vendored manually, not installed as a plugin), fall back to copying the templates by hand from [`templates/SESSION_PRIMER.md`](templates/SESSION_PRIMER.md), [`templates/OUTSTANDING_ITEMS.md`](templates/OUTSTANDING_ITEMS.md), [`templates/PROJECT_CONTEXT.md`](templates/PROJECT_CONTEXT.md), and [`templates/LEARNINGS.md`](templates/LEARNINGS.md) into the project's `.session-continuity/`, filling placeholders, and committing the set. +If the `/session-continuity:primer` command is not installed (e.g. this skill was vendored manually, not installed as a plugin), fall back to copying the templates by hand from [`templates/SESSION_PRIMER.md`](templates/SESSION_PRIMER.md), [`templates/BACKLOG.md`](templates/BACKLOG.md), [`templates/ROADMAP.md`](templates/ROADMAP.md), [`templates/PROJECT_CONTEXT.md`](templates/PROJECT_CONTEXT.md), and [`templates/LEARNINGS.md`](templates/LEARNINGS.md) into the project's `.session-continuity/`, filling placeholders, and committing the set. ## Quick start (existing project with these files) @@ -93,7 +94,7 @@ Sections of the primer most likely to be stale: Other sections (layout, packages, conventions) drift more slowly but are fair game if the repo shifted. Alongside the primer, also update the separate file -`.session-continuity/OUTSTANDING_ITEMS.md`: remove things you just +`.session-continuity/BACKLOG.md`: remove things you just finished, add newly-flagged follow-ups from code review or user feedback. **Before marking any item DONE, verify it against the actual code** — one grep or read per load-bearing claim, not against memory @@ -102,7 +103,7 @@ mentions an item's keywords does not prove the item shipped; a fix landing inside an unrelated commit can leave an item reading OPEN when it already shipped. Both directions are real drift. -**Numbering convention for OUTSTANDING_ITEMS.md — mirrors LEARNINGS.** +**Numbering convention for BACKLOG.md — mirrors LEARNINGS.** A new item takes the next unused number across the whole file. A closed item is deleted outright, never renumbered, never reused — this keeps cross-references ("see item 4") valid for as long as item 4 exists. @@ -167,4 +168,4 @@ A bug qualifies when any of: For the full gate/hook reference, the "what goes where" decision tree, customization guidance, team-wide rollout steps, red flags for when *not* to use this skill, complementary mechanisms, and the philosophy -behind the four-file split, see [`REFERENCE.md`](REFERENCE.md). +behind the five-file split, see [`REFERENCE.md`](REFERENCE.md). diff --git a/skills/session-continuity/templates/OUTSTANDING_ITEMS.md b/skills/session-continuity/templates/BACKLOG.md similarity index 90% rename from skills/session-continuity/templates/OUTSTANDING_ITEMS.md rename to skills/session-continuity/templates/BACKLOG.md index b0c94a0..32a3588 100644 --- a/skills/session-continuity/templates/OUTSTANDING_ITEMS.md +++ b/skills/session-continuity/templates/BACKLOG.md @@ -1,6 +1,6 @@ -# Outstanding Items — {{PROJECT_NAME}} +# Backlog — {{PROJECT_NAME}} -Backlog of explicitly deferred follow-ups and decisions — not bugs (those +Explicitly deferred follow-ups and decisions — not bugs (those go in `.session-continuity/LEARNINGS.md`), not current state (that's `.session-continuity/SESSION_PRIMER.md`). An item lives here from the moment it's flagged until the moment the code proves it resolved, then @@ -20,7 +20,7 @@ design sketch, an invariant, or a rejected-alternatives discussion, put that in a spec under `meta/superpowers/...` and link it here — this file stays a scannable list, not a second spec repository. -{{OUTSTANDING_ITEMS}} +{{BACKLOG}} <!-- Example: ### 1. `/session-continuity:doctor` command diff --git a/skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md b/skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md index 34e7287..3eb9483 100644 --- a/skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md +++ b/skills/session-continuity/templates/CLAUDE_MD_SNIPPET.md @@ -11,15 +11,16 @@ Before touching anything, read `.session-continuity/SESSION_PRIMER.md` (current state) and `.session-continuity/LEARNINGS.md` (bugs that were expensive to diagnose — grep it when something surprises you). Read `.session-continuity/PROJECT_CONTEXT.md` once per session for stable repo -shape, and `.session-continuity/OUTSTANDING_ITEMS.md` for the backlog of -deferred decisions and follow-ups; both change rarely. +shape, `.session-continuity/BACKLOG.md` for deferred decisions and +follow-ups, and `.session-continuity/ROADMAP.md` for strategic direction; +all three change rarely. **Refresh the primer alongside substantive commits.** Stage the update in the same commit as the real change — never a primer-only commit (exceptions: a one-shot catch-up, correcting a factual error, or recording a just-shipped release). When a bug takes 15+ minutes to diagnose, append a LEARNINGS entry. -**Before marking any outstanding item DONE, verify it against the actual +**Before marking any backlog item DONE, verify it against the actual code** — one grep or read per load-bearing claim, not memory and not a commit-subject keyword match alone. A commit whose subject mentions an item's keywords does not prove it shipped; a fix landing inside an unrelated diff --git a/skills/session-continuity/templates/ROADMAP.md b/skills/session-continuity/templates/ROADMAP.md new file mode 100644 index 0000000..8467a47 --- /dev/null +++ b/skills/session-continuity/templates/ROADMAP.md @@ -0,0 +1,19 @@ +# Roadmap — {{PROJECT_NAME}} + +Strategic direction — where this project is headed, not the tactical +queue (that's `.session-continuity/BACKLOG.md`). Freeform: no numbering, +no permanence rules, no length cap. Rewrite sections wholesale as +direction changes; this file's history lives in git, not in careful +edits. + +## Now + +{{ROADMAP_NOW}} + +## Next + +{{ROADMAP_NEXT}} + +## Later + +{{ROADMAP_LATER}} diff --git a/skills/session-continuity/templates/SESSION_PRIMER.md b/skills/session-continuity/templates/SESSION_PRIMER.md index c645741..ec4afef 100644 --- a/skills/session-continuity/templates/SESSION_PRIMER.md +++ b/skills/session-continuity/templates/SESSION_PRIMER.md @@ -5,7 +5,8 @@ file is the shortest path to what changed recently. For stable repo context (layout, conventions, modules), read `.session-continuity/PROJECT_CONTEXT.md` once per session — it changes rarely. For the backlog of deferred decisions and follow-ups, read -`.session-continuity/OUTSTANDING_ITEMS.md`. +`.session-continuity/BACKLOG.md`; for strategic direction, read +`.session-continuity/ROADMAP.md`. ## First things first (read these before touching anything)