diff --git a/plugins/ultraplan-local/.gitignore b/plugins/ultraplan-local/.gitignore index e28a372..8570495 100644 --- a/plugins/ultraplan-local/.gitignore +++ b/plugins/ultraplan-local/.gitignore @@ -15,3 +15,8 @@ Desktop.ini REMEMBER.md TODO.md ROADMAP.md + +# Local planning docs (briefs, design notes, observations) — never committed. +# Existing tracked files in docs/ predate this rule; new planning docs stay local. +docs/ultracontinue-brief.md +docs/ultracontinue-design-notes.md diff --git a/plugins/ultraplan-local/docs/ultracontinue-brief.md b/plugins/ultraplan-local/docs/ultracontinue-brief.md deleted file mode 100644 index eae952e..0000000 --- a/plugins/ultraplan-local/docs/ultracontinue-brief.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -type: ultrabrief -brief_version: 2.0 -created: 2026-05-01 -task: "Add /ultracontinue command for zero-friction multi-session resumption" -slug: ultracontinue -project_dir: .claude/projects/2026-05-01-ultracontinue/ -research_topics: 3 -research_status: pending -auto_research: false -interview_turns: 0 -source: manual ---- - -# Task: `/ultracontinue` — Zero-Friction Multi-Session Resumption - -> Drafted manually 2026-05-01 from KTG/Claude design dialogue after the -> config-audit v5.0.0 release run (5 sessions, ~40 turns of `NEXT-SESSION-PROMPT.local.md` -> handoffs). Brief follows the `/ultrabrief-local` template for consistency -> with the rest of the ultraplan-local pipeline, but was not produced through -> the interview — it is a hand-written design brief. `/ultraplan-local` should -> still be able to consume it. - -## Intent - -Multi-session execution today (e.g. config-audit v5.0.0's 5-session release run) requires KTG to manually maintain a `NEXT-SESSION-PROMPT.local.md` at the end of every session and copy-paste its contents into the next fresh Claude Code session. This works but adds two friction points per session: (1) at session-end, decide what context the next session needs and write it; (2) at session-start, locate the file and paste it. Across a 5-session run that's 10 manual context-handover steps, each prone to omission, copy errors, or stale state. The `NEXT-SESSION-PROMPT.local.md` convention is captured in KTG's auto-memory as `feedback_session_handoff_prompt.md` but is not formalized in any tool — it lives entirely in operator discipline. - -The opportunity: a single command, identical across all projects, that bootstraps the next session with zero thinking. KTG starts a fresh Claude session, types `/ultracontinue`, and the right context loads. End of friction. - -## Goal - -A new `/ultracontinue` command in the `ultraplan-local` plugin that reads a per-project state file (`.claude/projects//.session-state.local.json`), shows a 3-line summary (project, next-session label, brief path), and immediately begins executing the next session. Works whether the previous session was driven by `/ultraexecute-local` (formal pipeline) or executed manually turn-by-turn (informal pipeline like the v5.0.0 release run). The state file is the contract — any session-end mechanism may write to it, and `/ultracontinue` only reads. - -## Non-Goals - -- **Replace `/ultraexecute-local --resume`.** That flag resumes a SINGLE session from a `progress.json` checkpoint after a crash. `/ultracontinue` advances to the NEXT session in a multi-session plan. They are complementary, not overlapping. -- **Replace `graceful-handoff`.** That plugin solves context-budget rescue (dump state when current session approaches its token limit). `/ultracontinue` solves planned multi-session continuation. They MAY share the state-file convention as a consistency win, but `/ultracontinue` must work standalone without `graceful-handoff` installed. -- **Auto-orchestrate the entire multi-session run from one command.** `/ultracontinue` advances ONE session per invocation. Running 5 sessions back-to-back requires 5 invocations across 5 fresh Claude sessions (which is the point — context resets between them). -- **Replace `NEXT-SESSION-PROMPT.local.md` retroactively.** Existing projects mid-flight may keep using it. The new command works alongside it; migration is opt-in per project. -- **Build a session scheduler / cron / background runner.** Out of scope. KTG starts each session manually. - -## Constraints - -- **Per-project state file.** Path: `.claude/projects//.session-state.local.json`. Gitignored by default. No global state. -- **No hard dependency on `graceful-handoff`.** `/ultracontinue` must work in projects/repos where `graceful-handoff` is not installed. -- **Works for both formal and informal multi-session flows.** Formal = `/ultraexecute-local` writes the state file as part of its standard end-of-session contract. Informal = a tiny helper command (or KTG manually) writes the state file at end of a manual session series like the v5.0.0 release run. -- **Zero new external dependencies.** Plain `node:fs` JSON read. No npm packages. -- **Cross-platform.** Node `.mjs` script, no shell-isms; works on macOS / Linux / Windows. -- **Convention is documented in `docs/HANDOVER-CONTRACTS.md`** — same place as the brief/research/plan/progress.json contracts already live. The state file gets a sixth handover entry. - -## Preferences - -- **State file IS the contract.** `/ultracontinue` reads it; multiple writers can update it. Loose coupling > tight coupling to a specific writer. -- **Minimal state-file schema.** `project`, `next_session_brief_path`, `next_session_label`, `status`, `updated_at`. Everything else is optional metadata. -- **No interactive prompts in `/ultracontinue` startup.** Show summary, start. If KTG wants to abort, Ctrl+C. Per dialogue: "ingen prompts, men la informasjon synes". -- **Match existing ultraplan-local skill structure.** New command file at `commands/ultracontinue-local.md`, no agents needed (deterministic file read), follow existing frontmatter conventions. -- **Match existing handover-validator pattern.** Add `lib/validators/session-state-validator.mjs` for the new contract; CLI returns `{valid, errors[], warnings[], parsed}`. - -## Non-Functional Requirements - -- **Cold-start latency: < 500ms** from `/ultracontinue` invocation to "begin executing session" output. -- **Failure mode is obvious.** Missing state file → tell user "no active multi-session project here; start with `/ultrabrief-local` or `/ultraplan-local`". Malformed state file → tell user the validation error and where to fix it. -- **Idempotent.** Running `/ultracontinue` twice in the same session does not advance state. State only advances when the SESSION completes (writer's responsibility). -- **Self-documenting.** First-time user can `/ultracontinue --help` and understand the model without reading other docs. -- **Zero secrets in the state file.** Status, paths, labels — never API keys, never user content beyond filenames. - -## Success Criteria - -Falsifiable, command-checkable: - -- **SC-1:** A new project with `.claude/projects//.session-state.local.json` containing the documented schema can be resumed via `/ultracontinue` from a fresh Claude session, and the correct brief loads. Verified by running the command in a fixture project and asserting the loaded content. -- **SC-2:** `/ultracontinue` invoked in a directory with no state file emits a helpful message (not a stack trace) pointing at `/ultrabrief-local` / `/ultraplan-local` as the entry points. Verified: exit cleanly with informative stderr. -- **SC-3:** The session-state-validator CLI exists at `lib/validators/session-state-validator.mjs` and returns `{valid:true, errors:[], warnings:[], parsed:{...}}` for a well-formed file; structured errors with stable codes for malformed files. Verified via fixture-backed tests. -- **SC-4:** `/ultraexecute-local` writes the state file at end-of-session — both for explicit session-spec runs (`--session N`) and for formal session-strategy plans. Verified: after a session completes, `.session-state.local.json` exists and points at next session. (May land in a follow-up step if it requires significant ultraexecute restructure.) -- **SC-5:** A `/ultraplan-local end-session` (or equivalent) helper exists for INFORMAL multi-session flows like the v5.0.0 release run — single command writes the state file pointing at the next session brief. Verified: invocation produces a valid state file the validator accepts. -- **SC-6:** `docs/HANDOVER-CONTRACTS.md` has a "Handover 6 — `.session-state.local.json`" entry with producer, consumer, path conventions, schema, body invariants, validation strategy, versioning, and failure modes. Verified: file exists with the section heading. -- **SC-7:** Plugin `README.md`, `CLAUDE.md`, and root marketplace `README.md` document `/ultracontinue` in command tables. Verified: grep finds the command name in all three. -- **SC-8:** Cross-project consistency: running `/ultracontinue` in two different projects (config-audit-style and any greenfield project) shows identical output structure (project / next-session-label / brief-path / "Begin?"-equivalent narration). Verified by manual diff or fixture-based test. -- **SC-9:** Tests: at least 1 unit test for the validator, 1 integration test for the command's load+narrate flow, 1 negative test (missing file), 1 negative test (malformed file). Plugin's `node --test 'tests/**/*.test.mjs'` stays green. -- **SC-10:** No new external dependencies in `package.json` or any new `node_modules/` directory created by this work. Verified: `git diff package.json` shows no `dependencies` change; `find . -name node_modules -not -path '*/tests/fixtures/*'` returns no new entries. - -## Research Plan - -Three research topics. Topics 1 and 2 are local (codebase-only); topic 3 is light external (verify Anthropic / Claude Code conventions). - -### Topic 1: `/ultraexecute-local` end-of-session integration depth - -- **Why this matters:** Per dialogue: "ultraexecute-local må være 100% konsekvent for hvordan den fullfører hver eneste sesjon". The state file's reliability depends on EVERY session-end path writing it. This research scopes how invasive that change is. -- **Research question:** "Where in `commands/ultraexecute-local.md` does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across (a) successful session, (b) failed session with manual abort, (c) compaction-survival recovery, (d) `--session N` explicit single-session runs?" -- **Suggested invocation:** `/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Where in ultraexecute-local does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across all session-end paths?"` -- **Required for plan steps:** ultraexecute-local code edits; failure-mode handling; whether SC-4 lands in v1.0 or follow-up -- **Confidence needed:** high -- **Estimated cost:** standard — agent swarm -- **Scope hint:** local - -### Topic 2: `graceful-handoff` plugin alignment - -- **Why this matters:** The two plugins solve adjacent problems and SHOULD share the state-file convention without making `graceful-handoff` a hard dep. This research determines whether `graceful-handoff` writes a similar file today, what schema it uses, and whether convergence is one-sided (graceful-handoff adopts ultraplan's schema) or mutual (both align on a v1 schema co-published in ultraplan-local). -- **Research question:** "Does `graceful-handoff` already produce a session-state file, what is its schema, and what is the minimum-friction path to make it write to the same `.session-state.local.json` convention without imposing a hard dependency from `/ultracontinue` on `graceful-handoff`?" -- **Suggested invocation:** `/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Does graceful-handoff produce a session-state file? What schema? Convergence path?"` -- **Required for plan steps:** SC-5 helper command design; whether `graceful-handoff` gets a docs note in its README pointing at the convention -- **Confidence needed:** medium -- **Estimated cost:** quick — inline research -- **Scope hint:** local (both plugins are in this repo) - -### Topic 3: Claude Code slash-command conventions for read+execute commands - -- **Why this matters:** `/ultracontinue` reads state then immediately starts work. We need to verify that this pattern (no `AskUserQuestion`, just narrate-and-go) matches Claude Code's UX expectations and doesn't trip any guardrails (e.g. auto-approval behavior in plan mode, hook ordering, allowed-tools list for the slash command). -- **Research question:** "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation, and what `allowed-tools` / `model` / frontmatter pattern do similar commands use?" -- **Suggested invocation:** `/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --external "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation?"` -- **Required for plan steps:** `commands/ultracontinue-local.md` frontmatter + behavior section -- **Confidence needed:** medium -- **Estimated cost:** quick — docs lookup -- **Scope hint:** external - -## Open Questions / Assumptions - -- **[ASSUMPTION]** State-file format `.session-state.local.json` is JSON, not YAML — matches `progress.json` convention from ultraplan-local. Could be YAML for human-edit-friendliness, but JSON has mechanical-validator advantages and parity with existing `progress.json`. -- **[ASSUMPTION]** State file is gitignored via the existing `*.local.*` pattern (already in most plugin `.gitignore` files including config-audit). No new gitignore entry needed. -- **[QUESTION]** Should `/ultracontinue` accept an optional `` arg for projects not at the cwd? Default is "find `.claude/projects/<...>/.session-state.local.json` reachable from cwd". Argument override = nice-to-have. -- **[QUESTION]** Should the state file track ALL completed sessions (history), or just last + next? Minimal contract = last + next. History is metadata that can grow as needed without breaking compat. -- **[QUESTION]** Naming — `/ultracontinue` vs `/ultraplan-local continue` vs `/continue`. KTG decision in dialogue: `/ultracontinue` for muscle-memory parity with the other ultra-prefixed commands. Plan should confirm no global Claude Code `/continue` builtin collides. -- **[QUESTION]** What's the upgrade path for projects that already have `NEXT-SESSION-PROMPT.local.md` (config-audit historical, ultraplan-local historical)? Backward compat = `/ultracontinue` could read either if state-file is missing. Or simpler: documented manual migration ("write a state file pointing at your existing NEXT-SESSION-PROMPT"). - -## Prior Attempts - -- **`NEXT-SESSION-PROMPT.local.md` manual convention.** Captured in KTG's auto-memory (`feedback_session_handoff_prompt.md` and `feedback_next_session_prompt_manual.md`). Used heavily in config-audit v5.0.0 release (5 sessions). Worked, but operator-driven — KTG must remember to invoke it at session-start AND write it at session-end. The auto-memory entry `feedback_next_session_prompt_manual.md` explicitly notes: "Ikke foreslå auto-loading via SessionStart/CLAUDE.md. Manuell invokasjon unngår stale-fil-risiko." This brief addresses the friction without re-introducing the stale-file risk: `/ultracontinue` is still operator-invoked, but the state file is mechanically validated and the load is deterministic. - -- **`/ultraexecute-local --session N` flag.** Already exists and works for HEADLESS / scripted multi-session runs via session specs. Does not address the INTERACTIVE multi-session case where each session is a fresh Claude Code chat. - -- **`graceful-handoff` plugin.** Solves a different problem (intra-session context-budget rescue). Pattern overlap exists; this brief proposes alignment without dependency. - -## Metadata - -- **Created:** 2026-05-01 -- **Interview turns:** 0 (manual brief from design dialogue) -- **Auto-research opted in:** no — research is suggested but KTG decides -- **Source:** manual - ---- - -## How to continue - -Manual (recommended for this brief — research is light and the planning happens once): - -```bash -# Run the three research topics (order does not matter): -/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Where in ultraexecute-local does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across all session-end paths?" -/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Does graceful-handoff produce a session-state file? What schema? Convergence path?" -/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --external "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation?" - -# Then plan: -/ultraplan-local --project .claude/projects/2026-05-01-ultracontinue - -# Then execute (likely 1-2 sessions; not large enough to need /ultracontinue itself): -/ultraexecute-local --project .claude/projects/2026-05-01-ultracontinue -``` - -Skip-research path (faster, lower confidence): `/ultraplan-local --brief plugins/ultraplan-local/docs/ultracontinue-brief.md` directly. Will ship `/ultracontinue` with assumptions noted and SC-4 (ultraexecute integration) likely deferred to follow-up. diff --git a/plugins/ultraplan-local/docs/ultracontinue-design-notes.md b/plugins/ultraplan-local/docs/ultracontinue-design-notes.md deleted file mode 100644 index f25b30a..0000000 --- a/plugins/ultraplan-local/docs/ultracontinue-design-notes.md +++ /dev/null @@ -1,117 +0,0 @@ -# `/ultracontinue` — Design Notes - -> **Companion to:** `ultracontinue-brief.md` (sibling file in this folder). -> **Captured:** 2026-05-01, end of config-audit v5.0.0 release session. -> **Purpose:** Preserve the dialogue rationale that shaped the brief so a -> fresh session (with no memory of the discussion) can plan + execute -> with full context. Read this AFTER the brief, not instead of it. - ---- - -## Why this work exists (origin) - -The brief was drafted immediately after shipping `config-audit v5.0.0` — a 5-session release run (alpha.1 → alpha.2 → beta.1 → rc.1 → release) executed across 5 fresh Claude Code sessions. Each session ended with KTG (or Claude on KTG's behalf) hand-writing a `NEXT-SESSION-PROMPT.local.md` file containing the canonical "paste this into the next session" prompt. Each session began with KTG manually reading + invoking that prompt. - -The pattern works (v5 shipped clean, 635 tests, SC-6b PASS at -0.85% delta) but is operator-driven: ~10 manual context-handover steps across the run, each a candidate for omission, copy errors, or stale-file risk. - -Initial Q from KTG: "Er det formalisert i ultraexecute-local at NEXT-SESSION-PROMPT.local.md er mekanismen for å lage en ny prompt til neste sesjon?" - -Investigation found: **No, it is not.** `NEXT-SESSION-PROMPT.local.md` references in the ultraplan-local plugin tree exist only in historical project artifacts (`.claude/projects/2026-04-18-v3.0-skill-factory-ekstraksjon/`). The convention lives in KTG's auto-memory (`feedback_session_handoff_prompt.md`, `feedback_next_session_prompt_manual.md`) — not in any tool. `/ultraexecute-local` has its own multi-session model via session specs (YAML manifests + `--session N` flag), but that's for scripted/headless runs, not interactive multi-session. - -KTG's framing of the goal: *"Jeg ønsker at det blir så enkelt å kjøre X antall sesjoner i sekvens slik at samme kommando kan kjøres for hver eneste sesjon for å redusere mental belastning, og jeg ønsker at dette blir likt mellom alle sesjoner."* - -That's the load-bearing constraint: **identical command, every session, every project.** - ---- - -## The key design insight - -The brief's Goal section reads "state-filen ER kontrakten" — that phrase came out of dialogue and is the load-bearing decision. - -Initial framing was "build a `/ultracontinue` skill that wraps a state-write helper". The problem with that framing: it ties the consistency promise to a specific writer. If `/ultraexecute-local` writes the state file but a manual session series (like the v5 release) doesn't, the convention is broken in the cases that matter most. - -Reframing: **the state file is the contract, not the writer.** `/ultracontinue` reads a documented JSON convention. ANY tool, helper command, or operator-driven session-end may write to it. Loose coupling. The convention is what's universal, not the integration depth into any one command. - -This shifts the work-shape from "build one big integration" to "(1) define the convention, (2) build the reader, (3) build writers wherever they make sense — including a tiny manual-session helper that doesn't require touching `/ultraexecute-local` at all". SC-4 (full ultraexecute integration) becomes optional/follow-up rather than a v1.0 blocker. - ---- - -## Decisions and alternatives - -### 1. Where does `/ultracontinue` live? - -**Decision:** `ultraplan-local` plugin. - -**Alternative considered:** `graceful-handoff` plugin (since it already deals with "save state, restart in new context"). - -**Reasoning:** graceful-handoff solves intra-session context-budget rescue (one project's session is hitting token limits, dump and restart). `/ultracontinue` solves planned multi-session execution (this is session 3 of 5 in a release run). Different problems sharing convention surface. ultraplan-local is the natural home because multi-session planning is part of its remit (see `--decompose`, session-spec template, `--session N` flag). - -KTG noted graceful-handoff "trenger det også for konsistens" — captured in brief as Topic 2 of the research plan. Convergence is desirable but not blocking; `/ultracontinue` must work standalone. - -### 2. State scope: per-project vs global - -**Decision:** Per-project. `.claude/projects//.session-state.local.json`. - -**Alternative considered:** `~/.claude/active-session.json` (one active project at a time, machine-global). - -**Reasoning:** KTG explicit: "Per prosjekt". Global has the same single-active-project assumption baked in but breaks if KTG context-switches. Per-project also matches existing ultraplan-local convention (briefs, plans, progress.json all live under `.claude/projects//`). - -### 3. UX: prompt before starting next session? - -**Decision:** No interactive prompt. Show 3-line summary (project / next-session-label / brief-path), then start executing. - -**Alternative considered:** Y/N prompt ("Run session 3 now?"). - -**Reasoning:** From dialogue: "Maksimalt brukervennlig = ingen prompts, men la informasjon synes." Y/N is friction. Information visibility matters; gating on confirmation does not. If KTG wants to abort, Ctrl+C. Brief codifies this in NFRs. - -### 4. State-file format: JSON vs YAML - -**Decision (assumption in brief):** JSON. - -**Reasoning:** Parity with `progress.json` already in ultraplan-local. Mechanical validator parity. Marked as `[ASSUMPTION]` so plan-critic / scope-guardian can flag if there's a strong case for YAML during planning. - -### 5. Command name: `/ultracontinue` vs `/ultraplan-local continue` vs `/continue` - -**Decision:** `/ultracontinue` (KTG choice). - -**Reasoning:** Muscle-memory parity with the four existing ultra-commands (`/ultrabrief-local`, `/ultraresearch-local`, `/ultraplan-local`, `/ultraexecute-local`). `/continue` is risky (potential collision with Claude Code builtins — flagged as open question in brief). - -### 6. Single command for N sessions, or N invocations? - -**Decision:** N invocations. Each `/ultracontinue` advances exactly ONE session. - -**Alternative considered:** "auto-run all remaining sessions." - -**Reasoning:** Multi-session exists precisely because context resets between sessions are valuable. Compaction-survival, fresh perspective, no token-budget rot. Running N sessions in one go destroys the reason multi-session exists. Captured in brief as explicit non-goal. - ---- - -## What's NOT in the brief but worth knowing - -1. **Anti-pattern flagged in KTG's auto-memory:** `feedback_next_session_prompt_manual.md` says "Ikke foreslå auto-loading via SessionStart/CLAUDE.md. Manuell invokasjon unngår stale-fil-risiko." `/ultracontinue` respects this — it's still operator-invoked. The improvement is that the file the operator loads is mechanically defined and validated, not a hand-written prompt that may have drifted from reality. - -2. **Existing handover-contracts pattern:** `docs/HANDOVER-CONTRACTS.md` already documents 5 handovers (brief→research, research→plan, architecture→plan, plan→execute, progress.json). Adding `.session-state.local.json` as Handover 6 is the natural placement and SC-6 in the brief codifies it. - -3. **Plan-critic / scope-guardian risks to anticipate:** - - Plan-critic will likely push on SC-4 (ultraexecute integration depth). The brief positions this as "may land in a follow-up" — defend that framing or accept it lands in v1.0 if the research finds the insertion points are clean. - - Scope-guardian may flag SC-5 (helper command) as scope creep if ultraplan-local doesn't already have an `end-session` slash. It's NEW surface but justified by the "informal multi-session" use case (v5 release). Plan should make this trade-off explicit. - -4. **The v5 release run is the canonical motivating example.** When in doubt, ask: "would this have removed friction in the 5-session config-audit v5 run?" If no, scope it out. If yes, scope it in. - -5. **Token-budget realism:** This brief is being created at the END of a 250K-context conversation that already shipped v5.0.0. The implementer of `/ultracontinue` will be a fresh session with this brief + design-notes + handover-contracts as context. Keep that in mind when writing the plan — front-load decisions, minimize cross-references that require reading more files than necessary. - ---- - -## Recommended next steps for the implementing session - -1. **Read in this order:** `ultracontinue-brief.md` → `ultracontinue-design-notes.md` (this file) → `docs/HANDOVER-CONTRACTS.md` (just the structure, to know where Handover 6 fits) → `commands/ultraexecute-local.md` end-of-session sections (for SC-4 scoping). - -2. **Decide research path:** - - Light research path (recommended if context-budget is a concern): skip topics 1 and 2, run only Topic 3 (Claude Code slash-command conventions) since 1 and 2 are largely answerable from local code-reading during planning. `/ultraresearch-local --external "..."` for Topic 3 alone. - - Full research path: run all 3 as suggested in the brief. - -3. **Plan with `/ultraplan-local --brief plugins/ultraplan-local/docs/ultracontinue-brief.md`** (or `--project .claude/projects/2026-05-01-ultracontinue` if you set up a project dir for the research outputs first). - -4. **Expect 1-2 execution sessions.** Small surface area: validator + reader-command + helper writer + docs sweep + tests. Not a multi-session epic — meta-irony noted (the work to ship `/ultracontinue` itself doesn't need `/ultracontinue`). - -5. **Don't forget the marketplace root README** — KTG conventions: every plugin doc-affecting change updates plugin README + plugin CLAUDE.md + root marketplace README. Brief's SC-7 codifies this.