docs(agent-ops): agent-ops 스킬·룰·라우터 갱신

- router: refine-local-plans 라우팅 추가, plan/review 역할 경계 명시
- plan: review stub 템플릿 및 SKILL.md 보강
- code-review: SKILL.md, agent yaml, user-review 템플릿 갱신
- finalize-task-routing: SKILL.md 및 agent yaml 갱신
- _templates: implementation-user-review-request-section 수정
- rules/common/rules.md, AGENTS.md: archive 접근 예외 확장
This commit is contained in:
toki 2026-07-22 18:10:19 +09:00
parent 56767f8a35
commit e8df747b5f
12 changed files with 387 additions and 265 deletions

View file

@ -8,7 +8,7 @@
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다.
- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**``agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다.
- `agent-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
@ -52,4 +52,4 @@
**테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**
- local: `agent-test/local/rules.md` (없으면 `create-test`)
- local: `agent-test/local/rules.md` (없으면 `create-test`)

View file

@ -8,7 +8,7 @@
- 코드 변경 전 관련 domain rule을 먼저 확인한다.
- 요청 범위를 넘는 변경을 하지 않는다.
- 불확실하면 단정하지 말고 후보를 제시한다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, 또는 plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우에만 필요한 파일을 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다.
- `agent-task/archive/**`는 일반 작업에서 읽지 않는다. 예외: 사용자가 과거 작업 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우, active `PLAN-*.md` / `CODE_REVIEW-*.md` / `USER_REVIEW.md`가 특정 archive evidence 경로를 명시한 경우, plan/code-review 루프의 split subtask 선행 의존성 충족 여부를 확인하는 경우, 또는 plan 스킬이 같은 task group의 새 index를 충돌 없이 할당하는 경우에만 필요한 범위를 좁게 읽는다. split 의존성 확인은 같은 task group의 후보 `complete.log`만 읽을 수 있다. index 할당은 같은 task group의 archived sibling directory basename만 열람하고 내부 파일은 읽지 않는다.
- `agent-roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다.
- `agent-ui/` 디렉터리가 있는 프로젝트에서도 `agent-ui/definition/archive/**``agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다. UI 과거 결정, 복원, 비교, 해결된 user review 확인이 필요한 경우에만 `agent-ops/rules/common/rules-agent-ui.md`의 archive 접근 규칙을 따른다.
- `agent-spec/` 디렉터리가 있는 프로젝트에서 현재 구현 스펙 확인, 기존 기능 변경, 완료 검토, 구현 스펙 생성/갱신 요청은 세션 1회 `agent-ops/rules/common/rules-agent-spec.md`를 읽고, `agent-spec/index.md`와 매칭되는 spec 문서만 읽는다.
@ -52,4 +52,4 @@
**테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**
- local: `agent-test/local/rules.md` (없으면 `create-test`)
- local: `agent-test/local/rules.md` (없으면 `create-test`)

View file

@ -1,6 +1,6 @@
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
_선택된 Milestone `구현 잠금 > 결정 필요`가 구현을 막을 때만 채운다. 이 섹션을 포함한 모든 구현 소유 섹션을 채운 뒤 `review-ready`를 보고하고 종료한다. code-review를 실행하거나 review model을 시작하지 않는다._
- 상태: 없음
- 사유 유형: 없음
@ -8,5 +8,5 @@ _기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 후속으로 해결할 수 없는 이유: 없음
- 재개 조건: 없음

View file

@ -1,6 +1,6 @@
---
name: code-review
description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, implementation-time 사용자 리뷰 요청, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state. PASS writes complete.log and moves the task to archive; WARN/FAIL must invoke the plan skill, which reruns finalize-task-routing before writing the next pair, unless the user-review gate requires USER_REVIEW.md.
description: "Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, NEXT_STATE.md recovery, implementation-time 사용자 리뷰 요청, or 리뷰 루프. Review and archive one active pair, then leave exactly one next artifact: a follow-up PLAN/CODE_REVIEW pair, USER_REVIEW.md, or complete.log. Plan, implementation, and review use different models."
---
# Code Review
@ -10,41 +10,60 @@ description: Use for active task review requests such as 리뷰 진행해, 리
Review the implementation phase of the plan-code-review loop:
```text
plan skill -> finalize-task-routing -> implementation -> code-review skill
^ |
+----- WARN/FAIL: invoke plan skill with raw findings -+
plan model -> implementation model -> review model
^ |
+-- different plan model on WARN/FAIL -+
```
Implementation may stop early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. This is the only implementation-time decision-stop path, and it is valid only for a selected Milestone `구현 잠금 > 결정 필요` item. Implementation must not ask the user directly, present choices in chat, or call a user-input tool such as `request_user_input`. Code-review validates that request and, when justified, writes `USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`.
Implementation may end its coding phase early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. This path is valid only for a selected Milestone `구현 잠금 > 결정 필요` item. The implementation model must not ask the user directly, call a user-input tool, or execute code-review. It fills every implementation-owned section, reports `review-ready`, and stops for a later review model.
The review agent must select exactly one next-state artifact before ending:
- **Plan**: a different plan model writes one follow-up PLAN/CODE_REVIEW pair.
- **User review**: the review agent writes `USER_REVIEW.md`.
- **Complete**: the review agent writes `complete.log` and archives the task.
Archived findings or `plan-ready` alone are not a valid review result.
The three-output rule begins only after a `review-ready` pair or resolvable `USER_REVIEW.md` passes preflight. An unfilled stub remains in the implementation stage and is not a started review.
`NEXT_STATE.md` is a transient recovery record with `kind: pair-finalization` or `kind: user-review-resolution`. It must exist before destructive transition work and is removed as the final filesystem mutation only after the selected branch is fully verified.
## Hard Actor Boundary
- Plan, implementation, and review use different model identities; separate agents or reasoning settings on the same model do not satisfy this rule.
- Runtime must preserve the exact selected task path and runtime-provided model identities through every handoff. A filled role identity is immutable for that pair; a retry uses the same model identity. Lane/G and agent names are not model identities.
- The review model owns the verdict, archive, and USER_REVIEW/complete finalization. It must not edit product source/tests or author a follow-up plan.
- On WARN/FAIL, dispatch a plan model different from both the implementation and review models. End only after the follow-up pair exists; do not implement it.
## Core Loop Rules
- Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` or `USER_REVIEW.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`.
- Finalize every selected active state: for `CODE_REVIEW-*-G??.md`, append one verdict, prepare the required next state, archive the active review and plan files, then materialize exactly one next state; for `USER_REVIEW.md` completion, update the stop state, write `complete.log`, and archive the task.
- Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-<milestone-slug>`, report completion metadata for the runtime event. `WARN` or `FAIL` normally invokes `agent-ops/skills/common/plan/SKILL.md`, which must run `finalize-task-routing` before writing the next active pair; if the user-review gate triggers, write `USER_REVIEW.md` instead. A completed `USER_REVIEW.md` uses the same terminal `complete.log` and archive path as `PASS`.
- A filled implementation-owned `사용자 리뷰 요청` is a review input, not a next state by itself. The user-review gate triggers only when the request is tied to a concrete selected Milestone `구현 잠금 > 결정 필요` item. If it is vague, unsupported, repo-fixable, about external environment/secret/service setup, a generic scope conflict, loop exhaustion, or only missing evidence that a follow-up agent can produce by rerunning commands or collecting artifacts, invoke the plan skill for a normal WARN/FAIL follow-up instead.
- Do not replace `USER_REVIEW.md` with an inline user question. When the user-review gate triggers, write the file-based stop state and report its path.
- Do not ask for confirmation before WARN/FAIL follow-up files. If the user-review gate triggers, write `USER_REVIEW.md`; otherwise invoke the plan skill with the current raw findings and let it write the smallest concrete follow-up after fresh routing.
- Recovery: if a prior turn appended a verdict without archive or next-state files, do not append another verdict; resume Step 5 preparation/archive from that verdict. If exactly one member of the pair was archived after both archive destinations had been preflighted, verify the archived member and remaining source/destination, finish that archive, then use the post-archive recovery below. If both logs exist with a verdict but the required next state is absent, reconstruct it from those exact logs: PASS resumes `complete.log`; WARN/FAIL reruns the plan skill in `write` mode with raw archived findings and `isolated-reassessment`; a valid user-review gate rerenders `USER_REVIEW.md`. If a prior turn resolved `USER_REVIEW.md` without `complete.log`, resume at the matching finalization step.
- Keep the selected `{task_name}` through review finalization.
- `PASS`: archive the pair, write `complete.log`, and move the task to monthly archive.
- `WARN`/`FAIL`: apply the user-review gate, then archive the pair. Write `USER_REVIEW.md` for a valid gate; otherwise dispatch a different plan model to write the follow-up pair.
- A filled `사용자 리뷰 요청` is valid only for a selected Milestone lock decision. Otherwise record the blocker as a WARN/FAIL finding for the next plan model.
- Do not replace `USER_REVIEW.md` with an inline user question. When the gate triggers, write the file-based stop state and include its path in the final report.
- Every unresolved `Required` forces `FAIL`; every `Suggested` forces `WARN`. Both require a follow-up pair unless the user-review gate writes `USER_REVIEW.md`.
- Recovery: finish missing review-owned finalization, then dispatch the different plan model when WARN/FAIL lacks a follow-up pair. Never plan or implement with the review model.
## User Review Gate
`USER_REVIEW.md` is a loop stop state only for selected Milestone lock decisions. Default to a normal WARN/FAIL follow-up; the gate requires positive evidence that the blocker is already represented, or must be represented, as a Milestone `구현 잠금 > 결정 필요` item.
`USER_REVIEW.md` is a loop stop state only for selected Milestone lock decisions. The default WARN/FAIL branch creates a follow-up pair through a different plan model. The gate requires positive evidence that the blocker is already represented as a concrete selected Milestone `구현 잠금 > 결정 필요` item.
- Compute `review-number` as `count(agent-task/{task_name}/code_review_*.log) + 1` before archiving the active review.
- Repeated `WARN`/`FAIL`, loop exhaustion, missing verification evidence, and test environment blockers do not trigger `USER_REVIEW.md` by themselves. Invoke the plan skill for a narrower follow-up or report the non-roadmap blocker as verification evidence that remains unresolved.
- Derive the pending review archive suffix as `0` when no `code_review_*.log` exists, otherwise `max(existing numeric suffix) + 1`; set `review-number` to that suffix plus one.
- Repeated `WARN`/`FAIL`, missing verification evidence, and environment blockers do not trigger `USER_REVIEW.md`; record them as findings for the next plan model.
- If the active review file has a filled `사용자 리뷰 요청` with `상태` other than `없음`, validate that `사유 유형` is `milestone-lock`, that `연결 대상` points to the selected Milestone, and that the requested decision matches a Milestone `구현 잠금 > 결정 필요` item.
- If the filled request is about external environment/secret/service setup, unsupported device, generic scope conflict, agent execution limits, missing handoff evidence, incomplete verification records, or anything not tied to the Milestone lock, do not write `USER_REVIEW.md`; archive the review and invoke the plan skill for a normal WARN/FAIL follow-up when implementation can continue, or report the blocker without asking the user.
- A valid Milestone-lock request is `Required`/`FAIL` and writes `USER_REVIEW.md` instead of a follow-up pair.
- If the request is not tied to the Milestone lock, do not write `USER_REVIEW.md`; record it as a WARN/FAIL finding.
- `USER_REVIEW.md` is created from `agent-ops/skills/common/code-review/templates/user-review-template.md`, filled with the archived loop history, current archived plan/review paths, verdict, loop count, blocking evidence, connection target, and the exact Milestone decision item.
## User Review Resolution
When an active `USER_REVIEW.md` exists and the linked Milestone decision closes the task as complete/PASS, finalization is still owned by this skill.
When an active `USER_REVIEW.md` exists, it remains terminal until the linked Milestone decision is resolved. After resolution, this skill either completes PASS finalization or dispatches a different plan model when more implementation is required.
- Read `USER_REVIEW.md`, archived `plan_*.log`, and archived `code_review_*.log` in that task directory.
- Verify the linked decision and any follow-up evidence are sufficient to close the task. If a new implementation plan is needed instead, do not close; route back to the plan skill, which archives `USER_REVIEW.md` to `user_review_N.log` before writing a new plan.
- Update `USER_REVIEW.md` in place to show a resolved state, final verdict, loop history, fulfilled decision items, and the evidence that closed the stop state.
- Write `complete.log` from `agent-ops/skills/common/code-review/templates/complete-log-template.md` before moving or archiving the task directory. Include both the original archived review verdict and the user-review resolution line in `루프 이력`.
- Verify that the linked decision is resolved. If it is unresolved, leave `USER_REVIEW.md` unchanged. If it requires implementation, record the resolution in that file and write `NEXT_STATE.md` with `kind: user-review-resolution`, `target: plan`, task, plan number, source path, expected `user_review_N.log`, archived plan/review evidence paths, and forbidden implementation/review model identities. Archive it using `N=0` or `max(existing numeric suffix) + 1`, then dispatch a different plan model. Verify the pair, update the applicable archived checklist, prepare the report, and remove the pending file as the final filesystem mutation.
- If the resolved decision closes the task, first select and preflight the exact collision-safe task archive path. Write `NEXT_STATE.md` with `kind: user-review-resolution`, `target: complete`, `task`, `plan`, `completion_timestamp`, `archive_month`, `task_archive_path`, source path, and archived evidence. Then update `USER_REVIEW.md` in place with that timestamp, resolved state, final verdict, loop history, fulfilled decision items, and closing evidence. Reuse the timestamp and archive path in finalization.
- On that complete/PASS branch, write `complete.log` from `agent-ops/skills/common/code-review/templates/complete-log-template.md` before moving or archiving the task directory. Include both the original archived review verdict and the user-review resolution line in `루프 이력`.
- Then apply the same task-directory archive move and `m-<milestone-slug>` PASS completion metadata rules as a normal `PASS`.
- Do not leave an active task directory that contains `USER_REVIEW.md` and `*.log` files but no `complete.log` after the linked Milestone decision resolves the task as complete/PASS.
@ -88,27 +107,27 @@ Milestone task group contract:
- Do not call `update-roadmap` from this skill. The runtime consumes the PASS completion event, checks current state, resolves the active Milestone, and calls `update-roadmap` if needed.
- For `m-<milestone-slug>` PASS tasks, report the original active task path, final archive path, complete log path, task group, and milestone slug so the runtime has deterministic event inputs.
Follow-up routing boundary:
Follow-up handoff:
- This skill records current source, actual verification output, and findings, but it must not estimate or recommend the next lane/G.
- On WARN/FAIL, invoke the plan skill in `prepare-follow-up` mode with the selected task path and raw current evidence before archiving the current pair.
- Do not pass the archived lane, grade, routing score, rationale, or filename as plan-routing input. Archive paths remain evidence pointers, and actual logs/findings remain raw evidence.
- The plan skill must complete its full analysis and mandatory `finalize-task-routing` step before it writes the next pair. Code-review must not create a routed follow-up pair directly.
- Repair non-behavioral review artifact drift during review instead of failing solely for it when implementation correctness, tests, and contracts remain judgeable.
- Record concrete findings, affected paths, verification evidence, and release conditions in the archived review log.
- The review model must not choose the next lane/G or write the follow-up pair.
- Dispatch a different plan model with the exact archived log paths. That model performs isolated routing, writes the pair, reports `implementation-ready`, and stops.
- The review agent is responsible for ensuring that the follow-up pair exists, even though the different plan model authors it.
Directory states:
| State | Meaning |
|-------|---------|
| `PLAN-*-G??.md` + unfilled `CODE_REVIEW-*-G??.md` stub/placeholders | Implementation is not judgeable; review should fail completeness if invoked |
| `PLAN-*-G??.md` + unfilled `CODE_REVIEW-*-G??.md` stub/placeholders | `implementation-ready` or incomplete implementation; do not start review or append a verdict |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation claims a selected Milestone lock decision blocker; review validates the request and writes `USER_REVIEW.md` only if justified |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` without verdict | Ready for code-review skill |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Review finalization pending; do not append another verdict, resume Step 5 preparation/archive |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` without verdict | `review-ready`; the review model may consume it |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Transitional; do not append another verdict and immediately resume Step 5 preparation/archive |
| Exactly one active pair member + its newly archived counterpart | Partial archive after a preflighted finalization; verify both identities, finish the remaining archive, then resume post-archive recovery |
| `NEXT_STATE.md` | Review finalization is in progress; resume its recorded target and do not start implementation |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; linked Milestone lock decision must be resolved before creating another plan |
| `USER_REVIEW.md` + `*.log` files | Linked Milestone decision is required |
| `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS or user-review-resolved PASS); not active |
| Only `*.log` files (no `complete.log`) | If the newest review log has a verdict and its required next state is absent, post-archive finalization is pending; otherwise the task is terminated mid-loop or abandoned |
| Only matching `plan_*.log` / `code_review_*.log` with WARN/FAIL | Internal `plan-ready`; dispatch a different plan model to create the follow-up pair |
The implementing agent never archives or deletes active files; archiving is this skill's responsibility.
@ -124,6 +143,8 @@ Also note active user-review stops, excluding `agent-task/archive/**`:
- `agent-task/*/USER_REVIEW.md`
- `agent-task/*/*/USER_REVIEW.md`
Also find `NEXT_STATE.md` with the same one-level and two-level task globs. A selected pending file takes precedence over other classification: validate its task/plan identity and resume its recorded target. If several exist and no task path was selected, list them without mutation.
Classify the combined set of active `CODE_REVIEW-*-G??.md` and `USER_REVIEW.md` paths. Apply the first matching row:
| Result | Action |
@ -134,14 +155,17 @@ Classify the combined set of active `CODE_REVIEW-*-G??.md` and `USER_REVIEW.md`
| No active paths | Apply the finalization-recovery scan below; stop only when it finds no recoverable task. |
| Multiple active paths | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active path, use that directory. Otherwise list paths and stop with an ambiguity report; do not choose by agent judgment and do not create a user-review request for routing ambiguity. |
If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state instead of overwriting either state.
If a selected task directory contains both `USER_REVIEW.md` and an active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, do not overwrite either state or ask the user to choose between files. Validate provenance: a valid unresolved `USER_REVIEW.md` remains the terminal state; otherwise resume the provable active-pair or finalization recovery path and preserve the inconsistent path as review evidence.
Finalization-recovery scan, excluding `agent-task/archive/**`:
An unfilled review stub is not `review-ready`. Leave the pair unchanged and return it to the implementation stage; this precondition check occurs before review begins.
- Candidate A has exactly one active plan, no active review/USER_REVIEW/complete.log, and a newest review log whose verdict belongs to that plan's current loop.
- Candidate B has no active plan/review/USER_REVIEW/complete.log, and its newest plan/review logs form one loop whose review verdict requires a missing next state.
- Accept only candidates whose exact source/archive identities and verdict can be proven from headers, log suffixes, and review contents. Do not treat a generic log-only abandoned directory as recoverable.
- If the user/runtime names one candidate task path, resume it. Otherwise resume only when exactly one candidate exists; list multiple candidates as ambiguity. Use the Core Loop Rules recovery path and never append a second verdict.
Finalization-recovery scan covers active task paths plus the narrow archive exceptions `agent-task/archive/*/*/*/NEXT_STATE.md` and `agent-task/archive/*/*/*/*/NEXT_STATE.md`:
- Find task directories with `NEXT_STATE.md`, a verdict-appended active review, a partially archived pair, `complete.log` not yet moved, or matching archived plan/review logs with no active pair, `USER_REVIEW.md`, or `complete.log`. Inside archive, inspect only the pending file and its named artifacts; after a task move, resolve those artifact basenames under its persisted `task_archive_path`.
- Match plan/review artifacts by their `task` and `plan` headers, not by modification time alone.
- Recover the user/runtime-selected task path. Without one, recover only a single unambiguous candidate; list multiple candidates without mutating them.
- Resume a verdict or partial archive at Step 5. Move a pending `complete.log` task. For archived WARN/FAIL without a next artifact, dispatch the different plan model. For archived PASS or a valid gate, finish the missing `complete.log` or `USER_REVIEW.md`. If legacy recovery lacks `NEXT_STATE.md`, reconstruct it from the exact headers, verdict, and archive paths before continuing.
- A newly created unfilled follow-up pair already satisfies the prior review's Plan output; do not review it until implementation makes it `review-ready`.
## Step 2 - Load Context
@ -159,14 +183,15 @@ If the active plan or review file contains `Agent UI Completion`, also read `age
Before writing the verdict:
- Compare actual source files against every planned checklist item.
- Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`; repair non-behavioral drift when implementation remains judgeable.
- Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`. Do not edit either checklist to repair drift; when correction is needed, record it as a WARN/FAIL finding.
- When the active artifacts have `Roadmap Targets`, check whether the referenced Milestone has `SDD: 필요`. When it does, read only that Milestone and its SDD, compare implementation evidence against the SDD Acceptance Scenarios/Evidence Map for the targeted task ids, and fail completeness or verification trust when evidence is insufficient. Do not require a separate SDD target section.
- Directly repair obvious non-behavioral source nits when safe: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change.
- Record obvious non-behavioral source nits such as typos, stale comments, docs, or formatting. Do not edit source/test files during review; Nit-only findings may follow the PASS rule below.
- If a checklist item contains integrated verification for a feature, treat that feature item as incomplete until both implementation evidence and the matching verification output are present. Do not accept a separate unchecked completion-criteria item as a substitute.
- Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item; repair clear artifact drift when evidence supports completion.
- Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item. Do not mark or rewrite implementation-owned items on its behalf; classify missing or inconsistent entries by their effect on completeness and verification trust.
- Verify that the Plan identity matches in both files and that the review stub records the Implementation identity. Require runtime to record the Review identity before verdict; filled identities are immutable. Reject review start unless all three are pairwise different, and do not infer identity from lane/G or agent name.
- If the active plan or review file contains `Agent UI Completion`, verify the implementation-owned fields are filled before PASS: listed agent-ui docs exist, actual code evidence paths exist, requested status updates are explicit, and implementation verification evidence is present. Missing or untrusted evidence is a completeness or verification-trust issue.
- Treat review artifact gaps as failures only when they prevent judging implementation correctness, tests, contracts, or verification trust.
- Read the `사용자 리뷰 요청` section. If `상태` is not `없음`, validate the exact decision needed, `연결 대상`, blocker evidence, command output or not-run reason, why automatic follow-up cannot resolve it, and resume condition before deciding whether the user-review gate triggers. Reject the request unless it is tied to a selected Milestone `구현 잠금 > 결정 필요` item.
- Read `사용자 리뷰 요청`. If filled, validate the exact linked Milestone decision and blocker evidence; reject non-lock requests.
- Grep renamed/removed symbols for stale references.
- Confirm every required test exists, name matches, and assertions are meaningful.
- Cross-check claimed verification output in the active review file against actual code and project commands.
@ -176,7 +201,7 @@ Before writing the verdict:
Append `코드리뷰 결과` to the active `CODE_REVIEW-*-G??.md`.
Before appending `PASS`, if all other PASS conditions are met and the active review file contains `Agent UI Completion`, perform the review-pass status update first: update the listed agent-ui docs to `구현됨`, add actual code evidence, run `validate-agent-ui`, and mark the section's review-agent-owned finalization items. If this update or validation fails, do not append `PASS`; classify the failure as `WARN` or `FAIL` and write the normal follow-up.
Before appending `PASS`, if all other PASS conditions are met and the active review file contains `Agent UI Completion`, perform the review-pass status update first: update the listed agent-ui docs to `구현됨`, add actual code evidence, run `validate-agent-ui`, and mark the section's review-agent-owned finalization items. If this update or validation fails, do not append `PASS`; classify and record it as a normal WARN/FAIL finding.
Required fields:
@ -192,14 +217,14 @@ Severity semantics:
| Verdict | Meaning | Follow-up plan |
|---------|---------|----------------|
| `PASS` | No Required/Suggested issues. Nit-only findings may still PASS. | No |
| `WARN` | One or more Suggested issues, zero Required. | Yes, unless the user-review gate triggers |
| `FAIL` | One or more Required issues. | Yes, unless the user-review gate triggers |
| `WARN` | One or more Suggested issues, zero Required. | Follow-up pair via a different plan model; a valid gate is normally `FAIL` |
| `FAIL` | One or more Required issues, including a valid Milestone-lock request. | Follow-up pair via a different plan model, except a valid `USER_REVIEW.md` gate |
Issue severity:
- `Required`: correctness, API contract, missing required test, missing integrated verification, plan-completeness issue, or review artifact gaps that prevent judging implementation quality.
- `Required`: correctness, API contract, missing required test, missing integrated verification, plan-completeness issue, review artifact gaps that prevent judging implementation quality, or a valid selected Milestone-lock decision that blocks implementation.
- `Suggested`: useful improvement that should enter the loop but does not block correctness.
- `Nit`: tiny cleanup; directly repair obvious non-behavioral cases when safe, otherwise record without forcing WARN.
- `Nit`: tiny cleanup; record it without editing implementation-owned files or forcing WARN.
Verdict consistency:
@ -207,38 +232,19 @@ Verdict consistency:
- Any Fail dimension or any Required issue forces `FAIL`.
- Any Warn dimension or any Suggested issue forces `WARN`, unless the only findings are explicitly Nit and every dimension remains Pass.
## Step 5 - Prepare Next State And Archive Active Files
## Step 5 - Archive Active Files
Do not archive WARN/FAIL files until the next-state content is fully prepared in memory.
- `PASS`: no routed follow-up preparation is required.
- `WARN`/`FAIL`: apply the user-review gate before any rename.
- If the gate triggers, render the complete `USER_REVIEW.md` body from `agent-ops/skills/common/code-review/templates/user-review-template.md` in memory.
- Otherwise build the follow-up handoff described below and fully execute `agent-ops/skills/common/plan/SKILL.md` in `prepare-follow-up` mode.
Before preparing a follow-up, count the existing logs and parse each current active basename. Set `current_review_archive_number=count(code_review_*.log)` and `current_plan_archive_number=count(plan_*.log)`. Derive `current_review_archive_name` and `current_plan_archive_name` from the current active files' own lane/grade plus those numbers. These names describe the pair being closed, not the next route.
The follow-up handoff contains the selected `{task_name}`, current verdict, Required/Suggested/Nit findings, affected files, actual verification output, current ownership/dependency facts, roadmap carryover, `REVIEW_<PARENT_TAG>`, and those predicted current-pair archive names. Keep current active paths only as evidence pointers. Do not add the prior lane, grade, routing score, rationale, or a preferred next route to the neutral routing snapshot, and require plan to omit route-bearing basenames from the isolated routing input. The plan may use current archive names only after routing to render `Archive Evidence Snapshot`.
- `prepare-follow-up` must return `status: routed`, the exact routed basenames, `prepared_plan`, `prepared_review`, `plan_number`, `current_plan_archive_name`, `current_plan_archive_number`, `current_review_archive_name`, `current_review_archive_number`, `plan_log_number`, `review_log_number`, and `gitignore_repair_needed`. It must have executed `finalize-task-routing` in `isolated-reassessment` mode.
- Verify that the returned current archive names/numbers equal the values derived before preparation, and that `plan_log_number` / `review_log_number` are the post-archive counts embedded in the new review stub for its future archive.
- If preparation returns `needs_evidence`, continue evidence collection and rerun it before archiving.
- If preparation returns `blocked`, leave the verdict-appended active PLAN/CODE_REVIEW pair in place, do not check archive/next-state items, and report a resumable finalization blocker. A later code-review invocation resumes this step without appending another verdict.
After the required next state is prepared, archive is mandatory for `PASS`, `WARN`, and `FAIL`. Ensure `.gitignore` has the Agent-Ops managed gitignore block for task artifacts before writing `*.log` outputs. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, and `agent-roadmap/current.md`. Apply the repair here when `prepare-follow-up` returned `gitignore_repair_needed: true`.
Preflight both archive operations before either rename:
1. Recount existing `code_review_*.log` as `current_review_archive_number`. Parse the active review's lane/grade from its own basename and derive `current_review_archive_name=code_review_{current_review_lane}_{current_review_grade}_{current_review_archive_number}.log`.
2. Recount existing `plan_*.log` as `current_plan_archive_number`. Parse the active plan's lane/grade from its own basename and derive `current_plan_archive_name=plan_{current_build_lane}_{current_build_grade}_{current_plan_archive_number}.log`.
3. Require both destinations not to exist. When the active stub contains concrete expected archive names, require them to match the derived names; legacy generic placeholders do not override the derived values.
4. For WARN/FAIL, require exact matches with both prepared current archive names/numbers. If any check fails, do not rename either file.
After both operations pass preflight, rename the active review and then the active plan to those exact names. If either current archive count or derived name changed after preparation, discard the prepared pair and rerun plan `prepare-follow-up` before renaming. After archiving, verify that the actual plan/review log counts equal the prepared `plan_log_number` and `review_log_number`; neither active `.md` file remains until Step 6 materializes the prepared next state.
- For a valid user-review gate, render `USER_REVIEW.md` in memory before renaming.
- Ensure `.gitignore` exposes `agent-task/**/*.md` and `agent-task/**/*.log`.
- Derive each archive suffix as `0` when no matching log exists, otherwise `max(existing numeric suffix) + 1`; combine it with that active file's own lane/grade.
- Compute and preflight both destinations before the first rename. Partial-archive recovery must reuse those expected destinations, not recompute after one rename.
- For a new archive, require both destinations to be absent. For partial recovery, require the existing destination to match the pending identity and only the remaining destination to be absent.
- Before the first rename, write `NEXT_STATE.md` with no placeholders: `kind: pair-finalization`, `task`, `plan`, `verdict`, `target` (`plan`, `user-review`, or `complete`), active basenames, expected archive paths, and the implementation/review model identities forbidden for a follow-up Plan model. For `target: complete`, also select, preflight, and persist `completion_timestamp`, `archive_month`, and the exact collision-safe `task_archive_path`. Reuse an identical pending file during recovery; reject conflicting contents.
- Rename the review, then the plan. Verify no active pair remains.
## Step 6 - Post-Review Actions
For `PASS`, write `agent-task/{task_name}/complete.log` before reporting. If a `USER_REVIEW.md` stop is resolved as complete/PASS, write the same `complete.log` before archiving that task.
For `PASS`, write `agent-task/{task_name}/complete.log` using the timestamp persisted in `NEXT_STATE.md`. If a `USER_REVIEW.md` stop is resolved as complete/PASS, use its fixed resolution timestamp. Write `complete.log` before archiving that task.
Complete log template:
@ -250,46 +256,48 @@ Complete log template:
- If the archived review log contains `Agent UI Completion`, copy the completed evidence into `complete.log`. If there is no `Agent UI Completion` section, remove the optional complete-log section entirely.
- Use `없음` for empty `잔여 Nit` or `후속 작업`.
- A PASS `complete.log` must not contain unresolved Required or Suggested issues. Nit-only leftovers may be recorded under `잔여 Nit`.
- After verifying `complete.log`, keep the matching `NEXT_STATE.md` until task movement and archived checklist finalization finish.
For `WARN` or `FAIL`, materialize the next state prepared in Step 5 immediately after archive:
For `WARN` or `FAIL` after archive:
- If the user-review gate triggered, write the prepared body to `agent-task/{task_name}/USER_REVIEW.md`. It must use only `milestone-lock`, contain every archived loop entry plus the exact linked decision, and contain no placeholder. Do not write active PLAN/CODE_REVIEW files or `complete.log`.
- Otherwise write `prepared_plan` and `prepared_review` byte-for-byte to their routed basenames. Do not rerun, adjust, compare, or upgrade their lane/G after archive.
- Verify the written follow-up pair contains the predicted archived plan/review paths in identical `Archive Evidence Snapshot` sections and contains no unresolved token from the review-stub template inventory. Unrelated braces in commands or code are allowed.
- A prior local failure never changes the prepared pair into an automatic cloud upgrade.
- If the user-review gate triggered, write and verify `USER_REVIEW.md`, then keep the matching `NEXT_STATE.md` through Step 7 finalization.
- Otherwise dispatch a different plan model with the archived plan/review paths and wait for its `implementation-ready` result. Require one new routed PLAN/CODE_REVIEW pair at the same task path, verify it, then keep the matching `NEXT_STATE.md` through Step 7 finalization. The review model must not write that pair or edit product source/tests.
- Stop before implementation.
If the task group is `m-<milestone-slug>` and the user-review gate triggered, report that the milestone task is blocked on user review; do not emit PASS completion metadata and do not call `update-roadmap`.
If the task group is `m-<milestone-slug>` and the user-review gate triggered, prepare a blocked-on-user-review report; do not emit PASS completion metadata and do not call `update-roadmap`.
## Step 7 - Complete Review-Only Checklist, Move PASS Task, And Report
After Step 6:
- If verdict is `PASS`, determine archive month from the current completion date as `YYYY/MM`, create the needed archive parent directories, then move the selected active task directory `agent-task/{task_name}/` to `agent-task/archive/YYYY/MM/{task_name}/`. For split work, the selected active task directory is the subtask directory, and the archive must preserve the task group path, e.g. `agent-task/refactoring/01_core/` moves to `agent-task/archive/YYYY/MM/refactoring/01_core/`.
- Do not overwrite an existing archive directory. If `agent-task/archive/YYYY/MM/{task_name}/` already exists, append the next numeric suffix to the final path segment: single-plan `agent-task/archive/YYYY/MM/{task_group}_1/`, split-plan `agent-task/archive/YYYY/MM/{task_group}/{subtask_dir}_1/`, and so on.
- If verdict is `PASS`, create the parent of the exact task archive path persisted in `NEXT_STATE.md`, preflight it again, then move the selected active task directory there. Recovery must reuse that path and timestamp rather than the current date or a newly calculated suffix.
- Select collision suffixes before writing `NEXT_STATE.md`: if the natural monthly destination exists, append the next numeric suffix to the final path segment. Never overwrite or recalculate the persisted destination during recovery.
- After moving a split subtask, remove the active parent `agent-task/{task_group}/` only if it is empty. If sibling subtask directories or other files remain, leave the parent task group in place.
- If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. Report completion event metadata after the task archive move: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, `complete.log` path, archived plan/review log paths, and `roadmap-completion=<Task ids from complete.log or none>`.
- If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. After the task archive move, prepare completion event metadata: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, `complete.log` path, archived plan/review log paths, and `roadmap-completion=<Task ids from complete.log or none>`.
- The runtime consumes that completion event, checks current state, and calls `update-roadmap` if needed. `update-roadmap` only checks Milestone Task ids when `complete.log` contains `Roadmap Completion`; if the section is absent, roadmap Task completion is a no-op even for `m-*` task groups.
- If verdict is `PASS` and the archived review log contains `Agent UI Completion`, ensure the listed agent-ui status/evidence update and `validate-agent-ui` check are complete before writing or finalizing `complete.log`. Do not defer this to runtime or Milestone completion.
- `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-<milestone-slug>` task group when the original task was Milestone-linked.
- `WARN` and `FAIL` do not update the roadmap Milestone. The dispatched plan model keeps the same task path.
- `USER_REVIEW` does not update the roadmap Milestone and does not produce PASS completion metadata. Keep the active task directory in place with `USER_REVIEW.md` and archived plan/review logs until the linked Milestone lock decision is resolved.
- If `USER_REVIEW.md` is later resolved as complete/PASS by linked Milestone decision and evidence, write `complete.log`, move the task directory to archive, and report `m-*` PASS completion metadata just like a normal `PASS`.
- For `PASS`, open the moved `agent-task/archive/YYYY/MM/{final_task_name}/{current_review_archive_name}`, where `{final_task_name}` is the archived task path, including `{task_group}/` for split work.
- For user-review-resolved PASS, confirm the moved archive contains the resolved `USER_REVIEW.md`, `complete.log`, and the existing archived `plan_*.log` / `code_review_*.log`; do not recreate an active review file only to add a new checklist item.
- For `WARN` or `FAIL`, open `agent-task/{task_name}/{current_review_archive_name}`.
- Run `git check-ignore -q --` on the generated task artifacts (`plan_*.log`, `code_review_*.log`, `user_review_*.log` when present, `complete.log` when present, and active follow-up `.md` files). If any are ignored, apply the Agent-Ops managed gitignore block and re-check before reporting.
- Run `git check-ignore -q --` on generated logs and terminal files. If any are ignored, repair the Agent-Ops block and re-check.
- Check every applicable item in `코드리뷰 전용 체크리스트`; leave mutually exclusive verdict items unchecked.
- If any applicable item cannot be checked, finish the missing archive, `complete.log`, task-directory move, mandatory plan-skill follow-up, or `USER_REVIEW.md` write first.
- If any applicable item cannot be checked, finish the missing archive, follow-up pair handoff, `complete.log`, task-directory move, or `USER_REVIEW.md` write first.
- Do not recreate an active review file just to update this checklist; update the archived `code_review_*.log`.
- Only report after the archived review log has the verdict, applicable checked review-only checklist, required next-state files, for `PASS` or user-review-resolved PASS the final task archive move, for `m-*` PASS tasks the completion event metadata, and for unresolved `USER_REVIEW` the filled `USER_REVIEW.md`.
- Complete every applicable archived checklist item and prepare the branch report with its final paths and metadata.
- Remove `NEXT_STATE.md` from the active task or moved archive as the final filesystem mutation only after the selected artifact, archived checklist, and report data are verified.
- Report only after confirming that `NEXT_STATE.md` no longer exists.
Report Required/Suggested counts, archive names, the final task archive path for `PASS`, the new plan path for normal `WARN`/`FAIL`, the `USER_REVIEW.md` path for user review stops, and any `m-*` runtime completion event metadata.
Report exactly one output: follow-up plan pair, `USER_REVIEW.md`, or `complete.log`. Include the relevant paths.
## Review Dimensions
| Dimension | Check |
|-----------|-------|
| Correctness | Logic, edge cases, concurrency, errors |
| Completeness | Planned implementation/verification items are done; review artifact drift is repaired when judgeable |
| Completeness | Planned implementation/verification items are done; implementation-owned artifact drift is classified and routed without reviewer edits |
| Test coverage | Required tests present and meaningful |
| API contract | Call sites, compatibility, docs |
| Code quality | No debug prints, dead code, leftover TODOs |
@ -303,25 +311,27 @@ Report Required/Suggested counts, archive names, the final task archive path for
- Name exact stale symbols or missing tests.
- Do not write vague praise or style opinions without a rule.
- Every dimension gets Pass/Warn/Fail.
- For follow-up plans about verification trust, specify deterministic commands, for example `rg --sort path`, and forbid repo-local tool artifacts.
- For verification-trust findings, specify deterministic commands, for example `rg --sort path`, and forbid repo-local tool artifacts.
## Final Checklist
- Exactly one next-state outcome was selected: a follow-up PLAN/CODE_REVIEW pair, `USER_REVIEW.md`, or `complete.log`.
- `NEXT_STATE.md` was written before archive mutation, retained through branch finalization, and removed as the final filesystem mutation before reporting.
- `{current_review_archive_name}` exists with the verdict appended and was derived from the archived active review's own route.
- `{current_plan_archive_name}` exists and was derived from the archived active plan's own route.
- `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`; generated task artifacts are not ignored by `git check-ignore`.
- No active `.md` files remain after PASS or user-review-resolved PASS.
- PASS or user-review-resolved PASS: `complete.log` written from `agent-ops/skills/common/code-review/templates/complete-log-template.md`, then task directory moved under `agent-task/archive/YYYY/MM/` with task-group path preserved for split work.
- PASS milestone task group: `m-<milestone-slug>` completion event metadata was reported for runtime; roadmap was not modified by code-review.
- PASS milestone task group: `m-<milestone-slug>` completion event metadata is prepared for runtime; roadmap was not modified by code-review.
- PASS with `Roadmap Targets`: `complete.log` contains `Roadmap Completion` with Milestone path, Task ids, archived plan/review evidence, and verification evidence.
- PASS without `Roadmap Targets`: `complete.log` omits `Roadmap Completion` and reported metadata says `roadmap-completion=none`.
- PASS without `Roadmap Targets`: `complete.log` omits `Roadmap Completion` and prepared metadata says `roadmap-completion=none`.
- PASS with `Agent UI Completion`: listed agent-ui docs were updated to `구현됨` with code evidence, `validate-agent-ui` passed, and `complete.log` contains `Agent UI Completion`.
- PASS without `Agent UI Completion`: complete.log omits `Agent UI Completion`.
- PASS split: empty active parent `agent-task/{task_group}/` removed after the subtask move; non-empty parent left in place.
- WARN/FAIL without user-review gate: the plan skill was invoked for the exact task path, completed `finalize-task-routing`, and created new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` files matching the fresh routed output; no `complete.log`.
- WARN/FAIL follow-up: the plan input omitted prior lane/G assessment, and the new active plan/review stub contain identical `Archive Evidence Snapshot` sections with prior archived plan/review log paths, verdict, issue summary, affected files, verification evidence, and specific archive paths allowed for narrow reread when needed.
- WARN/FAIL without user-review gate: a different plan model wrote one follow-up pair, the reviewer did not plan or implement, and the `implementation-ready` report is prepared.
- Follow-up review stubs include the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` and forbid direct user prompts during implementation.
- USER_REVIEW: `USER_REVIEW.md` exists from template, no active `PLAN-*.md` or `CODE_REVIEW-*.md` remains, and no `complete.log` was written.
- Implementation-requested USER_REVIEW: archived review log preserves the filled `사용자 리뷰 요청` evidence and the generated `USER_REVIEW.md` records the exact linked Milestone decision needed.
- USER_REVIEW resolved as PASS: archived task contains both resolved `USER_REVIEW.md` and `complete.log`.
- USER_REVIEW resolved to more implementation: `USER_REVIEW.md` was archived to `user_review_N.log`, a different plan model wrote one follow-up pair, and the `implementation-ready` report is prepared.
- The applicable review-agent-only finalization checklist was completed before reporting.

View file

@ -1,4 +1,4 @@
interface:
display_name: "Code Review"
short_description: "Review and route task loops"
default_prompt: "Use $code-review to review or resolve the active task, archive it, and on WARN/FAIL invoke $plan so $finalize-task-routing creates the next routed pair."
short_description: "Review and leave the required next artifact"
default_prompt: "Use $code-review to leave exactly one result: a follow-up pair authored by a different Plan model, USER_REVIEW.md, or complete.log."

View file

@ -47,4 +47,4 @@ USER_REVIEW
## 종료 규칙
- 연결 결정과 evidence가 이 stop state를 완료/PASS로 해소하면 `USER_REVIEW.md`를 해소 상태로 갱신하고, `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
- 새 구현이 필요하면 `plan` 스킬이 `USER_REVIEW.md``user_review_N.log`로 아카이브한 뒤 새 `PLAN-*-G??.md` / `CODE_REVIEW-*-G??.md`를 작성한다.
- 새 구현이 필요하면 review가 해소 결과와 `kind: user-review-resolution`, `target: plan`, task/plan, 예상 user-review archive, 기존 loop evidence, 금지 model identity를 `NEXT_STATE.md`에 기록한 뒤 `USER_REVIEW.md`를 아카이브한다. 다른 Plan 모델이 새 pair를 작성하면 review가 검증하고 pending 파일 제거를 마지막 파일 변경으로 수행한다.

View file

@ -10,6 +10,8 @@ description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/
계획 분석이 끝난 뒤 구현과 리뷰 target의 lane과 G 등급을 처음부터 평가하고 canonical 파일명을 반환한다.
이 스킬은 라우팅 판단의 단일 원본이며 plan/review 내용을 작성하거나 task 파일을 직접 생성하지 않는다.
Lane/G는 capability 요구사항이다. Runtime은 plan, build, review를 서로 다른 모델 identity에 배정해야 하며, 같은 lane/G여도 같은 모델을 재사용하면 안 된다.
## 언제 호출할지
- `plan`이 최초 PLAN/CODE_REVIEW pair를 쓰기 직전
@ -20,15 +22,15 @@ description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/
## 입력
- `targets`: `build`, `review`, 또는 둘 다. `plan`은 항상 둘 다 전달한다 (필수)
- `evaluation_mode`: 이전 라우팅이 없는 최초 평가는 `first-pass`, 무효화된 기존 라우팅이 있는 평가`isolated-reassessment` (필수)
- `task_snapshot`: 사용자 요구, 현재 scope, 수정/영향 경로, 불변조건, 상태 전이, 검증 계획과 실제 증거 (필수)
- `evaluation_mode`: 이전 라우팅이 없는 최초 평가는 `first-pass`, 무효화된 기존 라우팅의 lane/grade/score/rationale를 입력에서 격리하고 현재 미해결 작업을 처음부터 평가하는 모드`isolated-reassessment` (필수)
- `task_snapshot`: 사용자 요구, 현재 scope, 수정/영향 경로, 불변조건, 상태 전이, 검증 계획, 이미 존재하는 증거 또는 `none` (필수)
- `context_snapshot`: 함께 유지해야 하는 source/test/diff/log/contract 범위와 분할 가능성 (필수)
- `ownership_snapshot`: 공유 상태, 병행 작업, sibling task, 외부 책임 경계 (필수)
- `decision_snapshot`: 미해결 의미 판단, 사용자 권한이 필요한 결정, 외부 환경 의존성 (필수)
- `invalidation_evidence`: 검증 실패, 실제 로그, review finding, 변경된 범위 등 현재 판정을 바꾸는 원시 증거 (선택)
이전 `lane`, `grade`, 점수, 라우팅 사유, routed filename은 입력에서 제외한다.
이전 PLAN/CODE_REVIEW 문서의 코드 경로, 실제 로그, finding은 원본에서 재확인한 뒤 원시 증거로만 사용할 수 있다.
이전 PLAN/CODE_REVIEW 문서의 코드 경로, 기존 로그, finding은 경로와 revision 관련성을 정적으로 확인한 뒤 원시 증거로만 사용할 수 있다. 확인을 위해 검증 명령을 다시 실행하지 않는다.
## 먼저 확인할 것
@ -36,40 +38,48 @@ description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/
- [ ] 호출자가 plan 분석, scope, split, 검증 계획을 모두 확정했는가
- [ ] `targets`마다 필요한 구현 또는 리뷰 작업이 구분되어 있는가
- [ ] 이전 lane/G와 그 평가 문구가 입력에서 격리되었는가
- [ ] `isolated-reassessment`이면 이전 평가를 보지 않은 새 평가 context/sub-invocation에 중립 snapshot만 전달했는가
- [ ] 주장이나 요약이 아니라 현재 파일, diff, 명령 출력, 확정된 제약을 우선 증거로 사용했는가
- [ ] `isolated-reassessment`이면 이전 lane/grade/score/rationale/preferred route를 제외한 중립 snapshot만 평가 입력으로 사용했는가
- [ ] 현재 파일, diff, 확정된 제약, 이미 기록된 명령 출력을 우선 증거로 사용했는가
## 검증 책임
- Routing은 계획된 검증의 결정성과 관찰 가능성만 평가한다. 실행 전 출력 부재는 `unknown` 또는 `needs_evidence` 사유가 아니다.
- Plan과 routing은 구현 검증을 실행하지 않는다. 이 스킬은 canonical filename 계산 script만 실행한다.
- Build가 검증과 출력 기록을 맡고, review가 evidence를 확인하며 review scope에 필요한 명령을 재실행한다.
## 실행 절차
1. **평가 상태 초기화**
- 호출할 때마다 각 target을 `unrouted`로 시작한다.
- `isolated-reassessment`는 이전 평가가 없는 새 context/sub-invocation에서 실행하고, 현재 원시 증거로 재구성한 중립 snapshot만 노출한다.
- 호출자가 격리 실행을 제공할 수 없으면 독립 재평가를 완료했다고 주장하지 말고 `status: blocked`, `blocked_reason: isolated-routing-unavailable`을 반환한다.
- `isolated-reassessment`는 이전 lane/grade/score/rationale/preferred route를 입력에서 제외하고, 현재 미해결 Required/Suggested, 영향 경로, 검증, 소유권, 결정 상태로 재구성한 중립 snapshot만 평가한다.
- `isolated-reassessment`는 plan 역할 안의 라우팅 재평가다. 별도 routing model은 필요 없으며 plan/build/review의 서로 다른 모델 조건은 그대로 유지한다.
- 이전 lane/G를 승계하거나 하한으로 사용하지 않는다.
- 실패 횟수, Required 개수, 이전 G 등급만으로 cloud 또는 상위 G를 선택하지 않는다.
- 실패는 자동 승격 조건이 아니라 현재 증거에 추가되는 판정 무효화 사건으로만 취급한다.
- 새 결과가 확정되기 전에는 이전 평가와 비교하지 않는다. 필요하면 호출자가 routed 출력 이후에만 감사용 delta를 기록한다.
- 새 결과가 확정되기 전에는 이전 평가와 비교하지 않는다. 감사용 비교가 요청된 경우에만 호출자가 routed 출력 이후 delta를 기록한다.
2. **폐쇄성 평가**
- 각 target을 bounded local execution으로 완료·판정할 수 있는지를 기준으로 아래 값을 `true`, `false`, `unknown` 중 하나로 독립 판정하고 근거를 한 줄로 기록한다.
- `scope_closed`: 정확성 조건과 영향 경로가 확정된 범위 안에서 설명되는가
- `context_closed`: 중요한 증거를 생략하지 않고 필요한 컨텍스트를 함께 다룰 수 있는가
- 계획 분석 결과, 해당 target을 수행하는 동안 긴 컨텍스트를 유지해야 한다고 판단되면 `context_closed=false`로 판정한다.
- `verification_closed`: 결정적인 명령과 관찰로 성공 여부를 증명할 수 있는가
- `evidence_trusted`: 검증이 의도한 실제 경로를 실행하며 출력이 재현 가능하고 현재 상태와 일치하는가
- `verification_closed`: 계획된 명령과 관찰로 build/review가 성공 여부를 결정적으로 증명할 수 있는가
- `evidence_trusted`: 검증 경로와 evidence 출처가 구체적이고 재현 가능한가. 최초 plan에서는 실행 전 검증 설계의 신뢰성을 평가하며 PASS 출력은 요구하지 않는다.
- `ownership_closed`: 공유 상태, 병행 작업, 외부 소유권이 판단을 모호하게 만들지 않는가
- `decision_closed`: 사용자 권한이나 미해결 외부 의미 결정 없이 작업을 완료할 수 있는가
- active review follow-up에서는 유효한 Milestone-lock 결정만 `false`의 terminal gate가 될 수 있다. 환경, permission, secret, service, evidence 한계는 해결 완료 여부가 아니라 blocker 확인·해제 조건·재검증이 계획 가능한지를 평가한다.
- 동시성, dirty worktree, 외부 명령, 많은 finding은 그 자체로 lane을 결정하지 않는다. 위 폐쇄성에 미치는 영향만 평가한다.
3. **판정 가능성 확인**
- 하나라도 `unknown`이면 `status: needs_evidence`와 필요한 증거를 반환한다. lane, grade, filename은 반환하지 않는다.
- 하나 이상의 값이 `false`이고 cloud의 더 넓은 컨텍스트나 진단도 그 폐쇄 실패를 해소할 수 없으면 `status: blocked`, 폐쇄 실패별 `blocked_reason`, 해제 조건을 반환한다. 사용자 권한, secret, 접근 권한, 제품 결정은 대표적인 예일 뿐이며 이에 한정하지 않는다.
- 호출자는 `needs_evidence`를 cloud로 해석하지 말고 증거를 보강한 뒤 이 스킬을 처음부터 다시 실행한다.
- 하나라도 `unknown`이면 `status: needs_evidence`와 필요한 정적 planning evidence를 반환한다. 실행 전 PASS 출력 부재는 `unknown` 사유가 아니다. lane, grade, filename은 반환하지 않는다.
- first-pass에서 하나 이상의 값이 `false`이고 cloud의 더 넓은 컨텍스트나 진단도 그 폐쇄 실패를 해소할 수 없으면 `status: blocked`, 폐쇄 실패별 `blocked_reason`, 해제 조건을 반환한다. 이 상태는 routed pair가 생성되기 전의 loop-entry 거절이며, active loop의 terminal state가 아니다.
- active code-review의 `isolated-reassessment`에서는 유효한 Milestone-lock 결정이 이미 code-review의 `USER_REVIEW.md` gate로 분기되어야 한다. 그 외 환경, permission, secret, service, ownership, verification 제한은 blocker 증거·결정적 해제 조건·재검증을 포함하는 follow-up으로 평가하고 `blocked`를 반환하지 않는다.
- 호출자는 `needs_evidence`를 cloud로 해석하지 말고 정적 planning evidence를 보강한 뒤 이 스킬을 처음부터 다시 실행한다. routing을 위해 구현 검증을 실행하지 않는다.
4. **Lane 결정**
- 모든 폐쇄성이 `true`인 target만 `local`로 정한다.
- `unknown`이 없고 하나 이상의 폐쇄성이 `false`이며 cloud의 더 넓은 컨텍스트나 진단이 그 실패를 실제로 해소할 수 있을 때 `cloud`로 정한다.
- `false`를 cloud가 해소할 수 있는지 근거를 기록한다. 해소 가능성을 설명할 수 없으면 추측으로 cloud를 선택하지 않고 Step 3의 `blocked`를 반환한다.
- `false`를 cloud가 해소할 수 있는지 근거를 기록한다. 해소 가능성을 설명할 수 없는 first-pass target만 Step 3의 `blocked`를 반환한다. Active code-review의 `isolated-reassessment`에서는 `blocked`를 반환하지 말고, 유효한 Milestone-lock 결정은 code-review의 `USER_REVIEW.md` gate로 돌려보내며 그 외 제한은 blocker 증거·결정적 해제 조건·재검증을 수행하는 bounded follow-up scope로 재구성한 뒤 폐쇄성을 다시 평가한다.
- 실패 후에도 현재 폐쇄성이 모두 `true`이면 다시 `local`을 선택할 수 있다.
- lane은 capability fit이며 작업량이나 모델 사용량 균형을 위한 값이 아니다.
@ -98,16 +108,17 @@ description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/
- 모든 요청 target이 `routed`일 때만 filename을 반환한다.
- 결과 확정 뒤 scope, 검증, 증거, 소유권, 결정 조건이 달라지면 결과를 무효화하고 Step 1부터 다시 실행한다.
## 실행 결과 검증
## 라우팅 결과 확인
- [ ] 모든 요청 target에 여섯 폐쇄성 값과 현재 증거 근거가 있는가
- [ ] 재평가가 `isolated-reassessment`로 실행되었고 새 결과 전까지 이전 평가가 노출·비교되지 않았는가
- [ ] 재평가가 `isolated-reassessment`로 실행되었고 새 결과를 확정하기 전에 이전 lane/grade/score/rationale를 입력·하한·비교 기준으로 사용하지 않았는가
- [ ] `unknown` 또는 `blocked` 상태에서 lane/G/filename을 만들지 않았는가
- [ ] 이전 lane/G, 실패 횟수, finding 개수를 승계하거나 자동 승격 근거로 사용하지 않았는가
- [ ] lane을 먼저 정하고 G 등급을 별도 차원 점수로 산정했는가
- [ ] 각 target에 formatter script를 실행했고 grade와 filename을 stdout 그대로 사용했는가
- [ ] build/review filename이 target별 formatter 결과와 정확히 일치하는가
- 검증 실패 시: 결과를 `unrouted`로 폐기하고 누락된 현재 증거부터 보강한 뒤 전체 평가를 다시 수행한다.
- [ ] plan/build/review model identity 분리 조건을 runtime handoff에 남겼는가
- 확인 실패 시 결과를 `unrouted`로 폐기하고 누락된 정적 planning evidence부터 보강한 뒤 전체 평가를 다시 수행한다.
## 출력 형식
@ -172,10 +183,14 @@ blocked_reason: null
## 금지 사항
- 이전 lane/G를 기본값, 최소값, 비교 기준으로 사용하지 않는다.
- 기존 평가가 있는 재평가를 같은 평가 context에서 수행하지 않는다.
- `isolated-reassessment`에 별도 routing model을 요구하거나, 이를 근거로 한 모델이 plan/build/review 중 둘 이상을 맡게 하지 않는다.
- active review follow-up에서 `USER_REVIEW.md` gate가 아닌 blocker를 사용자 질문이나 `blocked` terminal로 바꾸지 않는다.
- 기존 평가가 있다는 이유로 같은 호출에서 재평가하는 것을 금지하지 않는다. 다만 이전 lane/grade/score/rationale/preferred route를 재평가 입력이나 하한으로 사용하지 않는다.
- local 실패를 이유로 cloud로 자동 승격하지 않는다.
- 높은 local G로 cloud에 필요한 컨텍스트나 판단을 보상하지 않는다.
- 파일 수, 동시성, dirty 상태, Required 개수 같은 단일 휴리스틱으로 lane을 정하지 않는다.
- grade나 filename을 formatter script 출력과 다르게 수작업으로 만들지 않는다.
- `needs_evidence``cloud`로 치환하거나 미완성 상태에서 routed filename을 만들지 않는다.
- 실행 전 PASS evidence를 요구하거나 routing 중 구현 검증 명령을 실행하지 않는다.
- PLAN, CODE_REVIEW, archive, complete.log 파일을 직접 생성·수정·이동하지 않는다.
- 이 routing 스킬은 다음 역할을 시작하지 않는다. 호출 runtime은 handoff 후 반드시 다른 model identity를 배정한다.

View file

@ -1,4 +1,4 @@
interface:
display_name: "Finalize Task Routing"
short_description: "Finalize task lane, grade, and filenames"
default_prompt: "Use $finalize-task-routing after task analysis to independently determine build/review lanes, grades, and canonical filenames."
default_prompt: "Use $finalize-task-routing to determine build/review capability routes while requiring distinct plan, build, and review model identities."

View file

@ -1,6 +1,6 @@
---
name: plan
description: Analyze the current repository and write a detailed PLAN-{build_lane}-GNN.md plus CODE_REVIEW-{review_lane}-GNN.md stub for implementation work. Use for every feature, refactor, bug fix, and code-review WARN/FAIL follow-up that enters the plan-code-review loop. Every initial or follow-up pair must run finalize-task-routing after analysis and before routed filenames are chosen. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap.
description: "Analyze the repository and write routed PLAN/CODE_REVIEW pairs for initial work or archived WARN/FAIL findings. The plan model only plans: it writes the pair, reports implementation-ready, and stops. Plan, implementation, and review must use different model identities."
---
# Plan
@ -10,35 +10,40 @@ description: Analyze the current repository and write a detailed PLAN-{build_lan
Create the planning artifacts for the implementation loop:
```text
plan skill -> analysis -> finalize-task-routing -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub
implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md, or blocked-state user-review request recorded in the review stub
code-review skill -> verdict + archive, complete.log and task-directory archive move, USER_REVIEW.md, or mandatory plan-skill follow-up
runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call
plan model -> implementation-ready -> implementation model -> review-ready -> review model
^ |
+--------------------------- plan-ready ----------------------------+
```
`code-review` may stop the automatic loop with `USER_REVIEW.md` only when a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation. Repeated non-PASS reviews, test environment blockers, external environment/secret/service setup, generic scope changes, and verification evidence gaps are not user-review reasons by themselves; they should become normal follow-up plans or unresolved verification evidence. Plan creation after `USER_REVIEW.md` requires the linked Milestone decision to be resolved. If the decision closes the task as complete/PASS, code-review resolves `USER_REVIEW.md`, writes `complete.log`, and archives the task instead of creating a new plan.
After writing the pair, report `implementation-ready` and stop.
The plan file and review stub must be self-sufficient for implementation agents that do not read this skill. If implementation discovers a selected Milestone `구현 잠금 > 결정 필요` item that blocks safe progress, the implementing agent records a `사용자 리뷰 요청` in the active `CODE_REVIEW-*-G??.md`, leaves active files in place, and reports ready for review. This stop path is file-based only during implementation: the implementing agent must not interrupt the loop by asking the user directly, presenting choices in chat, or calling a user-input tool such as `request_user_input`. The code-review skill validates that request and writes `USER_REVIEW.md` when the stop is justified. Use `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` as the shared section template.
Role completion means leaving the runnable PLAN/CODE_REVIEW pair; it does not include implementation.
`code-review` writes `USER_REVIEW.md` only when a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation. Other blockers become `plan-ready` findings.
Plan, implementation, and review use different model identities; separate agents using the same model do not satisfy this rule.
## Workflow Contract
This skill intentionally uses routed active files under an active task directory as the state protocol. Do not change this directory or filename contract unless the paired code-review skill is updated together.
Invocation modes:
Role boundary:
- `write` is the default for initial plans and explicit replans. After routing, this skill archives any prior active pair and writes the new pair.
- `prepare-follow-up` is used only when code-review has appended WARN/FAIL but has not archived the active pair. This skill completes analysis, final routing, and exact PLAN/review-stub rendering in memory without mutating repository files. It returns `prepared_plan`, `prepared_review`, their routed basenames, the current pair's predicted archive names/numbers, and the post-archive log counts used by the new pair.
- Both modes execute the same mandatory Step 3. `prepare-follow-up` is not a route-only shortcut.
- The plan model may inspect source/tests but must not edit them or run implementation verification.
- Write only PLAN/CODE_REVIEW files and required planning metadata.
- Do not implement, review, invoke `code-review`, or start another agent.
- Record the runtime-provided Plan model identity in both files. It is immutable for that pair; do not infer it from lane/G or agent name.
Task path terms:
- `{task_group}` is the top-level work category under `agent-task/`. Normal task groups use a short snake_case name such as `refactoring`.
- Milestone-linked work uses the reserved task group form `m-<milestone-slug>`, where `<milestone-slug>` is the active Milestone filename without `.md`.
- `{subtask_dir}` is used only for split work and follows the existing indexed directory naming rules below, such as `01_core` or `02+01_db`.
- `{subtask_dir}` is an indexed executable sibling inside grouped work and follows the naming rules below, such as `01_core` or `02+01_db`.
- `{subtask_name}` is the short snake_case name after the index or dependency prefix inside `{subtask_dir}`.
- `{task_name}` in headers and templates means the active task path relative to `agent-task/`: either `{task_group}` for a single-plan task or `{task_group}/{subtask_dir}` for a split subtask.
- `{task_name}` in headers and templates means the active task path relative to `agent-task/`: either `{task_group}` for a one-off task or `{task_group}/{subtask_dir}` for a grouped task.
- A single-plan task stores active files directly under `agent-task/{task_group}/`.
- Split work stores active files under `agent-task/{task_group}/{subtask_dir}/`; the parent `agent-task/{task_group}/` is only the grouping folder and must not contain active plan/review files.
- Grouped work stores one active pair under each `agent-task/{task_group}/{subtask_dir}/`; the parent `agent-task/{task_group}/` must not contain active plan/review files.
- Initial planning may create immediate sibling pairs. A `plan-ready` follow-up keeps the exact existing task path and writes one replacement pair.
Filename rules:
@ -48,30 +53,29 @@ Filename rules:
- `GNN` is a two-digit capability grade from `G01` to `G10`; the runtime maps lane+grade to current models externally.
- Lane, grade, and both canonical basenames come only from `agent-ops/skills/common/finalize-task-routing/SKILL.md`.
Role boundary rules:
Generated pair boundary:
- Implementing agents fill implementation-owned `CODE_REVIEW-*-G??.md` sections, keep active files in place, and report ready for review.
- If implementation cannot continue because a selected Milestone `구현 잠금 > 결정 필요` item is unresolved, implementing agents fill the review stub's `사용자 리뷰 요청` section with the exact linked decision, evidence, commands/output, and resume condition, then stop with active files in place.
- During implementation, do not ask the user directly, present multiple-choice prompts in chat, or call `request_user_input`/equivalent input tools. Milestone lock choices belong in the review stub's `사용자 리뷰 요청` section so code-review can validate and create `USER_REVIEW.md` only when justified.
- Required UI evidence capture that needs a user-owned device, emulator, permission, secret, or interactive access unavailable to the agent is a verification blocker, not a user-review reason by itself. Record attempted commands and blocker evidence in `검증 결과` or `계획 대비 변경 사항` so code-review can write a normal follow-up or unresolved verification report.
- Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, review-only checklist) is code-review-skill only.
- The implementation model edits source/tests and fills implementation-owned review sections, then reports `review-ready` and stops.
- The review model judges and archives the pair. On WARN/FAIL, orchestration dispatches a different plan model; no model performs another role itself.
Split decision policy:
Planning-time verification boundary:
- Default to multiple subtask directories under one task group. Before writing any plan, decide whether the work has smaller independently reviewable implementation units.
- If there is any natural dependency boundary, ownership boundary, subsystem boundary, API-vs-call-site phase, test strategy split, or independently reviewable risk, write multiple subtask directories under one task group.
- A single plan is an exception. Use one only when all of these are true: the work is one coherent implementation unit, it has one primary ownership boundary, it has no prerequisite subtask, splitting would create artificial coordination overhead, and the whole change remains easy to review at once.
- When uncertain, split. Do not choose a single plan merely because it is shorter to write.
- Record the split decision in the plan. For a single plan, explicitly state why each applicable split boundary does not require a separate task. For multi-plan output, list the shared `{task_group}`, each sibling `{subtask_dir}`, and its dependency relationship.
- This skill designs verification; build executes it and records actual output, and review validates the evidence and reruns commands required by its review scope.
- During planning, use repository files, manifests, scripts, workflows, rules, and already-recorded evidence only. Do not refresh existing evidence.
- Do not run compile, build, test, lint, source formatter, smoke/E2E, live/remote checks, package installation, dependency download, or cache warming while planning.
- Missing implementation-time output is not a planning evidence gap. Record the command, expected result, assumptions, and responsible build/review stage instead.
Split gates:
Shallow sibling extraction policy:
- Split when the work combines shared API/foundation changes with broad call-site rollout. Put the API/foundation in an earlier task and the rollout in dependent task(s).
- Split when the work touches multiple domains or ownership boundaries, unless the change is purely mechanical and trivially reviewable.
- Split when different parts can be verified with different focused tests or have different risk profiles.
- Split when a likely failure in one part would force rewriting unrelated parts of the plan.
- Split when one part can produce a useful `complete.log` before another part starts.
- Split when mobile/UI verification can hang on emulator/device state, modal, permission dialog, animation, or external runner; isolate evidence recovery from feature implementation.
- Treat a Milestone Epic or other broad request as a selection boundary. Select exactly one next executable Milestone Task or non-roadmap candidate; do not batch every Task in the Epic.
- Before loading implementation files in depth, use the selected Task, roadmap/SDD, repository structure, and targeted symbol/test inventory to make one shallow splitability check.
- If the selected Task has at least two clearly separable implementation or verification chunks and keeping them together would make local context unnecessarily broad, materialize the minimum complete set of immediate sibling tasks. Otherwise keep one task.
- Create one routed PLAN/CODE_REVIEW pair for every materialized sibling. Do not create empty directories, placeholder files, index-only reservations, decomposition caches, or manifests.
- Split only one level. Do not recursively subdivide siblings or expand into other Milestone Tasks. Reuse the shallow inventory and load only each sibling's required source/test regions.
- Account for the selected Task's required scope across the sibling set. Do not hide a known required chunk as deferred prose. Irreducible scope that has no coherent boundary remains one task and is handled by final cloud routing.
- Declare each sibling's intended write set and shared mutable state. Siblings may run in parallel only when their write sets are disjoint and they have no state, ordering, or contract-handoff dependency; read-only overlap is allowed.
- If write sets overlap or one sibling consumes another's state or contract, merge them or encode the producer as a `+` predecessor. Unknown overlap is not parallel-safe.
- Record the full immediate sibling set and real dependencies in every sibling plan. Approximate but bounded fan-out is preferred over exhaustive decomposition.
Task directory naming rules:
@ -79,34 +83,33 @@ Task directory naming rules:
- If the plan is based on a selected active Milestone, use `agent-task/m-<milestone-slug>/` as the task group. Do not include the Phase slug, Epic id, Task id, or a separate task slug in the task group.
- `m-<milestone-slug>` is a reserved top-level task group namespace for Milestone-linked work. Non-roadmap tasks must not use `m-`.
- Runtime completion-event routing for `m-*` reads only the top-level `{task_group}` name. It resolves `<milestone-slug>` by matching exactly one active file at `agent-roadmap/phase/*/milestones/<milestone-slug>.md`; archive paths are not target candidates.
- When split gates require decomposition, create one shared category folder and multiple subtask directories under it. Each subtask directory owns exactly one normal active plan file and one normal active review stub.
- Multi-plan output is a set of independent `PLAN-{build_lane}-GNN.md` + `CODE_REVIEW-{review_lane}-GNN.md` pairs across `agent-task/{task_group}/{subtask_dir}/` folders, not multiple plan files inside one folder.
- Multi-plan subtask directory names must start with a stable two-digit task index. The index must increase across sibling subtask directories for sorting, but it is not a serial execution dependency.
- New Milestone/Epic task extraction creates either one indexed `{subtask_dir}` or the immediate sibling set selected by the shallow split.
- Choose the next two-digit index after all active sibling indices and archived sibling directory basenames for the same task group. Read archive basenames only; do not read archived file contents. Allocate consecutive indices only to siblings that will receive routed pairs in this invocation.
- Each indexed directory owns exactly one normal active plan file and one normal active review stub. The index increases for sorting but is not a serial execution dependency.
- Use `NN_{subtask_name}` for a task with no runtime dependencies, e.g. `01_core`, `04_docs`, `05_ui`.
- Use `NN+PP[,QQ...]_{subtask_name}` for a task that depends on earlier task indices, e.g. `02+01_db`, `03+01,02_api`, `06+05_integration`.
- Valid independent pattern: `^[0-9]{2}_[a-z0-9_]+$`.
- Valid dependent pattern: `^[0-9]{2}\+[0-9]{2}(,[0-9]{2})*_[a-z0-9_]+$`.
- `NN`, `PP`, and `QQ` are two-digit indices. Every predecessor index after `+` must be lower than `NN` and must refer to a sibling multi-plan subtask directory under the same `{task_group}`.
- `NN`, `PP`, and `QQ` are two-digit indices. Every predecessor index after `+` must be lower than `NN` and must refer to a sibling indexed task directory under the same `{task_group}`.
- The first `_` after the index or dependency list starts `{subtask_name}`. `{subtask_name}` stays short snake_case and may contain additional underscores.
- Runtime scheduling reads only the `{subtask_dir}` name: `_` means `depends_on=[]`; `+` means `depends_on` is the comma-separated index list between `+` and the first `_`.
- Scheduling contract: a runtime that consumes task directories reads only `{subtask_dir}`; `_` means `depends_on=[]`, and `+` means `depends_on` is the comma-separated index list between `+` and the first `_`. This skill records dependencies but does not start or schedule workers.
- An independent `NN_...` name asserts that its write set and shared mutable state do not conflict with concurrently runnable siblings. Any write/state/ordering/contract conflict must appear as `NN+PP[,QQ...]_...` or be merged into one sibling.
- Subtask directory names are the source of truth for runtime dependencies. Do not hide extra dependencies only in the plan body, and do not create a bare `NN+{subtask_name}` without predecessor indices.
- A predecessor index is satisfied by a `complete.log` for the matching predecessor subtask under the same `{task_group}`. Check active siblings first, then matching archived subtasks across all archive month folders. This is a narrow exception to the normal archive skip rule: read only candidate predecessor `complete.log` files needed to prove split dependency completion.
- For predecessor index `PP`, the only valid active lookup candidates are `agent-task/{task_group}/PP_*/complete.log` and `agent-task/{task_group}/PP+*/complete.log`.
- For predecessor index `PP`, the only valid archive lookup candidates are `agent-task/archive/*/*/{task_group}/PP_*/complete.log` and `agent-task/archive/*/*/{task_group}/PP+*/complete.log`.
- Archive lookup matches the predecessor index at the start of the archived subtask directory name, such as `01_...` or `01+...`, under the same `{task_group}`. If multiple candidates match one predecessor index, do not choose by guess; record the ambiguity and require a concrete task path or runtime selection.
- Do not treat an archived predecessor as the active task to edit. Archive lookup is only for dependency satisfaction before writing or implementing a dependent split plan.
- Example: split a refactoring common core plus two app integrations under `agent-task/refactoring/` as `01_core`, `02+01_edge_integration`, `03+01_node_integration`. Both integrations depend only on `01_core` and may run in parallel after `01_core` has `complete.log`.
- Example: split three sequential tasks under one task group as `01_schema`, `02+01_migration`, `03+02_api`.
- Example: split independent docs/UI plus an integration under one task group as `01_core`, `02+01_db`, `03+02_api`, `04_docs`, `05_ui`, `06+05_integration`; `01_core`, `04_docs`, and `05_ui` can start together, and `06+05_integration` waits only for `05_ui`.
- `01_core`, `02+01_edge_integration`, and `03+01_node_integration` express two integrations that may run in parallel after `01_core` completes. A shallow split may create all three routed sibling pairs in one invocation.
- Preserve task group and subtask directory names verbatim; do not normalize, reinterpret, or choose execution order by agent judgment.
Final routing boundary:
- Do not estimate, inherit, or write lane/G while analyzing. Keep the task `unrouted` until all plan scope, split, verification, evidence, ownership, and decision facts are complete.
- Do not estimate, inherit, or write lane/G while analyzing. Keep the task `unrouted` until plan scope, split, verification design, ownership, decision facts, and available existing evidence are complete.
- Execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` for both `build` and `review` after analysis. Its routed outputs are the only source for active PLAN/CODE_REVIEW filenames.
- Apply this boundary to first-pass plans, review WARN/FAIL follow-ups, USER_REVIEW replans, and each split subtask independently.
- A previous loop's lane, grade, score, rationale, and filename are quarantined. Prior code paths, actual command output, and review findings may be carried only as revalidated raw evidence.
- `needs_evidence` requires evidence collection and a fresh full routing run. `blocked` stops plan-file creation. Neither state may produce active routed filenames.
- Apply this boundary independently to every first-pass sibling and to each review WARN/FAIL or USER_REVIEW replan.
- A previous loop's lane, grade, score, rationale, and filename are quarantined. Prior code paths, recorded command output, and review findings may be carried as raw evidence after confirming their path and revision relevance without rerunning commands.
- `needs_evidence` requires missing static planning facts and a fresh full routing run. It must not trigger implementation verification. A first-pass `blocked` may prevent loop entry; once a selected review loop is active, a valid Milestone-lock decision routes to `USER_REVIEW.md`, while every other limitation becomes a routed follow-up with its blocker evidence and deterministic release condition.
- If plan facts change after routing, invalidate both target results and run final routing again before writing files.
- Treat non-behavioral review artifact drift and obvious non-behavioral source nits as current-scope evidence; they do not bypass final routing.
@ -115,24 +118,35 @@ Directory states:
| State | Meaning |
|-------|---------|
| `PLAN-*-G??.md` only | Invalid; plan skill always writes both active files |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub | Implementation is pending/in progress |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation claims a selected Milestone lock decision blocker; ready for code-review to validate and create `USER_REVIEW.md` only if justified |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` without verdict | Ready for code-review skill |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Review finalization is pending. Continue only when code-review invokes `prepare-follow-up`; `write` mode must not overwrite this state. |
| `STAGED_BATCH.md` | Multi-sibling write transaction; finish every listed sibling before reporting |
| `STAGED_PLAN.md` only | Pair write interrupted; render the matching staged review from this fixed plan without rerouting |
| `STAGED_PLAN.md` + `STAGED_CODE_REVIEW.md` | Pair is fully staged; verify and promote both without rerouting |
| unstarted active pair + staged replacement | Explicit replan transaction; archive only the old pair, then promote the staged pair |
| one old active member + its archived counterpart + staged replacement | Interrupted replan archive; finish the old archive, then promote the staged pair |
| routed PLAN plus matching `STAGED_CODE_REVIEW.md` | Partial promotion; promote the staged review and do not rewrite the PLAN |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub | `implementation-ready`; a different implementation model consumes the pair |
| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | `review-ready`; a different review model consumes the pair |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with appended verdict | Review finalization pending; the plan model must not modify it |
| `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; linked Milestone lock decision must be resolved before creating another plan |
| `USER_REVIEW.md` + `*.log` files | Linked Milestone decision is required before planning |
| `NEXT_STATE.md` with `target: plan`, archived pair, and no active pair | Review-dispatched `plan-ready`; write one follow-up pair and leave the pending file for review finalization |
| `NEXT_STATE.md` with another target | Review finalization pending; the plan model must not modify it |
| `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS or user-review-resolved PASS); not active |
| Only `*.log` files (no `complete.log`) | Inspect the newest review log. A verdict with no required next state is post-archive finalization pending; otherwise the task is terminated mid-loop or abandoned. |
| Matching archived plan/review logs with WARN/FAIL | `plan-ready`; create one follow-up pair from those exact logs |
## Step 1 - Determine Task
If the user names the task explicitly, use that task group or task path.
If the user names an exact existing task path for continuation or replan, use it. Do not treat a Milestone/Epic id or title as an exact task path.
Any plan-creation request scoped to a Milestone, Epic, or other broad roadmap item enters new-task extraction mode unless it selects an existing indexed task. Select one Milestone Task inside the requested Epic before applying sibling extraction.
Otherwise, find active plan files with both globs, excluding `agent-task/archive/**`:
- `agent-task/*/PLAN-*-G??.md`
- `agent-task/*/*/PLAN-*-G??.md`
Find `agent-task/*/STAGED_BATCH.md`, then `STAGED_PLAN.md` and `STAGED_CODE_REVIEW.md` with the task-depth globs before classifying active plans or selecting a new task. A staged state wins selection and resumes every listed sibling at Steps 5-6 with the recorded Plan model identity, without rerouting or a new task path. Do not apply active-pair stop rules until that transaction finishes.
Also note active user-review stops, excluding `agent-task/archive/**`:
- `agent-task/*/USER_REVIEW.md`
@ -140,17 +154,21 @@ Also note active user-review stops, excluding `agent-task/archive/**`:
| Result | Action |
|--------|--------|
| Exactly one | Continue that task |
| Exactly one | Select it, then apply the active-state guards below |
| None | Create a new task only for a feature/refactor/fix/follow-up that belongs in this workflow |
| Multiple | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active plan, use it. Otherwise list paths and stop with an ambiguity report; do not choose by agent judgment and do not create a user-review request for routing ambiguity. |
The routed plan file is the loop entry point. A missing active plan normally means only that no plan has been started for a new task; do not create task files for casual analysis, status, or review requests unless the user explicitly asks for a plan.
For an exact task path with no active pair, accept follow-up planning only when the newest matching archived review log is WARN/FAIL and its plan log is identifiable. Treat that pair as `plan-ready` evidence.
If no active plan exists but one or more `USER_REVIEW.md` files exist, report that the linked Milestone decision is required and list the paths unless one path is explicitly selected for resolution or replanning. If a selected active task directory contains `USER_REVIEW.md`, read it before planning. Do not write a new follow-up plan unless the linked Milestone decision has been resolved or the new plan explicitly replans around that recorded decision. When planning resumes from `USER_REVIEW.md`, archive it to `user_review_N.log` in the same task directory before writing the new active plan/review pair, and record the resolved decision in the new plan `배경` or `분석 결과`.
When review dispatch includes `NEXT_STATE.md` with `target: plan`, require its `task` and old `plan` to match the archived reviewed pair; the follow-up uses the next monotonic plan number. Refuse the handoff if the current Plan model identity is forbidden. Write the pair but do not edit `NEXT_STATE.md`; review owns final verification.
If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state and do not overwrite either state until a later explicit command selects either user-review resolution or the active plan/review path.
If `USER_REVIEW.md` exists, do not plan until a review model resolves and archives it.
If the selected review already has an appended verdict, accept it only in `prepare-follow-up` mode invoked by code-review. In every other mode, leave the pair unchanged and report that code-review finalization must resume.
If a selected task directory contains both `USER_REVIEW.md` and an active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, do not overwrite either state or ask the user to choose between files. Treat a valid unresolved `USER_REVIEW.md` as the terminal state; otherwise return the exact paths and provenance to code-review finalization/recovery so it can continue from evidence rather than waiting for another instruction.
If an active review already has a verdict, leave it unchanged and report that review finalization is required.
If the selected active pair is an unfilled stub, report `implementation-ready` and stop. Replan it only when the user explicitly requests replan before implementation starts. If its implementation-owned sections are filled and it has no verdict, report `review-ready` and stop.
로드맵 확인:
@ -174,60 +192,51 @@ If the selected review already has an appended verdict, accept it only in `prepa
- 제품 선택, 우선순위 결정처럼 에이전트가 확정할 수 없는 항목은 구현 계획의 실행 checklist로 쓰지 않는다. 그런 항목이 남아 있으면 plan 생성을 멈추고 `구현 잠금 > 결정 필요`로 분리한다.
- 기능 Task에 `검증:`이 있으면 구현 계획의 같은 plan item 안에 해당 검증을 포함한다. 검증이 명시되지 않은 기능 Task에는 억지 검증 항목을 만들지 말고, 필요한 일반 빌드/회귀 확인만 최종 검증에 둔다.
- 선택한 활성 Milestone 범위에 속하는 구현 계획이면 `{task_group}``m-<milestone-slug>`로 정한다. `<milestone-slug>`는 선택한 Milestone 경로의 파일명에서 `.md`를 제거한 값이다.
- 같은 Milestone에서 split work가 필요하면 기존 split 규칙 그대로 `agent-task/m-<milestone-slug>/<subtask_dir>/` 아래에 계획 파일을 만든다.
- Milestone 기능 Task 완료를 목표로 하는 계획이면 `Roadmap Targets` 섹션에 활성 Milestone 경로와 완료 대상 Task id를 고정한다. 이 섹션은 `complete.log``Roadmap Completion` 근거로 복사되어 `update-roadmap`이 해당 Task만 체크하는 anchor가 된다. 이 섹션은 `{task_group}`이 해당 Milestone slug의 `m-<milestone-slug>`일 때만 쓴다.
- Milestone 작업이 아니거나, Milestone 안의 조사/하위 구현처럼 특정 기능 Task 완료를 주장하지 않는 계획이`Roadmap Targets` 섹션을 쓰지 않는다. 섹션이 없으면 PASS 후에도 roadmap Task 체크를 하지 않는다.
- Milestone 또는 Epic 범위의 plan 생성은 먼저 Milestone Task 하나를 선택하고, 그 Task가 크면 immediate sibling pair들을 `agent-task/m-<milestone-slug>/<subtask_dir>/` 아래에 함께 만든다. Epic은 선택 범위일 뿐 완료 대상으로 쓰지 않는다.
- Milestone 기능 Task 완료를 목표로 하는 계획이면 `Roadmap Targets` 섹션에 활성 Milestone 경로와 완료 대상 Task id를 고정한다. Sibling split에서는 모든 필수 sibling을 선행 조건으로 가진 closure sibling 하나에만 이 섹션을 둔다. 자연스러운 마지막 sibling이 없으면 작은 integration/verification closure sibling을 만든다. 이 섹션은 `complete.log``Roadmap Completion` 근거로 복사되어 `update-roadmap`이 해당 Task만 체크하는 anchor가 된다. `{task_group}`이 해당 Milestone slug의 `m-<milestone-slug>`일 때만 쓴다.
- Milestone 작업이 아니거나, Milestone 안의 조사/부분 구현처럼 이번 작업만으로 특정 기능 Task 완료를 주장할 수 없으`Roadmap Targets` 섹션을 쓰지 않는다. 해당 기능 Task의 남은 acceptance를 실제로 닫는 마지막 작업에만 넣는다. 섹션이 없으면 PASS 후에도 roadmap Task 체크를 하지 않는다.
- `agent-roadmap/` 디렉터리가 없으면 기존 task routing 규칙대로 진행한다.
Use short snake_case task group names for non-roadmap work, e.g. `api_refactor`.
Before choosing plan files or task directory names, apply the split decision policy above. When the policy allows a single plan, write active files directly under `agent-task/{task_group}/` and record the exception rationale. When the policy requires multiple plans, choose one shared `{task_group}` and `{subtask_dir}` names using the task directory naming rules above. Do not put multiple active plan files in one active task directory, and do not mix split subtask directories with active plan/review files directly in the parent task group.
Before choosing plan files or task directory names, apply the shallow sibling extraction policy once. Choose one task directory or a complete immediate sibling set. Do not put multiple active plan files in one task directory or mix indexed task directories with active plan/review files directly in the parent task group.
## Step 2 - Analyze Before Writing
Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed file edits before writing plan/review files are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits when the repository already uses agent-test for the relevant scope or the user explicitly asked to maintain test rules.
Complete these four items before creating active plan/review files. The only allowed pre-plan edits are local `agent-roadmap/current.md` creation or `.gitignore` repair needed for routing. Report test-rule gaps separately; do not create or update test rules while planning.
- [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Agent-test is optional: some repositories or tasks intentionally do not have or use `agent-test/`. Check `agent-test/<test_env>/rules.md`; read it in full when present, even if it appears blank or skeleton. If it is absent, record that no agent-test rule was applied and choose fallback verification sources from repository manifests, scripts, workflows, domain rules, or direct read-only environment probes. Do not create agent-test files merely because a plan has verification. Invoke `create-test` only when the user asked for test-rule creation/maintenance, the current task is itself test-rule work, or the repository already uses agent-test for this scope and the missing/blank rule is a real maintenance gap. If creation is not appropriate or possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself.
- [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads.
- [ ] **Resolve test profiles** — if env rules exist and contain `## 라우팅`, read every matching `agent-test/<test_env>/<test-profile>.md` in full. If agent-test is absent or intentionally unused for the task, skip profile resolution and record the fallback verification source. Use `create-test` for missing or structurally blank routes/profiles only when the repository already uses agent-test for this scope or the task is test-rule maintenance. Use `update-test` only when verified command or criteria facts are available or the user asked to maintain test rules. If a profile exists but leaves command/criteria values as `<확인 필요>`, record the incomplete values and choose fallback verification commands from repository manifests or workflows with lower confidence. Do not claim agent-test requires a command that is not written in the env rules or matched profiles.
- [ ] **Preflight non-local test environments** — when any required verification leaves the current checkout, including remote runner, field/bootstrap, external provider, Docker/code-server, emulator/device, or shared long-running runtime, derive a read-only preflight before writing final verification commands. Use matched `agent-test` rules when they exist and apply; otherwise derive the preflight from repository manifests, scripts, workflows, domain rules, current task evidence, user-provided environment facts, and direct read-only probes. Record runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, command help/version output needed by the verification, config path, runtime identity such as Edge id, ports/process state, external hosts, and OS/arch assumptions. If the preflight shows stale artifacts, dirty/divergent checkout, wrong identity, missing command, closed ports, host OS mismatch, or unsynced source, the plan must add an explicit setup/sync/rebuild step or report the blocker; do not write verification commands that silently assume profile or fallback values are already true.
- [ ] **Read all test files in full** — read every test file that exercises the changed behavior, including files implied by matched agent-test profiles when any are used and by the repository test layout.
- [ ] **Assess test coverage** — for each behavior change, explicitly record whether existing tests cover it.
- [ ] **Assess split boundaries first** — identify dependency boundaries, ownership boundaries, API-vs-call-site phases, test strategy splits, risk profile splits, and independently verifiable subwork before selecting plan files. If any split gate applies or the decision is uncertain, write multiple subtask directories under one task group instead of one plan.
- [ ] **Resolve split predecessor completion** — if the selected or proposed subtask directory has `NN+PP[,QQ...]_...`, resolve each predecessor index under the same task group. Check only the active and archive candidate patterns defined in the task directory naming rules. Record found active/archive paths, missing predecessors, or ambiguous matches in `분석 결과 > 분할 판단` and, when order matters, `의존 관계 및 구현 순서`.
- [ ] **Grep all symbol references** — for any renamed or removed symbol, find every call site and import chain.
- [ ] **Check dependency manifests** — before adding any new package, verify its presence in go.mod / package manifest.
- [ ] **Pre-check compile issues** — identify missing interface implementations, type mismatches, and broken imports.
- [ ] **Verify verification commands** — confirm that the final verification commands actually run in this repository layout.
- [ ] **Stabilize fragile verification** — for search or generated-output checks, choose deterministic commands up front, such as `rg --sort path`, and decide whether cached test output is acceptable or `-count=1` is required.
- [ ] **Fix scope and split once** — select one executable candidate from the request and required roadmap/SDD context. Keep it whole or freeze one immediate sibling set; do not recurse.
- [ ] **Fix directories and dependencies** — allocate indices, encode real predecessors, and confirm concurrent siblings have disjoint writes and no shared state or ordering conflict. Resolve only the predecessor `complete.log` paths required by dependent siblings.
- [ ] **Inspect the implementation surface** — read targeted source/test regions, affected contracts, renamed or removed symbol references, and relevant manifests. Identify obvious dependency, import, type, or implementation risks statically; do not load unrelated files or compile.
- [ ] **Write the verification contract** — use the user-selected `test_env` or `local` by default. Read applicable rules/profiles or a static fallback, then record test additions or gaps, exact commands, workdir, expected results, cache policy when stale results could hide failure, and any non-local preflight assumptions. Do not execute commands, probe environments, or mutate test rules.
## Step 3 - Finalize Task Routing
This step is mandatory and must be the last semantic decision before routed filenames are fixed. Complete Step 2 and prepare the full plan structure in memory before starting it.
- [ ] **Build neutral input**prepare current scope, affected paths, invariants, context size, split result, verification plan, actual evidence, ownership, unresolved decisions, and failure evidence for `build` and `review`. Exclude every previous lane, grade, routing score, rationale, filename, and archive basename that exposes them.
- [ ] **Select evaluation mode** — use `first-pass` only when no prior routing exists. Review follow-ups, invalidated routes, and USER_REVIEW replans use `isolated-reassessment` and must pass the neutral input to a fresh evaluation context/sub-invocation that has not seen the previous assessment.
- [ ] **Run the routing skill** — read and fully execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` with both targets in the selected mode. Do not reproduce or replace its decision logic inside this skill. If isolated evaluation is unavailable, treat the routing result as `blocked`; do not silently evaluate in the current anchored context.
- [ ] **Resolve non-final states** — for `needs_evidence`, collect the named evidence and rerun from `unrouted`; for `blocked`, stop without mutating task files and report the exact release condition. In `prepare-follow-up`, leave the verdict-appended active pair in place so code-review recovery can resume without losing the loop state.
- [ ] **Accept only routed output** — require independent `build` and `review` closure records, lane, grade scores, GNN, and canonical filename.
- [ ] **Freeze the result** — use those exact basenames in Steps 4-6. If any routing input changes before the files are written, discard both outputs and repeat this step from the beginning.
- [ ] **Build neutral input** — for each sibling, prepare its scope, affected paths, invariants, context size, sibling-set position, verification plan, available existing evidence, ownership, unresolved decisions, and existing failure evidence for `build` and `review`. Exclude every previous lane, grade, routing score, rationale, filename, and archive basename that exposes them.
- [ ] **Select evaluation mode** — use `first-pass` for new work and `isolated-reassessment` for `plan-ready` findings. Exclude the previous lane, grade, score, rationale, and preferred route.
- [ ] **Run the routing skill** — read and fully execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` with both targets independently for each sibling. Do not reproduce or replace its decision logic inside this skill. Do not return `blocked` merely because a separate evaluation context or explicit follow-up instruction is unavailable.
- [ ] **Resolve non-final states** — for `needs_evidence`, collect only static planning facts and rerun. Never execute implementation verification.
- [ ] **Accept only a fully routed set** — require independent `build` and `review` closure records, lane, grade scores, GNN, and canonical filename for every sibling. If any new sibling is not routed, write none of the new sibling batch.
- [ ] **Freeze the result** — use each sibling's exact basenames in Steps 4-6. If any routing input or sibling boundary changes before files are written, discard the affected set and repeat this step.
## Step 4 - Archive Existing Active Files
## Step 4 - Prepare Task Files
In `write` mode, complete this step before writing new active files. In `prepare-follow-up` mode, calculate the same counts and archive names but do not modify any repository file; code-review owns the later archive.
Apply this step independently to every routed sibling directory. Do not archive or overwrite unrelated active siblings.
- Validate that the task directory contains at most one active `PLAN-(local|cloud)-G(0[1-9]|10).md`, at most one active `CODE_REVIEW-(local|cloud)-G(0[1-9]|10).md`, and at most one `USER_REVIEW.md`. Reject ambiguous or malformed active names.
- In `write` mode, ensure `.gitignore` has the Agent-Ops managed gitignore block before renaming any active file to `*.log` or creating local `agent-roadmap/current.md`. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, and `agent-roadmap/current.md`. In `prepare-follow-up` mode, only inspect the block and return `gitignore_repair_needed: true|false`; code-review performs any repair after preparation.
- Count existing `plan_*.log` as `current_plan_archive_number`. If an active plan exists, parse `current_build_lane` and `current_build_grade` from that active filename and set `current_plan_archive_name=plan_{current_build_lane}_{current_build_grade}_{current_plan_archive_number}.log`. Require that destination not to exist. In `write` mode rename that exact active file to the calculated name; in `prepare-follow-up` only return the name and number. Never use the newly routed build lane/grade to archive the old active plan.
- Count existing `code_review_*.log` as `current_review_archive_number`. If an active review exists, parse `current_review_lane` and `current_review_grade` from that active filename and set `current_review_archive_name=code_review_{current_review_lane}_{current_review_grade}_{current_review_archive_number}.log`. Require that destination not to exist. In `write` mode rename that exact active file to the calculated name; in `prepare-follow-up` only return the name and number. Never use the newly routed review lane/grade to archive the old active review.
- Count existing `user_review_*.log` as `current_user_review_archive_number`. If `USER_REVIEW.md` exists and the linked Milestone decision is resolved for replanning, set `current_user_review_archive_name=user_review_{current_user_review_archive_number}.log`; require that destination not to exist and rename it only in `write` mode.
- Compute `post_archive_plan_log_count`, `post_archive_review_log_count`, and `post_archive_user_review_log_count` from the filesystem after actual archive in `write` mode, or from the predicted addition of each current active file in `prepare-follow-up` mode.
- Validate that the task directory contains at most one active routed pair, at most one staged pair, and at most one `USER_REVIEW.md`. Reject ambiguous, malformed, or identity-mismatched files.
- For multi-sibling work, require at most one `STAGED_BATCH.md` in the task-group parent.
- Ensure `.gitignore` exposes task Markdown and log files.
- Do not archive review artifacts. A `plan-ready` pair is already archived by the review model.
- For an explicit replan with an unstarted active pair, calculate its archive destinations but defer renames until the replacement pair is fully staged.
- Use monotonic suffixes for the new pair's future archive names.
Set `plan_number=post_archive_plan_log_count`. The new pair's future archive suffixes are `plan_log_number=post_archive_plan_log_count` and `review_log_number=post_archive_review_log_count`. These are intentionally different concepts from `current_plan_archive_number` and `current_review_archive_number`.
Set each `next_log_suffix` to `0` when no matching log exists, otherwise `max(existing numeric suffix) + 1`. A normal new pair uses those suffixes. An explicit replacement archives the old pair at those suffixes and uses suffix plus one for the staged pair. Set `plan_number=plan_log_number`.
## Step 5 - Write Plan File
## Step 5 - Render Plan File
Render the complete plan in memory first. In `write` mode, write it to the routed plan basename. In `prepare-follow-up` mode, return the exact rendered body as `prepared_plan` and do not write it.
Render each complete plan in memory. Do not write the routed PLAN basename yet.
Header line must be exactly:
@ -238,11 +247,12 @@ Header line must be exactly:
Required sections:
- Title.
- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only. Also state that if implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, the implementer must fill the review stub's `사용자 리뷰 요청` section with exact linked evidence and stop for code-review; the implementer must not ask the user directly, present chat choices, call `request_user_input`, create `USER_REVIEW.md`, archive logs, or write `complete.log`. State that environment/secret/service blockers, generic scope changes, and evidence gaps a follow-up agent can close are not user-review requests by themselves.
- `이 파일을 읽는 구현 에이전트에게`: state that the implementation model differs from the plan/review models, fills implementation-owned sections, reports `review-ready`, and stops without reviewing or starting another agent.
- `역할 모델`: record the immutable runtime-provided Plan identity and point to the review stub as the mutable ledger for Implementation/Review identities.
- `배경`: 2-4 sentences explaining why the work is needed.
- `사용자 리뷰 요청 흐름`: state that only selected Milestone lock decisions are recorded in the active review stub's `사용자 리뷰 요청` section, copied from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; direct user prompts during implementation are forbidden, and code-review owns validation plus the actual `USER_REVIEW.md` file write.
- `Archive Evidence Snapshot`: include this section only when the plan resumes from `USER_REVIEW.md`, a prior archived review, or any archive evidence. Omit it for first-pass plans with no archive evidence. The section must contain only the archive facts needed to implement without rereading archive by default: prior task/archive paths, verdict, Required/Suggested/Nit summary, affected files, verification evidence, and any roadmap carryover. If exact prior context is still required, cite the specific archive file paths allowed to read; do not ask the implementer to search `agent-task/archive/**` broadly.
- `Roadmap Targets`: include this section only when the plan is intended to complete one or more existing Milestone 기능 Task ids. Omit the section entirely for non-roadmap work or Milestone-adjacent work that should not check a Task on PASS. Format exactly:
- `Roadmap Targets`: include this section only when the plan is intended to complete one or more existing Milestone 기능 Task ids. In a sibling set, include it only in the closure sibling whose directory dependencies cover every required predecessor. Omit the section entirely for non-roadmap work or partial siblings that should not check a Task on PASS. Format exactly:
```markdown
## Roadmap Targets
@ -271,30 +281,30 @@ Required sections:
- `agent-ui/definition/views/<view-id>/index.md`: `계획` -> `구현됨`
```
- `분석 결과`: record the findings from Step 2 and the final routed output from Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections:
- `읽은 파일`: list every source and test file read during analysis, with path. List agent-test rule/profile files only when they were actually present and read.
- `읽은 파일`: list every source and test file read during analysis, with path. Mark large files read by targeted symbol/range instead of implying a whole-file read. List agent-test rule/profile files only when they were actually present and read.
- `SDD 기준`: for `SDD: 필요` Milestones, list the SDD path, status, targeted Acceptance Scenario ids, their Milestone Task ids, and the Evidence Map rows that drive the plan. State explicitly how those rows shaped the implementation checklist and final verification. If the selected Milestone has `SDD: 불필요`, state the recorded reason. If the work is not Milestone-linked, state "not applicable".
- `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test/<test_env>/rules.md` was present/read/missing/intentionally unused, every matched profile path read when any, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If any required verification leaves the current checkout, include a `테스트 환경 프리플라이트` record with runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, required command help/version output, config path, runtime identity such as Edge id, ports/process state, external hosts, OS/arch assumptions, and the exact setup/sync/rebuild step or blocker derived from mismatches. If agent-test is absent or unusable, explicitly say no agent-test rule was applied, what fallback is used, and whether test-rule maintenance is actually needed or not needed for this task.
- `테스트 환경 규칙`: state the chosen `test_env`, rules/profile paths actually read, commands selected, incomplete values, and static fallback source. For verification outside the checkout, record the planned build/review preflight commands and assumptions without claiming current runner, process, port, sync, or artifact state.
- `테스트 커버리지 공백`: list each behavior change and whether existing tests cover it; explicitly note gaps.
- `심볼 참조`: list renamed/removed symbols and every call site found, or state "none" if no symbols were changed.
- `분할 판단`: state that the split decision policy was evaluated before choosing plan files. For a single plan, explain why each relevant split gate does not apply and why single-plan coordination is safer than splitting. For multi-plan output, list the shared task group plus each sibling subtask directory and dependency relationship. For dependent subtask plans, include each predecessor index and whether it is satisfied by an active or archived `complete.log`, missing, or ambiguous.
- `분할 판단`: record the selected candidate, whether it stayed single or split, the complete immediate sibling directory set, each scope, write set, shared mutable state, collision result, and dependencies. State why no further split is needed. For a dependent sibling, include each predecessor index and whether it is newly materialized, satisfied by active/archive `complete.log`, missing, or ambiguous.
- `범위 결정 근거`: state which files or areas were explicitly excluded from this change and why. This is the boundary justification — the implementing agent must not silently expand scope beyond what is recorded here.
- `최종 라우팅`: record the `evaluation_mode` plus `build` and `review` closure results, grade scores, lane, GNN, and canonical filename returned by `finalize-task-routing`. Do not include or compare a previous loop's lane/G.
- `구현 체크리스트`: a top-level checklist the implementing agent must follow while coding. Include one item per implementation/verification unit; if the roadmap feature Task has `검증:`, keep that verification in the same checklist item instead of making a separate completion-criteria item. Include one item for whole-plan intermediate/final verification only when it is not already covered by the feature items, and make the final item exactly: `- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.` Copy this checklist into the review stub's `구현 체크리스트` section with the same item text and order.
- `구현 체크리스트`: a top-level checklist the implementing agent must follow while coding. Include one item per implementation/verification unit; if the roadmap feature Task has `검증:`, keep that verification in the same checklist item. Make the final item exactly: `- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 채우고 review-ready를 보고한 뒤 현재 실행을 종료한다. code-review를 실행하거나 다음 에이전트를 시작하지 않는다.` Copy it into the review stub unchanged.
- One item per change: `### [TAG-1] Title`, `TAG-2`, etc.
- `수정 파일 요약`: table mapping files to item ids.
- `최종 검증`: runnable commands and expected outcome. Prefer commands from the matched agent-test env/profile rules. If agent-test is missing, blank, skeleton, or lacks a matching command, use repository manifests/workflows as fallback and record that fallback in `분석 결과 > 테스트 환경 규칙`. Commands must be exact and deterministic enough for the reviewer to rerun; use stable ordering for searches and state whether cached test output is acceptable. The final line of this section must read exactly — **"모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."**
- `최종 검증`: runnable commands and expected outcome. Prefer commands from the matched agent-test env/profile rules. The final line must read exactly — **"검증 결과를 review stub에 기록하고 review-ready를 보고한 뒤 현재 실행을 종료한다. code-review를 실행하거나 다음 에이전트를 시작하지 않는다."**
Each plan item must include:
Each plan item must include the applicable fields below:
- `문제`: concrete problem with file:line references.
- `해결 방법`: exact approach and before/after code block for non-trivial changes.
- `수정 파일 및 체크리스트`: exhaustive file-level checklist.
- `테스트 작성`: explicit write/skip decision. If writing tests, include path, test name, assertion goal, and fixtures. If skipping, justify.
- `중간 검증`: runnable commands and expected result.
- `중간 검증` (optional): include it only when a later plan item depends on that result; otherwise rely on final verification.
Include `의존 관계 및 구현 순서` only when order matters.
For split multi-plan work, the `{subtask_dir}` directory name is the runtime source of truth. If a plan has a `NN+PP[,QQ...]_...` subtask directory name, `의존 관계 및 구현 순서` must echo the decoded predecessor subtask directories under the same task group that must produce `complete.log` before implementation starts, and it must not add dependencies that are absent from the directory name. If a predecessor already completed, cite the active or archived `complete.log` path that satisfies it.
For grouped work, the `{subtask_dir}` directory name is the runtime source of truth. If a plan has a `NN+PP[,QQ...]_...` task directory name, `의존 관계 및 구현 순서` must echo the decoded predecessor task directories under the same task group that must produce `complete.log` before implementation starts, and it must not add dependencies that are absent from the directory name. If a predecessor already completed, cite the active or archived `complete.log` path that satisfies it.
Quality rules:
@ -318,6 +328,8 @@ Test policy:
Verification fidelity rules:
These are execution rules for build and review, not commands for the plan author to run.
- Plan verification commands are a contract. The implementing agent must run them exactly as written.
- If a command must be changed, the implementing agent must record the replacement command and reason in `계획 대비 변경 사항`, then paste the replacement command's actual stdout/stderr.
- Before claiming a tool is unavailable, run and record `command -v <tool>` or the project-equivalent check.
@ -331,17 +343,24 @@ Verification fidelity rules:
## Step 6 - Write Review Stub
Read `agent-ops/skills/common/plan/templates/review-stub-template.md` in full only after Step 3 returns `status: routed`.
Read `agent-ops/skills/common/plan/templates/review-stub-template.md` in full only after Step 3 returns `status: routed` for the complete new sibling set.
Replace every occurrence of each token below:
- Scalar tokens: `{date}`, `{task_group}`, `{task_name}`, `{plan_number}`, `{TAG}`, `{build_lane}`, `{build_grade}`, `{review_lane}`, `{review_grade}`, `{plan_log_number}`, `{review_log_number}`.
- Scalar tokens: `{date}`, `{task_group}`, `{task_name}`, `{plan_number}`, `{TAG}`, `{plan_model_identity}`, `{build_lane}`, `{build_grade}`, `{review_lane}`, `{review_grade}`, `{plan_log_number}`, `{review_log_number}`.
- Plan-copy tokens: `{roadmap_targets_or_omit}`, `{archive_evidence_snapshot_or_omit}`, `{agent_ui_completion_or_omit}`, `{implementation_checklist}`, `{review_checkpoints}`.
- Generated row/section tokens: `{implementation_completion_rows}` contains one row for every plan item, and `{verification_result_sections}` contains the fixed verification instructions plus every intermediate/final command from the plan.
- `{implementation_user_review_request_section}` is replaced by the full contents of `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; do not prepend another `사용자 리뷰 요청` heading.
Use the routed build/review grades independently. Remove optional plan-copy content by replacing its token with an empty string, not by leaving template instructions.
In `write` mode, write the rendered stub to the routed review basename. In `prepare-follow-up` mode, return it as `prepared_review` without writing.
Do not write or return a prepared pair when either routing target is not `routed`. After rendering, scan for the exact template-token inventory above and reject the output if any known token remains; do not reject unrelated braces in copied commands or code.
Do not write any pair when a sibling's routing target is not `routed`. After rendering, scan every stub for the exact template-token inventory above and reject the output if any known token remains; do not reject unrelated braces in copied commands or code.
For a multi-sibling set, first write `STAGED_BATCH.md` with the task group, Plan identity, complete sibling paths, frozen scopes, routed basenames, and source-evidence fingerprints. Recovery must finish every listed pair without changing scope/routing; reject fingerprint drift. Remove the batch marker only after all listed pairs are verified.
For each sibling, write the complete plan to `STAGED_PLAN.md`, then the complete stub to `STAGED_CODE_REVIEW.md`. An existing staged plan is immutable: use it as the render source, create only a missing staged review, and reject conflicts. Verify both headers, identities, routed basenames, and bodies before promotion.
For an explicit replacement, preflight the old pair's calculated log destinations after both staged files exist, then rename the old review and old plan. On interruption, match the remaining old member, archived counterpart, and staged pair by task/plan headers; finish only the missing old archive and never overwrite a log.
Preflight both routed destinations, then rename `STAGED_PLAN.md` to the routed PLAN basename and `STAGED_CODE_REVIEW.md` to the routed CODE_REVIEW basename. If only the PLAN was promoted, verify it against the staged identity and promote only the remaining review. Never reroute or create a second PLAN during staged recovery.
## Naming
@ -354,28 +373,14 @@ Do not write or return a prepared pair when either routing target is not `routed
## Final Checklist
- In `write` mode, the routed `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under `agent-task/{task_name}/`. In `prepare-follow-up` mode, neither routed file was written; both exact bodies and basenames were returned while the verdict-appended current pair remained active.
- In `write` mode, `.gitignore` has the Agent-Ops managed block that unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`. In `prepare-follow-up` mode, the block was only inspected and any needed repair was returned as `gitignore_repair_needed`.
- Single-plan work stores active files directly under `agent-task/{task_group}/`.
- Split work, if any, uses one shared `agent-task/{task_group}/` parent and one subtask directory per plan/review pair with names like `01_core`, `02+01_edge_integration`, `03+01_node_integration`; dependency details live in the subtask directory name as `NN+PP[,QQ...]_subtask_name`.
- Milestone-linked work uses `agent-task/m-<milestone-slug>/` as the task group; non-roadmap task groups do not start with `m-`.
- Both first lines match `<!-- task={task_name} plan={plan_number} tag={TAG} -->`.
- The review stub was rendered from `agent-ops/skills/common/plan/templates/review-stub-template.md` after routing and has no unresolved known template token.
- In `write` mode, previous active files, if any, were archived with lane/grade parsed from their own basenames and the correct current archive suffixes. In `prepare-follow-up` mode, those archive names were only predicted.
- In `write` mode when resuming from `USER_REVIEW.md`, it was archived to the calculated `current_user_review_archive_name` and the resolved linked Milestone decision was recorded in the new plan.
- `Roadmap Targets` exists only when PASS should check explicit Milestone Task ids, the task group is `m-<milestone-slug>` for the listed Milestone path, and every listed Task id exists in the selected active Milestone.
- If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too.
- If `Agent UI Completion` exists in the plan, the review stub contains the matching section with implementation-owned evidence fields. If it does not exist in the plan, the review stub omits it too.
- If the selected Milestone has `SDD: 필요`, the plan's `분석 결과 > SDD 기준` proves that the implementation checklist and final verification were derived from the approved SDD Acceptance Scenarios and Evidence Map. Missing SDD mapping blocks plan creation.
- If the plan is a follow-up or resumes from prior archive evidence, it has `Archive Evidence Snapshot` and the review stub contains the identical section.
- `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank/intentionally-unused state, matched profiles read when any, and any fallback verification source.
- Dependent split plans record predecessor completion using active sibling `complete.log` or matching archived `complete.log`; ambiguous archive matches are not guessed.
- Every plan item has problem, solution, checklist, test decision, and intermediate verification.
- The plan and review stub have matching `구현 체크리스트` item text/order, and the final checkbox is the mandatory `CODE_REVIEW-*-G??.md` completion item.
- `finalize-task-routing` ran after all analysis for both `build` and `review` in the required evaluation mode; its output status is `routed`, and the active filenames plus `분석 결과 > 최종 라우팅` exactly match its two results.
- Review WARN/FAIL follow-ups entered through this plan skill and did not inherit or compare the archived lane/G.
- The plan's implementer instructions and review stub both forbid direct user prompts during implementation and explain the implementation-time `사용자 리뷰 요청` stop path.
- The review stub includes the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`.
- The review stub has a clearly marked `코드리뷰 전용 체크리스트` owned only by the review agent.
- Routed review file completion table lists every plan item.
- In `prepare-follow-up`, no repository file was mutated and the returned prepared basenames/bodies, `plan_number`, current archive names/numbers, post-archive log counts, and `gitignore_repair_needed` are complete; in `write`, prior active state was archived with its own parsed route and both new active files were written.
- Every planned sibling has one fully routed PLAN/CODE_REVIEW output pair for the correct task path, with matching headers, checklist, conditional sections, and no template tokens.
- No `STAGED_BATCH.md`, `STAGED_PLAN.md`, or `STAGED_CODE_REVIEW.md` remains after every routed pair is verified.
- Directory names encode every real dependency; parallel siblings have no write, state, ordering, or contract conflict.
- `Roadmap Targets`, Agent UI, SDD, archive evidence, and user-review sections appear only when their stated conditions apply and match between PLAN and CODE_REVIEW.
- Verification records the selected environment, static sources, test decision, commands, and expected results without plan-time execution output. Intermediate verification appears only when it adds an early failure signal.
- The plan model wrote the routed pair, reported `implementation-ready`, and stopped without implementing, reviewing, or starting another agent.
- For a review-dispatched follow-up, the matching `NEXT_STATE.md` was left unchanged for review finalization.
- An explicitly replaced unstarted pair was archived only after its replacement pair was fully staged, with distinct monotonic log suffixes.
- Follow-up routing does not inherit prior lane/G, and implementation/user-review ownership remains unchanged.
- Every generated pair states the three-model separation and one-role-per-invocation boundary.
- Both files contain the same runtime-provided Plan model identity; Implementation and Review identities remain pending until those roles start.

View file

@ -5,10 +5,11 @@
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> This implementation model must differ from the plan and review models. Fill implementation-owned sections, report `review-ready`, and stop. Do not review or start another agent.
> If a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation, record it in `사용자 리뷰 요청`. Record other blockers in the implementation-owned evidence; they are not user-facing stopping states.
> A later review model consumes this file state.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) belongs only to the review model.
> `review-ready` ends the current invocation. `USER_REVIEW.md` stops the loop for a decision; `complete.log` ends the task.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
@ -16,21 +17,31 @@
date={date}
task={task_name}, plan={plan_number}, tag={TAG}
## 역할 모델
- Plan: `{plan_model_identity}`
- Implementation: `pending`
- Review: `pending`
> Runtime만 최초 역할 시작 시 해당 identity를 기록한다. 기록된 identity는 이 pair에서 변경하지 않으며, 재시도는 같은 model identity를 사용한다. 세 identity는 모두 달라야 한다.
{roadmap_targets_or_omit}
{archive_evidence_snapshot_or_omit}
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
> Review 모델은 plan/implementation 모델과 달라야 한다. product source/test를 수정하거나 plan을 실행하지 않는다.
> Review는 후속 PLAN/CODE_REVIEW pair, `USER_REVIEW.md`, `complete.log` 중 정확히 하나를 남긴 뒤 종료한다. archive log만 남기고 종료하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-{review_lane}-{review_grade}.md``code_review_{review_lane}_{review_grade}_{review_log_number}.log`, `PLAN-{build_lane}-{build_grade}.md``plan_{build_lane}_{build_grade}_{plan_log_number}.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 plan skill을 실행해 fresh routing된 다음 active pair를 만들거나 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
3. PASS이면 `complete.log` 작성 후 task를 archive한다. WARN/FAIL이면 `USER_REVIEW.md`를 쓰거나 다른 Plan 모델을 호출해 후속 pair를 만든다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 준비한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한다.
---
@ -53,16 +64,19 @@ task={task_name}, plan={plan_number}, tag={TAG}
- [ ] `코드리뷰 결과``PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [ ] Runtime이 기록한 Plan/Implementation/Review model identity가 모두 다르다.
- [ ] active `CODE_REVIEW-*-G??.md``code_review_{review_lane}_{review_grade}_{review_log_number}.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md``plan_{build_lane}_{build_grade}_{plan_log_number}.log`로 아카이브한다.
- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md``agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] archive 전에 `NEXT_STATE.md`를 기록하고 branch finalization이 끝날 때까지 유지한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/``agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 준비하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 plan skill을 실행하고 `finalize-task-routing`의 fresh 결과와 일치하는 다음 active `PLAN-{build_lane}-GNN.md``CODE_REVIEW-{review_lane}-GNN.md`를 작성하며 `complete.log`를 작성하지 않는다.
- [ ] WARN/FAIL이고 user-review gate가 아니면 active pair를 archive하고 다른 Plan 모델이 같은 task path에 후속 pair를 쓰게 한 뒤 `implementation-ready` 보고 정보를 준비한다. Review 모델은 직접 plan이나 구현을 하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
- [ ] USER_REVIEW 해소가 새 구현을 요구하면 `USER_REVIEW.md`를 archive하고 다른 Plan 모델이 후속 pair를 쓰게 한 뒤 `implementation-ready` 보고 정보를 준비한다.
## 계획 대비 변경 사항
@ -86,13 +100,14 @@ _구현 에이전트가 주요 설계 결정 사항을 기록한다._
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
> Leave review-only sections unchanged, report `review-ready`, and stop. Do not execute code-review or start another agent.
## 섹션 소유권
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed | Implementation model fills its sections, reports `review-ready`, and stops |
| 역할 모델 | Mixed | Plan identity is fixed; runtime replaces each pending role once. Filled identities are immutable, and duplicate identity blocks that role |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` |

View file

@ -0,0 +1,69 @@
---
name: refine-local-plans
description: 현재 plan들 세분화해, 현재 plan 세분화, 기존 plan 더 나눠, local plan 분리해 같은 요청에서 이미 생성된 plan을 추가 분리할 때 사용한다. 미착수 PLAN-local 작업만 유지하거나 최대 3개의 local sibling plan으로 한 단계 분리하고 PLAN/CODE_REVIEW 쌍과 직접 dependency만 갱신한다.
---
# refine-local-plans
## 목표
기존 local plan의 범위를 더 작은 실행 단위로 나눈다. 분리 판단과 문서 갱신은 완료하되 구현 조사나 실행 검증은 하지 않는다.
## 대상
- 사용자가 지정한 `agent-task/{task_group}` 또는 `PLAN-local-G??.md`를 대상으로 삼는다.
- 대상을 생략하면 미착수 local plan이 있는 active task group이 정확히 하나일 때만 사용한다. 여러 개면 후보 경로만 보고하고 멈춘다.
- `PLAN-local-G??.md`만 분리한다. cloud plan은 직접 dependency 참조를 바꿔야 할 때만 해당 참조를 갱신한다.
- 구현 기록, review verdict, `complete.log`, `USER_REVIEW.md`, `*.log`가 있는 작업은 제외하고 이유를 보고한다.
- 대상 PLAN/CODE_REVIEW pair와 dependency를 실제로 바꿔야 하는 미착수 active sibling pair만 읽는다.
- index 할당에는 같은 task group의 active directory name과 archived sibling directory basename만 사용한다. 이미 완료된 direct predecessor의 상태를 기록할 때만 후보 `complete.log`를 active/archive에서 좁게 읽는다.
- roadmap, source, test 또는 다른 skill을 추가로 읽거나 호출하지 않는다.
- PLAN만으로 독립 경계가 명확하지 않으면 추가 조사 없이 유지한다.
## 절차
1. **범위를 추린다**
- 각 PLAN의 목적, 변경 범위, checklist, verification, dependency만 정리한다.
- CODE_REVIEW는 미착수 stub 여부와 복제할 문서 구조만 확인한다.
- active sibling directory name으로 direct dependent를 찾고, dependency가 바뀌는 미착수 pair만 갱신 대상으로 추가한다.
2. **유지 또는 분리를 결정한다**
- 의미 있는 독립 경계가 두 개면 2개, 세 개면 최대 3개로 한 단계만 분리한다.
- 각 child가 단독으로 구현 가능한 결과를 가져야 한다. 공유 상태나 dependency가 더 복잡해지면 유지한다.
- 원본 checklist와 verification을 담당 child에 빠짐없이 배분하되 실행하지 않는다.
3. **PLAN/CODE_REVIEW 쌍을 갱신한다**
- 첫 child는 원본 index와 기존 predecessor 표기를 유지하고 slug만 범위에 맞게 바꾼다.
- 추가 child는 active와 archive directory basename에 없는 다음 index를 사용한다.
- 모든 child는 원본 PLAN의 build lane/G와 CODE_REVIEW의 review lane/G를 그대로 사용한다. 새 routing은 하지 않는다.
- 직렬 child에만 실제 predecessor를 표시하고 병렬 child에는 인위적인 dependency를 만들지 않는다.
- 원본을 의존하던 sibling은 실제로 필요한 child를 모두 의존하도록 참조를 갱신한다.
- dependency가 바뀐 sibling의 안내문, 배경, 분할 판단, 범위 근거, 의존 관계, review checklist에서 이전 predecessor 참조를 모두 갱신한다.
- 이미 완료된 predecessor는 matching active/archive `complete.log`의 정확한 경로를 인용한다. 새로 만든 child는 완료됐다고 쓰지 않는다.
- subtask directory name이 runtime dependency의 source of truth이므로 `최종 검증`이나 review의 구현 검증에 active 위치를 가정한 `test -f agent-task/{task_group}/{predecessor}/complete.log`를 추가하지 않는다. review 전용 checklist에서 matching active/archive `complete.log`를 확인한다.
- 원본에 `Roadmap Targets`가 있으면 다른 child를 모두 거친 자연스러운 closure child에만 둔다. 그런 closure가 없으면 분리하지 않는다.
- 관련 없는 sibling의 index, route, 본문은 변경하지 않는다.
4. **문서만 확인하고 완료한다**
- 변경한 directory마다 PLAN/CODE_REVIEW가 한 쌍인지 확인한다.
- 원본 범위, checklist, verification이 child 집합에 모두 남았는지 확인한다.
- 변경한 dependency가 actual active child 또는 matching archived predecessor와 일치하는지 확인한다.
- 변경한 pair 전체에서 이전 predecessor index/name과 active-only `complete.log` 검증 명령이 남지 않았는지 확인하고 어긋난 문서는 바로 고친다.
## 출력
```text
Local plan refinement
- targets: <PLAN 경로>
- decisions: <유지 | 원본 -> child 목록>
- dependency updates: <변경 내용 또는 없음>
- document check: passed
```
## 금지
- inventory/validator script, compile, build, test, lint, formatter, smoke/E2E, live/remote 검증을 실행하지 않는다.
- source/test 재분석, verification 명령 실행, package 설치, dependency 다운로드, cache warming을 하지 않는다.
- `plan` 또는 `finalize-task-routing`으로 child를 재라우팅하지 않는다.
- 전체 active sibling 재인덱싱, repository 밖 staging, 전체 task group 복원 절차를 사용하지 않는다.
- plan 밖 구현 범위를 추가하거나 child를 재귀 분리하지 않는다.

View file

@ -36,6 +36,7 @@
| 이 마일스톤은 X가 끝나야 가능해, A 전까지 B 잠가둬, 잠금 해제 조건은 X야, X 프로젝트 작업 뒤에 현재 마일스톤 진행, 의존성 설정해, 외부 의존 잠금 | `agent-ops/skills/common/update-roadmap/SKILL.md` |
| roadmap dependency 확인, locks.yaml 판별, 외부 의존 잠금 확인, unlock-ready 판별, 잠금 해제 조건 충족 여부 확인, roadmap-dependency-checker.sh | `agent-ops/skills/common/check-roadmap-dependency/SKILL.md` |
| 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 로드맵상 현 위치, 현재 마일스톤 위치, current 기준 breadcrumb | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` |
| 현재 plan들 세분화해, 현재 plan 세분화, 기존 plan 더 나눠, local plan 분리해 | `agent-ops/skills/common/refine-local-plans/SKILL.md` |
| 계획 세워줘, 계획 작성해, 계획 만들어줘, 구현 계획, PLAN.md, plan, plan 작성해, plan 만들어줘 | `agent-ops/skills/common/plan/SKILL.md` |
| 최종 라우팅, task routing, cloud/local 재평가, lane/G 판단, G 등급 재평가, routed filename 결정 | `agent-ops/skills/common/finalize-task-routing/SKILL.md` |
| 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` |
@ -44,8 +45,15 @@
| agent-ops pull해, agent-ops 가져와, agentic-framework에서 가져와, agent-ops 내려받아 | `agent-ops/skills/common/sync-pull/SKILL.md` |
| 도메인 업데이트, domain rule 갱신, 도메인 검토, domain 스캔 | `agent-ops/skills/common/update-domain-rule/SKILL.md` |
라우팅 우선순위:
Plan/review 역할 경계:
- 선택한 task에 `NEXT_STATE.md`가 있으면 다른 역할보다 `code-review` 복구를 먼저 수행한다.
- 선택한 task group에 `STAGED_BATCH.md`, `STAGED_PLAN.md`, 또는 `STAGED_CODE_REVIEW.md`가 있으면 `plan` 복구를 먼저 수행하며, marker가 남아 있는 동안 implementation/review를 시작하지 않는다.
- PLAN/CODE_REVIEW 작성 또는 재작성이 요청 범위에 포함되면 `plan`을 선택한다. `plan`이 최종 단계에서 `finalize-task-routing`을 필수 호출한다.
- lane/G/canonical filename 판단만 요청되고 plan 문서 작성은 요청되지 않았을 때만 `finalize-task-routing`을 직접 선택한다.
- 코드 리뷰 요청은 `code-review`를 선택한다. WARN/FAIL follow-up은 `code-review -> plan -> finalize-task-routing` 순서를 유지한다.
- plan, implementation, review는 서로 다른 모델이 한 역할씩 수행한다. 현재/root 모델은 다음 역할을 다른 모델에 맡길 수 있지만 직접 그 역할을 수행하지 않는다.
- Runtime은 선택 task path와 역할별 model identity를 pair/handoff에 기록한다. 다음 역할 시작 전에 identity 중복을 거부하고, 구현 소유 리뷰 섹션이 모두 채워진 `review-ready` 상태에서만 Review 모델을 시작한다.
- Plan은 PLAN/CODE_REVIEW pair 작성, implementation은 리뷰 문서 완성, review는 후속 plan pair·`USER_REVIEW.md`·`complete.log` 중 하나를 남긴 뒤 끝난다.
- WARN/FAIL 리뷰는 다른 Plan 모델이 후속 pair를 작성한 뒤 끝나며, 같은 리뷰 흐름에서 구현하지 않는다.
- Review는 archive 전에 `NEXT_STATE.md`를 기록하고 branch finalization 내내 유지한 뒤 마지막 파일 변경으로 제거한다. 중단 시 이 파일의 target부터 재개한다.
- 정상 역할 종료 상태에는 `STAGED_BATCH.md`, `STAGED_PLAN.md`, `STAGED_CODE_REVIEW.md`, `NEXT_STATE.md`가 없다. `USER_REVIEW.md`는 결정 대기 terminal/evidence이며, 해소 후 replan이면 `user_review_N.log`, 완료면 task archive로 수렴한다.