harness-workflow

Files (11)

• SKILL.md
• clarify.md · references/
• dod-flutter.md · references/dod/
• dod-frontend.md · references/dod/
• dod-springboot.md · references/dod/
• gate.md · references/
• parallel-modes.md · references/
• start.md · references/
• flutter.md · references/test-stacks/
• frontend.md · references/test-stacks/
• springboot.md · references/test-stacks/

SKILL.md (first lines)

# /harness-workflow — 통합 오케스트레이터 (유일 진입점)

> **직교 원칙**: 유지되는 Jira/Harness 스킬은 수정하지 않고 `Skill()` 로 호출. 상세 절차는 단계 진입 시에만 `references/<단계>.md` 를 Read (lazy-load 를 단계 레벨까지 연장).
> **폐기된 단독 명령** (2026-07-20, harness v2 설계 §3·ADR-106): `/jira-start` `/jira-clarify` `/jira-test` `/jira-commit` `/harness-resume` — 사용자가 이 이름으로 요청하면 해당 **단계만** 이 워크플로 절차로 수행하면 된다 (풀사이클 강제 아님).

## Usage

```
/harness-workflow <KEY>                # 단일 이슈 (BE+FE 걸치면 자동 2레인)
/harness-workflow <KEY1> <KEY2> ...    # 다중부모 fan-out (worktree 격리 — references/parallel-modes.md)
```

## ⛔ Guard — HARNESS_MODE (최우선)

`HARNESS_MODE` 확인: `suggest`/`auto` 면 진행, 미설정/빈값/`off` 면 안내 후 중단. 정책 SSoT: `~/.claude/skills/_harness-guard.md` (**`Skill()` 호출 금지** — Read 또는 env 직접 확인).

## 단계 결정표

| # | 단계 | 하는 일 | 상세/호출 | 산출물 | 게이트 |
|---|------|---------|-----------|--------|--------|
| ① | start | 이슈 조회·브랜치·assignee·In Progress | `references/start.md` | `feat/<KEY>` 브랜치 | — |
| ② | grill | 요구·결정사항 확정 (모호할 때만, 한 번에 한 질문) | `Skill('grilling')` + `references/clarify.md` (사전 크롤링) | 확정 결정 목록 | 이슈가 이미 구체적이면 skip |
| ③ | plan | recon → dev-guide 생성 (+ ingest forecast 자동 chain) | `Skill('jira-plan', <KEY>)` **필수 — 우회 금지** (§6 forecast 발화) | `docs/<KEY>-dev-guide.md` | INDEX.md cross-ref 선조회 (ALWAYS) |
| ④ | contract | DoD·Verify Targets·인간게이트 명시 | `Skill('harness-plan', <KEY>)` | `.claude/runtime/sprint-contract/<KEY>.md` | — |
| — | **승인** | dev-guide+contract 요약 제시 | — | — | **사용자 승인 필수** (수정 요청 시 ③ 복귀) |
| ⑤ | compile | (opt-in) dev-guide → step 컴파일 | `Skill('jira-compile', <KEY>)` — 대형 이슈·무인 실행 시에만 | `phases/<KEY>/index.json` + `step*.md` | 소형 이슈는 skip (러너는 opt-in) |
| ⑥ | execute | 구현 | attended: dynamic Workflow 레인 (`references/parallel-modes.md` — 모든 `agent()` 에 `opts.model`, 스모크 프로브) / unattended: `harness-execute.py` 러너 | 코드 + step summary | blocked/error 시 인간 개입 |
| ⑦ | review | fan-out 전문 리뷰 + Codex adversarial (`scripts/codex-review.sh` 래퍼) | `Skill('harness-review')` | `.claude/runtime/aggregate-verdict.md` | PASS→⑧ / ITERATE(≤3)→수정 후 재리뷰 / ESCALATE→재계획 |
| ⑧ | gate | 테스트+빌드 GREEN → DoD → 커밋 → Jira 댓글 | `references/gate.md` + `Skill('harness-gate')` | commit SHA | **review-gate hook 이 verdict≠PASS commit 물리 차단** (JSON deny) |
| ⑨ | complete | QA 전이 + push + closure ingest + wiki-lint | `Skill('jira-complete', <KEY>)` **필수 — 우회 금지** (§4.4/4.6/4.7 chain 발화) | INDEX row closed·LOG append | — |

**Phase 반복**: contract 의 Phase 수만큼 ⑥→⑦ 을 Phase 단위로 반복 (Inner Loop 는 같은 Phase 안에서만 — Phase 간 blocker 는 ESCALATE).

## 병렬 모드 (fan-out 표준 = dynamic Workflow)

- **모드 결정**: 부모 키 2개 이상 → 다중부모 fan-out / 단일 이슈 BE+FE → 2레인. 두 모드 모두 `references/parallel-modes.md` 가 SSoT.
- **Agent Teams 신규 사용 금지** (실측 결함 4건 — LOG 228·632, CHANGELOG 116·235). 구 `--subtasks` 정식 모드(ADR-070)는 표면 제거 — Jira 하위이슈가 있으면 댓글/전이만 부모와 함께 처리하고, 병렬 실행 단위는 위 2모드로 판단.
- 모델 티어링(메인=fable): fable=orchestration·verify·크로스레인 seam / opus=난이도 상 / sonnet=중·하. 규칙 3개(전 `agent()` model 명시·스모크 프로브·fable 레인 사유 필수)는 `references/parallel-modes.md`.

## 재개 (구 /harness-resume 폐기)

중단된 작업 재개 = 상태 파일 읽고 이어가기 한 줄:
1. `phases/<KEY>/index.json` 있으면 첫 `pending` step 부터 (러너/컴파일 이슈).
2. 없으면 `.claude/runtime/workflow-state.json`(이슈별 임시 산출물) + `sprint-contract/<KEY>.md` + 최신 `aggregate-verdict.md` 를 Read 후 결정표의 해당 단계부터 재개.
3. Jira 상태는 건드리지 않는다 (이미 ① 이 처리).

## 에러 핸들링

| 에러 | 처리 |
|------|------|
| 브랜치 충돌 | 사용자 알림, 수동 해결 후 재시도 |
| 빌드 실패 | 프로젝트 build-resolver 에이전트 제안 |
| 리뷰 에이전트 미존재 | 해당 축 스킵 + 경고 |
| Codex 래퍼 exit 42 | opus skeptic workflow 자동 폴백, verdict 에 `codex=fallback(<사유>)` |
| 3회 ITERATE 동일 blocker | ESCALATE → 재계획 제안 |

## HARNESS_MODE 동작

| 모드 | 동작 |
|------|------|
| `auto` | 전체 자동 진행, 승인 게이트만 수동. review-gate 가 commit 물리 차단 |
| `suggest` | plan/review/gate 단계마다 사용자 확인. review-gate 는 경고만 |
| `off` | 워크플로 호출은 동작하나 hook 비활성 |

## 자기 점검 (종료 직전)

`docs/INDEX-SCHEMA.md` 존재 시 — ③ ingest forecast + ⑨ closure ingest + wiki-lint summary 호출 흔적이 대화에 모두 있어야 함. 누락 감지 → 즉시 일괄 호출 + 사용자 보고.

From bigbulgogiburger/claude_jira_harness, MIT.

More from bigbulgogiburger/claude_jira_harness