Ganpan (간판)

GitHub-native 멀티 에이전트 오케스트레이션 툴킷 — Issues / PRs / 라벨을 단일 상태 머신으로 삼아, 여러 AI 에이전트가 Triager → Coder → Reviewer → QA 레인을 나눠 협업하도록 만드는 Claude Code + Codex 지원 툴킷입니다.

별도의 큐나 DB 없이 GitHub 자체를 작업 보드로 사용합니다. 각 이슈는 status:* 라벨로 상태가 표현되고, 에이전트들은 라벨을 보고 자기 일을 집어가며, 머지는 항상 사람이 합니다(branch protection으로 강제).

---

동작 개요

이슈 하나가 라벨을 따라 흐릅니다:

status:triage      ── /triage ──▶   status:agent-ready
status:agent-ready ── /work-issue ▶ status:in-progress ──▶ status:in-review (PR 생성)
status:in-review   ── 사람이 머지 + /review-queue ──▶ status:qa
status:qa          ── /qa-check ──▶ status:done   (실패 시 rework / blocked)

| 레인 | Claude Code | Codex Skill | 역할 | |------|-------------|-------------|------| | Triager | /ganpan:triage | ganpan-triage | 고아 락 회수(reclaim) 후 status:triage 이슈를 분류 → agent-ready 또는 blocked | | Coder | /ganpan:work-issue | ganpan-work-issue | agent-ready 이슈를 클레임 → worktree에서 구현 → PR 생성 → in-review | | Reviewer | /ganpan:review-queue | ganpan-review-queue | in-review PR을 리뷰. 머지/승인은 절대 안 함 — 사람에게 머지 요청, 통과 시 qa | | QA | /ganpan:qa-check | ganpan-qa-check | 머지된 작업을 실제 실행·검증. 통과 → done, 실패 → rework 또는 blocked | | Setup | /ganpan:orch-setup | ganpan-setup | 1회 셋업 (아래 참고) | | 통합 런처 | /ganpan:run-all | — | 4개 레인(Triager·Coder·Reviewer·QA)을 백그라운드 에이전트로 한 번에 병렬 1회 스윕 (Claude Code 전용) |

> 플러그인 커맨드는 플러그인 이름으로 네임스페이싱됩니다. 정식 호출은 /ganpan:triage이며, 충돌이 없으면 짧은 /triage로도 호출됩니다.

---

사전 준비물

• gh (GitHub CLI, 인증 완료), git, jq, yq
• 테스트 실행 시 bats

command -v gh jq yq git   # 모두 존재하는지 확인
gh auth status            # 인증 확인 (HTTPS 권장)

지원 표면

| Surface | Status | Primary UX | |---|---|---| | Claude Code plugin | first-class | /ganpan: commands | | Copy-in Claude install | first-class fallback | .claude/commands + scripts | | Codex repo-local skills | Phase 1 MVP | .agents/skills/ganpan- | | CLI runner | planned | ganpan lane ... | | Codex plugin | planned | Codex plugin install |

---

설치

방법 A — 플러그인 (권장)

1. /plugin marketplace add Laeyoung/Ganpan
2. /plugin install ganpan@laeyoung
3. 대상 레포 루트에서:  /ganpan:orch-setup owner/repo
4. /ganpan:orch-setup 이 출력하는 사람용 체크리스트 완료

/ganpan:orch-setup이 자동으로 해주는 것:

• 사전 준비물·인증 점검
• .claude/orchestration.json 작성 (인자에서 repo / bot 채움)
• .github/labels.yml + 이슈 템플릿 설치
• CLAUDE.md 컨벤션 병합
• 라벨 부트스트랩

방법 B — copy-in (플러그인을 쓰지 않을 때)

ganpan 체크아웃에서 대상 레포로 파일을 직접 복사합니다:

./install.sh <대상-레포-경로>

이 경우 config는 템플릿만 복사되므로, .claude/orchestration.json을 열어 repo·bot(필요 시 project.number)을 직접 채워야 합니다.

업그레이드: install.sh를 다시 실행하면 버전 sentinel이 다른 파일만 갱신됩니다. v1(자동 sentinel 이전) 설치본에서 처음 올릴 때는 ./install.sh <대상> --force를 쓰거나 기존 scripts/orchestration/·.claude/commands/를 먼저 지우세요.

방법 C — Codex repo-local skills (Phase 1 MVP)

Codex CLI/IDE가 대상 레포에서 repo-local skills를 읽도록 설치합니다:

./install.sh <대상-레포-경로> --target codex

설치되는 항목:

• .agents/skills/ganpan-*
• AGENTS.md Ganpan conventions block
• scripts/orchestration/*.sh
• .ganpan/orchestration.json 템플릿. 단, 기존 .claude/orchestration.json만 있으면 legacy fallback으로 두고 새 .ganpan config를 자동 생성하지 않습니다.
• .github/labels.yml + issue template

Claude와 Codex surface를 함께 설치하려면:

./install.sh <대상-레포-경로> --target both

설치 후 설정·라벨 부트스트랩·검증·레인 실행·트러블슈팅까지의 전체 절차는 docs/CODEX_RUNBOOK.md 를 따르세요.

---

셋업 이후 사람이 해야 할 일

/ganpan:orch-setup이 자동화하지 못하는 부분(체크리스트로 안내됨):

1. 봇 계정 + Fine-grained PAT — 대상 레포에만 Contents RW / Pull requests RW / Issues RW / Projects RW, 만료 90일. GH_TOKEN=github_pat_...로 export(HTTPS 사용; --with-token 금지). 이는 권장이 아니라 실행 전제조건입니다 — 레인은 시작 시 gh 행위 주체가 config.bot과 일치하는지 확인하고, 일치하지 않으면(예: GH_TOKEN 미설정 → 개인 계정으로 폴백) 즉시 중단합니다. (CI 등 봇 PAT가 곧 주체임이 확실한 경우에만 호출 단위로 ORCH_SKIP_ACTOR_CHECK=1을 쓸 수 있으며, 전역 export는 금지.) 2. 봇을 대상 레포 협업자로 추가. 3. (선택) GitHub Project 생성 후 project.number 설정 — 없으면 null로 두면 sync는 no-op. 4. main 브랜치 보호 — 사람 리뷰 1회 필수, force-push·직접 push 금지, 관리자 포함, 리뷰 dismissal 제한. 봇 토큰은 admin이면 안 됨. 5. Worktree 의존성 전략 — 이슈별 worktree(../wt-issue-<n>)가 의존성을 어떻게 공유할지 결정(예: Node는 node_modules 심볼릭 링크).

---

레인 실행 (각각 별도 터미널)

Triager :  /loop 10m /ganpan:triage
Coder   :  /loop /ganpan:work-issue
Reviewer:  /loop 5m /ganpan:review-queue
QA      :  /goal 로 /ganpan:qa-check 래핑

한 번에 실행 (통합 런처)

claude agents(Agent View) 한 곳에서 4개 레인을 운영하려면:

/loop 20m /ganpan:run-all      # 20m은 예시 — 조정 가능. bare 실행 시 1회 스윕

/ganpan:run-all은 매 틱마다 4개 레인을 백그라운드 에이전트로 띄워 각자 1회 스윕 후 종료합니다(Agent View에 함께 표시). 단일 인스턴스만 권장(2개 동시 실행 시 worker pool·WIP 압력 2배). Coder는 틱당 최대 3 사이클이라, 백로그가 깊으면 전용 /loop /ganpan:work-issue를 함께 돌리세요.

> ⚠️ /loop 간격은 한 스윕 소요 시간보다 넉넉히 잡으세요. 런처는 띄운 에이전트를 기다리지 않고 반환하므로, 스윕(특히 Coder의 긴 빌드/테스트)이 간격보다 오래 걸리면 다음 틱이 실행 중인 배치 위에 새 배치를 띄웁니다. Coder claim은 WIP 게이트로 wipLimit까지만 묶이지만, 겹친 Reviewer/QA는 같은 이슈를 중복 처리할 수 있습니다(중복 코멘트·낭비).

통합 스모크 테스트 (수동)

1. 이슈를 연다 → status:triage 부여됨. 2. /ganpan:triage 1회 → status:agent-ready. 3. /ganpan:work-issue 1회 → status:in-progress → PR과 함께 status:in-review. 4. 사람이 PR 승인·머지 → /ganpan:review-queue → status:qa. 5. /ganpan:qa-check → status:done (실패 시 rework/blocked).

---

설정 (.ganpan/orchestration.json 또는 .claude/orchestration.json)

config discovery 순서:

1. $ORCH_CONFIG 2. .ganpan/orchestration.json 3. .claude/orchestration.json

새 Codex 설치는 .ganpan/orchestration.json을 사용합니다. 기존 Claude 설치는 .claude/orchestration.json을 계속 사용할 수 있습니다.

{
  "repo": "owner/repo",          // 대상 레포
  "bot": "bot-login",            // 봇 계정 로그인
  "candidateN": 5,               // Coder가 한 번에 고려하는 후보 이슈 수
  "wipLimit": 5,                 // 동시 진행(in-progress) 상한
  "reclaim": { "timeoutMinutes": 120, "heartbeatMinutes": 15 },
  "commands": { "test": null, "build": null, "lint": null },  // 자동 감지 보완용
  "worktreeBaseDir": "../",      // wt-issue-<n> 가 생성될 위치
  "project": { "number": null, "statusField": "Status" }      // GitHub Project 연동(선택)
}

---

컨벤션 (대상 레포에 병합됨)

• 커밋: Conventional Commits — type(scope): subject (type ∈ feat, fix, docs, refactor, test, chore, perf, build, ci). 본문은 무엇을·왜, 푸터는 Closes #<n>.
• 브랜치/worktree: 이슈 1개 → 브랜치 issue-<n> → worktree ../wt-issue-<n>. 남의 wt-issue-*를 force-push·삭제 금지.
• 머지 게이트: 에이전트는 PR 승인·머지를 하지 않음. 사람이 리뷰·머지(branch protection으로 강제).

---

저장소 구조

.claude-plugin/marketplace.json          # 마켓플레이스 매니페스트 (name: laeyoung)
plugins/orchestration/
  ├─ .claude-plugin/plugin.json          # 플러그인 매니페스트 (name: ganpan)
  ├─ commands/                           # 레인 커맨드 (triage / work-issue / ... / run-all)
  ├─ scripts/orchestration/              # 엔진 셸 스크립트 (claim, reclaim, lib, ...)
  ├─ references/lanes/                   # 공유 lane protocol reference
  └─ assets/                             # config 템플릿, labels.yml, 이슈 템플릿, CLAUDE.md
plugins/ganpan-codex/
  ├─ skills/ganpan-*/                    # Codex repo-local skill source
  └─ assets/AGENTS.md                    # Codex target repo conventions
install.sh                               # copy-in 설치/업그레이드
docs/SETUP.md                            # 상세 셋업 가이드
tests/                                   # bats 테스트

---

알려진 잔여 위험

• 봇 토큰이 Projects:write 보유 → 영향 범위가 넓음(라이브 보드 sync를 위한 트레이드오프).
• 단일 봇 정체성 → self-approval은 토큰 분리가 아니라 branch protection으로만 차단됨.
• Contents:write 봇은 main 이외 브랜치를 force-push·삭제할 수 있음.

자세한 내용은 docs/SETUP.md를 참고하세요.

Codex 전용 설치와 실행 절차는 docs/CODEX_RUNBOOK.md를 참고하세요. Phase 2/3 개발자는 docs/PHASE1_DEV_LOG.md와 docs/CODEX_ADAPTER_RULES.md를 먼저 확인하세요.