quest-loop 0.1.0 → 0.3.2

package/lib/codex-native.mjs

@@ -0,0 +1,425 @@
+// Native setup helpers. These are intentionally kept out of the quest store
+// layer: they inspect/install agent integration files, not quest records.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const AGENTS = ["quest-executor", "quest-reviewer"];
+const PROVIDERS = {
+  codex: {
+    label: "Codex",
+    extension: "toml",
+    projectDir: ".codex",
+    userDir: join(homedir(), ".codex", "agents"),
+  },
+  claude: {
+    label: "Claude",
+    extension: "md",
+    projectDir: ".claude",
+    userDir: join(homedir(), ".claude", "agents"),
+  },
+};
+
+function readJson(rel) {
+  return JSON.parse(readFileSync(join(PLUGIN_ROOT, rel), "utf8"));
+}
+
+// Like readJson but returns null instead of throwing. The plugin manifests
+// (.codex-plugin / .claude-plugin) are NOT part of the npm `files` allow-list,
+// so they are absent from a pure `npm install -g quest-loop` install — reading
+// them must never crash `quest --version` or `quest codex doctor`.
+function readJsonSafe(rel) {
+  try {
+    return readJson(rel);
+  } catch {
+    return null;
+  }
+}
+
+function runCmd(cmd, args, { cwd, env } = {}) {
+  return spawnSync(cmd, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+  });
+}
+
+function check(name, ok, detail, extra = {}) {
+  return { name, ok: Boolean(ok), detail, ...extra };
+}
+
+function projectRoot(cwd, env) {
+  const res = runCmd("git", ["rev-parse", "--show-toplevel"], { cwd, env });
+  if (res.status === 0 && res.stdout.trim()) return res.stdout.trim();
+  return resolve(cwd);
+}
+
+function providerConfig(provider) {
+  const cfg = PROVIDERS[provider];
+  if (!cfg) throw new Error(`unknown native agent provider "${provider}"`);
+  return cfg;
+}
+
+function targetDir(provider, scope, cwd, env) {
+  const cfg = providerConfig(provider);
+  if (scope === "user") return cfg.userDir;
+  if (scope === "project") return join(projectRoot(cwd, env), cfg.projectDir, "agents");
+  throw new Error(`--scope must be project or user (got "${scope}")`);
+}
+
+function installedAgentDirs(provider, cwd, env) {
+  const cfg = providerConfig(provider);
+  return [
+    join(projectRoot(cwd, env), cfg.projectDir, "agents"),
+    cfg.userDir,
+  ];
+}
+
+function sameFile(path, text) {
+  try {
+    if (lstatSync(path).isSymbolicLink()) return false;
+    return readFileSync(path, "utf8") === text;
+  } catch {
+    return false;
+  }
+}
+
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function extractTexts(promptInputJson) {
+  try {
+    const items = JSON.parse(promptInputJson);
+    const texts = [];
+    const walk = (v) => {
+      if (Array.isArray(v)) return v.forEach(walk);
+      if (!v || typeof v !== "object") return;
+      if (typeof v.text === "string") texts.push(v.text);
+      if (typeof v.content === "string") texts.push(v.content);
+      for (const child of Object.values(v)) walk(child);
+    };
+    walk(items);
+    return texts.join("\n");
+  } catch {
+    return promptInputJson;
+  }
+}
+
+function questSkillEntries(promptInputJson) {
+  const text = extractTexts(promptInputJson);
+  const entries = [];
+  const re = /- quest:(plan|work|orchestrate|retro|protocol|setup):[^\n]+\(file: ([^)]+)\)/g;
+  for (const m of text.matchAll(re)) entries.push({ name: m[1], path: m[2] });
+  return entries.sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+}
+
+function pathRootForQuestSkill(path) {
+  // Match POSIX `/skills/` and Windows `\skills\` so the neutral-root check
+  // does not falsely split every skill path into its own root on Windows.
+  const i = path.search(/[/\\]skills[/\\]/);
+  return i === -1 ? path : path.slice(0, i);
+}
+
+function featureEnabled(output, name) {
+  for (const line of String(output || "").split("\n")) {
+    const parts = line.trim().split(/\s+/);
+    if (parts[0] === name) return parts.at(-1) === "true";
+  }
+  return false;
+}
+
+function upgradeHint() {
+  return "run `codex plugin marketplace upgrade quest`, `codex plugin add quest@quest`, then start a new Codex thread";
+}
+
+function duplicateSkillNames(entries) {
+  const counts = new Map();
+  for (const entry of entries) counts.set(entry.name, (counts.get(entry.name) || 0) + 1);
+  return [...counts.entries()].filter(([, count]) => count > 1).map(([name]) => name).sort();
+}
+
+export function versionInfo() {
+  // package.json is always shipped; the plugin manifests may be absent on a
+  // CLI-only npm install, so they are read tolerantly.
+  const pkg = readJson("package.json");
+  const codexManifest = readJsonSafe(".codex-plugin/plugin.json");
+  const claudeManifest = readJsonSafe(".claude-plugin/plugin.json");
+  return {
+    package: pkg.version,
+    codex: codexManifest?.version ?? null,
+    claude: claudeManifest?.version ?? null,
+  };
+}
+
+function installProviderAgents(provider, { scope = "project", dryRun = false, force = false, cwd = process.cwd(), env = process.env } = {}) {
+  const cfg = providerConfig(provider);
+  const dir = targetDir(provider, scope, cwd, env);
+  const dirConflicts = [dirname(dir), dir]
+    .filter((path, index, all) => all.indexOf(path) === index)
+    .filter((path) => existsSync(path) && isSymlink(path))
+    .map((path) => ({ name: null, path, reason: "symlink" }));
+
+  // Plan every agent first; only touch disk once the whole set is known to be
+  // conflict-free. A mixed create+conflict run must not leave a partial install.
+  const plans = AGENTS.map((name) => {
+    const src = join(PLUGIN_ROOT, "agents", `${name}.${cfg.extension}`);
+    const dest = join(dir, `${name}.${cfg.extension}`);
+    const text = readFileSync(src, "utf8");
+    const exists = existsSync(dest);
+    const symlink = exists && isSymlink(dest);
+    let action;
+    if (symlink) action = "conflict";
+    else if (exists && sameFile(dest, text)) action = "unchanged";
+    else if (exists && !force) action = "conflict";
+    else action = exists ? "replace" : "create";
+    return { name, path: dest, action, text, reason: symlink ? "symlink" : undefined };
+  });
+
+  const conflicts = [
+    ...dirConflicts,
+    ...plans.filter((p) => p.action === "conflict").map(({ name, path, reason }) => ({ name, path, ...(reason ? { reason } : {}) })),
+  ];
+  const actions = plans.map(({ name, path, action }) => ({ name, path, action }));
+  const ok = conflicts.length === 0;
+
+  if (ok && !dryRun) {
+    if (dirConflicts.length) throw new Error(`refusing to write agent templates through symlinked path: ${dirConflicts.map((c) => c.path).join(", ")}`);
+    for (const p of plans) {
+      if (p.action === "unchanged") continue;
+      mkdirSync(dir, { recursive: true });
+      if (isSymlink(dirname(p.path)) || isSymlink(p.path)) throw new Error(`refusing to write agent template through symlinked path: ${p.path}`);
+      writeFileSync(p.path, p.text);
+    }
+  }
+
+  return { ok, provider, scope, target: dir, dry_run: dryRun, actions, conflicts };
+}
+
+export function installAgents(options = {}) {
+  return installProviderAgents("codex", options);
+}
+
+export function installClaudeAgents(options = {}) {
+  return installProviderAgents("claude", options);
+}
+
+function questCliPathCheck(cwd, env, versions) {
+  const pathQuestVersion = runCmd("quest", ["--version"], { cwd, env });
+  const pathVersion = pathQuestVersion.status === 0 ? pathQuestVersion.stdout.trim() : null;
+  return check(
+    "quest-cli-path",
+    pathQuestVersion.status !== 0 || pathVersion === versions.package,
+    pathQuestVersion.status === 0
+      ? (pathVersion === versions.package
+        ? `quest on PATH=${pathVersion}`
+        : `quest on PATH=${pathVersion}, package=${versions.package}; update with \`npm install -g quest-loop@${versions.package}\` or run the checkout binary explicitly`)
+      : `quest not found on PATH (${(pathQuestVersion.stderr || pathQuestVersion.error?.message || "not found").trim()}); current package=${versions.package}`,
+    { path_version: pathVersion, expected_version: versions.package },
+  );
+}
+
+function nativeAgentsCheck(provider, cwd, env) {
+  const cfg = providerConfig(provider);
+  const agentDirs = installedAgentDirs(provider, cwd, env);
+  const missing = [];
+  const stale = [];
+  const found = {};
+  for (const name of AGENTS) {
+    const bundled = readFileSync(join(PLUGIN_ROOT, "agents", `${name}.${cfg.extension}`), "utf8");
+    const path = agentDirs.map((dir) => join(dir, `${name}.${cfg.extension}`)).find((p) => existsSync(p));
+    if (!path) {
+      missing.push(name);
+      continue;
+    }
+    found[name] = path;
+    // Existence alone can mask a stale user-scope copy shadowing an out-of-date
+    // project install — compare against the bundled definition.
+    if (!sameFile(path, bundled)) stale.push(name);
+  }
+  const agentDetail = [
+    missing.length ? `missing: ${missing.join(", ")}` : null,
+    stale.length ? `stale (run install-agents --force): ${stale.join(", ")}` : null,
+  ].filter(Boolean).join("; ") || `installed ${cfg.label} templates current: ${Object.values(found).join(", ")}`;
+  return check(
+    "native-agents",
+    missing.length === 0 && stale.length === 0,
+    agentDetail,
+    { found, missing, stale, provider },
+  );
+}
+
+export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
+  const checks = [];
+  const versions = versionInfo();
+  // package.json ships everywhere; the plugin manifests may be absent on a
+  // CLI-only npm install. Treat absent manifests as "not applicable" rather than
+  // a hard mismatch, and fall back to the package version as the expected plugin
+  // version so a legitimate CLI-only doctor run is not spuriously red.
+  const manifestVersion = versions.codex ?? versions.package;
+  const presentManifests = [["codex", versions.codex], ["claude", versions.claude]].filter(([, v]) => v != null);
+  const absent = ["codex", "claude"].filter((k) => versions[k] == null);
+
+  checks.push(check(
+    "version-sync",
+    presentManifests.every(([, v]) => v === versions.package),
+    `package=${versions.package}, codex=${versions.codex ?? "absent"}, claude=${versions.claude ?? "absent"}` +
+      (absent.length ? ` (${absent.join(", ")} manifest absent — CLI-only install)` : ""),
+    { versions },
+  ));
+
+  checks.push(questCliPathCheck(cwd, env, versions));
+
+  const codexVersion = runCmd("codex", ["--version"], { cwd, env });
+  checks.push(check(
+    "codex-cli",
+    codexVersion.status === 0,
+    codexVersion.status === 0 ? codexVersion.stdout.trim() : (codexVersion.stderr || codexVersion.error?.message || "codex not found").trim(),
+  ));
+
+  if (codexVersion.status === 0) {
+    const list = runCmd("codex", ["plugin", "list", "--json"], { cwd, env });
+    let installed;
+    try {
+      const parsed = JSON.parse(list.stdout || "{}");
+      installed = (parsed.installed || []).find((p) => p.pluginId === "quest@quest" || (p.name === "quest" && p.marketplaceName === "quest"));
+    } catch {
+      installed = null;
+    }
+    checks.push(check(
+      "plugin-installed",
+      list.status === 0 && installed?.enabled === true,
+      installed ? `quest@quest ${installed.version} enabled=${installed.enabled}` : (list.stderr || "quest@quest not installed").trim(),
+      { installed: installed ?? null },
+    ));
+    checks.push(check(
+      "plugin-version",
+      Boolean(installed && installed.version === manifestVersion),
+      installed
+        ? (installed.version === manifestVersion
+          ? `installed=${installed.version}, manifest=${manifestVersion}`
+          : `installed=${installed.version}, manifest=${manifestVersion}; ${upgradeHint()}`)
+        : `manifest=${manifestVersion}; ${upgradeHint()}`,
+    ));
+
+    const features = runCmd("codex", ["features", "list"], { cwd, env });
+    const multiAgent = features.status === 0 && featureEnabled(features.stdout, "multi_agent");
+    const goals = features.status === 0 && featureEnabled(features.stdout, "goals");
+    checks.push(check(
+      "multi-agent-feature",
+      multiAgent,
+      features.status === 0
+        ? (multiAgent
+          ? "multi_agent enabled; native Codex quest-executor dispatch available"
+          : "multi_agent is not enabled; use quest-run fallback")
+        : ((features.stderr || features.error?.message || "could not inspect Codex feature flags").trim() + "; use quest-run fallback"),
+      { feature: "multi_agent" },
+    ));
+    checks.push(check(
+      "goals-feature",
+      goals,
+      features.status === 0
+        ? (goals
+          ? "goals enabled; native create_goal/get_goal dispatch available"
+          : "goals is not enabled; native goal-mode dispatch requires create_goal/get_goal")
+        : ((features.stderr || features.error?.message || "could not inspect Codex feature flags").trim() + "; native goal-mode dispatch unavailable"),
+      { feature: "goals" },
+    ));
+
+    const debug = runCmd("codex", ["debug", "prompt-input", "noop"], { cwd: tmpdir(), env });
+    // Require a hook-parse *problem*, not merely the word "hook" next to "warnings".
+    // Matches both orderings ("hook parse warning" / "failed to parse hook") while
+    // ignoring benign summaries like "loaded 4 hooks, 0 warnings".
+    const hookWarning = /(?:parse|parsing)[^\n]*\bhook\b|\bhook\b[^\n]*(?:parse|parsing|invalid|malformed)|failed to (?:parse|load)[^\n]*\bhook\b/i.test(debug.stderr || "");
+    checks.push(check(
+      "hook-parser",
+      debug.status === 0 && !hookWarning,
+      debug.status === 0 ? (hookWarning ? debug.stderr.trim() : "no hook parse warnings") : (debug.stderr || "codex debug failed").trim(),
+    ));
+
+    const entries = debug.status === 0 ? questSkillEntries(debug.stdout) : [];
+    const requiredSkills = ["plan", "work", "orchestrate", "retro", "protocol"];
+    const missingSkills = requiredSkills.filter((name) => !entries.some((entry) => entry.name === name));
+    const paths = entries.map((entry) => entry.path);
+    const roots = [...new Set(paths.map(pathRootForQuestSkill))];
+    const duplicateSkills = duplicateSkillNames(entries);
+    checks.push(check(
+      "single-neutral-skill-root",
+      missingSkills.length === 0 && roots.length === 1 && duplicateSkills.length === 0,
+      paths.length
+        ? `${entries.length} quest skill entries across ${roots.length} root(s)` +
+          (duplicateSkills.length ? `; duplicate skill names: ${duplicateSkills.join(", ")}; ${upgradeHint()}` : "")
+        : "quest skills not found in neutral prompt-input",
+      { skills: entries, missing_skills: missingSkills, duplicate_skills: duplicateSkills, skill_paths: paths, skill_roots: roots },
+    ));
+  }
+
+  checks.push(nativeAgentsCheck("codex", cwd, env));
+
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+export function claudeDoctor({ cwd = process.cwd(), env = process.env } = {}) {
+  const checks = [];
+  const versions = versionInfo();
+  const manifestVersion = versions.claude ?? versions.package;
+  const presentManifests = [["codex", versions.codex], ["claude", versions.claude]].filter(([, v]) => v != null);
+  const absent = ["codex", "claude"].filter((k) => versions[k] == null);
+
+  checks.push(check(
+    "version-sync",
+    presentManifests.every(([, v]) => v === versions.package),
+    `package=${versions.package}, codex=${versions.codex ?? "absent"}, claude=${versions.claude ?? "absent"}` +
+      (absent.length ? ` (${absent.join(", ")} manifest absent — CLI-only install)` : ""),
+    { versions },
+  ));
+
+  checks.push(questCliPathCheck(cwd, env, versions));
+
+  const claudeVersion = runCmd("claude", ["--version"], { cwd, env });
+  checks.push(check(
+    "claude-cli",
+    claudeVersion.status === 0,
+    claudeVersion.status === 0 ? claudeVersion.stdout.trim() : (claudeVersion.stderr || claudeVersion.error?.message || "claude not found").trim(),
+  ));
+
+  if (claudeVersion.status === 0) {
+    const list = runCmd("claude", ["plugin", "list", "--json"], { cwd, env });
+    let installed;
+    try {
+      const parsed = JSON.parse(list.stdout || "[]");
+      const plugins = Array.isArray(parsed) ? parsed : (parsed.installed || []);
+      installed = plugins.find((p) => p.id === "quest@quest" || p.pluginId === "quest@quest" || (p.name === "quest" && p.marketplaceName === "quest"));
+    } catch {
+      installed = null;
+    }
+    checks.push(check(
+      "plugin-installed",
+      list.status === 0 && installed?.enabled === true,
+      installed ? `quest@quest ${installed.version} enabled=${installed.enabled}` : (list.stderr || "quest@quest not installed").trim(),
+      { installed: installed ?? null },
+    ));
+    checks.push(check(
+      "plugin-version",
+      Boolean(installed && installed.version === manifestVersion),
+      installed
+        ? (installed.version === manifestVersion
+          ? `installed=${installed.version}, manifest=${manifestVersion}`
+          : `installed=${installed.version}, manifest=${manifestVersion}; run \`claude plugin update quest@quest\`, then restart Claude Code`)
+        : `manifest=${manifestVersion}; run \`claude plugin install quest@quest\`, then restart Claude Code`,
+    ));
+  }
+
+  checks.push(nativeAgentsCheck("claude", cwd, env));
+
+  return { ok: checks.every((c) => c.ok), checks };
+}

package/lib/config.mjs

@@ -16,7 +16,7 @@ export class ConfigError extends Error {
 export const BUILTIN_DEFAULTS = {
   worker: "claude",
   claude: { model: "opus", effort: "xhigh" },
-  codex: { model: "gpt-5.5", reasoning_effort: "medium" },
+  codex: { model: "gpt-5.5", reasoning_effort: "medium", goal_mode: "auto" },
   max_iterations: 8,
   priority: "p2",
 };

package/lib/contract.mjs

@@ -79,7 +79,7 @@ export function parseCheckpoints(body) {
   return checkpoints;
 }
 
-export function makeCheckpoint({ timestamp, quest_status, iteration, changed, validation_summary, pr, head_sha, failed_approaches, compatible_expansion, note }) {
+export function makeCheckpoint({ timestamp, quest_status, iteration, changed, validation_summary, pr, head_sha, failed_approaches, compatible_expansion, reopen_reason, note }) {
   if (!QUEST_STATUSES.includes(quest_status)) {
     throw new ContractError(`quest_status must be one of ${QUEST_STATUSES.join(" | ")} (got "${quest_status}")`, { hint: "store statuses like todo/cancelled are not checkpoint verdicts" });
   }
@@ -100,6 +100,7 @@ export function makeCheckpoint({ timestamp, quest_status, iteration, changed, va
   out.push(`- validation_summary: ${oneLine("validation_summary", validation_summary)}`);
   if (failed_approaches) out.push(`- failed_approaches: ${oneLine("failed_approaches", failed_approaches)}`);
   if (compatible_expansion) out.push(`- compatible_expansion: ${oneLine("compatible_expansion", compatible_expansion)}`);
+  if (reopen_reason) out.push(`- reopen_reason: ${oneLine("reopen_reason", reopen_reason)}`);
   if (note && String(note).trim() !== "") out.push("", String(note).trim());
   return out.join("\n");
 }
@@ -122,11 +123,30 @@ const TRANSITIONS = {
 export function assertTransition(from, to) {
   if (!(TRANSITIONS[from] ?? []).includes(to)) {
     throw new ContractError(`illegal status transition: ${from} → ${to}`, {
-      hint: from === "complete" || from === "cancelled" ? `${from} is terminal — file a new quest instead` : `legal from "${from}": ${TRANSITIONS[from].join(", ") || "(none)"}`,
+      hint:
+        from === "complete"
+          ? "complete is terminal for checkpoints — use `quest reopen <id> --reason` to legally re-enter the loop"
+          : from === "cancelled"
+          ? "cancelled is terminal — file a new quest instead"
+          : `legal from "${from}": ${(TRANSITIONS[from] ?? []).join(", ") || "(none)"}`,
     });
   }
 }
 
+// The single legal path from a terminal `complete` status back into the loop.
+// Deliberately NOT part of TRANSITIONS.complete (which stays []): only the
+// `quest reopen` verb calls this, so a stray checkpoint can never resurrect a
+// complete quest. `cancelled` stays fully terminal — file a new quest instead.
+export function assertReopen(from) {
+  if (from === "complete") return;
+  throw new ContractError(`cannot reopen a ${from} quest — only complete quests are reopenable`, {
+    hint:
+      from === "cancelled"
+        ? "cancelled is terminal — file a new quest instead"
+        : `${from} is not terminal; advance it with \`quest checkpoint\` (or \`quest start\` if todo)`,
+  });
+}
+
 export function lintRecord({ front, body, checkpoints }, { filename } = {}) {
   const problems = [];
   for (const key of REQUIRED_FRONT) {

package/lib/help.mjs

@@ -9,12 +9,13 @@ iterations that end in checkpoints; \`quest-run\` drives headless workers.`;
 
 export const COMMANDS = {
   init: {
-    purpose: "Create a quest store (.quests/) in the current directory",
-    usage: "quest init [--backend local|github] [--repo owner/name] [--agents-md]",
+    purpose: "Create a quest store (.quests/) and install project agent templates",
+    usage: "quest init [--backend local|github] [--repo owner/name] [--agents-md] [--no-agents]",
     flags: [
       ["--backend <b>", "record storage: local files (default) or github issues"],
       ["--repo <owner/name>", "required with --backend github"],
       ["--agents-md", "append a quest orientation section to ./AGENTS.md"],
+      ["--no-agents", "skip installing .codex/agents and .claude/agents templates"],
     ],
     example: "quest init",
   },
@@ -51,7 +52,7 @@ export const COMMANDS = {
     flags: [
       ["--status <s>", "todo | in_progress | blocked | complete | cancelled"],
       ["--parent <id>", "children of an epic"],
-      ["--ready", "todo quests whose depends_on are all complete (dispatch order)"],
+      ["--ready", "todo quests whose depends_on are all complete, excluding epics with open children (dispatch order)"],
       ["--json", "machine-readable output"],
     ],
     example: "quest list --ready",
@@ -92,6 +93,12 @@ export const COMMANDS = {
     flags: [["--reason <why>", "required — recorded in the record"]],
     example: 'quest cancel 4 --reason "superseded by quest 7"',
   },
+  reopen: {
+    purpose: "Reopen a complete quest back into the loop (complete → in_progress)",
+    usage: "quest reopen <id> --reason <why>",
+    flags: [["--reason <why>", "required — recorded in an audited reopen checkpoint"]],
+    example: 'quest reopen 4 --reason "review found npm audit criticals after completion"',
+  },
   edit: {
     purpose: "Compatibly expand a quest (additions only; anchors are immutable)",
     usage: "quest edit <id> [--add-done-when D]… [--add-milestone M]… [--add-context C] --rationale <why>",
@@ -130,6 +137,32 @@ export const COMMANDS = {
     ],
     example: "quest runs --active",
   },
+  codex: {
+    purpose: "Inspect or install Quest's native Codex integration",
+    usage: "quest codex doctor [--json] | quest codex install-agents [--scope project|user] [--dry-run] [--force] [--json]",
+    flags: [
+      ["doctor", "check Codex CLI, multi-agent support, plugin install/version, hooks, skill roots, and native-agent templates"],
+      ["install-agents", "install quest-executor and quest-reviewer as native Codex custom agents"],
+      ["--scope <s>", "project (default: .codex/agents at repo root) or user (~/.codex/agents)"],
+      ["--dry-run", "show intended agent writes without changing files"],
+      ["--force", "replace existing agent files"],
+      ["--json", "machine-readable output"],
+    ],
+    example: "quest codex install-agents --scope project && quest codex doctor",
+  },
+  claude: {
+    purpose: "Inspect or install Quest's native Claude Code integration",
+    usage: "quest claude doctor [--json] | quest claude install-agents [--scope project|user] [--dry-run] [--force] [--json]",
+    flags: [
+      ["doctor", "check Claude CLI, plugin install/version, and native-agent templates"],
+      ["install-agents", "install quest-executor and quest-reviewer as native Claude Code custom agents"],
+      ["--scope <s>", "project (default: .claude/agents at repo root) or user (~/.claude/agents)"],
+      ["--dry-run", "show intended agent writes without changing files"],
+      ["--force", "replace existing agent files"],
+      ["--json", "machine-readable output"],
+    ],
+    example: "quest claude install-agents --scope project && quest claude doctor",
+  },
 };
 
 export function renderCommandHelp(name) {
@@ -163,7 +196,7 @@ export function renderStatusOverview({ counts, ready, activeRuns, backend }) {
     for (const q of ready.slice(0, 3)) lines.push(`  ${q.id}. [${q.priority}] ${q.title}`);
     lines.push("", "Next: `quest show <id>` to read one, or dispatch with `quest-run <id>`.");
   } else if (!parts.length) {
-    lines.push("", "Next: create your first quest — see `quest create --help` (or use the /quest:plan skill).");
+    lines.push("", "Next: create your first quest — see `quest create --help` (or use the $quest:plan skill).");
   } else {
     lines.push("", "Nothing ready to start. `quest list` to see everything.");
   }
@@ -183,13 +216,15 @@ export function renderNoStore() {
   ].join("\n");
 }
 
-export function renderInitNextSteps(backend) {
+export function renderInitNextSteps(backend, { agentsInstalled = true } = {}) {
   return [
     "",
     "Store created. Next steps:",
-    "  1. Author a quest:   quest create --help   (or /quest:plan in your agent session)",
+    ...(agentsInstalled ? ["  0. Restart agent sessions so newly installed project templates are loaded"] : []),
+    "  1. Author a quest:   quest create --help   (or $quest:plan in your agent session)",
     "  2. Check it:         quest lint --all",
-    "  3. Work it:          /quest:work <id> in-session, or quest-run <id> headless",
+    "  3. Work it:          $quest:work <id> in-session, or quest-run <id> headless",
+    ...(agentsInstalled ? [] : ["  Agent templates skipped; install later with `quest codex install-agents --scope project` and `quest claude install-agents --scope project`."]),
     ...(backend === "github" ? ["", "Records live as GitHub issues; config and amendments stay local in .quests/."] : []),
   ].join("\n");
 }