issue

Files (2)

• SKILL.md
• stages.md · references/

SKILL.md (first lines)

Codex 질문 도구: `request_user_input`은 제공되는 모드에서만 사용한다. 사용할 수 없으면 `request_user_input_async` 또는 간결한 평문 질문을 사용한다. 승인 요청은 현재 세션의 상위 지침을 따르고, 응답이 없다는 이유로 승인 처리하지 않는다.


# jira-harness 플러그인의 issue 스킬 — 이슈 라우터

`jira-harness 플러그인의 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` | 이 저장소는 설정 전 | `jira-harness 플러그인의 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) 의 같은 이름 절을 읽고 따른다

| stage | 한 줄 | 주체 · 수단 | 끝나면 |
|-------|------|------------|--------|
| start | **하위이슈 확장** · 브랜치 채택/생성 · 상태 JSON · Jira 착수(assignee·전이·댓글) | `issue-start.mjs` + Atlassian MCP 3콜 | grill (키 3개+ 또는 범위 불명이면 먼저 recon) |
| recon | 결정 분기점만 찾는 정찰(선택) | Workflow `workflows/recon.js` (sonnet) | grill |
| grill | 분기점을 **한 번에 하나씩** 묻고 확정 | `jira-harness 플러그인의 grilling 스킬` 을 그 자리에서 따른다 | `issue-set.mjs --decision` · `--stage plan` |
| plan | dev-guide 초안 + 레인·DoD 설계 → **사용자 승인** | Workflow `workflows/plan.js` → `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 이 고치고 메인이 패치를 회수·적용, Herdr 밖이면 메인이 순차 구현 | 직접 / `herdr-lanes.mjs implement`([herdr-lanes.md](references/herdr-lanes.md) §implement) | verify |
| verify | **Codex 판정** → (Codex 가 못 채운 자리에만) 워크플로 ≤4레인 → **메인이 확정/기각** → 기록 | `codex-review.sh` → `scripts/lanes-codex.mjs verify --json` → `issue-set.mjs --review` | gate |
| gate | 커밋 전 경량(컴파일·린트) / push 전 전량(DoD 프로브 → 빌드·테스트·extra → DoD tests) | `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 → Jira 전이·댓글 | `issue-complete.mjs` → `wiki-row.mjs` → `wiki-lint.mjs` → MCP | 사람 머지 대기 (자동 머지 금지) |

## 3. 훅이 막았을 때 — 사유 코드는 Codex 차단 메시지의 `[jira-harness] 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` 가 없는 경로를 가리켜도 여기다 | 코드 문제가 아니다 — `jira-harness 플러그인의 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 실행 경로**: verify 레인은 `scripts/lanes-codex.mjs`를 사용한다. 개별 역할 위임은 `subagents/<name>.toml`의 `developer_instructions`를 읽어 `spawn_agent` 프롬프트에 넣는다. Claude 에이전트 이름이나 모델 티어를 Codex 호출 인자로 넘기지 않는다. recon/plan 의 저장 워크플로는 아직 이식되지 않았다 — 해당 자동 실행을 요청받으면 미지원으로 보고하고 수동 진행 범위를 확인한다. **implement 는 이식됐다**: Herdr 안이고 `herdr.lanes` 가 `implement`/`all` 이면 `scripts/herdr-lanes.mjs implement` 가 레인마다 worktree + kind pane 을 띄우고 패치를 회수한다(Node 스크립트라 Codex 에서도 그대로 돈다). Herdr 밖이면 메인이 레인을 순차로 직접 구현한다.
- **하위이슈(항상)**: 사용자가 준 이슈는 **몇 개든** 그 하위이슈를 같이 꺼내 처리한다 — 플래그 없음("이 이슈만" 이라고 하면 건너뜀). start 직전에 키마다 `getJiraIssue` 로 읽어 `issue-subtasks.mjs` 로 풀고(끝난 하위·다른 프로젝트·`harness.json` `subtasks.match` 밖은 제외), 부모+하위를 아래 다중 키 한 브랜치로 처리한다. 구현은 Herdr 밖이면 한 작업트리(전략 A), Herdr 레인이면 하위마다 레인+worktree(전략 B) — stages.md §start·§implement·§complete.
- **다중 키** `ABC-696,ABC-940`(하위가 붙으면 `ABC-696-697-698` 꼴): 브랜치 `feat/ABC-696-940` 하나, dev-guide 한 장, 상태 JSON 하나. Jira 콜은 키마다.
- **worktree**: 어느 worktree 에서 실행해도 상태·로그는 메인 저장소의 runtime 에 쓰인다 — 같은 브랜치의 게이트 기록을 worktree 와 메인이 공유한다.
- `harness.json` 의 게이트 명령이 틀렸으면 이 스킬에서 고치지 않는다 — `jira-harness 플러그인의 setup 스킬` 의 일이다.

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

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

From bigbulgogiburger/jira-harness, MIT.

More from bigbulgogiburger/jira-harness