@crouton-kit/crouter 0.3.3 → 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 flow plan new`:\n\n  echo '<plan markdown>' | crtr flow 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 job start reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr job start 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 flow 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 flow plan new\`:
+Run \`crtr mode plan new\`:
 
-  echo '<plan markdown>' | crtr flow 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 job start 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 job start 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: '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 job start).',
+                    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 job start reviewer --artifact-path ${path} --artifact-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: '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: '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: '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],
     });
 }