@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/commands/mode.js

@@ -1,231 +0,0 @@
-// `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/plan.d.ts

@@ -1,4 +0,0 @@
-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,322 +0,0 @@
-// `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
-re-discovering context. Work through these phases before saving.
-
-### Phase 1: Understand
-
-Build a full picture of the request and the code. Search for reusable
-functions, patterns, and existing implementations before proposing new ones.
-
-Launch up to 3 Explore subagents IN PARALLEL (single message, multiple tool
-calls). Use 1 agent for isolated, small-scope tasks; use more when scope is
-uncertain or multiple subsystems are involved. Give each a distinct focus so
-they don't duplicate work.
-
-### Phase 2: Design
-
-Design the implementation from Phase 1 findings. Default to launching at least
-1 Plan agent to validate your understanding and surface alternatives. Skip only
-for trivially small tasks (typo fixes, single-line renames). Use up to 3 agents
-for large refactors or architectural changes.
-
-In the Plan agent prompt: include file paths, code-path traces, requirements,
-and constraints from Phase 1. Request a detailed implementation plan.
-
-### Phase 3: Review findings
-
-Read the critical files identified by agents. Confirm the plan aligns with the
-user's request. Use AskUserQuestion ONLY to clarify requirements or choose
-between approaches — never to ask "is this okay?" or "should I proceed?".
-
-### Phase 4: Compose the plan body
-
-Quality bar — every item below is cheap to satisfy and saves the implementer
-from re-deciding:
-
-- Every decision pinned. No "if X then Y" branches, no "investigate whether…",
-  no deferred choices. If you don't know, find out or ask now.
-- No timelines, no fallbacks, no magic values, no "for now" shortcuts.
-- Where the plan creates a new interface, schema, or contract, write the actual
-  shape, not "design a Foo type."
-
-Required sections:
-
-  # Plan: <one-line title>
-
-  ## Context
-  <why this change is being made — the problem, what prompted it, intended outcome>
-
-  ## Recommended approach
-  <your chosen approach only. Concise enough to scan, detailed enough to execute.>
-
-  ## Files to modify / create
-  - \`path/to/file.ts\` — <what changes>
-
-  ## Existing utilities to reuse
-  - \`functionName\` from \`path/to/file.ts:LL\` — <why it fits>
-
-  ## Verification
-  <how to test end-to-end — run the code, run tests, etc.>
-
-For plans touching 4+ files across distinct concerns, structure parallel tasks:
-
-  ## Tasks
-  - **Task 1**: <name>
-    - Files: \`a.ts\`, \`b.ts\` (disjoint from other tasks)
-    - Depends on: (none) | Task N
-    - Integration: <shared types/APIs with exact shape>
-    - Changes: <bullets>
-
-Skip the Tasks structure for small plans; it's noise when there's no
-parallelism to unlock.
-
-### Phase 5: Save
-
-Run \`crtr mode plan new\`:
-
-  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\`).
-- Pipe the full plan markdown composed in Phase 4 on stdin.
-- \`--spec\` (optional): name of the spec this plan implements. Enables alignment
-  check by the reviewer.
-
-Output: \`{path, follow_up}\`. The \`follow_up\` field names the exact next call
-— run it.
-
-### Phase 6: Oversize check
-
-If \`follow_up\` contains an oversize advisory (plan exceeds 200 lines), split
-into a short index plan plus nested part plans, each under the threshold.
-Re-save. The implementer executes parts one at a time; long monolithic plans
-are under-decomposed.
-
-### Phase 7: Done
-
-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 mode reviewer\`.
-If the user is ready to build, ask once whether to hand off; if yes, run:
-\`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';
-import { paginate } from '../core/pagination.js';
-export function registerPlan() {
-    const planNew = defineLeaf({
-        name: 'new',
-        help: {
-            name: 'mode plan new',
-            summary: 'draft a plan from intent and optional spec alignment',
-            guide: PLAN_NEW_GUIDE,
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Kebab-case slug used as the artifact filename. No spaces; use hyphens.',
-                },
-                {
-                    kind: 'stdin',
-                    name: 'body',
-                    required: true,
-                    constraint: "Full planning prose. Treated as the planner's north star; not parsed further.",
-                },
-                {
-                    kind: 'flag',
-                    name: 'spec',
-                    type: 'string',
-                    required: false,
-                    constraint: 'Name of the spec this plan implements. Enables alignment check on write. Must reference an existing spec artifact.',
-                },
-            ],
-            output: [
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the written plan artifact.',
-                },
-                {
-                    name: 'follow_up',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Recommended next call (reviewer spawn via `crtr mode reviewer`).',
-                },
-            ],
-            outputKind: 'object',
-            effects: [
-                'Writes a plan artifact to the plans artifact directory.',
-                'If `--spec` is provided, records the spec alignment reference in the artifact frontmatter.',
-            ],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const body = input['body'];
-            const spec = input['spec'];
-            const meta = {};
-            if (spec !== undefined)
-                meta['spec'] = spec;
-            const { path, oversize, lineCount } = saveArtifact('plans', name, body, meta);
-            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) {
-                follow_up +=
-                    ` OVERSIZE ADVISORY: this plan is ${lineCount} lines (> ${OVERSIZE_WARN_LINES}). Split into a short index plan plus nested part plans before reviewing.`;
-            }
-            return { path, follow_up };
-        },
-    });
-    const planShow = defineLeaf({
-        name: 'show',
-        help: {
-            name: 'mode plan show',
-            summary: 'read a plan artifact by name',
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Exact artifact name (no path extension). Use `plan list` to enumerate.',
-                },
-            ],
-            output: [
-                {
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Artifact name as stored.',
-                },
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the artifact file.',
-                },
-                {
-                    name: 'body',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Full plan body text.',
-                },
-                {
-                    name: 'spec',
-                    type: 'string | null',
-                    required: true,
-                    constraint: 'Associated spec name, or null if none.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const record = readArtifact('plans', name);
-            return { name: record.name, path: record.path, body: record.body, spec: record.spec };
-        },
-    });
-    const planList = defineLeaf({
-        name: 'list',
-        help: {
-            name: 'mode plan list',
-            summary: 'paginated list of plan artifacts, sorted ascending by name',
-            params: [
-                {
-                    kind: 'flag',
-                    name: 'scope',
-                    type: 'enum',
-                    choices: ['user', 'project', 'all'],
-                    required: false,
-                    constraint: 'Filter by scope. Omit to list all.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'limit',
-                    type: 'int',
-                    required: false,
-                    default: 20,
-                    constraint: 'Default 20, max 100.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'cursor',
-                    type: 'string',
-                    required: false,
-                    constraint: "Opaque token from a previous response's next_cursor. Omit on first call.",
-                },
-            ],
-            output: [
-                {
-                    name: 'items',
-                    type: 'object[]',
-                    required: true,
-                    constraint: 'Each: {name, path, updated_at}. Sorted ascending by name.',
-                },
-                {
-                    name: 'next_cursor',
-                    type: 'string | null',
-                    required: true,
-                    constraint: 'Pass on the next call to continue. null means no more items.',
-                },
-                {
-                    name: 'total',
-                    type: 'integer | null',
-                    required: true,
-                    constraint: 'Total plans matching the query. Exact when cheap; null on large/filtered sets — do not retry to force it.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const limit = input['limit'] ?? 20;
-            const cursor = input['cursor'];
-            const all = listArtifacts('plans');
-            const result = paginate(all, { limit, cursor }, {
-                defaultLimit: 20,
-                maxLimit: 100,
-                keyOf: (item) => item.name,
-                total: 'count',
-            });
-            return {
-                items: result.items,
-                next_cursor: result.next_cursor,
-                total: result.total,
-            };
-        },
-    });
-    return defineBranch({
-        name: 'plan',
-        help: {
-            name: 'mode plan',
-            summary: 'create and read plan artifacts',
-            model: 'Lifecycle: draft -> active -> handed-off.',
-            children: [
-                { name: 'new', desc: 'draft a plan from intent', useWhen: 'starting fresh work or decomposing a spec' },
-                { name: 'show', desc: 'read a plan by name', useWhen: 'reasoning about an existing plan' },
-                { 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/spec.d.ts

@@ -1,3 +0,0 @@
-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;