@jjlabsio/claude-crew 0.1.39 → 0.1.41

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jjlabsio/claude-crew",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": "Jaejin Song <wowlxx28@gmail.com>",
   "license": "MIT",

package/scripts/crew-agent-runner.mjs

@@ -9,6 +9,10 @@ import {
   loadUserConfig
 } from "./lib/config.mjs";
 import { parseArgv } from "./lib/cli.mjs";
+import {
+  persistCrewArtifact,
+  ArtifactPersistError
+} from "./lib/artifacts.mjs";
 import {
   dispatch,
   DispatchError,
@@ -42,6 +46,10 @@ async function main(argv) {
     return dispatchCommand(flags);
   }
 
+  if (command === "persist-artifact") {
+    return persistArtifactCommand(flags);
+  }
+
   if (command === "render-followup") {
     return renderFollowupCommand(flags);
   }
@@ -224,6 +232,61 @@ function renderFollowupCommand(flags) {
   }
 }
 
+async function persistArtifactCommand(flags) {
+  if (typeof flags.role !== "string" || flags.role.length === 0) {
+    console.error("Missing required --role <name>");
+    return 1;
+  }
+
+  if (
+    typeof flags["result-file"] !== "string" ||
+    flags["result-file"].length === 0
+  ) {
+    console.error("Missing required --result-file <path>");
+    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 contract = findContract(flags.role, contracts);
+    if (!contract) {
+      throw new Error(`Unknown role: ${flags.role}`);
+    }
+
+    const agentResult = JSON.parse(readFileSync(flags["result-file"], "utf8"));
+    const request = JSON.parse(readFileSync(flags["request-file"], "utf8"));
+
+    const savedPath = await persistCrewArtifact({
+      workspaceRoot: process.cwd(),
+      contract,
+      request,
+      agentResult
+    });
+
+    if (savedPath) {
+      process.stdout.write(`${JSON.stringify({ artifact_path: savedPath })}\n`);
+    } else {
+      process.stdout.write(`${JSON.stringify({ artifact_path: null })}\n`);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof ArtifactPersistError) {
+      console.error(error.message);
+      return 1;
+    }
+    console.error(error.message);
+    return 1;
+  }
+}
+
 async function dispatchCommand(flags) {
   if (typeof flags.role !== "string" || flags.role.length === 0) {
     console.error("Missing required --role <name>");
@@ -376,6 +439,9 @@ function usage() {
   console.error(
     "       crew-agent-runner dispatch --role <name> --request-file <path> [--json] [--resume-handle <thread-id>]"
   );
+  console.error(
+    "       crew-agent-runner persist-artifact --role <name> --result-file <path> --request-file <path>"
+  );
 }
 
 const exitCode = await main(process.argv.slice(2));

package/scripts/lib/artifacts.mjs

@@ -0,0 +1,89 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, normalize, resolve, relative } from "node:path";
+
+export class ArtifactPersistError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArtifactPersistError";
+  }
+}
+
+export async function persistCrewArtifact({ workspaceRoot, contract, request, agentResult }) {
+  if (!shouldPersist(contract, agentResult)) {
+    return null;
+  }
+
+  const target = findArtifactTarget(contract);
+  if (!target) {
+    return null;
+  }
+
+  const resolvedTarget = replaceTaskId(target, request?.taskId);
+  const absolutePath = validateTargetPath(workspaceRoot, resolvedTarget);
+
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, agentResult.artifact, "utf8");
+
+  return absolutePath;
+}
+
+function shouldPersist(contract, agentResult) {
+  if (contract?.capabilities?.workspaceAccess !== "read-only") {
+    return false;
+  }
+
+  if (agentResult?.status !== "complete") {
+    return false;
+  }
+
+  if (typeof agentResult.artifact !== "string" || agentResult.artifact.length === 0) {
+    return false;
+  }
+
+  return true;
+}
+
+function findArtifactTarget(contract) {
+  const outputs = Array.isArray(contract?.outputs) ? contract.outputs : [];
+  for (const output of outputs) {
+    if (
+      output?.type === "artifact" &&
+      typeof output.target === "string" &&
+      output.target.startsWith(".crew/")
+    ) {
+      return output.target;
+    }
+  }
+  return null;
+}
+
+function replaceTaskId(target, taskId) {
+  if (typeof taskId === "string" && taskId.length > 0) {
+    return target.replace(/\{task-id\}/g, taskId);
+  }
+  return target;
+}
+
+function validateTargetPath(workspaceRoot, target) {
+  if (!workspaceRoot || typeof workspaceRoot !== "string") {
+    throw new ArtifactPersistError("workspaceRoot is required.");
+  }
+
+  const normalized = normalize(target);
+
+  if (normalized.startsWith("/") || normalized.startsWith("\\")) {
+    throw new ArtifactPersistError(`Absolute path rejected: ${target}`);
+  }
+
+  const crewBase = resolve(workspaceRoot, ".crew");
+  const absolutePath = resolve(workspaceRoot, normalized);
+  const rel = relative(crewBase, absolutePath);
+
+  if (rel.startsWith("..") || rel === "") {
+    throw new ArtifactPersistError(
+      `Target path escapes .crew/ directory: ${target}`
+    );
+  }
+
+  return absolutePath;
+}

package/scripts/lib/dispatch.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { persistCrewArtifact, ArtifactPersistError } from "./artifacts.mjs";
 import { renderPrompt } from "./render.mjs";
 
 const DEFAULT_COMPANION = fileURLToPath(
@@ -84,6 +85,11 @@ export async function dispatch(input) {
       });
     }
 
+    const artifactPath = await persistArtifactSafe(input, agentResult);
+    if (artifactPath) {
+      return { ...agentResult, artifact_path: artifactPath };
+    }
+
     return agentResult;
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
@@ -235,6 +241,24 @@ function resolveCompanion(input = {}) {
   };
 }
 
+async function persistArtifactSafe(input, agentResult) {
+  try {
+    return await persistCrewArtifact({
+      workspaceRoot: process.cwd(),
+      contract: input.contract,
+      request: input.request,
+      agentResult
+    });
+  } catch (error) {
+    if (error instanceof ArtifactPersistError) {
+      throw new DispatchError(`Artifact persist failed: ${error.message}`, {
+        agentResult
+      });
+    }
+    throw error;
+  }
+}
+
 function isNodeScript(value) {
   const name = basename(String(value));
   return name.endsWith(".mjs") || name.endsWith(".js");

package/scripts/lib/render.mjs

@@ -8,7 +8,7 @@ export function renderPrompt(input) {
     section("Instructions", request.instruction, { required: true }),
     section("Success Gate", request.successGate),
     section("Failure Handling", request.failureHandling),
-    section("AgentResult Contract", renderAgentResultContract())
+    section("AgentResult Contract", renderAgentResultContract(contract))
   ].filter(Boolean);
 
   return `${parts.join("\n\n")}\n`;
@@ -41,7 +41,7 @@ function renderCapability(contract) {
     `canAskUser: ${String(tools.includes("AskUserQuestion"))}`,
     `canRequestAgent: ${String(tools.includes("Agent"))}`,
     `canUseShell: ${String(tools.includes("Bash"))}`,
-    `canWriteCrewFiles: ${String(canWriteCrewFiles(outputs))}`
+    `canReturnCrewArtifact: ${String(canReturnCrewArtifact(outputs, contract.capabilities?.workspaceAccess))}`
   ].join("\n");
 }
 
@@ -73,15 +73,19 @@ function renderJson(value) {
   return JSON.stringify(value, null, 2);
 }
 
-function renderAgentResultContract() {
-  return [
+function renderAgentResultContract(contract = {}) {
+  const outputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+  const workspaceAccess = contract.capabilities?.workspaceAccess;
+  const returnArtifact = canReturnCrewArtifact(outputs, workspaceAccess);
+
+  const lines = [
     "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,',
+    `  "artifact": ${returnArtifact ? '"full Markdown content of the artifact"' : "null"},`,
     '  "questions": [],',
     '  "requests": [],',
     '  "summary": "short summary",',
@@ -97,7 +101,15 @@ function renderAgentResultContract() {
     "- 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");
+  ];
+
+  if (returnArtifact) {
+    lines.push(
+      "- Do NOT write the artifact file yourself. Instead, put the full Markdown content into the artifact field as a string. The runner will validate and save it to the target path."
+    );
+  }
+
+  return lines.join("\n");
 }
 
 function normalizeBody(body) {
@@ -127,7 +139,11 @@ function titleCase(value) {
     .join("-");
 }
 
-function canWriteCrewFiles(outputs) {
+export function canReturnCrewArtifact(outputs, workspaceAccess) {
+  if (workspaceAccess !== "read-only") {
+    return false;
+  }
+
   return outputs.some((output) => {
     return (
       output?.type === "artifact" &&

package/skills/crew-interview/SKILL.md

@@ -20,6 +20,7 @@ description: 유저 요구사항을 인터뷰하여 개발 가능한 수준의 s
 - 유저 승인 없이 crew-plan으로 전환하지 않는다.
 - 추측으로 비즈니스 결정을 채우지 않는다.
 - `git worktree add`를 직접 실행하지 않는다. 워크트리는 `EnterWorktree` 도구만 사용한다.
+- `EnterWorktree` 호출 전에 프로젝트 디렉토리에 파일이나 디렉토리를 생성하지 않는다. 워크트리 진입 전 request-file이 필요하면 OS 임시 디렉토리(`$TMPDIR`)를 사용한다.
 
 ---
 
@@ -68,11 +69,11 @@ output:
 - 최초 요구사항 체크리스트 평가
 
 role instructions:
-- PM은 요청 내용에서 키워드를 추출하여 kebab-case task-id를 생성한다.
-- PM이 task-id를 반환하면 오케스트레이터가 `EnterWorktree(name: "crew/{task-id}")`를 호출하여 Claude 워크트리를 생성하고 진입한다. 이후 모든 파일 작업은 워크트리 안에서 수행된다.
+- 오케스트레이터가 요청 내용에서 키워드를 추출하여 kebab-case task-id를 직접 생성한다 (에이전트 호출 불필요).
+- 오케스트레이터가 `EnterWorktree(name: "crew/{task-id}")`를 호출하여 Claude 워크트리를 생성하고 진입한다. 이후 모든 파일 작업은 워크트리 안에서 수행된다.
 - 오케스트레이터가 유저 원본 요청을 `.crew/plans/{task-id}/brief.md`에 저장한다.
 - Explorer는 프로젝트 구조를 병렬로 파악하고, 결과를 파일로 저장하지 않고 인터뷰 컨텍스트로만 제공한다.
-- PM은 유저 요청과 Explorer 결과를 기반으로 체크리스트 5개 항목을 첫 평가한다.
+- PM은 유저 요청과 Explorer 결과를 기반으로 체크리스트 5개 항목을 첫 평가한다 (워크트리 내부에서 실행).
 
 success gate:
 - Claude 워크트리 `crew/{task-id}`에 진입했다.
@@ -86,10 +87,12 @@ failure handling:
 
 **1b. task-id 생성 + 워크트리 진입 + brief.md 작성**
 
-1. task-id는 요청 내용에서 키워드를 추출하여 kebab-case로 생성한다.
+1. 오케스트레이터가 요청 내용에서 키워드를 추출하여 kebab-case task-id를 직접 생성한다. 에이전트 호출 없이 수행한다.
 2. `EnterWorktree(name: "crew/{task-id}")`를 호출하여 Claude 워크트리를 생성하고 진입한다. 이미 해당 워크트리 안이면 이 단계를 건너뛴다.
 3. 유저 요청 원문을 `.crew/plans/{task-id}/brief.md`에 저장한다.
 
+주의: 1~2단계에서 에이전트를 호출하거나 파일을 프로젝트 디렉토리에 생성하지 않는다. 모든 에이전트 호출(PM, Explorer)과 파일 작업은 워크트리 진입 후에 수행한다.
+
 **1c. Explorer 호출 (병렬, 워크트리 진입 후)**
 
 Explorer는 중앙 runner를 통해 병렬 실행되어 프로젝트 구조를 파악한다.