agent-rig/rig

rig-epic — 통합 브랜치 워크플로우

각 항목을 직접 메인 브랜치에 올리면 런타임 계약이 일시적으로 깨질 수 있는 다중 항목 작업을 위해, 하위 PR을 공유 통합 브랜치에 쌓고 마지막에 해당 브랜치를 하나의 PR로 스쿼시하여 메인 브랜치에 병합합니다. 각 하위 PR은 실제 단계 그대로 검토되며, 메인 브랜치로의 전달은 하나의 스쿼시 리베이스로 이루어집니다.

설정

.rig/config.json을 읽습니다 (괄호 안은 기본값):

• tracker.provider — linear | github | none (none). 상위/하위 항목 저장 방식을 결정합니다. none인 경우 항목은 에픽 상태 파일 (아래 참조)에만 저장되며, 트래커 호출이 없습니다.
• tracker.team / tracker.project / tracker.ticketPrefix / tracker.githubIntegration.
• vcs.baseRef (origin/main), vcs.defaultBranch (main), vcs.protectedBranchMergeQueue (false).
• sourceScope[0] — plan 중 탐색할 위치.
• agents.architect / agents.reviewer (기본값 rig-<role>) — 새 컨텍스트 review 패널용.

/rig-task (하위 항목별), /rig-worktree (체크아웃), /rig-review + /rig-review fix (결합된 diff 리뷰), /rig-tidy (선택 사항)에 위임합니다.

에픽 상태 파일 (외부 메모리 대체)

각 활성 에픽은 리포지토리 로컬 JSON 파일인 .rig/epics/<integration-branch>.json 에 추적됩니다:

{
  "parent": "ABC-42 또는 tracker=none인 경우 슬러그",
  "parentTitle": "...",
  "integrationBranch": "abc-42-<slug>",
  "whyEpic": "어떤 하위 항목이 어떻게 상호 얽혀 있는지",
  "children": [
    { "id": "ABC-43", "title": "...", "blockedBy": [], "branch": null, "status": "todo|merged" }
  ]
}

이것이 next/run/review/finish/prune이 읽는 단일 진실 공급원입니다. .rig/epics/를 .gitignore에 추가하세요 (일시적인 조정 상태입니다). 상위 항목 추론 ( <PARENT>가 생략된 경우): .rig/epics/*.json이 정확히 하나 있으면 사용하고, 없거나 여러 개이면 묻습니다.

의도 배너: 모든 호출은 첫 줄에 하나의 줄을 반드시 출력해야 합니다 — 모드, PR이 대상으로 하는 브랜치, 수행하지 않을 작업:

rig-epic: <서브커맨드> — <액션>. PR 대상 브랜치: <브랜치>. 수행하지 않음: <작업>.

status (기본값, 보고 전용)

에픽 상태 파일을 읽습니다. 보고: 통합 브랜치 + vcs.baseRef보다 앞선 커밋 수; 열린 하위 PR (gh pr list --base <integration-branch>) 및 해당 상태; 각 하위 항목의 트래커 상태 (트래커가 있는 경우); 남은 병합/삭제된 워크트리 (/rig-epic prune 제안); 한 줄 권장 사항 (하위 PR X 열기, /rig-epic next 준비 완료, 또는 /rig-epic finish 준비 완료). 아무것도 수정하지 않고, 아무것도 생성하지 않습니다.

plan <FEATURE>

기능을 상위 + 3~8개의 하위 항목으로 분해하고, 상태 파일을 작성한 후 start로 체인합니다.

작업이 진정한 에픽 형태일 때만 사용하세요 (하위 항목이 상호 얽혀 있음 — 즉, 적어도 하나의 하위 항목의 런타임 계약이 다른 하위 항목이 부분적으로 완료된 것에 의존함). 항목이 독립적이고 각각 메인 브랜치에 단독으로 올릴 수 있다면 중단하고 사용자에게 대신 /rig-sprint plan을 실행하라고 알리세요 — 동일한 분해 방식, 통합 브랜치 없음.

절차

1. 컨텍스트 읽기. 프로젝트에 제품/사양 문서가 있으면 읽기 (확실하지 않으면 묻기); 코드베이스 탐색 (sourceScope[0])하여 현재 상태 확인. 트래커가 구성된 경우 먼저 중복 항목을 검색.
2. 에픽 여부 확인 (위의 상호 얽힘 테스트 기준). 아니오 → /rig-sprint plan으로 전송.
3. 상위 항목 생성.
   • tracker: linear/github → 상위 항목 생성 (설정의 팀/프로젝트 사용); 설명에는 개요, 에픽인 이유, 계획된 하위 항목 포함.
   • tracker: none → 상위 항목은 상태 파일에만 기록된 슬러그 + 제목.
4. 각 하위 항목 생성 및 의존성 엣지 기록.
   • 단일 에이전트 세션에 충분히 작게 (1–3개 파일); 구체적이고 테스트 가능한 승인 기준; 기초 작업을 먼저.
   • 모든 실제 의존성에 대해 blockedBy 기록 — 이것이 next가 다음 차단되지 않은 하위 항목을 선택하기 위해 읽는 것입니다. 이것 없으면 선언 순서로 선택되어 얽힌 에픽에서 잘못됩니다.
   • 트래커 모드: 트래커의 네이티브 상위/차단 관계를 설정하고 상태 파일에 미러링. none: 상태 파일만.
5. 요약 테이블 표시 (ID · 제목 · 의존 대상).
6. start <PARENT>로 체인 — plan은 계획 및 시작입니다; 묻지 않고 진행.
7. start 후 중단. 통합 브랜치, 하위 항목, 다음 단계 (/rig-epic next 개별, /rig-epic run 반복) 보고. 절대 run을 자동 시작하지 마세요 — 실행은 명시적 옵트인입니다.

start <PARENT>

사전 점검: git fetch origin; 상위 항목과 하나 이상의 하위 항목이 존재하는지 확인 (트래커에서, 또는 none의 경우 인수로).

1. 통합 브랜치 이름: <parent-slug>-<title-slug> (케밥 케이스, 예: abc-42-agent-as-definition).
2. vcs.baseRef에서 통합 브랜치를 자르기 (로컬 체크아웃 없이):

   git fetch origin
   git push origin <vcs.baseRef>:refs/heads/<integration-branch>
   

   비파괴적. 브랜치가 이미 존재하면 그대로 둡니다 (절대 덮어쓰지 않음 — 진행 중인 작업을 파괴할 수 있음).
3. .rig/epics/<integration-branch>.json 작성 (위 스키마 사용) — 상위 항목, 에픽 이유, 모든 하위 항목 + blockedBy. 이것이 각 /rig-task <child>가 메인 브랜치 대신 통합 브랜치를 대상으로 하게 만듭니다.
4. 트래커가 구성된 경우, 각 하위 항목에 "통합 브랜치: 대상 <integration-branch>, 메인 브랜치 아님" 메모를 추가하여 다음 에이전트가 이 스킬을 다시 읽지 않도록 하고, 상위 항목이 진행 중(In Progress) 상태인지 확인 (적응형: 아직 시작되지 않은 경우에만 이동; 라이브 통합이 수행한 경우 연기). 하위 항목은 /rig-task 1단계에서 자체 진행 중 상태를 얻습니다.
5. 세션 이름을 "EPIC: <parent title> (<parent>)" 로 설정 (scripts/set-session-name.sh 통해; Claude Code 전용, 다른 곳에서는 무효)하여 백그라운드 작업 목록이 에픽으로 읽히도록 합니다. 하위 항목은 "FEAT:"/"CHORE:" 접두사로 자체 이름을 설정하며 --skip-if-prefix "EPIC:"이 적용되어 에픽 레이블이 위에 유지됩니다.
6. 보고: 브랜치, 하위 항목, 다음 단계.

next (단일 하위 항목)

1. 활성 통합 브랜치 확인 (하나 예상; 여러 개면 묻기). 세션이 아직 EPIC:으로 명명되지 않은 경우 (즉, next가 start를 통해 호출되지 않고 직접 호출된 경우), "EPIC: <parent title> (<parent>)"로 이름 지정 (Claude Code 전용).
2. 다음 차단되지 않은 하위 항목 선택: blockedBy가 모두 통합 브랜치에 병합된 첫 번째 완료되지 않은 하위 항목. 선택과 이유를 배너에 명시.
3. 이전 하위 항목이 병합되었는지 확인. --auto-merge (4단계)를 사용하면 각 하위 PR이 CI 통과 시 자체적으로 통합 브랜치에 병합되므로 통합 팁이 자동으로 진행됨 — git fetch origin으로 확인만 하면 됩니다. (--auto-merge 없이 실행된 하위 항목에 대한 대체: 해당 팁으로 브랜치를 빨리 감기 — git push origin origin/<previous-child-branch>:refs/heads/<integration-branch> — 해당 PR을 MERGED로 자동 닫습니다. 다시 실행해도 안전.)
4. /rig-task <CHILD> --base <integration-branch> --auto-merge 실행 (run의 사전 스펙 리뷰가 이미 스펙을 확인한 경우 --spec-cleared 추가) — --base는 하위 항목의 워크트리 브랜치가 통합 브랜치에서 나오고 PR도 이를 대상으로 하게 함; --auto-merge는 하위 항목이 자체 PR 검토 완료 후 gh pr merge --squash --auto를 활성화하여 CI가 통합 브랜치에 병합하도록 함 (항상 스쿼시 사용 — 리베이스 병합은 많은 리포지토리에서 허용되지 않음. 통합 브랜치에 필수 검사가 없으면 하위 항목이 직접 병합됨). 원샷 실행 (시작→완료); 병합 게이트에 대한 단일 결과 문자열 반환.
5. 병합 게이트 — clean만 병합 가능:
   • clean → 하위 항목이 자동 병합을 활성화했으므로 CI 통과 시 PR이 병합됨. 대기: gh pr view <N> --json state 폴링 (~60초, 최대 ~30분)하여 MERGED 상태가 될 때까지 기다린 후 git fetch origin으로 팁이 진행되었는지 확인. 상태 파일에 하위 항목 merged + 해당 브랜치 기록, 하위 항목 티켓이 완료(Done) 상태인지 확인 (적응형 — 이미 완료된 경우에만 이동; 라이브 통합이 닫은 경우 연기). CI 실패 / 병합되지 않음 → clean이 아닌 것으로 처리.
   • 그 외 (actionable/timeout, 또는 트래커에 의해 일시 중단된 상태) → 하위 항목이 자동 병합을 활성화하지 않음; 중단. 결과, PR URL, 리뷰어 요약 표시. 사용자 대기; 일시 중단된 리뷰를 재시도하지 않음.

next는 정확히 하나의 하위 항목을 처리합니다. 반복을 위해 run을 사용하세요.

run [--advisor]

사전 로드된 스펙 리뷰 — 루프 전에 한 번. 모든 하위 항목의 스펙을 함께 사전 검토하여, 실행 중에 한 번에 하나씩 차단 요소를 발견하는 것을 방지합니다. 스펙 질문에서 일시 중단된 하위 항목은 전체 에픽을 지연시키므로 (병렬 또는 지속 실행에서 일시 중단된 하위 항목은 배치 전체를 실패시킬 수 있음), 어떤 하위 항목도 코딩을 시작하기 전에 스펙을 해결합니다:

1. agents.architect + agents.qa를 모든 하위 항목의 스펙에 대해 확장하여 통합 브랜치를 기준으로 읽고, 각각의 차단 요소를 반환.
2. 하나의 차단 목록으로 통합하고 한 번에 해결 — 트래커에서 명확히 하거나 사용자와 결정. 이것이 에픽의 단일 스펙 결정 지점입니다.
3. 그런 다음 각 하위 항목을 자체 스펙 게이트가 사전 확인된 상태로 실행: /rig-task <CHILD> --base <integration-branch> --auto-merge --spec-cleared — 이미 답변된 질문에 대해 하위 항목이 다시 일시 중단되지 않도록 합니다.

이것은 코딩 전 스펙 패스입니다; 결합된 diff review (아래)는 병합 후 코드 패스입니다 — 다른 게이트입니다.

--advisor (무인). 사람 대신 어드바이저 패스를 사용하여 사전 로드된 게이트를 결정합니다: 위임된 agents.architect 리뷰가 아키텍트 + QA 스펙을 읽고 진행 (각 하위 항목의 코더에게 전달할 합성된 방향)하거나, 사람이 결정해야 할 항목을 명명한 차단 보고서와 함께 중단합니다. 사람이 기다리지 않으므로 에픽이 하위 PR까지 무인으로 실행됩니다; 진정한 차단 요소는 여전히 중단되어 잘못된 스펙으로 확장되는 것을 방지합니다. (페어링된 Smithers 지속 워크플로우는 저렴한 모델 — "Fable 어드바이저" — 로 이를 구현하여 시작된 에픽이 게이트에서 멈추지 않습니다.)

그런 다음 차단되지 않은 하위 항목이 없을 때까지 next를 반복합니다:

차단되지 않은 하위 항목이 있는 동안:
  /rig-epic next 실행            # 하위 항목은 --spec-cleared로 실행 (스펙이 사전 로드됨)
  병합 없이 중단되면 (결과 ≠ clean) → 중단, 반환
  그렇지 않으면 → 차단되지 않은 하위 항목 재평가

큐가 비면 "에픽 /rig-epic finish 준비 완료" 보고.

review [<PARENT>]

마지막 하위 항목이 통합 브랜치에 병합된 후, finish 전에 실행합니다. 각 /rig-task 내의 PR별 리뷰 (/rig-review)는 각 하위 항목을 격리하여 보지만, 이는 결합된 형태와 모든 것이 병합된 후에만 보이는 단순화를 확인합니다. 새 컨텍스트 하위 에이전트 (입력 = 스쿼시된 diff + 하위 PR 제목)는 구현자가 기억하는 합리화를 상속할 수 없습니다.

prune 전에 실행 — 리뷰 하위 에이전트는 작동하는 체크아웃이 필요합니다; 여전히 존재하는 하위 워크트리를 재사용 (새 설치 + 환경 재심볼릭 링크 방지).

1. 통합 브랜치 확인; git fetch origin.
2. 통합 브랜치 워크트리 확인 ($WT). 병합된 하위 워크트리를 통합 팁까지 빨리 감기하여 재사용하거나, /rig-worktree (--base <integration-branch> --reuse)로 새로 생성.
3. 세 개의 하위 에이전트를 병렬로 확장 (하나의 메시지, 세 개의 Agent 호출), 각각 cd $WT로 통합 팁 체크아웃:
   • 렌즈 1 — 단순화 (agents.architect): diff git diff <vcs.baseRef>...HEAD; 하위 PR 목록 gh pr list --base <BR> --state merged. 목표: 축소할 추상화, 하나의 PR이 추가했지만 다른 PR의 최종 형태가 중복으로 만든 헬퍼, 아무도 설정하지 않은 구성 변수, 결합된 diff에서 죽은 코드 경로, 단일 호출자 유형 찾기. 구체적인 삭제/병합, file:line, 영향이 큰 순서. 정확성은 건너뜁니다.
   • 렌즈 2 — 교차 PR 정확성 (agents.reviewer): 프로젝트의 리뷰 패턴 카탈로그 (review.patternsFile)를 결합된 diff에 대해 실행. PR별 리뷰는 이미 실행됨; 병합된 형태에서만 보이는 상호작용 포착 (PR-A의 헬퍼 vs PR-D의 오래된 호출자; PR-B가 제거한 노브를 PR-F가 여전히 읽음). P0/P1/P2, file:line + 카테고리 포함.
   • 렌즈 3 — 죽은 코드 및 오래된 참조 (agents.reviewer): diff가 추가한 모든 심볼에 대해, 다른 곳에서 호출됩니까? 제거된 모든 심볼에 대해, 트리 (워크플로우, 매니페스트, IaC, 스크립트, 문서)에서 잔여 참조를 grep. file:line으로 보고.
4. 통합 — 중복 제거, 렌즈별로 그룹화된 하나의 P0/P1/P2 목록 생성, 개수 출력.
5. 분류:
   • 항목 0개 → clean — /rig-epic finish 준비 완료, 중단.
   • 발견 사항 있음 → AskUserQuestion으로 질문: 지금 적용 / 건너뛰고 계속 마무리 (후속 작업으로 다운그레이드) / 일시 중지. 지금 적용 선택 시, $WT에서 /rig-review fix --source local 실행 (agents.coder 생성, clean까지 재리뷰), 커밋 + git push origin <integration-branch>, review를 한 번 재실행하여 수렴 확인.
6. 결과 문자열 (finish용): clean — ... / applied — ... / paused — ....

finish [<PARENT>] [--merge]

전체 통합 브랜치를 메인 브랜치에 대한 단일 PR로 스쿼시합니다. 기본값: PR을 열고 중단 — 이것이 눈으로 확인할 단일 PR입니다.

review는 하드 게이트입니다. finish는 항상 먼저 review를 실행합니다. 스쿼시 PR은 clean 또는 applied인 경우에만 열립니다. paused인 경우 중단하고 대기합니다.

1. review (게이트) 인라인 실행; 결과에 따라 분기 (clean/applied → 진행; paused → 중단 및 보류 중인 발견 사항 출력).
2. 필요시 새로 고침 및 리베이스. git fetch origin; git log <vcs.baseRef>..origin/<integration-branch> --oneline 나열. 메인 브랜치가 이동한 경우 통합 브랜치를 먼저 리베이스 (로컬 사본에서 git rebase <vcs.baseRef>, 그 다음 git push --force-with-lease origin <local>:<integration-branch>).
3. 최종 PR 열기 vcs.defaultBranch를 대상으로, 상위 항목을 참조하는 제목과 모든 하위 항목의 요약을 본문으로 포함. 종결 동사가 있는 트래커 (Fixes <PARENT> / Closes #<n>)가 있으면 포함하여 상위 항목이 자동 종료되도록 함.

...

[번역을 위해 잘림]