@crouton-kit/crouter 0.3.3 → 0.3.11

package/dist/commands/skill.js

@@ -1,8 +1,10 @@
 // `crtr skill` subtree handlers — P3 implementation.
-// Sub-branches: find {list, search, grep}, read {show, where}, author {guide, scaffold}, state {enable, disable}.
+// Sub-branches: find {list, search, grep}, author {guide, scaffold}, state {enable, disable}.
+// Leaf children of skill: read.
 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';
@@ -17,7 +19,7 @@ import { skillCreatePrompt, skillTemplatePrompt } from '../prompts/skill.js';
 // ---------------------------------------------------------------------------
 function formatNeighborQualifier(s) {
     return s.plugin === SCOPE_SKILL_PLUGIN
-        ? `${s.scope}:${s.name}`
+        ? `${s.scope}/${s.name}`
         : `${s.plugin}/${s.name}`;
 }
 function formatNeighborKeywords(s) {
@@ -33,7 +35,7 @@ function buildNeighborsSection(skill) {
         return null;
     const lines = [
         '## Neighbors',
-        '*Auto-discovered from filesystem. Run `crtr skill read show <name>` for full description + body.*',
+        '*Auto-discovered from filesystem. Run `crtr skill read <name>` for full description + body.*',
         '',
     ];
     if (siblings.length > 0) {
@@ -127,7 +129,7 @@ const findList = defineLeaf({
                 return po;
             return a.name.localeCompare(b.name);
         });
-        const keyOf = (sk) => `${sk.scope}:${sk.plugin}/${sk.name}`;
+        const keyOf = (sk) => `${sk.scope}/${sk.plugin}/${sk.name}`;
         const params = {};
         if (limit !== undefined)
             params.limit = limit;
@@ -155,7 +157,7 @@ const findList = defineLeaf({
             }),
             next_cursor: result.next_cursor,
             total: result.total,
-            follow_up: 'Use `crtr skill read show <name>` for the full SKILL.md body. Run `crtr skill find list -h` for filters and verbosity.',
+            follow_up: 'Use `crtr skill read <name>` for the full SKILL.md body. Run `crtr skill find list -h` for filters and verbosity.',
         };
     },
 });
@@ -240,7 +242,7 @@ const findSearch = defineLeaf({
                 score: h.score,
                 description: h.skill.frontmatter.description !== undefined ? h.skill.frontmatter.description : null,
             })),
-            follow_up: 'Use `crtr skill read show <name>` for the full SKILL.md body. Run `crtr skill find search -h` for filters.',
+            follow_up: 'Use `crtr skill read <name>` for the full SKILL.md body. Run `crtr skill find search -h` for filters.',
         };
     },
 });
@@ -322,25 +324,27 @@ const findBranch = defineBranch({
     children: [findList, findSearch, findGrep],
 });
 // ---------------------------------------------------------------------------
-// read sub-branch
+// read leaf
 // ---------------------------------------------------------------------------
-const readShow = defineLeaf({
-    name: 'show',
+const readLeaf = defineLeaf({
+    name: 'read',
     help: {
-        name: 'skill read show',
-        summary: 'print SKILL.md body for a named skill',
+        name: 'skill read',
+        summary: 'load SKILL.md body and resolution metadata for a named skill',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Forms: <name>, <plugin>:<name>, <scope>:<name>, <scope>:<plugin>/<name>.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Forms: <name>, <plugin>/<name>, <scope>/<name>, <scope>/<plugin>/<name>.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution when name is ambiguous.' },
             { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Narrows resolution to a specific plugin.' },
-            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes YAML frontmatter in the output.' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes YAML frontmatter in the output content.' },
+            { kind: 'flag', name: 'no-body', type: 'bool', required: false, constraint: 'When present, omits the body — returns resolution metadata only. Use to confirm a skill exists or locate it without loading SKILL.md.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
             { name: 'plugin', type: 'string', required: true, constraint: 'Plugin the skill belongs to.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the skill was resolved from.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to SKILL.md.' },
-            { name: 'content', type: 'string', required: true, constraint: 'SKILL.md body (with or without frontmatter per the --frontmatter flag).' },
+            { name: 'content', type: 'string', required: false, constraint: 'SKILL.md body (with or without frontmatter per --frontmatter). Omitted when --no-body is set.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Hints at variant flags. Present on default reads; omitted when --no-body is set.' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -350,6 +354,7 @@ const readShow = defineLeaf({
         const scopeStr = input['scope'];
         const pluginFilter = input['plugin'];
         const includeFrontmatter = input['frontmatter'];
+        const noBody = input['noBody'];
         const resolveOpts = {};
         if (scopeStr !== undefined) {
             const resolved = resolveScopeArg(scopeStr);
@@ -359,70 +364,21 @@ const readShow = defineLeaf({
         if (pluginFilter !== undefined)
             resolveOpts.pluginFilter = pluginFilter;
         const skillObj = resolveSkill(nameRaw, resolveOpts);
-        const rawContent = readText(skillObj.path);
-        const rawBody = includeFrontmatter ? rawContent : parseFrontmatter(rawContent).body;
-        const content = appendNeighbors(skillObj, rawBody);
-        return {
-            name: skillObj.name,
-            plugin: skillObj.plugin,
-            scope: skillObj.scope,
-            path: skillObj.path,
-            content,
-        };
-    },
-});
-const readWhere = defineLeaf({
-    name: 'where',
-    help: {
-        name: 'skill read where',
-        summary: 'show resolution metadata for a named skill without reading its body',
-        params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
-            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Narrows resolution to a specific plugin.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
-            { name: 'plugin', type: 'string', required: true, constraint: 'Plugin the skill belongs to.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the skill was resolved from.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to SKILL.md.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const nameRaw = input['name'];
-        const scopeStr = input['scope'];
-        const pluginFilter = input['plugin'];
-        const resolveOpts = {};
-        if (scopeStr !== undefined) {
-            const resolved = resolveScopeArg(scopeStr);
-            if (resolved !== 'all')
-                resolveOpts.scope = resolved;
-        }
-        if (pluginFilter !== undefined)
-            resolveOpts.pluginFilter = pluginFilter;
-        const skillObj = resolveSkill(nameRaw, resolveOpts);
-        return {
+        const out = {
             name: skillObj.name,
             plugin: skillObj.plugin,
             scope: skillObj.scope,
             path: skillObj.path,
         };
+        if (noBody)
+            return out;
+        const rawContent = readText(skillObj.path);
+        const rawBody = includeFrontmatter ? rawContent : parseFrontmatter(rawContent).body;
+        out['content'] = appendNeighbors(skillObj, rawBody);
+        out['follow_up'] = 'Add --no-body to skip the body and return path/scope/plugin only. Add --frontmatter to include YAML frontmatter in content.';
+        return out;
     },
 });
-const readBranch = defineBranch({
-    name: 'read',
-    help: {
-        name: 'skill read',
-        summary: 'read skill content or resolve its location',
-        children: [
-            { name: 'show', desc: 'print SKILL.md body', useWhen: 'loading skill content to act on it' },
-            { name: 'where', desc: 'show resolution metadata only', useWhen: 'verifying which skill resolves and from where, without loading its body' },
-        ],
-    },
-    children: [readShow, readWhere],
-});
 // ---------------------------------------------------------------------------
 // author sub-branch
 // ---------------------------------------------------------------------------
@@ -461,7 +417,7 @@ const authorScaffold = defineLeaf({
         name: 'skill author scaffold',
         summary: 'create an empty SKILL.md stub at the given qualifier',
         params: [
-            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>:<skill> form.' },
+            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>/<skill> form.' },
             { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform.' },
             { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Short description written to frontmatter.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
@@ -481,16 +437,22 @@ const authorScaffold = defineLeaf({
         const typeStr = input['type'];
         const description = input['description'];
         const scopeStr = input['scope'];
-        const { plugin: pluginName, name: skillName } = parseSkillQualifier(qualifier);
-        if (!skillName) {
+        const parsed = parseSkillQualifier(qualifier);
+        if (parsed.segments.length === 0) {
             throw usage('skill name required in qualifier');
         }
+        // For scaffold, the qualifier is always <plugin>/<skill>. If it's a single segment,
+        // treat it as a scope-direct skill name. Otherwise first segment is the plugin.
+        const pluginName = parsed.segments.length > 1 ? parsed.segments[0] : undefined;
+        const skillName = parsed.segments.length > 1
+            ? parsed.segments.slice(1).join('/')
+            : parsed.segments[0];
         if (typeStr !== undefined && !isSkillType(typeStr)) {
             throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
         }
         const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
         let skillFile;
-        // Scope-direct: no plugin qualifier, or explicit `_:` sentinel
+        // Scope-direct: no plugin qualifier, or explicit `_/` sentinel (internal only)
         if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
             const scope = resolveWriteScope(scopeStr);
             const scopeRootPath = requireScopeRoot(scope);
@@ -578,7 +540,7 @@ const stateEnable = defineLeaf({
         name: 'skill state enable',
         summary: 'enable a skill in the given scope',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
         ],
         output: [
@@ -597,7 +559,7 @@ const stateDisable = defineLeaf({
         name: 'skill state disable',
         summary: 'disable a skill in the given scope, hiding it from list and agent discovery',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
         ],
         output: [
@@ -622,12 +584,11 @@ const stateBranch = defineBranch({
     },
     children: [stateEnable, stateDisable],
 });
-// ---------------------------------------------------------------------------
-// Loaded-skills catalog (dynamicState for `skill -h`)
-// ---------------------------------------------------------------------------
-// A skill is a forest root within its source (scope+plugin) when no other
-// skill in that same source is its ancestor (`name` prefix + '/'). Nested
-// children stay discoverable via `skill find list` and the Neighbors section.
+/** 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 {
@@ -640,37 +601,93 @@ function buildSkillCatalog() {
         return null;
     const bySource = new Map();
     for (const s of skills) {
-        const key = `${s.scope}${s.plugin}`;
+        const key = `${s.scope}\t${s.plugin}`;
         const arr = bySource.get(key);
         if (arr)
             arr.push(s);
         else
             bySource.set(key, [s]);
     }
-    const byPrefix = new Map();
-    for (const group of bySource.values()) {
+    const projectSources = [];
+    const userSources = [];
+    for (const [key, group] of bySource) {
+        const [scope, plugin] = key.split('\t');
         const names = group.map((g) => g.name);
-        for (const s of group) {
-            const isChild = names.some((n) => n !== s.name && s.name.startsWith(n + '/'));
-            if (isChild)
-                continue;
-            const prefix = s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}:` : `${s.plugin}/`;
-            let set = byPrefix.get(prefix);
-            if (!set) {
-                set = new Set();
-                byPrefix.set(prefix, set);
+        const roots = names
+            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
+            .sort();
+        if (roots.length === 0)
+            continue;
+        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
+    }
+    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)
+        return;
+    const count = sources.reduce((n, s) => n + s.roots.length, 0);
+    out.push('');
+    out.push(`${label} (${count})`);
+    const sentinel = sources.filter((s) => s.plugin === SCOPE_SKILL_PLUGIN);
+    const named = sources
+        .filter((s) => s.plugin !== SCOPE_SKILL_PLUGIN)
+        .sort((a, b) => a.plugin.localeCompare(b.plugin));
+    for (const s of sentinel) {
+        for (const n of s.roots)
+            out.push(`  ${n}`);
+    }
+    if (named.length === 0)
+        return;
+    const classified = named.map((s) => {
+        const subcats = new Map();
+        const bare = [];
+        for (const n of s.roots) {
+            const slash = n.indexOf('/');
+            if (slash === -1) {
+                bare.push(n);
+            }
+            else {
+                const sub = n.slice(0, slash);
+                const rest = n.slice(slash + 1);
+                const arr = subcats.get(sub);
+                if (arr)
+                    arr.push(rest);
+                else
+                    subcats.set(sub, [rest]);
             }
-            set.add(s.name);
+        }
+        return { plugin: s.plugin, roots: s.roots, subcats, bare };
+    });
+    // Smart-nest: a plugin nests iff it has 2+ distinct subcategories.
+    const nests = (p) => p.subcats.size >= 2;
+    const inlineLabels = classified.filter((p) => !nests(p)).map((p) => `${p.plugin}/`);
+    const inlineW = inlineLabels.reduce((m, p) => (p.length > m ? p.length : m), 0);
+    for (const p of classified) {
+        if (nests(p)) {
+            out.push(`  ${p.plugin}/`);
+            if (p.bare.length > 0) {
+                out.push(`    ${[...p.bare].sort().join(', ')}`);
+            }
+            const subKeys = [...p.subcats.keys()].sort();
+            const subLabels = subKeys.map((k) => `${k}/`);
+            const subW = subLabels.reduce((m, k) => (k.length > m ? k.length : m), 0);
+            for (let i = 0; i < subKeys.length; i++) {
+                const children = p.subcats.get(subKeys[i]).sort();
+                out.push(`    ${subLabels[i].padEnd(subW)}  ${children.join(', ')}`);
+            }
+        }
+        else {
+            const pluginLabel = `${p.plugin}/`;
+            out.push(`  ${pluginLabel.padEnd(inlineW)}  ${[...p.roots].sort().join(', ')}`);
         }
     }
-    const prefixes = [...byPrefix.keys()].sort();
-    const prefixW = prefixes.reduce((m, p) => (p.length > m ? p.length : m), 0);
-    const lines = [`Loaded skills (${skills.length})`];
-    for (const prefix of prefixes) {
-        const names = [...byPrefix.get(prefix)].sort();
-        lines.push(`  ${prefix.padEnd(prefixW)}  ${names.join(', ')}`);
-    }
-    return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
 // Root export
@@ -678,18 +695,24 @@ function buildSkillCatalog() {
 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',
-            model: '`find` when you do not yet know which skill applies — it locates candidates by topic, keyword, or body text. `read` when you have a name and need the SKILL.md content or its on-disk location. `author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Append `-h` at any branch or leaf for its full schema.',
+            model: '`find` when you do not yet know which skill applies — it locates candidates by topic, keyword, or body text. `read` (leaf) loads SKILL.md by name; takes the name as a positional, returns body + metadata, accepts --no-body to skip the body. `author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Append `-h` at any branch or leaf for its full schema.',
             dynamicState: buildSkillCatalog,
             children: [
                 { name: 'find', desc: 'list, search, or grep skills', useWhen: 'discovering what skills are available' },
-                { name: 'read', desc: 'read skill content or resolve location', useWhen: 'loading a skill to act on it' },
+                { name: 'read', desc: 'load SKILL.md body + metadata for a named skill', useWhen: 'loading a skill to act on it' },
                 { name: 'author', desc: 'create and scaffold skills', useWhen: 'writing a new skill' },
                 { name: 'state', desc: 'enable or disable skills', useWhen: 'toggling skill visibility' },
             ],
         },
-        children: [findBranch, readBranch, authorBranch, stateBranch],
+        children: [findBranch, readLeaf, authorBranch, stateBranch],
     });
 }

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 flow spec new`:\n\n  echo '<spec markdown>' | crtr flow 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 job start 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 flow 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 flow spec new\`:
+Run \`crtr mode spec new\`:
 
-  echo '<spec markdown>' | crtr flow 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 job start 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: '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 job start).',
+                    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 job start planner --artifact-path ${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 job start 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: '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: '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: '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',