pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/skills/reflect/scripts/claude-project-dir.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Print Claude Code's transcripts directory for this session.
+//
+//   node claude-project-dir.mjs [workspace]
+//
+// The directory is <config>/projects/<name>, where <config> is
+// $CLAUDE_CONFIG_DIR or ~/.claude. Claude Code sets $CLAUDE_CODE_SESSION_ID in
+// its shell, so the directory holding <id>.jsonl or <id>/<id>.jsonl is this
+// session's, wherever the shell has moved since; only names are read. With a
+// workspace argument, or without a session id, <name> is derived from the
+// workspace, the current directory by default, which must be the directory the
+// session started in. Claude Code
+// derives <name> from that path by turning every character other than an ASCII
+// letter or digit into "-". A name longer than 200 characters keeps its first 200 and gains "-"
+// and a base-36 hash of the path. $CLAUDE_CODE_PROJECT_DIR_NAME replaces <name>
+// when $CLAUDE_CONFIG_DIR is set too and the name is 1 to 64 letters, digits,
+// "_" or "-" other than a Windows reserved device name. If the derived
+// directory is missing, the one directory that shares the first 200 characters
+// is taken instead, so a hash that changes in a later Claude Code release still
+// resolves. Exits 1 when no directory exists.
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const MAX_NAME = 200;
+// The names Claude Code 2.1.296 accepts from CLAUDE_CODE_PROJECT_DIR_NAME.
+const CHOSEN_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const RESERVED_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+// A session id names a file, so it never holds a path separator or "..".
+const SESSION_ID = /^[A-Za-z0-9-]+$/;
+
+// Claude Code 2.1.296's string hash, a 32-bit Java-style hash.
+function hash(text) {
+  let h = 0;
+  for (let i = 0; i < text.length; i++) h = ((h << 5) - h + text.charCodeAt(i)) | 0;
+  return h;
+}
+
+export function projectDirName(workspace) {
+  const name = workspace.replace(/[^a-zA-Z0-9]/g, "-");
+  if (name.length <= MAX_NAME) return name;
+  return `${name.slice(0, MAX_NAME)}-${Math.abs(hash(workspace)).toString(36)}`;
+}
+
+function sessionDir(projects, sessionId) {
+  if (!sessionId || !SESSION_ID.test(sessionId) || !existsSync(projects)) return null;
+  const dirs = readdirSync(projects, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(projects, entry.name));
+  // A bare <id>/ is not enough: Claude Code's Workflow tool creates one under
+  // the shell's current project, which may be another project.
+  const transcript = (dir) =>
+    existsSync(join(dir, `${sessionId}.jsonl`)) || existsSync(join(dir, sessionId, `${sessionId}.jsonl`));
+  return dirs.find(transcript) ?? null;
+}
+
+export function projectDir(
+  workspace,
+  {
+    config = process.env.CLAUDE_CONFIG_DIR,
+    home = process.env.HOME,
+    sessionId = process.env.CLAUDE_CODE_SESSION_ID,
+    chosenName = process.env.CLAUDE_CODE_PROJECT_DIR_NAME,
+  } = {},
+) {
+  const projects = join(config || join(home || homedir(), ".claude"), "projects");
+  const session = sessionDir(projects, sessionId);
+  if (session) return session;
+  const chosen = config ? chosenName : undefined;
+  const valid = chosen && CHOSEN_NAME.test(chosen) && !RESERVED_NAME.test(chosen);
+  const name = valid ? chosen : projectDirName(workspace);
+  const derived = join(projects, name);
+  if (existsSync(derived)) return derived;
+  if (name.length <= MAX_NAME) return null;
+  const prefix = `${name.slice(0, MAX_NAME)}-`;
+  const matches = existsSync(projects) ? readdirSync(projects).filter((entry) => entry.startsWith(prefix)) : [];
+  return matches.length === 1 ? join(projects, matches[0]) : null;
+}
+
+// Claude Code names a session by its start directory's real path, and keeps the
+// path as given when that directory has since been removed.
+function resolvedPath(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return resolve(path);
+  }
+}
+
+function main(argv) {
+  if (argv.length > 1) {
+    console.error("usage: claude-project-dir.mjs [workspace]");
+    return 2;
+  }
+  const workspace = argv[0] ? resolvedPath(argv[0]) : process.cwd();
+  // A directory argument asks for that workspace's sessions, not this session's.
+  const dir = projectDir(workspace, argv[0] ? { sessionId: null, chosenName: null } : {});
+  if (!dir) {
+    console.error(`no Claude Code transcripts directory for ${workspace}`);
+    return 1;
+  }
+  console.log(dir);
+  return 0;
+}
+
+// node leaves argv[1] unresolved and may set it to a non-file (`node -e ... arg`).
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/plugins/pstack/skills/reflect/scripts/find-transcript.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// Locate the transcript whose opening user prompt carries a fragment.
+//
+//   node find-transcript.mjs <transcripts-dir> <opening-prompt-fragment> [workspace]
+//
+// Prints the newest matching path, or exits 1 with "no transcript". Covers
+// Claude Code's three layouts under one per-project directory (flat
+// <id>.jsonl, nested <id>/<id>.jsonl, subagent <id>/subagents/<child>.jsonl)
+// Pi's <iso>_<id>.jsonl under its per-cwd sessions directory, and GitHub
+// Copilot's <id>/events.jsonl under its session-state directory, told apart by
+// Pi's session header line and Copilot's session.start event. Each candidate is
+// streamed line by line; a Claude Code or Copilot transcript is abandoned at its
+// first typed user record. Copilot searches compare the session header's cwd
+// with the workspace (the current directory by default) before reading user
+// messages. A Pi session is read to its last entry to find
+// the active branch. A Codex rollout is refused by name rather than read as an
+// empty Claude transcript.
+import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+// readline also breaks on U+2028 and U+2029, which JSON leaves unescaped.
+async function* jsonlLines(stream) {
+  let rest = "";
+  for await (const chunk of stream) {
+    const parts = (rest + chunk).split("\n");
+    rest = parts.pop();
+    yield* parts;
+  }
+  if (rest) yield rest;
+}
+
+// Session cleanup can delete a transcript or its session directory while a
+// search runs. Anything under the root that vanishes after it was listed is
+// skipped; a missing root still throws.
+export function rethrowUnlessRemoved(error) {
+  if (error.code !== "ENOENT") throw error;
+}
+
+export function candidates(projectsDir, maxDepth = 2) {
+  const files = [];
+  const walk = (dir, depth) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(full);
+      else if (entry.isDirectory() && depth < maxDepth) {
+        try {
+          walk(full, depth + 1);
+        } catch (error) {
+          rethrowUnlessRemoved(error);
+        }
+      }
+    }
+  };
+  walk(projectsDir, 0);
+  return files
+    .flatMap((path) => {
+      const stat = statSync(path, { throwIfNoEntry: false });
+      return stat ? [{ path, mtime: stat.mtimeMs }] : [];
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+}
+
+function text(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((block) => typeof block?.text === "string")
+      .map((block) => block.text)
+      .join("\n");
+  }
+  return null;
+}
+
+// `user` records Claude Code writes for a local command (/clear, !cmd) and its
+// output, not a prompt the user typed. A skill invocation leads with
+// <command-message> and is kept: its <command-args> carry what the user typed.
+const LOCAL_COMMAND = /^\s*<(?:command-name|local-command-stdout|bash-input)>/u;
+
+// A Pi session opens with this header line; Claude Code transcripts never do.
+const isPiHeader = (record) =>
+  record?.type === "session" && Number.isInteger(record.version) && typeof record.cwd === "string";
+// A Codex rollout opens with its session metadata.
+const isCodexHeader = (record) => record?.type === "session_meta";
+
+// A Copilot events.jsonl opens with this event and records each prompt the
+// user typed as a `user.message` event.
+const isCopilotHeader = (record) => record?.type === "session.start" && typeof record.data === "object";
+
+async function copilotOpening(head, records, workspace) {
+  if (workspace !== undefined) {
+    const cwd = head.data?.context?.cwd;
+    if (typeof cwd !== "string" || !isAbsolute(cwd)) return null;
+    try {
+      if (realpathSync(cwd) !== realpathSync(workspace)) return null;
+    } catch {
+      // A removed or inaccessible workspace cannot identify this session.
+      return null;
+    }
+  }
+  for await (const record of records) {
+    if (record?.type !== "user.message") continue;
+    const prompt = text(record.data?.content);
+    if (prompt) return prompt;
+  }
+  return null;
+}
+
+async function* parsed(lines) {
+  for await (const line of lines) {
+    try {
+      yield JSON.parse(line);
+    } catch {}
+  }
+}
+
+async function* prepend(head, rest) {
+  yield head;
+  yield* rest;
+}
+
+// A Claude Code transcript opens with the first prompt the user typed.
+async function claudeOpening(records) {
+  for await (const record of records) {
+    if (record?.type !== "user" || record.isMeta) continue;
+    const prompt = text(record.message?.content);
+    if (prompt && !LOCAL_COMMAND.test(prompt)) return prompt;
+  }
+  return null;
+}
+
+// Pi branches in place: every entry is appended to one file and linked to its
+// parent by id, and the last entry is the current leaf. The opening prompt is
+// the first user message on the path from that leaf to its root, which may not
+// be the first one in file order.
+async function piOpening(records) {
+  const entries = new Map();
+  let leaf = null;
+  for await (const record of records) {
+    if (typeof record?.id !== "string") continue;
+    const isUser = record.type === "message" && record.message?.role === "user";
+    entries.set(record.id, { parentId: record.parentId ?? null, prompt: isUser ? text(record.message.content) || null : null });
+    leaf = record.id;
+  }
+  let prompt = null;
+  const seen = new Set();
+  for (let id = leaf; entries.has(id) && !seen.has(id); id = entries.get(id).parentId) {
+    seen.add(id);
+    prompt = entries.get(id).prompt ?? prompt;
+  }
+  return prompt;
+}
+
+// Readers by opening record. Claude Code writes no header, so its row is last
+// and takes every file the others do not claim.
+const READERS = [
+  [isPiHeader, (head, rest) => piOpening(rest)],
+  [isCopilotHeader, (head, rest, path, workspace) => copilotOpening(head, rest, workspace)],
+  [isCodexHeader, (head, rest, path) => {
+    throw new Error(`${path} is a Codex rollout, which find-transcript does not read; pass the session digest instead`);
+  }],
+  [() => true, (head, rest) => claudeOpening(prepend(head, rest))],
+];
+
+export async function openingPrompt(path, workspace) {
+  const stream = createReadStream(path, { encoding: "utf8" });
+  try {
+    const records = parsed(jsonlLines(stream));
+    const { value: head, done } = await records.next();
+    if (done) return null;
+    const [, read] = READERS.find(([matches]) => matches(head));
+    return await read(head, records, path, workspace);
+  } finally {
+    stream.destroy();
+  }
+}
+
+export async function findTranscript(projectsDir, fragment, workspace = process.cwd()) {
+  for (const { path } of candidates(projectsDir)) {
+    try {
+      const prompt = await openingPrompt(path, workspace);
+      if (prompt?.includes(fragment)) return path;
+    } catch (error) {
+      rethrowUnlessRemoved(error);
+    }
+  }
+  return null;
+}
+
+async function main(argv) {
+  const [projectsDir, fragment, workspace] = argv;
+  if (!projectsDir || !fragment || argv.length > 3) {
+    console.error("usage: find-transcript.mjs <transcripts-dir> <opening-prompt-fragment> [workspace]");
+    return 2;
+  }
+  const path = await findTranscript(projectsDir, fragment, workspace);
+  if (!path) {
+    console.error(`no transcript under ${projectsDir} opens with ${JSON.stringify(fragment)}`);
+    return 1;
+  }
+  console.log(path);
+  return 0;
+}
+
+// node leaves argv[1] unresolved and may set it to a non-file (`node -e ... arg`).
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/plugins/pstack/skills/setup-pstack/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: setup-pstack
+description: Configure which models pstack uses per role. Detects available models and writes the current runtime's override sheet. Use for /setup-pstack, "configure pstack models", changing pstack's model choices, or turning the SessionStart hook on or off.
+---
+
+# Setup pstack
+
+On Codex, read the [platform mapping](../poteto-mode/references/codex-tools.md), including its per-skill notes, before following this skill.
+
+On GitHub Copilot, read the [platform mapping](../poteto-mode/references/copilot-tools.md), including its per-skill notes, before following this skill.
+
+On Muse, read the [platform mapping](../poteto-mode/references/muse-tools.md), including its per-skill notes, before following this skill.
+
+On Antigravity, read the [platform mapping](../poteto-mode/references/agy-tools.md), including its per-skill notes, before following this skill.
+
+Write the current runtime's per-role model override sheet. Each pstack skill names a default model inline; the override sheet adapts those defaults to the models you actually have access to.
+
+On any runtime other than Claude Code, read [Other runtimes](references/runtimes.md) first. Its table gives the sheet path, how the sheet loads, and how to list models, and your runtime's section says which steps change. The rest of this file describes Claude Code.
+
+On Claude Code the config directory is `$CLAUDE_CONFIG_DIR` when that variable is set and `~/.claude` otherwise. This skill calls it `<config>`, and the sheet is `<config>/pstack-models.md`. Claude Code has no auto-applied "rules" mechanism like Cursor's `.mdc`, so inclusion is explicit: the user adds a line to `<config>/CLAUDE.md` (or their project `CLAUDE.md`) such as:
+
+```text
+@<config>/pstack-models.md
+```
+
+with `<config>` written as the resolved path, so the file is loaded as context for every session.
+
+## Steps
+
+### 1. Detect available models
+
+Enumerate the model names the `Agent` tool's `model` parameter accepts in this session. That is the dependable source. On Claude Code they are the family names listed in [Models](#models) below, each running that family's current model, and a full model ID is rejected. The default panel is listed there too. The panel is chosen for cross-family diversity. Ask the user to confirm or paste any additional slugs they want available. Never write a real slug you have not confirmed is available. The aliases `inherit-parent` and `auto` are always valid even though they are not detected slugs. Both mean the role runs on the parent session's model, which the `Agent` call expresses by omitting `model`.
+
+### 2. Load current state
+
+The default role-to-model mapping is the rule shape shown in the Write the override sheet step below. If the current runtime's sheet already exists, read it and treat its values as the current choices. Otherwise start from those defaults. A line whose role is not in that shape, such as `how critics`, is from a retired role. Drop it. An older sheet may name full model IDs that start with `claude-`, which the `Agent` tool rejects. Replace each with its family name, the word after `claude-`.
+
+### 3. Map and confirm
+
+Show every role with its current model, marking any real slug not in the detected set as needing a choice. Also list each line step 2 dropped or rewrote. Ask whether to accept as-is or change specific roles, offering the detected models plus `inherit-parent` and `auto` as the options. Prefer `AskUserQuestion` over free text. For panel roles (arena runners, architect runners, interrogate reviewers) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. `arena cross-judge pool` is also a list, but Arena runs one judge. It tries only values from a family other than the parent's, in list order, so order it by preference. An `inherit-parent` or `auto` value never judges. `swarm workers` is the default model for every worker unless a race or comparison assigns another model per arm.
+
+Then ask for the default reasoning effort, the `default effort` line. It is `session`, which keeps the parent session's effort, or one of the levels in [Models](#models). Start from the default listed there. Every role value without a suffix runs at it. Then ask whether any role should run at another level. A role value may carry one after its slug, as in `<slug> @xhigh`; panel entries take their own, as in `<slug> @xhigh, <slug> @max`. Each level is passed as the dispatch's effort, so the choice holds without changing the session. Leave the suffix off for the default effort.
+
+### 4. Choose whether the session hook routes tasks
+
+On Claude Code, the plugin's `SessionStart` hook injects the poteto-mode mandate on startup, resume, clear, and compact. Ask whether to keep the hook. The default is on. The answer is the `session hook` line in the current runtime's sheet: `on` or `off`. With no sheet or no line, the hook injects. The line is inert on other runtimes without a pstack routing hook.
+
+### 5. Validate
+
+Every real slug written must be in the detected set. `inherit-parent` and `auto` always pass. Validate the slug without any `@<level>` suffix, and the level against the effort levels in [Models](#models). The `default effort` value is one of those levels or `session`. If a chosen real slug or level is not available, stop and ask again.
+
+### 6. Write the override sheet
+
+Write the current runtime's sheet with the shape below. Overwrite the whole file so re-runs stay idempotent.
+
+```markdown
+# pstack model configuration
+
+Per-role model overrides for pstack skills. Each pstack SKILL.md names its defaults in a Models section; the values here override those defaults. Delete a line to fall back to the skill default. A value of `inherit-parent` or `auto` runs that role on the parent session's model (the `Agent` call omits `model`); an alias entry in a panel list still counts toward that panel's fan-out. A model may carry a reasoning effort, as in `opus @xhigh` (levels: low, medium, high, xhigh, max); the role's subagent then runs at that level, each entry of a panel list on its own. `default effort` sets the level for a value without one; `session` uses the runtime's platform mapping to start from the parent session's effort. On Codex this requires active-turn metadata or an explicit effort choice. `session hook: off` stops the supported runtime's pstack routing hook from injecting the poteto-mode mandate; any other value, or no line, leaves it on.
+
+feature, refactoring: sonnet
+bug-fix: opus
+perf-issue: opus
+hillclimb: opus
+judgment and prose: opus
+strongest judgment: fable
+how explorer: opus
+how explainer: opus
+why investigators: opus
+why synthesizer: opus
+reflect tooling: opus
+reflect judgment, divergent, synthesizer: opus
+arena runners: opus, fable, sonnet, haiku
+arena cross-judge pool: opus, fable, sonnet, haiku
+swarm workers: opus
+architect runners: opus, fable, sonnet, haiku
+interrogate reviewers: opus, fable, sonnet, haiku
+thermos reviewers: opus
+no-comments reviewer: opus
+
+default effort: session
+session hook: on
+```
+
+### 7. Wire it in
+
+On Claude Code, if `<config>/CLAUDE.md` does not already include `<config>/pstack-models.md`, append an `@` line naming the sheet's resolved path, such as `@~/.claude/pstack-models.md`, so the model rows load on every session. If the user prefers project scope, add the include to the project's `CLAUDE.md` instead.
+
+### 8. Confirm
+
+Tell the user where the override was written, how its model rows load, and whether the plugin hook is on. Re-running this skill updates the override sheet.
+
+### 9. Offer a verification skill (optional)
+
+Check whether the project has a way to drive the real app for proof (a project `verify` or `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke [`/create-verification-skill`](../create-verification-skill/SKILL.md). On no, move on without pushing.
+
+### 10. Offer a formal verification skill (optional)
+
+Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke [`/create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md). On no, move on without pushing.
+
+## Models
+
+Stamped from `plugins/pstack/models.json` (edit there, rerun `tools/generate.mjs`).
+
+- Available Claude models: `opus`, `fable`, `sonnet`, `haiku`
+- Default panel: `opus`, `fable`, `sonnet`, `haiku`
+- Reasoning effort levels: `low`, `medium`, `high`, `xhigh`, `max`
+- Default reasoning effort: `session`
+- Single-role default: `opus`

package/plugins/pstack/skills/setup-pstack/copilot.md

@@ -0,0 +1,88 @@
+# Setup pstack on GitHub Copilot
+
+On GitHub Copilot this file replaces the model, effort, and hook questions in steps 1, 3, and 4 of [setup-pstack](SKILL.md), the sheet header in step 6, and step 7. Steps 2, 5, 8, 9, and 10 still apply. pstack ships no Copilot model defaults, so every model in the sheet comes from the user's answers. Never pick a model the user has not chosen, and never write the Claude Code names in [Models](SKILL.md#models) or step 6's values into a Copilot sheet.
+
+Run setup on a model at least as strong as gpt-5.4-mini or a Sonnet-class Claude model. On a Haiku-class model, setup picked models the user never chose in about half of the smoke runs.
+
+## Asking
+
+Copilot's `ask_user` takes one question per call with a fixed choice list. That list is a `choices` list, or one `oneOf` string property of a `requestedSchema` where `ask_user` takes an elicitation form. Its UI adds a free-text option on its own. Treat it as single-select, because the Copilot app's `ask_user` has no multi-select. Ask every model question through `ask_user` with a `choices` list. Never ask for models as one open question, such as which roles should change and to what, and never bundle two questions into one call. Emulate multi-select with sequential single-select questions, as the panel slots below do.
+
+- Do not propose, pre-select, or label any model `(Recommended)`. A first setup has no default to recommend.
+- On a re-run, put step 2's saved value for the question first, labeled `(current)`. Picking it keeps that value.
+- A typed answer counts only when it is a detected model ID or `inherit-parent`; otherwise ask the same question again.
+- An answer the user already gave in the request counts. Ask only the questions it leaves open.
+- When `ask_user` is not available (a `-p` run, or `--no-ask-user`) and a model question is still open, do not choose for the user and do not write the sheet. Tell the user to run `setup-pstack` in an interactive session, and run this session's roles as `inherit-parent`.
+
+## Current state
+
+On Copilot, step 2's saved values are the role lines the plugin hook put in context. When the context says this Copilot home has no pstack model sheet yet, or that the sheet is invalid, there are none. Read the sheet only when none of these is in context, as in a skills-only install. Do not test for the sheet or its directory with `bash`. Each such command touches a path outside the workspace and asks for access. `${COPILOT_HOME:-~/.copilot}` exists whenever Copilot runs, so do not create it.
+
+## Sheet header
+
+A Copilot sheet uses step 6's role lines and settings under this header in place of step 6's paragraph, because every role keeps a line and `check-sheet.sh` checks that:
+
+```markdown
+# pstack model configuration
+
+Per-role model choices for pstack skills on GitHub Copilot, written by setup-pstack. Every role keeps its line; rerun setup-pstack to change one. A value of `inherit-parent` or `auto` runs that role on the parent session's model (the `task` call omits `model`); an alias entry in a panel list still counts toward that panel's fan-out. A model may carry a reasoning effort, as in `gpt-5.5 @xhigh` (levels: low, medium, high, xhigh, max), which the `task` call passes as `reasoning_effort`. `default effort` sets the level for a value without one; `session` keeps the parent session's effort. `session hook: off` stops the SessionStart hook from injecting the poteto-mode mandate; any other value, or no line, leaves it on. `panel vendors: any` records that the user kept a panel whose models come from one vendor.
+```
+
+## Detect models
+
+The detected set is the `model` enum of the `task` tool, with full IDs exactly as the enum lists them. Never shorten one to a family name. If this session has no `task` tool or its enum is not visible, write `inherit-parent` for every role, skip the model questions, and tell the user to rerun `setup-pstack` in a session with the `task` tool. The Claude Code names in [Models](SKILL.md#models) and the values in step 6's sheet shape are not Copilot model IDs; never write them into a Copilot sheet.
+
+Group the detected IDs by vendor, from each ID's text before its first hyphen. `claude` is Claude, `gpt` is GPT, `gemini` is Gemini, `grok` is Grok, `kimi` is Kimi, and any other ID is Other. Keep the enum's order within a vendor.
+
+## Choosing one model
+
+Each model question below picks one value in two `ask_user` calls, so no choices list holds the whole enum:
+
+1. **Vendor.** One choice per vendor with its model count, such as `GPT (12 models)`, then `inherit-parent (run on the session's model)`. A vendor with a single model shows that model's ID instead, and picking it ends the question.
+2. **Model.** That vendor's IDs, then `Back to vendors`.
+
+When the detected set plus `inherit-parent` is 8 choices or fewer, skip the vendor step and list every ID in one question. `auto` means the same as `inherit-parent` in pstack, so it is not a separate choice; a saved `auto` shows as `auto (current)` on a re-run.
+
+## Roles by tier
+
+Each tier question below writes every role in its row. The panel row's roles each take the whole panel list.
+
+| Tier | Roles |
+| --- | --- |
+| Default | `bug-fix`, `perf-issue`, `hillclimb`, `judgment and prose`, `how explorer`, `how explainer`, `why investigators`, `why synthesizer`, `reflect tooling`, `reflect judgment, divergent, synthesizer`, `swarm workers`, `thermos reviewers`, `no-comments reviewer` |
+| Strongest | `strongest judgment` |
+| Worker | `feature, refactoring` |
+| Panel | `arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers` |
+
+## Question sequence
+
+Ask in this order. Each model question is the vendor and model pair above; every other question is one `ask_user` call.
+
+0. **Session model.** "Run every pstack role on this session's model?" with `Yes, use the session's model for every role` and `No, choose models by tier`. This is for a plan that offers one model or only automatic selection, and for anyone who wants no per-role choices. On a re-run, put the choice that matches the saved sheet first, labeled `(current)`. Yes skips questions 1 through 7 and the model detection. Set every role line to `inherit-parent`, with three `inherit-parent` entries in each panel role. Ask questions 8 and 9, then say in step 8 that the panels' diversity is reduced and that panel entries can differ only by reasoning effort. This path needs no `panel vendors: any` line, because a panel of only `inherit-parent` needs no vendor check. No answers the questions below.
+1. **Default model.** "Default model: runs <the Default row's roles>." It writes every role in the Default row.
+2. **Worker model.** "Worker model: runs <the Worker row's roles>." It writes every role in the Worker row.
+3. **Strongest model.** "Strongest model: runs <the Strongest row's roles>." It writes every role in the Strongest row.
+4. **Panel model 1 of 3**, then **panel model 2 of 3**, then **panel model 3 of 3**, as three separate questions. "Panel model N of 3: panels run one subagent per model, and models from different vendors catch different mistakes." In slots 2 and 3, list the vendors not yet in the panel first, then the rest, then `inherit-parent`. Do not offer a model already in the panel.
+5. **More panel models.** "Add a 4th panel model?" with `Done` as the first choice and `Add a 4th` second. Adding asks one more slot the same way, then asks again for a 5th. Stop offering at 5 models.
+6. **Vendor check.** When the panel's model IDs, not counting `inherit-parent`, all come from one vendor and more than one vendor is detected, ask "The panel is single-vendor (Claude), so its cross-checks share blind spots." with `Pick the panel again` and `Keep it anyway`. Picking again returns to panel model 1. `Keep it anyway` writes the line `panel vendors: any` after the `session hook` line. When only one vendor is detected, skip this question, write `panel vendors: any`, and say in step 8 that the panel's diversity is reduced. A panel of only `inherit-parent` needs no check.
+7. **Overrides.** "Override any individual role?" with `No, write the sheet (Recommended)` first, then one choice per tier row, with the row's current value in its label, as `Strongest (<its model ID>)`. Picking a row asks which of its roles to change, then asks one model for that role as in [Choosing one model](#choosing-one-model), with its value first as `(current)`. A panel role asks its list's slots as in questions 4 through 6 instead. After each override, ask this question again, until the answer is `No, write the sheet`.
+8. **Session hook.** "Keep the session hook that routes tasks to poteto-mode?" with `On (default)` and `Off`. On a re-run, the saved value comes first as `(current)`.
+9. **Default effort.** "Default reasoning effort for pstack subagents?" with `session (keep the parent's effort)` first, then `low`, `medium`, `high`, `xhigh`, and `max`. It writes the `default effort` line. On a re-run, the saved value comes first as `(current)`. Ask no per-role effort; a saved `@<level>` suffix on a role value stays as written.
+
+The panel from questions 4 through 6 writes every panel role, in slot order. On a re-run, the saved value for each tier question is the first role in its row, and for panel model N the Nth entry of the first panel role. A role whose saved value differs from its question's saved value keeps it, and question 6 shows it.
+
+## Write and check
+
+Validate as step 5 describes. Copilot's file tools expand neither `~` nor variables, so print the sheet's absolute path with `echo "${COPILOT_HOME:-$HOME/.copilot}/pstack-models.md"` in `bash`, and write the whole sheet to exactly that path in one tool call, so the write asks for path access at most once.
+
+Then run `sh <this skill's directory>/scripts/check-sheet.sh` through `bash`, with the directory's absolute path and no arguments. It checks the Copilot sheet as the plugin hook does at session start: every role has a line, every entry is `inherit-parent`, `auto`, or a model ID with an optional `@<level>`, and each panel names models from two vendors unless the sheet has `panel vendors: any`. It prints `sheet ok`, or `sheet invalid:` and each problem. On `sheet invalid`, fix those lines and write the whole sheet again, then rerun the check. The plugin hook approves the check without a prompt.
+
+For the rest of this session, use the values you just wrote; do not read the sheet back. Later sessions get them from the plugin hook and do not ask again.
+
+## Wire it in
+
+Add no include line: Copilot does not expand `@~/` paths in user instructions, and the plugin hook injects the sheet's role lines at session start. If the hook is on but this session's context lacks the routing mandate (the block that opens `You have pstack.`), another hook or a skills-only install has displaced it. Offer to append this standing instruction to `~/.copilot/copilot-instructions.md` instead:
+
+```text
+pstack: for a task that touches more than one file, changes a signature other files call, involves a design choice, or is a bug with an unknown cause or a performance issue, load the poteto-mode skill and follow it. Resolve Claude tool and model names through poteto-mode's references/copilot-tools.md; role models are in ~/.copilot/pstack-models.md.
+```

package/plugins/pstack/skills/setup-pstack/references/runtimes.md

@@ -0,0 +1,75 @@
+# Other runtimes
+
+The role lines are the same everywhere. What differs is the sheet path, how the runtime loads it, and how you list models. Detect models with the runtime's own tool and never write a slug you have not seen listed. A runtime whose subagent call has no model parameter still gets the sheet, as the record of the user's choice, and applies it where it can. The `session hook` line applies to the Claude Code, Codex, GitHub Copilot, Muse, MiniMax Code, Antigravity, OMP, and OpenCode 2 plugins and to the pstack Pi extension.
+
+`<codex-home>` is `$CODEX_HOME` when that variable is set and `~/.codex` otherwise.
+
+| Runtime | Sheet | Load | List models | Status |
+| --- | --- | --- | --- | --- |
+| Claude Code | `<config>/pstack-models.md` | `@<config>/pstack-models.md` in `<config>/CLAUDE.md` | the `Agent` tool's model parameter | verified live |
+| Codex | `<codex-home>/pstack-models.md` | model rows: paste into `<codex-home>/AGENTS.md`; hook setting: read by the plugin | your configured Codex models, see [codex-tools.md](../../poteto-mode/references/codex-tools.md#model-names) | hook contract tested; discovery verified |
+| Pi | `pstack-models.md` in the Pi agent directory, `$PI_CODING_AGENT_DIR` or `~/.pi/agent` | read by the pstack Pi extension, model rows and hook setting both; no include line | `pi --list-models`, see [pi-tools.md](../../poteto-mode/references/pi-tools.md#model-names) and its `setup-pstack` note | extension contract tested offline; live results in the repository's `docs/pi-equivalence.md` |
+| GitHub Copilot (CLI and app) | `${COPILOT_HOME:-~/.copilot}/pstack-models.md` | the plugin hook checks it and injects its role lines at session start; skills-only installs read it with `view` | the `task` tool's `model` enum, see [copilot-tools.md](../../poteto-mode/references/copilot-tools.md#model-names) | hook contract tested; CLI install smoke-tested |
+| Muse | `${XDG_CONFIG_HOME:-~/.config}/muse/pstack-models.md` | the plugin hook reads it and injects its role lines at session start, once hooks are approved; no include line | the model catalog (`muse model-profile show <model>` names each one), see [muse-tools.md](../../poteto-mode/references/muse-tools.md#model-names) | hook contract tested; plugin install verified |
+| MiniMax Code | `~/.minimax/pstack-models.md`, even when `MINIMAX_DATA_DIR` moves MiniMax's data directory, since MiniMax Code withholds that variable from hooks and its `bash` tool | model rows: read by the agent before a role-model skill, or paste into `AGENTS.md` in MiniMax Code's data directory; hook setting: read by the plugin | `mcode provider list` or the `model` slash command, see [minimax-tools.md](../../poteto-mode/references/minimax-tools.md#model-names) | hook contract tested; plugin load smoke-tested on 0.7.4; no live session |
+| Kimi Code CLI | `<KIMI_CODE_HOME>/pstack-models.md`, or `~/.kimi-code/pstack-models.md` when unset | read by the agent before a role-model skill; no hook setting | the `Agent` tool's model parameter when available, see [kimi-tools.md](../../poteto-mode/references/kimi-tools.md#model-names) | installation and synthetic-provider context delivery checked on Kimi 2.4.1 for macOS; model compliance untested |
+| Antigravity (`agy`) | `~/.gemini/config/pstack-models.md` | model rows: read by the agent before a role-model skill, or paste into `~/.gemini/config/AGENTS.md`; hook setting: read by the plugin's `SessionStart` hook | `invoke_subagent`'s `Model` enum (`inherit`, `flash_lite`, `flash`, `pro`), see [agy-tools.md](../../poteto-mode/references/agy-tools.md#model-names) | tested with `agy` 1.5.0 on macOS: plugin install, hook on/off, full skill read and a live subagent reply; Windows untested |
+| OMP | `~/.omp/pstack-models.md` (global across profiles; hook only) | read by the OMP plugin for routing | `omp models --kind chat`; model roles use OMP configuration, see [omp-tools.md](../../poteto-mode/references/omp-tools.md#model-names) | installation, skill access, and the routing toggle checked on OMP 18.16.0 with a synthetic provider; model compliance untested |
+| Grok Build | `${GROK_HOME:-~/.grok}/pstack-models.md` | read by the agent before a role-model skill; the `session hook` line does not control the Grok routing hint | the `spawn_subagent` tool's advertised models; use overrides only at the user's explicit request; see [grok.md](../../poteto-mode/references/grok.md#model-names) | synthetic-provider plugin and skill loading tested |
+| OpenCode 2 | `${XDG_CONFIG_HOME:-~/.config}/opencode/pstack-models.md` | add the path to the `instructions` array in `opencode.jsonc`; the plugin reads the hook setting directly | the `models` command in the session; see [opencode-tools.md](../../poteto-mode/references/opencode-tools.md#model-names) | native skill activation and routing tested on 2.2.5 with a loopback provider |
+| Gemini CLI | `~/.gemini/pstack-models.md` | `@~/.gemini/pstack-models.md` in `~/.gemini/GEMINI.md` | the `model` slash command in the session | from published docs, no live session |
+| Prime Agent | no documented sheet path; Prime's configuration chooses models | | | no live session |
+
+Every runtime uses its row above in place of the Claude Code paths and step 7's include line. A section below exists only for a step change the table cannot express.
+
+## Codex
+
+- **Step 3 (map and confirm).** `session` effort requires the current thread's active-turn metadata, which some hosts do not expose. The platform mapping's helper reads it; when it is unavailable, an explicit effort choice is required before dispatching. Offer a fixed default level for those hosts instead of promising automatic inheritance.
+- **Step 4 (session hook).** The plugin's `SessionStart` hook injects the mandate as on Claude Code, after the user trusts plugin hooks through `/hooks`.
+- **Step 5 (validate).** The effort levels are the `reasoning_effort` values your Codex models accept.
+- **Step 7 (wire it in).** Paste the `default effort` line into `<codex-home>/AGENTS.md` with the model rows, but not the `session hook` line: the plugin hook reads that from the sheet.
+
+## GitHub Copilot
+
+Follow [the Copilot setup](../copilot.md); its opening names the steps it replaces.
+
+## Muse
+
+- **Step 4 (session hook).** The native plugin's `SessionStart` hook injects the mandate and the role lines only after the user approves the plugin's hooks with `muse plugins approve pstack`. In step 8, name that command when it has not run yet.
+
+## Pi
+
+- **Step 4 (session hook).** The pstack extension adds the mandate to the system prompt at every agent start.
+
+## OpenCode 2
+
+- **Steps 3 and 5 (effort, validate).** The `subagent` tool has no effort field. Skip the effort questions in step 3 and effort validation in step 5, and omit the `default effort` line and `@<level>` suffixes. A variant the user asks for goes in the model ID as `providerID/modelID#variant`.
+- **Step 4 (session hook).** The native plugin adds the mandate to root-session model requests.
+
+## Antigravity
+
+- **Steps 3 and 5 (effort, validate).** `invoke_subagent` takes a `Model` and no effort parameter. Skip the effort questions in step 3 and effort validation in step 5, and omit the `default effort` line and `@<level>` suffixes.
+
+## Kimi Code CLI
+
+- **Steps 1 and 6 (detect models, write the sheet).** Describe `inherit-parent` and `auto` as omitting `model`: Kimi uses the configured subagent default when present, otherwise the parent's model. Write that meaning in the sheet header. If the `Agent` tool has no `model` parameter, offer only these aliases.
+- **Step 2 (load current state).** Preserve model aliases exactly, including ones starting with `claude-`; do not apply the Claude Code family-name rewrite.
+- **Steps 3, 4, and 5 (effort, session hook, validate).** Skip step 4, the effort questions in step 3, and effort validation in step 5. Omit effort and `session hook` lines and suffixes from the sheet.
+- **Step 8 (confirm).** Explain that routing is controlled by the plugin's enabled state instead of reporting a hook setting.
+
+## Grok Build
+
+Read the [platform mapping](../../poteto-mode/references/grok.md) first.
+
+- **Step 1 (detect models).** Use the models advertised by `spawn_subagent` and ask the user to confirm choices; the session model selector is supplementary. If the tool exposes no `model` parameter, explain that per-call model selection is unavailable and offer only `inherit-parent` and `auto`; both omit `model`, and configured subagent overrides may still apply. Write that meaning in the sheet header.
+- **Step 2 (load current state).** Preserve full `claude-` IDs and validate them against the tool's advertised models instead of rewriting them to family names.
+- **Steps 3, 4, and 5 (effort, session hook, validate).** Skip step 4, the effort questions in step 3, and effort validation in step 5. Omit effort and `session hook` lines and suffixes from the sheet. Grok exposes no per-call effort parameter.
+- **Step 8 (confirm).** Explain that the enabled plugin supplies a model-followed routing hint that the `session hook` setting does not control.
+
+## OMP
+
+Follow [OMP setup](../../poteto-mode/references/omp-tools.md#model-names) instead of steps 1 through 8. OMP uses native model roles and agent overrides; its global pstack sheet controls only the session hook.
+
+1. Ask whether main-session routing should be on or off for all OMP profiles.
+2. In `~/.omp/pstack-models.md`, replace all `session hook:` lines with one exact `session hook: on` or `session hook: off` line, preserving other lines and the existing encoding.
+3. Confirm the global scope and restart the session to clear earlier context.

package/plugins/pstack/skills/setup-pstack/scripts/check-sheet.awk

@@ -0,0 +1,10 @@
+# check-sheet.sh's program: run after sheet.awk with the sheet as input.
+{ sheet_add($0) }
+END {
+  problems = sheet_problems()
+  if (problems != "") {
+    print "sheet invalid: " problems
+    exit 1
+  }
+  print "sheet ok"
+}