@cardor/agent-harness-kit 2.5.0 → 2.6.0

package/dist/cli.js

@@ -36,6 +36,51 @@ var write = (cwd2, relPath, content, mode) => {
   writeFileSync(abs, content, { encoding: "utf8", mode });
 };
 
+// src/core/materializer/delegation-guidance.ts
+var PROVIDER_DELEGATION_GUIDANCE = {
+  "claude-code": {
+    invoke: ["@mention"],
+    sequential: "Use @<role-name> to delegate to a specific agent. Claude selects the subagent by role name.",
+    parallel: "Launch multiple @mentions in a single message for parallel work.",
+    contextTransfer: "Pass a self-contained objective, scope, known context, restrictions, and output contract with each @mention.",
+    waitForCompletion: "Wait for each @mention to complete before proceeding to the next step."
+  },
+  opencode: {
+    invoke: ["@mention"],
+    sequential: "Use @<role-name> to delegate to a specific agent. Child sessions need a self-contained objective.",
+    parallel: "Launch multiple @mentions in a single message for parallel work.",
+    contextTransfer: "Each child session needs: objective, scope, known context, restrictions, output contract.",
+    waitForCompletion: "Wait for each @mention to complete before proceeding."
+  },
+  "codex-cli": {
+    invoke: ["spawn", "delegate", "parallel", "wait", "summarize"],
+    sequential: "Use spawn \u2192 delegate \u2192 wait \u2192 summarize pattern. Explicit commands for each step.",
+    parallel: "Use parallel spawns for independent agents. Wait for all to complete.",
+    contextTransfer: "Provide full context in the spawn command \u2014 no shared state between children.",
+    waitForCompletion: "Use explicit wait after spawning parallel tasks.",
+    inspectProgress: "Check progress via status commands between waits."
+  },
+  "grok-cli": {
+    invoke: ["project subagent", "/tasks"],
+    sequential: "Refer to project-defined subagents by role name.",
+    parallel: "Launch multiple project subagents by role for parallel work.",
+    contextTransfer: "Provide bounded context when delegating to subagents.",
+    waitForCompletion: "Wait for subagent completion before proceeding.",
+    inspectProgress: "Use /tasks to check progress of running subagents."
+  }
+};
+function renderDelegationGuidance(provider, _audience = "lead") {
+  const guidance = PROVIDER_DELEGATION_GUIDANCE[provider];
+  if (!guidance) return "";
+  const lines = [];
+  for (const [key, value] of Object.entries(guidance)) {
+    if (key === "invoke") continue;
+    const label = key.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase());
+    lines.push(`- ${label}: ${value}`);
+  }
+  return lines.join("\n");
+}
+
 // src/core/materializer/detect-package-manager.ts
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
 import { join as join4 } from "path";
@@ -207,15 +252,12 @@ var MCP_CLAUDE_PERMISSIONS_LEAD = [
   "mcp__agent-harness-kit__actions_write",
   "mcp__agent-harness-kit__actions_complete",
   "mcp__agent-harness-kit__actions_get",
-  "mcp__agent-harness-kit__actions_record_file",
-  "mcp__agent-harness-kit__actions_record_tool",
-  "mcp__agent-harness-kit__tasks_get",
-  "mcp__agent-harness-kit__tasks_claim",
-  "mcp__agent-harness-kit__tasks_add",
-  "mcp__agent-harness-kit__tasks_update",
-  "mcp__agent-harness-kit__tasks_edit",
-  "mcp__agent-harness-kit__tasks_archive",
-  "mcp__agent-harness-kit__tasks_unarchive",
+  "mcp__agent-harness-kit__actions_get_by_id",
+  "mcp__agent-harness-kit__actions_handoff_get",
+  "mcp__agent-harness-kit__actions_handoff_write",
+  "mcp__agent-harness-kit__actions_list",
+  "mcp__agent-harness-kit__actions_sections_get",
+  "mcp__agent-harness-kit__actions_sections_list",
   "mcp__agent-harness-kit__tasks_acceptance_get",
   "mcp__agent-harness-kit__docs_search",
   "mcp__agent-harness-kit__ahk_doctor"
@@ -225,6 +267,12 @@ var MCP_CLAUDE_PERMISSIONS_EXPLORER = [
   "mcp__agent-harness-kit__actions_write",
   "mcp__agent-harness-kit__actions_complete",
   "mcp__agent-harness-kit__actions_get",
+  "mcp__agent-harness-kit__actions_get_by_id",
+  "mcp__agent-harness-kit__actions_handoff_get",
+  "mcp__agent-harness-kit__actions_handoff_write",
+  "mcp__agent-harness-kit__actions_list",
+  "mcp__agent-harness-kit__actions_sections_get",
+  "mcp__agent-harness-kit__actions_sections_list",
   "mcp__agent-harness-kit__actions_record_file",
   "mcp__agent-harness-kit__actions_record_tool",
   "mcp__agent-harness-kit__tasks_get",
@@ -238,6 +286,12 @@ var MCP_CLAUDE_PERMISSIONS_BUILDER = [
   "mcp__agent-harness-kit__actions_write",
   "mcp__agent-harness-kit__actions_complete",
   "mcp__agent-harness-kit__actions_get",
+  "mcp__agent-harness-kit__actions_get_by_id",
+  "mcp__agent-harness-kit__actions_handoff_get",
+  "mcp__agent-harness-kit__actions_handoff_write",
+  "mcp__agent-harness-kit__actions_list",
+  "mcp__agent-harness-kit__actions_sections_get",
+  "mcp__agent-harness-kit__actions_sections_list",
   "mcp__agent-harness-kit__actions_record_file",
   "mcp__agent-harness-kit__actions_record_tool",
   "mcp__agent-harness-kit__tasks_get",
@@ -256,6 +310,12 @@ var MCP_CLAUDE_PERMISSIONS_REVIEWER = [
   "mcp__agent-harness-kit__actions_write",
   "mcp__agent-harness-kit__actions_complete",
   "mcp__agent-harness-kit__actions_get",
+  "mcp__agent-harness-kit__actions_get_by_id",
+  "mcp__agent-harness-kit__actions_handoff_get",
+  "mcp__agent-harness-kit__actions_handoff_write",
+  "mcp__agent-harness-kit__actions_list",
+  "mcp__agent-harness-kit__actions_sections_get",
+  "mcp__agent-harness-kit__actions_sections_list",
   "mcp__agent-harness-kit__actions_record_file",
   "mcp__agent-harness-kit__actions_record_tool",
   "mcp__agent-harness-kit__tasks_get",
@@ -275,6 +335,12 @@ var MCP_CLAUDE_PERMISSIONS_CONSULTANT = [
   "mcp__agent-harness-kit__actions_write",
   "mcp__agent-harness-kit__actions_complete",
   "mcp__agent-harness-kit__actions_get",
+  "mcp__agent-harness-kit__actions_get_by_id",
+  "mcp__agent-harness-kit__actions_handoff_get",
+  "mcp__agent-harness-kit__actions_handoff_write",
+  "mcp__agent-harness-kit__actions_list",
+  "mcp__agent-harness-kit__actions_sections_get",
+  "mcp__agent-harness-kit__actions_sections_list",
   "mcp__agent-harness-kit__actions_record_file",
   "mcp__agent-harness-kit__actions_record_tool",
   "mcp__agent-harness-kit__tasks_get",
@@ -417,6 +483,37 @@ function mergeGrokConfigToml(filePath, port, cwd2, pm = "npm") {
   writeFileSync2(filePath, content, "utf8");
 }
 
+// src/core/materializer/provider-research-capabilities.ts
+var capabilities = {
+  "claude-code": { context7: true, mintlifyIndex: false, webSearch: true },
+  opencode: { context7: true, mintlifyIndex: true, webSearch: true },
+  "codex-cli": { context7: true, mintlifyIndex: false, webSearch: true },
+  "grok-cli": { context7: true, mintlifyIndex: false, webSearch: true }
+};
+function getResearchCapabilities(provider) {
+  return capabilities[provider];
+}
+function buildCapabilityHints(provider) {
+  const caps = getResearchCapabilities(provider);
+  const hints = [];
+  if (caps.context7) {
+    hints.push("- Context7 MCP tools available: resolve library ID before querying docs");
+  } else {
+    hints.push("- Context7 MCP tools NOT available \u2014 use official web documentation");
+  }
+  if (caps.mintlifyIndex) {
+    hints.push("- Mintlify Index available for publisher-maintained technical documentation");
+  } else {
+    hints.push("- Mintlify Index NOT available \u2014 fall back to official web documentation");
+  }
+  if (caps.webSearch) {
+    hints.push("- Web search available for current information outside documentation indexes");
+  } else {
+    hints.push("- Web search NOT available \u2014 report proof boundary, do not describe remembered behavior as current");
+  }
+  return hints.join("\n");
+}
+
 // src/core/materializer/scaffold-utils.ts
 import { createHash } from "crypto";
 import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
@@ -489,12 +586,12 @@ echo "Edit this file with your project's health checks."
 echo "It must exit 0 for agents to start working."
 exit 1
 `;
-function agentsMd(config) {
+function agentsMdBody(config, fileName, extraInitLines = "", orchestratingOverride) {
   const { name, description, docsPath } = config.project;
   const port = config.tools.mcp.port;
-  return `# AGENTS.md \u2014 ${name}
+  let body = `# ${fileName} \u2014 ${name}
 
-> **Read this file first.** It is the navigation map for every AI agent working in this repository.
+**Read this file first.** It is the navigation map for every AI agent working in this repository.
 
 ## Project
 
@@ -526,7 +623,12 @@ actions.write        actionId section text                  \u2192 record a sect
 actions.record_tool  actionId calls[]                        \u2192 batch-log tool calls to the Tools dashboard (array, min 1)
 actions.record_file  actionId files[]                        \u2192 batch-log file touches to the Files dashboard (array, min 1)
 actions.complete     actionId summary                       \u2192 close the action
-actions.get          taskId                                 \u2192 full action history for a task
+actions.list         taskId [agent] [status] [limit] [cursor] \u2192 compact newest-first action index with pagination
+actions.get_by_id    actionId                               \u2192 single action with section index (no content)
+actions.sections_list actionId [types] [limit] [cursor]      \u2192 compact section index with type filtering
+actions.sections_get sectionId [length] [offset]             \u2192 ranged section content reader
+actions.handoff.get    taskId [recipient]                     \u2192 newest completed canonical handoff
+actions.handoff.write  actionId recipient ...                 \u2192 recipient-directed bounded handoff
 tasks.add            title [slug] [description] [acceptance] \u2192 create a new task from natural language
 tasks.get            [status]                               \u2192 list tasks (pending | in_progress | done | blocked)
 tasks.claim          id                                     \u2192 atomically claim a pending task
@@ -542,15 +644,15 @@ docs.search          query                                  \u2192 search ${docs
    - Assess user intent: only run health.sh if changes are needed
    - tasks.get('in_progress') \u2192 resume if something is in progress
    - tasks.get('pending') \u2192 pick lowest id
-
+${extraInitLines ? "\n" : ""}${extraInitLines}
 2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
-   - Each agent calls actions.start(taskId, agentName) \u2192 numeric actionId
-   - Accumulate tool calls / file touches as you work; flush periodically (every few calls or at a phase boundary) via actions.record_tool(actionId, calls: [...]) and actions.record_file(actionId, files: [...]) \u2014 both are batch-only, even a single entry goes through as a one-element array
-   - Closes with actions.complete(actionId, summary)
+     - Each agent calls actions.start(taskId, agentName) \u2192 numeric actionId
+     - Accumulate tool calls / file touches as you work; flush periodically (every few calls or at a phase boundary) via actions.record_tool(actionId, calls: [...]) and actions.record_file(actionId, files: [...]) \u2014 both are batch-only, even a single entry goes through as a one-element array
+     - Closes with actions.complete(actionId, summary)
 
 3. CLOSE
-   - tasks.update(taskId, 'done')
-   - Run health.sh (if changes were made) \u2192 must be green before closing
+     - tasks.update(taskId, 'done')
+     - Run health.sh (if changes were made) \u2192 must be green before closing
 \`\`\`
 
 ## Agent roles
@@ -568,93 +670,39 @@ docs.search          query                                  \u2192 search ${docs
 \`\`\`
 Always:         .harness/current.md (or MCP tasks.get)
 If implementing: ${docsPath}/
-If orchestrating: Agent definition files in your provider's agents directory
+If orchestrating: ${orchestratingOverride ?? "Agent definition files in your provider's agents directory"}
 \`\`\`
 `;
+  if (extraInitLines) {
+    body = body.replace(
+      "   - tasks.get('pending') \u2192 pick lowest id\n",
+      `   - tasks.get('pending') \u2192 pick lowest id
+${extraInitLines}
+`
+    );
+  }
+  return body;
 }
-function claudeMd(config) {
-  const { name, description, docsPath } = config.project;
-  const port = config.tools.mcp.port;
-  return `# CLAUDE.md \u2014 ${name}
-
-> **Read this file first.** It is the navigation map for every AI agent working in this repository.
-
-## Project
-
-**${name}** \u2014 ${description}
+function agentsMd(config, capabilityHints = "") {
+  const capabilityBlock = capabilityHints ? `## Available Research Tools
 
-## Health check (run before making codebase changes)
+${capabilityHints}
 
-\`\`\`bash
-bash health.sh
-\`\`\`
-
-If it exits non-zero, stop and report the issue. Do not proceed with codebase changes until health is green.
-
-## Harness data (source of truth)
-
-| File | Purpose |
-|------|---------|
-| \`.harness/harness.db\` | SQLite: all tasks, actions, file changes, tool calls |
-| \`.harness/current.md\` | Markdown fallback \u2014 read this if MCP server is unavailable |
-| \`.harness/feature_list.json\` | Human-editable task seed list |
-
-## MCP tools (preferred)
-
-The harness exposes tools via MCP server on port ${port}. Use these instead of reading files directly.
-
-\`\`\`
-actions.start        taskId agent                           \u2192 start an action, returns a numeric actionId
-actions.write        actionId section text                  \u2192 record a section (result, blockers, ...)
-actions.record_tool  actionId calls[]                        \u2192 batch-log tool calls to the Tools dashboard (array, min 1)
-actions.record_file  actionId files[]                        \u2192 batch-log file touches to the Files dashboard (array, min 1)
-actions.complete     actionId summary                       \u2192 close the action
-actions.get          taskId                                 \u2192 full action history for a task
-tasks.add            title [slug] [description] [acceptance] \u2192 create a new task from natural language
-tasks.get            [status]                               \u2192 list tasks (pending | in_progress | done | blocked)
-tasks.claim          id                                     \u2192 atomically claim a pending task
-tasks.update         id status                              \u2192 change task status
-tasks.acceptance.update criterionId                        \u2192 mark an acceptance criterion as met
-docs.search          query                                  \u2192 search ${docsPath} for relevant content
-\`\`\`
-
-## Workflow
-
-\`\`\`
-1. INIT
-   - Assess user intent: only run health.sh if changes are needed
-   - tasks.get('in_progress') \u2192 resume if something is in progress
-   - tasks.get('pending') \u2192 pick lowest id
-   - No pending tasks? \u2192 ask user, infer fields, call tasks.add, then tasks.claim
-
-2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
-   - Each agent calls actions.start(taskId, agentName) \u2192 numeric actionId
-   - Accumulate tool calls / file touches as you work; flush periodically (every few calls or at a phase boundary) via actions.record_tool(actionId, calls: [...]) and actions.record_file(actionId, files: [...]) \u2014 both are batch-only, even a single entry goes through as a one-element array
-   - Closes with actions.complete(actionId, summary)
-
-3. CLOSE
-   - tasks.update(taskId, 'done')
-   - Run health.sh (if changes were made) \u2192 must be green before closing
-\`\`\`
-
-## Agent roles
-
-| Agent | Responsibility |
-|-------|---------------|
-| lead | Decomposes the task into a plan, assigns sub-agents |
-| explorer | Reads and maps relevant code, never writes |
-| consultant | Technical advisor, runs after explorer, before builder. Never writes code. |
-| builder | Implements the plan, writes files |
-| reviewer | Verifies acceptance criteria, approves or blocks |
+` : "";
+  return `${capabilityBlock}${agentsMdBody(config, "AGENTS.md")}`;
+}
+function claudeMd(config, capabilityHints = "") {
+  const capabilityBlock = capabilityHints ? `## Available Research Tools
 
-## What to read
+${capabilityHints}
 
-\`\`\`
-Always:         .harness/current.md (or MCP tasks.get)
-If implementing: ${docsPath}/
-If orchestrating: Agent definition files in .claude/agents/
-\`\`\`
-`;
+` : "";
+  return `${capabilityBlock}${agentsMdBody(
+    config,
+    "CLAUDE.md",
+    "    - No pending tasks? \u2192 ask user, infer fields, call tasks.add, then tasks.claim",
+    "Agent definition files in .claude/agents/"
+  )}`;
 }
 function configObjectBody(params) {
   const isGlobal = params.scope === "global";
@@ -772,20 +820,54 @@ ${configObjectBody(params)}}
 module.exports = config
 `;
 }
-function agentLead(vars) {
-  return loadAgentTemplate("lead", vars);
+function injectCapabilityHints(md, capabilityHints) {
+  if (!capabilityHints) return md;
+  const headingMatch = md.match(/^(#\s+.*?\n\n)/m);
+  if (!headingMatch) return md;
+  return `${headingMatch[1]}## Available Research Tools
+
+${capabilityHints}
+
+${md.slice(headingMatch[1].length)}`;
+}
+function injectDelegationGuidance(md, delegationGuidance) {
+  if (!delegationGuidance) return md;
+  const researchSection = md.match(/(## Available Research Tools\n\n[\s\S]*?)\n\n/m);
+  if (researchSection) {
+    const insertionPoint = researchSection[1].length + "## Available Research Tools\n\n".length;
+    const afterResearch = md.slice(insertionPoint);
+    return md.slice(0, insertionPoint) + `
+## Provider Delegation Guidance
+
+${delegationGuidance}
+
+${afterResearch}`;
+  }
+  const headingMatch = md.match(/^(#\s+.*?\n\n)/m);
+  if (!headingMatch) return md;
+  return `${headingMatch[1]}## Provider Delegation Guidance
+
+${delegationGuidance}
+
+${md.slice(headingMatch[1].length)}`;
+}
+function agentLead(opts, capabilityHints = "", delegationGuidance = "") {
+  let result = loadAgentTemplate("lead", opts);
+  result = injectCapabilityHints(result, capabilityHints);
+  result = injectDelegationGuidance(result, delegationGuidance);
+  return result;
 }
-function agentExplorer(vars) {
-  return loadAgentTemplate("explorer", vars);
+function agentExplorer(opts, capabilityHints = "") {
+  return injectCapabilityHints(loadAgentTemplate("explorer", opts), capabilityHints);
 }
-function agentBuilder(vars) {
-  return loadAgentTemplate("builder", vars);
+function agentBuilder(opts, capabilityHints = "") {
+  return injectCapabilityHints(loadAgentTemplate("builder", opts), capabilityHints);
 }
-function agentConsultant(vars) {
-  return loadAgentTemplate("consultant", vars);
+function agentConsultant(opts, capabilityHints = "") {
+  return injectCapabilityHints(loadAgentTemplate("consultant", opts), capabilityHints);
 }
-function agentReviewer(vars) {
-  return loadAgentTemplate("reviewer", vars);
+function agentReviewer(opts, capabilityHints = "") {
+  return injectCapabilityHints(loadAgentTemplate("reviewer", opts), capabilityHints);
 }
 function stripFrontmatter(md) {
   const parts = md.split(/^---\s*$/m);
@@ -828,13 +910,23 @@ ${safe(instructions)}
 """
 `;
 }
-function agentLeadToml(vars, opts) {
+function agentLeadToml(vars, opts, delegationGuidance = "") {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("lead", "lead", description, body, opts);
+  const bodyWithDelegation = delegationGuidance ? `${body}
+
+## Provider Delegation Guidance
+
+${delegationGuidance}` : body;
+  return toCodexToml("lead", "lead", description, bodyWithDelegation, opts);
 }
-function agentLeadAsDefaultToml(vars, opts) {
+function agentLeadAsDefaultToml(vars, opts, delegationGuidance = "") {
   const { description, body } = stripFrontmatter(loadAgentTemplate("lead", vars));
-  return toCodexToml("default", "lead", description, body, opts);
+  const bodyWithDelegation = delegationGuidance ? `${body}
+
+## Provider Delegation Guidance
+
+${delegationGuidance}` : body;
+  return toCodexToml("default", "lead", description, bodyWithDelegation, opts);
 }
 function agentExplorerToml(vars, opts) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("explorer", vars));
@@ -1056,33 +1148,38 @@ function appendGitignore(cwd2) {
 function slugify(title) {
   return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
 }
-function writeSkills(cwd2, skillsDir) {
+function writeSkills(cwd2, skillsDir, delegationGuidance) {
   const skillNames = ["ahk-ask", "ahk-consultant", "ahk-triage", "ahk-review", "ahk-test"];
   for (const skillName of skillNames) {
     const src = join6(__dirname2, "skills", skillName, "SKILL.md");
     const destDir = join6(cwd2, skillsDir, skillName);
     const dest = join6(destDir, "SKILL.md");
     mkdirSync3(destDir, { recursive: true });
-    writeFileSync3(dest, readFileSync5(src, "utf8"), "utf8");
+    let content = readFileSync5(src, "utf8");
+    if (delegationGuidance) {
+      content = injectDelegationGuidance(content, delegationGuidance);
+    }
+    writeFileSync3(dest, content, "utf8");
   }
 }
 
 // src/core/materializer/claude-code.ts
-function claudeAgentFiles(config, modelsByRole) {
+function claudeAgentFiles(config, modelsByRole, capabilityHints = "") {
   const projectName = config.project.name;
   return [
-    { relPath: ".claude/agents/lead.md", content: translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead", { model: modelsByRole?.lead }) },
-    { relPath: ".claude/agents/explorer.md", content: translateFrontmatterForClaudeCode(agentExplorer({ projectName }), "explorer", { model: modelsByRole?.explorer }) },
-    { relPath: ".claude/agents/consultant.md", content: translateFrontmatterForClaudeCode(agentConsultant({ projectName }), "consultant", { model: modelsByRole?.consultant }) },
-    { relPath: ".claude/agents/builder.md", content: translateFrontmatterForClaudeCode(agentBuilder({ projectName }), "builder", { model: modelsByRole?.builder }) },
-    { relPath: ".claude/agents/reviewer.md", content: translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer", { model: modelsByRole?.reviewer }) }
+    { relPath: ".claude/agents/lead.md", content: translateFrontmatterForClaudeCode(agentLead({ projectName }, capabilityHints, renderDelegationGuidance("claude-code", "lead")), "lead", { model: modelsByRole?.lead }) },
+    { relPath: ".claude/agents/explorer.md", content: translateFrontmatterForClaudeCode(agentExplorer({ projectName }, capabilityHints), "explorer", { model: modelsByRole?.explorer }) },
+    { relPath: ".claude/agents/consultant.md", content: translateFrontmatterForClaudeCode(agentConsultant({ projectName }, capabilityHints), "consultant", { model: modelsByRole?.consultant }) },
+    { relPath: ".claude/agents/builder.md", content: translateFrontmatterForClaudeCode(agentBuilder({ projectName }, capabilityHints), "builder", { model: modelsByRole?.builder }) },
+    { relPath: ".claude/agents/reviewer.md", content: translateFrontmatterForClaudeCode(agentReviewer({ projectName }, capabilityHints), "reviewer", { model: modelsByRole?.reviewer }) }
   ];
 }
 var ClaudeCodeMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2, claudeAgentModels } = opts;
-    write(cwd2, "AGENTS.md", stampGenerated(agentsMd(config)));
-    write(cwd2, "CLAUDE.md", stampGenerated(claudeMd(config)));
+    const capabilityHints = buildCapabilityHints("claude-code");
+    write(cwd2, "AGENTS.md", stampGenerated(agentsMd(config, capabilityHints)));
+    write(cwd2, "CLAUDE.md", stampGenerated(claudeMd(config, capabilityHints)));
     if (!existsSync6(join7(cwd2, "health.sh"))) {
       write(cwd2, "health.sh", HEALTH_SH, 493);
     }
@@ -1099,30 +1196,31 @@ No tasks in progress.
 `
       );
     }
-    writeAgentFiles(cwd2, claudeAgentFiles(config, claudeAgentModels));
+    writeAgentFiles(cwd2, claudeAgentFiles(config, claudeAgentModels, capabilityHints));
     mergeClaudeMcpJson(join7(cwd2, ".mcp.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     mergeClaudeSettingsJson(join7(cwd2, ".claude/settings.json"));
     mergeClaudeSettingsLocalJson(join7(cwd2, ".claude/settings.local.json"));
     appendGitignore(cwd2);
-    writeSkills(cwd2, ".claude/skills");
+    writeSkills(cwd2, ".claude/skills", renderDelegationGuidance("claude-code", "coordination-skill"));
   }
   async build(config, cwd2, opts = {}) {
+    const capabilityHints = buildCapabilityHints("claude-code");
     const derived = reconcileGeneratedFiles(
       cwd2,
       [
-        { relPath: "AGENTS.md", content: agentsMd(config) },
-        { relPath: "CLAUDE.md", content: claudeMd(config) }
+        { relPath: "AGENTS.md", content: agentsMd(config, capabilityHints) },
+        { relPath: "CLAUDE.md", content: claudeMd(config, capabilityHints) }
       ],
       { force: opts.force, backupRoot: join7(cwd2, config.storage.dir, "backups") }
     );
-    const agents = writeAgentFiles(cwd2, claudeAgentFiles(config, opts.claudeAgentModels), {
+    const agents = writeAgentFiles(cwd2, claudeAgentFiles(config, opts.claudeAgentModels, capabilityHints), {
       force: opts.force,
       backupRoot: join7(cwd2, config.storage.dir, "backups")
     });
     mergeClaudeMcpJson(join7(cwd2, ".mcp.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     mergeClaudeSettingsJson(join7(cwd2, ".claude/settings.json"));
     mergeClaudeSettingsLocalJson(join7(cwd2, ".claude/settings.local.json"));
-    writeSkills(cwd2, ".claude/skills");
+    writeSkills(cwd2, ".claude/skills", renderDelegationGuidance("claude-code", "coordination-skill"));
     return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
@@ -1152,15 +1250,15 @@ No tasks in progress.
 // src/core/materializer/codex-cli.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
 import { join as join8, resolve as resolve3 } from "path";
-function codexAgentFiles(config, modelsByRole) {
+function codexAgentFiles(config, modelsByRole, _capabilityHints = "") {
   const projectName = config.project.name;
   return [
-    { relPath: ".codex/agents/lead.toml", content: agentLeadToml({ projectName }, modelsByRole?.lead) },
+    { relPath: ".codex/agents/lead.toml", content: agentLeadToml({ projectName }, modelsByRole?.lead, renderDelegationGuidance("codex-cli", "lead")) },
     { relPath: ".codex/agents/explorer.toml", content: agentExplorerToml({ projectName }, modelsByRole?.explorer) },
     { relPath: ".codex/agents/consultant.toml", content: agentConsultantToml({ projectName }, modelsByRole?.consultant) },
     { relPath: ".codex/agents/builder.toml", content: agentBuilderToml({ projectName }, modelsByRole?.builder) },
     { relPath: ".codex/agents/reviewer.toml", content: agentReviewerToml({ projectName }, modelsByRole?.reviewer) },
-    { relPath: ".codex/agents/default.toml", content: agentLeadAsDefaultToml({ projectName }, modelsByRole?.lead) }
+    { relPath: ".codex/agents/default.toml", content: agentLeadAsDefaultToml({ projectName }, modelsByRole?.lead, renderDelegationGuidance("codex-cli", "lead")) }
   ];
 }
 var CodexCliMaterializer = class {
@@ -1190,7 +1288,7 @@ No tasks in progress.
     writeAgentFiles(cwd2, codexAgentFiles(config, codexAgentModels));
     mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
-    writeSkills(cwd2, ".agents/skills");
+    writeSkills(cwd2, ".agents/skills", renderDelegationGuidance("codex-cli", "coordination-skill"));
   }
   async build(config, cwd2, opts = {}) {
     const derived = reconcileGeneratedFiles(
@@ -1203,7 +1301,7 @@ No tasks in progress.
       backupRoot: join8(cwd2, config.storage.dir, "backups")
     });
     mergeCodexConfigToml(join8(cwd2, ".codex/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
-    writeSkills(cwd2, ".agents/skills");
+    writeSkills(cwd2, ".agents/skills", renderDelegationGuidance("codex-cli", "coordination-skill"));
     return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
@@ -1220,7 +1318,7 @@ import { join as join9, resolve as resolve4 } from "path";
 function grokAgentFiles(config) {
   const projectName = config.project.name;
   return [
-    { relPath: ".grok/agents/lead.md", content: translateFrontmatterForGrok(agentLead({ projectName }), "lead") },
+    { relPath: ".grok/agents/lead.md", content: translateFrontmatterForGrok(agentLead({ projectName }, "", renderDelegationGuidance("grok-cli", "lead")), "lead") },
     { relPath: ".grok/agents/explorer.md", content: translateFrontmatterForGrok(agentExplorer({ projectName }), "explorer") },
     { relPath: ".grok/agents/consultant.md", content: translateFrontmatterForGrok(agentConsultant({ projectName }), "consultant") },
     { relPath: ".grok/agents/builder.md", content: translateFrontmatterForGrok(agentBuilder({ projectName }), "builder") },
@@ -1254,7 +1352,7 @@ No tasks in progress.
     writeAgentFiles(cwd2, grokAgentFiles(config));
     mergeGrokConfigToml(join9(cwd2, ".grok/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
-    writeSkills(cwd2, ".grok/skills");
+    writeSkills(cwd2, ".grok/skills", renderDelegationGuidance("grok-cli", "coordination-skill"));
   }
   async build(config, cwd2, opts = {}) {
     const derived = reconcileGeneratedFiles(
@@ -1267,7 +1365,7 @@ No tasks in progress.
       backupRoot: join9(cwd2, config.storage.dir, "backups")
     });
     mergeGrokConfigToml(join9(cwd2, ".grok/config.toml"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
-    writeSkills(cwd2, ".grok/skills");
+    writeSkills(cwd2, ".grok/skills", renderDelegationGuidance("grok-cli", "coordination-skill"));
     return { agents, derived };
   }
   async migrate(config, _to, _cwd) {
@@ -1281,25 +1379,26 @@ No tasks in progress.
 // src/core/materializer/opencode.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "fs";
 import { join as join10, resolve as resolve5 } from "path";
-function opencodeAgentFiles(config) {
+function opencodeAgentFiles(config, capabilityHints = "") {
   const projectName = config.project.name;
   return [
-    { relPath: ".opencode/agents/lead.md", content: translateFrontmatterForOpenCode(agentLead({ projectName }), "lead") },
-    { relPath: ".opencode/agents/explorer.md", content: translateFrontmatterForOpenCode(agentExplorer({ projectName }), "explorer") },
-    { relPath: ".opencode/agents/consultant.md", content: translateFrontmatterForOpenCode(agentConsultant({ projectName }), "consultant") },
-    { relPath: ".opencode/agents/builder.md", content: translateFrontmatterForOpenCode(agentBuilder({ projectName }), "builder") },
-    { relPath: ".opencode/agents/reviewer.md", content: translateFrontmatterForOpenCode(agentReviewer({ projectName }), "reviewer") }
+    { relPath: ".opencode/agents/lead.md", content: translateFrontmatterForOpenCode(agentLead({ projectName }, capabilityHints, renderDelegationGuidance("opencode", "lead")), "lead") },
+    { relPath: ".opencode/agents/explorer.md", content: translateFrontmatterForOpenCode(agentExplorer({ projectName }, capabilityHints), "explorer") },
+    { relPath: ".opencode/agents/consultant.md", content: translateFrontmatterForOpenCode(agentConsultant({ projectName }, capabilityHints), "consultant") },
+    { relPath: ".opencode/agents/builder.md", content: translateFrontmatterForOpenCode(agentBuilder({ projectName }, capabilityHints), "builder") },
+    { relPath: ".opencode/agents/reviewer.md", content: translateFrontmatterForOpenCode(agentReviewer({ projectName }, capabilityHints), "reviewer") }
   ];
 }
 var OpenCodeMaterializer = class {
   async scaffold(config, opts) {
     const { cwd: cwd2 } = opts;
+    const capabilityHints = buildCapabilityHints("opencode");
     const write2 = (relPath, content, mode) => {
       const abs = join10(cwd2, relPath);
       mkdirSync6(resolve5(abs, ".."), { recursive: true });
       writeFileSync6(abs, content, { encoding: "utf8", mode });
     };
-    write2("AGENTS.md", stampGenerated(agentsMd(config)));
+    write2("AGENTS.md", stampGenerated(agentsMd(config, capabilityHints)));
     if (!existsSync9(join10(cwd2, "health.sh"))) {
       write2("health.sh", HEALTH_SH, 493);
     }
@@ -1315,23 +1414,24 @@ No tasks in progress.
 `
       );
     }
-    writeAgentFiles(cwd2, opencodeAgentFiles(config));
+    writeAgentFiles(cwd2, opencodeAgentFiles(config, capabilityHints));
     mergeOpencodeJson(join10(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
     appendGitignore(cwd2);
-    writeSkills(cwd2, ".opencode/skills");
+    writeSkills(cwd2, ".opencode/skills", renderDelegationGuidance("opencode", "coordination-skill"));
   }
   async build(config, cwd2, opts = {}) {
+    const capabilityHints = buildCapabilityHints("opencode");
     const derived = reconcileGeneratedFiles(
       cwd2,
-      [{ relPath: "AGENTS.md", content: agentsMd(config) }],
+      [{ relPath: "AGENTS.md", content: agentsMd(config, capabilityHints) }],
       { force: opts.force, backupRoot: join10(cwd2, config.storage.dir, "backups") }
     );
-    const agents = writeAgentFiles(cwd2, opencodeAgentFiles(config), {
+    const agents = writeAgentFiles(cwd2, opencodeAgentFiles(config, capabilityHints), {
       force: opts.force,
       backupRoot: join10(cwd2, config.storage.dir, "backups")
     });
     mergeOpencodeJson(join10(cwd2, "opencode.json"), config.tools.mcp.port, cwd2, detectPackageManager(cwd2));
-    writeSkills(cwd2, ".opencode/skills");
+    writeSkills(cwd2, ".opencode/skills", renderDelegationGuidance("opencode", "coordination-skill"));
     return { agents, derived };
   }
   async migrate(config, _to, _cwd) {