@jjlabsio/claude-crew 0.1.33 → 0.1.35

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/skillDispatchContract.mjs

@@ -0,0 +1,93 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const RUNNER_DISPATCH_MARKER =
+  "중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다.";
+
+export const COMMON_AGENT_INTERFACE_HEADING =
+  "## 공통 에이전트 실행 인터페이스";
+
+export const REQUIRED_INTERFACE_MARKERS = [
+  COMMON_AGENT_INTERFACE_HEADING,
+  'node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json',
+  "request-file",
+  "action == dispatch",
+  "action == agent",
+  "직접 하위 에이전트를 호출하지 않는다",
+  "AgentResult"
+];
+
+const FORBIDDEN_DIRECT_DISPATCH_PATTERNS = [
+  /Agent\(/,
+  /Bash\(/,
+  new RegExp(["crew", "codex", "companion"].join("-")),
+  /runAgent\(/,
+  new RegExp(["AskUser", "Question"].join("")),
+  new RegExp(`<${["crew", "agent", "result"].join("-")}>`)
+];
+
+export async function validateWorkflowSkillDispatchContracts({
+  root = process.cwd()
+} = {}) {
+  const skillsDir = join(root, "skills");
+  const errors = [];
+  let entries = [];
+
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return errors;
+    }
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const relPath = `skills/${entry.name}/SKILL.md`;
+    const text = await readUtf8OrNull(join(root, relPath));
+    if (!text || entry.name === "crew-agent-runner") {
+      continue;
+    }
+
+    if (!text.includes(RUNNER_DISPATCH_MARKER)) {
+      continue;
+    }
+
+    errors.push(...validateWorkflowSkillDispatchContract(text, relPath));
+  }
+
+  return errors;
+}
+
+export function validateWorkflowSkillDispatchContract(text, relPath = "SKILL.md") {
+  const errors = [];
+
+  for (const pattern of FORBIDDEN_DIRECT_DISPATCH_PATTERNS) {
+    if (pattern.test(text)) {
+      errors.push(`${relPath}: direct agent dispatch is forbidden: ${pattern}`);
+    }
+  }
+
+  for (const marker of REQUIRED_INTERFACE_MARKERS) {
+    if (!text.includes(marker)) {
+      errors.push(`${relPath}: missing runner dispatch interface marker: ${marker}`);
+    }
+  }
+
+  return errors;
+}
+
+async function readUtf8OrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}

package/scripts/lib/validate.mjs

@@ -0,0 +1,104 @@
+import { readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+import { deriveBuildOutput, resolveBuildInputs } from "./build.mjs";
+import { loadContracts } from "./contracts.mjs";
+import { validateWorkflowSkillDispatchContracts } from "./skillDispatchContract.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 }));
+  errors.push(
+    ...(await validateWorkflowSkillDispatchContracts({ root: projectRoot }))
+  );
+
+  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,113 @@
+---
+name: crew-agent-runner
+description: 모든 crew 에이전트 dispatch의 중앙 규약 — provider별 호출법 캡슐화
+---
+
+# crew-agent-runner
+
+crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구현하지 않고 이 중앙 규약을 따른다. 본 스킬은 prepare, 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. request 객체 작성
+
+`{ role, inputs (path+content), instruction, successGate, failureHandling, taskId }` 형태의 임시 JSON 파일을 작성한다.
+
+### 2. prepare
+
+오케스트레이터는 `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+prepare는 provider/model/contract를 해석하고 다음 action 중 하나를 반환한다.
+
+### 3a. dispatch action
+
+`action == dispatch`이면 prepare가 반환한 command를 실행한다. 이 경로는 Codex provider role에만 사용하며 AgentResult JSON을 즉시 반환한다.
+
+### 3b. agent action
+
+`action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 메인 오케스트레이터가 Claude provider 역할을 실행하고, sub-agent 결과를 AgentResult JSON 형식으로 정규화한다.
+
+주의: 업무 스킬은 직접 provider를 분기하거나 직접 하위 에이전트를 호출하지 않는다. 항상 prepare 결과의 action만 수행한다.
+
+## 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 한도