@cardor/agent-harness-kit 1.6.5 → 1.6.8

package/README.md

@@ -107,7 +107,7 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 ## Features
 
 - **Provider-agnostic** — works with Claude Code, OpenCode, Codex CLI, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
-- **Structured 4-agent workflow** — Lead, Explorer, Builder, and Reviewer each have defined responsibilities and can only act within their role.
+- **Structured 5-agent workflow** — Lead, Explorer, Consultant, Builder, and Reviewer each have defined responsibilities and can only act within their role.
 - **Atomic task claiming** — agents use `tasks.claim()` which uses a SQLite transaction to prevent two agents from picking up the same task at the same time.
 - **Full audit trail** — every action, file touched, tool used, and section written is stored in SQLite and queryable.
 - **Health gate** — agents must run `health.sh` and get a green exit before starting or closing any task. You define what "healthy" means.
@@ -151,7 +151,7 @@ ahk init
 
 ### `ahk init`
 
-Interactive scaffold. Asks for your project name, description, AI provider, whether to install globally, docs path, task adapter, and an optional first task. Creates all harness files in the current directory (or home directory if global).
+Interactive scaffold. Asks for your project name, description, AI provider, docs path, task adapter, and an optional first task. Creates all harness files in the current directory.
 
 ```bash
 ahk init
@@ -163,8 +163,6 @@ ahk init --name "my-app" --provider codex-cli   --docs ./docs --tasks local
 
 Run this once per project. Safe to re-run — it will not overwrite files you've customized.
 
-**Global installation** — if you answer yes to "Install globally?", files go to `~/.claude` (Claude Code), `~/.config/opencode` (OpenCode), or `~/.codex` (Codex CLI). This lets you share one harness config across all your projects.
-
 ---
 
 ### `ahk build`

package/dist/cli.js

@@ -334,7 +334,7 @@ docs.search          query                                  \u2192 search ${docs
    - tasks.get('in_progress') \u2192 resume if something is in progress
    - tasks.get('pending') \u2192 pick lowest id
 
-2. WORK  (lead \u2192 explorer \u2192 builder \u2192 reviewer)
+2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
    - Each agent calls actions.start(taskId, agentName) \u2192 actionId
    - After EVERY tool call: actions.record_tool(actionId, toolName, args, summary)
    - After EVERY file change: actions.record_file(actionId, filePath, operation, notes)
@@ -351,6 +351,7 @@ docs.search          query                                  \u2192 search ${docs
 |-------|---------------|
 | 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 |
 
@@ -418,7 +419,7 @@ docs.search          query                                  \u2192 search ${docs
    - 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 builder \u2192 reviewer)
+2. WORK  (lead \u2192 explorer \u2192 consultant \u2192 builder \u2192 reviewer)
    - Each agent calls actions.start(taskId, agentName) \u2192 actionId
    - After EVERY tool call: actions.record_tool(actionId, toolName, args, summary)
    - After EVERY file change: actions.record_file(actionId, filePath, operation, notes)
@@ -435,6 +436,7 @@ docs.search          query                                  \u2192 search ${docs
 |-------|---------------|
 | 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 |
 
@@ -564,6 +566,10 @@ function agentReviewerToml(vars) {
   const { description, body } = stripFrontmatter(loadAgentTemplate("reviewer", vars));
   return toCodexToml("reviewer", description, body, "read-only");
 }
+function agentConsultantToml(vars) {
+  const { description, body } = stripFrontmatter(loadAgentTemplate("consultant", vars));
+  return toCodexToml("consultant", description, body, "read-only");
+}
 function translateFrontmatterForClaudeCode(md, agentName) {
   const permissionsMap = {
     lead: [...MCP_CLAUDE_PERMISSIONS_LEAD],
@@ -629,10 +635,15 @@ async function syncAgentPermissions(cwd2) {
       continue;
     }
     const content = readFileSync3(filePath, "utf-8");
-    const toolsBlock = `tools:
-${tools.map((t) => `  - ${t}`).join("\n")}
-`;
-    const updated = content.replace(/tools:\n(?:  - [^\n]+\n)*/m, toolsBlock);
+    const updated = content.replace(
+      /(tools:\n)((?:  - [^\n]+\n)*)/m,
+      (_match, header, toolsSection) => {
+        const nativeLines = toolsSection.split("\n").filter((line) => line.trim() && !line.includes("mcp__"));
+        const nativeSection = nativeLines.length ? nativeLines.join("\n") + "\n" : "";
+        const mcpSection = tools.map((t) => `  - ${t}`).join("\n") + "\n";
+        return header + nativeSection + mcpSection;
+      }
+    );
     if (updated === content) {
       console.log(`  ${agent}.md already in sync`);
     } else {
@@ -738,6 +749,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths }));
+    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths }));
     writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName }));
@@ -756,6 +768,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".codex/agents/lead.toml", agentLeadToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/explorer.toml", agentExplorerToml({ projectName, allowedPaths }));
+    writeAgentFile(cwd2, ".codex/agents/consultant.toml", agentConsultantToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/builder.toml", agentBuilderToml({ projectName, writablePaths }));
     writeAgentFile(cwd2, ".codex/agents/reviewer.toml", agentReviewerToml({ projectName }));
     writeAgentFile(cwd2, ".codex/agents/default.toml", agentLeadAsDefaultToml({ projectName }));
@@ -800,6 +813,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
     writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
+    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
     writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
     writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
     mergeOpencodeJson(join6(cwd2, "opencode.json"), config.tools.mcp.port);
@@ -817,6 +831,7 @@ No tasks in progress.
     const writablePaths = (config.agents.builder.writablePaths ?? []).join(", ");
     writeAgentFile(cwd2, ".opencode/agents/lead.md", translateFrontmatterForOpenCode(agentLead({ projectName })));
     writeAgentFile(cwd2, ".opencode/agents/explorer.md", translateFrontmatterForOpenCode(agentExplorer({ projectName, allowedPaths })));
+    writeAgentFile(cwd2, ".opencode/agents/consultant.md", translateFrontmatterForOpenCode(agentConsultant({ projectName })));
     writeAgentFile(cwd2, ".opencode/agents/builder.md", translateFrontmatterForOpenCode(agentBuilder({ projectName, writablePaths })));
     writeAgentFile(cwd2, ".opencode/agents/reviewer.md", translateFrontmatterForOpenCode(agentReviewer({ projectName })));
     mergeOpencodeJson(join6(cwd2, "opencode.json"), config.tools.mcp.port);
@@ -1792,7 +1807,7 @@ async function runHealth(cwd2) {
   if (!dbOk) allOk = false;
   const providerFiles = getProviderHealthFiles(config.provider);
   const agentsDir = providerFiles.agentsDir;
-  const agentNames = ["lead", "explorer", "builder", "reviewer"];
+  const agentNames = ["lead", "explorer", "consultant", "builder", "reviewer"];
   const agentsLabelWidth = "[checking agents] ".length;
   for (let i = 0; i < agentNames.length; i++) {
     const name = agentNames[i];
@@ -1856,7 +1871,6 @@ function getProviderHealthFiles(provider) {
 
 // src/commands/init.ts
 import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync9 } from "fs";
-import { homedir } from "os";
 import { join as join12 } from "path";
 import * as p3 from "@clack/prompts";
 import pc6 from "picocolors";
@@ -2051,18 +2065,6 @@ async function runInit(cwd2, flags) {
     }
     provider = val;
   }
-  let globalInstallation = false;
-  const globalVal = await p3.confirm({
-    message: "Install globally (to home directory)?",
-    initialValue: false
-  });
-  if (p3.isCancel(globalVal)) {
-    p3.cancel("Cancelled.");
-    process.exit(0);
-  }
-  if (globalVal) {
-    globalInstallation = true;
-  }
   let docsPath;
   if (flags.docs) {
     docsPath = flags.docs;
@@ -2137,14 +2139,7 @@ async function runInit(cwd2, flags) {
   try {
     const config = applyConfigDefaults({ name, description, provider, docsPath, tasksAdapter });
     const materializer = getMaterializer(provider);
-    let installDir = cwd2;
-    if (globalInstallation) {
-      if (provider === "claude-code") {
-        installDir = join12(homedir(), ".claude");
-      } else {
-        installDir = join12(homedir(), ".config", "opencode");
-      }
-    }
+    const installDir = cwd2;
     const configContent = configTs({
       name,
       description,
@@ -2173,8 +2168,7 @@ async function runInit(cwd2, flags) {
     p3.log.error(err instanceof Error ? err.message : String(err));
     throw err;
   }
-  const agentHarnessKitDir = globalInstallation ? "home directory" : "current directory";
-  console.log(pc6.green(`\u2713 Scaffolded harness in ${agentHarnessKitDir}`));
+  console.log(pc6.green("\u2713 Scaffolded harness in current directory"));
   const agentsDir = provider === "claude-code" ? ".claude/agents/" : ".opencode/agents/";
   const mcpFile = provider === "claude-code" ? ".claude/mcp.json" : "./opencode.json";
   console.log("");
@@ -2250,7 +2244,7 @@ import { existsSync as existsSync9, readdirSync, rmSync } from "fs";
 import { join as join13, resolve as resolve9 } from "path";
 import * as p5 from "@clack/prompts";
 import pc8 from "picocolors";
-var AGENT_MD_FILES = ["lead", "explorer", "builder", "reviewer"];
+var AGENT_MD_FILES = ["lead", "explorer", "consultant", "builder", "reviewer"];
 async function resetAgentMds(cwd2, provider) {
   const agentDir = provider === "claude-code" ? ".claude/agents" : ".opencode/agents";
   const agentDirPath = resolve9(cwd2, agentDir);