@crouton-kit/crouter 0.1.7 → 0.1.9

package/dist/cli.js

@@ -13,7 +13,7 @@ import { registerPlanCommand } from './commands/plan.js';
 import { registerSpecCommand } from './commands/spec.js';
 import { registerAgentCommand } from './commands/agent.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
-import { ensureBootSkill, ensureOfficialMarketplace } from './core/bootstrap.js';
+import { ensureBootSkill, ensureOfficialMarketplace, ensureProjectScope } from './core/bootstrap.js';
 function readPackageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     const pkgPath = join(here, '..', 'package.json');
@@ -38,6 +38,7 @@ registerSpecCommand(program);
 registerAgentCommand(program);
 ensureOfficialMarketplace(process.argv);
 ensureBootSkill(process.argv);
+ensureProjectScope(process.argv);
 maybeAutoUpdate(process.argv);
 program.parseAsync().catch((err) => {
     process.stderr.write(`crtr: ${err instanceof Error ? err.message : String(err)}\n`);

package/dist/commands/skill.js

@@ -31,11 +31,18 @@ function buildShowFooter(skillPath) {
 function wrapSkill(name, path, content) {
     return `<skill name="${name}" path="${path}">\n${content.endsWith('\n') ? content : content + '\n'}</skill>`;
 }
+const SKILL_IDENTIFIER_HELP = 'Skill identifier forms (accepted by show, path, where, enable, disable):\n' +
+    '  <name>                       bare name — resolves scope-root first, then plugins\n' +
+    '  <plugin>:<name>              explicit plugin (canonical)\n' +
+    '  <scope>:<name>               scope-root skill in a specific scope (user|project)\n' +
+    '  <scope>:<plugin>/<name>      fully qualified — matches `skill list` / `skill search` output\n' +
+    '  <plugin>/<name>              shorthand for <plugin>:<name> when unambiguous';
 export function registerSkillCommands(program) {
     const skill = program
         .command('skill [nameOrVerb] [rest...]')
         .description('manage and inspect skills')
         .option('--frontmatter', 'include YAML frontmatter in the printed body')
+        .addHelpText('after', '\n' + SKILL_IDENTIFIER_HELP)
         .action(async (nameOrVerb, _rest, opts) => {
         if (nameOrVerb === undefined) {
             out(skillPrompt());
@@ -62,6 +69,8 @@ export function registerSkillCommands(program) {
         .option('--plugin <name>', 'filter by plugin name')
         .option('-a, --all', 'include disabled skills')
         .option('--json', 'emit JSON')
+        .addHelpText('after', '\nOutput format: <scope>:<plugin>/<name> — paste this identifier into ' +
+        '`crtr skill show` to read the skill.')
         .action(async (opts) => {
         try {
             const scopes = listScopes(opts.scope);
@@ -109,6 +118,12 @@ export function registerSkillCommands(program) {
         .option('--plugin <name>', 'filter by plugin name')
         .option('--frontmatter', 'include YAML frontmatter in the printed body')
         .option('--json', 'emit JSON')
+        .addHelpText('after', '\nExamples:\n' +
+        '  crtr skill show rules                              # bare name\n' +
+        '  crtr skill show claude-authoring:rules             # plugin:name (canonical)\n' +
+        '  crtr skill show user:claude-authoring/rules        # scope:plugin/name (matches search/list output)\n' +
+        '  crtr skill show claude-authoring/rules             # plugin/name shorthand\n\n' +
+        SKILL_IDENTIFIER_HELP)
         .action(async (name, opts) => {
         try {
             const scopeArg = resolveScopeArg(opts.scope);
@@ -363,6 +378,8 @@ export function registerSkillCommands(program) {
         .option('-a, --all', 'include disabled skills')
         .option('--body', 'also search SKILL.md body')
         .option('--json', 'emit JSON')
+        .addHelpText('after', '\nOutput columns (tab-separated): <scope>:<plugin>/<name>  <matched-fields>  <description>\n' +
+        'The identifier is pasteable into `crtr skill show`.')
         .action(async (query, opts) => {
         try {
             const needle = query.toLowerCase();

package/dist/core/artifact.js

@@ -6,7 +6,8 @@ import { CRTR_DIR_NAME } from '../types.js';
 import { ensureDir, pathExists, readText, walkFiles } from './fs-utils.js';
 import { usage, notFound, general } from './errors.js';
 import { out, hint, jsonOut, handleError, info } from './output.js';
-import { spawnSidePaneReview, DEFAULT_PANE_OPTS, } from './spawn.js';
+import { spawnSidePaneReview, countPanesInCurrentWindow, DEFAULT_PANE_OPTS, } from './spawn.js';
+import { readConfig } from './config.js';
 export function mangleCwd(cwd = process.cwd()) {
     return cwd.replace(/\//g, '-');
 }
@@ -32,7 +33,17 @@ export function inTmux() {
     return Boolean(process.env.TMUX);
 }
 export function openInTmuxPane(path) {
-    const result = spawnSync('termrender', ['--tmux', path], {
+    // Always pass --watch so the pane live-updates when the agent edits the
+    // file. The watcher re-detects width on resize and survives parse errors.
+    const args = ['--tmux', '--watch'];
+    // If the current tmux window is already at the configured pane budget,
+    // open in a new window instead of cramping the existing split further.
+    const maxPanes = readConfig('user').max_panes_per_window;
+    if (countPanesInCurrentWindow() >= maxPanes) {
+        args.push('--tmux-new-window');
+    }
+    args.push(path);
+    const result = spawnSync('termrender', args, {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.error) {
@@ -52,7 +63,7 @@ export function openInTmuxPane(path) {
     }
     const paneId = result.stdout.toString().trim();
     if (paneId)
-        hint(`opened in tmux pane ${paneId}`);
+        hint(`opened in tmux pane ${paneId} (live — edits to the file refresh the view)`);
 }
 async function readStdin() {
     const chunks = [];

package/dist/core/bootstrap.d.ts

@@ -3,3 +3,4 @@ export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs
 export declare const OFFICIAL_MARKETPLACE_REF = "main";
 export declare function ensureBootSkill(argv: string[]): void;
 export declare function ensureOfficialMarketplace(argv: string[]): void;
+export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -1,11 +1,12 @@
 import { writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { userScopeRoot } from './scope.js';
+import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js';
 import { ensureDir, pathExists, readText, removePath, nowIso } from './fs-utils.js';
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
 import { readMarketplaceManifest } from './manifest.js';
+import { CRTR_DIR_NAME } from '../types.js';
 export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
 export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
 export const OFFICIAL_MARKETPLACE_REF = 'main';
@@ -141,3 +142,29 @@ export function ensureOfficialMarketplace(argv) {
         }
     }
 }
+export function ensureProjectScope(argv) {
+    try {
+        if (process.env.CRTR_NO_AUTO_INIT === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        // Already inside a project scope (here or in an ancestor) — nothing to do.
+        if (findProjectScopeRoot() !== null)
+            return;
+        const cwd = process.cwd();
+        // Never auto-init at $HOME — that path is reserved for the user scope.
+        if (cwd === homedir())
+            return;
+        const projectRoot = join(cwd, CRTR_DIR_NAME);
+        if (projectRoot === userScopeRoot())
+            return;
+        ensureScopeInitialized('project', projectRoot);
+        resetScopeCache();
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: project-init error: ${msg}\n`);
+        }
+    }
+}

package/dist/core/resolver.d.ts

@@ -18,10 +18,12 @@ export interface SkillResolutionOpts {
     pluginFilter?: string;
 }
 export declare function resolveSkill(rawName: string, opts?: SkillResolutionOpts): Skill;
-export declare function parseSkillQualifier(raw: string): {
+export interface ParsedSkillQualifier {
+    scope?: Scope;
     plugin?: string;
     name: string;
-};
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
 export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
 export declare function listAllMarketplaces(): InstalledMarketplace[];
 export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;

package/dist/core/resolver.js

@@ -4,7 +4,7 @@ import { readConfig } from './config.js';
 import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
-import { ambiguous, notFound } from './errors.js';
+import { ambiguous, notFound, usage } from './errors.js';
 import { marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
 export function listInstalledPlugins(scope) {
     const dir = pluginsDir(scope);
@@ -139,16 +139,47 @@ export function listAllSkills(scopeFilter) {
     ];
 }
 export function resolveSkill(rawName, opts = {}) {
-    const { plugin: pluginQualifier, name } = parseSkillQualifier(rawName);
-    const plugins = opts.scope ? listInstalledPlugins(opts.scope) : listAllPlugins();
+    const parsed = parseSkillQualifier(rawName);
+    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
+        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
+    }
+    if (parsed.plugin && opts.pluginFilter && parsed.plugin !== opts.pluginFilter) {
+        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${parsed.plugin}" but --plugin is "${opts.pluginFilter}"`);
+    }
+    const effectiveScope = opts.scope ?? parsed.scope;
+    const effectivePluginFilter = opts.pluginFilter ?? parsed.plugin;
+    const direct = findSkillMatches(parsed.name, parsed.plugin, effectiveScope, effectivePluginFilter);
+    if (direct.length > 0)
+        return pickMatch(direct, parsed.name, parsed.plugin);
+    // Fallback: bare `plugin/name` (no colon) — try splitting on first `/`.
+    // Disambiguates "claude-authoring/rules" (which the search/list display also emits as
+    // "user:claude-authoring/rules") from a nested scope-root skill of the same shape.
+    if (!parsed.plugin && parsed.name.includes('/')) {
+        const slashIdx = parsed.name.indexOf('/');
+        const maybePlugin = parsed.name.slice(0, slashIdx);
+        const rest = parsed.name.slice(slashIdx + 1);
+        if (effectivePluginFilter === undefined || effectivePluginFilter === maybePlugin) {
+            const fallback = findSkillMatches(rest, maybePlugin, effectiveScope, maybePlugin);
+            if (fallback.length > 0)
+                return pickMatch(fallback, rest, maybePlugin);
+        }
+    }
+    throw notFound(formatNotFoundMessage(rawName, parsed), {
+        skill: parsed.name,
+        plugin: parsed.plugin,
+        scope: parsed.scope,
+    });
+}
+function findSkillMatches(name, pluginQualifier, scope, pluginFilter) {
+    const plugins = scope ? listInstalledPlugins(scope) : listAllPlugins();
     const enabledPlugins = plugins.filter((p) => p.enabled);
     const cfgs = loadScopeConfigs();
     const matches = [];
     // Scope-root skills first — they're the user's own captured knowledge.
-    if (!opts.pluginFilter &&
+    if (!pluginFilter &&
         (pluginQualifier === undefined || pluginQualifier === SCOPE_SKILL_PLUGIN)) {
-        const scopes = opts.scope
-            ? [opts.scope]
+        const scopes = scope
+            ? [scope]
             : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
         for (const s of scopes) {
             const skillsRoot = scopeSkillsDir(s);
@@ -176,7 +207,7 @@ export function resolveSkill(rawName, opts = {}) {
     for (const plugin of ordered) {
         if (pluginQualifier && plugin.name !== pluginQualifier)
             continue;
-        if (opts.pluginFilter && plugin.name !== opts.pluginFilter)
+        if (pluginFilter && plugin.name !== pluginFilter)
             continue;
         const skillPath = join(plugin.root, SKILLS_DIR, ...name.split('/'), SKILL_ENTRY_FILE);
         if (!pathExists(skillPath))
@@ -195,20 +226,16 @@ export function resolveSkill(rawName, opts = {}) {
             disabledIn,
         });
     }
-    if (matches.length === 0) {
-        throw notFound(pluginQualifier
-            ? `skill not found: ${pluginQualifier}:${name}`
-            : `skill not found: ${name}`, { skill: name, plugin: pluginQualifier });
-    }
+    return matches;
+}
+function pickMatch(matches, name, pluginQualifier) {
     if (matches.length === 1)
         return matches[0];
     const sameScopeAndPlugin = matches.every((m) => m.plugin === matches[0].plugin && m.scope === matches[0].scope);
     if (sameScopeAndPlugin)
         return matches[0];
-    // Resolution order picks the first; flag ambiguity only if user didn't qualify.
-    if (!pluginQualifier) {
+    if (!pluginQualifier)
         return matches[0];
-    }
     throw ambiguous(`ambiguous skill: ${name}`, {
         skill: name,
         candidates: matches.map((m) => ({
@@ -218,11 +245,111 @@ export function resolveSkill(rawName, opts = {}) {
         })),
     });
 }
+function formatNotFoundMessage(rawName, parsed) {
+    const suggestions = suggestSkills(parsed.name, parsed.plugin);
+    const lines = [`skill not found: ${rawName}`];
+    lines.push('       expected forms: <name>, <plugin>:<name>, <scope>:<plugin>/<name>');
+    if (suggestions.length > 0) {
+        const formatted = suggestions
+            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}:${s.name}`)
+            .slice(0, 3);
+        lines.push(`       did you mean: ${formatted.join(', ')}`);
+    }
+    else {
+        lines.push('       run `crtr skill list` or `crtr skill search <query>` to discover skills');
+    }
+    return lines.join('\n');
+}
+function suggestSkills(name, plugin) {
+    let all;
+    try {
+        all = listAllSkills();
+    }
+    catch {
+        return [];
+    }
+    const target = name.toLowerCase();
+    const targetBase = target.split('/').pop() ?? target;
+    const targetPluginGuess = target.includes('/') ? target.split('/')[0] : undefined;
+    const exactName = all.filter((s) => s.name.toLowerCase() === target);
+    if (exactName.length > 0)
+        return exactName;
+    const exactBase = all.filter((s) => {
+        const sBase = s.name.toLowerCase().split('/').pop() ?? s.name.toLowerCase();
+        return sBase === targetBase;
+    });
+    if (exactBase.length > 0)
+        return exactBase;
+    const scored = all
+        .map((s) => {
+        const sName = s.name.toLowerCase();
+        const sBase = sName.split('/').pop() ?? sName;
+        const sPlugin = s.plugin.toLowerCase();
+        let score = 0;
+        if (plugin !== undefined && sPlugin === plugin.toLowerCase())
+            score += 5;
+        if (targetPluginGuess !== undefined && sPlugin === targetPluginGuess)
+            score += 5;
+        if (sName.includes(target) || target.includes(sName))
+            score += 4;
+        if (sBase.includes(targetBase) || targetBase.includes(sBase))
+            score += 3;
+        if (editDistance(sBase, targetBase) <= 2)
+            score += 4;
+        return { skill: s, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, 3).map((x) => x.skill);
+}
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j];
+    }
+    return prev[b.length];
+}
+const SCOPE_QUALIFIERS = new Set(['user', 'project']);
+// Accepted identifier forms:
+//   <name>                         — bare name; scope-root first, then plugins
+//   <plugin>:<name>                — explicit plugin
+//   <scope>:<name>                 — scope-root in a specific scope
+//   <scope>:<plugin>/<name>        — fully qualified (matches `skill list` / `skill search` display)
+// Bare `<plugin>/<name>` (no colon) is handled as a fallback inside resolveSkill.
 export function parseSkillQualifier(raw) {
-    const idx = raw.indexOf(':');
-    if (idx === -1)
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1)
         return { name: raw };
-    return { plugin: raw.slice(0, idx), name: raw.slice(idx + 1) };
+    const before = raw.slice(0, colonIdx);
+    const after = raw.slice(colonIdx + 1);
+    if (SCOPE_QUALIFIERS.has(before)) {
+        const scope = before;
+        const slashIdx = after.indexOf('/');
+        if (slashIdx !== -1) {
+            return {
+                scope,
+                plugin: after.slice(0, slashIdx),
+                name: after.slice(slashIdx + 1),
+            };
+        }
+        return { scope, name: after };
+    }
+    return { plugin: before, name: after };
 }
 function orderPluginsByResolution(plugins) {
     const score = (p) => {

package/dist/prompts/agent.js

@@ -25,37 +25,97 @@ The originating pane has closed; the user is watching you here. Begin now.`;
  * First user message for a plan → implementation handoff.
  */
 export function implementHandoffPrompt(planPath) {
-    return `You are an implementation agent. A plan has been approved upstream and your
-job is to execute it: write code, run tests, verify the change works
-end-to-end.
+    return `You are executing an approved plan. For small plans, implement directly.
+For plans with parallelizable scale, orchestrate parallel subagents and
+coordinate them — don't write all the code yourself when the plan is
+structured to fan out.
 
 **Plan to implement:** ${planPath}
 
-## Process
-
-1. Read the plan end-to-end before touching code.
-2. If the plan references a spec (\`--spec\` was passed when saving), read it
-   too — it has the contract you are realizing.
-3. Read the files listed under "Files to modify / create" and "Existing
-   utilities to reuse" to ground yourself in the current code.
-4. Execute the plan step by step. Stay within scope — if the plan does not
-   call for a change, do not make it.
-5. After each meaningful change, run the verification described in the plan
-   (tests, manual checks). Fix anything that fails before continuing.
-6. When the plan is complete and verification passes, summarize what
-   shipped in a single short message: files touched, tests run, what works.
-
-## Guardrails
-
-- **Do not redesign.** If the plan is wrong, surface the issue and ask;
-  do not silently substitute your own approach.
-- **Do not expand scope.** No drive-by refactors, no "while I'm here" cleanup.
-- **Honor existing conventions.** Match the file's style, naming, and
-  patterns. Use the utilities the plan named.
-- Commit only if the user asks.
+## Phase 1: Read
+
+1. Read the plan end-to-end. If it references a spec (\`--spec\` was passed
+   at save time), read that too — it's the contract you are realizing.
+2. Read the files the plan names under "Files to modify / create" (or the
+   per-task \`Files:\` lines) and "Existing utilities to reuse" to ground
+   yourself in current code.
+3. If the plan has task blocks with dependencies, extract the task list,
+   dependency graph, and integration contracts.
+
+## Phase 2: Scale
+
+Count the plan's **independent task groups** (tasks with no mutual
+dependencies that can run in parallel). Pick the strategy:
+
+| Independent groups | Files touched | Strategy |
+|-------------------|---------------|----------|
+| 1                 | 1–3           | **Implement directly.** Skip Phases 3–5; just execute the plan and go to Phase 6. |
+| 1–2               | 3–5           | Implement directly, or single subagent if you want parallelism with verification |
+| 2–4               | 5–15          | **2 parallel subagents** |
+| 4–8               | 10–30         | **3 parallel subagents** |
+| 8+                | 25+           | **4 parallel subagents** (cap) |
+
+Use the higher column to pick the tier. Never spawn more subagents than
+there are independent groups. **Bump one tier** if: tight cross-group
+interface coordination, mixed languages/frameworks, or both infra +
+application layers change.
+
+## Phase 3: Partition
+
+Group tasks into **disjoint sets** where:
+
+- Each group owns clear file boundaries — **no two groups edit the same files**.
+- Within a group, tasks are sequenced for one subagent to execute in order.
+- Across groups, dependencies become layers: dependent groups run *after*
+  their predecessors complete.
+
+If two tasks must touch the same file, sequence them in the same group.
+
+## Phase 4: Dispatch
 
-When verification passes, your turn ends. The user may then ask for a code
-review via \`crtr agent review\`.
+For each task group in the current dependency layer, dispatch a subagent
+in parallel via the Task tool. Use \`general-purpose\` by default; use
+\`devcore:programmer\` if the project has devcore installed.
+
+**Each subagent's prompt must include:**
+- The specific tasks from the plan it owns (paste verbatim)
+- The plan path: \`${planPath}\`
+- The spec path if one exists
+- The exact file ownership for this group
+- Integration contracts it produces or consumes (types, APIs, shapes)
+- **Constraint: do NOT run tests or typechecks** — other subagents may be
+  mid-edit. The orchestrator runs verification at layer boundaries.
+- Instruction to return when its tasks are complete, surfacing blockers
+
+## Phase 5: Coordinate
+
+Wait for all subagents in the current layer. Then:
+
+- If any reports a blocker, resolve it: fix yourself, adjust scope with
+  the user, or re-dispatch a corrected task. Don't proceed past the blocker.
+- Run the plan's verification for the just-finished layer (tests, manual
+  checks). Fix any failures before dispatching the next layer.
+- Dispatch the next layer.
+
+**Stay in the coordinator role.** Don't implement tasks yourself unless a
+subagent returns blocked work and the fix is small enough that re-dispatch
+would be slower.
+
+## Phase 6: Report
+
+When all tasks complete and verification passes, write one short message:
+files touched per group, tests run, what works. The user may then ask for
+a code review via \`crtr agent review\`.
+
+## Guardrails (apply to you AND your subagents)
+
+- **No redesign.** If the plan is wrong, surface the issue — do not
+  silently substitute your own approach.
+- **No scope expansion.** No drive-by refactors, no "while I'm here"
+  cleanup, no new abstractions the plan didn't request.
+- **Honor conventions.** Match each file's existing style, naming, and
+  patterns. Use the utilities the plan named.
+- **Commit only if the user asks.**
 
 You were launched in a new tmux pane via \`crtr agent implement\`. The
 originating pane has closed; the user is watching you here. Begin by reading

package/dist/prompts/plan.js

@@ -58,6 +58,19 @@ between approaches. Never use it to ask the user "is this plan okay?" or
 
 ## Phase 4: Final Plan
 
+### Quality bar
+
+Hold the draft to these — they're cheap to satisfy and they save the
+implementer from re-deciding things:
+
+- 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 rather than "design a Foo type."
+
+### Save
+
 Save the plan with \`crtr plan --name <kebab-case-name>\`. Pipe the markdown
 body in via stdin (heredoc):
 
@@ -85,6 +98,22 @@ Be concise enough to scan, detailed enough to execute.>
 EOF
 \`\`\`
 
+For plans touching 4+ files across distinct concerns, the implementer can
+dispatch parallel subagents — but only if you structure tasks for it. In
+that case, replace "Files to modify / create" with task blocks like:
+
+\`\`\`
+## 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 this structure for small plans; it's noise when there's no
+parallelism to unlock.
+
 - Pick a short, descriptive kebab-case name. Names may be nested
   (\`crtr plan --name auth/jwt-refresh\`) — they become subdirectories.
 - If this plan implements a saved spec, pass \`--spec <spec-name>\` so the
@@ -92,7 +121,11 @@ EOF
   \`crtr plan --name <name> --spec <spec-name> <<'EOF' ... EOF\`
 - The file lands at \`${plansDir}/<name>.md\`.
 - If you are running inside tmux, the saved plan auto-opens in a side pane
-  via termrender. No extra step needed.
+  (or a new window when the current one is full) via termrender. The pane
+  is **live** — it re-renders whenever the file changes on disk. For small
+  tweaks, **edit the file path directly with the Edit tool** instead of
+  re-running the heredoc save; the pane updates in place. Re-save via
+  heredoc only when you want to re-trigger the reviewer.
 
 ## Phase 5: Review
 

package/dist/prompts/review.js

@@ -16,40 +16,53 @@ summarize or chat after submission — \`crtr agent submit\` IS the response.
 If you cannot complete the review (file missing, totally malformed, etc.),
 still call \`crtr agent submit\` with a brief explanation of why.`;
 export function specReviewPrompt(specPath) {
-    return `You are reviewing a spec document. Verify it is complete and ready for planning.
+    return `You are reviewing a spec document. Verify it is complete and ready for
+planning.
 
 **Spec to review:** ${specPath}
 
-## What to Check
+Read the spec end-to-end first.
 
-| Category | What to Look For |
+## What to check
+
+| Category | What to look for |
 |----------|------------------|
 | Completeness | TODOs, placeholders, "TBD", incomplete sections |
 | Consistency | Internal contradictions, conflicting requirements |
 | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
-| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+| Scope | Focused enough for a single plan |
 | YAGNI | Unrequested features, over-engineering |
 
-## Calibration
+For specs with non-trivial component interaction, also walk the primary
+flow from trigger to final state and check whether preconditions, state
+transitions, failure handling, and handoffs between components are
+actually specified. This is the highest-signal check when there are
+seams to fall between — skip it for self-contained specs.
 
-**Only flag issues that would cause real problems during implementation planning.**
-A missing section, a contradiction, or a requirement so ambiguous it could be
-interpreted two different ways — those are issues. Minor wording improvements,
-stylistic preferences, and "sections less detailed than others" are not.
+For larger specs touching established patterns, optionally spawn a Task
+agent (\`general-purpose\`, \`sonnet\`) to cross-check the spec's design
+against \`CLAUDE.md\` / \`.claude/rules/*.md\` and the files it references,
+looking for contradictions with project conventions. Skip for small specs.
+
+## Calibration
 
-Approve unless there are serious gaps that would lead to a flawed plan.
+Approve unless an implementer or planner would be led astray. Real issues:
+missing requirements, contradictory design, unspecified failure modes on
+critical paths, requirements ambiguous enough to be built two ways. Not
+issues: wording preferences, "I'd have organized this differently",
+sections less detailed than others.
 
-## Output Format
+## Output
 
 ## Spec Review
 
 **Status:** Approved | Issues Found
 
 **Issues (if any):**
-- [Section X]: [specific issue] - [why it matters for planning]
+- [Section]: [specific issue] — [why it matters for planning]
 
 **Recommendations (advisory, do not block approval):**
-- [suggestions for improvement]
+- [suggestions]
 
 ${SUBMIT_INSTRUCTIONS}`;
 }
@@ -65,39 +78,46 @@ merits (internal completeness, task decomposition, buildability). Skip the
 
 Read the plan first, then the spec, then evaluate alignment and the other
 criteria below.`;
-    return `You are reviewing a plan document. Verify it is complete and ready for implementation.
+    return `You are reviewing a plan document. Verify it is complete and ready for
+implementation.
 
 ${inputs}
 
-## What to Check
+## What to check
 
-| Category | What to Look For |
+| Category | What to look for |
 |----------|------------------|
 | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
-| Spec Alignment | Plan covers spec requirements, no major scope creep |
-| Task Decomposition | Tasks have clear boundaries, steps are actionable |
-| Buildability | Could an engineer follow this plan without getting stuck? |
+${specPath === null ? '' : '| Spec alignment | Plan covers spec requirements, no major scope creep, no unjustified divergence from the spec\'s design |\n'}| Resolved decisions | No "if X then Y" branches, no "investigate whether…", no deferred choices |
+| Buildability | Could an engineer follow this without getting stuck or re-deciding things? |
+| Quality smells | Timelines, "for now" shortcuts, magic values, fallbacks, missing type definitions where the plan creates a new contract |
 
-## Calibration
+For medium+ plans that claim parallelizable tasks, also check that tasks
+own disjoint files (or call out unavoidable overlap) and that shared
+types/APIs between tasks have their contracts specified.
+
+For large plans${specPath === null ? '' : ', or when spec coverage feels uncertain'}, you may
+optionally spawn one Task agent (\`general-purpose\`, \`sonnet\`) to
+cross-check ${specPath === null ? 'coverage of the plan\'s own stated phases against its task list' : `spec requirements at \`${specPath}\` against plan tasks`}.
+Skip for small plans.
 
-**Only flag issues that would cause real problems during implementation.**
-An implementer building the wrong thing or getting stuck is an issue.
-Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+## Calibration
 
-Approve unless there are serious gaps — missing requirements from the spec,
-contradictory steps, placeholder content, or tasks so vague they can't be acted on.
+Approve unless an implementer would build the wrong thing, get stuck, or
+ship something that violates the plan's quality bar. Minor wording,
+stylistic preferences, and "nice to have" reorganizations are NOT issues.
 
-## Output Format
+## Output
 
 ## Plan Review
 
 **Status:** Approved | Issues Found
 
 **Issues (if any):**
-- [Task X, Step Y]: [specific issue] - [why it matters for implementation]
+- [Task / Section]: [specific issue] — [why it matters for implementation]
 
 **Recommendations (advisory, do not block approval):**
-- [suggestions for improvement]
+- [suggestions]
 
 ${SUBMIT_INSTRUCTIONS}`;
 }

package/dist/prompts/skill.js

@@ -5,6 +5,22 @@ Skills are markdown the agent loads on demand. **Audience: future LLM agent
 sessions, not humans.** Write for the model: terse, decision-first, dense.
 The CLI is the index — \`crtr skill list/search/grep\` discovers what's saved.
 
+## Route by intent
+
+If a query follows this prompt, route based on it. Run the suggested command
+first, then act on its output.
+
+- **Capture** ("save", "remember", "build context for", "make a skill"):
+  \`crtr skill create [topic]\` — picks template, hints next command.
+- **Find** ("what do we have on X", "skill for Y"):
+  \`crtr skill search <query>\` → \`crtr skill show <name>\` on best hit.
+- **Load by name** ("show me X"): \`crtr skill show <name>\`.
+- **List all**: \`crtr skill list\`.
+- **No intent given / query empty**: ask the user what they want before running.
+
+Don't load \`create\` and \`template\` outputs in the same turn — \`create\` decides
+the type, then call \`template\`.
+
 Locations (resolution order):
 1. **Scope-direct** \`<scope-root>/skills/<name>/SKILL.md\` → \`user:<name>\` / \`project:<name>\`
 2. **Plugin skills** \`<plugin>/skills/<name>/SKILL.md\` → \`<scope>:<plugin>/<name>\`

package/dist/prompts/spec.js

@@ -12,6 +12,10 @@ Specs for this directory live at:
 If a relevant prior spec already exists there, read it first. Treat an
 existing spec as the starting point — extend or revise rather than restart.
 
+**Anti-pattern: do not fish for clarifications upfront.** Draft a concrete
+spec first based on your investigation, *then* iterate. A specific draft the
+user can react to converges faster than a list of questions in a vacuum.
+
 ## Phase 1: Shape
 
 Build a comprehensive picture of the problem and the relevant code. Surface
@@ -36,18 +40,25 @@ should be:
 - **Behavior-focused** — describes what the system does, not how.
 - **Scoped** — covers one observable behavior.
 
-Prefer EARS-style phrasing where it fits (\`When <trigger>, the system shall
-<behavior>\`), but do not force it. Group requirements by capability.
+Group requirements by capability. Plain English is fine for most things. If
+a requirement is conditional or stateful enough that phrasing gets fuzzy,
+EARS templates can sharpen it (\`When <trigger>, the system shall <behavior>\`
+or \`If <condition>, then the system shall <response>\`) — reach for them
+when they earn their keep, not by default.
 
-You may launch a Plan agent to draft requirements for a specific capability
-in parallel, but for small specs writing them yourself is usually faster.
+For larger / multi-component designs, before moving on it's worth walking
+the design end-to-end as a sanity check: at each step from trigger to
+final state, ask whether preconditions, state, failure handling, and
+handoffs between components are actually specified. Skip this for small
+self-contained specs — it's the kind of thing that catches bugs in the
+seams, so apply it where there are seams.
 
 ## Phase 3: Deepen
 
 - Read the critical files identified during Phase 1 to deepen your
   understanding before locking decisions.
-- Reconcile the requirements against the shape — if a requirement reveals a
-  gap in the design, refine the design before saving.
+- Reconcile requirements against the shape — if a requirement reveals a gap
+  in the design, refine the design before saving.
 - Use **AskUserQuestion** for any remaining ambiguities. Bias toward asking
   when a decision is non-obvious or when the user's intent is genuinely
   unclear.
@@ -74,10 +85,10 @@ outcome. Include relevant constraints — user goals, stakeholders, deadlines.>
 they were chosen. Reference existing code with \`file_path:line_number\`.>
 
 ## Requirements
-<grouped behavioral requirements. Each one testable.>
+<grouped behavioral requirements. Each one testable. Plain English is fine.>
 
 ### <Capability A>
-- When <trigger>, the system shall <behavior>.
+- <one observable behavior>
 - ...
 
 ### <Capability B>
@@ -96,7 +107,11 @@ EOF
   (\`crtr spec --name auth/refresh-tokens\`).
 - The file lands at \`${specsDir}/<name>.md\`.
 - If you are running inside tmux, the saved spec auto-opens in a side pane
-  via termrender. No extra step needed.
+  (or a new window when the current one is full) via termrender. The pane
+  is **live** — it re-renders whenever the file changes on disk. For small
+  tweaks, **edit the file path directly with the Edit tool** instead of
+  re-running the heredoc save; the pane updates in place. Re-save via
+  heredoc only when you want to re-trigger the reviewer.
 
 ## Phase 5: Review
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",