cclaw-cli 7.7.0 → 8.1.0

package/dist/content/core-agents.js

@@ -1,782 +1,55 @@
-import { conversationLanguagePolicyBullets } from "./language-policy.js";
-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);
-}
-const WORKER_RETURN_SCHEMA = {
-    statusField: "status",
-    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
-    requiredFields: ["status", "filesChanged", "testsRun", "evidenceRefs", "concerns", "needsContext", "blockers"],
-    evidenceFields: ["testsRun", "evidenceRefs"]
-};
-const REVIEW_RETURN_SCHEMA = {
-    statusField: "status",
-    allowedStatuses: ["PASS", "PASS_WITH_GAPS", "FAIL", "BLOCKED"],
-    requiredFields: ["status", "findings", "criteria", "evidenceRefs", "blockers"],
-    evidenceFields: ["findings.location", "criteria.evidence", "evidenceRefs"]
-};
-const ADVISORY_RETURN_SCHEMA = {
-    statusField: "status",
-    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
-    requiredFields: ["status", "summary", "recommendations", "evidenceRefs", "unknowns"],
-    evidenceFields: ["evidenceRefs", "recommendations"]
-};
-const CRITIC_ADVISORY_RETURN_SCHEMA = {
-    ...ADVISORY_RETURN_SCHEMA,
-    optionalFields: ["predictions", "predictionsValidated", "openQuestions", "realistCheckResults"]
-};
-const DOC_RETURN_SCHEMA = {
-    statusField: "status",
-    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
-    requiredFields: ["status", "filesUpdated", "summary", "evidenceRefs", "openQuestions"],
-    evidenceFields: ["filesUpdated", "evidenceRefs"]
-};
-function workerAckContract() {
-    return `## Worker ACK Contract
-
-Before doing substantive work, return an ACK object that the parent can record:
-
-\`\`\`json
-{
-  "status": "ACK",
-  "spanId": "<parent spanId>",
-  "dispatchId": "<parent dispatchId or workerRunId>",
-  "dispatchSurface": "claude-task|cursor-task|opencode-agent|codex-agent|generic-task|role-switch",
-  "agentDefinitionPath": ".cclaw/agents/<agent>.md or harness generated path",
-  "ackTs": "<ISO timestamp>"
-}
-\`\`\`
-
-Finish with the required return schema plus the same \`spanId\` and \`dispatchId\`. The parent must not claim isolated completion unless ACK/result proof matches the ledger/event span.`;
-}
-/**
- * TDD worker self-record contract. The parent records `scheduled` and
- * `launched` rows BEFORE dispatching the Task; the worker records
- * `acknowledged` (on entry) and `completed` (on exit).
- */
-function tddWorkerSelfRecordContract(agentName) {
-    const isBuilder = agentName === "slice-builder";
-    const refactorOutcomeFlag = isBuilder
-        ? " --refactor-outcome=inline|deferred [--refactor-rationale=\"<why>\"]"
-        : "";
-    const laneFlags = isBuilder
-        ? " [--claim-token=<t>] [--lane-id=<lane>] [--lease-until=<iso>]"
-        : "";
-    return `## TDD worker delegation self-record contract
-
-You are a TDD worker dispatched via \`Task\`. The parent already wrote your \`scheduled\` and \`launched\` ledger rows BEFORE invoking you. **Your responsibility is to self-record \`acknowledged\` on entry and \`completed\` on exit** by invoking \`.cclaw/hooks/delegation-record.mjs\` directly. Do NOT skip these — the controller depends on them, the linter validates them, and back-fill via \`--repair\` is reserved for recovery only.
-
-**On entry — record acknowledgement (BEFORE doing work):**
-
-\`\`\`bash
-ACK_TS="$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%SZ)"
-node .cclaw/hooks/delegation-record.mjs \\
-  --stage=tdd --agent=${agentName} --mode=mandatory \\
-  --status=acknowledged \\
-  --span-id=<spanId from controller dispatch> \\
-  --dispatch-id=<dispatchId from controller dispatch> \\
-  --dispatch-surface=<surface from controller dispatch> \\
-  --agent-definition-path=.cclaw/agents/${agentName}.md \\
-  --ack-ts="$ACK_TS" \\
-  --json
-\`\`\`
-
-**On exit — record completion (AFTER work + verification):**
-
-\`\`\`bash
-COMPLETED_TS="$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%SZ)"
-node .cclaw/hooks/delegation-record.mjs \\
-  --stage=tdd --agent=${agentName} --mode=mandatory \\
-  --status=completed \\
-  --span-id=<same spanId> \\
-  --completed-ts="$COMPLETED_TS" \\
-  --evidence-ref="<test-path-or-artifact-ref>"${refactorOutcomeFlag}${laneFlags} \\
-  --json
-\`\`\`
-
-Reuse the same \`<spanId>\` and \`<dispatchId>\` across both rows. **GREEN evidence freshness** (slice-builder): the FIRST \`--evidence-ref\` MUST (1) reference the same test the matching \`phase=red\` row cited (basename/stem substring; reject \`green_evidence_red_test_mismatch\`), (2) include a recognized passing-runner line such as \`=> N passed; 0 failed\`, \`N passed in 0.42s\`, or \`ok pkg 0.12s\` (reject \`green_evidence_passing_assertion_missing\`), AND (3) be captured AFTER \`ackTs\` of this span — \`completedTs - ackTs\` must be ≥ \`flow-state.json::tddGreenMinElapsedMs\` (default 4000ms; reject \`green_evidence_too_fresh\`). Escape clause for legitimate observational GREEN: pass \`--green-mode=observational\`. \`--ack-ts\` and \`--completed-ts\` must be monotonic on the span (\`startTs ≤ launchedTs ≤ ackTs ≤ completedTs\`); the helper rejects out-of-order writes with \`delegation_timestamp_non_monotonic\`. If the helper rejects with \`dispatch_active_span_collision\` against a stale span, surface the conflicting \`spanId\` to the parent — do NOT silently retry with \`--allow-parallel\`.`;
-}
-function formatReturnSchema(schema) {
-    const lines = [
-        `- Status field: \`${schema.statusField}\``,
-        `- Allowed statuses: ${schema.allowedStatuses.map((status) => `\`${status}\``).join(", ")}`,
-        `- Required fields: ${schema.requiredFields.map((field) => `\`${field}\``).join(", ")}`,
-        `- Evidence fields: ${schema.evidenceFields.map((field) => `\`${field}\``).join(", ")}`
-    ];
-    if (schema.optionalFields && schema.optionalFields.length > 0) {
-        lines.push(`- Optional fields: ${schema.optionalFields.map((field) => `\`${field}\``).join(", ")}`);
-    }
-    return lines.join("\n");
-}
-function formattedAgentsForStages(stages) {
-    const summary = stageDelegationSummary("standard");
-    const merged = [];
-    for (const stage of stages) {
-        const row = summary.find((item) => item.stage === stage);
-        if (!row)
-            continue;
-        for (const agent of row.primaryAgents) {
-            if (!merged.includes(agent)) {
-                merged.push(agent);
-            }
-        }
-    }
-    return merged.length > 0 ? merged.join(", ") : "none";
-}
-function activationModeSummary() {
-    const summary = stageDelegationSummary("standard");
-    const mandatory = new Set();
-    const proactive = new Set();
-    for (const row of summary) {
-        for (const agent of row.mandatoryAgents) {
-            mandatory.add(agent);
-        }
-        for (const agent of row.proactiveAgents) {
-            proactive.add(agent);
-        }
-    }
-    return {
-        mandatory: [...mandatory].join(", "),
-        proactive: [...proactive].join(", ")
-    };
-}
-/**
- * Canonical slice-builder worker protocol text (embedded in the agent body and
- * echoed in the TDD skill block).
- */
-export function sliceBuilderProtocol() {
-    return [
-        "## slice-builder protocol",
-        "",
-        "**slice-builder** is the canonical worker for **one feature-atomic implementation unit/slice** end-to-end: **RED → GREEN → REFACTOR → inline DOC** in **one** delegated span. The unit may contain internal 2-5 minute TDD steps; do not split those into separate agents unless the parent selected `strict-micro`. Multiple slice-builder spans run in parallel only when topology is `parallel-builders` and the wave plan declares disjoint `claimedPaths`.",
-        "",
-        "### Invariants",
-        "- Produce failing RED evidence (or cite the delegated RED artifact) **before** production edits.",
-        "- Stay inside the slice contract: `claimedPaths`, acceptance mapping, and forbidden-change lists from the parent.",
-        "- When `tdd.isolationMode=worktree|auto`, run the slice inside the assigned worktree path (never in the shared repo root) so filesystem isolation enforces the claimed-path fence.",
-        "- When `tdd.commitMode=managed-per-slice`, do **not** hand-edit git state for slice files (no manual `git add/commit` on claimed paths). Let `.cclaw/hooks/slice-commit.mjs` own per-slice commits.",
-        "- After GREEN, refactor inline **or** record deferred refactor via the same `--refactor-outcome` mechanics the controller specifies.",
-        "- Own the prose slice summary at `<artifacts-dir>/tdd-slices/S-<id>.md` yourself.",
-        "",
-        "### Events",
-        "- Honor every `delegation-record`/`delegation-record.mjs` row shape the controller requests so artifact linters keep passing.",
-        "- The umbrella `slice-completed` row ties RED/GREEN/REFACTOR/DOC timestamps to your builder span.",
-        "",
-        "### Event → status flag table (7.6.0 — phase-event status validation)",
-        "",
-        "Phase-level granularity is only meaningful on terminal outcomes. The dispatch-level ack (no `--phase`) is the controller saying \"I see the dispatch surface back\" — it stays on `--status=acknowledged`. Phase events MUST use `--status=completed` or `--status=failed`. The hook rejects mismatches with `phase_event_requires_completed_or_failed_status` (exit 2) and prints a corrected-command hint.",
-        "",
-        "| event | --phase | --status |",
-        "|---|---|---|",
-        "| dispatch ack (controller-side) | (none) | `acknowledged` |",
-        "| RED watched-fail captured | `red` | `completed` |",
-        "| GREEN test passes | `green` | `completed` (with `--refactor-outcome=inline\\|deferred\\|...`) |",
-        "| REFACTOR landed | `refactor` | `completed` |",
-        "| DOC card landed (triggers slice-commit) | `doc` | `completed` |",
-        "| BLOCKED / unrecoverable | (any phase reached) | `failed` |",
-        "",
-        "Common slip: recording every phase event with `--status=acknowledged` (e.g. `--phase=doc --status=acknowledged`). The event row is silently dropped from terminal-phase aggregations, `slice-commit.mjs` never fires (it only triggers on `phase=doc status=completed`), and `wave-status` reports the slice as phantom-open. Recovery requires raw backfill commands. The 7.6.0 hook validator forbids this configuration up front.",
-        "",
-        "### Streaming output contract",
-        "- Emit one JSON line to stdout per completed phase: `{\"event\":\"phase-completed\",\"stage\":\"tdd\",\"sliceId\":\"S-<n>\",\"phase\":\"<red|green|refactor|refactor-deferred|doc>\",\"spanId\":\"<span>\",\"runId\":\"<run>\",\"ts\":\"<iso>\"}`.",
-        "- For `phase=green` with inline/deferred refactor folding, include `refactorOutcome.mode` in the same JSON line so live controllers can close the slice without waiting for file sync.",
-        "- If streaming is unavailable in your harness/runtime, keep writing canonical `delegation-record` rows; controller-side live mode will fall back to file-based events.",
-        "",
-        "**Role boundary:** do not widen scope, do not self-approve ship-level review, and do not recurse into other agents unless the parent explicitly directs it."
-    ].join("\n");
-}
-/**
- * Canonical specialist roster materialized under `.cclaw/agents/`.
- *
- * Declared with `satisfies` so the array retains literal `name` types for
- * downstream type-level consumers (e.g. `AgentName`), while still being
- * checked against the `AgentDefinition` shape at compile time. Do not add
- * an explicit `AgentDefinition[]` annotation here — it would widen `name`
- * to `string` and break the compile-time drift guard.
- */
-export const CCLAW_AGENTS = [
+import { SPECIALIST_PROMPTS } from "./specialist-prompts/index.js";
+export const CORE_AGENTS = [
     {
-        name: "researcher",
-        description: "PROACTIVE when context readiness, repo search, reference patterns, or external docs could change a stage decision. MUST summarize search-before-read evidence before large reads.",
-        tools: ["Read", "Grep", "Glob", "WebSearch"],
-        model: "fast",
-        activation: "proactive",
-        relatedStages: ["brainstorm", "scope", "design", "plan"],
-        returnSchema: ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are a **context readiness and research specialist**.",
-            "",
-            "When invoked:",
-            "1. Start with search/query summaries before reading large files.",
-            "2. Name provider status when known: graph/search/docs/MCP/semantic index freshness.",
-            "3. Separate observed facts from assumptions and stale or missing context.",
-            "4. Return concise evidence refs the controller can paste into stage artifacts.",
-            "",
-            "**Role boundary:** research and context synthesis only. Do NOT edit files."
-        ].join("\n")
-    },
-    {
-        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"],
-        returnSchema: ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are an **implementation planning specialist** (staff engineer mindset).",
-            "",
-            "When invoked:",
-            "1. Map upstream decisions, scope boundaries, and explicit drift before planning.",
-            "2. Break the work into concrete sub-problems with dependencies and existing-module fit.",
-            "3. Enforce one-question discipline: ask only decision-changing questions, one at a time.",
-            "4. Produce an ordered execution plan with verification checks and handoff quality notes.",
-            "5. Highlight risks and unknowns that need user decisions.",
-            "",
-            "**Role boundary:** planning only. Do NOT write production code."
-        ].join("\n")
-    },
-    {
-        name: "product-discovery",
-        description: "MANDATORY during brainstorm and PROACTIVE during scope when value framing or expansion strategy needs product-level discovery pressure.",
-        tools: ["Read", "Grep", "Glob", "WebSearch"],
-        model: "deep",
-        activation: "mandatory",
-        relatedStages: ["brainstorm", "scope"],
-        returnSchema: ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are a **product discovery specialist**.",
-            "",
-            "**Mode: discovery** (default)",
-            "- persona / user and job to be done",
-            "- pain or trigger",
-            "- value hypothesis and success metric",
-            "- evidence or signal strength",
-            "- why now, do-nothing consequence, and non-goals",
-            "",
-            "**Mode: strategist** (trigger when scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION)",
-            "- 10x vision and ideal outcome versus baseline scope",
-            "- concrete expansion proposals (not cosmetic variants)",
-            "- expected upside, reversibility, and trajectory impact",
-            "- explicit add/defer/skip recommendation per proposal",
-            "",
-            "For technical-maintenance work, translate these modes to operator/developer outcomes, failure-mode reduction, verification signal quality, and trajectory impact.",
-            "",
-            "**Role boundary:** frame value and trajectory fit. Do NOT choose implementation architecture."
-        ].join("\n")
-    },
-    {
-        name: "divergent-thinker",
-        description: "PROACTIVE before planner/critic convergence when brainstorm or scope needs option-space expansion and alternative framings.",
-        tools: ["Read", "Grep", "Glob", "WebSearch"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["brainstorm", "scope"],
-        returnSchema: ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are a **creative divergent-thinker** dispatched BEFORE planner/critic converge on a single path.",
-            "",
-            "Your job:",
-            "1. Generate 3-5 alternative framings of the problem.",
-            "2. Generate 3-5 alternative approaches per framing where reasonable.",
-            "3. For each option, include one-line pro/con plus reversibility flag.",
-            "4. Highlight option-space the user might not have considered.",
-            "5. Return concise structured output in `recommendations[]` for planner/critic consumption.",
-            "",
-            "Role boundary: divergence only.",
-            "- Do NOT recommend a single approach.",
-            "- Do NOT validate feasibility (feasibility-reviewer owns that).",
-            "- Do NOT critique premise validity (critic owns that).",
-            "",
-            "You are an explicit amplifier of option-space; convergence happens after you."
-        ].join("\n")
-    },
-    {
-        name: "critic",
-        description: "PROACTIVE during brainstorm/scope/design when premises, alternatives, cost, rollback, or hidden assumptions need adversarial pressure.",
-        tools: ["Read", "Grep", "Glob", "WebSearch"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["brainstorm", "scope", "design"],
-        returnSchema: CRITIC_ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are an **adversarial critic** for product and engineering decisions.",
-            "",
-            "## Why this matters",
-            "False approval is expensive: a missed flaw early can cost 10-100x more to unwind after implementation.",
-            "Anchor every concern in evidence and avoid inventing hypothetical blockers without proof.",
-            "",
-            "## Pre-commitment predictions",
-            "Before deep investigation, list your hypotheses in `predictions[]` (what you expect to find and why).",
-            "",
-            "## Multi-perspective angles",
-            "Pick context-aware angles before analysis:",
-            "- plan/spec/scope: `executor`, `stakeholder`, `skeptic`",
-            "- design/code: `security`, `operator`, `new-hire`",
-            "",
-            "## Gap analysis",
-            "Name what is missing (evidence gaps, undefined contracts, absent safeguards), not just what looks wrong.",
-            "",
-            "## Self-audit",
-            "Low-confidence concerns (confidence <=4/10) must move into `openQuestions[]` and should not block stage transition by themselves.",
-            "",
-            "## Realist check",
-            "For each Critical/Major concern, test if it would realistically ship; downgrade or suppress concerns that are not plausible in this context.",
-            "Record the result in `realistCheckResults[]`.",
-            "",
-            "## ADVERSARIAL mode escalation",
-            "Escalate to ADVERSARIAL mode when reviewers disagree, your confidence is low, or trust/security boundaries are involved.",
-            "",
-            "Return validated risks, disproven predictions in `predictionsValidated[]`, and the smallest decision-changing recommendation."
-        ].join("\n")
-    },
-    {
-        name: "architect",
-        description: "MANDATORY during design and final ship verification. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and cross-stage cohesion before release.",
-        tools: ["Read", "Grep", "Glob", "WebSearch"],
-        model: "deep",
-        activation: "mandatory",
-        relatedStages: ["design", "ship"],
-        returnSchema: ADVISORY_RETURN_SCHEMA,
-        body: [
-            "You are an **architecture validation specialist**.",
-            "",
-            "Check architecture boundaries, existing-system fit, critical paths, data/state flow, alternatives, rescue paths, and verification hooks.",
-            "Return chosen path risks, rejected alternatives, switch triggers, and required evidence before spec handoff.",
-            "At ship, perform cross-stage verification across scope/design/spec/plan/review/code and flag DRIFT_DETECTED when shipped behavior diverges from locked decisions.",
-            "",
-            "**Role boundary:** design validation only. Do NOT write implementation code."
-        ].join("\n")
-    },
-    {
-        name: "spec-validator",
-        description: "MANDATORY during standard/deep spec. MUST BE USED to validate measurable acceptance criteria, assumptions, edge cases, and testability mapping.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "mandatory",
-        relatedStages: ["spec"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **specification validation specialist**.",
-            "",
-            "For every acceptance criterion, verify it is observable, measurable, falsifiable, mapped to upstream decisions, and paired with concrete verification evidence.",
-            "Flag vague language, missing edge cases, hidden assumptions, and RED tests that cannot be expressed.",
-            "",
-            "**Role boundary:** validate the spec; do NOT write plan tasks or implementation."
-        ].join("\n")
-    },
-    {
-        name: "spec-document-reviewer",
-        description: "PROACTIVE during spec when self-review surfaces issues, subsystem boundaries feel broad, or the artifact needs a final plan-readiness pass.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["spec"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **spec document reviewer** focused on plan-readiness.",
-            "",
-            "Run a concise pass over:",
-            "- completeness of required spec sections",
-            "- consistency across acceptance criteria, assumptions, and mapping",
-            "- clarity / ambiguity / placeholder drift",
-            "- single-subsystem scope fit and YAGNI pressure",
-            "",
-            "Return `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `BLOCKED` with concrete evidence refs and minimal corrective actions.",
-            "",
-            "**Role boundary:** review the spec artifact only; do NOT write plan tasks or implementation."
-        ].join("\n")
-    },
-    {
-        name: "coherence-reviewer",
-        description: "PROACTIVE during spec/plan/design when internal consistency must be validated across sections, terminology, references, and dependency narratives.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["spec", "plan", "design"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **document coherence reviewer** focused on consistency, not quality scoring.",
-            "",
-            "Check for:",
-            "- contradictions between sections",
-            "- terminology drift (same concept named differently)",
-            "- broken internal references and forward-reference mismatches",
-            "- dependency/storyline conflicts between architecture, scope, and execution notes",
-            "",
-            "Return `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `BLOCKED` with calibrated, evidence-anchored findings.",
-            "",
-            "**Role boundary:** consistency checks only. Do NOT rewrite the document or propose architecture alternatives."
-        ].join("\n")
-    },
-    {
-        name: "scope-guardian-reviewer",
-        description: "PROACTIVE during scope/plan/design when complexity growth, scope drift, or unnecessary abstraction risk needs a dedicated challenge pass.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["scope", "plan", "design"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **scope guard reviewer** focused on minimum viable change and complexity discipline.",
-            "",
-            "Check for:",
-            "- whether the document reuses existing solutions before adding abstractions",
-            "- scope-goal alignment and minimum useful slice",
-            "- complexity smell tests (generic utilities, framework-ahead-of-need patterns, speculative layers)",
-            "- dependency ordering that can accidentally widen scope",
-            "",
-            "Return `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `BLOCKED` with concrete evidence refs and smallest corrective action.",
-            "",
-            "**Role boundary:** challenge over-scope and unnecessary complexity; do NOT replace planner/architect ownership."
-        ].join("\n")
-    },
-    {
-        name: "feasibility-reviewer",
-        description: "PROACTIVE during plan/design when resource, runtime, environment, dependency, or rollout assumptions can make the solution non-viable.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "proactive",
-        relatedStages: ["plan", "design"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **feasibility reviewer** focused on execution realism.",
-            "",
-            "Check for:",
-            "- resource/time assumptions versus current constraints",
-            "- runtime and environment assumptions (infrastructure, limits, deployment shape)",
-            "- availability/reliability assumptions for external dependencies",
-            "- rollout and operational risk under real-world conditions",
-            "",
-            "Return `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `BLOCKED` with evidence and explicit risk-to-ship mapping.",
-            "",
-            "**Role boundary:** feasibility realism only; do NOT redesign architecture unless feasibility is blocked."
-        ].join("\n")
-    },
-    {
-        name: "reviewer",
-        description: "MANDATORY during review. MUST BE USED to run a two-pass audit with explicit inline lens coverage for performance, compatibility, and observability.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
-        activation: "mandatory",
-        relatedStages: ["spec", "review", "ship"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        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.",
-            "",
-            "## Lens Coverage",
-            "Performance: NO_IMPACT / FOUND_<n>",
-            "Compatibility: NO_IMPACT / FOUND_<n>",
-            "Observability: NO_IMPACT / FOUND_<n>",
-            "Security: routed to security-reviewer (always separate)",
-            "",
-            "### Companion lens skills (load on-demand, never all-at-once)",
-            "- **review-perf-lens** — load when reviewing code touching hot paths, loops over large data, network/disk I/O, render hot paths, or sub-100ms latency budgets.",
-            "- **review-compat-lens** — load when reviewing code that runs on multiple OS/runtime/browser targets, modifies shared library APIs, or changes serialized payload shapes.",
-            "- **review-observability-lens** — load when reviewing code that adds/removes logging, metrics, traces, error reporting, or audit/compliance signals.",
-            "If none of those triggers apply, do NOT load the lens skills — they are deep-dive context, not default reading.",
-            "",
-            "For each finding include:",
-            "- Severity: `Critical` | `Important` | `Suggestion`",
-            "- Location: `file:line`; if no line is possible, state the no-line reason",
-            "- Problem and concrete recommendation",
-            "",
-            "Also report files inspected, changed-file coverage, diagnostics run, dependency/version audit when relevant, and a no-finding attestation when no issues are found.",
-            "",
-            "**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"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        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",
-            "- `NO_CHANGE_ATTESTATION` or `NO_SECURITY_IMPACT` with inspected surfaces when no security finding exists"
-        ].join("\n")
+        id: "brainstormer",
+        title: "Brainstormer",
+        activation: "on-demand",
+        modes: ["frame", "scope", "alternatives"],
+        description: "Frame what/why and scope. Optional alternatives sweep when the request is ambiguous.",
+        prompt: SPECIALIST_PROMPTS.brainstormer
     },
     {
-        name: "integration-overseer",
-        description: "ON-DEMAND after TDD fan-out to verify cross-slice cohesion contract integrity, integration surfaces, and shared invariants before review handoff.",
-        tools: ["Read", "Grep", "Glob"],
-        model: "balanced",
+        id: "architect",
+        title: "Architect",
         activation: "on-demand",
-        relatedStages: ["tdd", "review"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are an **integration overseer** for TDD fan-out runs.",
-            "",
-            "You are dispatched after parallel `slice-builder` lanes complete.",
-            "",
-            "Checks:",
-            "- every integration test named in `cohesion-contract.md` passes (or has explicit gap rationale)",
-            "- naming conventions remain consistent across slices",
-            "- shared invariants stay true after fan-in",
-            "- boundary types at touchpoints match the contract",
-            "- integration between slices is executable and regression-safe",
-            "",
-            "Return `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `BLOCKED` with evidence refs and explicit integration risks.",
-            "",
-            "**Role boundary:** integration and cohesion oversight only; do NOT implement production code."
-        ].join("\n")
+        modes: ["architecture", "feasibility"],
+        description: "Architectural decisions plus feasibility against the current codebase.",
+        prompt: SPECIALIST_PROMPTS.architect
     },
     {
-        name: "release-reviewer",
-        description: "MANDATORY during ship. MUST BE USED for release readiness, rollback, finalization mode, evidence freshness, and victory detector checks.",
-        tools: ["Read", "Grep", "Glob", "Bash"],
-        model: "balanced",
-        activation: "mandatory",
-        relatedStages: ["ship"],
-        returnSchema: REVIEW_RETURN_SCHEMA,
-        body: [
-            "You are a **release readiness reviewer**.",
-            "",
-            "Verify preflight evidence, review verdict freshness, rollback trigger and steps, finalization enum, no-VCS handoff when applicable, learnings capture, and handoff completeness.",
-            "Block ship on stale evidence, unresolved criticals, missing rollback, or ambiguous finalization."
-        ].join("\n")
+        id: "planner",
+        title: "Planner",
+        activation: "on-demand",
+        modes: ["research", "work-breakdown", "topology"],
+        description: "Targeted research, work breakdown into AC, execution topology recommendation.",
+        prompt: SPECIALIST_PROMPTS.planner
     },
     {
-        name: "doc-updater",
-        description: "MANDATORY only at ship; PROACTIVE during tdd/review whenever behavior, config, or 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"],
-        returnSchema: DOC_RETURN_SCHEMA,
-        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, rollout, rollback, and operational notes",
-            "- public-surface change notes tied to actual changed files",
-            "",
-            "Preserve existing tone and structure; avoid rewrites for style alone."
-        ].join("\n")
+        id: "reviewer",
+        title: "Reviewer",
+        activation: "on-demand",
+        modes: ["code", "text-review", "integration", "release", "adversarial"],
+        description: "Multi-mode reviewer covering code, plan/spec text, integration, release readiness, and adversarial sweeps.",
+        prompt: SPECIALIST_PROMPTS.reviewer
     },
     {
-        name: "slice-builder",
-        description: "MANDATORY for delegated TDD slices. Owns RED → GREEN → REFACTOR → per-slice DOC for one feature-atomic implementation unit/slice in a single delegated span. Multiple slice-builder spans run in parallel only under `parallel-builders` topology with disjoint `claimedPaths`; `strict-micro` keeps tiny tasks separate.",
-        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
-        model: "balanced",
-        activation: "mandatory",
-        relatedStages: ["tdd"],
-        returnSchema: WORKER_RETURN_SCHEMA,
-        body: [
-            "You are **slice-builder**, the canonical vertical-slice TDD worker.",
-            "",
-            sliceBuilderProtocol(),
-            "",
-            "**Mode hints:**",
-            "- **TDD-bound (default)** — RED evidence precedes GREEN; preserve behavior across REFACTOR; document outcomes in `tdd-slices/S-<id>.md`.",
-            "- **Generic** — only when the parent explicitly disables TDD gates for quick-track breadth; bounded scope and verification still apply.",
-            "",
-            "**Role boundary:** obey the parent's phase flags (`--phase=red|green|refactor|doc`); never improvise undeclared parallelism."
-        ].join("\n")
+        id: "security-reviewer",
+        title: "Security reviewer",
+        activation: "on-demand",
+        modes: ["threat-model", "sensitive-change"],
+        description: "Threat-model + focused review of sensitive changes. Sets security_flag for compound learnings.",
+        prompt: SPECIALIST_PROMPTS["security-reviewer"]
     },
     {
-        name: "fixer",
-        description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.",
-        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
-        model: "balanced",
+        id: "slice-builder",
+        title: "Slice builder",
         activation: "on-demand",
-        relatedStages: ["review", "tdd"],
-        returnSchema: WORKER_RETURN_SCHEMA,
-        body: [
-            "You are a **fresh fixer worker** dispatched after a review found a concrete gap.",
-            "",
-            "Rules:",
-            "1. Start from the failing criterion and reviewer evidence, not from implementer claims.",
-            "2. Stay inside the allowed files and forbidden-change constraints.",
-            "3. Apply the smallest fix and rerun the relevant verification.",
-            "4. Return the strict fixer JSON schema before prose.",
-            "",
-            "**Role boundary:** fix only the cited gap; do not redesign the slice."
-        ].join("\n")
+        modes: ["build", "fix-only"],
+        description: "Implements AC slices and post-review scoped fixes. Always commits per AC via commit-helper.",
+        prompt: SPECIALIST_PROMPTS["slice-builder"]
     }
 ];
-/**
- * Agents whose rendered `.cclaw/agents/<name>.md` file gets the TDD worker
- * self-record helper template. Controllers dispatch these via `Task` during
- * TDD; they own `acknowledged` and `completed` ledger writes.
- */
-const TDD_WORKER_SELF_RECORD_AGENTS = new Set([
-    "slice-builder",
-    "integration-overseer"
-]);
-import { stageDelegationSummary } from "./stage-schema.js";
-/**
- * Render a complete cclaw agent markdown file (YAML frontmatter + body).
- */
-function defaultTaskDelegationSection(agentName) {
-    return `
-
-## Task Tool Delegation
-
-Use native Task/subagent delegation only when this agent's role requires isolated context or strict lifecycle evidence. Keep the delegation prompt self-contained and bounded to this agent's role.
-
-${agentName === "reviewer"
-        ? "- For large/high-risk diffs, load optional deep lens skills (`review-perf-lens`, `review-compat-lens`, `review-observability-lens`) before final verdict."
-        : "_No extra agent-specific delegation template is required._"}
-`;
-}
-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 = defaultTaskDelegationSection(agent.name);
-    const tddWorkerSelfRecordSection = TDD_WORKER_SELF_RECORD_AGENTS.has(agent.name)
-        ? `\n${tddWorkerSelfRecordContract(agent.name)}\n`
-        : "";
-    return `${frontmatter}
-
-# ${agent.name}
-
-${agent.body}
-
-## Activation
-
-- Mode: ${agent.activation}
-- Related stages: ${relatedStages}
-
-${workerAckContract()}
-${tddWorkerSelfRecordSection}
-## Required Return Schema
-
-STRICT_RETURN_SCHEMA: return a structured object matching this contract before any narrative when delegated. Include \`spanId\`, \`dispatchId\` or \`workerRunId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and lifecycle timestamps when provided by the parent.
-
-${formatReturnSchema(agent.returnSchema)}
-
-## Rules
-
-## Conversation Language Policy
-
-${conversationLanguagePolicyBullets()}
-- 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() {
-    const brainstormPrimary = formattedAgentsForStages(["brainstorm"]);
-    const scopeDesignPlanPrimary = formattedAgentsForStages(["scope", "design", "plan"]);
-    const specPrimary = formattedAgentsForStages(["spec"]);
-    const tddPrimary = formattedAgentsForStages(["tdd"]);
-    const reviewPrimary = formattedAgentsForStages(["review"]);
-    const shipPrimary = formattedAgentsForStages(["ship"]);
-    return `| Stage Entry | Primary Agent(s) | Supporting guidance |
-|---|---|---|
-| Brainstorm (start with \`/cc <idea>\`) | ${brainstormPrimary} | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
-| Scope / Design / Plan (via \`/cc\`) | ${scopeDesignPlanPrimary} | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
-| Spec (via \`/cc\`) | ${specPrimary} | planner (if ambiguity or conflicts remain) |
-| TDD (via \`/cc\`) | ${tddPrimary} | doc-updater on public behavior/config changes |
-| Review (via \`/cc\`) | ${reviewPrimary} | conditional second reviewer for high blast-radius diffs |
-| Ship (via \`/cc\`) | ${shipPrimary} | security-reviewer when release risk is elevated |
-`;
-}
-/**
- * Cost tier routing for the specialist agent roster.
- */
-export function agentCostTierTable() {
-    return `| Tier | Use for | Example agents |
-|---|---|---|
-| \`deep\` | one heavy planning/strategy pass per stage | planner, product-discovery |
-| \`balanced\` | discovery, criticism, review, TDD, and bounded worker execution | critic, spec-document-reviewer, coherence-reviewer, scope-guardian-reviewer, feasibility-reviewer, reviewer, security-reviewer, slice-builder, fixer |
-| \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
-`;
-}
-export function agentRegistryMatrix() {
-    const rows = CCLAW_AGENTS.map((agent) => {
-        const stages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "none";
-        return `| ${agent.name} | ${agent.activation} | ${agent.model} | ${stages} | ${agent.returnSchema.allowedStatuses.join(" / ")} |`;
-    }).join("\n");
-    return `| Agent | Activation | Model | Related stages | Terminal statuses |
-|---|---|---|---|---|
-${rows}`;
-}
-/**
- * AGENTS.md-ready section describing cclaw’s specialist delegation model.
- */
-export function agentsAgentsMdBlock() {
-    return `### Agent Specialists
-
-cclaw defines specialist personas for \`.cclaw/agents/\`: ${CCLAW_AGENTS.map((agent) => agent.name).join(", ")}.
-**TDD work** is owned end-to-end by **slice-builder** — one worker per slice, multiple workers in parallel within a wave when \`claimedPaths\` are disjoint.
-
-${agentRoutingTable()}
-
-### Agent Registry Matrix
-
-${agentRegistryMatrix()}
-
-### 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
-
-${(() => {
-        const mode = activationModeSummary();
-        return `- **Mandatory:** ${mode.mandatory}.
-- **Proactive:** ${mode.proactive}.
-- **On-demand:** fixer. 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.
-`;
+export function renderAgentMarkdown(agent) {
+    const modes = agent.modes.map((mode) => `- ${mode}`).join("\n");
+    return `---\nname: ${agent.id}\ntitle: ${agent.title}\nactivation: ${agent.activation}\n---\n\n# ${agent.title}\n\n${agent.description}\n\n## Modes\n\n${modes}\n\n## Prompt\n\n${agent.prompt}\n`;
 }