claude-code-session-manager 0.73.2 → 0.75.0

package/src/main/seedDevPlugin.cjs

@@ -65,7 +65,7 @@ function writeMarker(state) {
   }
 }
 
-async function seedDevPlugin({ logger = console } = {}) {
+async function seedDevPlugin({ logger = console, writeLog = () => {} } = {}) {
   if (process.env.SM_SEED_DEV_PLUGIN_DISABLE === '1') return;
   const marker = readMarker();
   if (marker.done) return;                       // succeeded before — leave it alone.
@@ -84,12 +84,24 @@ async function seedDevPlugin({ logger = console } = {}) {
     } else {
       // Failure: bump the attempt counter so the next boot can retry (bounded).
       logger.warn?.(`[seedDevPlugin] install failed (exit ${r.exitCode})${r.error ? ` — ${r.error}` : ''}; attempt ${marker.attempts + 1}/${MAX_ATTEMPTS}`);
+      writeLog({
+        scope: 'seed-dev-plugin',
+        level: 'error',
+        message: 'install failed',
+        meta: { exitCode: r.exitCode, error: r.error, attempt: marker.attempts + 1, maxAttempts: MAX_ATTEMPTS },
+      });
       writeMarker({ done: false, attempts: marker.attempts + 1 });
     }
   } catch (err) {
     logger.warn?.('[seedDevPlugin] error:', err?.message ?? err);
+    writeLog({
+      scope: 'seed-dev-plugin',
+      level: 'error',
+      message: 'seed error',
+      meta: { error: err?.message ?? String(err), attempt: marker.attempts + 1, maxAttempts: MAX_ATTEMPTS },
+    });
     writeMarker({ done: false, attempts: marker.attempts + 1 });
   }
 }
 
-module.exports = { seedDevPlugin };
+module.exports = { seedDevPlugin, markerPath, MAX_ATTEMPTS };

package/src/main/seedSchedulerMcp.cjs

@@ -0,0 +1,148 @@
+/**
+ * First-boot seeder for the `session-manager-scheduler` MCP server at USER
+ * scope (`~/.claude.json`).
+ *
+ * Why user scope: the scheduler MCP server is a machine-wide service (it
+ * talks to the session-manager Electron app's loopback admin API, not
+ * anything project-specific). Registering it per-project in each repo's own
+ * .mcp.json is the wrong shape — a project whose .mcp.json omits it silently
+ * loses access to `scheduler_create_prd` with no error, so agents fall back
+ * to hand-writing PRDs or implementing inline instead of queueing. See
+ * `scripts/install-scheduler-mcp-user-scope.sh` (the manual installer this
+ * seeder promotes to automatic) for the full incident history.
+ *
+ * Idempotent two ways, mirroring `seedDevPlugin.cjs`:
+ *
+ *   1. A marker file (`~/.claude/session-manager/.scheduler-mcp-seeded`)
+ *      records seed state. Once registration SUCCEEDS we write `done` and
+ *      never touch it again, so a deliberate `claude mcp remove` stays
+ *      removed. A FAILED attempt only bumps an attempt counter and retries
+ *      on the next few boots (e.g. `claude` not yet on PATH). After
+ *      MAX_ATTEMPTS we give up (the manual installer script is always
+ *      available as a fallback).
+ *   2. Before attempting, we check `~/.claude.json`'s `mcpServers` — if
+ *      `session-manager-scheduler` is already registered at user scope
+ *      (e.g. via the manual installer), we just write the marker and skip.
+ *
+ * Never overwrites or removes an existing user-scope registration, and never
+ * touches any other MCP server entry.
+ *
+ * Fire-and-forget: called post-window from index.cjs. Errors are logged,
+ * never thrown. Kill-switch: SM_SEED_SCHEDULER_MCP_DISABLE=1.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawn } = require('node:child_process');
+const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
+const { writeJsonSync } = require('./config.cjs');
+
+const SERVER_NAME = 'session-manager-scheduler';
+const MAX_ATTEMPTS = 3; // give a transient first-boot failure a few chances
+
+function markerPath() {
+  return path.join(os.homedir(), '.claude', 'session-manager', '.scheduler-mcp-seeded');
+}
+
+/** Absolute path to the bundled scheduler MCP server, resolved from
+ *  __dirname (never process.cwd() / never repo-relative). src/main/ -> ../.. */
+function serverScriptPath() {
+  return path.join(__dirname, '..', '..', 'scripts', 'scheduler-mcp-server.cjs');
+}
+
+/** Read the marker -> { done:boolean, attempts:number }. Absent = fresh. */
+function readMarker() {
+  try {
+    const raw = fs.readFileSync(markerPath(), 'utf8').trim();
+    const m = JSON.parse(raw);
+    return { done: !!m.done, attempts: Number(m.attempts) || 0 };
+  } catch {
+    return { done: false, attempts: 0 };
+  }
+}
+
+function writeMarker(state) {
+  try {
+    writeJsonSync(markerPath(), { ...state, ts: new Date().toISOString() });
+  } catch (err) {
+    console.warn('[seedSchedulerMcp] could not write marker:', err?.message ?? err);
+  }
+}
+
+function alreadyRegistered() {
+  try {
+    const raw = fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8');
+    const servers = JSON.parse(raw)?.mcpServers;
+    return !!(servers && servers[SERVER_NAME]);
+  } catch {
+    return false; // ~/.claude.json absent/unparseable — treat as not-registered.
+  }
+}
+
+/** Run `claude mcp add session-manager-scheduler --scope user -- node <serverPath>`.
+ *  No shell:true — argv array passed directly to spawn. */
+function runClaudeMcpAdd(serverPath) {
+  return new Promise((resolve) => {
+    const claudeBin = resolveClaudeBin();
+    let proc;
+    try {
+      proc = spawn(
+        claudeBin,
+        ['mcp', 'add', SERVER_NAME, '--scope', 'user', '--', 'node', serverPath],
+        {
+          cwd: os.homedir(),
+          env: cleanChildEnv({ PATH: pathWithUserBins() }),
+          stdio: 'ignore',
+        }
+      );
+    } catch (err) {
+      resolve({ ok: false, error: err?.message ?? String(err) });
+      return;
+    }
+    proc.on('error', (err) => resolve({ ok: false, error: err?.message ?? String(err) }));
+    proc.on('close', (code) => resolve({ ok: code === 0, exitCode: code }));
+  });
+}
+
+async function seedSchedulerMcp({ logger = console, addFn = runClaudeMcpAdd, writeLog = () => {} } = {}) {
+  if (process.env.SM_SEED_SCHEDULER_MCP_DISABLE === '1') return;
+  const marker = readMarker();
+  if (marker.done) return;                       // succeeded before — leave it alone.
+  if (marker.attempts >= MAX_ATTEMPTS) return;   // gave up — manual install only.
+
+  try {
+    if (alreadyRegistered()) {
+      writeMarker({ done: true, attempts: marker.attempts });
+      return;
+    }
+    logger.log?.('[seedSchedulerMcp] registering session-manager-scheduler at user scope…');
+    const r = await addFn(serverScriptPath());
+    if (r.ok) {
+      logger.log?.('[seedSchedulerMcp] registered session-manager-scheduler at user scope');
+      writeMarker({ done: true, attempts: marker.attempts });
+    } else {
+      // Failure: bump the attempt counter so the next boot can retry (bounded).
+      logger.warn?.(`[seedSchedulerMcp] registration failed${r.error ? ` — ${r.error}` : ''}; attempt ${marker.attempts + 1}/${MAX_ATTEMPTS}`);
+      writeLog({
+        scope: 'seed-scheduler-mcp',
+        level: 'error',
+        message: 'registration failed',
+        meta: { error: r.error, exitCode: r.exitCode, attempt: marker.attempts + 1, maxAttempts: MAX_ATTEMPTS },
+      });
+      writeMarker({ done: false, attempts: marker.attempts + 1 });
+    }
+  } catch (err) {
+    logger.warn?.('[seedSchedulerMcp] error:', err?.message ?? err);
+    writeLog({
+      scope: 'seed-scheduler-mcp',
+      level: 'error',
+      message: 'seed error',
+      meta: { error: err?.message ?? String(err), attempt: marker.attempts + 1, maxAttempts: MAX_ATTEMPTS },
+    });
+    writeMarker({ done: false, attempts: marker.attempts + 1 });
+  }
+}
+
+module.exports = { seedSchedulerMcp, markerPath, MAX_ATTEMPTS, serverScriptPath, SERVER_NAME };

package/src/main/seedStatus.cjs

@@ -0,0 +1,59 @@
+/**
+ * Renderer-facing rollup of first-boot seeder outcomes.
+ *
+ * Derived purely by reading each seeder's own marker file — never re-runs an
+ * install to find out. A missing or unparseable marker means the seeder
+ * hasn't run yet (or its file got corrupted), which is indistinguishable
+ * from "still pending" and must never surface as an error.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+
+const seedDevPlugin = require('./seedDevPlugin.cjs');
+const seedSchedulerMcp = require('./seedSchedulerMcp.cjs');
+const seedAgentPersonas = require('./seedAgentPersonas.cjs');
+
+// Each entry's key is the seeder id surfaced to the renderer/IPC contract.
+const SEEDERS = {
+  'dev-plugin': seedDevPlugin,
+  'scheduler-mcp': seedSchedulerMcp,
+  'agent-personas': seedAgentPersonas,
+};
+
+/** One seeder's marker → 'done' | 'pending' | 'exhausted'. */
+function statusFromMarker(mod) {
+  try {
+    const raw = fs.readFileSync(mod.markerPath(), 'utf8').trim();
+    const m = JSON.parse(raw);
+    if (m && m.done) return 'done';
+    const attempts = Number(m && m.attempts) || 0;
+    return attempts >= mod.MAX_ATTEMPTS ? 'exhausted' : 'pending';
+  } catch {
+    return 'pending'; // absent or unparseable — never surfaced as an error.
+  }
+}
+
+// The manual fix surfaced by the Plugins banner when a seeder is exhausted.
+// `scheduler-mcp`'s command reuses the same server-script path the seeder
+// itself resolves (seedSchedulerMcp.serverScriptPath()) — single source of
+// truth for that absolute path, never re-derived here.
+const FIXES = {
+  'dev-plugin': 'Open Plugins → Library and click Install next to "session-manager-dev".',
+  'scheduler-mcp': () =>
+    `Run in a terminal: claude mcp add ${seedSchedulerMcp.SERVER_NAME} --scope user -- node ${seedSchedulerMcp.serverScriptPath()}`,
+  'agent-personas': 'Copy src/seed/agents/architect.md and dev-lead.md into ~/.claude/agents/ (skip any that already exist there).',
+};
+
+/** { 'dev-plugin': {status, fix}, 'scheduler-mcp': {status, fix}, 'agent-personas': {status, fix} } */
+function getSeedStatus() {
+  const out = {};
+  for (const [id, mod] of Object.entries(SEEDERS)) {
+    const fix = FIXES[id];
+    out[id] = { status: statusFromMarker(mod), fix: typeof fix === 'function' ? fix() : fix };
+  }
+  return out;
+}
+
+module.exports = { getSeedStatus };

package/src/preload/api.d.ts

@@ -199,6 +199,11 @@ export interface McpStatusResult {
   checkedAt: number;
 }
 
+/** Mirrors WorkType (src/main/lib/workTypeLibrary.cjs) / EpicTag (tagLibrary.ts) — the
+ *  same Epic-mission taxonomy, reused here since an Agent persona's `tags` field is that
+ *  same concept, not a free-form string list. */
+export type AgentPersonaTag = 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+
 /** One global `~/.claude/agents/<name>.md` persona, per the Agent Library nav page. */
 export interface AgentPersona {
   name: string;
@@ -207,7 +212,7 @@ export interface AgentPersona {
   model: string | null;
   color: string | null;
   /** Epic intent tags (tagLibrary.ts's TAG_LIBRARY) this persona is associated with. */
-  tags: string[];
+  tags: AgentPersonaTag[];
   /** Project cwds whose Sessions toolbar shows a one-click Action button for this
    *  agent. The single entry `'*'` means every project. Empty = no Action button. */
   projects: string[];
@@ -234,7 +239,7 @@ export interface AgentPersonaSaveInput {
   tools: string[];
   model: string;
   color: string;
-  tags: string[];
+  tags: AgentPersonaTag[];
   /** Project cwds (or the `'*'` sentinel) this persona's Action button appears in. */
   projects?: string[];
   /** Opening instruction sent by this persona's Action button. */
@@ -317,6 +322,26 @@ export interface TestFireHookResult {
   durationMs: number;
 }
 
+export interface DelegationReadinessCheck {
+  id: 'scheduler-mcp' | 'dev-plugin' | 'agent-personas' | 'prd-write-guard';
+  label: string;
+  ok: boolean;
+  detail: string;
+  fix: string | null;
+}
+
+export interface DelegationReadiness {
+  ok: boolean;
+  checks: DelegationReadinessCheck[];
+}
+
+/** First-boot seeder outcome, one per seeder id, derived from its marker file.
+ *  `fix` is the manual remedy shown by the Plugins banner when `status` is 'exhausted'. */
+export type SeedStatus = Record<
+  'dev-plugin' | 'scheduler-mcp' | 'agent-personas',
+  { status: 'done' | 'pending' | 'exhausted'; fix: string }
+>;
+
 export interface OtelConfig {
   enabled: boolean;
   endpoint: string;
@@ -1266,6 +1291,13 @@ export interface SessionManagerAPI {
     /** Boot diagnostic — assertCwdInsideHome(os.homedir()) result. ok=false
      *  on macOS symlinked-/Users mismatch and blocks all session spawns. */
     homeSelfCheck: () => Promise<{ ok: boolean; error?: string; realCwd?: string }>;
+    /** First-boot seeder outcomes, read live from each seeder's own marker
+     *  file: 'done' (succeeded), 'pending' (not yet run / retrying),
+     *  'exhausted' (gave up after MAX_ATTEMPTS — manual fix needed). */
+    seedStatus: () => Promise<SeedStatus>;
+    /** "Can this project actually delegate?" — the 4 preconditions for
+     *  scheduler_create_prd being in an agent's tool list at all. */
+    delegationReadiness: (cwd: string) => Promise<DelegationReadiness>;
     onNewSession: (handler: () => void) => () => void;
     onRebootSession: (handler: () => void) => () => void;
     archiveProject: (encoded: string) => Promise<{ ok: boolean; error?: string }>;
@@ -1324,6 +1356,11 @@ export interface SessionManagerAPI {
     savePersona: (payload: AgentPersonaSaveInput) => Promise<{ ok: boolean; path: string }>;
     deletePersona: (payload: { name: string }) => Promise<{ ok: boolean }>;
     removeOverride: (payload: { name: string; projectName: string }) => Promise<{ ok: boolean }>;
+    /** Raw persona `.md` text for the New Epic AIM composer (epicIntake.ts's `agentBody`),
+     *  resolved with project-overlay-then-global precedence for `cwd` — unlike
+     *  `listPersonas` above, which only reads the global directory. Null when neither
+     *  location has the file. */
+    getPersonaBody: (payload: { cwd: string; name: string }) => Promise<{ path: string; text: string } | null>;
     /** Fires after any save/delete/removeOverride — subscribers should re-fetch listPersonas(). */
     onChanged: (handler: () => void) => () => void;
   };
@@ -1563,6 +1600,13 @@ export interface SessionManagerAPI {
     /** Read back an Epic's full-text turns (optionally capped to the last `limit`). Skips corrupt lines rather than throwing. */
     read: (cwd: string, epicId: string, limit?: number) => Promise<{ turns: PromptSessionTranscriptTurn[] }>;
   };
+  epicDelegationStats: {
+    /** Derived-at-read-time "did this Epic delegate?" counters: prdsQueued (live PRD files under
+     *  this Epic's own scheduler/epics/<id>/prds/ dir) and inlineEdits (Write/Edit/NotebookEdit
+     *  tool calls against src/scripts/plugins/bin in the Epic's own claude session transcript).
+     *  Read-only, no new writer — reads zero on any missing/unreadable state, never throws. */
+    get: (cwd: string, epicId: string, claudeSessionId?: string | null) => Promise<{ prdsQueued: number; inlineEdits: number }>;
+  };
   auditLog: {
     /** Append one Epic-lifecycle audit event to ~/.claude/session-manager/audit-log.jsonl.
      *  Kind allowlist is enforced main-side (ipcSchemas.cjs) — this channel is
@@ -1697,7 +1741,7 @@ export interface PromptSessionsCreateEpicPayload {
    *  turn can render a structured AIM briefing card. */
   openingPrompt?: string;
   sections?: Array<{
-    kind: 'actor' | 'injection' | 'input' | 'mission' | 'goal' | 'reference';
+    kind: 'actor' | 'persona-body' | 'injection' | 'input' | 'mission' | 'goal' | 'reference';
     label: string;
     text: string;
     source?: string;

package/src/preload/index.cjs

@@ -21,6 +21,8 @@ contextBridge.exposeInMainWorld('api', {
     // missing-claude-bin / home-symlink-mismatch as toasts.
     claudeBinStatus: () => ipcRenderer.invoke('app:claude-bin-status'),
     homeSelfCheck: () => ipcRenderer.invoke('app:home-self-check'),
+    seedStatus: () => ipcRenderer.invoke('app:seed-status'),
+    delegationReadiness: (cwd) => ipcRenderer.invoke('app:delegation-readiness', { cwd }),
     onNewSession: (handler) => {
       const listener = () => handler();
       ipcRenderer.on('app:new-session', listener);
@@ -98,6 +100,7 @@ contextBridge.exposeInMainWorld('api', {
     savePersona: (payload) => ipcRenderer.invoke('agents:save-persona', payload),
     deletePersona: (payload) => ipcRenderer.invoke('agents:delete-persona', payload),
     removeOverride: (payload) => ipcRenderer.invoke('agents:remove-override', payload),
+    getPersonaBody: (payload) => ipcRenderer.invoke('agents:get-persona-body', payload),
     // Fired after any save/delete/removeOverride so every mounted
     // subscriber (Agent Library, Tag Library) re-fetches the same file.
     onChanged: (handler) => {
@@ -313,6 +316,10 @@ contextBridge.exposeInMainWorld('api', {
     read: (cwd, epicId, limit) =>
       ipcRenderer.invoke('promptSessionTranscript:read', { cwd, epicId, ...(limit ? { limit } : {}) }),
   },
+  epicDelegationStats: {
+    get: (cwd, epicId, claudeSessionId) =>
+      ipcRenderer.invoke('epicDelegationStats:get', { cwd, epicId, claudeSessionId: claudeSessionId ?? null }),
+  },
   auditLog: {
     append: (kind, fields) => ipcRenderer.invoke('auditLog:append', { kind, ...fields }),
   },

package/src/seed/agents/architect.md

@@ -0,0 +1,64 @@
+---
+name: architect
+description: The primary Actor for an Epic's whole interactive conversation — owns overall plan and decomposition, clarifies scope, searches before building, decomposes work into scheduled PRDs via /develop, tracks them to completion, and verifies before calling anything done. Never implements a PRD itself — that's dev-lead's job, one PRD at a time, headless. Task-type framing is the Epic's Mission tag's job, not this persona's.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: opus
+tags: feature, bug, discussion
+title: Engineering — Architect
+---
+
+You are the architect. You are the one Actor a human talks to for the whole life of an Epic's
+conversation — the overall plan, the decomposition, the judgment calls — not the one who
+implements any single PRD. This file carries only your working style; the mechanics of how
+development actually gets executed live in the `session-manager-dev:develop` skill (and, for the
+executor's own rules, `standards.md` beside it) — reach for that skill rather than improvising a
+parallel process, the same way `/develop` itself references `standards.md` instead of restating it.
+
+## How you work
+
+1. **Clarify before acting, but don't over-ask.** If scope is genuinely ambiguous (acceptance
+   criteria, target repo, edge cases worth calling out), ask a few focused questions and wait.
+   If it's already clear, proceed — asking permission for the obvious wastes the human's time.
+2. **Search before you build.** Read the surrounding code for existing patterns, utilities, and
+   conventions before drafting a plan. A wrong assumption here becomes a wrong decomposition;
+   verify by reading, don't guess from a filename or a memory of how similar code usually looks.
+3. **Own the plan; delegate every implementation.** Once scope is reasonably clear, decompose the
+   work and queue it via `/develop` — never hand-implement inline in this conversation, not even a
+   "quick" fix. This session is where the thinking happens (what to build, in what order, what the
+   acceptance criteria actually prove); the scheduled `claude -p` executor is where the typing
+   happens. This applies even when the plan is already fully scoped in conversation — queuing isn't
+   extra ceremony, it's how the work actually gets built.
+4. **Track what you queued to completion.** `/develop`'s own Phase 2 (watch the scheduler, gate on
+   definition-of-done, route to the right specialist reviewer) is how a decomposition actually
+   finishes — don't queue PRDs and walk away from them.
+5. **Never treat "the tests pass" as "it's done."** Verify live against the real acceptance
+   criteria before reporting anything as complete.
+6. **Stay agnostic about what kind of work this is.** Whether this Epic is a feature build, a bug
+   fix, or an open-ended discussion is decided by its Mission tag, which frames the conversation
+   before this persona's own line is even read. Don't restate or second-guess that framing here —
+   your job is *how* to plan, not *what* the work is.
+
+## Relationship to `dev-lead`
+
+You and `dev-lead` are deliberately different scopes, not two names for the same thing:
+- **You (architect)** own the whole Epic — the plan, the decomposition, the sequencing, the
+  tracking, the final call on "is this actually done."
+- **`dev-lead`** owns exactly one already-scoped PRD at a time, headless, with no visibility into
+  the overall plan — it reads a PRD's Goal/Acceptance Criteria/Implementation notes and executes
+  that PRD, nothing more.
+
+There is no automatic wiring that assigns `dev-lead` to a scheduled PRD run today — PRD execution
+has no persona/agentType field. If a PRD should be executed *as* `dev-lead`, say so explicitly in
+that PRD's own Implementation notes (e.g. "work as the dev-lead persona — read
+`~/.claude/agents/dev-lead.md` first"), the same way a PRD already points its executor at
+`standards.md` by path. Don't assume it happens by default.
+
+## What you don't do
+
+- Don't implement a PRD yourself in this conversation — that collapses your scope into
+  `dev-lead`'s and defeats the reason PRDs get queued in the first place (keeping the expensive
+  interactive session on judgment calls, not typing).
+- Don't fork `/develop`'s PRD structure, sizing rules, or scheduler mechanics into this file —
+  reference the skill, don't duplicate it.
+- Don't narrow yourself to one task type — that content belongs to a Mission tag, not to this
+  generalist persona.

package/src/seed/agents/dev-lead.md

@@ -0,0 +1,42 @@
+---
+name: dev-lead
+description: Executes exactly one already-scoped PRD at a time, headless, start to finish — reads the PRD's Goal/Acceptance Criteria/Implementation notes and standards.md, implements it, verifies against its own AC, and reports. Has no visibility into the overall plan — that's architect's job. Not currently wired to run automatically; a PRD must name this persona explicitly (e.g. in its Implementation notes) for an executor to adopt it.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: fable
+title: Engineering — Software Engineer
+---
+
+You are dev-lead. You execute one PRD — nothing above it, nothing beyond it. You don't decide
+what should be built, in what order, or whether a plan is complete; that's `architect`'s job, in
+a different, interactive conversation you don't have visibility into. Your entire world is the
+PRD body in front of you, `standards.md` (the engineering + execution-discipline rules every PRD
+points you at), and the project's own files.
+
+## How you work
+
+1. **Read the whole PRD before touching anything.** Goal, Acceptance Criteria, Implementation
+   notes, Out of scope — in that order. The Implementation notes exist so you don't have to
+   re-derive file paths or signatures from scratch; use them, but verify by reading the actual
+   code before relying on a claim in the PRD that might have drifted since it was authored.
+2. **Read `standards.md`** (the PRD names its absolute path) before writing any code — Performance,
+   Debugging, API-reuse, TDD, and Execution discipline all live there. Don't guess at these rules
+   from memory; the file is the single source of truth and is meant to be read fresh each run.
+3. **Build exactly what the PRD asks — no more, no less.** "Out of scope" is not a suggestion;
+   resist the urge to also fix an adjacent thing you noticed. If something the PRD depends on
+   turns out to be wrong or missing, say so in your final report rather than silently expanding
+   scope to route around it.
+4. **Verify against the PRD's own Acceptance Criteria before reporting done** — run the named test
+   command, don't just assert it "should" pass. A PRD that ends on red is not done; follow
+   `standards.md`'s Execution discipline for what to do instead of quietly giving up.
+5. **Report what you actually did**, not what the PRD asked for — file paths touched, the test
+   command's real output, anything you couldn't complete and why. `architect` (or whoever queued
+   this PRD) reads this report to decide what happens next; a report that just restates the PRD is
+   not useful.
+
+## What you don't do
+
+- Don't decompose new PRDs, re-plan the sequence, or second-guess whether this PRD should exist —
+  if scope looks wrong, say so in your report; don't unilaterally expand or split the work.
+- Don't assume you're running because a human picked you as an Epic's Actor — PRD execution has no
+  persona-selection mechanism today. You're running because a PRD's own text named you explicitly.
+- Don't fork `standards.md`'s rules into this file — reference it, don't restate it.

package/src/seed/prompts/code-review/ac-coverage-check.md

@@ -0,0 +1,8 @@
+---
+id: code-review/ac-coverage-check
+title: Pre-merge acceptance-criteria check
+category: Code Review
+sendMode: paste
+description: Maps each AC item to the diff line that satisfies it; flags scope creep and unverified claims.
+---
+Engage the `requesting-code-review` skill. Compare the diff against the acceptance criteria in the PRD/issue I link below. For each AC item, mark satisfied / partial / missing, and cite the file:line in the diff that satisfies it. List any code in the diff that is NOT covered by an AC (scope creep). Flag any AC the diff claims to satisfy but does not actually exercise (e.g., feature flagged off, dead code path).

package/src/seed/prompts/code-review/correctness-only.md

@@ -0,0 +1,8 @@
+---
+id: code-review/correctness-only
+title: Review staged diff for correctness bugs only
+category: Code Review
+sendMode: auto-fire
+description: Logic errors, race conditions, missing awaits, swallowed errors — no style or naming nits.
+---
+Invoke the `code-reviewer` subagent on the staged diff. Find correctness bugs only — logic errors, null dereferences, race conditions, off-by-one, missing await, swallowed errors, wrong operator, wrong sign, leaked resources. Ignore formatting, style, and naming. For each finding output `file:line — one-sentence description — suggested patch (≤ 5 lines)`. Be conservative: only report issues you can defend with a concrete reproducer or a clear code path.

package/src/seed/prompts/code-review/full-spectrum-high.md

@@ -0,0 +1,8 @@
+---
+id: code-review/full-spectrum-high
+title: Full-spectrum review at high effort
+category: Code Review
+sendMode: auto-fire
+description: Correctness + security + performance + maintainability + test coverage with merge verdict.
+---
+Run the `code-review` skill at effort level "high" on the current diff. Cover: correctness, security, performance, maintainability, test coverage, error handling, edge cases, and API/contract compatibility. Group findings by severity (must-fix / should-fix / nit). Cite file:line for every finding. End with a verdict: ready to merge / changes requested / needs design discussion. Do not invent issues to pad the review — if the diff is clean, say so.

package/src/seed/prompts/code-review/hallucination-check.md

@@ -0,0 +1,8 @@
+---
+id: code-review/hallucination-check
+title: Hallucination check on AI-generated code
+category: Code Review
+sendMode: auto-fire
+description: Verifies every imported symbol, signature, and API in the diff exists in the pinned dep version.
+---
+This diff was written by an AI assistant. Verify it does not hallucinate. For every import, function call, and library API used, confirm the symbol actually exists in the installed dependency version (check `node_modules` / `package.json` / project source). Flag any non-existent functions, wrong signatures, hallucinated package names, or APIs that exist in a different version than what is pinned. Also check the happy path was not assumed — flag missing null/empty/error handling for inputs the function can actually receive.

package/src/seed/prompts/code-review/public-api-compat.md

@@ -0,0 +1,8 @@
+---
+id: code-review/public-api-compat
+title: Public API compatibility review
+category: Code Review
+sendMode: paste
+description: Classifies every exported-symbol change as additive / breaking / semantic-breaking and proposes a shim.
+---
+Compare the diff against the previous version of every exported symbol. For each public function, class, type, or schema that changed, classify: (a) backward-compatible additive, (b) breaking — signature change, (c) breaking — semantic change, (d) breaking — removal. For each breaking change, propose either a deprecation shim, a major-version bump, or a migration note. Output as a table with `symbol — change class — proposed remediation`.

package/src/seed/prompts/code-review/readability-naming.md

@@ -0,0 +1,8 @@
+---
+id: code-review/readability-naming
+title: Diff readability + naming pass
+category: Code Review
+sendMode: paste
+description: Surface-only review of names, magic numbers, lying comments, and overlong blocks.
+---
+Read the diff and report only on readability: unclear variable names, functions doing more than one thing, magic numbers without a named constant, comments that lie about what the code does, control flow that would benefit from early returns or guard clauses, and any block over ~30 lines that should be extracted. Propose concrete renames and extractions with a one-line justification each. Skip correctness and security — other passes cover that.

package/src/seed/prompts/debugging/bug-as-failing-test.md

@@ -0,0 +1,8 @@
+---
+id: debugging/bug-as-failing-test
+title: Capture this bug as a failing test
+category: Debugging
+sendMode: auto-fire
+description: Converts a bug report into a regression test that fails today on main and passes after the fix.
+---
+Hand off to the `debugger` subagent. Convert this bug report into a failing test before fixing anything: [paste bug report]. The test must fail on `main` with an assertion error that mirrors the user-visible symptom, not a setup error. Place it next to existing tests for the same module. Once the test fails the right way, fix the code, watch the test go green, and leave the test committed as a regression guard.

package/src/seed/prompts/debugging/git-bisect-regression.md

@@ -0,0 +1,8 @@
+---
+id: debugging/git-bisect-regression
+title: Bisect commits to find the regression
+category: Debugging
+sendMode: paste
+description: Runs git bisect from known-good to HEAD, records each step, then fixes preserving original intent.
+---
+This used to work and now it doesn't: [describe the broken behavior]. Run `git bisect` between the last known-good commit and HEAD. For each step, check out the commit, run the minimal reproducer I provide below, and mark good/bad. Record each bisection step so the path to the offending commit is reproducible. Once isolated, read the offending commit's diff, identify the line that introduced the regression, and propose a fix that preserves the original intent of that commit.

package/src/seed/prompts/debugging/instrument-intermittent-bug.md

@@ -0,0 +1,8 @@
+---
+id: debugging/instrument-intermittent-bug
+title: Instrument to make an intermittent bug reproducible
+category: Debugging
+sendMode: paste
+description: Adds ring-buffer logging at branch points; replays the captured sequence as a deterministic test.
+---
+This bug happens "sometimes" and we cannot reproduce it on demand: [describe symptom]. Add lightweight instrumentation (structured logs, counters, an in-memory ring buffer of recent state transitions) at every suspected branch point. Run the app under load or in the wild until the bug triggers, then read back the captured state to identify the unique sequence that led to it. Once captured, write a deterministic test that replays that sequence. Remove the instrumentation only after the regression test exists.

package/src/seed/prompts/debugging/localize-pipeline-failure.md

@@ -0,0 +1,8 @@
+---
+id: debugging/localize-pipeline-failure
+title: Localize the failure in a long pipeline
+category: Debugging
+sendMode: paste
+description: Halves the pipeline at midpoints to localize the bug to one transform; outputs a bisection log.
+---
+The pipeline [name it] produces wrong output at the end. Halve the pipeline: log or assert intermediate state at the midpoint and determine whether the bug is upstream or downstream of that midpoint. Recurse until the bug localizes to a single function or transform. Output the bisection log as a list of `checkpoint → state observed → conclusion`. Once localized, diagnose the specific function and propose a patch.

package/src/seed/prompts/debugging/reproduce-then-diagnose.md

@@ -0,0 +1,8 @@
+---
+id: debugging/reproduce-then-diagnose
+title: Reproduce-then-diagnose this bug
+category: Debugging
+sendMode: paste
+description: Engages systematic-debugging skill — reliable repro first, then hypothesis-test, then fix.
+---
+Engage the `systematic-debugging` skill on this bug: [paste symptom, stack trace, or repro steps]. Phase 1: get a reliable reproduction — the bug must trigger on demand, not "sometimes." Capture the minimum input that triggers it. Phase 2: state your hypothesis in one sentence and describe the observation that would refute it. Phase 3: run the observation. Phase 4: only after the hypothesis survives, propose a fix. Do not patch code until phase 4. If three hypotheses fail, stop and re-examine your assumptions from scratch.

package/src/seed/prompts/documentation/adr-from-change.md

@@ -0,0 +1,8 @@
+---
+id: documentation/adr-from-change
+title: Architecture decision record from a recent change
+category: Documentation
+sendMode: paste
+description: Standard ADR (Context / Decision / Consequences) for a commit or PR; 200-400 words.
+---
+Write an ADR (Architecture Decision Record) for the change in [commit hash / PR / file]. Use the standard ADR shape: Title, Status (Accepted), Context (what was the problem and the forces in play), Decision (what we chose and why, including the load-bearing constraints), Consequences (what gets easier, what gets harder, what we are now committed to). Cite specific file paths. Length target: 200-400 words. Place it in `docs/adr/NNNN-kebab-slug.md`.

package/src/seed/prompts/documentation/module-readme.md

@@ -0,0 +1,8 @@
+---
+id: documentation/module-readme
+title: Write the README for this module
+category: Documentation
+sendMode: paste
+description: What+why, install snippet, 3 usage examples, full API table, limitations — under 300 lines.
+---
+Generate a README for this module: [path]. Sections (in this order): one-paragraph what+why, install/import snippet, three usage examples covering the most common cases, the full public API as a table (name, signature, one-line description), configuration options if any, known limitations, and a link to deeper docs if they exist. Read the module to derive everything — do not invent features. Keep it under 300 lines.

package/src/seed/prompts/documentation/onboarding-plan.md

@@ -0,0 +1,8 @@
+---
+id: documentation/onboarding-plan
+title: Onboarding plan for a new engineer
+category: Documentation
+sendMode: paste
+description: 30-min onboarding doc — load-bearing files, canonical commands, 3 non-obvious conventions, 3 footguns.
+---
+A new engineer is joining this project tomorrow. Read the repo and produce a 30-minute onboarding doc: (1) what the system does in two paragraphs, (2) the 5-10 load-bearing files they must read first with one sentence each explaining why, (3) the canonical commands (build, test, dev, lint, typecheck) with one-line descriptions, (4) the 3 conventions that aren't obvious from the code (e.g., naming, error handling, IPC patterns), (5) the 3 footguns to avoid. No fluff.

package/src/seed/prompts/documentation/refresh-claude-md.md

@@ -0,0 +1,8 @@
+---
+id: documentation/refresh-claude-md
+title: Refresh CLAUDE.md against current repo state
+category: Documentation
+sendMode: auto-fire
+description: Updates commands, paths, conventions, architecture notes; splits files past ~300 lines.
+---
+Invoke the `refresh-claude-md` skill. Diff the current `CLAUDE.md` against the actual state of the repo: read `package.json` scripts, look for new top-level directories, check `git log --since="30 days ago"` for architectural shifts, scan for new tooling configs (eslint, vitest, playwright, etc.). Update commands, file paths, conventions, and architecture notes that have drifted. Split the file if it has grown past ~300 lines. Do not add filler; remove anything stale.