@crouton-kit/crouter 0.3.3 → 0.3.8

package/README.md

@@ -19,8 +19,8 @@ crtr --help
 Browse and install plugins from it:
 
 ```bash
-crtr marketplace browse crouter-official-marketplace
-crtr marketplace install crouter-official-marketplace:<plugin>
+crtr pkg market inspect browse --marketplace crouter-official-marketplace
+crtr pkg market manage install --marketplace crouter-official-marketplace --plugin <plugin>
 ```
 
 To opt out of the bootstrap (e.g. in CI), set `CRTR_NO_BOOTSTRAP=1`.

package/dist/builtin-skills/skills/crouter-development/marketplaces/SKILL.md

@@ -107,7 +107,7 @@ mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/skills
 $EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
 
 # Add at least one skill
-crtr skill author scaffold my-new-plugin:first-skill --type playbook --description "Use when …"
+crtr skill author scaffold my-new-plugin/first-skill --type playbook --description "Use when …"
 
 # Add the plugin to the marketplace index
 $EDITOR .crouter-marketplace/marketplace.json

package/dist/builtin-skills/skills/crouter-development/plugins/SKILL.md

@@ -96,7 +96,7 @@ Three ways a plugin lands in a scope:
 mkdir -p my-plugin/.crouter-plugin my-plugin/skills
 $EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
 cd my-plugin
-crtr skill author scaffold my-plugin:my-first-skill --type playbook --description "Use when …"
+crtr skill author scaffold my-plugin/my-first-skill --type playbook --description "Use when …"
 
 # Symlink for fast iteration — no clone, edits land immediately
 ln -s $(pwd) ~/.crouter/plugins/my-plugin
@@ -124,9 +124,9 @@ Standard semver:
 
 ## Enable/disable
 
-`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill find list` and don't resolve via `crtr skill read show <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
+`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill find list` and don't resolve via `crtr skill read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
-Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>:<skill>`.
+Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>/<skill>`.
 
 ## What goes in a plugin
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { defineRoot, runCli } from './core/command.js';
-import { registerFlow } from './commands/flow.js';
+import { registerAgent } from './commands/agent.js';
 import { registerSkill } from './commands/skill.js';
 import { registerPkg } from './commands/pkg.js';
 import { registerJob } from './commands/job.js';
@@ -12,18 +12,18 @@ const root = defineRoot({
     help: {
         tagline: 'crtr: agentic planning runtime.',
         concepts: [
-            { name: 'flow', desc: 'spec → plan → debug: the development process' },
+            { name: 'agent', desc: 'agentic workflows: spec → plan → debug, and spawning workers' },
             { name: 'skill', desc: 'loadable SKILL.md document an agent reads to adopt a workflow' },
             { name: 'pkg', desc: 'plugins and marketplaces that supply skills' },
-            { name: 'job', desc: 'a running agent worker and its logs and result' },
+            { name: 'job', desc: 'producer-agnostic record of any ongoing task — its logs and result' },
             { name: 'human', desc: 'human-in-the-loop decisions, document review, and live display' },
             { name: 'sys', desc: 'crtr configuration, diagnostics, and self-management' },
         ],
         subtrees: [
-            { name: 'flow', desc: 'spec, plan, and debug workflows', useWhen: 'capturing requirements, planning work, or root-causing a bug' },
+            { name: 'agent', desc: 'spec/plan/debug and spawn workers', useWhen: 'capturing requirements, planning, debugging, or launching an agent worker' },
             { name: 'skill', desc: 'discover, read, author, and manage skills', useWhen: 'working with SKILL.md documents' },
             { name: 'pkg', desc: 'manage plugins and marketplaces', useWhen: 'installing or browsing skill collections' },
-            { name: 'job', desc: 'spawn, monitor, and collect from agent workers', useWhen: 'running or watching agent jobs' },
+            { name: 'job', desc: 'monitor and collect from any ongoing task', useWhen: 'reading status, logs, or result of a job started by any producer' },
             { name: 'human', desc: 'ask, approve, review, notify, show, inbox, list', useWhen: 'putting a decision or document in front of a person' },
             { name: 'sys', desc: 'config, doctor, update, version', useWhen: 'managing the crtr installation' },
         ],
@@ -32,7 +32,7 @@ const root = defineRoot({
         ],
     },
     subtrees: [
-        registerFlow(),
+        registerAgent(),
         registerSkill(),
         registerPkg(),
         registerJob(),

package/dist/commands/__tests__/skill.test.js

@@ -139,14 +139,15 @@ describe('skill find grep params', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// skill read show
+// skill read
 // ---------------------------------------------------------------------------
-describe('skill read show params', () => {
+describe('skill read params', () => {
     const params = [
         { kind: 'positional', name: 'name', required: true, constraint: '' },
         scopeWriteFlag,
         pluginFlag,
         { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: '' },
+        { kind: 'flag', name: 'no-body', type: 'bool', required: false, constraint: '' },
     ];
     test('name positional required', async () => {
         await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
@@ -155,6 +156,10 @@ describe('skill read show params', () => {
         const r = await parseArgv(params, ['my-skill']);
         assert.equal(r['name'], 'my-skill');
     });
+    test('nested name parsed correctly', async () => {
+        const r = await parseArgv(params, ['some/nested/skill']);
+        assert.equal(r['name'], 'some/nested/skill');
+    });
     test('--frontmatter presence = true', async () => {
         const r = await parseArgv(params, ['my-skill', '--frontmatter']);
         assert.equal(r['frontmatter'], true);
@@ -163,6 +168,14 @@ describe('skill read show params', () => {
         const r = await parseArgv(params, ['my-skill']);
         assert.equal(r['frontmatter'], false);
     });
+    test('--no-body presence = true (kebab to camelCase key)', async () => {
+        const r = await parseArgv(params, ['my-skill', '--no-body']);
+        assert.equal(r['noBody'], true);
+    });
+    test('--no-body absent = false', async () => {
+        const r = await parseArgv(params, ['my-skill']);
+        assert.equal(r['noBody'], false);
+    });
     test('--scope rejects all', async () => {
         await assert.rejects(() => parseArgv(params, ['my-skill', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
     });
@@ -170,23 +183,6 @@ describe('skill read show params', () => {
         const r = await parseArgv(params, ['my-skill', '--scope', 'user']);
         assert.equal(r['scope'], 'user');
     });
-});
-// ---------------------------------------------------------------------------
-// skill read where
-// ---------------------------------------------------------------------------
-describe('skill read where params', () => {
-    const params = [
-        { kind: 'positional', name: 'name', required: true, constraint: '' },
-        scopeWriteFlag,
-        pluginFlag,
-    ];
-    test('name positional required', async () => {
-        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
-    });
-    test('name parsed correctly', async () => {
-        const r = await parseArgv(params, ['some/nested/skill']);
-        assert.equal(r['name'], 'some/nested/skill');
-    });
     test('--scope project valid', async () => {
         const r = await parseArgv(params, ['skillname', '--scope', 'project']);
         assert.equal(r['scope'], 'project');
@@ -239,26 +235,26 @@ describe('skill author scaffold params', () => {
         await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
     });
     test('qualifier parsed correctly', async () => {
-        const r = await parseArgv(params, ['myplugin:myskill']);
-        assert.equal(r['qualifier'], 'myplugin:myskill');
+        const r = await parseArgv(params, ['myplugin/myskill']);
+        assert.equal(r['qualifier'], 'myplugin/myskill');
     });
     test('full invocation', async () => {
         const r = await parseArgv(params, [
-            'myplugin:myskill',
+            'myplugin/myskill',
             '--type', 'playbook',
             '--scope', 'project',
             '--description', 'Use when debugging',
         ]);
-        assert.equal(r['qualifier'], 'myplugin:myskill');
+        assert.equal(r['qualifier'], 'myplugin/myskill');
         assert.equal(r['type'], 'playbook');
         assert.equal(r['scope'], 'project');
         assert.equal(r['description'], 'Use when debugging');
     });
     test('--type invalid rejects', async () => {
-        await assert.rejects(() => parseArgv(params, ['q:s', '--type', 'invalid']), (e) => { assert.match(e.message, /must be one of/); return true; });
+        await assert.rejects(() => parseArgv(params, ['q/s', '--type', 'invalid']), (e) => { assert.match(e.message, /must be one of/); return true; });
     });
     test('--scope all rejects', async () => {
-        await assert.rejects(() => parseArgv(params, ['q:s', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
+        await assert.rejects(() => parseArgv(params, ['q/s', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
     });
 });
 // ---------------------------------------------------------------------------
@@ -287,8 +283,8 @@ describe('skill state enable/disable params', () => {
     test('--scope all rejects', async () => {
         await assert.rejects(() => parseArgv(params, ['my-skill', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
     });
-    test('plugin:skill qualifier as name', async () => {
-        const r = await parseArgv(params, ['myplugin:myskill']);
-        assert.equal(r['name'], 'myplugin:myskill');
+    test('plugin/skill qualifier as name', async () => {
+        const r = await parseArgv(params, ['myplugin/myskill']);
+        assert.equal(r['name'], 'myplugin/myskill');
     });
 });

package/dist/commands/{flow.d.ts → agent.d.ts}

@@ -1,2 +1,2 @@
 import type { BranchDef } from '../core/command.js';
-export declare function registerFlow(): BranchDef;
+export declare function registerAgent(): BranchDef;

package/dist/commands/agent.js

@@ -0,0 +1,384 @@
+// `crtr agent` umbrella — agentic workflows: spec/plan/debug + spawn primitives.
+//
+// `agent new {prompt,fork,planner,implementer,reviewer}` are the spawn leaves
+// (formerly `job start *`). Spawning creates a job record; monitoring lives at
+// `crtr job`. This split keeps the job registry agnostic of producer — agents
+// are one producer, future producers compose under their own subtree.
+//
+// Terminal-write contract for spawned workers:
+//   Worker calls `crtr job submit` → jobs.writeResult(jobId, result, 'done').
+//   If claude exits without submitting, the wrapper shell calls `crtr job _fail`
+//   → jobs.writeResult(jobId, {}, 'failed') IF result.json does not yet exist.
+//   `job read result` watches result.json appearance as the sole completion signal.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { createJob, appendEvent } from '../core/jobs.js';
+import { spawnAgent, spawnAndDetach, isInTmux } from '../core/spawn.js';
+import { readConfig } from '../core/config.js';
+import { planHandoffPrompt, implementHandoffPrompt, reviewerHandoffPrompt } from '../prompts/agent.js';
+import { existsSync } from 'node:fs';
+import { registerSpec } from './spec.js';
+import { registerPlan } from './plan.js';
+import { registerDebug } from './debug.js';
+const DEFAULT_KILL_SECS = 2;
+function followUpResult(jobId) {
+    return `crtr job read result ${jobId} --wait`;
+}
+function resolveMaxPanes() {
+    const cfg = readConfig('user');
+    return cfg.max_panes_per_window;
+}
+function assertTmux() {
+    if (!isInTmux()) {
+        throw new InputError({
+            error: 'not_in_tmux',
+            message: 'crtr agent new requires tmux (TMUX env var not set).',
+            next: 'Run inside a tmux session.',
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// agent new prompt
+// ---------------------------------------------------------------------------
+const newPrompt = defineLeaf({
+    name: 'prompt',
+    help: {
+        name: 'agent new prompt',
+        summary: 'spawn a fresh Claude agent with a prompt; returns a job handle immediately',
+        params: [
+            { kind: 'stdin', name: 'prompt', required: true, constraint: 'Prompt text sent to the spawned agent.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory for the spawned agent. Defaults to process.cwd().' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Display name passed to `claude -n`; surfaces in pane title and /resume picker.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `crtr job read status|logs|result` and `crtr job cancel`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Spawns a Claude agent in a sibling tmux pane.',
+            'Creates a job entry at $XDG_STATE_HOME/crtr/jobs/<job_id>/.',
+            'On completion, result writes atomically to result.json.',
+        ],
+    },
+    run: async (input) => {
+        assertTmux();
+        const prompt = input['prompt'];
+        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
+        const name = input['name'];
+        const { jobId } = createJob('prompt', { cwd });
+        const promptWithSubmit = `${prompt}
+
+---
+When your task is complete, submit your result (markdown body piped on stdin):
+\`\`\`bash
+crtr job submit ${jobId} <<'MD'
+<your result as markdown>
+MD
+\`\`\`
+If you cannot complete the task, submit a failure with a reason (no stdin needed):
+\`\`\`bash
+crtr job submit ${jobId} --status failed --reason "<why>"
+\`\`\``;
+        const result = spawnAgent({
+            prompt: promptWithSubmit,
+            cwd,
+            jobId,
+            maxPanesPerWindow: resolveMaxPanes(),
+            name,
+        });
+        if (result.status === 'not-in-tmux') {
+            throw new InputError({ error: 'not_in_tmux', message: result.message, next: 'Run inside a tmux session.' });
+        }
+        if (result.status === 'spawn-failed') {
+            throw new InputError({ error: 'spawn_failed', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        const paneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `pane ${paneLabel} spawned` });
+        return { job_id: jobId, follow_up: followUpResult(jobId) };
+    },
+});
+// ---------------------------------------------------------------------------
+// agent new fork
+// ---------------------------------------------------------------------------
+const newFork = defineLeaf({
+    name: 'fork',
+    help: {
+        name: 'agent new fork',
+        summary: 'fork the current Claude session into a sibling pane; returns a job handle immediately',
+        params: [
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Display name passed to `claude -n`; surfaces in pane title and /resume picker.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `crtr job read *` and `crtr job cancel`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Requires $CLAUDE_CODE_SESSION_ID — must run inside Claude Code.',
+            'Spawns a forked Claude session in a sibling tmux pane.',
+            'Creates a job entry and result sidecar as with `agent new prompt`.',
+        ],
+    },
+    run: async (input) => {
+        assertTmux();
+        const parentSessionId = process.env['CLAUDE_CODE_SESSION_ID'];
+        if (parentSessionId === undefined || parentSessionId === '') {
+            throw new InputError({
+                error: 'missing_session_id',
+                message: 'crtr agent new fork requires $CLAUDE_CODE_SESSION_ID — must run inside Claude Code.',
+                next: 'Run this command from within a Claude Code session.',
+            });
+        }
+        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
+        const name = input['name'];
+        const { jobId } = createJob('fork', { cwd });
+        const promptWithSubmit = `Fork of session ${parentSessionId}
+
+---
+When your task is complete, submit your result (markdown body piped on stdin):
+\`\`\`bash
+crtr job submit ${jobId} <<'MD'
+<your result as markdown>
+MD
+\`\`\`
+If you cannot complete the task, submit a failure with a reason (no stdin needed):
+\`\`\`bash
+crtr job submit ${jobId} --status failed --reason "<why>"
+\`\`\``;
+        const result = spawnAgent({
+            prompt: promptWithSubmit,
+            cwd,
+            jobId,
+            fork: { sessionId: parentSessionId },
+            maxPanesPerWindow: resolveMaxPanes(),
+            name,
+        });
+        if (result.status === 'not-in-tmux') {
+            throw new InputError({ error: 'not_in_tmux', message: result.message, next: 'Run inside a tmux session.' });
+        }
+        if (result.status === 'spawn-failed') {
+            throw new InputError({ error: 'spawn_failed', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        const forkPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `forked pane ${forkPaneLabel} spawned` });
+        return { job_id: jobId, follow_up: followUpResult(jobId) };
+    },
+});
+// ---------------------------------------------------------------------------
+// agent new planner
+// ---------------------------------------------------------------------------
+const newPlanner = defineLeaf({
+    name: 'planner',
+    help: {
+        name: 'agent new planner',
+        summary: 'launch a planning agent for an approved spec; closes the originating pane after handoff',
+        params: [
+            { kind: 'positional', name: 'spec_path', type: 'path', required: true, constraint: 'Absolute path to the spec file.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Display name passed to `claude -n`; surfaces in pane title and /resume picker.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `crtr job read *` and `crtr job cancel`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Spawns a planner agent in a sibling tmux pane.',
+            'Closes the originating pane after a short delay.',
+            'Creates a job entry and result sidecar.',
+        ],
+    },
+    run: async (input) => {
+        assertTmux();
+        const specPath = input['spec_path'];
+        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
+        const name = input['name'];
+        if (!existsSync(specPath)) {
+            throw new InputError({
+                error: 'not_found',
+                message: `spec not found: ${specPath}`,
+                field: 'spec_path',
+                next: 'Provide an absolute path to an existing spec file.',
+            });
+        }
+        const { jobId } = createJob('planner', { cwd });
+        const result = spawnAndDetach({
+            prompt: planHandoffPrompt(specPath, jobId),
+            cwd,
+            jobId,
+            placement: 'split-h',
+            killAfterSeconds: DEFAULT_KILL_SECS,
+            name,
+        });
+        if (result.status === 'not-in-tmux') {
+            throw new InputError({ error: 'not_in_tmux', message: result.message, next: 'Run inside a tmux session.' });
+        }
+        if (result.status === 'spawn-failed') {
+            throw new InputError({ error: 'spawn_failed', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        const plannerPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `planner pane ${plannerPaneLabel} spawned` });
+        return { job_id: jobId, follow_up: followUpResult(jobId) };
+    },
+});
+// ---------------------------------------------------------------------------
+// agent new implementer
+// ---------------------------------------------------------------------------
+const newImplementer = defineLeaf({
+    name: 'implementer',
+    help: {
+        name: 'agent new implementer',
+        summary: 'launch an implementation agent for an approved plan; closes the originating pane after handoff',
+        params: [
+            { kind: 'positional', name: 'plan_path', type: 'path', required: true, constraint: 'Absolute path to the plan file.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Display name passed to `claude -n`; surfaces in pane title and /resume picker.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `crtr job read *` and `crtr job cancel`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Spawns an implementer agent in a sibling tmux pane.',
+            'Closes the originating pane after a short delay.',
+            'Creates a job entry and result sidecar.',
+        ],
+    },
+    run: async (input) => {
+        assertTmux();
+        const planPath = input['plan_path'];
+        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
+        const name = input['name'];
+        if (!existsSync(planPath)) {
+            throw new InputError({
+                error: 'not_found',
+                message: `plan not found: ${planPath}`,
+                field: 'plan_path',
+                next: 'Provide an absolute path to an existing plan file.',
+            });
+        }
+        const { jobId } = createJob('implementer', { cwd });
+        const result = spawnAndDetach({
+            prompt: implementHandoffPrompt(planPath, jobId),
+            cwd,
+            jobId,
+            placement: 'split-h',
+            killAfterSeconds: DEFAULT_KILL_SECS,
+            name,
+        });
+        if (result.status === 'not-in-tmux') {
+            throw new InputError({ error: 'not_in_tmux', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        if (result.status === 'spawn-failed') {
+            throw new InputError({ error: 'spawn_failed', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        const implPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `implementer pane ${implPaneLabel} spawned` });
+        return { job_id: jobId, follow_up: followUpResult(jobId) };
+    },
+});
+// ---------------------------------------------------------------------------
+// agent new reviewer
+// ---------------------------------------------------------------------------
+const newReviewer = defineLeaf({
+    name: 'reviewer',
+    help: {
+        name: 'agent new reviewer',
+        summary: 'launch a reviewer agent for a plan or spec artifact; the originating pane stays alive to collect the verdict',
+        params: [
+            { kind: 'positional', name: 'artifact_path', type: 'path', required: true, constraint: 'Absolute path to the artifact to review.' },
+            { kind: 'flag', name: 'kind', type: 'enum', choices: ['plan', 'spec'], required: true, constraint: 'Artifact kind to review.' },
+            { kind: 'flag', name: 'spec-path', type: 'path', required: false, constraint: 'Absolute path to the spec, for plan reviews. Omit for spec reviews.' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Working directory. Defaults to process.cwd().' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Display name passed to `claude -n`; surfaces in pane title and /resume picker.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with `crtr job read *` and `crtr job cancel`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Spawns a reviewer agent in a sibling tmux pane.',
+            'The originating pane stays alive — wait on the result and act on the verdict.',
+            'Creates a job entry and result sidecar.',
+        ],
+    },
+    run: async (input) => {
+        assertTmux();
+        const artifactPath = input['artifact_path'];
+        const artifactKind = input['kind'];
+        const specPath = typeof input['specPath'] === 'string' ? input['specPath'] : undefined;
+        const cwd = typeof input['cwd'] === 'string' ? input['cwd'] : process.cwd();
+        const name = input['name'];
+        if (!existsSync(artifactPath)) {
+            throw new InputError({
+                error: 'not_found',
+                message: `artifact not found: ${artifactPath}`,
+                field: 'artifact_path',
+                next: 'Provide an absolute path to an existing artifact file.',
+            });
+        }
+        const { jobId } = createJob('reviewer', { cwd });
+        // The reviewer is a subordinate the caller waits on (verdict → revise or
+        // hand off), NOT a handoff successor. Use spawnAgent so the originating
+        // pane (planner/orchestrator) stays alive to collect the result; do not
+        // self-kill the caller the way planner/implementer handoffs do.
+        const result = spawnAgent({
+            prompt: reviewerHandoffPrompt(artifactPath, artifactKind, specPath !== undefined ? specPath : null, jobId),
+            cwd,
+            jobId,
+            maxPanesPerWindow: resolveMaxPanes(),
+            name,
+        });
+        if (result.status === 'not-in-tmux') {
+            throw new InputError({ error: 'not_in_tmux', message: result.message, next: 'Run inside a tmux session.' });
+        }
+        if (result.status === 'spawn-failed') {
+            throw new InputError({ error: 'spawn_failed', message: result.message, next: 'Check tmux is running and try again.' });
+        }
+        const reviewerPaneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+        appendEvent(jobId, { level: 'info', event: 'worker_started', message: `reviewer pane ${reviewerPaneLabel} spawned` });
+        return { job_id: jobId, follow_up: followUpResult(jobId) };
+    },
+});
+// ---------------------------------------------------------------------------
+// agent new (branch)
+// ---------------------------------------------------------------------------
+const newBranch = defineBranch({
+    name: 'new',
+    help: {
+        name: 'agent new',
+        summary: 'spawn agent workers; all return a job handle immediately',
+        children: [
+            { name: 'prompt', desc: 'fresh agent with a prompt', useWhen: 'spawning a general-purpose agent' },
+            { name: 'fork', desc: 'fork current session into a sibling pane', useWhen: 'branching the current session\'s context into a new agent' },
+            { name: 'planner', desc: 'planning agent for a spec', useWhen: 'handing off spec → plan decomposition' },
+            { name: 'implementer', desc: 'implementation agent for a plan', useWhen: 'handing off plan → code implementation' },
+            { name: 'reviewer', desc: 'review agent for a plan or spec', useWhen: 'launching a review of a plan or spec artifact' },
+        ],
+    },
+    children: [newPrompt, newFork, newPlanner, newImplementer, newReviewer],
+});
+// ---------------------------------------------------------------------------
+// agent (root umbrella)
+// ---------------------------------------------------------------------------
+export function registerAgent() {
+    return defineBranch({
+        name: 'agent',
+        help: {
+            name: 'agent',
+            summary: 'agentic workflows: spec, plan, debug, and spawning agent workers',
+            model: 'spec captures requirements; plan decomposes them; debug root-causes failures reproduce-first; new spawns the worker that executes the next phase. Spawned workers register as jobs — monitor and collect at `crtr job`.',
+            children: [
+                { name: 'spec', desc: 'create, read, list specifications', useWhen: 'capturing requirements before planning' },
+                { name: 'plan', desc: 'create, read, list plans', useWhen: 'shaping or inspecting work' },
+                { name: 'debug', desc: 'reproduce-first root-cause workflow', useWhen: 'a bug, test failure, or unexpected behavior needs root-causing' },
+                { name: 'new', desc: 'spawn agent workers (prompt, fork, planner, implementer, reviewer)', useWhen: 'launching a new agent worker' },
+            ],
+        },
+        children: [registerSpec(), registerPlan(), registerDebug(), newBranch],
+    });
+}

package/dist/commands/debug.d.ts

@@ -1,3 +1,3 @@
-export declare const FLOW_DEBUG_GUIDE = "## Debug workflow \u2014 reproduce first\n\nAudience: the agent that ran `crtr flow debug`. A reproduction agent is\nalready spawned in a sibling pane. It writes ONE failing integration test and\nnever fixes anything. You do everything after: gate on the repro, root-cause,\nfix, verify against that same test.\n\n### Phase 0: Await the repro agent\n\nRun `crtr job read result <job_id> --wait` (10-min budget).\nOn status:\"timeout\": re-issue the wait, or run `crtr job read logs <job_id> --follow`\nuntil the job is terminal.\n\n### Phase 1: Gate on reproduction\n\n`reproduces:true`: read `test_path`, run `test_command` YOURSELF, confirm\nit fails for the stated reason. Do not trust the agent's claim \u2014 if it passes\nor fails differently, treat repro as NOT achieved. This test is the regression\ngate; it stays in the suite after the fix.\n`status:\"failed\"` / `reproduces:false` / your run disproves it: no repro\nharness. Continue, but record \"no reproduction \u2014 fix unverified; do not claim\nverified-fixed.\"\n\n### Phase 2: Reconnaissance\n\nRead the key files yourself \u2014 entry point, failure point, the data flow\nbetween. `git log` / `git blame` near the failure: recent changes are\nhigh-signal.\n\n### Phase 3: Assess difficulty, scale investigators\n\nSimple \u2192 solo (Explore subagents for tracing if the area is large).\nMedium \u2192 2\u20133 parallel `devcore:senior-advisor`: data-flow tracer, assumption\nauditor, change investigator.\nHard (intermittent, races, \"been stuck\", many modules) \u2192 3\u20135 parallel:\nend-to-end tracer, assumption breaker, git archaeologist, boundary inspector.\nGive investigators file paths, observed behavior, and concrete tasks \u2014 never\nyour hypotheses. Challenge theories against each other; the one that survives\ndisconfirmation wins.\n\n### Phase 4: Fix\n\nMinimal root-cause fix. No scope expansion, no drive-by refactor.\n\n### Phase 5: Verify\n\nRe-run `test_command`: it MUST now pass. Run the broader suite for\nregressions. If there was no repro test, state the fix is unverified by\nreproduction and recommend explicit manual verification.\n\n### Phase 6: Report\n\nRoot cause (exact line + why), evidence, the now-passing repro test path,\nconfidence (High/Medium/Low; if not High, name what is uncertain).\n\n### Constraints\n\nThe repro test is the regression guard \u2014 it stays; a fix-agent must never\nweaken it. Investigators run in forked contexts; they return summaries, not\nraw output. No code changes during Phases 2\u20133 except the repro test.";
+export declare const FLOW_DEBUG_GUIDE = "## Debug workflow \u2014 reproduce first\n\nAudience: the agent that ran `crtr agent debug`. A reproduction agent is\nalready spawned in a sibling pane. It writes ONE failing integration test and\nnever fixes anything. You do everything after: gate on the repro, root-cause,\nfix, verify against that same test.\n\n### Phase 0: Await the repro agent\n\nRun `crtr job read result <job_id> --wait` (10-min budget).\nOn status:\"timeout\": re-issue the wait, or run `crtr job read logs <job_id> --follow`\nuntil the job is terminal.\n\n### Phase 1: Gate on reproduction\n\n`reproduces:true`: read `test_path`, run `test_command` YOURSELF, confirm\nit fails for the stated reason. Do not trust the agent's claim \u2014 if it passes\nor fails differently, treat repro as NOT achieved. This test is the regression\ngate; it stays in the suite after the fix.\n`status:\"failed\"` / `reproduces:false` / your run disproves it: no repro\nharness. Continue, but record \"no reproduction \u2014 fix unverified; do not claim\nverified-fixed.\"\n\n### Phase 2: Reconnaissance\n\nRead the key files yourself \u2014 entry point, failure point, the data flow\nbetween. `git log` / `git blame` near the failure: recent changes are\nhigh-signal.\n\n### Phase 3: Assess difficulty, scale investigators\n\nSimple \u2192 solo (Explore subagents for tracing if the area is large).\nMedium \u2192 2\u20133 parallel `devcore:senior-advisor`: data-flow tracer, assumption\nauditor, change investigator.\nHard (intermittent, races, \"been stuck\", many modules) \u2192 3\u20135 parallel:\nend-to-end tracer, assumption breaker, git archaeologist, boundary inspector.\nGive investigators file paths, observed behavior, and concrete tasks \u2014 never\nyour hypotheses. Challenge theories against each other; the one that survives\ndisconfirmation wins.\n\n### Phase 4: Fix\n\nMinimal root-cause fix. No scope expansion, no drive-by refactor.\n\n### Phase 5: Verify\n\nRe-run `test_command`: it MUST now pass. Run the broader suite for\nregressions. If there was no repro test, state the fix is unverified by\nreproduction and recommend explicit manual verification.\n\n### Phase 6: Report\n\nRoot cause (exact line + why), evidence, the now-passing repro test path,\nconfidence (High/Medium/Low; if not High, name what is uncertain).\n\n### Constraints\n\nThe repro test is the regression guard \u2014 it stays; a fix-agent must never\nweaken it. Investigators run in forked contexts; they return summaries, not\nraw output. No code changes during Phases 2\u20133 except the repro test.";
 import type { LeafDef } from '../core/command.js';
 export declare function registerDebug(): LeafDef;

package/dist/commands/debug.js

@@ -1,14 +1,14 @@
-// `crtr flow debug` leaf — reproduce-first root-cause workflow.
+// `crtr agent debug` leaf — reproduce-first root-cause workflow.
 //
 // Running it spawns a reproduction-only agent in a sibling tmux pane (the same
-// spawn + job-handle shape as `crtr job start prompt`) and returns a job handle
+// spawn + job-handle shape as `crtr agent new prompt`) and returns a job handle
 // plus a follow_up. The orchestrator-side methodology lives in FLOW_DEBUG_GUIDE
-// (the leaf's help.guide), loaded via `crtr flow debug -h` after the repro
+// (the leaf's help.guide), loaded via `crtr agent debug -h` after the repro
 // agent returns. Methodology stays in the CLI guide field, like PLAN_NEW_GUIDE;
 // no builtin skill.
 export const FLOW_DEBUG_GUIDE = `## Debug workflow — reproduce first
 
-Audience: the agent that ran \`crtr flow debug\`. A reproduction agent is
+Audience: the agent that ran \`crtr agent debug\`. A reproduction agent is
 already spawned in a sibling pane. It writes ONE failing integration test and
 never fixes anything. You do everything after: gate on the repro, root-cause,
 fix, verify against that same test.
@@ -82,7 +82,7 @@ function assertTmux() {
     if (!isInTmux()) {
         throw new InputError({
             error: 'not_in_tmux',
-            message: 'crtr flow debug requires tmux (TMUX env var not set).',
+            message: 'crtr agent debug requires tmux (TMUX env var not set).',
             next: 'Run inside a tmux session.',
         });
     }
@@ -91,7 +91,7 @@ export function registerDebug() {
     return defineLeaf({
         name: 'debug',
         help: {
-            name: 'flow debug',
+            name: 'agent debug',
             summary: 'reproduce-first root-cause workflow: spawns a reproduction agent, then you root-cause and fix',
             guide: FLOW_DEBUG_GUIDE,
             params: [
@@ -172,7 +172,7 @@ export function registerDebug() {
             });
             return {
                 job_id: jobId,
-                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr flow debug -h\` and follow the workflow from Phase 1.`,
+                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr agent debug -h\` and follow the workflow from Phase 1.`,
             };
         },
     });