issue

Files (2)

• SKILL.md
• stages.md · references/

SKILL.md (first lines)

> Codex 질문: `request_user_input`은 해당 도구가 제공되는 Plan 모드에서만 사용한다. 현재 도구 스키마를 따른다. `preview` 필드는 없다. 다른 모드에서는 제공되는 비동기 질문 도구 또는 짧은 일반 질문을 사용한다. 승인과 선호도 질문을 구분하고, 무응답을 승인으로 간주하지 않는다.


# caseworker:issue — 이슈 라우터

`caseworker:issue <KEY[,KEY…]> [--adopt] [--stage <단계>] [--unattended]`

## 0. 원칙 (왜 이렇게 나뉘어 있나)

- **이 스킬은 판단만 한다.** 브랜치·상태 JSON·게이트·리뷰 기록은 전부 `scripts/` 가 쓰고, `git commit`/`git push` 는 훅이 판정한다.
  모델이 상태 JSON 의 `gate`/`review` 를 손으로 쓰면 훅과 어긋나 막히거나, 더 나쁘게는 게이트 없이 통과한다.
- 기록의 신선도는 **git 트리 id** 로 잰다. "테스트 돌렸다" 는 말은 증거가 아니고, 게이트가 본 트리와 커밋될 트리가 같아야 통과다.
- 사람 결정(승인·human DoD)은 건너뛰지 않는다. 무인 모드에서는 권장안을 택하되 **그렇게 했다고 기록**한다.

## 1. 매 호출 첫 동작 — 지금 어디인가

`<P>` = 플러그인 루트 절대 경로. 이 스킬이 로드될 때 표시되는 `Base directory for this skill` 의 **두 단계 위**다(`skills/issue` 의 부모의 부모). 아래 모든 명령의 `<P>` 를 그 경로로 치환하고, 프로젝트 루트(또는 그 worktree)에서 실행한다.

```bash
node "<P>/scripts/issue-start.mjs" --status --json
```

| `code` | 뜻 | 다음 |
|--------|----|------|
| `NO_HARNESS` | 이 저장소는 설정 전 | `caseworker:setup` 을 안내하고 멈춘다 |
| `OUTSIDE_PATTERN` | 이슈 브랜치가 아니다 | 키가 있으면 **start**(기본 브랜치에서 새 브랜치). 현재 브랜치를 그대로 쓰려면 `--adopt` |
| `NO_STATE` | 이슈 브랜치인데 상태 없음 | **start** (`issue-start.mjs <KEY>` — 브랜치는 그대로 두고 상태만 만든다) |
| `OK` | 진행 중 | 출력의 `stage`·`next` 대로 §2 의 그 단계부터. `--stage` 가 있으면 그 단계로 점프(뒤로 가는 재계획도 허용) |

사용자의 말이 `next` 보다 우선이다 — "커밋해줘" 는 stage 와 무관하게 **gate → commit** 이다.

## 2. 단계 표 — 각 행의 절차는 [references/stages.md](references/stages.md) 의 같은 이름 절을 읽고 따른다

트래커는 어댑터 하나다(기본 `local` — 파일, 의존성 0). 어댑터별로 라우터가 무엇을 더 해야 하는지·키 형식은 [references/trackers.md](references/trackers.md).

| stage | 한 줄 | 주체 · 수단 | 끝나면 |
|-------|------|------------|--------|
| start | 브랜치 채택/생성 · 상태 JSON · 트래커 착수(전이·댓글·본문 읽기) | `issue-start.mjs` + 트래커 op(출력 `tracker.ops` — direct 면 이미 실행됨, router 면 라우터가 MCP 로 수행) | grill (키 3개+ 또는 범위 불명이면 먼저 recon) |
| recon | 결정 분기점만 찾는 정찰(선택) | 메인 또는 허용된 `spawn_agent` (recon 계약: references/stages.md) (sonnet) | grill |
| grill | 분기점을 **한 번에 하나씩** 묻고 확정 | `caseworker:grilling` 을 그 자리에서 따른다 | `issue-set.mjs --decision` · `--stage plan` |
| plan | dev-guide 초안 + 레인·DoD 설계 → **사용자 승인** | 메인 또는 허용된 `spawn_agent` (plan 계약: references/stages.md) → `issue-set.mjs --merge --from plan` → request_user_input | 승인 시 `.draft` 확정 · `wiki-row.mjs` forecast · `--stage implement` |
| implement | 코드 작성 — 레인 1개면 메인 직접. 2개+ 는 **Herdr 안 + `herdr.lanes` 가 `implement`/`all`** 이면 레인마다 worktree + kind(claude·codex·grok) pane 이 driver 옆에서 고치고 메인이 패치를 회수·적용, Herdr 밖이면 메인 순차(또는 허용된 `spawn_agent`) | 직접 / `herdr-lanes.mjs implement`([herdr-lanes.md](references/herdr-lanes.md) §implement) / `spawn_agent` (implement 계약: references/stages.md) | verify |
| verify | **Codex 판정** → (Codex 가 못 채운 자리에만) 워크플로 ≤4레인 → **메인이 확정/기각** → 기록 | `codex-review.sh` → `lanes-codex.mjs verify` → `issue-set.mjs --review` | gate |
| gate | 커밋 전 경량(컴파일·린트) / push 전 전량(DoD 프로브 → 빌드·테스트·extra) | `gate.mjs --commit` / `gate.mjs --full` | commit / push |
| commit·push | 평소처럼 `git commit` / `git push` — 훅이 판정 | 훅 (`hooks/hooks.json`) · 무인은 `safe-commit.mjs` | 다음 구현 또는 complete |
| complete | 전량 게이트·리뷰 신선 확인 → push → 상태 아카이브 → wiki closure → 트래커 전이·댓글 | `issue-complete.mjs` → `wiki-row.mjs` → `wiki-lint.mjs` → 트래커 op(출력 `tracker.ops` — direct 면 이미 실행됨, router 면 라우터가 MCP 로 수행) | 사람 머지 대기 (자동 머지 금지) |

## 3. 훅이 막았을 때 — 사유 코드는 stderr 의 `[caseworker] git <op>: <CODE> — …` 한 줄

| 코드 | 뜻 | 조치 |
|------|----|------|
| `BRANCH_PATTERN` | 이슈 브랜치가 아니고 상태도 없다 | `issue-start.mjs <KEY> --adopt`(이 브랜치를 채택) 또는 기본 브랜치로 가서 start |
| `NO_STATE` | 이슈가 시작되지 않았다 | `issue-start.mjs <KEY>` |
| `COMPLETED` | complete 가 상태를 아카이브한 브랜치에 **코드** 커밋 | closure 문서(CHANGELOG·wiki)는 docs-only 로 통과한다. 코드를 더 바꾸려면 `issue-start.mjs <KEY> --adopt` 로 다시 시작 |
| `DIRTY_TREE` | 게이트가 본 트리 ≠ 커밋될 트리(unstaged·untracked) | 전부 `git add -A` 하거나 `gate.mjs --commit --stage-all` |
| `NO_GATE` `GATE_STALE` `GATE_FAIL` `GATE_LOG_*` | 게이트 미실행·낡음·실패·로그 불일치 | `gate.mjs --commit` (push 면 `--full`) 재실행 |
| `GATE_LEVEL` | push 인데 경량 게이트뿐 | `gate.mjs --full` |
| `NO_REVIEW` `REVIEW_STALE` | 리뷰 없음 · 리뷰 이후 코드 변경 | verify — 이미 한 번 했으면 **델타 패스**만 |
| `REVIEW_BLOCKERS` | 확정 blocker 미해결 | 수정 → 델타 패스 |
| `BAD_STATE` | 상태 JSON 이 스키마에 안 맞는다(손으로 고친 흔적) | `issue-set.mjs` 로 값을 고치거나 `issue-start.mjs <KEY>` 로 다시 만든다 |
| `BAD_CONFIG` `HOOK_ERROR` | harness.json 이 스키마에 안 맞거나 판정 중 예외(fail-closed). 명령의 `cd`/`-C` 가 없는 경로를 가리켜도 여기다 | 코드 문제가 아니다 — `caseworker:setup` 으로 설정을 고친다(우회 금지). "판정할 디렉토리가 없다" 면 `cd` 를 변수·`~` 가 아닌 실제 경로로 |

`issue-complete.mjs` 는 같은 사다리에 `CLAUDE_MD_TOO_LONG`·`PUSH_FAILED` 를 더한다(stages.md §complete). `DOCS_ONLY`·`MODE_OFF`·suggest 경고는 통과다. docs-only 는 `git add … && git commit` · `commit -a` 처럼 한 명령이 스테이징까지 하면 스테이징 *예정* 파일(staged+unstaged+untracked)로 판정한다 — 훅은 명령 실행 *전*에 보므로 그때 인덱스는 비어 있다. 훅을 우회하려고 `--no-verify` 나 상태 JSON 편집을 쓰지 않는다 — 막힌 이유를 고치는 것이 항상 더 짧다.

## 4. 변형

- **`--unattended`(무인)**: request_user_input 을 부르지 않고 권장안을 택한다(결정·승인에 `(unattended)` 표기). 사람 게이트(human DoD·머지)에 닿으면 멈추고 보고. 커밋은 `node "<P>/scripts/safe-commit.mjs" -m "<메시지>" [--push]` — 훅과 같은 판정을 스크립트가 하고 통과할 때만 커밋한다(훅이 발화하지 않는 헤드리스 경로에서도 같은 규율).
- **Codex 위임**: 역할 원고는 `subagents/*.toml`의 `developer_instructions`다. 위임이 허용되면 `spawn_agent`에 원고와 범위·입출력 계약을 전달하고, 아니면 메인이 순차 수행한다. 검증 레인은 `scripts/lanes-codex.mjs verify`가 `{findings, lanes, dropped, delta}`를 반환한다. 실패 레인은 검증 완료로 세지 않는다. **구현 레인은 Herdr 안이면 `scripts/herdr-lanes.mjs implement`** 가 레인마다 worktree + kind pane 을 띄우고 패치를 회수한다(Node 스크립트라 Codex 에서도 그대로 돈다) — Herdr 밖이면 메인이 순차 구현한다.
- **트래커가 router 인데 MCP 가 없는 세션**: 코드 진행은 그대로 한다. `tracker.ops`(전이·댓글)를 수행하지 못했다는 사실을 보고에 "트래커 미반영: `<KEY>` transition(…) — MCP 도구 없음" 으로 남기고, 사람이 직접 처리하거나 MCP 연결 후 재실행하게 한다. 수행하지 못한 op 를 "완료" 로 적지 않는다.
- **다중 키** `HX-a3f8,HX-b2c1`(jira 면 `ABC-696,ABC-940`): 브랜치 `feat/HX-a3f8-b2c1` 하나, dev-guide 한 장, 상태 JSON 하나. 트래커 op 는 키마다 만들어진다.
- **worktree**: 어느 worktree 에서 실행해도 상태·로그는 메인 저장소의 runtime 에 쓰인다 — 같은 브랜치의 게이트 기록을 worktree 와 메인이 공유한다.
- `harness.json` 의 게이트 명령이 틀렸으면 이 스킬에서 고치지 않는다 — `caseworker:setup` 의 일이다.

## 5. 멈출 때마다 보고 (5줄 이내)

`stage` · 방금 한 것 · 훅/게이트/리뷰 결과 코드와 분모(테스트 N건, blocker N건) · 다음 한 수 · 사용자 결정이 필요한지.

From bigbulgogiburger/caseworker, MIT.

More from bigbulgogiburger/caseworker