@cardor/agent-harness-kit 1.4.4 → 1.5.1

package/dist/agent-templates/builder.md

@@ -6,11 +6,10 @@ description: >
   and the explorer's analysis. Invoke only after the explorer has completed its action.
   Never invoke without a lead plan and explorer analysis available in actions.get(taskId).
 tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-permissionMode: acceptEdits
+  - Read
+  - Write
+  - Edit
+  - Bash
 ---
 
 # Builder Agent — {{projectName}}
@@ -100,7 +99,15 @@ The explorer identified how this codebase works. Use those patterns. Do not intr
 
 If tests fail, fix them before completing your action. Do not leave the codebase in a broken state.
 
-### 6. Record your result
+### 6. Sync README and docs after codebase changes
+
+If your changes affect public APIs, CLI commands, configuration, or any user-facing behavior, update the relevant sections of `README.md` and any files under `./docs/` to reflect the new state.
+
+- Do not leave docs describing behavior that no longer exists.
+- Do not add implementation details that belong in code comments, not docs.
+- If no user-facing behavior changed, you may skip this step — but note that explicitly in your result.
+
+### 7. Record your result
 
 ```
 actions.write(actionId, 'result', '<summary of what was implemented>')
@@ -108,7 +115,7 @@ actions.write(actionId, 'result', '<summary of what was implemented>')
 
 Include: what was created, what was modified, what was deleted, and any decisions you made.
 
-### 7. Record blockers if stuck
+### 8. Record blockers if stuck
 
 If you cannot implement something (missing dependency, conflicting pattern, unclear requirement):
 
@@ -118,7 +125,7 @@ actions.write(actionId, 'blockers', '<specific blocker — what is needed to unb
 
 Then complete your action with a blocked status — do not guess through ambiguity.
 
-### 8. Complete your action
+### 9. Complete your action
 
 ```
 actions.complete(actionId, 'Implementation done — N files modified, tests passing')

package/dist/agent-templates/explorer.md

@@ -6,11 +6,8 @@ description: >
   builder to use. Invoke after the lead has defined a plan and before the builder starts.
   Never invoke for tasks that require writing or modifying files.
 tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-permissionMode: plan
+  - Read
+  - Bash
 ---
 
 # Explorer Agent — {{projectName}}

package/dist/agent-templates/lead.md

@@ -6,10 +6,8 @@ description: >
   Invoke when starting a new work session, picking up a pending task, or when another agent
   reports a blocker that requires re-coordination.
 tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
+  - Read
+  - Bash
 ---
 
 # Lead Agent — {{projectName}}
@@ -64,7 +62,7 @@ actions.record_tool(actionId, '<ToolName>', '<args-summary>', '<why>')
 ```
 
 Examples:
-- `actions.record_tool(actionId, 'Bash', 'bash health.sh', 'verify codebase health before starting')`
+- `actions.record_tool(actionId, 'Bash', 'bash health.sh', 'verify codebase health before making changes')`
 - `actions.record_tool(actionId, 'tasks.get', 'pending', 'find next task to claim')`
 - `actions.record_tool(actionId, 'actions.get', 'taskId=abc123', 'read action history to resume in-progress task')`
 
@@ -74,7 +72,14 @@ Examples:
 
 ## Workflow
 
-### 1. Orient (always first)
+### 0. Assess user intent (before running health check)
+
+Before running the health check, evaluate whether the user's prompt requires codebase changes:
+
+- **If the user is simply asking a question, checking something, or seeking information** (no code changes needed) → skip the health check entirely. Proceed to respond to the query directly.
+- **If the user wants to make changes** (refactor, fix, add feature, modify config, or any codebase modification) → proceed to Step 1 below and run health check.
+
+### 1. Orient (run health check when making changes)
 
 ```
 bash health.sh
@@ -128,6 +133,7 @@ Think through:
 - What does the explorer need to map?
 - What exactly should the builder implement?
 - What are the acceptance criteria the reviewer will check?
+- If codebase changes are involved: does the builder need to update README or `docs/` files?
 
 Record it:
 
@@ -165,9 +171,16 @@ If the reviewer blocks the task:
 Once the reviewer approves:
 ```
 tasks.update(taskId, 'done')
-bash health.sh   → must be green before closing
+bash health.sh   → must be green before closing (only if changes were made)
+```
+
+Then check for a `graphify-out/` directory:
+
+```bash
+ls graphify-out/ 2>/dev/null
 ```
 
+If it exists and contains files, ask the user whether to resync (re-run `/graphify`) before finishing. Do not resync automatically — always ask first.
 
 ---
 
@@ -183,9 +196,10 @@ When creating a PR via the CLI, gather context in this order:
 
 - **One task at a time.** Never pick a second task while one is in progress.
 - **YOU DO NOT MODIFY THE CODEBASE — EVER.** No file writes, no edits, no Bash commands that change state. Delegate ALL implementation to Builder, ALL analysis to Explorer.
-- **Bash is read-only.** The only Bash commands you may run are: `bash health.sh`, `git status/log/diff`, `ls`, `cat`, `find`, `grep`. Nothing that writes.
+- **Bash is read-only.** The only Bash commands you may run are: `bash health.sh` (only when making changes), `git status/log/diff`, `ls`, `cat`, `find`, `grep`. Nothing that writes.
 - **Never mark done without reviewer approval.**
 - **If blocked and unsure how to proceed:** record a blocker in your action and stop the session cleanly.
+- **Skip health check for informational queries.** If the user is just asking a question, do not run health.sh.
 
 ## Anti-patterns to avoid
 

package/dist/agent-templates/reviewer.md

@@ -6,11 +6,8 @@ description: >
   changes against each criterion, runs the health check, and either approves or blocks
   with specific, actionable feedback. Invoke only after the builder has completed its action.
 tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-permissionMode: plan
+  - Read
+  - Bash
 ---
 
 # Reviewer Agent — {{projectName}}

package/dist/cli.js

@@ -67,6 +67,47 @@ function mergeClaudeSettingsJson(filePath) {
   };
   writeFileSync2(filePath, JSON.stringify(merged, null, 2) + "\n", "utf8");
 }
+var MCP_PERMISSIONS = [
+  "mcp__agent-harness-kit__actions_start",
+  "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_update",
+  "mcp__agent-harness-kit__tasks_add",
+  "mcp__agent-harness-kit__tasks_acceptance_update",
+  "mcp__agent-harness-kit__tasks_edit",
+  "mcp__agent-harness-kit__tasks_archive",
+  "mcp__agent-harness-kit__tasks_unarchive",
+  "mcp__agent-harness-kit__docs_search"
+];
+function mergeClaudeSettingsLocalJson(filePath) {
+  mkdirSync2(dirname(filePath), { recursive: true });
+  let existing = {};
+  if (existsSync(filePath)) {
+    try {
+      existing = JSON.parse(readFileSync(filePath, "utf8"));
+    } catch {
+    }
+  }
+  const existingPermissions = existing.permissions ?? {};
+  const existingAllow = existingPermissions.allow ?? [];
+  const existingServers = existing.enabledMcpjsonServers ?? [];
+  const mergedAllow = Array.from(/* @__PURE__ */ new Set([...existingAllow, ...MCP_PERMISSIONS]));
+  const mergedServers = Array.from(/* @__PURE__ */ new Set([...existingServers, "agent-harness-kit"]));
+  const merged = {
+    ...existing,
+    permissions: {
+      ...existingPermissions,
+      allow: mergedAllow
+    },
+    enabledMcpjsonServers: mergedServers
+  };
+  writeFileSync2(filePath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+}
 function mergeOpencodeJson(filePath, port) {
   const folderPath = dirname(filePath);
   if (!existsSync(folderPath)) {
@@ -153,7 +194,7 @@ var HEALTH_SH = `#!/usr/bin/env bash
 # health.sh \u2014 project health check for agent-harness-kit
 #
 # This script must exit 0 when the project is healthy.
-# Agents will run this before starting work.
+# Agents will run this before making codebase changes.
 #
 # TODO: implement your project's health checks below.
 # Examples:
@@ -180,13 +221,13 @@ function agentsMd(config) {
 
 **${name}** \u2014 ${description}
 
-## Health check (run before starting)
+## Health check (run before making codebase changes)
 
 \`\`\`bash
 bash health.sh
 \`\`\`
 
-If it exits non-zero, stop and report the issue. Do not proceed with tasks until health is green.
+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)
 
@@ -219,7 +260,7 @@ docs.search          query                                  \u2192 search ${docs
 
 \`\`\`
 1. INIT
-   - Run health.sh \u2192 exit 1 means stop
+   - 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
 
@@ -231,7 +272,7 @@ docs.search          query                                  \u2192 search ${docs
 
 3. CLOSE
    - tasks.update(taskId, 'done')
-   - Run health.sh \u2192 must be green before closing
+   - Run health.sh (if changes were made) \u2192 must be green before closing
 \`\`\`
 
 ## Agent roles
@@ -263,13 +304,13 @@ function claudeMd(config) {
 
 **${name}** \u2014 ${description}
 
-## Health check (run before starting)
+## Health check (run before making codebase changes)
 
 \`\`\`bash
 bash health.sh
 \`\`\`
 
-If it exits non-zero, stop and report the issue. Do not proceed with tasks until health is green.
+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)
 
@@ -302,7 +343,7 @@ docs.search          query                                  \u2192 search ${docs
 
 \`\`\`
 1. INIT
-   - Run health.sh \u2192 exit 1 means stop
+   - 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
@@ -315,7 +356,7 @@ docs.search          query                                  \u2192 search ${docs
 
 3. CLOSE
    - tasks.update(taskId, 'done')
-   - Run health.sh \u2192 must be green before closing
+   - Run health.sh (if changes were made) \u2192 must be green before closing
 \`\`\`
 
 ## Agent roles
@@ -450,6 +491,55 @@ function agentReviewerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("reviewer", vars));
   return toCodexToml("reviewer", description, body, "read-only");
 }
+var CLAUDE_CODE_MCP_TOOLS = {
+  lead: [
+    // 'mcp__agent-harness-kit__actions.start',
+    // 'mcp__agent-harness-kit__actions.write',
+    // 'mcp__agent-harness-kit__actions.complete',
+    // 'mcp__agent-harness-kit__actions.get',
+    // 'mcp__agent-harness-kit__actions.record_tool',
+    // 'mcp__agent-harness-kit__tasks.get',
+    // 'mcp__agent-harness-kit__tasks.claim',
+    // 'mcp__agent-harness-kit__tasks.update',
+    // 'mcp__agent-harness-kit__tasks.add',
+  ],
+  explorer: [
+    // 'mcp__agent-harness-kit__actions.start',
+    // 'mcp__agent-harness-kit__actions.write',
+    // 'mcp__agent-harness-kit__actions.complete',
+    // 'mcp__agent-harness-kit__actions.get',
+    // 'mcp__agent-harness-kit__actions.record_tool',
+    // 'mcp__agent-harness-kit__docs.search',
+  ],
+  builder: [
+    // 'mcp__agent-harness-kit__actions.start',
+    // 'mcp__agent-harness-kit__actions.write',
+    // 'mcp__agent-harness-kit__actions.complete',
+    // 'mcp__agent-harness-kit__actions.get',
+    // 'mcp__agent-harness-kit__actions.record_tool',
+    // 'mcp__agent-harness-kit__actions.record_file',
+  ],
+  reviewer: [
+    // 'mcp__agent-harness-kit__actions.start',
+    // 'mcp__agent-harness-kit__actions.write',
+    // 'mcp__agent-harness-kit__actions.complete',
+    // 'mcp__agent-harness-kit__actions.get',
+    // 'mcp__agent-harness-kit__actions.record_tool',
+    // 'mcp__agent-harness-kit__tasks.acceptance.update',
+    // 'mcp__agent-harness-kit__tasks.update',
+  ]
+};
+function translateFrontmatterForClaudeCode(md, agentName) {
+  const mcpTools = CLAUDE_CODE_MCP_TOOLS[agentName] ?? [];
+  const mcpLines = mcpTools.map((t) => `  - ${t}`).join("\n");
+  return md.replace(/(tools:\n(?:  - (?!mcp__)[^\n]+\n)+)/, (match) => {
+    const trimmed = match.trimEnd();
+    return `${trimmed}
+  - Task
+${mcpLines}
+`;
+  });
+}
 var GITIGNORE_ENTRIES = `
 # agent-harness-kit
 .harness/harness.db
@@ -504,12 +594,13 @@ No tasks in progress.
     const projectName = config.project.name;
     const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".claude/agents/lead.md", agentLead({ projectName }));
-    writeAgentFile(cwd2, ".claude/agents/explorer.md", agentExplorer({ projectName, allowedPaths }));
-    writeAgentFile(cwd2, ".claude/agents/builder.md", agentBuilder({ projectName, writablePaths }));
-    writeAgentFile(cwd2, ".claude/agents/reviewer.md", agentReviewer({ projectName }));
-    mergeClaudeMcpJson(join4(cwd2, ".claude/mcp.json"), config.tools.mcp.port);
+    writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead"));
+    writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer"));
+    writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder"));
+    writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer"));
+    mergeClaudeMcpJson(join4(cwd2, ".mcp.json"), config.tools.mcp.port);
     mergeClaudeSettingsJson(join4(cwd2, ".claude/settings.json"));
+    mergeClaudeSettingsLocalJson(join4(cwd2, ".claude/settings.local.json"));
     appendGitignore(cwd2);
   }
   async build(config, cwd2) {
@@ -523,12 +614,13 @@ No tasks in progress.
     const projectName = config.project.name;
     const allowedPaths = (config.agents.explorer.allowedPaths ?? []).join(", ");
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
-    writeAgentFile(cwd2, ".claude/agents/lead.md", agentLead({ projectName }));
-    writeAgentFile(cwd2, ".claude/agents/explorer.md", agentExplorer({ projectName, allowedPaths }));
-    writeAgentFile(cwd2, ".claude/agents/builder.md", agentBuilder({ projectName, writablePaths }));
-    writeAgentFile(cwd2, ".claude/agents/reviewer.md", agentReviewer({ projectName }));
-    mergeClaudeMcpJson(join4(cwd2, ".claude/mcp.json"), config.tools.mcp.port);
+    writeAgentFile(cwd2, ".claude/agents/lead.md", translateFrontmatterForClaudeCode(agentLead({ projectName }), "lead"));
+    writeAgentFile(cwd2, ".claude/agents/explorer.md", translateFrontmatterForClaudeCode(agentExplorer({ projectName, allowedPaths }), "explorer"));
+    writeAgentFile(cwd2, ".claude/agents/builder.md", translateFrontmatterForClaudeCode(agentBuilder({ projectName, writablePaths }), "builder"));
+    writeAgentFile(cwd2, ".claude/agents/reviewer.md", translateFrontmatterForClaudeCode(agentReviewer({ projectName }), "reviewer"));
+    mergeClaudeMcpJson(join4(cwd2, ".mcp.json"), config.tools.mcp.port);
     mergeClaudeSettingsJson(join4(cwd2, ".claude/settings.json"));
+    mergeClaudeSettingsLocalJson(join4(cwd2, ".claude/settings.local.json"));
   }
   async migrate(config, _to, _cwd) {
     void config;
@@ -1636,7 +1728,7 @@ async function runHealth(cwd2) {
 function getProviderHealthFiles(provider) {
   switch (provider) {
     case "claude-code":
-      return { agentsDir: ".claude/agents", agentExtension: ".md", mcpFile: ".claude/mcp.json" };
+      return { agentsDir: ".claude/agents", agentExtension: ".md", mcpFile: ".mcp.json" };
     case "opencode":
       return { agentsDir: ".opencode/agents", agentExtension: ".md", mcpFile: "opencode.json" };
     case "codex-cli":