cclaw-cli 0.11.0 → 0.12.0

package/README.md

@@ -41,7 +41,7 @@ sequenceDiagram
 - **Low cognitive load:** one canonical stage flow instead of dozens of competing paths.
 - **Installer-first architecture:** generates files and hooks; does not run a hidden control plane.
 - **Hard-gated quality:** each stage has non-skippable constraints that reduce AI drift.
-- **Cross-harness parity:** same behavior model across Claude Code, Cursor, Codex, OpenCode.
+- **Tiered harness coverage:** transparent capability tiers across Claude Code, Cursor, Codex, OpenCode.
 - **Compounding context:** flow state + project knowledge get rehydrated on new sessions automatically.
 - **Incremental delivery:** active artifacts stay in one place; `cclaw archive` snapshots completed features into dated run folders.
 
@@ -114,16 +114,17 @@ Required repository secret:
 ├── commands/
 ├── hooks/
 ├── templates/
+├── references/
 ├── artifacts/                # active feature artifacts
 ├── state/
-├── knowledge.md              # append-only rule/pattern/lesson log
+├── knowledge.jsonl           # append-only strict-schema rule/pattern/lesson log
 └── runs/                     # archived feature snapshots (YYYY-MM-DD-feature-name)
 ```
 
 ## Harness Integration
 
 Supported harnesses: `claude`, `cursor`, `opencode`, `codex`. The full
-per-harness install surface, feature matrix, and lifecycle details live in
+per-harness tier/capability matrix, install surface, and lifecycle details live in
 [docs/harnesses.md](./docs/harnesses.md).
 
 ## License

package/dist/cli.d.ts

@@ -6,7 +6,13 @@ interface ParsedArgs {
     harnesses?: HarnessId[];
     track?: FlowTrack;
     profile?: InitProfile;
+    dryRun?: boolean;
+    interactive?: boolean;
     reconcileGates?: boolean;
+    doctorJson?: boolean;
+    doctorExplain?: boolean;
+    doctorQuiet?: boolean;
+    doctorOnly?: string[];
     archiveName?: string;
     showHelp?: boolean;
     showVersion?: boolean;

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { FLOW_TRACKS, HARNESS_IDS, INIT_PROFILES } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
@@ -9,6 +10,9 @@ import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
 import { RUNTIME_ROOT } from "./constants.js";
+import { createDefaultConfig, createProfileConfig } from "./config.js";
+import { detectHarnesses } from "./init-detect.js";
+import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
 export function usage() {
     return `cclaw - installer-first flow toolkit
@@ -22,10 +26,17 @@ Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
              Flags: --profile=<id>      Pre-fill defaults. One of: minimal | standard | full. Default: standard.
                     --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex). Overrides the profile default.
-                    --track=<id>        Flow track for new runs (standard | quick). Overrides the profile default.
+                    --track=<id>        Flow track for new runs (standard | medium | quick). Overrides the profile default.
+                    --interactive       Force interactive prompts (TTY only).
+                    --no-interactive    Skip interactive prompts even on TTY.
+                    --dry-run           Print resolved config + generated surfaces without writing files.
   sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
-  doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
+  doctor     Run health checks against the local .cclaw runtime. Exit code 2 when any error-severity check fails.
              Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
+                    --json              Emit machine-readable JSON output.
+                    --only=<filter>     Comma list of severities/check-name filters (error,warning,info,trace:,hook:...).
+                    --explain           Include fix + doc reference per check in text mode.
+                    --quiet             Print only failing checks (and totals).
   archive    Move .cclaw/artifacts into .cclaw/runs/<date>-<slug> and reset flow state.
              Flags: --name=<feature>    Feature slug (default: inferred from 00-idea.md).
   upgrade    Refresh generated files in .cclaw without modifying user artifacts.
@@ -94,6 +105,208 @@ function parseProfile(raw) {
     }
     return trimmed;
 }
+function isInitPromptAllowed(ctx) {
+    return Boolean(process.stdin.isTTY && ctx.stdout.isTTY);
+}
+function buildInitSurfacePreview(harnesses) {
+    const lines = [
+        ".cclaw/config.yaml",
+        ".cclaw/commands/*.md",
+        ".cclaw/skills/*/SKILL.md",
+        ".cclaw/state/*.json|*.jsonl",
+        ".cclaw/references/**",
+        "AGENTS.md (managed block)"
+    ];
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        lines.push(`${adapter.commandDir}/cc*.md`);
+        if (harness === "claude") {
+            lines.push(".claude/hooks/hooks.json");
+        }
+        if (harness === "cursor") {
+            lines.push(".cursor/hooks.json");
+            lines.push(".cursor/rules/cclaw-workflow.mdc");
+        }
+        if (harness === "codex") {
+            lines.push(".codex/hooks.json");
+        }
+        if (harness === "opencode") {
+            lines.push(".opencode/plugins/cclaw-plugin.mjs");
+            lines.push("opencode.json(.c) plugin registration");
+        }
+    }
+    return lines;
+}
+function inferTrackDefault(profile, track) {
+    if (track)
+        return track;
+    if (!profile)
+        return "standard";
+    return createProfileConfig(profile).defaultTrack ?? "standard";
+}
+async function promptInitConfig(defaults, ctx) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: ctx.stdout
+    });
+    const pickSingle = async (label, options, fallback) => {
+        while (true) {
+            ctx.stdout.write(`\n${label}\n`);
+            options.forEach((option, index) => {
+                const marker = option === fallback ? " (default)" : "";
+                ctx.stdout.write(`  ${index + 1}) ${option}${marker}\n`);
+            });
+            const answer = (await rl.question("> ")).trim();
+            if (answer.length === 0) {
+                return fallback;
+            }
+            const numeric = Number(answer);
+            if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length) {
+                return options[numeric - 1];
+            }
+            if (options.includes(answer)) {
+                return answer;
+            }
+            ctx.stdout.write("Invalid selection. Use option number or value.\n");
+        }
+    };
+    const pickHarnesses = async (fallback) => {
+        const fallbackText = fallback.join(",");
+        while (true) {
+            const answer = (await rl.question(`\nHarnesses (comma list from ${HARNESS_IDS.join(", ")}) [${fallbackText}]: `)).trim();
+            if (answer.length === 0) {
+                return fallback;
+            }
+            try {
+                const parsed = parseHarnesses(answer);
+                if (parsed.length === 0) {
+                    ctx.stdout.write("Select at least one harness.\n");
+                    continue;
+                }
+                return parsed;
+            }
+            catch (err) {
+                ctx.stdout.write(`${err instanceof Error ? err.message : "Invalid harness list"}\n`);
+            }
+        }
+    };
+    try {
+        const profile = await pickSingle("Select init profile:", INIT_PROFILES, defaults.profile);
+        const trackDefault = inferTrackDefault(profile, defaults.track);
+        const track = await pickSingle("Select default flow track:", FLOW_TRACKS, trackDefault);
+        const harnesses = await pickHarnesses(defaults.harnesses);
+        return { profile, track, harnesses };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function resolveInitInputs(parsed, ctx) {
+    const detectedHarnesses = parsed.harnesses ? [] : await detectHarnesses(ctx.cwd);
+    const autoHarnesses = parsed.harnesses
+        ? parsed.harnesses
+        : (detectedHarnesses.length > 0 ? detectedHarnesses : undefined);
+    const promptRequested = parsed.interactive === true;
+    const promptForbidden = parsed.interactive === false;
+    const implicitPrompt = !promptForbidden &&
+        isInitPromptAllowed(ctx) &&
+        parsed.profile === undefined &&
+        parsed.track === undefined &&
+        parsed.harnesses === undefined;
+    const shouldPrompt = promptRequested || implicitPrompt;
+    if (!shouldPrompt) {
+        return {
+            profile: parsed.profile,
+            track: parsed.track,
+            harnesses: autoHarnesses,
+            detectedHarnesses
+        };
+    }
+    if (!isInitPromptAllowed(ctx)) {
+        throw new Error("Interactive init requires a TTY. Remove --interactive or run in a terminal.");
+    }
+    const defaults = {
+        profile: parsed.profile ?? "standard",
+        track: inferTrackDefault(parsed.profile, parsed.track),
+        harnesses: autoHarnesses ?? HARNESS_IDS.slice()
+    };
+    const prompted = await promptInitConfig(defaults, ctx);
+    return {
+        profile: prompted.profile,
+        track: prompted.track,
+        harnesses: prompted.harnesses,
+        detectedHarnesses
+    };
+}
+function parseDoctorOnly(raw) {
+    return raw
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter((item) => item.length > 0);
+}
+function filterDoctorChecks(checks, filters) {
+    if (!filters || filters.length === 0) {
+        return checks;
+    }
+    return checks.filter((check) => {
+        const name = check.name.toLowerCase();
+        return filters.some((filter) => {
+            if (filter === "error" || filter === "warning" || filter === "info") {
+                return check.severity === filter;
+            }
+            return name.includes(filter);
+        });
+    });
+}
+function doctorCountsBySeverity(checks) {
+    const result = {
+        error: { total: 0, failing: 0 },
+        warning: { total: 0, failing: 0 },
+        info: { total: 0, failing: 0 }
+    };
+    for (const check of checks) {
+        const bucket = result[check.severity];
+        bucket.total += 1;
+        if (!check.ok) {
+            bucket.failing += 1;
+        }
+    }
+    return result;
+}
+function printDoctorText(ctx, checks, options) {
+    const orderedSeverities = ["error", "warning", "info"];
+    const view = options.quiet ? checks.filter((check) => !check.ok) : checks;
+    for (const severity of orderedSeverities) {
+        const inBucket = view.filter((check) => check.severity === severity);
+        if (inBucket.length === 0)
+            continue;
+        ctx.stdout.write(`\n[${severity.toUpperCase()}]\n`);
+        for (const check of inBucket) {
+            const status = check.ok ? "PASS" : "FAIL";
+            ctx.stdout.write(`${status} ${check.name} :: ${check.summary}\n`);
+            if (!options.quiet) {
+                ctx.stdout.write(`  details: ${check.details}\n`);
+            }
+            if (options.explain) {
+                ctx.stdout.write(`  fix: ${check.fix}\n`);
+                if (check.docRef) {
+                    ctx.stdout.write(`  docs: ${check.docRef}\n`);
+                }
+            }
+        }
+    }
+    const counts = doctorCountsBySeverity(checks);
+    const failingErrors = checks.filter((check) => check.severity === "error" && !check.ok).length;
+    ctx.stdout.write(`\nTotals: error ${counts.error.failing}/${counts.error.total} failing, ` +
+        `warning ${counts.warning.failing}/${counts.warning.total} failing, ` +
+        `info ${counts.info.failing}/${counts.info.total} failing\n`);
+    if (failingErrors > 0) {
+        ctx.stdout.write(`Doctor status: BLOCKED (${failingErrors} failing error checks)\n`);
+    }
+    else {
+        ctx.stdout.write("Doctor status: HEALTHY (no failing error checks)\n");
+    }
+}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -121,10 +334,38 @@ function parseArgs(argv) {
             parsed.profile = parseProfile(flag.replace("--profile=", ""));
             continue;
         }
+        if (flag === "--interactive") {
+            parsed.interactive = true;
+            continue;
+        }
+        if (flag === "--no-interactive") {
+            parsed.interactive = false;
+            continue;
+        }
+        if (flag === "--dry-run") {
+            parsed.dryRun = true;
+            continue;
+        }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
             continue;
         }
+        if (flag === "--json") {
+            parsed.doctorJson = true;
+            continue;
+        }
+        if (flag === "--explain") {
+            parsed.doctorExplain = true;
+            continue;
+        }
+        if (flag === "--quiet") {
+            parsed.doctorQuiet = true;
+            continue;
+        }
+        if (flag.startsWith("--only=")) {
+            parsed.doctorOnly = parseDoctorOnly(flag.replace("--only=", ""));
+            continue;
+        }
         if (flag.startsWith("--name=")) {
             parsed.archiveName = flag.replace("--name=", "").trim();
         }
@@ -146,14 +387,44 @@ async function runCommand(parsed, ctx) {
         return 1;
     }
     if (command === "init") {
+        const resolved = await resolveInitInputs(parsed, ctx);
+        const effectiveProfile = resolved.profile;
+        const effectiveTrack = resolved.track;
+        const effectiveHarnesses = resolved.harnesses;
+        if (parsed.dryRun === true) {
+            const previewConfig = effectiveProfile
+                ? createProfileConfig(effectiveProfile, {
+                    harnesses: effectiveHarnesses,
+                    defaultTrack: effectiveTrack
+                })
+                : createDefaultConfig(effectiveHarnesses, effectiveTrack);
+            const previewSurfaces = buildInitSurfacePreview(previewConfig.harnesses);
+            info(ctx, "Dry run: no files were written.");
+            if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
+                info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
+            }
+            ctx.stdout.write(`${JSON.stringify({
+                profile: effectiveProfile ?? "standard(default)",
+                track: previewConfig.defaultTrack ?? "standard",
+                harnesses: previewConfig.harnesses,
+                promptGuardMode: previewConfig.promptGuardMode,
+                gitHookGuards: previewConfig.gitHookGuards,
+                languageRulePacks: previewConfig.languageRulePacks,
+                generatedSurfaces: previewSurfaces
+            }, null, 2)}\n`);
+            return 0;
+        }
         await initCclaw({
             projectRoot: ctx.cwd,
-            harnesses: parsed.harnesses,
-            track: parsed.track,
-            profile: parsed.profile
+            harnesses: effectiveHarnesses,
+            track: effectiveTrack,
+            profile: effectiveProfile
         });
-        const profileNote = parsed.profile ? ` profile=${parsed.profile}` : "";
-        const trackNote = parsed.track ? ` track=${parsed.track}` : "";
+        if (resolved.detectedHarnesses.length > 0 && parsed.harnesses === undefined) {
+            info(ctx, `Detected harnesses from repo: ${resolved.detectedHarnesses.join(", ")}`);
+        }
+        const profileNote = effectiveProfile ? ` profile=${effectiveProfile}` : "";
+        const trackNote = effectiveTrack ? ` track=${effectiveTrack}` : "";
         const suffix = profileNote || trackNote ? ` (${(profileNote + trackNote).trim()})` : "";
         info(ctx, `Initialized .cclaw runtime and generated harness shims${suffix}`);
         return 0;
@@ -167,8 +438,25 @@ async function runCommand(parsed, ctx) {
         const checks = await doctorChecks(ctx.cwd, {
             reconcileCurrentStageGates: parsed.reconcileGates === true
         });
-        for (const check of checks) {
-            ctx.stdout.write(`${check.ok ? "PASS" : "FAIL"} ${check.name} :: ${check.details}\n`);
+        const filteredChecks = filterDoctorChecks(checks, parsed.doctorOnly);
+        const explain = parsed.doctorExplain === true;
+        const quiet = parsed.doctorQuiet === true;
+        if (parsed.doctorJson === true) {
+            const counts = doctorCountsBySeverity(filteredChecks);
+            ctx.stdout.write(`${JSON.stringify({
+                ok: doctorSucceeded(checks),
+                filters: parsed.doctorOnly ?? [],
+                counts,
+                checks: filteredChecks
+            }, null, 2)}\n`);
+        }
+        else {
+            if (filteredChecks.length === 0) {
+                ctx.stdout.write("No checks matched the --only filter.\n");
+            }
+            else {
+                printDoctorText(ctx, filteredChecks, { explain, quiet });
+            }
         }
         return doctorSucceeded(checks) ? 0 : 2;
     }

package/dist/content/core-agents.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agent persona content for cclaw.
+ *
+ * cclaw materializes markdown agent definitions (`.md` with YAML frontmatter)
+ * under `.cclaw/agents/` for harness delegation. Research work that does not
+ * need isolated subagent context lives in `.cclaw/skills/research/*.md`
+ * playbooks and is executed in-thread by the primary agent.
+ */
+export interface AgentDefinition {
+    /** Kebab-case identifier, e.g. `"reviewer"`. */
+    name: string;
+    /** When to invoke — include PROACTIVE / MUST BE USED guidance. */
+    description: string;
+    /** Allowed tools for this agent (harness-specific names). */
+    tools: string[];
+    /** Model tier for routing cost/latency vs depth. */
+    model: "fast" | "balanced" | "deep";
+    /** How the harness should treat activation relative to flow context. */
+    activation: "proactive" | "on-demand" | "mandatory";
+    /** cclaw flow stages this agent is designed to support. */
+    relatedStages: string[];
+    /** Markdown body rendered below the YAML frontmatter. */
+    body: string;
+}
+/**
+ * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ */
+export declare const CCLAW_AGENTS: AgentDefinition[];
+/**
+ * Render a complete cclaw agent markdown file (YAML frontmatter + body).
+ */
+export declare function agentMarkdown(agent: AgentDefinition): string;
+/**
+ * Markdown table mapping cclaw stage entry points to specialist agents.
+ */
+export declare function agentRoutingTable(): string;
+/**
+ * Cost tier routing for the core-5 agent roster.
+ */
+export declare function agentCostTierTable(): string;
+/**
+ * AGENTS.md-ready section describing cclaw’s specialist delegation model.
+ */
+export declare function agentsAgentsMdBlock(): string;

package/dist/content/core-agents.js

@@ -0,0 +1,225 @@
+/**
+ * Agent persona content for cclaw.
+ *
+ * cclaw materializes markdown agent definitions (`.md` with YAML frontmatter)
+ * under `.cclaw/agents/` for harness delegation. Research work that does not
+ * need isolated subagent context lives in `.cclaw/skills/research/*.md`
+ * playbooks and is executed in-thread by the primary agent.
+ */
+function yamlScalarString(value) {
+    // JSON double-quoted strings are valid YAML scalars and escape reliably.
+    return JSON.stringify(value);
+}
+function yamlFlowSequence(values) {
+    return JSON.stringify(values);
+}
+/**
+ * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ */
+export const CCLAW_AGENTS = [
+    {
+        name: "planner",
+        description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "mandatory",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        body: [
+            "You are an **implementation planning specialist** (staff engineer mindset).",
+            "",
+            "When invoked:",
+            "1. Analyze scope and break it into concrete sub-problems.",
+            "2. Map each sub-problem to existing modules and reusable code.",
+            "3. Produce an ordered execution plan with dependencies and checks.",
+            "4. Highlight risks and unknowns that need user decisions.",
+            "",
+            "**Role boundary:** planning only. Do NOT write production code."
+        ].join("\n")
+    },
+    {
+        name: "reviewer",
+        description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["spec", "review", "ship"],
+        body: [
+            "You are a **combined spec + code reviewer**.",
+            "",
+            "Run two explicit passes:",
+            "",
+            "1. **Spec pass**",
+            "   - For each acceptance criterion: PASS / PARTIAL / FAIL.",
+            "   - Cite evidence as `file:line`.",
+            "",
+            "2. **Code-quality pass**",
+            "   - Correctness: logic, boundaries, state transitions.",
+            "   - Maintainability: naming, structure, complexity, debt risks.",
+            "   - Performance: avoid obvious hot-path regressions.",
+            "   - Architecture fit: layering and contract stability.",
+            "",
+            "For each finding include:",
+            "- Severity: `Critical` | `Important` | `Suggestion`",
+            "- Location: `file:line`",
+            "- Problem and concrete recommendation",
+            "",
+            "**Trust model:** never rely on implementer claims; verify by reading code."
+        ].join("\n")
+    },
+    {
+        name: "security-reviewer",
+        description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["design", "review", "ship"],
+        body: [
+            "You are a **security vulnerability specialist** focused on exploitability.",
+            "",
+            "Check for (non-exhaustive):",
+            "- validation gaps and injection vectors",
+            "- authz/authn boundary violations",
+            "- secret leakage in code/logging",
+            "- unsafe file/system/network operations",
+            "- privilege escalation and trust-boundary misuse",
+            "",
+            "For each finding include:",
+            "- severity aligned to ship risk",
+            "- CWE ID when possible (or UNKNOWN)",
+            "- short proof-of-concept vector",
+            "- concrete control-oriented fix"
+        ].join("\n")
+    },
+    {
+        name: "test-author",
+        description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["tdd"],
+        body: [
+            "You are a **test-driven development** specialist.",
+            "",
+            "**Iron law:** no production code without a failing test first.",
+            "",
+            "Process:",
+            "1. RED: write a failing test for the desired behavior.",
+            "2. Verify RED fails for the right reason.",
+            "3. GREEN: implement minimal code to pass.",
+            "4. Verify GREEN on relevant suite/full suite.",
+            "5. REFACTOR with behavior preserved."
+        ].join("\n")
+    },
+    {
+        name: "doc-updater",
+        description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "mandatory",
+        relatedStages: ["tdd", "ship"],
+        body: [
+            "You are a **documentation maintenance specialist**.",
+            "",
+            "After code changes, verify and update only stale sections in:",
+            "- README / setup / usage",
+            "- API docs and examples",
+            "- migration and operational notes",
+            "",
+            "Preserve existing tone and structure; avoid rewrites for style alone."
+        ].join("\n")
+    }
+];
+import { enhancedAgentBody } from "./subagents.js";
+/**
+ * Render a complete cclaw agent markdown file (YAML frontmatter + body).
+ */
+export function agentMarkdown(agent) {
+    const frontmatter = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${yamlScalarString(agent.description)}`,
+        `tools: ${yamlFlowSequence(agent.tools)}`,
+        `model: ${agent.model}`,
+        "---"
+    ].join("\n");
+    const relatedStages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "(none)";
+    const taskDelegation = enhancedAgentBody(agent.name);
+    return `${frontmatter}
+
+# ${agent.name}
+
+${agent.body}
+
+## Activation
+
+- Mode: ${agent.activation}
+- Related stages: ${relatedStages}
+
+## Rules
+
+- Cite file:line for every finding
+- Do not make changes outside your specialist domain
+- Report findings with severity classification
+- If uncertain, say "UNKNOWN" - never guess
+
+${taskDelegation}
+`;
+}
+/**
+ * Markdown table mapping cclaw stage entry points to specialist agents.
+ */
+export function agentRoutingTable() {
+    return `| Stage Entry | Primary Agent(s) | Supporting guidance |
+|---|---|---|
+| Brainstorm (start with \`/cc <idea>\`) | planner | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
+| Scope / Design / Plan (via \`/cc-next\`) | planner | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
+| Spec (via \`/cc-next\`) | reviewer | planner (if ambiguity or conflicts remain) |
+| TDD (via \`/cc-next\`) | test-author | doc-updater on public behavior/config changes |
+| Review (via \`/cc-next\`) | reviewer, security-reviewer | conditional second reviewer for high blast-radius diffs |
+| Ship (via \`/cc-next\`) | doc-updater | security-reviewer when release risk is elevated |
+`;
+}
+/**
+ * Cost tier routing for the core-5 agent roster.
+ */
+export function agentCostTierTable() {
+    return `| Tier | Use for | Example agents |
+|---|---|---|
+| \`deep\` | one heavy planning pass per stage | planner |
+| \`balanced\` | review and TDD specialists with stronger reasoning depth | reviewer, security-reviewer, test-author |
+| \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
+`;
+}
+/**
+ * AGENTS.md-ready section describing cclaw’s specialist delegation model.
+ */
+export function agentsAgentsMdBlock() {
+    return `### Agent Specialists
+
+cclaw materializes **5 core specialist agents** under \`.cclaw/agents/\`.
+
+${agentRoutingTable()}
+
+### Research Playbooks (in-thread)
+
+Research work is no longer modeled as standalone personas. Use in-thread playbooks under \`.cclaw/skills/research/\`:
+
+- \`repo-scan.md\`
+- \`learnings-lookup.md\`
+- \`framework-docs-lookup.md\`
+- \`best-practices-lookup.md\`
+- \`git-history.md\`
+
+### Activation modes
+
+- **Mandatory:** planner (scope/design/plan), reviewer + security-reviewer (review), test-author (tdd), doc-updater (ship).
+- **Proactive:** planner on ambiguity, security-reviewer on trust-boundary movement outside review, doc-updater on behavior/config drift.
+- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.
+
+### Cost-aware routing
+
+${agentCostTierTable()}
+
+**Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.
+`;
+}

package/dist/content/doctor-references.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCTOR_REFERENCE_DIR = ".cclaw/references/doctor";
+export declare const DOCTOR_REFERENCE_MARKDOWN: Record<string, string>;