@jjlabsio/claude-crew 0.1.34 → 0.1.36

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "claude-crew",
       "source": "./",
       "description": "오케스트레이터 + PM, 플래너, 개발, QA, 마케팅 에이전트 팀으로 단일 제품의 개발과 마케팅을 통합 관리",
-      "version": "0.1.34",
+      "version": "0.1.36",
       "author": {
         "name": "Jaejin Song",
         "email": "wowlxx28@gmail.com"
@@ -28,5 +28,5 @@
       "category": "workflow"
     }
   ],
-  "version": "0.1.34"
+  "version": "0.1.36"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crew",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": {
     "name": "Jaejin Song",

package/hooks/enforce-delegation.mjs

@@ -10,6 +10,10 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 
+import { loadCatalog, loadProjectConfig, loadUserConfig } from '../scripts/lib/config.mjs';
+import { loadContracts } from '../scripts/lib/contracts.mjs';
+import { resolveRole } from '../scripts/lib/resolve.mjs';
+
 // ---------------------------------------------------------------------------
 // Read stdin
 // ---------------------------------------------------------------------------
@@ -52,6 +56,30 @@ function loadAgentDefinitions(pluginRoot) {
   return defs;
 }
 
+function resolveCrewRoleProvider(role) {
+  return resolveRole({
+    role,
+    catalog: loadCatalog(),
+    userConfig: loadUserConfig(),
+    projectConfig: loadProjectConfig(),
+    contracts: loadContracts()
+  });
+}
+
+function blockCodexAgentCall(role, resolved) {
+  return {
+    continue: true,
+    decision: 'block',
+    reason: [
+      `Role '${role}' is configured for Codex provider and cannot be called with the Agent tool.`,
+      'Use the central runner prepare/dispatch path instead:',
+      `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role ${role} --request-file <request-file> --json`,
+      `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" dispatch --role ${role} --request-file <request-file> --json`,
+      `Resolved model: ${resolved.model}${resolved.reasoning ? ` / ${resolved.reasoning}` : ''}`
+    ].join('\n')
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -86,6 +114,29 @@ async function main() {
 
   // Canonicalize subagent_type (strip plugin prefix if present)
   const rawType = input.subagent_type.replace(/^claude-crew:/, '');
+  let resolved = null;
+  try {
+    resolved = resolveCrewRoleProvider(rawType);
+  } catch {
+    resolved = null;
+  }
+
+  if (resolved?.provider === 'codex') {
+    console.log(JSON.stringify(blockCodexAgentCall(rawType, resolved)));
+    return;
+  }
+
+  if (resolved?.provider === 'claude' && !input.model && resolved.model) {
+    console.log(JSON.stringify({
+      continue: true,
+      modifiedInput: { ...input, model: resolved.model },
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: `model 자동 주입: ${rawType} → ${resolved.model}`,
+      },
+    }));
+    return;
+  }
 
   // Load agent definitions and auto-inject model if missing
   const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || dirname(import.meta.url.replace('file://', '')).replace('/hooks', '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jjlabsio/claude-crew",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": "Jaejin Song <wowlxx28@gmail.com>",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "smoke": "node tests/smoke/run.mjs",
     "test": "vitest",
     "test:run": "vitest run",
     "test:watch": "vitest"

package/scripts/crew-agent-runner.mjs

@@ -15,6 +15,7 @@ import {
   formatDispatchProviderGuardMessage
 } from "./lib/dispatch.mjs";
 import { installHooks } from "./lib/installHooks.mjs";
+import { prepareDispatch } from "./lib/prepare.mjs";
 import { renderFollowup } from "./lib/renderFollowup.mjs";
 import { renderPrompt } from "./lib/render.mjs";
 import { resolveRole } from "./lib/resolve.mjs";
@@ -33,6 +34,10 @@ async function main(argv) {
     return renderCommand(flags);
   }
 
+  if (command === "prepare") {
+    return prepareCommand(flags);
+  }
+
   if (command === "dispatch") {
     return dispatchCommand(flags);
   }
@@ -84,6 +89,49 @@ async function main(argv) {
   }
 }
 
+function prepareCommand(flags) {
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  if (
+    typeof flags["request-file"] !== "string" ||
+    flags["request-file"].length === 0
+  ) {
+    console.error("Missing required --request-file <path>");
+    return 1;
+  }
+
+  try {
+    const contracts = loadContracts();
+    const resolved = resolveRole({
+      role: flags.role,
+      catalog: loadCatalog(),
+      userConfig: loadUserConfig(),
+      projectConfig: loadProjectConfig(),
+      contracts
+    });
+    const request = JSON.parse(readFileSync(flags["request-file"], "utf8"));
+    const prepared = prepareDispatch({
+      role: flags.role,
+      requestFile: flags["request-file"],
+      request,
+      resolved
+    });
+
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(prepared, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatPrepared(prepared));
+    }
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
 async function installHooksCommand(flags) {
   if (
     flags.root !== undefined &&
@@ -292,6 +340,14 @@ function formatTable(value) {
     .join("\n")}\n`;
 }
 
+function formatPrepared(value) {
+  if (value.action === "dispatch") {
+    return `${value.command.join(" ")}\n`;
+  }
+
+  return value.prompt;
+}
+
 function findContract(role, contracts) {
   return contracts.roles.find((contract) => contract.role === role);
 }
@@ -310,6 +366,9 @@ function usage() {
   console.error("       crew-agent-runner build [--root <path>]");
   console.error("       crew-agent-runner validate [--root <path>]");
   console.error("       crew-agent-runner install-hooks [--root <path>]");
+  console.error(
+    "       crew-agent-runner prepare --role <name> --request-file <path> [--json]"
+  );
   console.error("       crew-agent-runner render --role <name> --request-file <path>");
   console.error(
     "       crew-agent-runner render-followup --previous-result <file> --new-input <file>"

package/scripts/lib/prepare.mjs

@@ -0,0 +1,37 @@
+import { renderPrompt } from "./render.mjs";
+import { pluginPath } from "./pluginRoot.mjs";
+
+export function prepareDispatch({ role, requestFile, request, resolved }) {
+  if (resolved.provider === "codex") {
+    return {
+      role,
+      provider: "codex",
+      action: "dispatch",
+      command: [
+        "node",
+        pluginPath("scripts", "crew-agent-runner.mjs"),
+        "dispatch",
+        "--role",
+        role,
+        "--request-file",
+        requestFile,
+        "--json"
+      ],
+      resolved
+    };
+  }
+
+  return {
+    role,
+    provider: "claude",
+    action: "agent",
+    subagent_type: role,
+    model: resolved.model,
+    prompt: renderPrompt({
+      role,
+      request,
+      contract: resolved.contract
+    }),
+    resolved
+  };
+}

package/scripts/lib/render.mjs

@@ -7,7 +7,8 @@ export function renderPrompt(input) {
     section("Outputs", renderJson(contract.outputs)),
     section("Instructions", request.instruction, { required: true }),
     section("Success Gate", request.successGate),
-    section("Failure Handling", request.failureHandling)
+    section("Failure Handling", request.failureHandling),
+    section("AgentResult Contract", renderAgentResultContract())
   ].filter(Boolean);
 
   return `${parts.join("\n\n")}\n`;
@@ -72,6 +73,33 @@ function renderJson(value) {
   return JSON.stringify(value, null, 2);
 }
 
+function renderAgentResultContract() {
+  return [
+    "Return exactly one final AgentResult JSON object wrapped in these tags:",
+    "",
+    "```text",
+    "<crew-agent-result>",
+    "{",
+    '  "status": "complete | blocked_on_user | needs_agent | needs_tool | failed",',
+    '  "artifact": null,',
+    '  "questions": [],',
+    '  "requests": [],',
+    '  "summary": "short summary",',
+    '  "error": null',
+    "}",
+    "</crew-agent-result>",
+    "```",
+    "",
+    "Rules:",
+    "- The wrapper tags are mandatory.",
+    "- The JSON inside the tags must be valid JSON.",
+    "- Use complete when the requested artifact is ready.",
+    "- Use blocked_on_user only with a non-empty questions array.",
+    "- Use needs_agent or needs_tool only with a non-empty requests array.",
+    "- Use failed with an error string when the task cannot continue."
+  ].join("\n");
+}
+
 function normalizeBody(body) {
   if (body === undefined || body === null) {
     return "";

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

@@ -3,6 +3,7 @@ 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);
@@ -26,6 +27,9 @@ export async function validate({ root = process.cwd() } = {}) {
     }))
   );
   errors.push(...compareSandboxConsistency({ contracts, catalog }));
+  errors.push(
+    ...(await validateWorkflowSkillDispatchContracts({ root: projectRoot }))
+  );
 
   return { ok: errors.length === 0, errors };
 }

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

@@ -5,7 +5,7 @@ description: 모든 crew 에이전트 dispatch의 중앙 규약 — provider별
 
 # crew-agent-runner
 
-crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구현하지 않고 이 중앙 규약을 따른다. 본 스킬은 resolve, dispatch, resume, followup 주입, retry/fallback/escalate 판단의 공통 표면을 정의한다.
+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 차단 도구입니다.)
@@ -14,26 +14,24 @@ crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구
 
 업무 스킬(crew-plan/crew-interview/crew-dev)이 role을 실행해야 할 때 본 절차를 따른다.
 
-### 1. resolve
+### 1. request 객체 작성
 
-오케스트레이터는 먼저 `node scripts/crew-agent-runner.mjs resolve --role <role> --json`을 실행하여 provider/model/contract 통합 표를 받는다.
+`{ role, inputs (path+content), instruction, successGate, failureHandling, taskId }` 형태의 임시 JSON 파일을 작성한다.
 
-### 2. request 객체 작성
+### 2. prepare
 
-`{ role, inputs (path+content), instruction, successGate, failureHandling, taskId }` 형태의 임시 JSON 파일을 작성한다.
+오케스트레이터는 `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+prepare는 provider/model/contract를 해석하고 다음 action 중 하나를 반환한다.
 
-### 3a. Codex 경로
+### 3a. dispatch action
 
-`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 경로를 사용.
+`action == dispatch`이면 prepare가 반환한 command를 실행한다. 이 경로는 Codex provider role에만 사용하며 AgentResult JSON을 즉시 반환한다.
 
-### 3b. Claude 경로
+### 3b. agent action
 
-`provider == claude`이면 다음 순서로 실행한다.
+`action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 메인 오케스트레이터가 Claude provider 역할을 실행하고, sub-agent 결과를 AgentResult JSON 형식으로 정규화한다.
 
-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 형식으로 정규화한다.
+주의: 업무 스킬은 직접 provider를 분기하거나 직접 하위 에이전트를 호출하지 않는다. 항상 prepare 결과의 action만 수행한다.
 
 ## AgentResult 상태 처리
 

package/skills/crew-dev/SKILL.md

@@ -23,6 +23,19 @@ description: contract.md를 입력으로 받아 Dev + CodeReviewer + QA 파이
 에이전트가 사용자 입력이 필요하다고 반환하면 오케스트레이터가 사용자에게 질문한다.
 에이전트가 추가 역할 실행이나 허용 도구 실행을 요청하면 오케스트레이터가 runner 정책에 따라 처리하고 같은 역할 실행에 후속 입력으로 주입한다.
 
+## 공통 에이전트 실행 인터페이스
+
+crew-dev의 모든 에이전트 실행은 역할이나 phase와 무관하게 아래 인터페이스만 사용한다.
+오케스트레이터는 `Dev`, `CodeReviewer`, `QA`, 후속 요청 role을 실행할 때마다 이 순서를 반복한다.
+
+1. `{ role, taskId, inputs, instruction, successGate, failureHandling }` 형태의 `request-file`을 작성한다.
+2. `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+3. `action == dispatch`이면 prepare가 반환한 command를 실행하고 AgentResult를 처리한다.
+4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
+
+이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
+provider 선택, 런타임 선택, AgentResult 반환 형식, 후속 입력 주입, retry/fallback/escalate 판단은 모두 중앙 runner 계약을 따른다.
+
 ---
 
 ## 절대 금지

package/skills/crew-interview/SKILL.md

@@ -36,6 +36,19 @@ description: 유저 요구사항을 인터뷰하여 개발 가능한 수준의 s
 
 에이전트 실행은 모두 중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다. 이 문서는 어떤 런타임을 어떻게 호출하는지가 아니라, 각 Phase가 어떤 역할에게 어떤 입력을 주고 어떤 결과를 받아야 하는지만 정의한다.
 
+## 공통 에이전트 실행 인터페이스
+
+crew-interview의 모든 에이전트 실행은 역할이나 phase와 무관하게 아래 인터페이스만 사용한다.
+오케스트레이터는 `pm`, `explorer`, `researcher`, 후속 요청 role을 실행할 때마다 이 순서를 반복한다.
+
+1. `{ role, taskId, inputs, instruction, successGate, failureHandling }` 형태의 `request-file`을 작성한다.
+2. `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+3. `action == dispatch`이면 prepare가 반환한 command를 실행하고 AgentResult를 처리한다.
+4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
+
+이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
+provider 선택, 런타임 선택, AgentResult 반환 형식, 후속 입력 주입, retry/fallback/escalate 판단은 모두 중앙 runner 계약을 따른다.
+
 ### Phase 1 — 초기화
 
 중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다.

package/skills/crew-plan/SKILL.md

@@ -42,6 +42,19 @@ crew-interview가 생성한 spec.md를 입력으로 받아 **HOW(어떻게 만
 
 각 에이전트 단계는 중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다. 이 문서는 역할, 입력, 기대 산출물, 검증 기준만 정의하며 실행 방식은 runner 계약을 따른다.
 
+## 공통 에이전트 실행 인터페이스
+
+crew-plan의 모든 에이전트 실행은 역할이나 step과 무관하게 아래 인터페이스만 사용한다.
+오케스트레이터는 `techlead`, `planner`, `plan-evaluator`, 후속 요청 role을 실행할 때마다 이 순서를 반복한다.
+
+1. `{ role, taskId, inputs, instruction, successGate, failureHandling }` 형태의 `request-file`을 작성한다.
+2. `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+3. `action == dispatch`이면 prepare가 반환한 command를 실행하고 AgentResult를 처리한다.
+4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
+
+이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
+provider 선택, 런타임 선택, AgentResult 반환 형식, 후속 입력 주입, retry/fallback/escalate 판단은 모두 중앙 runner 계약을 따른다.
+
 ### Step 1 — spec.md 검증
 
 role: orchestrator