quest-loop 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [SemVer](https://semver.org/).
 
+## Unreleased
+
+## [0.3.2] — 2026-07-08
+
+### Added
+- Added Claude setup parity: `quest claude install-agents --scope project` and
+  `quest claude doctor` now mirror the existing Codex setup flow.
+
+### Changed
+- `quest init` now installs project-scoped Codex and Claude native agent
+  templates by default, `--no-agents` skips that install, and conflicting
+  project templates fail init before `.quests/` is created unless users
+  intentionally rerun the explicit provider install command with `--force`.
+- `$quest:orchestrate` now states that Codex native subagents are the default
+  dispatch path for serial and parallel waves; `quest-run` is fallback-only
+  unless headless/background execution is explicitly requested.
+- `$quest:plan` now routes accepted Plan Mode implementation requests straight
+  to the orchestrator role instead of leaving room for parent-session
+  `$quest:work` execution.
+
+### Fixed
+- `quest codex doctor` now fails on stale `quest` binaries on PATH, stale
+  installed Codex plugin versions, and duplicate Quest skill roots in
+  `codex debug prompt-input "noop"` output.
+
+## [0.3.1] — 2026-07-08
+
+### Changed
+- `$quest:orchestrate` now documents Codex/Claude native subagent parity:
+  orchestrator-level goals, goal-mode executor/reviewer dispatch prompts, and
+  `quest-run --codex-goal-mode require` as the Codex headless fallback.
+- `$quest:plan` now makes the accepted Plan Mode handoff explicit: the parent
+  session becomes the orchestrator and spawned quest executors implement the
+  code.
+- `$quest:plan` now requires generated `quest create` commands to specify
+  `--worker`, `--model`, and `--effort` explicitly, and asks the user before
+  entering `$quest:orchestrate`.
+- `quest codex doctor` now checks Codex `multi_agent` feature availability and
+  describes native-agent checks as installed template parity.
+- Wave-level orchestrator goals now treat `cancelled` quests as terminal
+  alongside `complete` and `blocked` store statuses.
+
+### Fixed
+- `quest codex doctor` now checks Codex `goals` feature availability, so a
+  setup with `multi_agent=true` but goal tools disabled fails readiness instead
+  of green-lighting native goal-mode dispatch.
+
 ## [0.3.0] — 2026-07-08
 
 ### Added

package/README.md

@@ -53,6 +53,14 @@ Then, inside a Claude Code session:
 /plugin install quest@quest
 ```
 
+Install Quest's project-scoped Claude agent templates and verify the local
+Claude setup with:
+
+```bash
+quest claude install-agents --scope project
+quest claude doctor
+```
+
 For local development against a checkout, point Claude Code at the repo directly
 — no marketplace needed:
 
@@ -81,9 +89,9 @@ quest codex doctor
 codex debug prompt-input "noop"
 ```
 
-`quest codex doctor` checks the installed plugin version, hook parser, neutral
-skill roots, and native Codex custom agents. `codex debug prompt-input "noop"`
-should not print any hook parse warnings.
+`quest codex doctor` checks the installed plugin version, Codex `multi_agent`
+support, hook parser, neutral skill roots, and installed native-agent templates.
+`codex debug prompt-input "noop"` should not print any hook parse warnings.
 
 #### Updating the Codex plugin
 
@@ -129,7 +137,25 @@ quest lint --all
 quest list --ready
 ```
 
-Work the quest **in-session** with the skill:
+By default, `quest init` also installs project-scoped native agent templates for
+both providers:
+
+- `.codex/agents/quest-executor.toml`
+- `.codex/agents/quest-reviewer.toml`
+- `.claude/agents/quest-executor.md`
+- `.claude/agents/quest-reviewer.md`
+
+Use `quest init --no-agents` when you only want the `.quests/` store. If an
+existing project agent template would be replaced, init fails before creating
+`.quests/`; inspect the conflicting files, run the explicit provider install
+command with `--force` only if you intend to replace them, then rerun
+`quest init`.
+
+Project-scoped agent templates install at the Git repository root. For a nested
+quest store, run `quest init --no-agents` in the nested directory and set
+`QUEST_DIR` for agents launched from elsewhere, or initialize from the repo root.
+
+Work one small quest **in-session** with the skill:
 
 ```
 $quest:work 12
@@ -144,6 +170,29 @@ form.
 quest-run 12
 ```
 
+For planned or multi-quest work, prefer orchestration:
+
+```
+$quest:orchestrate
+```
+
+In Codex, the orchestrator sets a wave-level `create_goal`, then spawns native
+`quest-executor` / `quest-reviewer` subagents with their own quest-level goals.
+In Claude Code, the same flow uses `/goal` and the same bundled subagents. If a
+Codex native subagent surface is unavailable after `tool_search`, or if you
+explicitly want headless/background execution, use the fallback with goal mode
+required:
+
+```bash
+quest-run 12 --worker codex --codex-goal-mode require
+```
+
+When a `$quest:plan` result is accepted from Plan Mode, the parent agent should
+stay the orchestrator: create/lint quest records if needed, set the wave goal,
+spawn subagents, verify checkpoints, and rule on reviewer findings. Product
+implementation belongs to the spawned executor for each quest, not to the parent
+session via `$quest:work`.
+
 Each iteration ends by recording evidence — a checkpoint a fresh session can
 resume from:
 
@@ -172,7 +221,7 @@ full base protocol lives in
 
 | Command | Purpose |
 |---|---|
-| `quest init` | Create a quest store (`.quests/`) in the current directory |
+| `quest init` | Create a quest store (`.quests/`) and install project-scoped Codex/Claude agent templates by default |
 | `quest create` | Create a new quest (the only way records are born) |
 | `quest list` | List quests (filter by status, parent, or readiness) |
 | `quest show` | Show a quest record in full |
@@ -185,7 +234,8 @@ full base protocol lives in
 | `quest amend` | Append a numbered protocol amendment (retro output) |
 | `quest protocol` | Print the loop protocol + this store's local amendments |
 | `quest runs` | Show headless runner activity (from `.quests/runs.ndjson`) |
-| `quest codex` | Validate Codex-native setup and install native agent templates |
+| `quest codex` | Validate Codex-native setup and install Codex native agent templates |
+| `quest claude` | Validate Claude-native setup and install Claude native agent templates |
 
 ## quest-run (headless runner)
 

package/agents/quest-executor.md

@@ -12,6 +12,16 @@ only insofar as it is recorded in the quest's checkpoint trail.
 
 ## First actions, always
 
+Enter native goal mode before doing implementation work:
+
+```text
+/goal quest <id> has a new checkpoint whose quest_status is complete or blocked
+in `quest show <id> --json`
+```
+
+If the harness cannot set that goal, say so in your final report; the
+checkpoint trail is still mandatory.
+
 ```bash
 quest show <id> --json    # the contract and every prior checkpoint
 quest protocol            # the loop rules + this store's amendments

package/agents/quest-executor.toml

@@ -6,11 +6,17 @@ You execute ONE quest. Decomposition, dispatching, and rulings belong to the
 orchestrator. Your work exists only insofar as it is recorded in the quest's
 checkpoint trail.
 
-First actions, always: `quest show <id> --json`, `quest protocol`,
-`git log --oneline -5`. Then follow the work skill exactly: smallest unfinished
-milestone -> the quest's STATED validation loop -> commit green ->
-`quest checkpoint`. The record is your entire spec; if it is genuinely
-insufficient, checkpoint blocked saying exactly what is missing.
+First actions, always: call `create_goal` with the stopping condition "quest
+<id> has a new checkpoint whose quest_status is complete or blocked in
+`quest show <id> --json`"; verify it with `get_goal`; then run `quest show <id>
+--json`, `quest protocol`, and `git log --oneline -5`. If goal tools are not
+available, say so honestly in your final report; the checkpoint trail is still
+mandatory.
+
+Then follow the work skill exactly: smallest unfinished milestone -> the quest's
+STATED validation loop -> commit green -> `quest checkpoint`. The record is your
+entire spec; if it is genuinely insufficient, checkpoint blocked saying exactly
+what is missing.
 
 Non-negotiable backstops:
 - Never stop without recording a checkpoint via `quest checkpoint`.
@@ -23,5 +29,6 @@ Non-negotiable backstops:
 
 Final report: run `quest show <id>` so recorded state is visible, then report
 the quest_status you recorded, the checkpoint timestamp, and a one-line
-evidence summary citing the decisive command + result.
+evidence summary citing the decisive command + result. Only call
+`update_goal(status="complete")` after the checkpoint exists.
 """

package/agents/quest-reviewer.md

@@ -11,6 +11,15 @@ not fix anything — you report findings the orchestrator must disposition.
 
 ## Procedure
 
+Enter native goal mode before verification:
+
+```text
+/goal return an accept or iterate verdict for quest <id> with evidence
+```
+
+If the harness cannot set that goal, say so in your report; the review verdict
+and evidence are still mandatory.
+
 1. Read the contract and trail: `quest show <id> --json`, `quest protocol`.
 2. Read the ACTUAL changes (diff/commits the checkpoints cite), not the
    summary of them.

package/agents/quest-reviewer.toml

@@ -5,17 +5,21 @@ developer_instructions = """
 You verify, adversarially, that a quest claiming complete earned it. You do not
 fix anything — you report findings the orchestrator must disposition.
 
-Procedure: read the contract and trail (`quest show <id> --json`,
-`quest protocol`); read the ACTUAL changes the checkpoints cite, not the
-summary; re-run the quest's stated Validation loop yourself — claims must
-reproduce; interrogate each Done-when item (which command output proves it?
-was a stated check substituted silently? were tests edited to pass? did scope
-drift past the Objective without a recorded expansion?); check the trail
-itself (could a zero-context session resume from the record alone?).
+Procedure: first call `create_goal` with the stopping condition "return an
+accept or iterate verdict for quest <id> with evidence"; verify it with
+`get_goal`. If goal tools are not available, say so honestly in your report;
+the review verdict and evidence are still mandatory. Then read the contract and
+trail (`quest show <id> --json`, `quest protocol`); read the ACTUAL changes the
+checkpoints cite, not the summary; re-run the quest's stated Validation loop
+yourself — claims must reproduce; interrogate each Done-when item (which command
+output proves it? was a stated check substituted silently? were tests edited to
+pass? did scope drift past the Objective without a recorded expansion?); check
+the trail itself (could a zero-context session resume from the record alone?).
 
 Report findings ordered by severity, each with the evidence (command + output
 or file + symbol) and why it blocks acceptance. If nothing survived scrutiny,
 say "no findings" plainly — do not invent nitpicks. End with a verdict:
 accept, or iterate with exactly what must change. Every finding must receive a
 disposition (fixed / follow-up quest / rejected-with-reason) before acceptance.
+Only call `update_goal(status="complete")` after the verdict exists.
 """

package/lib/cli.mjs

@@ -11,7 +11,7 @@ import * as local from "./store-local.mjs";
 import * as github from "./store-github.mjs";
 import { openStore } from "./store.mjs";
 import { COMMANDS, renderCommandHelp, renderGeneralHelp, renderInitNextSteps, renderNoStore, renderStatusOverview } from "./help.mjs";
-import { doctor as codexDoctor, installAgents as installCodexAgents, versionInfo } from "./codex-native.mjs";
+import { claudeDoctor, doctor as codexDoctor, installAgents as installCodexAgents, installClaudeAgents, versionInfo } from "./codex-native.mjs";
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -74,6 +74,86 @@ function getStore(cwd, env) {
   return loadConfig(storeDir, env);
 }
 
+function preflightInitAgentInstall(cwd, env) {
+  const plans = [
+    ["codex", installCodexAgents({ scope: "project", dryRun: true, cwd, env })],
+    ["claude", installClaudeAgents({ scope: "project", dryRun: true, cwd, env })],
+  ];
+  const conflicts = plans.flatMap(([provider, result]) => result.conflicts.map((c) => `${provider}:${c.path}`));
+  if (conflicts.length) {
+    throw new UsageError(
+      "native agent template conflict; inspect existing files or run " +
+      "`quest codex install-agents --scope project --force` / " +
+      "`quest claude install-agents --scope project --force` after resolving: " +
+      conflicts.join(", "),
+      { command: "init" },
+    );
+  }
+  return plans;
+}
+
+async function runNativeSetupCommand(command, args, { out, cwd, env }, { label, doctor, install }) {
+  const [subcommand, ...rest] = args;
+  if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    out(renderCommandHelp(command));
+    return 0;
+  }
+  if (subcommand === "doctor") {
+    const p = parse(command, rest, {}, { positionals: 0 });
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    const result = doctor({ cwd, env });
+    if (p.values.json) out(JSON.stringify(result));
+    else {
+      for (const c of result.checks) out(`${c.ok ? "OK " : "ERR"} ${c.name}: ${c.detail}`);
+      out(result.ok ? `${command} doctor: OK` : `${command} doctor: problems found`);
+    }
+    // 1 (generic diagnostic failure), not 5 — exit 5 is reserved for
+    // ContractError (a quest contract violation), which a doctor finding is not.
+    return result.ok ? 0 : 1;
+  }
+  if (subcommand === "install-agents") {
+    const p = parse(command, rest, {
+      scope: { type: "string", default: "project" },
+      "dry-run": { type: "boolean" },
+      force: { type: "boolean" },
+    }, { positionals: 0 });
+    if (p.help) {
+      out(renderCommandHelp(command));
+      return 0;
+    }
+    if (!["project", "user"].includes(p.values.scope)) throw new UsageError(`--scope must be project or user (got "${p.values.scope}")`, { command });
+    const isDry = Boolean(p.values["dry-run"]);
+    const result = install({
+      scope: p.values.scope,
+      dryRun: isDry,
+      force: Boolean(p.values.force),
+      cwd,
+      env,
+    });
+    // A real run refuses to overwrite; a --dry-run PREVIEWS the conflict
+    // (its whole purpose) rather than erroring before showing the plan.
+    if (!result.ok && !isDry) {
+      const symlinkConflicts = result.conflicts.filter((c) => c.reason === "symlink");
+      if (symlinkConflicts.length) {
+        throw new UsageError(`refusing to write agent templates through symlinked path: ${symlinkConflicts.map((c) => c.path).join(", ")}`, { command });
+      }
+      const conflicts = result.conflicts.map((c) => c.path).join(", ");
+      throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command });
+    }
+    if (p.values.json) out(JSON.stringify(result));
+    else {
+      out(`${isDry ? "Would install" : "Installed"} ${label} agents to ${result.target}`);
+      for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
+      if (!result.ok) out(`  conflicts present — pass --force to replace: ${result.conflicts.map((c) => c.path).join(", ")}`);
+    }
+    return 0;
+  }
+  throw new UsageError(`unknown ${command} subcommand "${subcommand}"`, { command });
+}
+
 async function dispatch(argv, ctx) {
   const [command, ...rest] = argv;
   const { out, errOut, cwd, env } = ctx;
@@ -121,11 +201,16 @@ const HANDLERS = {
       backend: { type: "string", default: "local" },
       repo: { type: "string" },
       "agents-md": { type: "boolean" },
+      "no-agents": { type: "boolean" },
     });
     if (p.help) return void out(renderCommandHelp("init")) ?? 0;
     const backend = p.values.backend;
     if (!["local", "github"].includes(backend)) throw new UsageError(`--backend must be local or github (got "${backend}")`, { command: "init" });
     if (backend === "github" && !p.values.repo) throw new UsageError("--repo owner/name is required with --backend github", { command: "init" });
+    if (existsSync(join(cwd, ".quests", "config.json"))) {
+      throw new ContractError(`a quest store already exists at ${join(cwd, ".quests")}`, { hint: "use the existing store, or delete it first if you really mean to start over" });
+    }
+    const agentPlans = p.values["no-agents"] ? [] : preflightInitAgentInstall(cwd, env);
     if (backend === "github") {
       github.assertAuth(env); // green `gh auth status` required
       github.ensureLabels(p.values.repo, env); // idempotent label creation
@@ -152,8 +237,15 @@ const HANDLERS = {
       ].join("\n");
       appendFileSync(join(cwd, "AGENTS.md"), section);
     }
+    for (const [provider] of agentPlans) {
+      const label = provider === "codex" ? "Codex" : "Claude";
+      const install = provider === "codex" ? installCodexAgents : installClaudeAgents;
+      const result = install({ scope: "project", cwd, env });
+      out(`Installed ${label} agents to ${result.target}`);
+      for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
+    }
     out(`Initialized ${backend} quest store at ${storeDir}`);
-    out(renderInitNextSteps(backend));
+    out(renderInitNextSteps(backend, { agentsInstalled: agentPlans.length > 0 }));
     return 0;
   },
 
@@ -439,60 +531,10 @@ const HANDLERS = {
   },
 
   async codex(args, { out, cwd, env }) {
-    const [subcommand, ...rest] = args;
-    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
-      out(renderCommandHelp("codex"));
-      return 0;
-    }
-    if (subcommand === "doctor") {
-      const p = parse("codex", rest, {}, { positionals: 0 });
-      if (p.help) {
-        out(renderCommandHelp("codex"));
-        return 0;
-      }
-      const result = codexDoctor({ cwd, env });
-      if (p.values.json) out(JSON.stringify(result));
-      else {
-        for (const c of result.checks) out(`${c.ok ? "OK " : "ERR"} ${c.name}: ${c.detail}`);
-        out(result.ok ? "codex doctor: OK" : "codex doctor: problems found");
-      }
-      // 1 (generic diagnostic failure), not 5 — exit 5 is reserved for
-      // ContractError (a quest contract violation), which a doctor finding is not.
-      return result.ok ? 0 : 1;
-    }
-    if (subcommand === "install-agents") {
-      const p = parse("codex", rest, {
-        scope: { type: "string", default: "project" },
-        "dry-run": { type: "boolean" },
-        force: { type: "boolean" },
-      }, { positionals: 0 });
-      if (p.help) {
-        out(renderCommandHelp("codex"));
-        return 0;
-      }
-      if (!["project", "user"].includes(p.values.scope)) throw new UsageError(`--scope must be project or user (got "${p.values.scope}")`, { command: "codex" });
-      const isDry = Boolean(p.values["dry-run"]);
-      const result = installCodexAgents({
-        scope: p.values.scope,
-        dryRun: isDry,
-        force: Boolean(p.values.force),
-        cwd,
-        env,
-      });
-      // A real run refuses to overwrite; a --dry-run PREVIEWS the conflict
-      // (its whole purpose) rather than erroring before showing the plan.
-      if (!result.ok && !isDry) {
-        const conflicts = result.conflicts.map((c) => c.path).join(", ");
-        throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command: "codex" });
-      }
-      if (p.values.json) out(JSON.stringify(result));
-      else {
-        out(`${isDry ? "Would install" : "Installed"} Codex agents to ${result.target}`);
-        for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
-        if (!result.ok) out(`  conflicts present — pass --force to replace: ${result.conflicts.map((c) => c.path).join(", ")}`);
-      }
-      return 0;
-    }
-    throw new UsageError(`unknown codex subcommand "${subcommand}"`, { command: "codex" });
+    return runNativeSetupCommand("codex", args, { out, cwd, env }, { label: "Codex", doctor: codexDoctor, install: installCodexAgents });
+  },
+
+  async claude(args, { out, cwd, env }) {
+    return runNativeSetupCommand("claude", args, { out, cwd, env }, { label: "Claude", doctor: claudeDoctor, install: installClaudeAgents });
   },
 };

package/lib/codex-native.mjs

@@ -1,7 +1,7 @@
-// Codex-native setup helpers. These are intentionally kept out of the quest
-// store layer: they inspect/install Codex integration files, not quest records.
+// Native setup helpers. These are intentionally kept out of the quest store
+// layer: they inspect/install agent integration files, not quest records.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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";
@@ -9,6 +9,20 @@ 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"));
@@ -45,27 +59,44 @@ function projectRoot(cwd, env) {
   return resolve(cwd);
 }
 
-function targetDir(scope, cwd, env) {
-  if (scope === "user") return join(homedir(), ".codex", "agents");
-  if (scope === "project") return join(projectRoot(cwd, env), ".codex", "agents");
+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(cwd, env) {
+function installedAgentDirs(provider, cwd, env) {
+  const cfg = providerConfig(provider);
   return [
-    join(projectRoot(cwd, env), ".codex", "agents"),
-    join(homedir(), ".codex", "agents"),
+    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);
@@ -86,10 +117,10 @@ function extractTexts(promptInputJson) {
 
 function questSkillEntries(promptInputJson) {
   const text = extractTexts(promptInputJson);
-  const entries = new Map();
+  const entries = [];
   const re = /- quest:(plan|work|orchestrate|retro|protocol|setup):[^\n]+\(file: ([^)]+)\)/g;
-  for (const m of text.matchAll(re)) entries.set(m[1], m[2]);
-  return [...entries.entries()].map(([name, path]) => ({ name, path })).sort((a, b) => a.name.localeCompare(b.name));
+  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) {
@@ -99,6 +130,24 @@ function pathRootForQuestSkill(path) {
   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.
@@ -112,36 +161,101 @@ export function versionInfo() {
   };
 }
 
-export function installAgents({ scope = "project", dryRun = false, force = false, cwd = process.cwd(), env = process.env } = {}) {
-  const dir = targetDir(scope, cwd, env);
+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}.toml`);
-    const dest = join(dir, `${name}.toml`);
+    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 (exists && sameFile(dest, text)) action = "unchanged";
+    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 };
+    return { name, path: dest, action, text, reason: symlink ? "symlink" : undefined };
   });
 
-  const conflicts = plans.filter((p) => p.action === "conflict").map(({ name, path }) => ({ name, path }));
+  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, scope, target: dir, dry_run: dryRun, actions, conflicts };
+  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 } = {}) {
@@ -163,6 +277,8 @@ export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
     { versions },
   ));
 
+  checks.push(questCliPathCheck(cwd, env, versions));
+
   const codexVersion = runCmd("codex", ["--version"], { cwd, env });
   checks.push(check(
     "codex-cli",
@@ -188,7 +304,35 @@ export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
     checks.push(check(
       "plugin-version",
       Boolean(installed && installed.version === manifestVersion),
-      installed ? `installed=${installed.version}, manifest=${manifestVersion}` : `manifest=${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 });
@@ -207,40 +351,75 @@ export function doctor({ cwd = process.cwd(), env = process.env } = {}) {
     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,
-      paths.length ? `${entries.length} quest skills across ${roots.length} root(s)` : "quest skills not found in neutral prompt-input",
-      { skills: entries, missing_skills: missingSkills, skill_paths: paths, skill_roots: roots },
+      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 },
     ));
   }
 
-  const agentDirs = installedAgentDirs(cwd, env);
-  const missing = [];
-  const stale = [];
-  const found = {};
-  for (const name of AGENTS) {
-    const bundled = readFileSync(join(PLUGIN_ROOT, "agents", `${name}.toml`), "utf8");
-    const path = agentDirs.map((dir) => join(dir, `${name}.toml`)).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("; ") || `found: ${Object.values(found).join(", ")}`;
+  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(
-    "native-agents",
-    missing.length === 0 && stale.length === 0,
-    agentDetail,
-    { found, missing, stale },
+    "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/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",
   },
@@ -140,7 +141,7 @@ export const COMMANDS = {
     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, plugin install/version, hooks, skill roots, and native agents"],
+      ["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"],
@@ -149,6 +150,19 @@ export const COMMANDS = {
     ],
     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) {
@@ -202,13 +216,15 @@ export function renderNoStore() {
   ].join("\n");
 }
 
-export function renderInitNextSteps(backend) {
+export function renderInitNextSteps(backend, { agentsInstalled = true } = {}) {
   return [
     "",
     "Store created. Next steps:",
+    ...(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",
+    ...(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");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quest-loop",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Goal-loop engineering for coding agents: quest contracts, iterative execution with evidence checkpoints, Claude + Codex workers. Ships the `quest` store CLI and the `quest-run` headless runner.",
   "type": "module",
   "engines": { "node": ">=20" },

package/skills/orchestrate/SKILL.md

@@ -21,26 +21,50 @@ trails, and escalations only where a human ruling is genuinely needed.
    quest list --ready --json   # the dispatch queue (deps met, priority order)
    quest runs --active         # headless runners that outlived prior sessions
    ```
-2. **Dispatch** each ready quest per its record:
-   - In Codex, prefer the native `quest-executor` custom agent for an
-     interactive single quest; prompt = "Work quest <id> per $quest:work." If
-     the agent is missing, run `quest codex install-agents --scope project` (or
-     `$quest:setup`) before dispatching.
+   For an implementation accepted from `$quest:plan` in Codex Plan Mode, stay in
+   this orchestrator role. Do not implement product code inline; create/lint the
+   quest records if needed, then dispatch workers.
+2. **Pin the wave with native goal mode:**
+   - In Codex, call `create_goal` with this stopping condition:
+     "every quest in the scoped wave shows complete, blocked, or cancelled in
+     `quest list --json` output"; verify it with `get_goal`.
+   - In Claude Code, start the turn with `/goal` using the same condition.
+   If native goal mode is unavailable, say so and keep the Quest checkpoint
+   trail as the hard stop signal; do not pretend a goal was set.
+3. **Dispatch** each ready quest per its record:
+   - In Codex, the default path is native subagents for both serial and
+     parallel waves. If `spawn_agent` is not visible, call `tool_search` once
+     for subagent tools before choosing any fallback. When available, spawn:
+     `agent_type: "quest-executor"` and prompt =
+     `First call create_goal with: quest <id> has a new checkpoint whose
+     quest_status is complete or blocked in \`quest show <id> --json\`; verify
+     with get_goal; work quest <id> per $quest:work; only call
+     update_goal(status="complete") after the checkpoint exists.`
+     If the agent template is missing, run `quest codex install-agents --scope
+     project` (or `$quest:setup`) before dispatching.
    - In Claude Code, spawn the `quest-executor` subagent with the record's
-     `model`/`effort` as the dispatch override and the same prompt.
-   - For headless Codex/Claude work, parallel batches, or anything long-running,
-     run `quest-run <id>` in **background Bash** and keep working; you'll be
-     notified when it exits. Parallel file-disjoint quests:
-     `quest-run --ready --parallel 3` (add `--isolate worktree` when they touch
-     the same files).
-3. **Verify before you believe:** when a worker stops, run
+     `model`/`effort` as the dispatch override and prompt =
+     `/goal quest <id> has a new checkpoint whose quest_status is complete or
+     blocked in \`quest show <id> --json\`\nWork quest <id> per $quest:work.`
+   - Use `quest-run` only when native subagents are still unavailable after
+     `tool_search`, or when the user explicitly asks for headless/background
+     execution. Codex fallback must require goal mode:
+     `quest-run <id> --worker codex --codex-goal-mode require`. Headless
+     file-disjoint waves can use `quest-run --ready --parallel 3
+     --codex-goal-mode require` (add `--isolate worktree` when they touch the
+     same files). Claude headless runs already enter native `/goal` mode.
+4. **Verify before you believe:** when a worker stops, run
    `quest show <id> --json`. A stop WITHOUT a new checkpoint is a protocol
    violation — redispatch with exactly that instruction. Never accept a chat
    summary in place of a recorded checkpoint.
-4. **Review before accepting complete:** for non-trivial quests, spawn
-   `quest-reviewer` on the diff + checkpoint evidence. Every finding gets a
-   disposition: fixed / follow-up quest filed / rejected-with-reason.
-5. **Rule** (quote evidence, never adjectives):
+5. **Review before accepting complete:** for non-trivial quests, spawn
+   `quest-reviewer` on the diff + checkpoint evidence in the same harness. Give
+   it a goal: return an `accept` or `iterate` verdict with evidence. In Codex,
+   ask it to call `create_goal`/`get_goal` and only `update_goal` after the
+   verdict exists; in Claude Code, prefix the reviewer prompt with `/goal`.
+   Every finding gets a disposition: fixed / follow-up quest filed /
+   rejected-with-reason.
+6. **Rule** (quote evidence, never adjectives):
    - **accept** — the validation_summary's commands actually discharge the
      Done-when items.
    - **iterate-with-feedback** — send the specific gap back (continue the
@@ -49,7 +73,7 @@ trails, and escalations only where a human ruling is genuinely needed.
      re-parent the original honestly.
    - **escalate-to-human** — surface human-only decisions verbatim. Never
      guess a ruling the human should make.
-6. **Wave done?** When `quest list --ready` empties and nothing is in flight:
+7. **Wave done?** When `quest list --ready` empties and nothing is in flight:
    run `$quest:retro` before starting the next wave.
 
 ## Closing an epic
@@ -105,7 +129,7 @@ if so, reopen the epic too. `cancelled` is fully terminal — file a new quest.
 For an unattended wave, pin your own session to the outcome with a native goal:
 
 ```
-every quest in this wave shows complete or blocked in `quest list --json` output
+every quest in this wave shows complete, blocked, or cancelled in `quest list --json` output
 ```
 
 In Codex, use the native goal tool when available; in Claude Code, use
@@ -116,8 +140,8 @@ genuinely done.
 
 ```bash
 quest list --ready --json     # → [{"id":12,"worker":"claude"…},{"id":13,"worker":"codex"…}]
-# 12 → dispatch quest-executor subagent (model/effort from the record)
-# 13 → background Bash: quest-run 13
+# 12 → spawn quest-executor with a child /goal or create_goal prompt
+# 13 → spawn quest-executor too; use quest-run only if native subagents are unavailable
 # …executor stops →
 quest show 12 --json          # new checkpoint? quest_status? evidence?
 # reviewer on 12's diff → findings dispositioned → accept

package/skills/plan/SKILL.md

@@ -22,6 +22,28 @@ extra context.
 | Medium | 1 quest, dispatch an executor | needs iterations, fits one Objective |
 | Large | epic parent + child quests in waves | multiple objectives; order via `depends_on` |
 
+## Plan Mode handoff
+
+In Codex Plan Mode, do **not** implement product code after the user accepts a
+plan. Your role is to make the quest records real, then ask before orchestration:
+
+1. Create or confirm the quest records with `quest create` and `quest lint`.
+2. If the user accepted a plan and asked to implement it, your next role is
+   `$quest:orchestrate`, not `$quest:work`. Do not start editing product code in
+   the parent session.
+3. If the user only asked to create quests, ask whether to enter
+   `$quest:orchestrate` and dispatch the ready quests now. Do not silently
+   switch modes.
+4. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
+   goal-mode workers. If the user declines orchestration, stop after listing the
+   ready quest ids and validation commands.
+
+The parent session owns dispatch, checkpoint verification, reviewer rulings, and
+epic closure. The spawned executor owns implementation for exactly one quest.
+The parent session never uses `$quest:work <id>` after a Plan Mode handoff
+unless the user explicitly asks to bypass orchestration for a genuinely small
+single quest.
+
 For epics: create the parent first, then children with `--parent <id>` and
 `--depends-on` expressing the real order. `quest list --ready` becomes the
 dispatch queue — that is the whole wave mechanic.
@@ -51,8 +73,12 @@ Every field earns its place:
 - **Context**: files + symbols (`resolveConfig` in `lib/config.mjs`), related
   quests. NEVER bare line numbers — they rot.
 - **Out of scope**: the adjacent work you are explicitly not doing.
-- `--worker` / `--model` / `--effort` / `--max-iterations`: match the tier to
-  the difficulty; the defaults come from `.quests/config.json`.
+- `--worker`, `--model`, and `--effort`: always specify all three explicitly in
+  every `quest create` command you author. Pick them deliberately from the task's
+  risk, ambiguity, context size, and validation cost so the worker starts with
+  an intentional execution profile instead of inheriting blindly from defaults.
+- `--max-iterations`: match the loop budget to the difficulty; defaults in
+  `.quests/config.json` are fallback behavior, not a planning substitute.
 
 **Anti-patterns** (lint catches some, you catch the rest): adjective done-whens
 ("fast", "clean"); validation loops that are prose, not commands; objectives
@@ -61,7 +87,8 @@ hiding three objectives; context by line number; budgets so big they never bind.
 ## Worked example
 
 ```bash
-quest create --title "Add dark mode to settings" \
+quest create --worker codex --model gpt-5.5 --effort medium --max-iterations 4 \
+  --title "Add dark mode to settings" \
   --objective "The settings page offers a dark theme that persists across reloads." \
   --done-when "toggling theme switches the UI and survives reload" \
   --done-when "\`npm test\` passes including new theme tests" \
@@ -74,5 +101,6 @@ quest create --title "Add dark mode to settings" \
 quest lint 12   # always, before dispatch
 ```
 
-**Next:** dispatch with `$quest:orchestrate` (or work it yourself via
-`$quest:work <id>`). Rules and vocabulary: `$quest:protocol`.
+**Next:** dispatch with `$quest:orchestrate`. Only work it yourself via
+`$quest:work <id>` for genuinely small inline work outside Plan Mode and outside
+an accepted Plan Mode handoff. Rules and vocabulary: `$quest:protocol`.

package/skills/setup/SKILL.md

@@ -1,12 +1,31 @@
 ---
 name: setup
-description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex plugin integration.
-argument-hint: "[doctor|install-agents]"
+description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex or Claude plugin integration.
+argument-hint: "[doctor|install-agents|init]"
 ---
 
-# Set up Quest for Codex
+# Set up Quest native agents
 
-Use this for Codex integration work, not for ordinary quest execution.
+Use this for Codex or Claude integration work, not for ordinary quest execution.
+
+## Project Init
+
+`quest init` creates `.quests/` and, by default, installs project-scoped native
+agent templates for both providers:
+
+- `.codex/agents/quest-executor.toml`
+- `.codex/agents/quest-reviewer.toml`
+- `.claude/agents/quest-executor.md`
+- `.claude/agents/quest-reviewer.md`
+
+Use `quest init --no-agents` when you only want the quest store. If an existing
+project template conflicts, init fails before creating `.quests/`; inspect the
+file, run the explicit provider install command with `--force` only when you
+intend replacement, then rerun `quest init`.
+
+Project-scoped agent templates install at the Git repository root. For a nested
+quest store, use `quest init --no-agents` in the nested directory and set
+`QUEST_DIR` for agents launched from elsewhere, or initialize from the repo root.
 
 ## Doctor
 
@@ -16,26 +35,43 @@ Check the installed Codex-facing state from the actual Codex surfaces:
 quest codex doctor
 ```
 
-This verifies the Codex CLI, installed `quest@quest` plugin version, hook parser
-health, neutral-directory skill roots, and whether `quest-executor` plus
-`quest-reviewer` are available as native Codex custom agents.
+This verifies the Codex CLI, `quest` binary on PATH, `multi_agent` and `goals`
+feature flags, installed `quest@quest` plugin version, hook parser health,
+duplicate/stale Quest skill roots, and whether the `quest-executor` plus
+`quest-reviewer` native-agent templates are installed and current. Runtime
+dispatch still happens from the parent Codex session via native subagent tools;
+use `quest-run --codex-goal-mode require` only as the headless fallback.
+
+Check the installed Claude-facing state from the actual Claude surfaces:
+
+```bash
+quest claude doctor
+```
 
 ## Install Native Agents
 
-Install the custom agents for this repository:
+Install the Codex custom agents for this repository:
 
 ```bash
 quest codex install-agents --scope project
 ```
 
+Install the Claude custom agents for this repository:
+
+```bash
+quest claude install-agents --scope project
+```
+
 Use user scope only when you want the agents available everywhere:
 
 ```bash
 quest codex install-agents --scope user
+quest claude install-agents --scope user
 ```
 
 If an existing file conflicts, inspect it first. Use `--force` only when you
-intend to replace that custom agent with Quest's bundled definition.
+intend to replace that custom agent with Quest's bundled definition. Symlinked
+agent directories or files are refused rather than overwritten.
 
 ## Update Installed Plugin