[4.10] Claude/Codex 공용 Quality Gate 문서화

.agents/skills/branch-checkout/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: branch-checkout
+description: 작업 전용 Git 브랜치를 만들거나 전환한다. 별도 브랜치 체크아웃, task 브랜치 생성, 브랜치 전환 요청 시 사용.
+---
+
+# branch-checkout
+
+별도 작업 브랜치를 안전하게 만들거나 전환한다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`를 확인한다.
+2. 변경분이 있으면 요약하고, 전환해도 되는지 판단한다. 사용자 변경은 되돌리지 않는다.
+3. 필요하면 `git fetch origin`으로 원격 기준을 최신화한다.
+4. 기존 브랜치면 `git switch {branch}`를 실행한다.
+5. 새 브랜치면 `task/{task-id}-{short-slug}` 형식을 선호해 `git switch -c {branch}`를 실행한다.
+6. 전환 후 현재 브랜치와 남은 변경분을 보고한다.
+
+## 제한
+
+- `git reset --hard`, `git checkout --`, 강제 push는 실행하지 않는다.
+- 브랜치명이 불명확하면 Task ID나 사용자 목적에서 짧은 이름을 제안한다.

.agents/skills/git-push/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: git-push
+description: 현재 Git 브랜치를 안전하게 원격에 push한다. git push, upstream 설정, 작업 브랜치 게시 요청 시 사용.
+---
+
+# git-push
+
+현재 브랜치를 원격에 push한다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`를 확인한다.
+2. 현재 브랜치가 `main`/`master`면 push하지 말고 사용자 확인을 받는다.
+3. 커밋되지 않은 변경분이 있으면 push 대상이 아니므로 중단하고 보고한다.
+4. upstream이 있으면 `git push`를 실행한다.
+5. upstream이 없으면 `git push -u origin {current-branch}`를 실행한다.
+6. push 결과와 PR 작성 가능 여부를 보고한다.
+
+## 제한
+
+- `--force`, `--force-with-lease`는 사용하지 않는다.
+- 인증/권한/remote 오류는 원문을 요약하고 멈춘다.

.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: grill-me
+description: 아이디어·기능 요청을 한 번에 한 질문씩 인터뷰해서 docs/PRD.md 초안까지 작성한다. 새 프로젝트/기능 착수, PRD 작성, "grill me" 요청 시 사용.
+---
+
+# grill-me
+
+Codex용 PRD 인터뷰 스킬이다. `CLAUDE.md` 기획 규칙과 `.claude/skills/grill-me/SKILL.md`
+의 기존 의도를 따른다. 인터뷰만 하고 끝내지 말고 `docs/PRD.md` 작성까지 완료한다.
+
+## 절차
+
+1. 먼저 `AGENTS.md`, `CLAUDE.md`, 기존 `docs/PRD.md`, `docs/templates/PRD.md`를 읽는다.
+2. 코드베이스나 기존 문서로 답할 수 있는 내용은 직접 확인한다.
+3. 사용자에게 질문은 한 번에 하나만 한다.
+4. 모든 질문에는 권장 답과 이유를 함께 제시한다.
+5. 목적, 대상 사용자, 핵심 기능 3±2개, Non-goals, 측정 가능한 성공 기준이 나오면 질문을 멈춘다.
+6. `docs/templates/PRD.md`를 기준으로 `docs/PRD.md`를 작성하고, 미확정 항목은 Open Questions에 남긴다.
+7. 승인 후 UserFlow·DESIGN·Architecture 보완과 `$harness-plan` 실행을 안내한다.
+
+## 기본값
+
+- 산출 경로 기본값은 현재 프로젝트의 `docs/`다.
+- 사용자가 응답하지 않거나 headless 환경이면, 이미 확정된 내용과 권장 답을 기준으로 초안을 쓰고 미확정 항목을 Open Questions에 남긴다.

.agents/skills/harness-plan/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: harness-plan
+description: PRD·기획 문서를 실행 가능한 Task proposal로 분해하고 검증 후 tasks/index.json에 반영한다. Task 추가·변경이나 계획 수립 요청 시 사용.
+---
+
+# harness-plan
+
+Codex에서 Claude Code `/harness-plan`에 해당하는 절차를 직접 수행한다. `Plans.md`를
+직접 편집하지 않는다.
+
+## 절차
+
+1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `tasks/index.json`, `Plans.md`, 필요한 기획 문서를 읽는다.
+2. `python3 scripts/build_planning_context.py`로 planning context를 만든다.
+3. `harness.toml [plan].decomposer_command`가 있으면 그 명령으로 proposal을 만든다.
+4. 명령이 없거나 실패하고 `allow_inline_fallback = true`이면, 현재 Codex 세션이 `agents/task-decomposer.md` 기준으로 같은 proposal 파일 계약을 채운다.
+5. `python3 scripts/validate_task_proposal.py ...`로 proposal을 검증한다.
+6. 통과한 경우에만 `python3 scripts/apply_task_proposal.py ...`로 `tasks/index.json`에 반영한다.
+7. `python3 scripts/sync_plans.py`로 `Plans.md`를 재생성하고 `python3 scripts/validate_tasks.py`로 확인한다.
+
+## 규칙
+
+- proposal은 확정본이 아니다. 검증 전에는 `tasks/index.json`을 수정하지 않는다.
+- `.harness/events/planning.jsonl`의 사용자-facing 메시지는 쉬운 문장으로 남긴다.
+- 새 Task는 `agents/task-decomposer.md`의 INVEST·DoD·Acceptance 기준과
+  `agents/quality-gates.md`의 scope/YAGNI 기준을 만족해야 한다.

.agents/skills/harness-progress/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: harness-progress
+description: tasks/index.json 기준으로 진행 상황을 읽기 전용 요약한다. 상태 확인, 진행률, 다음 작업 추천 요청 시 사용.
+---
+
+# harness-progress
+
+`tasks/index.json`을 단일 출처로 진행 상황을 요약한다. 기본적으로 상태를 변경하지 않는다.
+
+## 절차
+
+1. `AGENTS.md`, `CLAUDE.md`, `tasks/index.json`을 읽는다.
+2. 필요하면 `python3 scripts/report_tasks.py`를 실행한다.
+3. `todo`, `wip`, `blocked`, `done` 수와 다음에 착수 가능한 Task를 요약한다.
+4. `Plans.md`가 stale일 가능성이 있으면 `python3 scripts/sync_plans.py --check` 결과를 보고한다.
+
+## 규칙
+
+- 사용자가 명시적으로 요청하지 않으면 `Plans.md`를 재생성하지 않는다.
+- Task 상태를 바꾸지 않는다.

.agents/skills/harness-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: harness-review
+description: 현재 diff를 Task, CLAUDE.md 규칙, Acceptance evidence 기준으로 코드 리뷰한다. 리뷰 요청이나 PR 전 점검 시 사용.
+---
+
+# harness-review
+
+Codex에서 Claude Code `/harness-review`에 해당하는 리뷰 절차를 수행한다.
+
+## 절차
+
+1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, 대상 Task, Acceptance evidence, 현재 diff를 읽는다.
+2. 코드 리뷰 관점으로 버그, 회귀 위험, 누락된 테스트, 규칙 위반, `agents/quality-gates.md` 위반을 우선 찾는다.
+3. findings를 심각도순으로 먼저 보고하고, 각 항목은 파일·라인 근거를 포함한다.
+4. 문제가 없으면 "발견 없음"을 명확히 말하고 남은 테스트 gap이나 잔여 위험만 짧게 남긴다.
+
+## 판정
+
+- `APPROVE`: blocker 없음, Acceptance evidence가 충분함.
+- `REQUEST_CHANGES`: 동작 버그, 규칙 위반, Acceptance 미실행/실패, 테스트 누락이 Task 완료를 막음.
+
+리뷰 중 직접 수정하지 않는다. 수정이 필요하면 findings를 근거로 구현 단계로 되돌린다.
+findings는 `agents/quality-gates.md`의 review/reporting gate처럼 먼저 보고하고,
+문제가 없으면 테스트 gap과 잔여 위험만 짧게 남긴다.

.agents/skills/harness-sync/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: harness-sync
+description: tasks/index.json을 검증하고 Plans.md snapshot을 재생성한다. 계획 동기화, snapshot 갱신 요청 시 사용.
+---
+
+# harness-sync
+
+`tasks/index.json`을 검증하고 `Plans.md` 읽기용 snapshot을 최신화한다.
+
+## 절차
+
+1. `AGENTS.md`, `CLAUDE.md`, `tasks/index.json`, `Plans.md`를 읽는다.
+2. `python3 scripts/validate_tasks.py`를 실행한다.
+3. 검증이 통과하면 `python3 scripts/sync_plans.py`를 실행한다.
+4. 다시 `python3 scripts/sync_plans.py --check`로 동기화 여부를 확인한다.
+
+## 규칙
+
+- `Plans.md`는 생성물이다. 직접 편집하지 않는다.
+- 검증 실패 시 `Plans.md`를 갱신하지 말고 실패 원인과 수정 필요 지점을 보고한다.

.agents/skills/harness-work/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: harness-work
+description: todo Task 하나를 선택해 세분화 게이트를 확인하고 구현, Acceptance, 테스트, 리뷰까지 진행한다. Task 구현 요청 시 사용.
+---
+
+# harness-work
+
+Codex에서 Claude Code `/harness-work`에 해당하는 절차를 직접 수행한다.
+
+## 절차
+
+1. `AGENTS.md`, `CLAUDE.md`, `agents/quality-gates.md`, `.harness/STATE.md`, 최근 `.harness/LESSONS.md`, `tasks/index.json`, `Plans.md`를 읽는다.
+2. 수행할 `todo` Task 하나를 고른다. 사용자가 지정한 Task가 있으면 그 Task를 우선한다.
+3. 구현 전 `agents/task-decomposer.md`의 세분화 기준과 `agents/quality-gates.md`의 scope/YAGNI 체크를 확인한다.
+4. 기준 미달이면 구현하지 말고 `$harness-plan` 절차로 하위 Task proposal을 만든다.
+5. 기준 통과 시 `.harness/STATE.md`를 갱신하고 구현한다.
+6. 작업 중 범위가 커지면 중단하고 `agents/quality-gates.md`의 split 조건과 task-decomposer 기준으로 재분해한다.
+7. 구현 후 `agents/test-agent.md` 절차대로 해당 Task Acceptance 명령과 관련 테스트 스위트를 실행한다.
+8. 검증 실패 시 수정 후 재실행한다.
+9. 검증 통과 후 `$harness-review` 절차로 현재 diff를 리뷰한다.
+
+## 완료 기준
+
+- Acceptance와 관련 테스트가 통과해야 한다.
+- Acceptance와 관련 테스트 통과 후 에이전트가 `tasks/index.json`의 대상 Task를
+  `done`으로 갱신하고 `Plans.md`를 재생성한다. GitHub Actions는 Task 상태를
+  전환하지 않는다.
+- 새 파일이나 역할 변경은 `.harness/CONTEXT_INDEX.md`에 반영한다.
+- ponytail/caveman Codex plugin 자동 동작을 가정하지 않는다. Codex에서는
+  `agents/quality-gates.md`를 직접 적용한다.

.agents/skills/pr-create/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: pr-create
+description: 현재 작업 브랜치에서 GitHub PR을 작성한다. PR 생성, draft PR 작성, Task 기반 PR 본문 작성 요청 시 사용.
+---
+
+# pr-create
+
+현재 작업 브랜치에서 GitHub PR을 작성한다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`를 확인한다.
+2. 현재 브랜치가 `main`/`master`면 PR을 만들지 않는다.
+3. 커밋되지 않은 변경분이 있으면 커밋이 필요하다고 보고하고 중단한다.
+4. 대상 Task를 `tasks/index.json`에서 확인한다.
+5. PR 본문에 변경 요약, 검증 결과, DoD/Acceptance evidence, 남은 위험을 포함한다.
+6. Task의 `gh` 값이 `#N`이면 `Closes #N`을 포함한다.
+7. 기본은 `gh pr create --draft`다. 사용자가 ready PR을 명시하면 draft를 생략할 수 있다.
+8. 생성 후 PR URL과 남은 merge gate를 보고한다.
+
+## 제한
+
+- Acceptance evidence가 없거나 리뷰가 `REQUEST_CHANGES`면 PR 생성 전 중단한다.
+- Task 상태 변경은 PR 생성 전에 Acceptance evidence와 함께 이미 반영돼 있어야 한다.
+  GitHub Actions가 상태를 대신 전환하지 않는다.

.claude/commands/branch-checkout.md

@@ -0,0 +1,24 @@
+---
+description: Create or switch to a dedicated task branch after checking repository state.
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git switch:*), Bash(git fetch:*), Read
+---
+
+# /branch-checkout
+
+별도 작업 브랜치를 만들거나 체크아웃한다. 사용자가 지정한 브랜치명이 있으면 사용하고,
+없으면 대상 Task ID와 제목을 바탕으로 `task/{task-id}-{short-slug}` 형식을 제안한다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`로 현재 상태를 확인한다.
+2. 변경분이 있으면 사용자 변경을 덮지 않도록 요약하고, 그대로 브랜치를 전환해도 되는지 확인한다.
+3. 필요하면 `git fetch origin`으로 원격 기준을 최신화한다.
+4. 기존 브랜치면 `git switch {branch}`를 실행한다.
+5. 새 브랜치면 기본 브랜치 기준을 확인한 뒤 `git switch -c {branch}`를 실행한다.
+6. 전환 후 현재 브랜치와 남은 변경분을 보고한다.
+
+## 주의
+
+- `git checkout --`, `git reset --hard`, 강제 push는 실행하지 않는다.
+- Task 브랜치는 `CLAUDE.md`의 GitHub 플로우에 맞춰 `task/{task-id}-{짧은-설명}`을 선호한다.
+- 인자: `$ARGUMENTS`

.claude/commands/git-push.md

@@ -0,0 +1,24 @@
+---
+description: Push the current branch safely after checking status, branch, and upstream.
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git remote:*), Bash(git push:*), Read
+---
+
+# /git-push
+
+현재 브랜치를 원격에 push한다. push 전에 브랜치, 변경분, upstream을 확인하고
+강제 push는 하지 않는다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`를 확인한다.
+2. 현재 브랜치가 `main`/`master`면 push하지 말고 사용자에게 확인을 요청한다.
+3. 커밋되지 않은 변경분이 있으면 push 대상이 아님을 알리고 중단한다.
+4. upstream이 있으면 `git push`를 실행한다.
+5. upstream이 없으면 `git push -u origin {current-branch}`를 실행한다.
+6. push 결과와 다음 단계(PR 작성 여부)를 보고한다.
+
+## 주의
+
+- `--force`, `--force-with-lease`는 사용하지 않는다.
+- 인증 실패나 remote 없음은 원문 에러를 보고하고 멈춘다.
+- 인자: `$ARGUMENTS`

.claude/commands/pr-create.md

@@ -0,0 +1,26 @@
+---
+description: Create a GitHub pull request from the current task branch with task and acceptance context.
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*), Bash(gh pr create:*), Bash(gh pr view:*), Read
+---
+
+# /pr-create
+
+현재 작업 브랜치에서 GitHub PR을 작성한다. PR 본문에는 Task, DoD, Acceptance evidence,
+리뷰 상태, 이슈 연결 정보를 포함한다.
+
+## 절차
+
+1. `git status --short`와 `git branch --show-current`를 확인한다.
+2. 현재 브랜치가 `main`/`master`면 PR을 만들지 않는다.
+3. 커밋되지 않은 변경분이 있으면 PR 생성 전에 커밋 필요 여부를 보고하고 중단한다.
+4. 대상 Task를 `tasks/index.json`에서 확인하고, `gh`가 `#N`이면 PR 본문에 `Closes #N`을 넣는다.
+5. Acceptance와 관련 테스트 실행 증거를 PR 본문에 요약한다.
+6. `gh pr create --draft`를 기본으로 사용한다. 사용자가 ready PR을 명시하면 draft를 생략할 수 있다.
+7. 생성 후 PR URL과 남은 merge gate를 보고한다.
+
+## 주의
+
+- `REQUEST_CHANGES` 상태이거나 Acceptance evidence가 없으면 PR 생성 전 중단한다.
+- Task 상태 변경은 PR 생성 전에 Acceptance evidence와 함께 이미 반영돼 있어야 한다.
+  GitHub Actions가 상태를 대신 전환하지 않는다.
+- 인자: `$ARGUMENTS`