@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/subagents.js

@@ -1,163 +0,0 @@
-// Subagent discovery + resolution.
-//
-// Subagents are markdown files with YAML frontmatter, modeled on the pi
-// subagent extension but surfaced through the crtr `agent` CLI. Each file
-// declares a name/description (+ optional tools/model) in frontmatter; its
-// markdown body becomes the spawned agent's appended system prompt.
-//
-// Layout mirrors skills, one level shallower (flat files, not nested dirs):
-//   <scope-root>/agents/<name>.md        — scope-root agents (user/project)
-//   <plugin-root>/agents/<name>.md       — plugin-provided agents
-//
-// Resolution precedence matches skills: project before user before builtin;
-// scope-root agents before plugin agents within a scope.
-import { join, basename } from 'node:path';
-import { readdirSync } from 'node:fs';
-import { AGENTS_DIR, SCOPE_SKILL_PLUGIN } from '../types.js';
-import { listAllPlugins, listInstalledPlugins } from './resolver.js';
-import { parseFrontmatterGeneric } from './frontmatter.js';
-import { pathExists, readText } from './fs-utils.js';
-import { projectScopeRoot, scopeRoot } from './scope.js';
-import { ambiguous, notFound } from './errors.js';
-/** `<scope-root>/agents` for a given scope, or null when the scope has no root. */
-export function scopeAgentsDir(scope) {
-    const root = scopeRoot(scope);
-    return root ? join(root, AGENTS_DIR) : null;
-}
-function coerceTools(value) {
-    if (Array.isArray(value)) {
-        const arr = value.map((v) => String(v).trim()).filter(Boolean);
-        return arr.length > 0 ? arr : undefined;
-    }
-    if (typeof value === 'string') {
-        const arr = value
-            .split(',')
-            .map((t) => t.trim())
-            .filter(Boolean);
-        return arr.length > 0 ? arr : undefined;
-    }
-    return undefined;
-}
-function parseSubagentFile(filePath, scope, plugin) {
-    let source;
-    try {
-        source = readText(filePath);
-    }
-    catch {
-        return null;
-    }
-    const { data, body } = parseFrontmatterGeneric(source);
-    if (data === null)
-        return null;
-    // Name defaults to the filename stem when frontmatter omits it. A description
-    // is required for the agent to be useful in listings; skip files without one.
-    const fileStem = basename(filePath).replace(/\.md$/i, '');
-    const name = typeof data.name === 'string' && data.name.trim() !== ''
-        ? data.name.trim()
-        : fileStem;
-    if (typeof data.description !== 'string' || data.description.trim() === '') {
-        return null;
-    }
-    const fm = {
-        name,
-        description: data.description.trim(),
-        tools: coerceTools(data.tools),
-        model: typeof data.model === 'string' && data.model.trim() !== '' ? data.model.trim() : undefined,
-    };
-    return {
-        name,
-        plugin,
-        scope,
-        path: filePath,
-        frontmatter: fm,
-        systemPrompt: body,
-    };
-}
-function listAgentsInDir(dir, scope, plugin) {
-    if (!pathExists(dir))
-        return [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const e of entries) {
-        if (!e.name.toLowerCase().endsWith('.md'))
-            continue;
-        if (!e.isFile() && !e.isSymbolicLink())
-            continue;
-        const parsed = parseSubagentFile(join(dir, e.name), scope, plugin);
-        if (parsed !== null)
-            out.push(parsed);
-    }
-    return out;
-}
-/** Scope-root agents under `<scope-root>/agents/*.md`. */
-export function listScopeRootSubagents(scope) {
-    if (scope === 'builtin')
-        return [];
-    const dir = scopeAgentsDir(scope);
-    if (!dir)
-        return [];
-    return listAgentsInDir(dir, scope, SCOPE_SKILL_PLUGIN);
-}
-/** All subagents: scope-root agents (project, user) plus enabled plugins. */
-export function listSubagents(scopeFilter) {
-    const scopes = scopeFilter
-        ? [scopeFilter]
-        : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
-    const fromScopeRoots = scopes.flatMap((s) => listScopeRootSubagents(s));
-    const plugins = scopeFilter ? listInstalledPlugins(scopeFilter) : listAllPlugins();
-    const fromPlugins = plugins
-        .filter((p) => p.enabled)
-        .flatMap((p) => listAgentsInDir(join(p.root, AGENTS_DIR), p.scope, p.name));
-    return [...fromScopeRoots, ...fromPlugins].sort((a, b) => a.name.localeCompare(b.name));
-}
-/** Canonical, unambiguous identifier: `<plugin>/<name>`, or bare `<name>` for
- *  scope-root agents. */
-export function subagentId(a) {
-    return a.plugin === SCOPE_SKILL_PLUGIN ? a.name : `${a.plugin}/${a.name}`;
-}
-/** Resolve a subagent by name. Accepts a bare `<name>` or a `<plugin>/<name>`
- *  qualifier. Project precedes user precedes builtin; scope-root precedes
- *  plugin. Throws notFound / ambiguous as the skill resolver does. */
-export function resolveSubagent(rawName, opts = {}) {
-    const slash = rawName.indexOf('/');
-    const pluginQualifier = opts.plugin ?? (slash !== -1 ? rawName.slice(0, slash) : undefined);
-    const name = slash !== -1 && opts.plugin === undefined ? rawName.slice(slash + 1) : rawName;
-    const all = listSubagents(opts.scope);
-    let matches = all.filter((a) => a.name === name);
-    if (pluginQualifier !== undefined) {
-        matches = matches.filter((a) => a.plugin === pluginQualifier ||
-            (pluginQualifier === SCOPE_SKILL_PLUGIN && a.plugin === SCOPE_SKILL_PLUGIN));
-    }
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length === 0) {
-        const known = all.map(subagentId).slice(0, 8).join(', ');
-        throw notFound(`subagent not found: ${rawName}`, {
-            subagent: name,
-            plugin: pluginQualifier,
-            next: known !== ''
-                ? `Known subagents: ${known}. Run \`crtr agent subagent list\` for the full set.`
-                : 'No subagents defined. Run `crtr agent subagent author -h` to scaffold one.',
-        });
-    }
-    // Multiple matches: prefer the highest-precedence scope/source deterministically.
-    const score = (a) => {
-        const scopeScore = a.scope === 'project' ? 0 : a.scope === 'user' ? 1 : 2;
-        const sourceScore = a.plugin === SCOPE_SKILL_PLUGIN ? 0 : 1;
-        return scopeScore * 2 + sourceScore;
-    };
-    const sorted = [...matches].sort((a, b) => score(a) - score(b));
-    if (score(sorted[0]) !== score(sorted[1]))
-        return sorted[0];
-    throw ambiguous(`ambiguous subagent: ${rawName}`, {
-        subagent: name,
-        candidates: matches.map((m) => ({ id: subagentId(m), scope: m.scope, path: m.path })),
-        next: 'Qualify with `<plugin>/<name>` or pass --scope to disambiguate.',
-    });
-}

package/dist/prompts/agent.d.ts

@@ -1,27 +0,0 @@
-/**
- * First user message for a spec → plan handoff.
- *
- * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr mode plan new -h`, then saves the plan via `crtr mode plan new`. This
- * avoids embedding the planPrompt() blob here and keeps the prompt in sync
- * with the live CLI without any coupling.
- */
-export declare function planHandoffPrompt(specPath: string, jobId: string): string;
-/**
- * First user message for a plan → implementation handoff.
- */
-export declare function implementHandoffPrompt(planPath: string, jobId: string): string;
-/**
- * First user message for a reviewer agent.
- * The reviewer submits via `crtr job submit` rather than `crtr agent submit`.
- */
-export declare function reviewerHandoffPrompt(artifactPath: string, artifactKind: 'plan' | 'spec', specPath: string | null, jobId: string): string;
-/**
- * First user message for a general `agent new` worker.
- *
- * The worker runs as an interactive agent in a tmux pane (not print mode), so
- * its stdout is NOT captured as the result — it must deliver its answer via
- * `crtr job submit`, exactly like the mode-handoff workers. The original task
- * is sent verbatim; the submit contract is appended after a separator.
- */
-export declare function agentNewPrompt(task: string, jobId: string): string;

package/dist/prompts/agent.js

@@ -1,184 +0,0 @@
-import { planReviewPrompt, specReviewPrompt } from './review.js';
-/**
- * First user message for a spec → plan handoff.
- *
- * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr mode plan new -h`, then saves the plan via `crtr mode plan new`. This
- * avoids embedding the planPrompt() blob here and keeps the prompt in sync
- * with the live CLI without any coupling.
- */
-export function planHandoffPrompt(specPath, jobId) {
-    return `You were launched in a new tmux pane to turn an approved spec into a plan.
-
-**Spec:** ${specPath}
-
-1. Run \`crtr mode plan new -h\` to load the planning workflow and output schema.
-2. Read the spec end-to-end.
-3. Follow the workflow from step 1 and save the plan by passing the plan markdown to \`crtr mode plan new\` on stdin.
-4. When done, submit a short markdown report on stdin:
-
-\`\`\`bash
-crtr job submit ${jobId} <<'MD'
-Plan saved at <path>. <one-line summary of the plan's shape>.
-MD
-\`\`\`
-
-If you cannot complete the plan, submit a failure with a reason:
-
-\`\`\`bash
-crtr job submit ${jobId} --status failed --reason "<why>"
-\`\`\`
-
-Begin now.`;
-}
-/**
- * First user message for a plan → implementation handoff.
- */
-export function implementHandoffPrompt(planPath, jobId) {
-    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}
-
-## Phase 1: Read
-
-1. Read the plan end-to-end. If it references a spec, read that too.
-2. Read the files the plan names under "Files to modify / create" 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
-
-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 and submit
-
-When all tasks complete and verification passes, submit a markdown report on stdin:
-
-\`\`\`bash
-crtr job submit ${jobId} <<'MD'
-**Summary:** <one-line summary of files touched>
-
-<optional further notes — verification output, surprises, callouts>
-MD
-\`\`\`
-
-If implementation fails, submit a failure with a reason:
-\`\`\`bash
-crtr job submit ${jobId} --status failed --reason "<why>"
-\`\`\`
-
-## 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.**
-
-Begin by reading the plan.`;
-}
-/**
- * First user message for a reviewer agent.
- * The reviewer submits via `crtr job submit` rather than `crtr agent submit`.
- */
-export function reviewerHandoffPrompt(artifactPath, artifactKind, specPath, jobId) {
-    const reviewBody = artifactKind === 'spec'
-        ? specReviewPrompt(artifactPath)
-        : planReviewPrompt(artifactPath, specPath);
-    const patched = reviewBody.replace('__CRTR_SUBMIT_INSTRUCTION__', `the submit command injected below. Pipe your full review markdown on stdin. The \`--kill-pane\` flag closes this reviewer pane after submission — keep it, do not drop it.\n\n\`\`\`bash\ncrtr job submit ${jobId} --kill-pane <<'MD'\n<your full review markdown — the same Status/Issues/Recommendations block you composed above>\nMD\n\`\`\`\n\nIf the artifact is too malformed to review, submit a failure instead:\n\n\`\`\`bash\ncrtr job submit ${jobId} --status failed --reason "<why>" --kill-pane\n\`\`\``);
-    return `${patched}
-
-After calling \`crtr job submit\`, your turn ends and the pane closes itself. Do NOT chat or summarize after submission.`;
-}
-/**
- * First user message for a general `agent new` worker.
- *
- * The worker runs as an interactive agent in a tmux pane (not print mode), so
- * its stdout is NOT captured as the result — it must deliver its answer via
- * `crtr job submit`, exactly like the mode-handoff workers. The original task
- * is sent verbatim; the submit contract is appended after a separator.
- */
-export function agentNewPrompt(task, jobId) {
-    return `${task}
-
----
-
-When you have finished the task above, deliver your final answer by piping your
-full markdown result to \`crtr job submit\` — this is how the result is returned
-to whoever spawned you:
-
-\`\`\`bash
-crtr job submit ${jobId} <<'MD'
-<your complete answer / findings>
-MD
-\`\`\`
-
-If you cannot complete the task, submit a failure with a reason instead:
-
-\`\`\`bash
-crtr job submit ${jobId} --status failed --reason "<why>"
-\`\`\`
-
-Do your work first; submit exactly once when done. After submitting, your turn ends.`;
-}

package/dist/prompts/debug.d.ts

@@ -1,8 +0,0 @@
-/**
- * First user message for a reproduction-only debug handoff.
- *
- * The agent's sole job is ONE failing integration test that reproduces the
- * reported bug. It never fixes the bug. Symmetric with the agent.ts handoff
- * builders: thin prompt, exact submit contract, turn ends after submit.
- */
-export declare function reproHandoffPrompt(issue: string, jobId: string): string;

package/dist/prompts/debug.js

@@ -1,44 +0,0 @@
-/**
- * First user message for a reproduction-only debug handoff.
- *
- * The agent's sole job is ONE failing integration test that reproduces the
- * reported bug. It never fixes the bug. Symmetric with the agent.ts handoff
- * builders: thin prompt, exact submit contract, turn ends after submit.
- */
-export function reproHandoffPrompt(issue, jobId) {
-    return `You were spawned solely to write ONE integration test that fails *because of this bug*:
-
-${issue}
-
-Rules — follow exactly:
-
-- Do NOT fix the bug. Do NOT modify product code to make a test pass. Your only output is a test.
-- The test must fail against the current code, and the failure must BE the reported bug — not an import error, a typo, or an unrelated assertion. Run it; paste the real failing output; confirm the failure mode matches the issue.
-- Prefer an integration test against real dependencies. Mocking away the broken component is theater and does NOT count as reproduction.
-- If you cannot produce a faithful failing test, GIVE UP. Never weaken assertions, hardcode expected values, or fabricate a clean-looking run — a tautological or over-mocked test is worse than none.
-
-Submit exactly one of the following via \`crtr job submit\`, then your turn ends — do not chat:
-
-Reproduced (markdown body on stdin):
-\`\`\`bash
-crtr job submit ${jobId} <<'MD'
-**Reproduces:** yes
-
-**Test path:** <path>
-
-**Test command:** \`<exact cmd>\`
-
-**Failure output:**
-\`\`\`
-<pasted failing output>
-\`\`\`
-MD
-\`\`\`
-
-Gave up (no faithful repro achievable):
-\`\`\`bash
-crtr job submit ${jobId} --status failed --reason "<why a faithful repro was not achievable>"
-\`\`\`
-
-Begin now.`;
-}