forge-delegate 1.0.4 → 1.0.7

package/README.md

@@ -116,6 +116,17 @@ inline; long ones are auto-backgrounded by Claude Code (past ~2 min) or run deta
 
 Full guide: [docs/DELEGATION.md](docs/DELEGATION.md)
 
+### The `delegate-work` skill
+
+Setup also installs a Claude Code skill (`~/.claude/skills/delegate-work/`, or
+`<project>/.claude/skills/` under `--scope project`). Skip it with `--no-skill`.
+
+It exists because MCP server `instructions` are injected once at session start and
+get buried as the context fills — by turn 30 they lose to whatever is in front of the
+model. A skill description is re-matched against every user turn, so the delegation
+triggers ("write tests for", "rename X everywhere", "fix the lint errors") stay live
+for the whole session instead of decaying.
+
 ## Configuration
 
 Stored in `~/.forge-delegate/config.json`, read fresh on every call — change it anytime without

package/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -35,15 +35,33 @@ function launchArray() {
   return isPublished ? ["npx", "-y", "forge-delegate", "serve"] : [process.execPath, join(here, "cli.mjs"), "serve"];
 }
 
-function registerClaude(launch, scope) {
+// The MCP server's `instructions` are injected once at session start and decay as the
+// context fills. A skill is re-matched against every user turn, so the delegation
+// triggers stay live for the whole session.
+function installClaudeSkill(scope, projectDir) {
+  const src = join(here, "skills", "delegate-work", "SKILL.md");
+  if (!existsSync(src)) return;
+  const root = scope === "user" ? join(homedir(), ".claude") : join(projectDir, ".claude");
+  const dest = join(root, "skills", "delegate-work", "SKILL.md");
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`  \u2713 delegate-work skill (${dest})`);
+}
+
+// `claude mcp` writes .mcp.json relative to its own cwd, so a project-scope install
+// must run from projectDir — otherwise it lands in whatever directory setup was
+// invoked from, and installClaudeSkill (which does honour projectDir) disagrees
+// with it.
+function registerClaude(launch, scope, projectDir) {
+  const opts = scope === "project" ? { cwd: projectDir } : {};
   try {
-    execSync(`claude mcp remove --scope ${scope} forge-delegate`, { stdio: "ignore" });
+    execSync(`claude mcp remove --scope ${scope} forge-delegate`, { ...opts, stdio: "ignore" });
   } catch {}
   try {
-    execSync(`claude mcp remove forge-delegate`, { stdio: "ignore" });
+    execSync(`claude mcp remove forge-delegate`, { ...opts, stdio: "ignore" });
   } catch {}
-  execSync(`claude mcp add --scope ${scope} forge-delegate -- ${launch}`, { stdio: "inherit" });
-  console.log(`  ✓ Claude Code (scope=${scope})`);
+  execSync(`claude mcp add --scope ${scope} forge-delegate -- ${launch}`, { ...opts, stdio: "inherit" });
+  console.log(`  ✓ Claude Code (scope=${scope}${scope === "project" ? `, ${projectDir}` : ""})`);
 }
 
 function codexConfigPath(scope, projectDir) {
@@ -125,7 +143,10 @@ async function setup() {
   // 2. Register with chosen hosts (claude / codex / opencode)
   for (const target of targets) {
     try {
-      if (target === "claude") registerClaude(launch, scope);
+      if (target === "claude") {
+        registerClaude(launch, scope, projectDir);
+        if (!flags["no-skill"]) installClaudeSkill(scope, projectDir);
+      }
       else if (target === "codex") registerCodex(launchArr, scope, projectDir);
       else if (target === "opencode") registerOpencode(launchArr, scope, projectDir);
       else console.log(`  ✗ unknown target '${target}' (use claude,codex,opencode)`);
@@ -169,7 +190,6 @@ function configCmd(argv) {
     if (flags.variant) patch.defaultVariant = flags.variant;
     if (flags.timeout) patch.timeoutMs = Number(flags.timeout) * 1000;
     if (flags.dir) patch.defaultDirectory = flags.dir;
-    if (flags["default-dir"]) patch.defaultDirectory = flags["default-dir"];
     if (flags.autoApprove !== undefined) patch.autoApprove = flags.autoApprove === "true" || flags.autoApprove === "1" || flags.autoApprove === true;
     saveConfig(patch);
     console.log(`updated ${configPath()}`);
@@ -236,8 +256,9 @@ forge-delegate — delegate coding work from Claude Code/Codex/opencode to other
 
 Usage:
   forge-delegate setup [--model provider/model] [--targets claude,codex,opencode]
-                       [--scope user|project] [--project-dir <path>]
+                       [--scope user|project] [--project-dir <path>] [--no-skill]
                                              Interactive setup; flags optional (run bare to be prompted)
+                                             --no-skill skips installing the delegate-work skill
   forge-delegate serve                        Start the MCP server (used internally by agents)
   forge-delegate config get                   Show current configuration
   forge-delegate config set --model <m> [--agent <a>] [--variant <v>]

package/install.sh

@@ -12,6 +12,7 @@
 #   --targets a,b,c          hosts to register with: claude,codex,opencode (default all)
 #   --scope user|project     registration scope (default user)
 #   --project-dir <path>     project for --scope project (default current dir)
+#   --no-skill               skip installing the delegate-work skill for Claude Code
 #   --no-opencode            skip auto-installing opencode if missing
 #   --no-npx                 skip the npx route, force clone/checkout
 #   --help
@@ -23,6 +24,7 @@ SCOPE="user"
 PROJECT_DIR=""
 NO_OPENCODE=0
 NO_NPX=0
+NO_SKILL=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -34,10 +36,11 @@ while [[ $# -gt 0 ]]; do
     --scope=*) SCOPE="${1#*=}"; shift ;;
     --project-dir) PROJECT_DIR="${2:-}"; shift 2 ;;
     --project-dir=*) PROJECT_DIR="${1#*=}"; shift ;;
+    --no-skill) NO_SKILL=1; shift ;;
     --no-opencode) NO_OPENCODE=1; shift ;;
     --no-npx) NO_NPX=1; shift ;;
     --help|-h)
-      sed -n '3,18p' "$0"
+      sed -n '3,19p' "$0"
       exit 0 ;;
     *) echo "unknown option: $1"; exit 1 ;;
   esac
@@ -68,6 +71,7 @@ fi
 ARGS=(--targets "$TARGETS" --scope "$SCOPE")
 if [[ -n "$MODEL" ]]; then ARGS+=(--model "$MODEL"); fi
 if [[ "$SCOPE" == "project" ]]; then ARGS+=(--project-dir "$PROJECT_DIR"); fi
+if [[ "$NO_SKILL" -eq 1 ]]; then ARGS+=(--no-skill); fi
 
 # 3. Preferred route: published npm package (works on Windows, always latest)
 if [[ "$NO_NPX" -eq 0 ]] && command -v npx >/dev/null 2>&1; then

package/lib.mjs

@@ -1,10 +1,8 @@
-import { execFile, spawn } from "node:child_process";
-import { promisify } from "node:util";
+import { spawn } from "node:child_process";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-const execFileAsync = promisify(execFile);
 export const OPENCODE_TIMEOUT = Number(process.env.FORGE_OPENCODE_TIMEOUT ?? 900_000);
 const CONFIG_DIR = join(homedir(), ".forge-delegate");
 const AUTH_PATH = join(homedir(), ".local/share/opencode/auth.json");
@@ -344,14 +342,3 @@ export async function runOne(model, prompt) {
   throw new Error(`unknown model '${model}' — see list_models`);
 }
 
-export async function gitDiff() {  try {
-    const { stdout } = await execFileAsync("git", ["diff", "HEAD"], {
-      cwd: process.cwd(),
-      maxBuffer: 5 * 1024 * 1024,
-    });
-    return stdout.trim();
-  } catch {
-    return null;
-  }
-}
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-delegate",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "MCP server that relays coding work to other AI models (DeepSeek, Gemini, OpenAI, Ollama) so Claude Code saves tokens",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "server.mjs",
     "lib.mjs",
     "install.sh",
+    "skills/",
     "docs/",
     "README.md"
   ],

package/server.mjs

@@ -4,13 +4,13 @@ import { z } from "zod";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdirSync, writeFileSync, readFileSync, existsSync, openSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import {
   logUsage,
   opencodeRun,
   runOne,
-  gitDiff,
   opencodeArgs,
   parseEvents,
   pickVariant,
@@ -24,25 +24,63 @@ import {
 
 const execFileAsync = promisify(execFile);
 const RUNS_DIR = join(homedir(), ".forge-delegate", "runs");
+const here = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(here, "package.json"), "utf8")).version;
 
-const INSTRUCTIONS = `forge-delegate gives you a crew of external AI models to delegate coding work to. Hand off the high-volume, low-risk work (boilerplate, tests, lint/type fixes, mechanical edits) to a cheap or free model and keep the expensive agent focused on architecture and judgment calls.
+// The server auto-updates (npx re-resolves latest on each spawn) but the installed
+// skill is a file on disk that only `setup` rewrites — so a published skill change
+// goes unnoticed. Compare the two and say so, rather than running stale in silence.
+function skillStatus() {
+  const src = join(here, "skills", "delegate-work", "SKILL.md");
+  if (!existsSync(src)) return null;
+  const dests = [
+    join(homedir(), ".claude", "skills", "delegate-work", "SKILL.md"),
+    join(process.cwd(), ".claude", "skills", "delegate-work", "SKILL.md"),
+  ];
+  const installed = dests.filter(existsSync);
+  if (!installed.length) return { state: "missing", detail: "not installed" };
+  const want = readFileSync(src, "utf8");
+  const stale = installed.filter((d) => readFileSync(d, "utf8") !== want);
+  return stale.length
+    ? { state: "stale", detail: `out of date: ${stale.join(", ")}` }
+    : { state: "ok", detail: "up to date" };
+}
+
+const SKILL_STATUS = skillStatus();
+if (SKILL_STATUS && SKILL_STATUS.state !== "ok") {
+  // stderr only — stdout is the JSON-RPC channel.
+  process.stderr.write(
+    `forge-delegate: delegate-work skill ${SKILL_STATUS.detail}. Run: npx -y forge-delegate setup\n`
+  );
+}
 
-COST POLICY — MANDATORY, NON-NEGOTIABLE:
-The user pays per delegated call on a budget plan. You MUST pick only cheap or free models for EVERY delegation (ask_model, delegate). NEVER pick top-tier, premium, flagship, or frontier models — not even "just this once" or for hard tasks. If a task seems too hard for a cheap model, split it into smaller delegated steps instead of upgrading. Run list_models and prefer free/cheap models (deepseek flash tiers, free opencode models, local ollama).
+const INSTRUCTIONS = `forge-delegate hands coding work to cheap external models running as full agents. They read the project and write the code in their own loop, so the work never passes through your context. Spend your context on judgment; delegate the typing.
+
+DELEGATE BY DEFAULT — do not hand-write these yourself:
+- Tests for code that already exists.
+- Mechanical refactors: renames, signature changes, import rewrites, API migrations.
+- Lint, type, and build errors — paste the error output and delegate the fix.
+- Boilerplate: CRUD endpoints, config and schema files, adapters, fixtures, scaffolding.
+- Ports and translations between languages, frameworks, or file formats.
+- The same edit repeated across 3 or more files.
+- Reading a large file or directory to answer one narrow question — delegate the reading, keep your context clean.
+- The survey half of an audit ("does this follow X standards", "is this secure", "where is the tech debt", "how does X work"). Delegate the gathering, keep the verdict: ask for a structured digest with a file path behind every claim, then judge it yourself. A claim with no path is not a finding.
+
+KEEP FOR YOURSELF: architecture, debugging an unknown root cause, security-sensitive code, anything where being wrong is expensive, and the verdict on whatever comes back. Delegation does not transfer responsibility for the result.
 
 Routing:
-- Quick one-shot questions → ask_model (direct API, no file access).
-- Multi-file edits/refactors/tests → delegate (inline by default; Claude Code auto-backgrounds calls past 2 min).
-- Parallel or fire-and-forget → delegate with background:true (returns a job id instantly); poll check_delegation for the result.
-- Follow-ups on a delegated area: pass the returned session id as continue_session.
-- Omit model/directory to use the configured defaults (get_delegate_config); change them anytime with set_delegate_config — never reinstall.
-- Never paste large files into your own context for delegation — delegate and let the agent read files itself.
-
-The per-tool descriptions are the authoritative reference.
+- One-shot question, no file access needed -> ask_model.
+- Anything touching files -> delegate (inline; Claude Code auto-backgrounds calls past 2 minutes).
+- Parallel fan-out or long jobs -> delegate with background:true, then poll check_delegation.
+- Follow-up in the same area -> pass the previous session id as continue_session.
+- Omit model/directory/agent: the configured defaults are already correct (get_delegate_config to see them, set_delegate_config to change them — never reinstall).
+- Never paste file contents into a task. Name the paths; the agent reads them itself.
+
+Cost: the configured default model is already a cheap or free tier — just use it. Do not override \`model\` upward to a premium or flagship tier; if a task looks too big for the default, split it into smaller delegations instead.
 `;
 
 const server = new McpServer(
-  { name: "forge-delegate", version: "1.0.0" },
+  { name: "forge-delegate", version: VERSION },
   { instructions: INSTRUCTIONS }
 );
 
@@ -79,7 +117,22 @@ async function startBackgroundJob(model, task, opts = {}) {
     stdio: ["ignore", out, out],
   });
   child.unref();
-  writeFileSync(join(RUNS_DIR, `${id}.json`), JSON.stringify({ id, pid: child.pid, model, directory: cwd, started: Date.now(), logPath }));
+  const started = Date.now();
+  const deadline = opts.timeoutMs ? started + opts.timeoutMs : null;
+  if (deadline) {
+    setTimeout(() => {
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {}
+      try {
+        process.kill(child.pid, "SIGKILL");
+      } catch {}
+    }, opts.timeoutMs).unref();
+  }
+  writeFileSync(
+    join(RUNS_DIR, `${id}.json`),
+    JSON.stringify({ id, pid: child.pid, model, directory: cwd, started, deadline, logPath })
+  );
   return id;
 }
 
@@ -120,7 +173,7 @@ server.tool(
 
 server.tool(
   "ask_model",
-  "Send a one-shot prompt to an external AI model and get its raw response. Fast direct API call; the model has NO file access and CANNOT take actions. For work requiring tools/files use delegate instead. model defaults to the configured defaultModel.",
+  "USE THIS INSTEAD OF ANSWERING FROM YOUR OWN REASONING when the question is self-contained and cheap to verify: a syntax or API detail, a regex, a short snippet, a second opinion on a design, a summary of text you already have. Sends a one-shot prompt to an external model and returns its raw response. Fast direct API call; the model has NO file access and CANNOT take actions — for anything touching files use delegate instead. Omit model to use the configured default (already a cheap tier).",
   {
     model: z.string().optional().describe("provider/model, e.g. deepseek/deepseek-v4-flash, ollama:llama3 (defaults to config defaultModel)"),
     prompt: z.string(),
@@ -137,7 +190,7 @@ server.tool(
 
 server.tool(
   "delegate",
-  "Delegate a coding task to another AI model running as a full agent (via local opencode): it reads your project, explores, and writes concrete code in its own tool loop — invisible to the caller's context. Runs INLINE by default (the result is returned in your context when done; Claude Code auto-backgrounds calls running past 2 minutes). Pass background:true to run detached and return a job id instantly, then poll check_delegation for the result — use that for parallel fan-out or hosts that block on long calls. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Optionally attach specific files in inline mode. model/directory/agent/autoApprove default from config.",
+  "USE THIS INSTEAD OF WRITING THE CODE YOURSELF when the task is: tests for code that already exists; a mechanical refactor (rename, signature change, import rewrite, API migration); fixing lint/type/build errors; boilerplate or scaffolding (CRUD endpoints, config, schemas, adapters, fixtures); a port between languages or frameworks; the same edit repeated across 3 or more files; reading a large file/directory to answer one narrow question; or the survey half of an audit (delegate the gathering, keep the verdict — demand a file path behind every claim). Hands the task to another AI model running as a full agent via local opencode: it reads your project, explores, and writes concrete code in its own tool loop — none of which enters your context. Keep architecture, unknown-root-cause debugging, and security-sensitive code for yourself, and always review what comes back. Runs INLINE by default (result returned when done; Claude Code auto-backgrounds calls past 2 minutes). Pass background:true to run detached and get a job id instantly, then poll check_delegation — use that for parallel fan-out or hosts that block on long calls. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Never paste file contents into task: name the paths and let the agent read them. model/directory/agent/autoApprove default from config — omit them.",
   {
     model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
     task: z.string(),
@@ -159,6 +212,7 @@ server.tool(
           directory: r.directory,
           agent: r.agent,
           autoApprove: r.autoApprove,
+          timeoutMs: r.timeoutMs,
         });
         return `Started background job ${id}. Poll with check_delegation(id: "${id}").`;
       });
@@ -202,7 +256,9 @@ server.tool(
       const parsed = parseEvents(log);
       const tail = parsed.text || "(agent still thinking, no text output yet)";
       const footer = parsed.sessionId ? ` · session: ${parsed.sessionId}` : "";
-      return `[${running ? "RUNNING" : "DONE"}] ${id} (${meta.model}, ${Math.round((Date.now() - meta.started) / 1000)}s)${footer}\n\n${tail.slice(-8000)}`;
+      let status = running ? "RUNNING" : "DONE";
+      if (meta.deadline && Date.now() > meta.deadline) status = "TIMED OUT";
+      return `[${status}] ${id} (${meta.model}, ${Math.round((Date.now() - meta.started) / 1000)}s)${footer}\n\n${tail.slice(-8000)}`;
     })
 );
 
@@ -215,7 +271,8 @@ server.tool(
     const { profiles, ...rest } = cfg;
     const lines = Object.entries(rest).map(([k, v]) => `  ${k}: ${v ?? "(unset)"}`);
     const prof = Object.entries(profiles).map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`).join("\n") || "  (none)";
-    return { content: [{ type: "text", text: `config: ${configPath()}\n${lines.join("\n")}\nprofiles:\n${prof}` }] };
+    const skill = SKILL_STATUS ? `\nskill (delegate-work): ${SKILL_STATUS.detail}${SKILL_STATUS.state === "ok" ? "" : " — run: npx -y forge-delegate setup"}` : "";
+    return { content: [{ type: "text", text: `config: ${configPath()}\n${lines.join("\n")}\nprofiles:\n${prof}${skill}` }] };
   }
 );
 

package/skills/delegate-work/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: delegate-work
+description: Hand a coding task to a cheap external model via forge-delegate instead of writing it yourself. Load BEFORE starting work that is high-volume and low-judgment - writing tests for code that already exists, mechanical refactors (renames, signature changes, import rewrites, API migrations), fixing lint/type/build errors, boilerplate and scaffolding (CRUD endpoints, config files, schemas, adapters, fixtures), porting code between languages or frameworks, the same edit repeated across 3 or more files, or reading a large file or directory to answer one narrow question. ALSO load for audit and survey questions - "does my codebase follow X", "audit", "review the architecture", "is this idiomatic", "where is the tech debt", "is this secure", "explore the codebase", "how does X work", "find where" - where the reading is wide but the judgment is narrow: delegate the survey, keep the verdict. Triggers on - "write tests for", "add tests", "rename X to Y everywhere", "refactor", "migrate", "port this to", "fix the lint errors", "fix the type errors", "scaffold", "boilerplate", "do the same for the other files".
+---
+
+# Delegating work to a cheap model
+
+`forge-delegate` runs another AI model as a full agent over this project. It reads
+files, explores, and writes code in its own tool loop. None of that passes through
+your context — you get back a summary and a diff on disk.
+
+The point is not to save the user money on your tokens. It is that your context is
+the scarce resource in a long session, and mechanical work burns it fast.
+
+## Decide
+
+Delegate when the task is **high-volume and low-judgment**: the shape of the correct
+answer is already known, and the work is typing it out across files.
+
+| Delegate | Keep |
+|---|---|
+| Tests for code that already exists | Deciding what behaviour to test |
+| Rename / signature change / import rewrite across files | Designing the new interface |
+| Fixing lint, type, or build errors | Debugging an unknown root cause |
+| CRUD endpoints, config, schemas, fixtures, adapters | Architecture and data modelling |
+| Porting between languages or frameworks | Security-sensitive code |
+| The same edit repeated across 3+ files | The first instance, so the pattern is right |
+| Reading a big file to answer one question | Anything where being wrong is expensive |
+
+Delegating does not transfer responsibility. Review what comes back before you
+report it as done.
+
+## Delegate the survey, keep the verdict
+
+An audit looks like judgment work, so it reads as "keep" — but only the *verdict* is
+judgment. The input gathering is mechanical, wide, and the single most expensive
+thing you can do to your own context. Split them:
+
+1. **Delegate the survey.** Ask for a structured digest, not an opinion:
+   "Report which framework this repo uses. List every routing and data-fetching
+   entry point: path, 3-line summary. Paths only, no assessment."
+2. **Keep the verdict.** Judge the digest yourself. You are now reading a page
+   instead of a repo, and the expensive-if-wrong part never left your hands.
+
+This covers "does this follow X standards", "is this secure", "where is the tech
+debt", "how does X work", "explore the codebase" — broad read, narrow judgment.
+
+**Demand paths as evidence.** A survey's worth depends on the cheap model reporting
+*absence* honestly, and "there is no Next.js here" is exactly the answer a weak model
+is least likely to give — it will produce a plausible audit of a framework you do not
+use rather than contradict the question's premise. Require a file path for every
+claim. A claim with no path attached is not a finding; spot-check two of them before
+you trust the rest.
+
+## Do it
+
+1. Do the judgment part yourself first — decide the interface, write the first
+   instance, name the files.
+2. Call `delegate` with a task that names paths. **Never paste file contents into
+   the task**; the agent reads them itself. That is the whole point.
+3. Omit `model`, `directory`, and `agent` — the configured defaults are already a
+   cheap or free tier. Do not raise `model` to a premium tier; if the task is too
+   big for the default, split it into smaller delegations.
+4. Review the result. Run the tests or the build yourself.
+
+```
+delegate(task: "Write unit tests for the exported functions in src/parser.ts.
+                Follow the style of tests/lexer.test.ts. Cover the error paths.")
+```
+
+Parallel or long-running work: `background: true` returns a job id immediately,
+then poll `check_delegation(id)`. Follow-up in the same area: pass the previous
+`session: <id>` back as `continue_session` so the agent skips re-exploring.
+
+For a question that needs no file access at all — a syntax detail, a regex, a
+second opinion — use `ask_model` instead; it is a direct API call with no agent loop.
+
+## Don't
+
+- Don't delegate a task you cannot describe precisely. Vague task, vague diff.
+- Don't delegate and walk away. Unreviewed delegated code is worse than no code.
+- Don't paste large files into the task text.
+- Don't accept a survey finding with no file path behind it.
+- Don't override `model` upward because a task "seems hard" — split it instead.