AgentHub/server/lib/lane-agents.js

/**
 * @file Installs a lane's driving instructions. For a `claude` lane that is
 * the ship-feature-lane pipeline's agent templates
 * (qc-local, senior-gate-reviewer) into a lane's own .claude/agents/, so a
 * driving session can launch them by the BARE subagent_type name. Source is
 * the repo's own `agents/` — the same files the agenthub plugin ships, where
 * they resolve as `agenthub:qc-local`; installing them into the lane is what
 * makes the unprefixed name work there too. Plain file I/O except
 * for one git call — resolving where a worktree lane's shared info/exclude
 * actually lives, the same git-dir/git-common-dir distinction E2's
 * lane-sync.js had to get right for info/attributes.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const fs = require("node:fs");
const path = require("node:path");
const { git } = require("./worktree");

const TEMPLATE_DIR = path.join(__dirname, "..", "..", "agents");
const TEMPLATE_FILES = ["qc-local.md", "senior-gate-reviewer.md"];
const EXCLUDE_LINE = ".claude/agents/";

// Codex reads no `.claude/agents/`, so for a codex lane the useful thing to
// install is the one instruction it DOES read: AGENTS.md, the project doc it
// loads from the working directory. Marker-delimited so a reinstall replaces
// exactly this block and never the user's own prose, and appended rather than
// written over an existing file.
const STAGE_BLOCK_START = "<!-- agenthub:stage:start -->";
const STAGE_BLOCK_END = "<!-- agenthub:stage:end -->";
const STAGE_BLOCK = `${STAGE_BLOCK_START}
## Declare your lane stage as you work

This directory is watched by AgentHub. Its pipeline map advances on its own by
*inferring* your stage from your tool calls, but an inference carries no
evidence — the node stays amber, never green. Only your own declaration does:

\`\`\`bash
agenthub stage <stage> --tool codex --evidence "<what is actually done>"
\`\`\`

- Call it at every real transition — starting to plan, starting to implement,
  running tests, opening the PR — not once at the end.
- \`--tool codex\` matters: one directory can back both a \`claude\` lane and a
  \`codex\` lane, and without a tool the command fails rather than guess. Inside
  a pane the dashboard started you need nothing — it carries \`AGENTHUB_LANE_ID\`.
- \`agenthub stage\` warns on stderr and names the valid nodes if a stage matches
  none of this lane's pipeline template.
- If it reports that no lane owns this directory, skip the stage calls and
  carry on. Stage reporting is reporting, never control flow.
- A one-line \`[agenthub]\` reminder may be typed straight into this pane asking for
  evidence on the current stage. That is the dashboard, not the user — treat it
  as the same instruction as this section and make the real call.
${STAGE_BLOCK_END}`;

/** Append the stage block to `<cwd>/AGENTS.md`, or replace an existing one. */
function installStageDoc(cwd) {
  const file = path.join(cwd, "AGENTS.md");
  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
  const start = existing.indexOf(STAGE_BLOCK_START);
  const end = existing.indexOf(STAGE_BLOCK_END);
  const next =
    start !== -1 && end > start
      ? existing.slice(0, start) + STAGE_BLOCK + existing.slice(end + STAGE_BLOCK_END.length)
      : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${STAGE_BLOCK}\n`;
  fs.writeFileSync(file, next);
  return "AGENTS.md";
}

/** The dir shared across every worktree of a repo — where info/exclude
 *  lives (same as info/attributes; MERGE_HEAD/HEAD/the index are the only
 *  per-worktree-private state, not this). */
async function commonGitDir(cwd) {
  const result = await git(cwd, ["rev-parse", "--git-common-dir"]);
  const dir = result.stdout.trim();
  return path.isAbsolute(dir) ? dir : path.join(cwd, dir);
}

/**
 * Copy both agent templates into `<lane.cwd>/.claude/agents/` (overwriting
 * any existing copy — this is a reinstall, not a merge) and idempotently
 * git-exclude that directory in the shared common git dir.
 *
 * A `codex` lane gets the AGENTS.md stage block instead — Codex never reads
 * `.claude/agents/`, and its own working copy is the only channel it does read.
 *
 * @param {{cwd: string, tool?: string}} lane
 * @returns {Promise<{installed: string[]}>}
 */
async function installAgents(lane) {
  if (!fs.existsSync(path.join(lane.cwd, ".git"))) {
    throw Object.assign(new Error(`lane has no .git — not a git repository: ${lane.cwd}`), {
      code: "ENOTGITREPO",
    });
  }

  if (lane.tool === "codex") return { installed: [installStageDoc(lane.cwd)] };

  const dest = path.join(lane.cwd, ".claude", "agents");
  fs.mkdirSync(dest, { recursive: true });
  const installed = [];
  for (const name of TEMPLATE_FILES) {
    fs.copyFileSync(path.join(TEMPLATE_DIR, name), path.join(dest, name));
    installed.push(name);
  }

  const infoDir = path.join(await commonGitDir(lane.cwd), "info");
  fs.mkdirSync(infoDir, { recursive: true });
  const excludePath = path.join(infoDir, "exclude");
  const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, "utf8") : "";
  const lines = existing.split("\n").filter(Boolean);
  if (!lines.includes(EXCLUDE_LINE)) {
    lines.push(EXCLUDE_LINE);
    fs.writeFileSync(excludePath, lines.join("\n") + "\n");
  }

  return { installed };
}

module.exports = { installAgents };