@printpractical/cruze 0.0.2 → 0.0.3

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.2 is the second preview. It adds upgrading and `realign`, and the fixes from the first real project's retro. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.3 is the third preview. It sets projects up for agents other than Claude Code, and runs reviews in the agent's own helpers when no review agent is configured. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.3/printpractical-cruze-0.0.3.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.2
+npm install -g --install-links github:PrintPractical/cruze#v0.0.3
 ```
 
 ### 2. Set up a repository
@@ -61,21 +61,21 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.3/printpractical-cruze-0.0.3.tgz
 ```
 
-`init` asks for the project name, then creates:
+`init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
 
 | Path | Purpose |
 | --- | --- |
 | `README.md` | Titled with the project name |
 | `CHANGELOG.md` | In [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format |
 | `AGENTS.md` | Agent instructions; Cruze keeps its managed sections current |
-| `CLAUDE.md` | One line that imports `AGENTS.md`, for Claude Code |
-| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses |
+| `CLAUDE.md` | For Claude Code only: a link to `AGENTS.md` |
+| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses, and for Claude Code the command `cruze review` runs |
 | `.github/workflows/ci.yml` | CI that runs `cruze validate`, `check` and `trace`; the walking-skeleton change adds the language's build and test steps |
 | `.gitattributes` | Merges Cruze's journals line by line, so parallel branches don't conflict on them |
-| `.agents/skills/cruze-*` | The Cruze skills, linked into `.claude/skills/` for Claude Code |
+| `.agents/skills/cruze-*` | The Cruze skills, also linked into `.claude/skills/` for Claude Code |
 
 Existing files are never overwritten, so it is safe to run in an existing repository.
 
@@ -130,7 +130,7 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `cruze roadmap prune` | Clears landed items from the roadmap's status when a release closes |
 | `cruze trace` | Fails when a delivered scenario has no test carrying its ID; `--all` checks every built scenario |
 | `cruze check` | Enforces the layer rules and the file budgets; `--ci` also fails on budget warnings |
-| `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml` |
+| `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml`. When no command is set, or its program isn't installed, it prints the role's prompt for the agent to run in a helper of its own |
 | `cruze land` | Merges a verified change into the living docs, re-stamps the approvals the merge would make stale, fills the Commands and Layout sections of `AGENTS.md`, and archives finished work |
 | `cruze realign status` | Lists what the installed Cruze expects of existing code since its `standards:` version, with what the CLI rules find now; `--full` covers every release |
 | `cruze realign done` | Moves `standards:` up once every finding is fixed, waived or scheduled in a change named with `--change` |

package/dist/adapters/inbound/cli/commands/review.js

@@ -14,5 +14,5 @@ export async function runReviewCommand(context            , args          , opti
     ...(blockers === undefined ? {} : { blockers }),
     ...(options.base === undefined ? {} : { base: options.base }),
   });
-  return { json: report, human: report.report };
+  return { json: report, human: report.status === "reported" ? report.report : `${report.instruction}\n\n${report.prompt}` };
 }

package/dist/adapters/inbound/cli/commands.js

@@ -10,7 +10,7 @@ import { runReviewCommand } from "./commands/review.js";
 import { runNext, runStatus } from "./commands/status.js";
 
 export const COMMANDS                                                      = {
-  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent <agent>] [--package <npm spec>]   set up this repository and install the skills" },
+  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
   install: { handler: runInstall, usage: "install [--agent <agent>]                         install or update the Cruze skills" },
   validate: { handler: runValidate, usage: "validate                                          check every document against the formats" },
   status: { handler: runStatus, usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },

package/dist/adapters/outbound/node_project_files.js

@@ -78,7 +78,8 @@ export class NodeProjectFiles                         {
     this.assertInsideRoot(resolve(dirname(linkPath), target));
     await mkdir(dirname(linkPath), { recursive: true });
     await rm(linkPath, { recursive: true, force: true });
-    await symlink(target, linkPath, "dir");
+    // No link type: on Windows, Node picks a file or directory link from what the target is.
+    await symlink(target, linkPath);
   }
 
   /** Resolves a project-relative path, refusing anything outside the root. */

package/dist/adapters/outbound/process_agent_runner.js

@@ -11,15 +11,20 @@ export class ProcessAgentRunner                        {
 
   run(command          , prompt        )                    {
     const [program, ...args] = command;
-    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    if (program === undefined) return Promise.resolve({ kind: "missing" });
     return new Promise((resolve) => {
       const child = spawn(program, args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let output = "";
       let error = "";
       child.stdout.on("data", (chunk        ) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk        ) => (error += chunk.toString("utf8")));
-      child.on("error", (failure) => resolve({ exitCode: 127, output, error: `${error}${failure.message}` }));
-      child.on("close", (code) => resolve({ exitCode: code ?? 1, output, error }));
+      // Spawning reports ENOENT when the program isn't on the PATH.
+      child.on("error", (failure                       ) =>
+        resolve(failure.code === "ENOENT" ? { kind: "missing" } : { kind: "finished", exitCode: 127, output, error: `${error}${failure.message}` }),
+      );
+      child.on("close", (code) => resolve({ kind: "finished", exitCode: code ?? 1, output, error }));
+      // A program that never started closes stdin; ignore the write error, since the spawn error reports it.
+      child.stdin.on("error", () => {});
       child.stdin.end(prompt);
     });
   }

package/dist/app/ports/agent_runner.js

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
                               
-                                                                            
+     
+                                                                                           
+                                                                          
+     
                                                             
  
 
-                           
-                   
-                 
-                
- 
+                                                                                                                   

package/dist/app/use_cases/init_project.js

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { agentSkillHome } from "../../domain/agent_skill_homes.js";
 import { parseProjectName } from "../../domain/project_name.js";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.js";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD,                 renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.js";
                                                  
                                                               
                                                      
@@ -10,6 +12,7 @@ import { installSkills,                          } from "./install_skills.js";
                 
                                                                 
                       
+                                                                                                          
                    
      
                                                                                                 
@@ -20,6 +23,7 @@ import { installSkills,                          } from "./install_skills.js";
 
                                     
                   
+                   
                     
                                                             
                     
@@ -36,11 +40,13 @@ export async function initProject(
 )                             {
   const { files, bundle, prompter } = deps;
   const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const agent = await chooseAgent(files, prompter, request.agents);
   const values = {
     project_name: project,
     project_name_quoted: JSON.stringify(project),
     cruze_version: bundle.version,
     cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+    review_setting: (await bundle.template(reviewSettingTemplate(agent))).trimEnd(),
   };
 
   const created           = [];
@@ -53,7 +59,29 @@ export async function initProject(
     await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
     created.push(entry.path);
   }
+  if (agent === "claude") {
+    if (await files.exists(CLAUDE_INSTRUCTIONS.path)) skipped.push(CLAUDE_INSTRUCTIONS.path);
+    else {
+      await files.link(CLAUDE_INSTRUCTIONS.path, CLAUDE_INSTRUCTIONS.target);
+      created.push(CLAUDE_INSTRUCTIONS.path);
+    }
+  }
 
-  const skills = await installSkills({ files, bundle }, { agents: request.agents });
-  return { project, created, skipped, skills };
+  const linkFor = new Set(request.agents.filter((a) => a !== "other"));
+  if (agent === "claude") linkFor.add("claude");
+  const skills = await installSkills({ files, bundle }, { agents: [...linkFor] });
+  return { project, agent, created, skipped, skills };
+}
+
+/** The agent named with `--agent`, or shown by the project's files, or else the answer to asking. */
+async function chooseAgent(files              , prompter          , requested          )                     {
+  if (requested.includes("claude")) return "claude";
+  if (requested.includes("other")) return "other";
+  for (const marker of agentSkillHome("claude")?.markers ?? []) {
+    if (await files.exists(marker)) return "claude";
+  }
+  const answer = (await prompter.ask(`Coding agent (${INIT_AGENTS.join(" or ")})`, "claude")).trim().toLowerCase();
+  const agent = INIT_AGENTS.find((a) => a === answer);
+  if (agent === undefined) throw new CruzeError("unknown-agent", `Unknown agent: ${answer}. Answer ${INIT_AGENTS.join(" or ")}, or pass --agent.`);
+  return agent;
 }

package/dist/app/use_cases/run_review.js

@@ -18,16 +18,19 @@ export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researche
                 
  
 
-                               
-             
-                
-                    
-                 
- 
+/**
+ * The role's report, or, when the configured agent isn't installed, the prompt for the calling
+ * agent to run in a helper of its own.
+ */
+                                                                                
+                                          
+                                                                    
+  
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written.
+ * from the conversation that produced the work. Returns the role's report as written, or the
+ * prompt to run in a helper when the configured agent isn't installed.
  */
 export async function runReview(deps                                       , request               )                        {
   if (!(ROLES                     ).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps                                       , req
     context.map((line) => `- ${line}`).join("\n"),
   ].join("\n\n");
 
-  const command = view.config?.config?.review.command ?? [];
+  const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
+  const command = view.config?.config?.review.command;
+  if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
+  if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
   if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
-  const report               = { role, command, report: run.output.trim() };
-  if (request.item !== undefined) report.item = request.item;
-  return report;
+  return { ...subject, command, status: "reported", report: run.output.trim() };
+}
+
+/** Why cruze review can't start the fresh context itself, and how the calling agent does instead. */
+function helperInstruction(program                    )         {
+  return [
+    program === undefined ? "No review agent is configured under review.command." : `${program} is not installed, so cruze review can't start a fresh context.`,
+    "Start a helper agent with no conversation history, give it this prompt and nothing else, and take its report as the role's report.",
+    "If you can't start a helper, tell the user, and have them run the prompt in a new session.",
+    "To have cruze review start an agent itself, set review.command in .cruze/config.yaml.",
+  ].join(" ");
 }
 
 async function bundledRole(deps             , role      )                  {

package/dist/domain/config.js

@@ -19,12 +19,12 @@ import { parse as parseYaml } from "yaml";
                   
                                                                                 
                                    
-                                                                                              
-                                
+     
+                                                                                          
+                                                                                  
+     
+                                 
  
-
-/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
-export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
 
                         
                
@@ -95,8 +95,8 @@ export function parseConfig(text        )               {
     }
   }
   const review = asRecord(root["review"]) ?? {};
-  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
-  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+  const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
+  if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
 
   const config              = {
     version: 1,
@@ -109,7 +109,7 @@ export function parseConfig(text        )               {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }

package/dist/domain/scaffold.js

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD                           = [
   { path: "README.md", template: "init/README.md" },
   { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
   { path: "AGENTS.md", template: "init/AGENTS.md" },
-  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
   { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
+/**
+ * The agents `cruze init` sets a project up for: Claude Code, which gets `CLAUDE.md`, linked skills
+ * and a review command, or any other agent, which reads `AGENTS.md` and `.agents/skills/`.
+ */
+export const INIT_AGENTS = ["claude", "other"]         ;
+                                                     
+
+/** Claude Code reads `CLAUDE.md`, so init links it to `AGENTS.md` rather than keeping a second copy. */
+export const CLAUDE_INSTRUCTIONS = { path: "CLAUDE.md", target: "AGENTS.md" };
+
+/** The template for the config's `review:` setting, which only Claude Code gets filled in. */
+export function reviewSettingTemplate(agent           )         {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template        , values                        )         {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key        ) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",

package/skills/formats/reference/config.md

@@ -51,7 +51,7 @@ layers:
 | `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
 | `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
-| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. The default runs Claude Code in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. |
+| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |
 
 Rules for layers:
 

package/skills/realign/notes/0.0.3.md

@@ -0,0 +1,11 @@
+# Realign notes: 0.0.3
+
+## New work only
+
+### review-helper-fallback: A review runs in a helper when no review agent is configured or installed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a role", step 3
+
+### optional-review-command: review.command is optional, and set only for Claude Code
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/config.md`, "Configuration format"

package/skills/realign/notes.md

@@ -5,6 +5,7 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 ## Releases
 
 - [0.0.2](notes/0.0.2.md)
+- [0.0.3](notes/0.0.3.md)
 
 ## Format
 

package/skills/roles/SKILL.md

@@ -19,7 +19,7 @@ A role is a prompt with fixed inputs and a report as its only output. It runs in
 
 1. Read the role file and gather exactly the inputs it lists. Done when you have every input path, plus any command output the role asks for.
 2. Start a fresh context: a helper agent with no conversation history, where the agent can start one. Give it the role file's full text and the inputs the role lists, including draft documents it names, and nothing else. Your own opinions, the conversation and your reasons for the design stay out.
-3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher` or `auditor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. If that can't run either, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
+3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher` or `auditor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. When no agent is configured, or it isn't installed, it reports `status: run-in-helper` with the role's full prompt instead: start a helper, such as a subagent, and give it exactly that prompt. If no fresh context can run, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
 4. Take the report as it comes back. Check its evidence against the files before you act on any finding.
 
 ## Running a review

package/src/adapters/inbound/cli/commands/review.ts

@@ -14,5 +14,5 @@ export async function runReviewCommand(context: CliContext, args: string[], opti
     ...(blockers === undefined ? {} : { blockers }),
     ...(options.base === undefined ? {} : { base: options.base }),
   });
-  return { json: report, human: report.report };
+  return { json: report, human: report.status === "reported" ? report.report : `${report.instruction}\n\n${report.prompt}` };
 }

package/src/adapters/inbound/cli/commands.ts

@@ -10,7 +10,7 @@ import { runReviewCommand } from "./commands/review.ts";
 import { runNext, runStatus } from "./commands/status.ts";
 
 export const COMMANDS: Record<string, { handler: Handler; usage: string }> = {
-  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent <agent>] [--package <npm spec>]   set up this repository and install the skills" },
+  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
   install: { handler: runInstall, usage: "install [--agent <agent>]                         install or update the Cruze skills" },
   validate: { handler: runValidate, usage: "validate                                          check every document against the formats" },
   status: { handler: runStatus, usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },

package/src/adapters/outbound/node_project_files.ts

@@ -78,7 +78,8 @@ export class NodeProjectFiles implements ProjectFiles {
     this.assertInsideRoot(resolve(dirname(linkPath), target));
     await mkdir(dirname(linkPath), { recursive: true });
     await rm(linkPath, { recursive: true, force: true });
-    await symlink(target, linkPath, "dir");
+    // No link type: on Windows, Node picks a file or directory link from what the target is.
+    await symlink(target, linkPath);
   }
 
   /** Resolves a project-relative path, refusing anything outside the root. */

package/src/adapters/outbound/process_agent_runner.ts

@@ -11,15 +11,20 @@ export class ProcessAgentRunner implements AgentRunner {
 
   run(command: string[], prompt: string): Promise<AgentRun> {
     const [program, ...args] = command;
-    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    if (program === undefined) return Promise.resolve({ kind: "missing" });
     return new Promise((resolve) => {
       const child = spawn(program, args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let output = "";
       let error = "";
       child.stdout.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk: Buffer) => (error += chunk.toString("utf8")));
-      child.on("error", (failure) => resolve({ exitCode: 127, output, error: `${error}${failure.message}` }));
-      child.on("close", (code) => resolve({ exitCode: code ?? 1, output, error }));
+      // Spawning reports ENOENT when the program isn't on the PATH.
+      child.on("error", (failure: NodeJS.ErrnoException) =>
+        resolve(failure.code === "ENOENT" ? { kind: "missing" } : { kind: "finished", exitCode: 127, output, error: `${error}${failure.message}` }),
+      );
+      child.on("close", (code) => resolve({ kind: "finished", exitCode: code ?? 1, output, error }));
+      // A program that never started closes stdin; ignore the write error, since the spawn error reports it.
+      child.stdin.on("error", () => {});
       child.stdin.end(prompt);
     });
   }

package/src/app/ports/agent_runner.ts

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
 export interface AgentRunner {
-  /** Runs `command` in the project root with `prompt` on standard input. */
+  /**
+   * Runs `command` in the project root with `prompt` on standard input. Reports `missing`,
+   * without running anything, when the command's program isn't installed.
+   */
   run(command: string[], prompt: string): Promise<AgentRun>;
 }
 
-export interface AgentRun {
-  exitCode: number;
-  output: string;
-  error: string;
-}
+export type AgentRun = { kind: "finished"; exitCode: number; output: string; error: string } | { kind: "missing" };

package/src/app/use_cases/init_project.ts

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { agentSkillHome } from "../../domain/agent_skill_homes.ts";
 import { parseProjectName } from "../../domain/project_name.ts";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.ts";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD, type InitAgent, renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.ts";
 import type { Bundle } from "../ports/bundle.ts";
 import type { ProjectFiles } from "../ports/project_files.ts";
 import type { Prompter } from "../ports/prompter.ts";
@@ -10,6 +12,7 @@ export interface InitProjectRequest {
   name?: string;
   /** Offered as the default answer when asking for the name. */
   defaultName: string;
+  /** From `--agent`: `claude`, `other`, or agents to link skills for. Asked for when it names neither. */
   agents: string[];
   /**
    * How CI runs this version of Cruze through npx, such as `github:PrintPractical/cruze#v0.0.1`
@@ -20,6 +23,7 @@ export interface InitProjectRequest {
 
 export interface InitProjectReport {
   project: string;
+  agent: InitAgent;
   created: string[];
   /** Files that already existed and were left untouched. */
   skipped: string[];
@@ -36,11 +40,13 @@ export async function initProject(
 ): Promise<InitProjectReport> {
   const { files, bundle, prompter } = deps;
   const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const agent = await chooseAgent(files, prompter, request.agents);
   const values = {
     project_name: project,
     project_name_quoted: JSON.stringify(project),
     cruze_version: bundle.version,
     cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+    review_setting: (await bundle.template(reviewSettingTemplate(agent))).trimEnd(),
   };
 
   const created: string[] = [];
@@ -53,7 +59,29 @@ export async function initProject(
     await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
     created.push(entry.path);
   }
+  if (agent === "claude") {
+    if (await files.exists(CLAUDE_INSTRUCTIONS.path)) skipped.push(CLAUDE_INSTRUCTIONS.path);
+    else {
+      await files.link(CLAUDE_INSTRUCTIONS.path, CLAUDE_INSTRUCTIONS.target);
+      created.push(CLAUDE_INSTRUCTIONS.path);
+    }
+  }
 
-  const skills = await installSkills({ files, bundle }, { agents: request.agents });
-  return { project, created, skipped, skills };
+  const linkFor = new Set(request.agents.filter((a) => a !== "other"));
+  if (agent === "claude") linkFor.add("claude");
+  const skills = await installSkills({ files, bundle }, { agents: [...linkFor] });
+  return { project, agent, created, skipped, skills };
+}
+
+/** The agent named with `--agent`, or shown by the project's files, or else the answer to asking. */
+async function chooseAgent(files: ProjectFiles, prompter: Prompter, requested: string[]): Promise<InitAgent> {
+  if (requested.includes("claude")) return "claude";
+  if (requested.includes("other")) return "other";
+  for (const marker of agentSkillHome("claude")?.markers ?? []) {
+    if (await files.exists(marker)) return "claude";
+  }
+  const answer = (await prompter.ask(`Coding agent (${INIT_AGENTS.join(" or ")})`, "claude")).trim().toLowerCase();
+  const agent = INIT_AGENTS.find((a) => a === answer);
+  if (agent === undefined) throw new CruzeError("unknown-agent", `Unknown agent: ${answer}. Answer ${INIT_AGENTS.join(" or ")}, or pass --agent.`);
+  return agent;
 }

package/src/app/use_cases/run_review.ts

@@ -18,16 +18,19 @@ export interface ReviewRequest {
   base?: string;
 }
 
-export interface ReviewReport {
-  role: Role;
-  item?: string;
-  command: string[];
-  report: string;
-}
+/**
+ * The role's report, or, when the configured agent isn't installed, the prompt for the calling
+ * agent to run in a helper of its own.
+ */
+export type ReviewReport = { role: Role; item?: string; command?: string[] } & (
+  | { status: "reported"; report: string }
+  | { status: "run-in-helper"; instruction: string; prompt: string }
+);
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written.
+ * from the conversation that produced the work. Returns the role's report as written, or the
+ * prompt to run in a helper when the configured agent isn't installed.
  */
 export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, request: ReviewRequest): Promise<ReviewReport> {
   if (!(ROLES as readonly string[]).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, req
     context.map((line) => `- ${line}`).join("\n"),
   ].join("\n\n");
 
-  const command = view.config?.config?.review.command ?? [];
+  const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
+  const command = view.config?.config?.review.command;
+  if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
+  if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
   if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
-  const report: ReviewReport = { role, command, report: run.output.trim() };
-  if (request.item !== undefined) report.item = request.item;
-  return report;
+  return { ...subject, command, status: "reported", report: run.output.trim() };
+}
+
+/** Why cruze review can't start the fresh context itself, and how the calling agent does instead. */
+function helperInstruction(program: string | undefined): string {
+  return [
+    program === undefined ? "No review agent is configured under review.command." : `${program} is not installed, so cruze review can't start a fresh context.`,
+    "Start a helper agent with no conversation history, give it this prompt and nothing else, and take its report as the role's report.",
+    "If you can't start a helper, tell the user, and have them run the prompt in a new session.",
+    "To have cruze review start an agent itself, set review.command in .cruze/config.yaml.",
+  ].join(" ");
 }
 
 async function bundledRole(deps: ProjectDeps, role: Role): Promise<string> {

package/src/domain/config.ts

@@ -19,13 +19,13 @@ export interface CruzeConfig {
   layers: Layer[];
   /** Named project commands, such as `test: cargo test`, shown in AGENTS.md. */
   commands: Record<string, string>;
-  /** How `cruze review` starts an agent in a fresh context: the program and its arguments. */
-  review: { command: string[] };
+  /**
+   * How `cruze review` starts an agent in a fresh context: the program and its arguments.
+   * Without one, the calling agent runs the role's prompt in a helper of its own.
+   */
+  review: { command?: string[] };
 }
 
-/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
-export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
-
 export interface Layer {
   name: string;
   paths: string[];
@@ -95,8 +95,8 @@ export function parseConfig(text: string): ConfigResult {
     }
   }
   const review = asRecord(root["review"]) ?? {};
-  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
-  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+  const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
+  if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
 
   const config: CruzeConfig = {
     version: 1,
@@ -109,7 +109,7 @@ export function parseConfig(text: string): ConfigResult {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }

package/src/domain/scaffold.ts

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD: readonly ScaffoldEntry[] = [
   { path: "README.md", template: "init/README.md" },
   { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
   { path: "AGENTS.md", template: "init/AGENTS.md" },
-  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
   { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
+/**
+ * The agents `cruze init` sets a project up for: Claude Code, which gets `CLAUDE.md`, linked skills
+ * and a review command, or any other agent, which reads `AGENTS.md` and `.agents/skills/`.
+ */
+export const INIT_AGENTS = ["claude", "other"] as const;
+export type InitAgent = (typeof INIT_AGENTS)[number];
+
+/** Claude Code reads `CLAUDE.md`, so init links it to `AGENTS.md` rather than keeping a second copy. */
+export const CLAUDE_INSTRUCTIONS = { path: "CLAUDE.md", target: "AGENTS.md" };
+
+/** The template for the config's `review:` setting, which only Claude Code gets filled in. */
+export function reviewSettingTemplate(agent: InitAgent): string {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template: string, values: Record<string, string>): string {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key: string) => {

package/templates/init/config.yaml

@@ -29,9 +29,4 @@ layers: []
 # walking-skeleton change fills them in; `cruze land` copies them into AGENTS.md.
 commands: {}
 
-# How `cruze review` starts an agent in a fresh context to run a role, with the
-# prompt on standard input. The default lets Claude Code read the project and run
-# git and cruze. The verifier runs the system, so add the project's build and run
-# commands, such as "Bash(cargo:*)". For Codex, use ["codex", "exec", "-"].
-review:
-  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]
+{{review_setting}}

package/templates/init/review/claude.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. This lets Claude Code read the project and run git
+# and cruze. The verifier runs the system, so add the project's build and run
+# commands, such as "Bash(cargo:*)". Without review.command, your agent runs each
+# role in a helper of its own.
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]

package/templates/init/review/other.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. Without it, your agent runs each role in a helper
+# of its own. To have cruze review start one instead, set the command, such as
+# ["codex", "exec", "-"] for Codex or ["opencode", "run", "--agent", "plan"] for
+# OpenCode.
+# review:
+#   command: ["codex", "exec", "-"]

package/templates/init/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md