@jjlabsio/claude-crew 0.1.32 → 0.1.34

package/scripts/lib/installHooks.mjs

@@ -0,0 +1,136 @@
+import { execFileSync } from "node:child_process";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const MANAGED_BLOCK = [
+  "# >>> crew-agent-runner managed >>>",
+  "node scripts/crew-agent-runner.mjs validate || {",
+  "  echo \"crew-agent-runner: validate failed. Run 'node scripts/crew-agent-runner.mjs build' to fix drift.\" >&2",
+  "  exit 1",
+  "}",
+  "# <<< crew-agent-runner managed <<<"
+].join("\n");
+
+const START_MARKER = "# >>> crew-agent-runner managed >>>";
+const END_MARKER = "# <<< crew-agent-runner managed <<<";
+const BASH_SHEBANG = "#!/usr/bin/env bash";
+
+export async function installHooks({ root = process.cwd() } = {}) {
+  const projectRoot = resolve(root);
+  if (!(await isPluginSourceRepo(projectRoot))) {
+    throw new Error(
+      "install-hooks is for claude-crew plugin developers only. " +
+        "End users do not need this command (build/validate are dev tools). " +
+        "If you are developing claude-crew, run from the plugin source repo root."
+    );
+  }
+
+  const hooksDir = await resolveHooksDir(projectRoot);
+  const hookPath = join(hooksDir, "pre-commit");
+  await mkdir(hooksDir, { recursive: true });
+
+  const existing = await readUtf8OrNull(hookPath);
+  const base = ensureShebang(existing ?? "");
+  const next = upsertManagedBlock(base, MANAGED_BLOCK);
+
+  if (next !== existing) {
+    await writeFile(hookPath, next, "utf8");
+  }
+  await chmod(hookPath, 0o755);
+
+  return { hookPath };
+}
+
+async function isPluginSourceRepo(root) {
+  try {
+    const pluginJsonPath = join(root, ".claude-plugin", "plugin.json");
+    const packageJsonPath = join(root, "package.json");
+    const pluginJsonStat = await stat(pluginJsonPath);
+    const packageJsonStat = await stat(packageJsonPath);
+    if (!pluginJsonStat.isFile() || !packageJsonStat.isFile()) {
+      return false;
+    }
+
+    const pkg = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return pkg.name === "@jjlabsio/claude-crew";
+  } catch {
+    return false;
+  }
+}
+
+export function ensureShebang(content) {
+  if (content.startsWith("#!")) {
+    return content;
+  }
+
+  return `${BASH_SHEBANG}\n${content}`;
+}
+
+export function upsertManagedBlock(content, block) {
+  const start = content.indexOf(START_MARKER);
+  if (start !== -1) {
+    const end = content.indexOf(END_MARKER, start + START_MARKER.length);
+    if (end !== -1) {
+      const afterEnd = end + END_MARKER.length;
+      return `${content.slice(0, start)}${block}${content.slice(afterEnd)}`;
+    }
+  }
+
+  const separator = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+  return `${content}${separator}${block}\n`;
+}
+
+async function resolveHooksDir(projectRoot) {
+  const configuredHooksPath = readConfiguredHooksPath(projectRoot);
+  if (configuredHooksPath) {
+    return isAbsolute(configuredHooksPath)
+      ? configuredHooksPath
+      : resolve(projectRoot, configuredHooksPath);
+  }
+
+  const dotGit = join(projectRoot, ".git");
+  try {
+    const dotGitStat = await stat(dotGit);
+    if (dotGitStat.isDirectory()) {
+      return join(dotGit, "hooks");
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return join(dotGit, "hooks");
+    }
+    throw error;
+  }
+
+  const gitFile = await readFile(dotGit, "utf8");
+  const match = /^gitdir:\s*(.+)\s*$/m.exec(gitFile);
+  if (!match) {
+    throw new Error(".git is not a directory or gitdir file");
+  }
+
+  const gitDir = match[1];
+  return join(isAbsolute(gitDir) ? gitDir : resolve(dirname(dotGit), gitDir), "hooks");
+}
+
+function readConfiguredHooksPath(projectRoot) {
+  try {
+    const hooksPath = execFileSync(
+      "git",
+      ["-C", projectRoot, "config", "--get", "core.hooksPath"],
+      { encoding: "utf8" }
+    ).trim();
+    return hooksPath || null;
+  } catch {
+    return null;
+  }
+}
+
+async function readUtf8OrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}

package/scripts/lib/pluginRoot.mjs

@@ -0,0 +1,10 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const PLUGIN_ROOT = resolve(HERE, "..", "..");
+
+export function pluginPath(...segments) {
+  return resolve(PLUGIN_ROOT, ...segments);
+}

package/scripts/lib/render.mjs

@@ -0,0 +1,110 @@
+export function renderPrompt(input) {
+  const { role, request = {}, contract = {} } = input;
+  const parts = [
+    `# ${titleCase(role)}`,
+    section("Capability", renderCapability(contract)),
+    section("Inputs", renderInputs(request.inputs, contract.inputs?.denied)),
+    section("Outputs", renderJson(contract.outputs)),
+    section("Instructions", request.instruction, { required: true }),
+    section("Success Gate", request.successGate),
+    section("Failure Handling", request.failureHandling)
+  ].filter(Boolean);
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+export function section(title, body, options = {}) {
+  const renderedBody = normalizeBody(body);
+  if (renderedBody.length === 0) {
+    if (options.required) {
+      return `## ${title}`;
+    }
+    return "";
+  }
+
+  return `## ${title}\n${renderedBody}`;
+}
+
+export function fenceBlock(body, fence = "---") {
+  return `${fence}\n${normalizeBlockBody(body)}\n${fence}`;
+}
+
+function renderCapability(contract) {
+  const tools = Array.isArray(contract.claudeSubagent?.tools)
+    ? contract.claudeSubagent.tools
+    : [];
+  const outputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+
+  return [
+    `workspaceAccess: ${contract.capabilities?.workspaceAccess ?? "unknown"}`,
+    `canAskUser: ${String(tools.includes("AskUserQuestion"))}`,
+    `canRequestAgent: ${String(tools.includes("Agent"))}`,
+    `canUseShell: ${String(tools.includes("Bash"))}`,
+    `canWriteCrewFiles: ${String(canWriteCrewFiles(outputs))}`
+  ].join("\n");
+}
+
+function renderInputs(inputs, denied) {
+  const lines = [];
+
+  if (Array.isArray(inputs) && inputs.length > 0) {
+    for (const item of inputs) {
+      lines.push(`### ${item.path}`);
+      lines.push(item.content ?? "");
+    }
+  }
+
+  if (Array.isArray(denied) && denied.length > 0) {
+    lines.push("### Denied Inputs");
+    for (const item of denied) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderJson(value) {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return JSON.stringify(value, null, 2);
+}
+
+function normalizeBody(body) {
+  if (body === undefined || body === null) {
+    return "";
+  }
+
+  return String(body).trim();
+}
+
+function normalizeBlockBody(body) {
+  if (body === undefined || body === null) {
+    return "";
+  }
+
+  return String(body)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n+$/g, "");
+}
+
+function titleCase(value) {
+  return String(value)
+    .split("-")
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join("-");
+}
+
+function canWriteCrewFiles(outputs) {
+  return outputs.some((output) => {
+    return (
+      output?.type === "artifact" &&
+      typeof output.target === "string" &&
+      output.target.startsWith(".crew/")
+    );
+  });
+}

package/scripts/lib/renderFollowup.mjs

@@ -0,0 +1,51 @@
+import { fenceBlock } from "./render.mjs";
+
+export function renderFollowup({ previousResult, newInput } = {}) {
+  return [
+    "## 이전 결과",
+    `status: ${normalizeInline(previousResult?.status)}`,
+    `summary: ${normalizeInline(previousResult?.summary)}`,
+    "artifact:",
+    fenceBlock(serializeArtifact(previousResult?.artifact)),
+    "",
+    "## 추가 입력",
+    normalizeBlock(newInput),
+    "",
+    "## 지시",
+    "계속 진행해라."
+  ].join("\n") + "\n";
+}
+
+function serializeArtifact(artifact) {
+  if (artifact === undefined || artifact === null) {
+    return "";
+  }
+
+  if (typeof artifact === "string") {
+    return artifact;
+  }
+
+  return JSON.stringify(artifact, null, 2);
+}
+
+function normalizeInline(value) {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return String(value)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n/g, " ");
+}
+
+function normalizeBlock(value) {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return String(value)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n+$/g, "");
+}

package/scripts/lib/resolve.mjs

@@ -0,0 +1,72 @@
+const PROVIDERS = new Set(["claude", "codex"]);
+
+export function resolveRole(input) {
+  const { role, catalog, userConfig = {}, projectConfig = {}, contracts } = input;
+  const contract = findContract(role, contracts);
+
+  if (!contract) {
+    throw new Error(`Unknown role: ${role}`);
+  }
+
+  const defaults = cascadeRoleConfig(role, catalog, userConfig, projectConfig);
+  const provider = defaults.provider;
+  if (!PROVIDERS.has(provider)) {
+    throw new Error(`Unknown provider for role ${role}: ${provider}`);
+  }
+
+  const model = defaults.model;
+  if (typeof model !== "string" || model.length === 0) {
+    throw new Error(`Missing model for role ${role}`);
+  }
+
+  const codexSandbox = catalog?.agent_runtime?.[role]?.codex_sandbox;
+  if (!["read-only", "workspace-write"].includes(codexSandbox)) {
+    throw new Error(`Missing codex_sandbox for role ${role}`);
+  }
+
+  const warnings = [];
+  const workspaceAccess = contract?.capabilities?.workspaceAccess;
+  if (codexSandbox !== workspaceAccess) {
+    warnings.push(
+      `${role}: codex_sandbox ${codexSandbox} does not match contract capabilities.workspaceAccess ${workspaceAccess}`
+    );
+  }
+
+  return {
+    role,
+    provider,
+    model,
+    reasoning: provider === "codex" ? defaults.reasoning ?? null : null,
+    codex_sandbox: codexSandbox,
+    contract,
+    dispatch: {
+      path: provider === "codex" ? "codex" : "claude",
+      write: codexSandbox === "workspace-write"
+    },
+    warnings
+  };
+}
+
+function cascadeRoleConfig(role, ...configs) {
+  return configs.reduce((merged, config) => {
+    return {
+      ...merged,
+      ...roleConfig(config, role)
+    };
+  }, {});
+}
+
+function roleConfig(config, role) {
+  return {
+    ...(config?.agent_defaults?.[role] ?? {}),
+    ...(config?.providers?.[role] ?? {})
+  };
+}
+
+function findContract(role, contracts) {
+  if (Array.isArray(contracts?.roles)) {
+    return contracts.roles.find((contract) => contract.role === role);
+  }
+
+  return contracts?.[role];
+}

package/scripts/lib/validate.mjs

@@ -0,0 +1,100 @@
+import { readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+import { deriveBuildOutput, resolveBuildInputs } from "./build.mjs";
+import { loadContracts } from "./contracts.mjs";
+
+export async function validate({ root = process.cwd() } = {}) {
+  const projectRoot = resolve(root);
+  const inputs = resolveBuildInputs(projectRoot);
+  const errors = [];
+
+  const contracts = loadContracts(inputs.contractsPath);
+  const catalog = JSON.parse(await readFile(inputs.catalogPath, "utf8"));
+  const derived = await deriveBuildOutput({
+    root: projectRoot,
+    contracts,
+    instructionsDir: inputs.instructionsDir,
+    pluginPath: inputs.pluginPath
+  });
+
+  errors.push(
+    ...(await compareDerived({
+      root: projectRoot,
+      pluginPath: inputs.pluginPath,
+      derived
+    }))
+  );
+  errors.push(...compareSandboxConsistency({ contracts, catalog }));
+
+  return { ok: errors.length === 0, errors };
+}
+
+export async function compareDerived({ root, pluginPath, derived }) {
+  const errors = [];
+
+  for (const [role, expected] of derived.agents.entries()) {
+    const relPath = `agents/${role}.md`;
+    const actual = await readUtf8OrNull(join(root, relPath));
+    if (actual !== expected) {
+      errors.push(`drift: ${relPath}`);
+    }
+  }
+
+  const actualPlugin = await readUtf8OrNull(pluginPath);
+  if (actualPlugin !== derived.pluginJson) {
+    errors.push(await pluginDriftMessage({ root, pluginPath, actualPlugin }));
+  }
+
+  return errors;
+}
+
+export function compareSandboxConsistency({ contracts, catalog }) {
+  const errors = [];
+
+  for (const contract of contracts.roles) {
+    const role = contract.role;
+    const workspaceAccess = contract.capabilities?.workspaceAccess;
+    const codexSandbox = catalog.agent_runtime?.[role]?.codex_sandbox;
+    if (workspaceAccess !== codexSandbox) {
+      errors.push(
+        `mismatch: ${role} workspaceAccess=${workspaceAccess} but codex_sandbox=${codexSandbox}`
+      );
+    }
+  }
+
+  return errors;
+}
+
+async function pluginDriftMessage({ root, pluginPath, actualPlugin }) {
+  const label = pluginLabel(root, pluginPath);
+  if (actualPlugin === null) {
+    return `drift: ${label}`;
+  }
+
+  try {
+    const plugin = JSON.parse(actualPlugin);
+    if (!Array.isArray(plugin.agents)) {
+      return `drift: ${label} agents`;
+    }
+    return `drift: ${label} agents`;
+  } catch {
+    return `drift: ${label}`;
+  }
+}
+
+function pluginLabel(root, pluginPath) {
+  const relPath = relative(root, pluginPath);
+  return relPath === ".claude-plugin/plugin.json" ? "plugin.json" : relPath;
+}
+
+async function readUtf8OrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}

package/skills/crew-agent-runner/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: crew-agent-runner
+description: 모든 crew 에이전트 dispatch의 중앙 규약 — provider별 호출법 캡슐화
+---
+
+# crew-agent-runner
+
+crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구현하지 않고 이 중앙 규약을 따른다. 본 스킬은 resolve, dispatch, resume, followup 주입, retry/fallback/escalate 판단의 공통 표면을 정의한다.
+
+설치 후 drift 차단용 pre-commit hook은 `node scripts/crew-agent-runner.mjs install-hooks`로 설치한다.
+(plugin 개발자 전용 — 사용자는 호출하지 않습니다. build/validate는 plugin source repo의 drift 차단 도구입니다.)
+
+## Dispatch 절차
+
+업무 스킬(crew-plan/crew-interview/crew-dev)이 role을 실행해야 할 때 본 절차를 따른다.
+
+### 1. resolve
+
+오케스트레이터는 먼저 `node scripts/crew-agent-runner.mjs resolve --role <role> --json`을 실행하여 provider/model/contract 통합 표를 받는다.
+
+### 2. request 객체 작성
+
+`{ role, inputs (path+content), instruction, successGate, failureHandling, taskId }` 형태의 임시 JSON 파일을 작성한다.
+
+### 3a. Codex 경로
+
+`provider == codex`이면 `node scripts/crew-agent-runner.mjs dispatch --role <role> --request-file <path> --json`을 실행한다. 이 명령은 AgentResult JSON을 즉시 반환한다.
+dispatch CLI는 codex provider role에만 사용. claude provider role은 render + Agent tool 경로를 사용.
+
+### 3b. Claude 경로
+
+`provider == claude`이면 다음 순서로 실행한다.
+
+1. `node scripts/crew-agent-runner.mjs render --role <role> --request-file <path>`를 실행하여 prompt 문자열을 받는다.
+2. 메인 오케스트레이터(Claude conversation)가 `Agent(subagent_type=<role>, model=<model>, prompt=<rendered>)`를 호출한다.
+3. sub-agent 결과를 AgentResult JSON 형식으로 정규화한다.
+
+## AgentResult 상태 처리
+
+AgentResult 5상태:
+
+### complete
+
+`artifact`를 `outputs.target`에 저장한다. 이후 다음 phase로 진행한다.
+
+### blocked_on_user
+
+`questions`를 메인 오케스트레이터의 사용자 질문 도구로 사용자에게 전달한다. 답변 수신 후 followup을 주입한다. 절차는 아래 Resume 섹션을 따른다.
+
+### needs_agent
+
+`requests`의 `role`을 새 dispatch 사이클로 실행한다. 결과를 followup으로 원래 에이전트에 주입한다.
+
+### needs_tool
+
+capability를 넘어선 도구 요청이다. 오케스트레이터가 `contract.policy`에 따라 직접 도구 실행 후 결과를 주입하거나, 실행할 수 없으면 `failed`로 escalate한다.
+
+### failed
+
+`contract.policy`의 `maxAttempts`, `fallbackProvider`, `escalateAfterAttempts`, `consecutiveSameFailureLimit`에 따라 처리한다.
+
+- retry: `maxAttempts` 미만이면 재시도한다.
+- fallbackProvider 전환: fallback provider가 있으면 provider를 전환한다.
+- 사용자 escalate: 한도에 도달했거나 같은 사유가 반복되면 사용자에게 에스컬레이션한다.
+
+## Resume
+
+`needs_agent` / `blocked_on_user` 상태에서 같은 sub-agent context를 이어가는 표준 절차.
+
+### Codex 경로
+
+1. `node scripts/crew-agent-runner.mjs render-followup --previous-result <file> --new-input <file>` 실행 → followup prompt 문자열 → 임시 파일에 저장.
+2. `node scripts/crew-agent-runner.mjs dispatch --role <role> --request-file <new-request-with-followup-prompt> --resume-handle <agent_handle> --json` 실행.
+   - 내부적으로 runner가 `crew-codex-companion.mjs task-resume-candidate`로 thread 일치 검증 후 `task --resume-last`를 호출하고 AgentResult를 정규화한다.
+3. AgentResult JSON을 받아 다음 상태 처리.
+
+주의: 직접 `crew-codex-companion.mjs task --resume-last`를 호출하지 말 것. runner의 candidate guard와 AgentResult 정규화를 건너뛴다.
+
+### Claude 경로
+
+1. `Agent` spawn으로 받은 sub-agent handle을 보존한다.
+2. `render-followup`을 사용하여 followup prompt를 생성한다.
+3. 메인 conversation에서 `SendMessage(to: <agent-handle>, message: <followup-prompt>)`로 같은 sub-agent에 후속 turn을 전달한다.
+
+## Followup 주입
+
+Followup prompt 형식은 양 provider에서 동일하다.
+
+```markdown
+## 이전 결과
+status: <status>
+summary: <summary>
+artifact:
+---
+<artifact>
+---
+
+## 추가 입력
+<new-input>
+
+## 지시
+계속 진행해라.
+```
+
+이 형식은 `runner.mjs render-followup`이 결정론적으로 생성한다.
+artifact가 객체/배열인 경우 runner가 JSON으로 직렬화하여 fence 블록 안에 삽입한다 (정보 손실 방지).
+
+## Retry / Fallback / Escalate
+
+`contract.policy`:
+
+- `maxAttempts`: retry 횟수 한도
+- `fallbackProvider`: `claude`/`codex` 전환
+- `escalateAfterAttempts`: 한도 도달 시 사용자 escalate
+- `consecutiveSameFailureLimit`: 같은 사유 연속 fail 한도