cclaw-cli 0.51.24 → 0.51.26

package/dist/config.d.ts

@@ -49,7 +49,7 @@ export declare function readConfig(projectRoot: string, options?: ReadConfigOpti
  * the user set them explicitly. Keeps the default template small and honest:
  * only knobs a new user would meaningfully flip show up.
  */
-type AdvancedConfigKey = "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws" | "optInAudits" | "reviewLoop";
+type AdvancedConfigKey = "vcs" | "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws" | "optInAudits" | "reviewLoop";
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *

package/dist/config.js

@@ -16,6 +16,7 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
     "harnesses",
+    "vcs",
     "strictness",
     "tddTestGlobs",
     "tdd",
@@ -51,6 +52,7 @@ const MINIMAL_CONFIG_KEYS = [
     "version",
     "flowVersion",
     "harnesses",
+    "vcs",
     "strictness",
     "gitHookGuards"
 ];
@@ -142,11 +144,13 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION,
         harnesses,
+        vcs: "git-local-only",
         strictness: "advisory",
         tddTestGlobs: [...tddTestPathPatterns],
         tdd: {
             testPathPatterns: tddTestPathPatterns,
-            productionPathPatterns: tddProductionPathPatterns
+            productionPathPatterns: tddProductionPathPatterns,
+            verificationRef: "auto"
         },
         compound: {
             recurrenceThreshold: DEFAULT_COMPOUND_RECURRENCE_THRESHOLD
@@ -244,6 +248,16 @@ export async function readConfig(projectRoot, options = {}) {
     const harnesses = hasHarnessesField
         ? [...new Set(validatedHarnesses)]
         : DEFAULT_HARNESSES;
+    const vcsRaw = parsed.vcs;
+    if (Object.prototype.hasOwnProperty.call(parsed, "vcs") &&
+        vcsRaw !== "git-with-remote" &&
+        vcsRaw !== "git-local-only" &&
+        vcsRaw !== "none") {
+        throw configValidationError(fullPath, `"vcs" must be one of: git-with-remote, git-local-only, none`);
+    }
+    const vcs = vcsRaw === "git-with-remote" || vcsRaw === "git-local-only" || vcsRaw === "none"
+        ? vcsRaw
+        : "git-local-only";
     const strictnessRaw = parsed.strictness;
     if (Object.prototype.hasOwnProperty.call(parsed, "strictness") &&
         strictnessRaw !== "advisory" &&
@@ -258,16 +272,24 @@ export async function readConfig(projectRoot, options = {}) {
     const tddRaw = parsed.tdd;
     let explicitTddTestPathPatterns;
     let explicitTddProductionPathPatterns;
+    let explicitTddVerificationRef;
     if (hasTddField) {
         if (!isRecord(tddRaw)) {
             throw configValidationError(fullPath, `"tdd" must be an object`);
         }
-        const unknownTddKeys = Object.keys(tddRaw).filter((key) => key !== "testPathPatterns" && key !== "productionPathPatterns");
+        const unknownTddKeys = Object.keys(tddRaw).filter((key) => key !== "testPathPatterns" && key !== "productionPathPatterns" && key !== "verificationRef");
         if (unknownTddKeys.length > 0) {
             throw configValidationError(fullPath, `"tdd" has unknown key(s): ${unknownTddKeys.join(", ")}`);
         }
         explicitTddTestPathPatterns = validateStringArray(tddRaw.testPathPatterns, "tdd.testPathPatterns", fullPath);
         explicitTddProductionPathPatterns = validateStringArray(tddRaw.productionPathPatterns, "tdd.productionPathPatterns", fullPath);
+        if (tddRaw.verificationRef !== undefined &&
+            tddRaw.verificationRef !== "auto" &&
+            tddRaw.verificationRef !== "required" &&
+            tddRaw.verificationRef !== "disabled") {
+            throw configValidationError(fullPath, '"tdd.verificationRef" must be one of: auto, required, disabled');
+        }
+        explicitTddVerificationRef = tddRaw.verificationRef;
     }
     if (tddTestGlobsRaw !== undefined &&
         explicitTddTestPathPatterns !== undefined &&
@@ -508,11 +530,13 @@ export async function readConfig(projectRoot, options = {}) {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
         harnesses,
+        vcs,
         strictness,
         tddTestGlobs,
         tdd: {
             testPathPatterns: resolvedTddTestPathPatterns,
-            productionPathPatterns: resolvedTddProductionPathPatterns
+            productionPathPatterns: resolvedTddProductionPathPatterns,
+            verificationRef: explicitTddVerificationRef ?? "auto"
         },
         compound: {
             recurrenceThreshold: compoundRecurrenceThreshold
@@ -538,6 +562,7 @@ function buildSerializableConfig(config, options = {}) {
         "version",
         "flowVersion",
         "harnesses",
+        "vcs",
         "strictness",
         "tddTestGlobs",
         "tdd",

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

@@ -6,6 +6,16 @@
  * need isolated subagent context lives in `.cclaw/skills/research/*.md`
  * playbooks and is executed in-thread by the primary agent.
  */
+export interface AgentReturnSchema {
+    /** Field carrying the terminal verdict/status token. */
+    statusField: string;
+    /** Exact allowed terminal values for this agent's first structured return. */
+    allowedStatuses: string[];
+    /** Fields the controller should expect in every completed response. */
+    requiredFields: string[];
+    /** Fields that must cite artifact anchors, commands, or code locations when applicable. */
+    evidenceFields: string[];
+}
 export interface AgentDefinition {
     /** Kebab-case identifier, e.g. `"reviewer"`. */
     name: string;
@@ -19,6 +29,8 @@ export interface AgentDefinition {
     activation: "proactive" | "on-demand" | "mandatory";
     /** cclaw flow stages this agent is designed to support. */
     relatedStages: string[];
+    /** Strict terminal return contract rendered into materialized agent files. */
+    returnSchema: AgentReturnSchema;
     /** Markdown body rendered below the YAML frontmatter. */
     body: string;
 }
@@ -32,12 +44,22 @@ export interface AgentDefinition {
  * to `string` and break the compile-time drift guard.
  */
 export declare const CCLAW_AGENTS: readonly [{
+    readonly name: "researcher";
+    readonly 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.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "fast";
+    readonly activation: "proactive";
+    readonly relatedStages: ["brainstorm", "scope", "design", "plan"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
     readonly name: "planner";
     readonly 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.";
     readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
     readonly model: "deep";
     readonly activation: "mandatory";
     readonly relatedStages: ["brainstorm", "scope", "design", "spec", "plan"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "product-manager";
@@ -46,6 +68,7 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "balanced";
     readonly activation: "proactive";
     readonly relatedStages: ["brainstorm", "scope"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "critic";
@@ -54,6 +77,25 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "balanced";
     readonly activation: "proactive";
     readonly relatedStages: ["brainstorm", "scope", "design"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "architect";
+    readonly description: "MANDATORY during design. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and spec handoff before implementation.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "deep";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["design"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "spec-validator";
+    readonly description: "MANDATORY during standard/deep spec. MUST BE USED to validate measurable acceptance criteria, assumptions, edge cases, and testability mapping.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["spec"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "reviewer";
@@ -62,6 +104,34 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "balanced";
     readonly activation: "mandatory";
     readonly relatedStages: ["spec", "review", "ship"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "performance-reviewer";
+    readonly description: "PROACTIVE during review for hot paths, IO, data volume, caching, rendering, or algorithmic cost changes. Produces no-impact rationale when clean.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "proactive";
+    readonly relatedStages: ["review"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "compatibility-reviewer";
+    readonly description: "PROACTIVE during design/review when public APIs, config, persisted data, CLI behavior, generated clients, or dependency versions may change.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "proactive";
+    readonly relatedStages: ["design", "review"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "observability-reviewer";
+    readonly description: "PROACTIVE during design/review when diagnosis, telemetry, rollout visibility, or supportability could affect safe operation.";
+    readonly tools: ["Read", "Grep", "Glob"];
+    readonly model: "balanced";
+    readonly activation: "proactive";
+    readonly relatedStages: ["design", "review"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "security-reviewer";
@@ -70,6 +140,7 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "balanced";
     readonly activation: "mandatory";
     readonly relatedStages: ["design", "review", "ship"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "test-author";
@@ -78,6 +149,16 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "balanced";
     readonly activation: "mandatory";
     readonly relatedStages: ["tdd"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "release-reviewer";
+    readonly description: "MANDATORY during ship. MUST BE USED for release readiness, rollback, finalization mode, evidence freshness, and victory detector checks.";
+    readonly tools: ["Read", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "mandatory";
+    readonly relatedStages: ["ship"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }, {
     readonly name: "doc-updater";
@@ -86,6 +167,34 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly model: "fast";
     readonly activation: "mandatory";
     readonly relatedStages: ["tdd", "ship"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "slice-implementer";
+    readonly description: "ON-DEMAND or PROACTIVE during TDD GREEN/REFACTOR for one bounded vertical slice after RED evidence exists and file ownership is non-overlapping.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "on-demand";
+    readonly relatedStages: ["tdd"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "implementer";
+    readonly description: "ON-DEMAND worker for one scoped implementation slice. Use only with self-contained task text, explicit file boundaries, and verification expectations.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "on-demand";
+    readonly relatedStages: ["tdd"];
+    readonly returnSchema: AgentReturnSchema;
+    readonly body: string;
+}, {
+    readonly name: "fixer";
+    readonly description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.";
+    readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
+    readonly model: "balanced";
+    readonly activation: "on-demand";
+    readonly relatedStages: ["review", "tdd"];
+    readonly returnSchema: AgentReturnSchema;
     readonly body: string;
 }];
 /**
@@ -106,6 +215,7 @@ export declare function agentRoutingTable(): string;
  * Cost tier routing for the specialist agent roster.
  */
 export declare function agentCostTierTable(): string;
+export declare function agentRegistryMatrix(): string;
 /**
  * AGENTS.md-ready section describing cclaw’s specialist delegation model.
  */

package/dist/content/core-agents.js

@@ -6,6 +6,56 @@ function yamlScalarString(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 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.`;
+}
+function formatReturnSchema(schema) {
+    return [
+        `- 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(", ")}`
+    ].join("\n");
+}
 function formattedAgentsForStages(stages) {
     const summary = stageDelegationSummary("standard");
     const merged = [];
@@ -48,6 +98,26 @@ function activationModeSummary() {
  * to `string` and break the compile-time drift guard.
  */
 export const CCLAW_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.",
@@ -55,6 +125,7 @@ export const CCLAW_AGENTS = [
         model: "deep",
         activation: "mandatory",
         relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
         body: [
             "You are an **implementation planning specialist** (staff engineer mindset).",
             "",
@@ -75,6 +146,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "proactive",
         relatedStages: ["brainstorm", "scope"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
         body: [
             "You are a **product discovery specialist**.",
             "",
@@ -97,6 +169,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "proactive",
         relatedStages: ["brainstorm", "scope", "design"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
         body: [
             "You are an **adversarial critic** for product and engineering decisions.",
             "",
@@ -109,6 +182,40 @@ export const CCLAW_AGENTS = [
             "Return confirmed risks, disproven concerns, and the smallest decision-changing recommendation."
         ].join("\n")
     },
+    {
+        name: "architect",
+        description: "MANDATORY during design. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and spec handoff before implementation.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "mandatory",
+        relatedStages: ["design"],
+        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.",
+            "",
+            "**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: "reviewer",
         description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
@@ -116,6 +223,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["spec", "review", "ship"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
         body: [
             "You are a **combined spec + code reviewer**.",
             "",
@@ -141,6 +249,51 @@ export const CCLAW_AGENTS = [
             "**Trust model:** never rely on implementer claims; verify by reading code."
         ].join("\n")
     },
+    {
+        name: "performance-reviewer",
+        description: "PROACTIVE during review for hot paths, IO, data volume, caching, rendering, or algorithmic cost changes. Produces no-impact rationale when clean.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **performance review specialist**.",
+            "",
+            "Check hot paths, algorithmic complexity, IO/network calls, caching behavior, bundle/runtime costs, and accidental N+1 or repeated work.",
+            "Every finding needs a concrete code citation and a measurement or measurement plan."
+        ].join("\n")
+    },
+    {
+        name: "compatibility-reviewer",
+        description: "PROACTIVE during design/review when public APIs, config, persisted data, CLI behavior, generated clients, or dependency versions may change.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["design", "review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **compatibility review specialist**.",
+            "",
+            "Check API compatibility, config/schema stability, persisted data migrations, CLI/user-facing behavior, generated clients, and rollout fallback paths.",
+            "Distinguish shipped compatibility obligations from in-branch implementation churn."
+        ].join("\n")
+    },
+    {
+        name: "observability-reviewer",
+        description: "PROACTIVE during design/review when diagnosis, telemetry, rollout visibility, or supportability could affect safe operation.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["design", "review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are an **observability review specialist**.",
+            "",
+            "Check logs, metrics, traces, alerts, debug handles, failure detection, and support handoff evidence for the changed paths.",
+            "Report missing visibility as a ship risk only when it affects diagnosis or rollback."
+        ].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.",
@@ -148,6 +301,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["design", "review", "ship"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
         body: [
             "You are a **security vulnerability specialist** focused on exploitability.",
             "",
@@ -173,6 +327,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
         body: [
             "You are a **test-driven development** specialist.",
             "",
@@ -186,6 +341,21 @@ export const CCLAW_AGENTS = [
             "5. REFACTOR with behavior preserved."
         ].join("\n")
     },
+    {
+        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")
+    },
     {
         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.",
@@ -193,6 +363,7 @@ export const CCLAW_AGENTS = [
         model: "fast",
         activation: "mandatory",
         relatedStages: ["tdd", "ship"],
+        returnSchema: DOC_RETURN_SCHEMA,
         body: [
             "You are a **documentation maintenance specialist**.",
             "",
@@ -204,6 +375,66 @@ export const CCLAW_AGENTS = [
             "",
             "Preserve existing tone and structure; avoid rewrites for style alone."
         ].join("\n")
+    },
+    {
+        name: "slice-implementer",
+        description: "ON-DEMAND or PROACTIVE during TDD GREEN/REFACTOR for one bounded vertical slice after RED evidence exists and file ownership is non-overlapping.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "on-demand",
+        relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
+        body: [
+            "You are a **vertical-slice implementation worker**.",
+            "",
+            "Rules:",
+            "1. Start only from the assigned RED failure and acceptance mapping.",
+            "2. Edit only the allowed files for the slice.",
+            "3. Implement the minimal GREEN change, then preserve behavior during REFACTOR.",
+            "4. Return files changed, tests run, evidence refs, concerns, and blockers.",
+            "",
+            "**Role boundary:** do not broaden scope, do not review your own work as final approval, and do not spawn subagents."
+        ].join("\n")
+    },
+    {
+        name: "implementer",
+        description: "ON-DEMAND worker for one scoped implementation slice. Use only with self-contained task text, explicit file boundaries, and verification expectations.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "on-demand",
+        relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
+        body: [
+            "You are an **implementation worker** for one bounded cclaw task.",
+            "",
+            "Rules:",
+            "1. Treat the parent prompt as the full task boundary; do not infer hidden scope from plan files.",
+            "2. Make the smallest coherent code change that satisfies the pasted acceptance criteria.",
+            "3. Run the requested verification commands when feasible and report representative evidence.",
+            "4. Return the strict worker JSON schema before prose.",
+            "",
+            "**Role boundary:** do not review your own work as final approval and do not spawn subagents."
+        ].join("\n")
+    },
+    {
+        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",
+        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")
     }
 ];
 import { stageDelegationSummary } from "./stage-schema.js";
@@ -233,6 +464,14 @@ ${agent.body}
 - Mode: ${agent.activation}
 - Related stages: ${relatedStages}
 
+${workerAckContract()}
+
+## 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
@@ -273,20 +512,33 @@ export function agentCostTierTable() {
     return `| Tier | Use for | Example agents |
 |---|---|---|
 | \`deep\` | one heavy planning pass per stage | planner |
-| \`balanced\` | discovery, criticism, review, and TDD specialists with stronger reasoning depth | product-manager, critic, reviewer, security-reviewer, test-author |
+| \`balanced\` | discovery, criticism, review, TDD, and bounded worker execution | product-manager, critic, reviewer, security-reviewer, test-author, implementer, 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 materializes specialist agents under \`.cclaw/agents/\`, including planner, product-manager, critic, reviewer, security-reviewer, test-author, and doc-updater.
+cclaw materializes specialist agents under \`.cclaw/agents/\`: ${CCLAW_AGENTS.map((agent) => agent.name).join(", ")}.
 
 ${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/\`:
@@ -303,7 +555,7 @@ ${(() => {
         const mode = activationModeSummary();
         return `- **Mandatory:** ${mode.mandatory}.
 - **Proactive:** ${mode.proactive}.
-- **On-demand:** none in the specialist roster; research playbooks are in-thread procedures.`;
+- **On-demand:** slice-implementer, implementer, fixer. Research playbooks are in-thread procedures.`;
     })()}
 
 ### Cost-aware routing