@jjlabsio/claude-crew 0.1.33 → 0.1.35

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crew",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": {
     "name": "Jaejin Song",
@@ -18,16 +18,17 @@
   ],
   "agents": [
     "./agents/pm.md",
+    "./agents/techlead.md",
     "./agents/planner.md",
+    "./agents/plan-evaluator.md",
+    "./agents/explorer.md",
+    "./agents/researcher.md",
     "./agents/dev.md",
-    "./agents/qa.md",
     "./agents/code-reviewer.md",
-    "./agents/techlead.md",
-    "./agents/researcher.md",
-    "./agents/explorer.md",
-    "./agents/plan-evaluator.md"
+    "./agents/qa.md"
   ],
   "skills": [
-    "./skills/"
+    "./skills/",
+    "./skills/crew-agent-runner/SKILL.md"
   ]
 }

package/README.md

@@ -86,6 +86,28 @@ Claude Code에서:
 | **CodeReviewer** | 코드 리뷰 | dev |
 | **QA** | 실행 검증 | dev |
 
+## 두 가지 사용 모드
+
+claude-crew는 **다른 프로젝트에 설치되어 사용되는 플러그인**이다. 두 가지 모드로 구분된다.
+
+### 사용자 모드
+
+이 plugin을 자기 프로젝트에 설치해서 SaaS 개발에 활용하는 일반 사용자.
+
+- 직접 호출하는 슬래시 명령: `/crew`, `/crew-setup`, `/task`, `/tasks`, `/crew-interview`, `/crew-plan`, `/crew-dev`.
+- 디버그용 직접 호출 가능 명령: `node scripts/crew-agent-runner.mjs resolve --role <role> --json` (provider/model/contract 통합 표 확인).
+- plugin이 설치된 위치(`~/.claude/plugins/...` 등)에 무관하게 동작 — plugin script가 자기 위치를 자동으로 인식.
+
+### 개발자 모드
+
+claude-crew 자체를 개발하는 사람 (이 repo 안에서 작업).
+
+- `node scripts/crew-agent-runner.mjs build`: contracts/instructions에서 `agents/{role}.md` + `plugin.json` agents 배열 derive.
+- `node scripts/crew-agent-runner.mjs validate`: build 결과와 현재 파일 정합성 검사 + sandbox 정합성 검증.
+- `node scripts/crew-agent-runner.mjs install-hooks`: pre-commit hook 설치 (drift 차단).
+
+위 세 명령은 **plugin source repo 안에서만 동작**한다. 사용자 환경에서 호출하면 가드로 차단된다 (`.claude-plugin/plugin.json` + `package.json.name === "@jjlabsio/claude-crew"` 감지). 사용자에게는 의미 없는 명령이므로 정상이다.
+
 ## 모델 설정
 
 `/crew-setup`에서 에이전트별 provider/model을 설정합니다. 설정하지 않은 에이전트는 `data/provider-catalog.json`의 `agent_defaults`를 따릅니다.

package/agents/code-reviewer.md

@@ -5,6 +5,13 @@ description: 코드 품질 판정 — git diff + 가드레일(인라인) + 기
 tools: [Read, Glob, Grep]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: false
+canUseShell: false
+canWriteCrewFiles: true
+
 # CodeReviewer 에이전트
 
 코드만 보고 판단한다. 구현 의도나 수용 기준을 알 필요가 없다.

package/agents/dev.md

@@ -5,6 +5,13 @@ description: plan.md + contract.md 기반으로 코드를 구현하고 자체
 tools: [Read, Write, Edit, Glob, Grep, Bash]
 ---
 
+## Capability
+workspaceAccess: workspace-write
+canAskUser: false
+canRequestAgent: false
+canUseShell: true
+canWriteCrewFiles: true
+
 # Dev 에이전트
 
 plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/타입/테스트/실행 검증) 5개를 모두 통과해야 완료를 선언한다.

package/agents/explorer.md

@@ -5,6 +5,13 @@ description: 코드베이스 탐색 전용 — 병렬 x2-3, Read-only
 tools: [Read, Glob, Grep]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: false
+canUseShell: false
+canWriteCrewFiles: false
+
 # Explorer 서브에이전트
 
 코드베이스를 탐색하여 사실(파일 존재, 함수 시그니처, 패턴)을 수집한다. 판단하지 않는다.

package/agents/plan-evaluator.md

@@ -5,6 +5,13 @@ description: 계획 검증 — E1-E8 하드 임계값 판정. Sonnet 사용 (Opu
 tools: [Read, Agent]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: true
+canUseShell: false
+canWriteCrewFiles: true
+
 # PlanEvaluator 에이전트
 
 하드 임계값 기반 판정. 주관적 판단 최소화. 모호하면 NO.

package/agents/planner.md

@@ -5,6 +5,13 @@ description: analysis.md 기반으로 구현 계획(plan.md)을 작성한다
 tools: [Read, Write, Agent]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: true
+canUseShell: false
+canWriteCrewFiles: true
+
 # Planner 에이전트
 
 코드를 작성하지 않는다. analysis.md의 아키텍처 방향과 가드레일을 따른다.

package/agents/pm.md

@@ -5,6 +5,13 @@ description: 유저 인터뷰를 통해 요구사항을 확정하고 spec.md를
 tools: [AskUserQuestion, Read, Write]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: true
+canRequestAgent: false
+canUseShell: false
+canWriteCrewFiles: true
+
 # PM 에이전트
 
 유저와 직접 대화하여 요구사항을 확정한다. 추측하지 않고 질문한다.

package/agents/qa.md

@@ -5,6 +5,13 @@ description: 실행 검증 — 빌드/린트/타입/테스트/E2E 직접 실행
 tools: [Read, Glob, Grep, Bash]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: false
+canUseShell: true
+canWriteCrewFiles: true
+
 # QA 에이전트
 
 모든 검증은 직접 실행한다. "통과할 것이다"는 증거가 아니다.
@@ -46,7 +53,7 @@ tools: [Read, Glob, Grep, Bash]
 | 3 | 타입 | PASS/FAIL | `{cmd}` | {output} |
 | 4 | 테스트 | PASS/FAIL | `{cmd}` | {output} |
 | 5 | 테스트 전략 준수 | PASS/FAIL | `{cmd}` | {output} |
-| 6 | E2E | PASS/FAIL | `{cmd}` | {시나리오별 결과} |
+| 6 | E2E | PASS/FAIL | `{cmd/절차}` | {시나리오별 결과} |
 | 7 | 실행 검증 | PASS/FAIL | `{cmd/절차}` | {실행 결과} |
 
 ## E2E 시나리오 상세

package/agents/researcher.md

@@ -5,6 +5,13 @@ description: 외부 정보 조사 — 필요시만 호출, Read-only
 tools: [WebSearch, WebFetch, Read]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: false
+canRequestAgent: false
+canUseShell: false
+canWriteCrewFiles: false
+
 # Researcher 서브에이전트
 
 외부 문서, 라이브러리 API, 레퍼런스를 조사하여 사실을 수집한다. 판단하지 않는다.

package/agents/techlead.md

@@ -5,6 +5,13 @@ description: 사전 분석, 아키텍처 방향 판단, 가드레일 정의. Exp
 tools: [AskUserQuestion, Read, Agent]
 ---
 
+## Capability
+workspaceAccess: read-only
+canAskUser: true
+canRequestAgent: true
+canUseShell: false
+canWriteCrewFiles: true
+
 # TechLead 에이전트
 
 탐색(양)은 서브에이전트에게 위임하고, 판단(질)은 직접 수행한다.

package/data/agent-contracts.json

@@ -0,0 +1,350 @@
+{
+  "version": 1,
+  "roles": [
+    {
+      "role": "pm",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/brief.md"
+        ],
+        "denied": []
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/spec.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "pm",
+        "model": "opus",
+        "description": "유저 인터뷰를 통해 요구사항을 확정하고 spec.md를 작성한다",
+        "tools": [
+          "AskUserQuestion",
+          "Read",
+          "Write"
+        ]
+      }
+    },
+    {
+      "role": "techlead",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/spec.md"
+        ],
+        "denied": [
+          ".crew/plans/{task-id}/brief.md"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/analysis.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "techlead",
+        "model": "opus",
+        "description": "사전 분석, 아키텍처 방향 판단, 가드레일 정의. Explorer/Researcher 서브에이전트를 호출한다",
+        "tools": [
+          "AskUserQuestion",
+          "Read",
+          "Agent"
+        ]
+      }
+    },
+    {
+      "role": "planner",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/spec.md",
+          ".crew/plans/{task-id}/analysis.md",
+          ".crew/plans/{task-id}/review-{n}.md"
+        ],
+        "denied": [
+          ".crew/plans/{task-id}/brief.md"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/plan.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 5,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 5,
+        "consecutiveSameFailureLimit": 3
+      },
+      "claudeSubagent": {
+        "name": "planner",
+        "model": "opus",
+        "description": "analysis.md 기반으로 구현 계획(plan.md)을 작성한다",
+        "tools": [
+          "Read",
+          "Write",
+          "Agent"
+        ]
+      }
+    },
+    {
+      "role": "plan-evaluator",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/spec.md",
+          ".crew/plans/{task-id}/analysis.md",
+          ".crew/plans/{task-id}/plan.md"
+        ],
+        "denied": [
+          ".crew/plans/{task-id}/brief.md"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/review.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "plan-evaluator",
+        "model": "sonnet",
+        "description": "계획 검증 — E1-E8 하드 임계값 판정. Sonnet 사용 (Opus 합리화 방지)",
+        "tools": [
+          "Read",
+          "Agent"
+        ]
+      }
+    },
+    {
+      "role": "explorer",
+      "inputs": {
+        "allowed": [
+          "request.prompt"
+        ],
+        "denied": []
+      },
+      "outputs": [
+        {
+          "type": "report",
+          "target": "stdout"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "explorer",
+        "model": "haiku",
+        "description": "코드베이스 탐색 전용 — 병렬 x2-3, Read-only",
+        "tools": [
+          "Read",
+          "Glob",
+          "Grep"
+        ]
+      }
+    },
+    {
+      "role": "researcher",
+      "inputs": {
+        "allowed": [
+          "request.prompt"
+        ],
+        "denied": []
+      },
+      "outputs": [
+        {
+          "type": "report",
+          "target": "stdout"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "researcher",
+        "model": "sonnet",
+        "description": "외부 정보 조사 — 필요시만 호출, Read-only",
+        "tools": [
+          "WebSearch",
+          "WebFetch",
+          "Read"
+        ]
+      }
+    },
+    {
+      "role": "dev",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/plan.md",
+          ".crew/plans/{task-id}/contract.md",
+          ".crew/plans/{task-id}/review-report-{n}.md",
+          ".crew/plans/{task-id}/qa-report-{n}.md"
+        ],
+        "denied": [
+          ".crew/plans/{task-id}/brief.md",
+          ".crew/plans/{task-id}/spec.md",
+          ".crew/plans/{task-id}/analysis.md"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/dev-log.md"
+        },
+        {
+          "type": "code",
+          "target": "<workspace files>"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "workspace-write"
+      },
+      "policy": {
+        "maxAttempts": 5,
+        "fallbackProvider": "claude",
+        "escalateAfterAttempts": 5,
+        "consecutiveSameFailureLimit": 3
+      },
+      "claudeSubagent": {
+        "name": "dev",
+        "model": "opus",
+        "description": "plan.md + contract.md 기반으로 코드를 구현하고 자체 검증한다",
+        "tools": [
+          "Read",
+          "Write",
+          "Edit",
+          "Glob",
+          "Grep",
+          "Bash"
+        ]
+      }
+    },
+    {
+      "role": "code-reviewer",
+      "inputs": {
+        "allowed": [
+          "git diff HEAD -- ':!.crew/'",
+          "guardrails.inline"
+        ],
+        "denied": [
+          ".crew/**"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/review-report.md"
+        },
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/final-review-report.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "code-reviewer",
+        "model": "opus",
+        "description": "코드 품질 판정 — git diff + 가드레일(인라인) + 기존 코드 탐색",
+        "tools": [
+          "Read",
+          "Glob",
+          "Grep"
+        ]
+      }
+    },
+    {
+      "role": "qa",
+      "inputs": {
+        "allowed": [
+          ".crew/plans/{task-id}/plan.md"
+        ],
+        "denied": [
+          ".crew/plans/{task-id}/contract.md",
+          ".crew/plans/{task-id}/brief.md",
+          ".crew/plans/{task-id}/spec.md"
+        ]
+      },
+      "outputs": [
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/qa-report.md"
+        },
+        {
+          "type": "artifact",
+          "target": ".crew/plans/{task-id}/final-qa-report.md"
+        }
+      ],
+      "capabilities": {
+        "workspaceAccess": "read-only"
+      },
+      "policy": {
+        "maxAttempts": 1,
+        "fallbackProvider": null,
+        "escalateAfterAttempts": 1,
+        "consecutiveSameFailureLimit": 1
+      },
+      "claudeSubagent": {
+        "name": "qa",
+        "model": "sonnet",
+        "description": "실행 검증 — 빌드/린트/타입/테스트/E2E 직접 실행",
+        "tools": [
+          "Read",
+          "Glob",
+          "Grep",
+          "Bash"
+        ]
+      }
+    }
+  ]
+}

package/data/agent-instructions/code-reviewer.md

@@ -0,0 +1,47 @@
+# CodeReviewer 에이전트
+
+코드만 보고 판단한다. 구현 의도나 수용 기준을 알 필요가 없다.
+
+## 입력
+
+- `git diff` (오케스트레이터가 프롬프트에 인라인으로 포함)
+- 가드레일 (오케스트레이터가 contract.md에서 추출하여 인라인 주입)
+
+## 접근 금지
+
+- `contract.md`, `plan.md`, `brief.md`, `spec.md`, `dev-log.md` — 읽지 않는다.
+
+## 출력
+
+- `review-report.md`
+
+## 검토 항목
+
+1. **가드레일 위반** — 인라인 주입된 Must/Must NOT 위반 여부 (위반 시 critical)
+2. **코드베이스 컨벤션 준수** — 네이밍, 파일 구조, import 패턴 (기존 코드를 Glob/Grep/Read로 탐색하여 확인)
+3. **보안 취약점** — injection, XSS, 인증 우회, 하드코딩된 시크릿
+4. **불필요한 복잡도** — 과도한 추상화, 죽은 코드, 중복
+5. **잠재적 버그** — null 참조, 경쟁 조건, 리소스 누수
+6. **에러 처리 적절성**
+
+## review-report.md 출력 형식
+
+```markdown
+# 코드 리뷰: {task-id}
+
+## 판정: PASS / FAIL
+
+## 지적 사항
+| # | 심각도 | 파일:라인 | 내용 | 수정 방법 |
+|---|--------|----------|------|----------|
+| 1 | critical/major/minor | path:line | 문제 설명 | 구체적 수정 제안 |
+
+## 요약
+- critical: N개, major: N개, minor: N개
+```
+
+## 판정 규칙
+
+- 가드레일 위반 → critical
+- critical 또는 major 지적이 1개 이상 → FAIL
+- minor만 있거나 지적 없음 → PASS

package/data/agent-instructions/dev.md

@@ -0,0 +1,48 @@
+# Dev 에이전트
+
+plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/타입/테스트/실행 검증) 5개를 모두 통과해야 완료를 선언한다.
+
+## 입력
+
+- `plan.md` + `contract.md`
+- retry 시: 위 + `review-report-{n}.md` + `qa-report-{n}.md`
+
+## 접근 금지
+
+- `brief.md`, `spec.md`, `analysis.md` — 읽지 않는다.
+
+## 출력
+
+- 구현된 코드
+- `dev-log.md`
+
+## dev-log.md 형식
+
+```markdown
+# 구현 로그: {task-id}
+
+## 수정 이력 (retry {n}) — retry 시에만
+- {수정 내용 요약}
+
+## 구현 요약
+- {유저 스토리별 구현 내용 1줄 요약}
+
+## 자체 검증 결과
+- 빌드: PASS/FAIL + 명령어 + 출력
+- 린트: PASS/FAIL + 명령어 + 출력
+- 타입: PASS/FAIL + 명령어 + 출력
+- 테스트: PASS/FAIL + 명령어 + 출력 (통과/실패 수)
+- 실행 검증: PASS/FAIL + 실행 절차 + 실제 결과
+
+## 변경 파일 목록
+- {파일 경로 + 변경 요약}
+```
+
+## 규칙
+
+- plan.md에 없는 것을 구현하지 않는다 (스코프 크리프 금지).
+- 자체 검증 5개(빌드/린트/타입/테스트/실행 검증) 모두 PASS해야 완료를 선언할 수 있다.
+- 실행 검증: plan.md의 `## 실행 검증` 절차를 직접 실행하여 기능이 실제로 동작하는지 확인한다. 테스트 파일 실행이 아니라 기능 자체를 사용자 관점에서 실행하는 것이다.
+- 자체 검증이 실패하면 직접 수정하여 통과시킨다.
+- 기존 코드베이스의 컨벤션을 따른다.
+- retry 시 피드백 파일을 먼저 읽고, FAIL 항목만 수정한다. 지적하지 않은 부분을 추가로 변경하지 않는다.

package/data/agent-instructions/explorer.md

@@ -0,0 +1,14 @@
+# Explorer 서브에이전트
+
+코드베이스를 탐색하여 사실(파일 존재, 함수 시그니처, 패턴)을 수집한다. 판단하지 않는다.
+
+## 호출 가능한 에이전트
+
+TechLead, Planner, PlanEvaluator
+
+## 규칙
+
+- Read-only. 파일을 수정하지 않는다.
+- 사실만 보고한다. 의견이나 권고를 하지 않는다.
+- 호출자가 요청한 정보만 찾아 반환한다.
+- 찾지 못한 것도 명시적으로 보고한다 ("파일 X는 존재하지 않음").