@crouton-kit/crouter 0.3.8 → 0.3.11

package/dist/commands/mode.js

@@ -0,0 +1,231 @@
+// `crtr mode` umbrella — modes of operation: spec, plan, implement, review, debug.
+//
+// Collects the workflow-oriented commands:
+//   spec / plan / debug  — the artifact and root-cause workflows (from their
+//                          own files); planner, implementer, reviewer — the
+//                          handoff-spawn leaves previously under `agent new`.
+//
+// The spawn primitives (agent new / fork) and subagent management remain under
+// `crtr agent`. Results from spawned workers are collected at `crtr job`.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { existsSync } from 'node:fs';
+import { createJob, appendEvent, recordJobPane } from '../core/jobs.js';
+import { spawnAndDetach, spawnAgent } from '../core/spawn.js';
+import { planHandoffPrompt, implementHandoffPrompt, reviewerHandoffPrompt, } from '../prompts/agent.js';
+import { assertTmux, resolveMaxPanes, followUpResult, } from './agent.js';
+import { registerSpec } from './spec.js';
+import { registerPlan } from './plan.js';
+import { registerDebug } from './debug.js';
+const DEFAULT_KILL_SECS = 2;
+// ---------------------------------------------------------------------------
+// mode planner
+// ---------------------------------------------------------------------------
+const newPlanner = defineLeaf({
+    name: 'planner',
+    help: {
+        name: 'mode 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 the agent CLI (`-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: 'Your own next call — run it and report the worker\'s result; do not relay it to the user.' },
+        ],
+        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.' });
+        }
+        if (result.paneId !== undefined)
+            recordJobPane(jobId, result.paneId);
+        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) };
+    },
+});
+// ---------------------------------------------------------------------------
+// mode implementer
+// ---------------------------------------------------------------------------
+const newImplementer = defineLeaf({
+    name: 'implementer',
+    help: {
+        name: 'mode 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 the agent CLI (`-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: 'Your own next call — run it and report the worker\'s result; do not relay it to the user.' },
+        ],
+        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.' });
+        }
+        if (result.paneId !== undefined)
+            recordJobPane(jobId, result.paneId);
+        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) };
+    },
+});
+// ---------------------------------------------------------------------------
+// mode reviewer
+// ---------------------------------------------------------------------------
+const newReviewer = defineLeaf({
+    name: 'reviewer',
+    help: {
+        name: 'mode 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 the agent CLI (`-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: 'Your own next call — run it and report the worker\'s result; do not relay it to the user.' },
+        ],
+        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.' });
+        }
+        if (result.paneId !== undefined)
+            recordJobPane(jobId, result.paneId);
+        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) };
+    },
+});
+// ---------------------------------------------------------------------------
+// mode (root umbrella)
+// ---------------------------------------------------------------------------
+export function registerMode() {
+    return defineBranch({
+        name: 'mode',
+        rootEntry: {
+            concept: 'modes of operation: spec → plan → implement → review → debug. Workflow commands for the full agentic development lifecycle',
+            desc: 'spec, plan, implement, review, debug workflows',
+            useWhen: 'running any structured workflow phase — writing a spec, decomposing into a plan, handing off to an implementer or reviewer, or root-causing a bug. These are the "what to do next" commands; `crtr agent new` is the raw spawn primitive.',
+        },
+        help: {
+            name: 'mode',
+            summary: 'modes of operation: spec, plan, implement, review, debug',
+            model: 'Full agentic development lifecycle in one subtree. spec captures requirements; plan decomposes them into executable steps; planner/implementer/reviewer are the handoff-spawn leaves that delegate each phase to a fresh worker and return a job handle; debug root-causes failures with a reproduce-first workflow. 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: 'planner', desc: 'planning agent for an approved spec', useWhen: 'handing off spec → plan decomposition to a fresh agent' },
+                { name: 'implementer', desc: 'implementation agent for an approved plan', useWhen: 'handing off plan → code implementation to a fresh agent' },
+                { name: 'reviewer', desc: 'review agent for a plan or spec artifact', useWhen: 'launching a review of a plan or spec artifact' },
+            ],
+        },
+        children: [registerSpec(), registerPlan(), registerDebug(), newPlanner, newImplementer, newReviewer],
+    });
+}

package/dist/commands/pkg.js

@@ -1008,6 +1008,11 @@ const marketBranch = defineBranch({
 export function registerPkg() {
     return defineBranch({
         name: 'pkg',
+        rootEntry: {
+            concept: 'plugins and marketplaces that supply skills',
+            desc: 'manage plugins and marketplaces',
+            useWhen: 'installing or browsing skill collections',
+        },
         help: {
             name: 'pkg',
             summary: 'manage plugins and plugin marketplaces',

package/dist/commands/plan.d.ts

@@ -1,4 +1,4 @@
-export declare const PLAN_NEW_GUIDE = "## Planning workflow\n\nBuild and save an implementation plan: a map another agent can execute without\nre-discovering context. Work through these phases before saving.\n\n### Phase 1: Understand\n\nBuild a full picture of the request and the code. Search for reusable\nfunctions, patterns, and existing implementations before proposing new ones.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for isolated, small-scope tasks; use more when scope is\nuncertain or multiple subsystems are involved. Give each a distinct focus so\nthey don't duplicate work.\n\n### Phase 2: Design\n\nDesign the implementation from Phase 1 findings. Default to launching at least\n1 Plan agent to validate your understanding and surface alternatives. Skip only\nfor trivially small tasks (typo fixes, single-line renames). Use up to 3 agents\nfor large refactors or architectural changes.\n\nIn the Plan agent prompt: include file paths, code-path traces, requirements,\nand constraints from Phase 1. Request a detailed implementation plan.\n\n### Phase 3: Review findings\n\nRead the critical files identified by agents. Confirm the plan aligns with the\nuser's request. Use AskUserQuestion ONLY to clarify requirements or choose\nbetween approaches \u2014 never to ask \"is this okay?\" or \"should I proceed?\".\n\n### Phase 4: Compose the plan body\n\nQuality bar \u2014 every item below is cheap to satisfy and saves the implementer\nfrom re-deciding:\n\n- Every decision pinned. No \"if X then Y\" branches, no \"investigate whether\u2026\",\n  no deferred choices. If you don't know, find out or ask now.\n- No timelines, no fallbacks, no magic values, no \"for now\" shortcuts.\n- Where the plan creates a new interface, schema, or contract, write the actual\n  shape, not \"design a Foo type.\"\n\nRequired sections:\n\n  # Plan: <one-line title>\n\n  ## Context\n  <why this change is being made \u2014 the problem, what prompted it, intended outcome>\n\n  ## Recommended approach\n  <your chosen approach only. Concise enough to scan, detailed enough to execute.>\n\n  ## Files to modify / create\n  - `path/to/file.ts` \u2014 <what changes>\n\n  ## Existing utilities to reuse\n  - `functionName` from `path/to/file.ts:LL` \u2014 <why it fits>\n\n  ## Verification\n  <how to test end-to-end \u2014 run the code, run tests, etc.>\n\nFor plans touching 4+ files across distinct concerns, structure parallel tasks:\n\n  ## Tasks\n  - **Task 1**: <name>\n    - Files: `a.ts`, `b.ts` (disjoint from other tasks)\n    - Depends on: (none) | Task N\n    - Integration: <shared types/APIs with exact shape>\n    - Changes: <bullets>\n\nSkip the Tasks structure for small plans; it's noise when there's no\nparallelism to unlock.\n\n### Phase 5: Save\n\nRun `crtr agent plan new`:\n\n  echo '<plan markdown>' | crtr agent plan new <kebab-case-name> [--spec <spec-name>]\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/jwt-refresh`).\n- Pipe the full plan markdown composed in Phase 4 on stdin.\n- `--spec` (optional): name of the spec this plan implements. Enables alignment\n  check by the reviewer.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Oversize check\n\nIf `follow_up` contains an oversize advisory (plan exceeds 200 lines), split\ninto a short index plan plus nested part plans, each under the threshold.\nRe-save. The implementer executes parts one at a time; long monolithic plans\nare under-decomposed.\n\n### Phase 7: Done\n\nAfter the reviewer approves the plan, your turn ends. Do not summarize in chat.\nFor a human gate, optionally put the plan in front of a person with `crtr\nhuman review` (anchored comments) and gate the handoff with `crtr human\napprove`. This complements \u2014 it does not replace \u2014 `crtr agent new reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr agent new implementer` with the plan path.";
+export declare const PLAN_NEW_GUIDE = "## Planning workflow\n\nBuild and save an implementation plan: a map another agent can execute without\nre-discovering context. Work through these phases before saving.\n\n### Phase 1: Understand\n\nBuild a full picture of the request and the code. Search for reusable\nfunctions, patterns, and existing implementations before proposing new ones.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for isolated, small-scope tasks; use more when scope is\nuncertain or multiple subsystems are involved. Give each a distinct focus so\nthey don't duplicate work.\n\n### Phase 2: Design\n\nDesign the implementation from Phase 1 findings. Default to launching at least\n1 Plan agent to validate your understanding and surface alternatives. Skip only\nfor trivially small tasks (typo fixes, single-line renames). Use up to 3 agents\nfor large refactors or architectural changes.\n\nIn the Plan agent prompt: include file paths, code-path traces, requirements,\nand constraints from Phase 1. Request a detailed implementation plan.\n\n### Phase 3: Review findings\n\nRead the critical files identified by agents. Confirm the plan aligns with the\nuser's request. Use AskUserQuestion ONLY to clarify requirements or choose\nbetween approaches \u2014 never to ask \"is this okay?\" or \"should I proceed?\".\n\n### Phase 4: Compose the plan body\n\nQuality bar \u2014 every item below is cheap to satisfy and saves the implementer\nfrom re-deciding:\n\n- Every decision pinned. No \"if X then Y\" branches, no \"investigate whether\u2026\",\n  no deferred choices. If you don't know, find out or ask now.\n- No timelines, no fallbacks, no magic values, no \"for now\" shortcuts.\n- Where the plan creates a new interface, schema, or contract, write the actual\n  shape, not \"design a Foo type.\"\n\nRequired sections:\n\n  # Plan: <one-line title>\n\n  ## Context\n  <why this change is being made \u2014 the problem, what prompted it, intended outcome>\n\n  ## Recommended approach\n  <your chosen approach only. Concise enough to scan, detailed enough to execute.>\n\n  ## Files to modify / create\n  - `path/to/file.ts` \u2014 <what changes>\n\n  ## Existing utilities to reuse\n  - `functionName` from `path/to/file.ts:LL` \u2014 <why it fits>\n\n  ## Verification\n  <how to test end-to-end \u2014 run the code, run tests, etc.>\n\nFor plans touching 4+ files across distinct concerns, structure parallel tasks:\n\n  ## Tasks\n  - **Task 1**: <name>\n    - Files: `a.ts`, `b.ts` (disjoint from other tasks)\n    - Depends on: (none) | Task N\n    - Integration: <shared types/APIs with exact shape>\n    - Changes: <bullets>\n\nSkip the Tasks structure for small plans; it's noise when there's no\nparallelism to unlock.\n\n### Phase 5: Save\n\nRun `crtr mode plan new`:\n\n  echo '<plan markdown>' | crtr mode plan new <kebab-case-name> [--spec <spec-name>]\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/jwt-refresh`).\n- Pipe the full plan markdown composed in Phase 4 on stdin.\n- `--spec` (optional): name of the spec this plan implements. Enables alignment\n  check by the reviewer.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Oversize check\n\nIf `follow_up` contains an oversize advisory (plan exceeds 200 lines), split\ninto a short index plan plus nested part plans, each under the threshold.\nRe-save. The implementer executes parts one at a time; long monolithic plans\nare under-decomposed.\n\n### Phase 7: Done\n\nAfter the reviewer approves the plan, your turn ends. Do not summarize in chat.\nFor a human gate, optionally put the plan in front of a person with `crtr\nhuman review` (anchored comments) and gate the handoff with `crtr human\napprove`. This complements \u2014 it does not replace \u2014 `crtr mode reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr mode implementer` with the plan path.";
 export declare const PLAN_SHOW_GUIDE = "";
 import type { BranchDef } from '../core/command.js';
 export declare function registerPlan(): BranchDef;

package/dist/commands/plan.js

@@ -1,4 +1,4 @@
-// `crtr agent plan` subtree — plan new / show / list handlers.
+// `crtr mode plan` subtree — plan new / show / list handlers.
 export const PLAN_NEW_GUIDE = `## Planning workflow
 
 Build and save an implementation plan: a map another agent can execute without
@@ -74,9 +74,9 @@ parallelism to unlock.
 
 ### Phase 5: Save
 
-Run \`crtr agent plan new\`:
+Run \`crtr mode plan new\`:
 
-  echo '<plan markdown>' | crtr agent plan new <kebab-case-name> [--spec <spec-name>]
+  echo '<plan markdown>' | crtr mode plan new <kebab-case-name> [--spec <spec-name>]
 
 - NAME: short kebab-case slug. Nested names become subdirectories
   (e.g. \`auth/jwt-refresh\`).
@@ -99,9 +99,9 @@ are under-decomposed.
 After the reviewer approves the plan, your turn ends. Do not summarize in chat.
 For a human gate, optionally put the plan in front of a person with \`crtr
 human review\` (anchored comments) and gate the handoff with \`crtr human
-approve\`. This complements — it does not replace — \`crtr agent new reviewer\`.
+approve\`. This complements — it does not replace — \`crtr mode reviewer\`.
 If the user is ready to build, ask once whether to hand off; if yes, run:
-\`crtr agent new implementer\` with the plan path.`;
+\`crtr mode implementer\` with the plan path.`;
 export const PLAN_SHOW_GUIDE = '';
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { saveArtifact, readArtifact, listArtifacts, OVERSIZE_WARN_LINES } from '../core/artifact.js';
@@ -110,7 +110,7 @@ export function registerPlan() {
     const planNew = defineLeaf({
         name: 'new',
         help: {
-            name: 'agent plan new',
+            name: 'mode plan new',
             summary: 'draft a plan from intent and optional spec alignment',
             guide: PLAN_NEW_GUIDE,
             params: [
@@ -146,7 +146,7 @@ export function registerPlan() {
                     name: 'follow_up',
                     type: 'string',
                     required: true,
-                    constraint: 'Recommended next call (reviewer spawn via `crtr agent new reviewer`).',
+                    constraint: 'Recommended next call (reviewer spawn via `crtr mode reviewer`).',
                 },
             ],
             outputKind: 'object',
@@ -163,7 +163,7 @@ export function registerPlan() {
             if (spec !== undefined)
                 meta['spec'] = spec;
             const { path, oversize, lineCount } = saveArtifact('plans', name, body, meta);
-            let follow_up = `Review it: crtr agent new reviewer ${path} --kind plan (returns {job_id}), then crtr job read result <job_id> --wait.`;
+            let follow_up = `Review it: crtr mode reviewer ${path} --kind plan (returns {job_id}), then crtr job read result <job_id> --wait.`;
             follow_up +=
                 ` Optional human gate (complements, does not replace the agent reviewer): crtr human review --file ${path} for anchored comments, then gate handoff with crtr human approve --title "Approve this plan?".`;
             if (oversize) {
@@ -176,7 +176,7 @@ export function registerPlan() {
     const planShow = defineLeaf({
         name: 'show',
         help: {
-            name: 'agent plan show',
+            name: 'mode plan show',
             summary: 'read a plan artifact by name',
             params: [
                 {
@@ -225,7 +225,7 @@ export function registerPlan() {
     const planList = defineLeaf({
         name: 'list',
         help: {
-            name: 'agent plan list',
+            name: 'mode plan list',
             summary: 'paginated list of plan artifacts, sorted ascending by name',
             params: [
                 {
@@ -295,7 +295,7 @@ export function registerPlan() {
     return defineBranch({
         name: 'plan',
         help: {
-            name: 'agent plan',
+            name: 'mode plan',
             summary: 'create and read plan artifacts',
             model: 'Lifecycle: draft -> active -> handed-off.',
             children: [
@@ -304,6 +304,19 @@ export function registerPlan() {
                 { name: 'list', desc: 'enumerate plans', useWhen: 'discovering what plans exist' },
             ],
         },
+        slash: {
+            name: 'plan',
+            description: 'Plan mode — decompose intent (and an optional spec) into an executable plan.',
+            argumentHint: '[what to plan]',
+            body: `You are entering **plan mode**: decompose work into an executable plan.
+
+1. Run \`crtr mode plan new -h\` to load the planning workflow and output schema.
+2. Follow it to draft the plan, then save by piping the markdown to \`crtr mode plan new <name>\` on stdin (pass \`--spec <path>\` if an approved spec exists).
+
+The request: $ARGUMENTS
+
+If no request was given, ask the user what to plan before starting.`,
+        },
         children: [planNew, planShow, planList],
     });
 }

package/dist/commands/skill.js

@@ -4,6 +4,7 @@
 import { join } from 'node:path';
 import { writeFileSync } from 'node:fs';
 import { defineBranch, defineLeaf } from '../core/command.js';
+import { stateBlock } from '../core/help.js';
 import { usage, general, notFound } from '../core/errors.js';
 import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, skillConfigKey, } from '../types.js';
 import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, listSkillSiblings, listSkillChildren, } from '../core/resolver.js';
@@ -583,6 +584,11 @@ const stateBranch = defineBranch({
     },
     children: [stateEnable, stateDisable],
 });
+/** The skill subtree's live state: the loaded-skills catalog as a self-named
+ *  `<skills count="N">` element. The tag carries the label and the count is an
+ *  attribute, so the body is the grouped tree alone — no "Loaded skills (N)"
+ *  header to duplicate. Returns null (block omitted) when discovery fails or
+ *  nothing is loaded. */
 function buildSkillCatalog() {
     let skills;
     try {
@@ -614,10 +620,14 @@ function buildSkillCatalog() {
             continue;
         (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
     }
-    const lines = [`Loaded skills (${skills.length})`];
-    renderCatalogSection('Project', projectSources, lines);
-    renderCatalogSection('User', userSources, lines);
-    return lines.join('\n');
+    const body = [];
+    renderCatalogSection('Project', projectSources, body);
+    renderCatalogSection('User', userSources, body);
+    // renderCatalogSection leads each section with a blank separator; drop the
+    // leading one so the element body starts on its first real line.
+    while (body.length > 0 && body[0] === '')
+        body.shift();
+    return stateBlock('skills', { count: skills.length }, body.join('\n'));
 }
 function renderCatalogSection(label, sources, out) {
     if (sources.length === 0)
@@ -685,6 +695,12 @@ function renderCatalogSection(label, sources, out) {
 export function registerSkill() {
     return defineBranch({
         name: 'skill',
+        rootEntry: {
+            concept: 'a SKILL.md you read to adopt its workflow',
+            desc: 'find, read, author, and manage skills',
+            useWhen: 'a task matches a loaded skill — read it before improvising. `crtr skill read <name>` loads one by name from the catalog below; `crtr skill find` only when the name is not already listed. Names are crtr identifiers, not file paths — never cat or find SKILL.md off disk.',
+            dynamicState: buildSkillCatalog,
+        },
         help: {
             name: 'skill',
             summary: 'discover, read, author, and manage skill state',

package/dist/commands/spec.d.ts

@@ -1,3 +1,3 @@
-export declare const SPEC_NEW_GUIDE = "## Spec workflow\n\nBuild and save a design + requirements spec: a document describing what to\nbuild, the shape of the solution, and the behaviors it must satisfy. A spec is\nupstream of a plan \u2014 it captures decisions, not implementation steps.\n\nAnti-pattern: do not fish for clarifications upfront. Draft a concrete spec\nfirst based on your investigation, then iterate. A specific draft the user can\nreact to converges faster than a list of questions in a vacuum.\n\n### Phase 1: Shape\n\nBuild a comprehensive picture of the problem and the relevant code. Surface\nexisting patterns, constraints, and prior decisions.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for narrow, well-scoped problems; use more when the spec\ntouches several subsystems or you need to compare existing implementations.\nQuality over quantity \u2014 3 agents maximum.\n\nAfter exploration, draft a high-level design: the shape of the solution, new or\nchanged pieces, the boundaries.\n\n### Phase 2: Requirements\n\nTranslate the shape into concrete behavioral requirements. Each requirement\nmust be:\n\n- Testable \u2014 has a clear pass/fail condition.\n- Behavior-focused \u2014 describes what the system does, not how.\n- Scoped \u2014 covers one observable behavior.\n\nGroup requirements by capability. Plain English is fine. For conditional or\nstateful behaviors, EARS templates sharpen phrasing:\n`When <trigger>, the system shall <behavior>` or\n`If <condition>, then the system shall <response>`.\n\nFor larger / multi-component designs, walk the design end-to-end: at each step\nfrom trigger to final state, verify preconditions, state, failure handling, and\nhandoffs between components are specified. Skip this for small self-contained\nspecs.\n\n### Phase 3: Deepen\n\nRead the critical files identified during Phase 1. Reconcile requirements\nagainst the shape \u2014 if a requirement reveals a gap in the design, refine the\ndesign before saving.\n\nUse AskUserQuestion ONLY to clarify requirements or choose between approaches.\nNever use it to ask \"is this spec okay?\" or \"should I save?\".\n\n### Phase 4: Compose the spec body\n\nRequired sections:\n\n  # Spec: <one-line title>\n\n  ## Context\n  <the problem this spec addresses, what motivates it, and the intended outcome.\n  Include relevant constraints \u2014 user goals, stakeholders, deadlines.>\n\n  ## Design\n  <the shape of the solution. Components, data flow, key decisions and why they\n  were chosen. Reference existing code with `file_path:line_number`.>\n\n  ## Requirements\n  <grouped behavioral requirements. Each one testable. Plain English is fine.>\n\n  ### <Capability A>\n  - <one observable behavior>\n\n  ### <Capability B>\n  - ...\n\n  ## Out of scope\n  <things explicitly NOT covered, so the next reader knows where the edges are.>\n\n  ## Open questions\n  <anything you could not resolve. Empty if all decisions are pinned.>\n\n### Phase 5: Save\n\nRun `crtr agent spec new`:\n\n  echo '<spec markdown>' | crtr agent spec new <kebab-case-name>\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/refresh-tokens`).\n- Pipe the full spec markdown composed in Phase 4 on stdin.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Done\n\nAfter the reviewer approves the spec, your turn ends. Do not summarize in chat.\nFor a human gate, optionally run `crtr human review` on the spec for anchored\ncomments and `crtr human approve` to gate the handoff \u2014 this complements, not\nreplaces, `crtr agent new reviewer`.\nIf the user is ready to plan, ask once whether to hand off; if yes, follow the\n`follow_up` instructions from the save output.";
+export declare const SPEC_NEW_GUIDE = "## Spec workflow\n\nBuild and save a design + requirements spec: a document describing what to\nbuild, the shape of the solution, and the behaviors it must satisfy. A spec is\nupstream of a plan \u2014 it captures decisions, not implementation steps.\n\nAnti-pattern: do not fish for clarifications upfront. Draft a concrete spec\nfirst based on your investigation, then iterate. A specific draft the user can\nreact to converges faster than a list of questions in a vacuum.\n\n### Phase 1: Shape\n\nBuild a comprehensive picture of the problem and the relevant code. Surface\nexisting patterns, constraints, and prior decisions.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for narrow, well-scoped problems; use more when the spec\ntouches several subsystems or you need to compare existing implementations.\nQuality over quantity \u2014 3 agents maximum.\n\nAfter exploration, draft a high-level design: the shape of the solution, new or\nchanged pieces, the boundaries.\n\n### Phase 2: Requirements\n\nTranslate the shape into concrete behavioral requirements. Each requirement\nmust be:\n\n- Testable \u2014 has a clear pass/fail condition.\n- Behavior-focused \u2014 describes what the system does, not how.\n- Scoped \u2014 covers one observable behavior.\n\nGroup requirements by capability. Plain English is fine. For conditional or\nstateful behaviors, EARS templates sharpen phrasing:\n`When <trigger>, the system shall <behavior>` or\n`If <condition>, then the system shall <response>`.\n\nFor larger / multi-component designs, walk the design end-to-end: at each step\nfrom trigger to final state, verify preconditions, state, failure handling, and\nhandoffs between components are specified. Skip this for small self-contained\nspecs.\n\n### Phase 3: Deepen\n\nRead the critical files identified during Phase 1. Reconcile requirements\nagainst the shape \u2014 if a requirement reveals a gap in the design, refine the\ndesign before saving.\n\nUse AskUserQuestion ONLY to clarify requirements or choose between approaches.\nNever use it to ask \"is this spec okay?\" or \"should I save?\".\n\n### Phase 4: Compose the spec body\n\nRequired sections:\n\n  # Spec: <one-line title>\n\n  ## Context\n  <the problem this spec addresses, what motivates it, and the intended outcome.\n  Include relevant constraints \u2014 user goals, stakeholders, deadlines.>\n\n  ## Design\n  <the shape of the solution. Components, data flow, key decisions and why they\n  were chosen. Reference existing code with `file_path:line_number`.>\n\n  ## Requirements\n  <grouped behavioral requirements. Each one testable. Plain English is fine.>\n\n  ### <Capability A>\n  - <one observable behavior>\n\n  ### <Capability B>\n  - ...\n\n  ## Out of scope\n  <things explicitly NOT covered, so the next reader knows where the edges are.>\n\n  ## Open questions\n  <anything you could not resolve. Empty if all decisions are pinned.>\n\n### Phase 5: Save\n\nRun `crtr mode spec new`:\n\n  echo '<spec markdown>' | crtr mode spec new <kebab-case-name>\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/refresh-tokens`).\n- Pipe the full spec markdown composed in Phase 4 on stdin.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Done\n\nAfter the reviewer approves the spec, your turn ends. Do not summarize in chat.\nFor a human gate, optionally run `crtr human review` on the spec for anchored\ncomments and `crtr human approve` to gate the handoff \u2014 this complements, not\nreplaces, `crtr mode reviewer`.\nIf the user is ready to plan, ask once whether to hand off; if yes, follow the\n`follow_up` instructions from the save output.";
 import type { BranchDef } from '../core/command.js';
 export declare function registerSpec(): BranchDef;

package/dist/commands/spec.js

@@ -1,4 +1,4 @@
-// `crtr agent spec` subtree — spec new / show / list handlers.
+// `crtr mode spec` subtree — spec new / show / list handlers.
 export const SPEC_NEW_GUIDE = `## Spec workflow
 
 Build and save a design + requirements spec: a document describing what to
@@ -81,9 +81,9 @@ Required sections:
 
 ### Phase 5: Save
 
-Run \`crtr agent spec new\`:
+Run \`crtr mode spec new\`:
 
-  echo '<spec markdown>' | crtr agent spec new <kebab-case-name>
+  echo '<spec markdown>' | crtr mode spec new <kebab-case-name>
 
 - NAME: short kebab-case slug. Nested names become subdirectories
   (e.g. \`auth/refresh-tokens\`).
@@ -97,7 +97,7 @@ Output: \`{path, follow_up}\`. The \`follow_up\` field names the exact next call
 After the reviewer approves the spec, your turn ends. Do not summarize in chat.
 For a human gate, optionally run \`crtr human review\` on the spec for anchored
 comments and \`crtr human approve\` to gate the handoff — this complements, not
-replaces, \`crtr agent new reviewer\`.
+replaces, \`crtr mode reviewer\`.
 If the user is ready to plan, ask once whether to hand off; if yes, follow the
 \`follow_up\` instructions from the save output.`;
 import { defineBranch, defineLeaf } from '../core/command.js';
@@ -107,7 +107,7 @@ export function registerSpec() {
     const specNew = defineLeaf({
         name: 'new',
         help: {
-            name: 'agent spec new',
+            name: 'mode spec new',
             summary: 'draft a specification artifact from intent',
             guide: SPEC_NEW_GUIDE,
             params: [
@@ -136,7 +136,7 @@ export function registerSpec() {
                     name: 'follow_up',
                     type: 'string',
                     required: true,
-                    constraint: 'Recommended next call (planner spawn via `crtr agent new planner`).',
+                    constraint: 'Recommended next call (planner spawn via `crtr mode planner`).',
                 },
             ],
             outputKind: 'object',
@@ -146,9 +146,9 @@ export function registerSpec() {
             const name = input['name'];
             const body = input['body'];
             const { path, oversize, lineCount } = saveArtifact('specs', name, body);
-            let follow_up = `Plan it: crtr agent new planner ${path} (returns {job_id}), then crtr job read result <job_id> --wait.`;
+            let follow_up = `Plan it: crtr mode planner ${path} (returns {job_id}), then crtr job read result <job_id> --wait.`;
             follow_up +=
-                ` Optional human gate before planning (complements, does not replace \`crtr agent new reviewer\`): crtr human review --file ${path} for anchored comments, then gate with crtr human approve --title "Approve this spec?".`;
+                ` Optional human gate before planning (complements, does not replace \`crtr mode reviewer\`): crtr human review --file ${path} for anchored comments, then gate with crtr human approve --title "Approve this spec?".`;
             if (oversize) {
                 follow_up +=
                     ` OVERSIZE ADVISORY: this spec is ${lineCount} lines (> ${OVERSIZE_WARN_LINES}). Split into focused sub-specs before planning.`;
@@ -159,7 +159,7 @@ export function registerSpec() {
     const specShow = defineLeaf({
         name: 'show',
         help: {
-            name: 'agent spec show',
+            name: 'mode spec show',
             summary: 'read a spec artifact by name',
             params: [
                 {
@@ -202,7 +202,7 @@ export function registerSpec() {
     const specList = defineLeaf({
         name: 'list',
         help: {
-            name: 'agent spec list',
+            name: 'mode spec list',
             summary: 'paginated list of spec artifacts, sorted ascending by name',
             params: [
                 {
@@ -272,7 +272,7 @@ export function registerSpec() {
     return defineBranch({
         name: 'spec',
         help: {
-            name: 'agent spec',
+            name: 'mode spec',
             summary: 'create and read specification artifacts',
             model: 'Lifecycle: draft -> approved. Approved specs drive plan creation.',
             children: [
@@ -281,6 +281,19 @@ export function registerSpec() {
                 { name: 'list', desc: 'enumerate specs', useWhen: 'discovering what specs exist' },
             ],
         },
+        slash: {
+            name: 'spec',
+            description: 'Spec mode — turn intent into a specification artifact (spec-driven workflow).',
+            argumentHint: '[what to spec]',
+            body: `You are entering **spec mode**: turn intent into a written specification artifact.
+
+1. Run \`crtr mode spec new -h\` to load the spec-authoring workflow and output schema.
+2. Follow that workflow to draft the spec, then save it by piping the markdown to \`crtr mode spec new <name>\` on stdin.
+
+The request: $ARGUMENTS
+
+If no request was given, ask the user what to spec before starting.`,
+        },
         children: [specNew, specShow, specList],
     });
 }

package/dist/commands/sys.js

@@ -697,6 +697,11 @@ const sysVersionLeaf = defineLeaf({
 export function registerSys() {
     return defineBranch({
         name: 'sys',
+        rootEntry: {
+            concept: 'crtr configuration, diagnostics, and self-management',
+            desc: 'config, doctor, update, version',
+            useWhen: 'managing the crtr installation',
+        },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, diagnostics, and self-management',

package/dist/core/__tests__/job.test.js

@@ -1,4 +1,4 @@
-// Tests for the job subtree (monitoring) and agent new * (spawning) argv
+// Tests for the job subtree (monitoring) and agent/mode spawn leaves argv
 // migration. Exercises parseArgv against each leaf's param schema directly —
 // no subprocess, no tmux, no filesystem side-effects from the handler.
 //
@@ -67,9 +67,9 @@ const failParams = [
     { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
 ];
 // ---------------------------------------------------------------------------
-// agent new prompt (formerly job start prompt)
+// agent new (formerly job start prompt)
 // ---------------------------------------------------------------------------
-describe('agent new prompt', () => {
+describe('agent new', () => {
     // stdin is handled by readStdinRaw() which requires actual stdin — we only
     // test the non-stdin flag parsing here.
     test('--cwd flag parsed as string', async () => {
@@ -91,9 +91,9 @@ describe('agent new prompt', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// agent new fork (formerly job start fork)
+// agent fork (formerly job start fork)
 // ---------------------------------------------------------------------------
-describe('agent new fork', () => {
+describe('agent fork', () => {
     test('no args parses cleanly', async () => {
         const result = await parseArgv(startForkParams, []);
         assert.equal(result['cwd'], undefined);
@@ -107,9 +107,9 @@ describe('agent new fork', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// agent new planner (formerly job start planner)
+// mode planner (formerly job start planner)
 // ---------------------------------------------------------------------------
-describe('agent new planner', () => {
+describe('mode planner', () => {
     test('positional spec_path required', async () => {
         await assert.rejects(() => parseArgv(startPlannerParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
     });
@@ -125,9 +125,9 @@ describe('agent new planner', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// agent new implementer (formerly job start implementer)
+// mode implementer (formerly job start implementer)
 // ---------------------------------------------------------------------------
-describe('agent new implementer', () => {
+describe('mode implementer', () => {
     test('positional plan_path required', async () => {
         await assert.rejects(() => parseArgv(startImplementerParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
     });
@@ -137,9 +137,9 @@ describe('agent new implementer', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// agent new reviewer (formerly job start reviewer)
+// mode reviewer (formerly job start reviewer)
 // ---------------------------------------------------------------------------
-describe('agent new reviewer', () => {
+describe('mode reviewer', () => {
     test('positional + --kind required', async () => {
         await assert.rejects(() => parseArgv(startReviewerParams, ['/tmp/artifact.md']), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
     });