@jjlabsio/claude-crew 0.1.43 → 0.1.44

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/package.json

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

package/scripts/crew-agent-runner.mjs

@@ -13,6 +13,7 @@ import {
   persistCrewArtifact,
   ArtifactPersistError
 } from "./lib/artifacts.mjs";
+import { checkpoint, CheckpointError } from "./lib/checkpoint.mjs";
 import {
   dispatch,
   DispatchError,
@@ -50,6 +51,10 @@ async function main(argv) {
     return persistArtifactCommand(flags);
   }
 
+  if (command === "checkpoint") {
+    return checkpointCommand(flags);
+  }
+
   if (command === "render-followup") {
     return renderFollowupCommand(flags);
   }
@@ -332,7 +337,8 @@ async function dispatchCommand(flags) {
       request,
       resolved,
       contract: resolved.contract,
-      resumeHandle: flags["resume-handle"]
+      resumeHandle: flags["resume-handle"],
+      noCheckpoint: flags["no-checkpoint"] === true
     });
 
     writeDispatchResult(agentResult, flags);
@@ -350,6 +356,33 @@ async function dispatchCommand(flags) {
   }
 }
 
+async function checkpointCommand(flags) {
+  if (typeof flags.message !== "string" || flags.message.length === 0) {
+    console.error("Missing required --message <text>");
+    return 1;
+  }
+
+  try {
+    const result = await checkpoint({ message: flags.message });
+
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else if (result.committed) {
+      process.stdout.write(`${result.hash} ${result.message}\n`);
+    } else {
+      process.stdout.write("Nothing to commit.\n");
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof CheckpointError) {
+      console.error(error.message);
+      return 1;
+    }
+    console.error(error.message);
+    return 1;
+  }
+}
+
 function renderCommand(flags) {
   if (typeof flags.role !== "string" || flags.role.length === 0) {
     console.error("Missing required --role <name>");
@@ -437,11 +470,14 @@ function usage() {
     "       crew-agent-runner render-followup --previous-result <file> --new-input <file>"
   );
   console.error(
-    "       crew-agent-runner dispatch --role <name> --request-file <path> [--json] [--resume-handle <thread-id>]"
+    "       crew-agent-runner dispatch --role <name> --request-file <path> [--json] [--resume-handle <thread-id>] [--no-checkpoint]"
   );
   console.error(
     "       crew-agent-runner persist-artifact --role <name> --result-file <path> --request-file <path>"
   );
+  console.error(
+    "       crew-agent-runner checkpoint --message <text> [--json]"
+  );
 }
 
 const exitCode = await main(process.argv.slice(2));

package/scripts/lib/artifacts.mjs

@@ -18,7 +18,7 @@ export async function persistCrewArtifact({ workspaceRoot, contract, request, ag
     return null;
   }
 
-  const resolvedTarget = replaceTaskId(target, request?.taskId);
+  const resolvedTarget = resolveTemplateTarget(target, request);
   const absolutePath = validateTargetPath(workspaceRoot, resolvedTarget);
 
   await mkdir(dirname(absolutePath), { recursive: true });
@@ -57,11 +57,34 @@ function findArtifactTarget(contract) {
   return null;
 }
 
-function replaceTaskId(target, taskId) {
-  if (typeof taskId === "string" && taskId.length > 0) {
-    return target.replace(/\{task-id\}/g, taskId);
+function resolveTemplateTarget(target, request) {
+  const values = {
+    "task-id": firstString(request?.taskId, request?.task_id, request?.["task-id"]),
+    "run-id": firstString(request?.runId, request?.run_id, request?.["run-id"])
+  };
+
+  const resolved = target.replace(/\{(task-id|run-id)\}/g, (match, name) => {
+    const value = values[name];
+    return value ?? match;
+  });
+
+  const unresolved = resolved.match(/\{[^}/\\]+\}/);
+  if (unresolved) {
+    throw new ArtifactPersistError(
+      `Unresolved template variable ${unresolved[0]} in artifact target: ${target}`
+    );
+  }
+
+  return resolved;
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
   }
-  return target;
+  return null;
 }
 
 function validateTargetPath(workspaceRoot, target) {

package/scripts/lib/checkpoint.mjs

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process";
+
+export class CheckpointError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CheckpointError";
+  }
+}
+
+export async function checkpoint({ message, cwd }) {
+  const workDir = cwd ?? process.cwd();
+
+  await git(["add", "-A"], workDir);
+
+  const status = await git(["status", "--porcelain"], workDir);
+  if (status.trim() === "") {
+    return { committed: false, hash: null, message: null };
+  }
+
+  await git(["commit", "--no-verify", "-m", message], workDir);
+
+  const hash = (await git(["rev-parse", "--short", "HEAD"], workDir)).trim();
+  return { committed: true, hash, message };
+}
+
+function git(args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", args, { cwd, encoding: "utf8" }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new CheckpointError(`git ${args[0]} failed: ${stderr || error.message}`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/scripts/lib/dispatch.mjs

@@ -5,6 +5,7 @@ import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { persistCrewArtifact, ArtifactPersistError } from "./artifacts.mjs";
+import { checkpoint } from "./checkpoint.mjs";
 import { renderPrompt } from "./render.mjs";
 
 const DEFAULT_COMPANION = fileURLToPath(
@@ -86,11 +87,20 @@ export async function dispatch(input) {
     }
 
     const artifactPath = await persistArtifactSafe(input, agentResult);
-    if (artifactPath) {
-      return { ...agentResult, artifact_path: artifactPath };
+    const result = artifactPath ? { ...agentResult, artifact_path: artifactPath } : agentResult;
+
+    if (!input.noCheckpoint && agentResult.status === "complete") {
+      const taskId = input.request?.taskId ?? input.request?.["task-id"] ?? input.request?.task_id ?? null;
+      const label = [input.role, taskId].filter(Boolean).join(" ");
+      const ckpt = await checkpointSafe(
+        `chore(crew): ${label} checkpoint`
+      );
+      if (ckpt) {
+        return { ...result, checkpoint: ckpt };
+      }
     }
 
-    return agentResult;
+    return result;
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
   }
@@ -259,6 +269,14 @@ async function persistArtifactSafe(input, agentResult) {
   }
 }
 
+async function checkpointSafe(message) {
+  try {
+    return await checkpoint({ message });
+  } catch {
+    return null;
+  }
+}
+
 function isNodeScript(value) {
   const name = basename(String(value));
   return name.endsWith(".mjs") || name.endsWith(".js");

package/skills/crew-dev/SKILL.md

@@ -30,7 +30,7 @@ crew-dev의 모든 에이전트 실행은 역할이나 phase와 무관하게 아
 
 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를 처리한다.
+3. `action == dispatch`이면 prepare가 반환한 command에 `--no-checkpoint`를 추가하여 실행하고 AgentResult를 처리한다. crew-dev는 US 단위 체크포인트를 직접 관리하므로 dispatch 자동 체크포인트를 사용하지 않는다.
 4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
 
 이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
@@ -69,6 +69,8 @@ provider 선택, 런타임 선택, AgentResult 반환 형식, 후속 입력 주
   qa-report-{n}.md          # US 단위 FAIL 시 아카이브
   final-review-report.md    # CodeReviewer: 최종 전체 리뷰 결과
   final-qa-report.md        # QA: 최종 전체 검증 결과
+  requests/                 # Dev/CodeReviewer/QA 실행 request-file 보존
+  runs/                     # Dev/CodeReviewer/QA 실행 결과/메타 보존
   .dev_loop_count           # US별 개발 루프 카운터, US PASS 시 리셋
   .dev_crash_count          # US별 구현 crash 카운터, US PASS 시 리셋
   .dev_crash_provider       # crash 발생 시 현재 사용 중인 provider 기록
@@ -150,7 +152,7 @@ role instructions:
 - **Phase 2b Step 1a — crash 감지 + retry**: Dev 실행이 비정상 종료되거나 자체 검증 결과가 불명확하면 crash로 판정한다. 오케스트레이터는 부분 변경을 마지막 체크포인트로 되돌리고 crash 카운터를 갱신한다. 동일 provider 재시도, provider fallback, 사용자 escalation은 runner 정책과 phase 카운터 규칙을 함께 적용한다.
 - **Phase 2b Step 2 — CodeReviewer + QA 병렬 검증**: CodeReviewer와 QA는 동시에 실행한다. CodeReviewer는 `.crew/` 메타 변경을 제외한 코드 변경분과 인라인 가드레일만 보고 품질을 판정한다. QA는 `plan.md` 산출물에서 현재 US의 테스트 시나리오를 확인하고 빌드, 린트, 타입 체크, 전체 테스트, 테스트 전략 준수, US 시나리오 검증을 직접 실행한다. 두 역할은 파일을 직접 작성하지 않고 결과 텍스트를 반환하며, 오케스트레이터가 각 보고서 산출물로 저장한다.
 - **Phase 2b Step 3 — 판정**: 오케스트레이터는 CodeReviewer PASS와 QA PASS가 모두 충족될 때만 US PASS로 판정한다. 하나라도 FAIL이면 US FAIL로 판정한다.
-- **Phase 2b Step 4 — 체크포인트 commit**: US PASS 즉시 전체 변경을 stage하고 `--no-verify` 옵션으로 `feat({task-id}): US-{k} {US 제목}` 커밋을 만든다. US 루프 카운터와 crash 카운터 산출물이 있으면 삭제한다.
+- **Phase 2b Step 4 — 체크포인트 commit**: US PASS 즉시 US 루프 카운터와 crash 카운터 산출물이 있으면 삭제한 뒤 `git add -A`로 전체 변경을 stage한다. 특히 `.crew/plans/{task-id}/requests/`, `.crew/plans/{task-id}/runs/`, 보고서, 카운터 파일처럼 새로 생긴 untracked 파이프라인 산출물이 체크포인트에서 누락되면 안 된다. stage 후 `git status --porcelain --untracked-files=all .crew/plans/{task-id}/`를 확인하고 출력이 남아 있으면 누락 산출물 경고와 함께 커밋하지 않고 실패 처리한다. 이상이 없을 때만 `git commit --no-verify -m "feat({task-id}): US-{k} {US 제목}"` 커밋을 만든다.
 - **Phase 2b Step 5 — FAIL 처리**: 오케스트레이터는 루프 카운터를 읽고, 상한 초과 또는 같은 기준 3회 연속 실패를 확인한다. 계속 진행 가능하면 최신 review/qa 보고서를 번호가 붙은 산출물로 아카이브하고 카운터를 증가시킨 뒤 Dev retry로 돌아간다. Dev retry에는 해당 US의 피드백만 전달한다.
 
 success gate:
@@ -214,9 +216,9 @@ output:
 
 role instructions:
 - **4a. 최종 판정**: CodeReviewer PASS와 QA PASS가 모두 충족될 때만 완료 처리한다. 하나라도 FAIL이면 Phase 3 failure handling을 적용한다.
-- **4b. PR 생성**: US 단위 커밋은 Phase 2에서 이미 완료되었으므로 추가 커밋은 만들지 않는다. 현재 브랜치를 push하고 PR을 생성한다.
+- **4b. 최종 checkpoint**: Phase 3에서 저장한 최종 보고서(`final-review-report.md`, `final-qa-report.md`)와 `contract.md` 상태를 `DONE`으로 갱신한 뒤, push 전에 `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" checkpoint --message "chore(crew-dev): {task-id} final"` 를 실행하여 모든 산출물을 커밋한다.
+- **4c. PR 생성**: 현재 브랜치를 push하고 PR을 생성한다.
 - PR 본문에는 구현 요약, 완료한 US 목록, 검증 결과, 최종 보고서 위치를 포함한다.
-- PR 생성 후 `contract.md` 상태를 `DONE`으로 갱신한다.
 
 success gate:
 - 원격 브랜치가 push되었다.

package/skills/crew-do/SKILL.md

@@ -152,6 +152,8 @@ active task와 연결된 경우:
 active task가 없는 경우:
 - `.crew/runs/{run-id}/result.md`에 결과를 저장한다.
 
+dispatch 경로(`action == dispatch`)에서 `complete`로 완료되면 자동으로 checkpoint 커밋을 생성한다. agent 경로(`action == agent`)에서는 자동 checkpoint가 없으므로, 오케스트레이터가 결과 처리 후 `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" checkpoint --message "chore(crew-do): {run-id} complete"` 를 직접 호출한다. 어느 경로든 오케스트레이터의 후처리(result.md 저장, task log 업데이트) 후에도 커밋되지 않은 변경이 남아 있으면 추가 checkpoint를 실행한다.
+
 `blocked_on_user`이면 questions를 사용자에게 전달하고, 답변을 받은 뒤 runner의 followup 절차로 같은 dev 실행에 주입한다.
 
 `needs_agent` 또는 `needs_tool`이면 중앙 runner 계약에 따라 오케스트레이터가 처리한다.
@@ -163,7 +165,7 @@ active task가 없는 경우:
 - 오케스트레이터가 코드를 직접 작성하지 않는다.
 - `dev`는 필요한 탐색, 수정, 검증을 직접 수행한다.
 - 요청 범위를 넘는 리팩터링을 하지 않는다.
-- 의존성 추가, 마이그레이션, 대규모 삭제, commit, push, PR 생성은 사용자 승인 없이 하지 않는다.
+- `dev` 에이전트는 의존성 추가, 마이그레이션, 대규모 삭제, commit, push, PR 생성을 하지 않는다. 완료 시 checkpoint 커밋은 오케스트레이터의 워크플로우 동작이며 별도 승인이 필요하지 않다.
 - 검증 가능한 명령을 실행하고, 실행하지 못한 검증은 이유를 보고한다.
 - `plan.md` 또는 `contract.md`가 없다는 이유로 direct mode를 실패 처리하지 않는다.
 - 위험하거나 되돌리기 어려운 변경은 `blocked_on_user`로 중단한다.

package/skills/crew-interview/SKILL.md

@@ -45,7 +45,7 @@ crew-interview의 모든 에이전트 실행은 역할이나 phase와 무관하
 
 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를 처리한다.
+3. `action == dispatch`이면 prepare가 반환한 command에 `--no-checkpoint`를 추가하여 실행하고 AgentResult를 처리한다. crew-interview는 다단계 워크플로우이므로 dispatch 자동 체크포인트를 사용하지 않고 워크플로우 완료 시 한 번만 checkpoint한다.
 4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
 
 이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
@@ -448,6 +448,16 @@ spec.md를 작성했습니다. 검토해주세요.
 
 ---
 
+## 워크플로우 완료 시 checkpoint
+
+오케스트레이터가 COMPLETE, ABORTED, 또는 ESCALATE를 반환하기 직전에, 워크플로우 중 생성된 모든 산출물(brief.md, spec.md, request-file 등)을 checkpoint 커밋한다.
+
+```
+node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" checkpoint --message "chore(crew-interview): {task-id} complete"
+```
+
+---
+
 ## 오케스트레이터 반환 스키마
 
 **COMPLETE**:

package/skills/crew-plan/SKILL.md

@@ -50,7 +50,7 @@ crew-plan의 모든 에이전트 실행은 역할이나 step과 무관하게 아
 
 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를 처리한다.
+3. `action == dispatch`이면 prepare가 반환한 command에 `--no-checkpoint`를 추가하여 실행하고 AgentResult를 처리한다. crew-plan은 다단계 워크플로우이므로 dispatch 자동 체크포인트를 사용하지 않고 워크플로우 완료 시 한 번만 checkpoint한다.
 4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
 
 이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
@@ -363,6 +363,16 @@ Planner + PlanEvaluator 사이클은 최대 5회 (초기 1회 + retry 최대 4
 
 ---
 
+## 워크플로우 완료 시 checkpoint
+
+오케스트레이터가 COMPLETE 또는 ESCALATE를 반환하기 직전에, 워크플로우 중 생성된 모든 산출물(analysis.md, plan.md, review.md, contract.md, request-file 등)을 checkpoint 커밋한다.
+
+```
+node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" checkpoint --message "chore(crew-plan): {task-id} complete"
+```
+
+---
+
 ## 오케스트레이터 반환 스키마
 
 **COMPLETE**: