claude-code-session-manager 0.26.0 → 0.28.0

package/plugins/session-manager-dev/skills/prd/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: prd
+description: >-
+  Write a PRD for the session-manager scheduler queue (the right place for
+  token-budget-managed work). Use this whenever the user says "make this a PRD",
+  "queue this up", "add to the scheduler", or asks for a PRD without specifying a
+  target location. Keywords: prd, queue, scheduler, scheduled-plans, token budget.
+---
+
+# /prd — author one scheduler PRD
+
+**Role:** `/prd` is the single authority on one PRD's *structure, location, and scope sizing*. It does not own the engineering rules (that's `standards.md`) and does not decompose a large ask into multiple PRDs (that's `/develop`). Never restate rules that live in `standards.md` — reference and append them.
+
+You are writing a PRD that will be executed by the user's session-manager scheduler — a system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour token-window resets, with auto-pause on rate-limit and auto-resume.
+
+## Canonical location — non-negotiable
+
+PRDs MUST be written to:
+
+```
+~/.claude/session-manager/scheduled-plans/prds/<NN>-<kebab-slug>.md
+```
+
+**Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the project root, the scheduler will not see it and the user loses their token-budget-managed execution. There is exactly one queue for all projects — that's intentional, because the 5-hour token budget is global across all of the user's Claude work. The `~` expands to `os.homedir()` so the same convention works for any user on any machine.
+
+## Filename rules
+
+- `NN` is the **parallel group** (2-digit zero-padded). Jobs in the same group run in parallel up to a concurrency cap; groups run serially. Pick `NN` by reading the existing files in `~/.claude/session-manager/scheduled-plans/prds/` and choosing:
+  - The same `NN` as a sibling that's logically independent and can run in parallel.
+  - The next unused `NN` if this PRD has a hard dependency on prior work landing first.
+- `<kebab-slug>` is a short, descriptive kebab-case identifier (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`). Keep under 60 chars.
+
+Compute the current max `NN` **deterministically** before writing — do NOT eyeball the `ls` or narrow the pattern (a grep like `'^10[0-9]'` silently misses `110+` and overwrites/mis-groups a PRD):
+
+```bash
+ls ~/.claude/session-manager/scheduled-plans/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
+```
+
+The last line is the highest in use; the next free group is **max+1**. Use that for an independent/dependent PRD, or reuse a specific sibling's `NN` only when you deliberately want it in that parallel group. Verify your chosen filename doesn't already exist before writing.
+
+## Required frontmatter
+
+```yaml
+---
+title: <one-line human-readable title>
+cwd: <path to target project — where claude -p will run>
+estimateMinutes: <integer wall-clock estimate>
+---
+```
+
+`cwd` is critical. Without it the job runs in the scheduler's default cwd (session-manager). Always set it to the path of the project the work targets. **Write it as `~/Projects/<repo>`** — the parser expands `~` to `os.homedir()` at ingest, so the same PRD works on Linux and macOS. Avoid hardcoding an absolute home path (`/home/<you>/Projects/<repo>`); it breaks on any machine with a different home directory.
+
+## Required body sections (in this order)
+
+```markdown
+# Goal
+
+<2-4 sentences. What the executor will build and why it matters. NO "as a user I want to" framing. Concrete: name the function, the file, the user-visible change.>
+
+# Acceptance criteria
+
+- [ ] <each line is a verifiable check the executor can run after building>
+- [ ] <include explicit file paths, function names, expected behavior>
+- [ ] a bounded test command passes, e.g. `timeout 300 npm run typecheck` / `pytest -x` / `cargo check` (the run-before-done / never-end-on-red rule lives in standards.md → Execution discipline; the AC just has to name the command).
+
+# Implementation notes
+
+<file paths the executor will need to read first; the architectural pattern to follow; any non-obvious constraints. Be specific. Quote function signatures if it saves the executor a Read call.>
+
+# Out of scope
+
+<short bulleted list of what NOT to build, to prevent scope creep>
+```
+
+## Self-containment is load-bearing
+
+The executor (`claude -p`) starts with NO conversation context — only this PRD body and the project files. So:
+
+- Include exact file paths (`src/main/index.cjs:142`).
+- Quote function signatures or relevant code blocks if the executor would have to grep for them.
+- Name the libraries / patterns to use (e.g. "use the existing `validatePath` helper in `config.cjs`").
+- Don't reference "the conversation we just had" or "the design we discussed."
+- If the PRD depends on another PRD's output, say so in `# Implementation notes` AND give it a higher `NN` so it queues after.
+
+## Scope sizing — keep it SMALL (data-driven, 2026-06)
+
+Across 400+ real runs the median PRD finishes in **~7 minutes**, p90 **~21 min**, p99 **~66 min** — yet authored `estimateMinutes` ran **5–8× too high**. Oversized scoping is the root problem: it anchors PRDs too big and pushes them into the rare >60-min tail where ~100% of true hangs live (deploy poll-loops, unbounded e2e suites).
+
+- **Target ~15 minutes of wall-clock work per PRD. Hard ceiling ~30 min — if you project more, SPLIT** into sequential `NN` PRDs and document the dependency in each.
+- Set `estimateMinutes` realistically: **p50≈8, p90≈21**. Don't write 60/90 — it's almost always wrong and it hides real outliers.
+- Each execution costs ~$0.50–$2; the 5-hour token window is global. Smaller PRDs = smaller blast radius when a run is rate-limited, timed out, or killed.
+- **`rateLimited` exit-1 is NOT a failure** — it's the scheduler's designed auto-pause; the job auto-resumes at the next window reset. Don't add retry logic for it.
+
+## Execution discipline — append it, don't restate it
+
+The runtime rules (bound every command, verify-before-done, fail-loud, stay-in-AC,
+negative-assertion-exits-0) have a single home: the **Execution discipline** section of
+`~/.claude/skills/develop/standards.md`. Don't paraphrase them here — they drift.
+
+Long hangs — not bad code — are the dominant *real* failure (the watchdog only fires at 4
+hours, so an unbounded command burns hours), so these rules are load-bearing and MUST reach
+the headless executor in the PRD body:
+
+- If this PRD is being authored **via `/develop`**, that skill already appends `standards.md`
+  verbatim — nothing to do here.
+- If you are authoring a PRD **directly** (`/prd` alone), **append the Execution discipline
+  section from `standards.md` to the PRD body** (under an `## Execution discipline` heading)
+  before queueing. That is the only way the bounded-command / verify-before-done rules reach
+  `claude -p`.
+
+The one rule worth echoing inline because it shapes the AC: **wrap every test/build/deploy/poll
+command in a hard timeout** (`timeout 300 npm run typecheck`, `timeout 120 npx playwright test
+one.spec.ts` — shard e2e to one spec, never a full suite; `curl --max-time 15`; bound any
+`until/while`). Never queue a publish that polls an endpoint until a condition — the #1 hang
+offender (PRD_AUTHORING §1/§5).
+
+## Workflow
+
+1. Read existing PRDs in `~/.claude/session-manager/scheduled-plans/prds/` to pick `NN`.
+2. Write the file with the structure above.
+3. Confirm to the user:
+   - The filename (so they can see it queued).
+   - The chosen `parallelGroup` (NN) and the rationale (parallel-with-X / serial-after-Y).
+   - The chosen `cwd` (so they can correct if it's wrong).
+   - Estimated wall time + a token-cost ballpark.
+4. Tell the user the PRD will fire when the scheduler's policy says — they can click "Run now" in the SchedulePanel to execute immediately, or wait for `when-available` polling.
+
+## What NOT to do
+
+- Don't write the PRD to `data/prds/`, `docs/prds/`, the project's own folder, or anywhere outside the canonical path. The user has explicitly flagged this as a recurring problem.
+- Don't combine multiple unrelated features into one PRD. Each PRD is one focused, completable unit.
+- Don't add a parallelGroup field to the frontmatter — the scheduler reads the filename prefix.
+- Don't leave `cwd` unset hoping for the default. Be explicit.
+- Don't write the PRD body inline in the chat for review *before* writing the file. Write the file directly, then confirm. The user wants the PRD queued, not draft-reviewed in chat.

package/plugins/session-manager-dev/skills/process-feedback/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: process-feedback
+description: >-
+  Process the current project's inbound feedback folder end-to-end: read every
+  open item, evaluate it against real code, and for work that belongs to this
+  project queue it as scheduled PRDs via /develop (never implement inline) —
+  then track those PRDs to completion, archive the item as processed, and fold
+  lessons back into the folder's README so future feedback (written by other
+  agents/projects) gets better. Use whenever the user says "/process-feedback",
+  "review the feedback folder", "work through the feedback", "any open
+  feedback?", or drops new files into feedback/. Keywords: feedback, intake,
+  external-feedback, cross-project requests, process feedback, triage feedback.
+model: opus
+---
+
+# process-feedback
+
+**Role:** the *agent-side intake* for the dev pipeline — the project-to-project complement of
+an interactive human prompt. It evaluates inbound feedback, dispatches the codeable parts to
+`/develop` (the shared pipeline), and owns the feedback-specific bookkeeping (status log,
+RESOLUTION, archive). It does **not** implement, and it does **not** re-specify how PRDs are
+tracked — that lives once, in `/develop` Phase 2.
+
+Work the project's intra-project feedback intake (`feedback/` at the repo root;
+some projects name it `external-feedback/`). Each file is a request from an
+upstream/downstream service in the same stack (e.g. Burrow ⇄ signal-builder ⇄
+social-signals-trader). The folder's own `README.md` is the authority on file
+conventions — read it first; the steps below are the process.
+
+**Core principle:** this skill *triages and dispatches*; it does not implement.
+Anything that requires writing code for this project is decomposed and queued as
+scheduled PRDs through **`/develop`**, which runs them headlessly on the
+session-manager scheduler. process-feedback then watches those PRDs to
+completion and does the bookkeeping. Implementing feedback inline — bypassing
+the scheduler — is the one thing this skill must not do.
+
+## Steps
+
+### 0. Quick-exit — bail in milliseconds if there's nothing to do
+
+**Do this first, cheaply, before reading any code or spawning anything.** This
+skill is run on a schedule across many projects (the scheduler's feedback sweep),
+so the empty case must cost almost nothing:
+
+- If neither `feedback/` nor `external-feedback/` exists → report
+  "no feedback intake in `<project>`" and **EXIT**.
+- If the folder exists but holds **no open item** (every file is in `processed/`
+  or marked ✅/archived; nothing open/🆕) → report "no open feedback in
+  `<project>`" and **EXIT immediately**. Do NOT read source, evaluate, or start
+  an agent loop.
+- Only when at least one **open** item exists do you continue — an open item
+  means *someone cares about this project*, so it's worth the full pass (and,
+  per step 7, leaving the README better for next time).
+
+### 1. Read the intake
+
+- Read `feedback/README.md` (conventions + the status log), then every file
+  whose status is open/🆕. Skip files already ✅/archived. Items already 🛠
+  (queued — see step 4) are in flight: don't re-queue them, just re-check their
+  PRD status (step 5).
+- If the folder doesn't exist, say so and stop — don't invent one.
+
+### 2. Evaluate before queueing
+
+For each open item, verify the claims against current code and live data —
+feedback cites the state of the world when it was written, which may have
+drifted. Then classify each ask:
+
+- **Ours, do it** — the fix belongs to this project. → goes to `/develop`
+  (step 3). Do NOT write the code here.
+- **Ours, decline** — conflicts with the project's contracts/vision (e.g. a
+  convenience ask that violates a service boundary). Decline explicitly in the
+  RESOLUTION with the reason; never silently skip. Resolved now (no code) →
+  close immediately in step 4.
+- **Theirs, forward** — the root cause lives in another service. Do NOT reach
+  across the boundary to hack around it; file a feedback/PRD item in *that*
+  project's intake folder and reference it (use `/my-feedback to <project>`).
+  Resolved now (no code in *this* repo) → close immediately in step 4.
+
+Root-cause with evidence (logs, live queries, health checks), not from the
+file's narrative alone — the reporter sees symptoms, you can see causes.
+
+### 3. Queue the work via /develop (never implement inline)
+
+For every **Ours, do it** item, invoke the **`develop`** skill to turn the ask
+into one or more self-contained PRDs in the scheduler queue. Hand `/develop` a
+complete brief so it does not have to re-ask scope — your step-2 evaluation
+already established it:
+
+- The goal, in this-project terms.
+- **Acceptance criteria taken from the feedback's own AC**, made verifiable
+  (with the test/health command to prove them).
+- The absolute `cwd`, plus the exact files/patterns/utilities to reuse that you
+  found while root-causing (the API-reuse standard — don't make the headless run
+  rediscover them).
+- Any constraints, service boundaries, or "out of scope" lines.
+
+`/develop` owns decomposition (small ~15-min PRDs), inlining the engineering
+standards, the `NN-` parallel grouping, and — because each PRD publishes its own
+work — the implementation **commit + deploy**. That means process-feedback does
+**not** commit implementation code; the PRDs do, when they run.
+
+Record the emitted PRD filenames/ids — you need them for steps 4–6.
+
+### 4. Interim bookkeeping — commit the triage now
+
+Two cases:
+
+- **Closed-without-code** items (declines, upstream forwards): append a full
+  `## RESOLUTION` (what was declined and why / what was forwarded where, with the
+  upstream file id), flip the README row to ✅, and `git mv` the file to
+  `feedback/processed/` — these are done.
+- **Queued** items (sent to `/develop`): append a `## RESOLUTION (in progress)`
+  recording the queued PRD filenames/ids and that execution is pending the
+  scheduler. Flip the README row to **🛠 queued** (add 🛠 to the log's legend if
+  absent) — **not** ✅. Leave the file in `feedback/` until the PRDs land. Do not
+  fabricate verification for code that hasn't run yet.
+
+Commit only this feedback bookkeeping + any upstream filings (message references
+the feedback file id, e.g. `chore(feedback): triage + queue 2026-06-10-01`).
+Only commit a clean, green tree; if unrelated in-flight work is mixed into the
+working tree, stop and tell the user instead of committing around it.
+
+### 5. Track to completion — delegate to /develop Phase 2
+
+The queued PRDs run headlessly and can take a while. **Do not re-implement the
+monitor here** — `/develop` Phase 2 already owns it (the 30-min scheduler watch,
+the escalate-on-stuck/`needs_review`/timeout logic, and the live verification
+against each PRD's acceptance criteria). When you call `/develop` in step 3, that
+tracking runs as part of it.
+
+Your only job in this step is to consume its outcome per queued item:
+
+- **`/develop` escalated a PRD** (failed / stuck / needs attention) — relay it to
+  the user with its specifics; leave the feedback item at 🛠 (still in flight)
+  until it's resolved or re-queued. Don't archive a broken item as done.
+- **`/develop` reported all of an item's PRDs landed + verified** — proceed to
+  step 6 to finalize that item's bookkeeping.
+
+### 6. Finalize the archive (when an item's PRDs land + verify)
+
+Once `/develop` Phase 2 reports an item's PRDs merged and verified against the AC:
+
+- Append the final `## RESOLUTION`: what changed, the PRD/commit refs, what was
+  declined/forwarded, and how `/develop` verified it (cite its gate result —
+  don't re-run the verification it already did).
+- Flip the README row **🛠 → ✅** (keep the row — the log is the durable index).
+- `git mv` the file to `feedback/processed/` (create the dir if needed). Closed
+  items live there as the durable record; only files entered in error are ever
+  deleted.
+- Commit the bookkeeping.
+
+### 7. Self-improve the intake (always do this)
+
+Update the folder's `README.md` guidance section based on what this round
+taught you:
+
+- What made an item easy to queue + close? Distill it into a bullet other agents
+  can imitate (cite the file as the example) — e.g. a feedback item that already
+  carried a crisp, testable AC turned straight into a clean PRD.
+- What slowed you down — a missing log path, an unverifiable claim, an ask that
+  actually belonged to a third service, a PRD that got stuck? Add the
+  counter-guidance.
+- Keep the section calibrated and short: merge/rewrite stale bullets rather than
+  appending forever.
+
+This step is the point of the skill: every processing pass should make the
+*next* pass cheaper.
+
+## Guardrails
+
+- **Never implement feedback inline.** Code that belongs to this project goes
+  through `/develop` → the scheduler. The only commits process-feedback makes
+  itself are feedback bookkeeping and upstream filings.
+- **Never mark a queued item ✅ or move it to `processed/` before its PRDs land
+  and verify.** Queued ≠ done; 🛠 is the honest interim state. An item archived
+  as resolved must point to merged, verified work.
+- Never delete feedback files to "clear" the folder — archive them.
+- Service boundaries outrank feedback asks: an item that requests a boundary
+  violation gets a documented decline + an upstream filing, not compliance.
+- Report honestly in the RESOLUTION: PRDs that failed or stalled, asks left
+  open, deps on other teams. An archived item with open external deps should say
+  what unblocks it.

package/plugins/session-manager-dev/skills/project-status/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: project-status
+model: opus
+description: >-
+  GLOBAL FRAMEWORK for one operational status rollup of the project in the
+  current working directory — defines the contract (what a status report must
+  contain, in what order, on which model) and DELEGATES the project-specific
+  measurement to that project's own `project-status-local` skill. Use whenever
+  the user asks "what's the project status", "/project-status", "how is this
+  project doing", "are the jobs healthy", or wants a one-shot status rollup for
+  the repo they're in. Keywords: project status, KPI, north-star, crons, jobs,
+  last run, health, rollup, ops.
+---
+
+# project-status — global framework
+
+This is the **global framework**, not an implementation. It owns the *contract*
+(what a status rollup must contain, the order, the presentation, the model
+expectation) and **delegates** the project-specific *how* to the project's own
+`project-status-local` skill.
+
+> **Two skills, no name collision (by design).**
+> `project-status` (this, global) = the framework/expectations.
+> `project-status-local` (per project) = the implementation.
+> They have **different names on purpose** — a project must NOT ship a second
+> skill also named `project-status`, because a same-name skill silently shadows
+> this one and drops everything it defines (that is exactly how the model
+> fallback got lost once). Each project ships exactly one `project-status-local`.
+
+## What to do when invoked
+
+First decide **scope**: one project (the current repo) or several (the user named
+multiple repos, said "all my projects", or wants a cross-project board).
+
+### Single project (the cwd)
+
+1. **Delegate if a local exists.** If a `project-status-local` skill is available
+   in the current project (it appears in the available-skills list), **invoke it**
+   (Skill tool, `skill: project-status-local`). It owns the specifics — which KPI
+   command to run, which crons are this project's, which health entrypoint to
+   call. Present its output; if it omits an element of the contract below, fill
+   the gap or note it.
+2. **Otherwise run the generic fallback inline** (the flow at the bottom) and, at
+   the end, **offer to scaffold a `project-status-local`** for this repo so the
+   next run is project-aware.
+
+Do not re-implement a project's specifics here — that belongs in its
+`project-status-local`.
+
+### Multiple projects (parallel fan-out)
+
+The whole point of the framework/`-local` split: the per-project work is
+**independent**, so run it **concurrently** — one project's KPI/crons/health
+never depends on another's.
+
+1. **Resolve the project list.** Use the repos the user named; for "all", or to
+   discover them, enumerate every repo that ships a local skill:
+   ```bash
+   for d in ~/Projects/*/.claude/skills/project-status-local/SKILL.md; do
+     [ -f "$d" ] && echo "${d%/.claude/skills/project-status-local/SKILL.md}"
+   done
+   ```
+2. **Fan out one agent per project — in a SINGLE message with multiple `Agent`
+   tool calls** so they run in parallel (sequential calls would defeat the
+   purpose). Each agent (`subagent_type: general-purpose`) gets a prompt like:
+   > `cd <ABS_REPO_PATH>`. Produce this repo's status rollup by executing its
+   > own `project-status-local`: **read** `.claude/skills/project-status-local/SKILL.md`
+   > and run its steps (they are deterministic — a `brief.py`/analyzer call, a
+   > `crontab -l | grep` for its crons, its `scripts/health.sh`). If the repo has
+   > no `project-status-local`, follow the generic contract (KPI→chores→health)
+   > using its `CLAUDE.md` + crontab + health entrypoint. Return a **compact**
+   > rollup (≤12 lines): the project name, the 7d North-Star line (KPI vs
+   > benchmark → alpha), the health color, and the single worst ❌/⚠️ chore.
+   Let each agent **inherit the model** (omit `model`) — it just runs the repo's
+   commands; this framework's `model: opus` governs *this* turn.
+3. **Aggregate** the returned rollups into one board: a lead table
+   (Project · 7d KPI · Health · Worst signal), RED/❌ projects first, then each
+   project's detail block beneath. Note any agent that failed to produce a rollup
+   (missing repo, broken local) rather than dropping it silently.
+
+Why agents, not the Skill tool, for the others: skill availability is bound to
+the launch repo, so `project-status-local` is only directly invokable for the
+**current** project. For other repos the agent reproduces the local by reading +
+running it (it is deterministic bash), which works from any cwd.
+
+## The contract (what every report must satisfy)
+
+Order — **1. North-Star KPI (last 7d) → 2. Chores (crons) → 3. Logs & usage
+patterns → 4. Health verdict.** Lead with the KPI line and the single worst
+❌/⚠️ chore or health signal; detail after. Keep it tight; relay engine/analyzer
+output rather than re-deriving numbers by hand.
+
+A status check is an **audit**, not just a liveness ping — it reads the project's
+*operational logs* (are the runs clean or throwing?) and its *usage/consumption
+patterns* (who consumes the product's outputs, how often, which surfaces are hot
+vs dead) alongside the KPI and crons. The KPI says "is the output valuable," the
+logs+usage say "is the machine actually being used, and is it healthy under that
+use." Both dimensions belong in every report.
+
+- **KPI (the intro):** the metric the project's `CLAUDE.md` mission statement
+  names as optimized (a `## North-Star KPI` / `## Objective` section, usually
+  linking a definition doc or a measurement command). Measure it over a trailing
+  7-day window with the project's own command; state it with the
+  benchmark/target the section defines. If `CLAUDE.md` declares no KPI, say so
+  plainly (it belongs in the mission statement) and use a git/activity summary
+  for the intro — never invent a metric.
+- **Chores:** only THIS project's cron jobs (match by repo name / absolute path),
+  each with last-run time, recent result, and an error count, in a table:
+  Job · Schedule · Purpose · Last run · Errors · Last result. Staleness: newest
+  log line older than ~2× cadence ⇒ ⚠️ overdue; an installed cron with an
+  empty/missing log ⇒ ❌ (often a Vixie-cron `TZ=` inline-prefix drop — fix with a
+  standalone `TZ=` line). Market-hours-only jobs stale overnight is expected.
+- **Logs & usage patterns:** two sub-parts, both delegated to the `-local` for
+  *where the data lives*, but expected in every report:
+  - **Logs** — scan the recent operational logs for error/warning rates,
+    tracebacks, timeouts, and silent-stall signatures (a job that "ran ok" but
+    did no work). Surface counts + the worst recent line, not just last-exit.
+  - **Usage / consumption** — how the project's *outputs* are actually consumed:
+    per-endpoint/-tool invocation counts, the consumer/tenant breakdown, and
+    hot-vs-cold surfaces over a trailing window. This answers "is what we built
+    being used, and by whom" — the dimension a KPI alone misses. The `-local`
+    names the source (a usage/metering store, an access log, or a proxy like a
+    panel/history table); if no usage source exists yet, say so and recommend
+    standing one up rather than inventing numbers.
+- **Health verdict:** run the project's own health entrypoint (first hit wins:
+  `scripts/health.sh` · `.claude/health.sh` · `bin/health.sh` · a `health`
+  Make/just target) and relay its GREEN/YELLOW/RED rollup. A non-zero exit for
+  YELLOW/RED is expected, not a skill failure; only a crash is.
+
+## After the audit — route findings, then improve (the loop)
+
+A status check shouldn't dead-end at a report. Once the four dimensions are in,
+**act on what the audit surfaced** — this is what makes `/project-status` a
+self-contained *bootstrap → evaluate → improve* loop, usable even on a brand-new
+project.
+
+**First, work the inbox — triage before generating new work.** Right after the
+audit, clear the inbound queue via **`/process-feedback`**: it evaluates any
+pending feedback (cross-project asks others filed to us, plus the prior cycle's
+`/optimize-kpi` item) and routes each — ours-do-it → `/develop`, theirs →
+`/my-feedback`, decline-with-reason. Don't generate new levers on top of an
+unprocessed backlog. (If the inbox is empty, say so and move on.)
+
+Then route **this audit's own findings**, by ownership:
+
+1. **A finding that belongs to another project** (an upstream/downstream service
+   in the stack — e.g. the data source is stale, a contract drifted): do NOT
+   reach across the boundary. File it with **`/my-feedback <project>`** into that
+   project's intake, and note it in the report. (Same rule as everywhere: service
+   boundaries outrank convenience.)
+2. **A finding that belongs to THIS project** (a real bug, a missing guard, an
+   enhancement the audit revealed — a cold sold-surface, a recurring error in the
+   logs, a usage gap): queue it as a scheduled PRD via **`/develop`** — never
+   implement it inline here. Record the queued PRD id in the report.
+3. **Nothing actionable** — just report.
+
+Then, the improvement gate: **if and only if the full health verdict is GREEN**
+(every check passing — not degraded, not down) **and** the KPI/crons are clean,
+invoke **`/optimize-kpi`** to drive the next North-Star improvement. The green gate
+is load-bearing: optimizing the KPI on a broken or degraded base is wasted
+motion — *fix health first* (via routes 1/2 above), and let a later run, once
+green, trigger the optimizer. State explicitly in the report whether the gate
+opened (green → optimize queued) or stayed shut (degraded/down → health findings
+routed first).
+
+This sequence — audit → route findings (my-feedback / develop) → optimize-when-green
+— is enough to bootstrap, evaluate, and continuously improve a project from a
+single `/project-status` invocation. The `-local` owns the *specifics* of each
+step; this framework owns the *loop*.
+
+## Model expectation (every local must mirror this)
+
+This framework runs on **`model: opus`** (Opus 4.8) — a status check is reasoning
+work that should run on the strongest model. **Every `project-status-local` MUST
+carry the same single-value `model: opus` frontmatter line**, so a direct
+`/project-status-local` invocation runs on Opus too. A local that omits it loses
+the override and runs on whatever the session model happens to be.
+
+> **Syntax matters — this is a real, documented field.** Skill frontmatter
+> `model:` takes a **single** value (the same aliases as `/model`: `opus`,
+> `sonnet`, `haiku`, `fable`, or a full id like `claude-opus-4-8`). It does NOT
+> accept a comma-separated fallback chain — `model: opus,sonnet` is an invalid
+> value and silently fails to apply (the skill then runs on the session model,
+> not Opus). Graceful failover to Sonnet is configured **at the session level**,
+> not per-skill, via `fallbackModel` in settings:
+> `"fallbackModel": ["opus", "sonnet"]` in `~/.claude/settings.json`. Per the
+> Claude Code docs, a skill's `model:` override applies for the rest of the
+> current turn and reverts to the session model on the next prompt.
+
+## Scaffolding a new `project-status-local` — establish the framework with the user
+
+When a project has none, **do not silently guess the implementation.** The whole
+point of the framework/`-local` split is that every project's report covers the
+**same four dimensions** (KPI · chores · logs+usage · health) — so the parent's job
+on a missing `-local` is to *establish those expectations with the user*, then
+write a complete local. Run a short **Q&A** (use `AskUserQuestion`, batching the
+gaps you couldn't auto-detect) to pin down each contract dimension:
+
+1. **Probe first, ask only the gaps.** Read `CLAUDE.md` (KPI section?), the
+   crontab (this repo's jobs + their log paths?), the repo for a health entrypoint
+   (`scripts/health.sh` etc.), and for a usage source (a metering/access-log store,
+   or a proxy table). Auto-fill what you can find.
+2. **Ask the user to confirm/supply the rest**, one question per unresolved
+   dimension:
+   - **KPI** — what is this project's North-Star metric + the command that measures
+     it over 7d? (If `CLAUDE.md` has no `## North-Star KPI` section, offer to add
+     one — the KPI belongs in the mission statement, not only the skill.)
+   - **Chores** — which crons are this project's, and where do their logs live?
+   - **Logs & usage** — which logs carry the operational signal, and **what is the
+     usage/consumption source** (a metering store / access log / proxy)? If none
+     exists, flag it and offer to stand one up — a project with no usage telemetry
+     can't answer "is what we built being used."
+   - **Health** — the health entrypoint + how to read its verdict.
+3. **Write the local** `<repo>/.claude/skills/project-status-local/SKILL.md` with
+   frontmatter `name: project-status-local`, `model: opus` (single value — see the
+   syntax note above; `fallbackModel` owns failover), a project-specific
+   `description`, and a body implementing **all four** contract dimensions against
+   the answers — so the next `/project-status` here is project-aware and consistent
+   with every other project's report.
+
+This Q&A is the deliberate "pain" that makes cross-project reports comparable:
+each `-local` is the *same contract*, filled with that project's specifics.
+
+## Generic fallback flow (no local present)
+
+Run inline only when the project ships no `project-status-local`:
+
+1. **Current time:** `date '+%Y-%m-%d %H:%M %Z'` (for staleness judgment).
+2. **KPI:** read `./CLAUDE.md`, find the North-Star section, run its measurement
+   command over 7 days, and state the headline. No KPI section ⇒ say so + git
+   summary.
+3. **Chores:** `crontab -l | grep -F "$(basename "$PWD")" | grep -v '^\s*#'`
+   (widen/narrow if the cron path differs from the dir name); for each job
+   `ls -la <log>` + `tail -n 8 <log>` + an `ERROR|Traceback|failed|exception`
+   count; render the chores table.
+4. **Logs & usage:** scan recent logs for error/warning rates + silent stalls;
+   look for a usage/consumption source (a metering store, an access log, or a
+   request/history table) and summarize per-surface invocation + consumer
+   patterns over a trailing window. If none exists, say so and recommend standing
+   one up — don't invent usage numbers.
+5. **Health:** run the project's health entrypoint and relay the rollup; if none
+   exists, infer from KPI + chores and offer to create `scripts/health.sh`.
+6. Lead with the 7d KPI line and the worst chore/health/usage signal. Then offer
+   to scaffold a `project-status-local` (Q&A above) so the next run is consistent.

package/plugins/session-manager-dev/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+---
+
+# Requesting Code Review
+
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch superpowers:code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md