--- name: plan description: Analyze the current repository and write a detailed PLAN-{build_lane}-GNN.md for implementation work. Also writes the CODE_REVIEW-{review_lane}-GNN.md stub that the implementing agent will fill in after coding. Use for any feature, refactor, bug fix, or follow-up fix that should enter the plan-code-review loop. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding. --- # Plan ## Purpose Create the planning artifacts for the implementation loop: ```text plan skill -> 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 PASS/user-review-resolved task-directory archive move, new follow-up plan/review files, or USER_REVIEW.md runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call ``` `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. 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. ## 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. 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-`, where `` 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_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. - 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. Filename rules: - Plan file: `PLAN-{build_lane}-GNN.md` - Review stub: `CODE_REVIEW-{review_lane}-GNN.md` - `{lane}` is only `local` or `cloud`; never put model names in filenames. - `GNN` is a two-digit capability grade from `G01` to `G10`; the runtime maps lane+grade to current models externally. Role boundary rules: - 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. Split decision policy: - 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. Split gates: - 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. Task directory naming rules: - A normal single-plan task uses `agent-task/{task_group}/` with a short snake_case category name, e.g. `agent-task/refactoring/`. - If the plan is based on a selected active Milestone, use `agent-task/m-/` as the task group. Do not include the Phase slug, Epic id, Task id, or a separate task slug in the task group. - `m-` 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 `` by matching exactly one active file at `agent-roadmap/phase/*/milestones/.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. - 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}`. - 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 `_`. - 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`. - Preserve task group and subtask directory names verbatim; do not normalize, reinterpret, or choose execution order by agent judgment. Routing rules: - Prefer `local` whenever the scope is bounded and verifiable; high local usage is fine. Do not choose `cloud` just to balance lane usage. - `local` is for bounded, explicit, locally verifiable work: required behavior is explicit in task evidence, contracts, or existing pattern; relevant context fits in edited files plus nearby types/helpers, direct call sites, and existing or planned targeted tests/fixtures; correctness can be checked by code inspection plus type/build/unit tests or deterministic commands; no open-ended product/design judgment, live external provider/runtime semantics, or broad cross-domain context is decisive. - Use `cloud` when any local condition is false, including when a plausible but wrong implementation could pass local checks while breaking behavior promised outside the bounded context. - `local-G01` through `local-G10` and `cloud-G01` through `cloud-G10` are valid. Lane is capability fit; grade is complexity within the chosen lane. Do not raise `local-GNN` to compensate for missing judgment, missing context, weak verification, or a previous loop failure. - Use `cloud-G07` or higher only when terminal-agent or external interactive behavior is central and cannot be made deterministic for local handling, or when the task requires more source/test/diff/log context than local can hold without omitting material evidence: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, terminal benchmark-style tasks, TUI/PTY/browser/screen repaint/cursor stream behavior, real bin/smoke/integration failures after unit tests passed, or very large cross-module/cross-domain changes that cannot be safely split. - For follow-ups from a review with 5+ `Required` findings, reassess lane/grade and default to `cloud-G07` or higher unless all findings are one narrow mechanical fix pattern; if keeping `local`, record why local conditions still hold. - Previous loop lane does not matter. Recompute lane from the current plan or follow-up scope using these rules. - Treat non-behavioral review artifact drift as reviewer-repairable unless it prevents judging implementation correctness, tests, or contracts. - Treat obvious non-behavioral source nits as reviewer-repairable too: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change. - Raise `GNN` with scope, ambiguity, missing tests, irreversible behavior, and blast radius after lane selection; keep grade model-independent. 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` | Ready for code-review skill | | `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 | | `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`) | Task terminated mid-loop or abandoned | ## Step 1 - Determine Task If the user names the task explicitly, use that task group or task path. Otherwise, find active plan files with both globs, excluding `agent-task/archive/**`: - `agent-task/*/PLAN-*-G??.md` - `agent-task/*/*/PLAN-*-G??.md` Also note active user-review stops, excluding `agent-task/archive/**`: - `agent-task/*/USER_REVIEW.md` - `agent-task/*/*/USER_REVIEW.md` | Result | Action | |--------|--------| | Exactly one | Continue that task | | 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. 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 `분석 결과`. 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. 로드맵 확인: - `agent-roadmap/current.md`는 브랜치별 로컬 포인터다. 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다. - `agent-roadmap/priority-queue.md`가 있으면 명시 target이 없는 구현 계획에서 Phase를 가로지르는 후보 순서를 확인하기 위해 읽는다. 큐 순서는 우선순위 참고이며, 상태/잠금/기능 원본은 각 Milestone 문서다. - 사용자가 target Milestone을 명시하지 않았고 요청이 "다음 작업" 또는 일반 구현 계획이면 `priority-queue.md`의 위에서 아래 순서 중 요청과 맞고 활성 경로에 존재하는 첫 Milestone을 우선 후보로 둔다. - `priority-queue.md` 링크가 깨졌으면 Milestone을 추측해 계획하지 말고 `update-roadmap`으로 큐 재정렬/재생성이 필요하다고 보고한다. - `agent-roadmap/`이 있는데 `current.md`가 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만들거나, `ROADMAP.md`의 Phase 흐름과 관련 `PHASE.md`에서 후보를 고른 뒤 로컬 current를 채운다. current 없음만으로 일반 task routing으로 빠지지 않는다. - `current.md`가 `agent-roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다. - 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다. - 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건`은 `[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나, 상태가 `잠금`이거나, 미완료 `결정 필요` 항목이 하나라도 있으면 실구현 계획을 만들지 않는다. - 구현 잠금에 걸린 Milestone에서는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, task directory, file/API/package 수준 구현 단계를 확정하지 말고 `구현 잠금 차단`으로 보고한다. 보고에는 Milestone 경로, 잠금 상태, 남은 `결정 필요` 항목, 다음에 필요한 `update-roadmap` 조치를 적는다. - 남은 `결정 필요` 항목이 현재 실구현 범위가 아니라고 판단되더라도 같은 plan 요청 안에서 구현 계획을 계속 쓰지 않는다. 먼저 roadmap-only 갱신으로 해당 항목을 `범위 제외`, 후속 Milestone, 또는 `작업 컨텍스트`로 옮기고 `구현 잠금`을 `해제`한 뒤 새 plan 요청에서 진행한다. - 선택한 Milestone에 `SDD: 필요`가 있으면 승인된 SDD를 구현 계획 작성의 입력으로 읽는다. SDD 문서가 없거나, 상태가 `[승인됨]`이 아니거나, `SDD 잠금`이 `잠금`이거나, 같은 디렉터리에 `USER_REVIEW.md`가 있으면 plan 파일을 만들지 말고 `roadmap-sdd` 또는 `update-roadmap` 조치가 필요하다고 보고한다. - `SDD: 필요` Milestone의 구현 계획은 Milestone 기능 Task만 보고 작성하지 않는다. 요청 대상 Task id에 연결된 SDD Acceptance Scenario와 Evidence Map을 먼저 매핑하고, 그 결과에서 구현 범위, checklist, 검증 명령, 완료 evidence를 역산한다. 매핑이 없거나 SDD와 Milestone Task가 어긋나면 plan 생성을 멈추고 SDD와 Milestone의 정합성 갱신이 필요하다고 보고한다. - 선택한 Milestone에 legacy `필수 기능`/`완료 기준`이 분리되어 있으면 plan 파일을 만들지 말고 `update-roadmap` 정규화가 필요하다고 보고한다. - 선택한 Phase 또는 Milestone 상태가 `[스케치]`이면 구현 계획 파일을 만들지 않는다. `[스케치]`는 컨셉 상태이므로 `update-roadmap`의 concretize 흐름으로 승격 조건, 결정 필요, 범위, 기능 Task를 정리해 `[계획]`으로 전환해야 한다고 보고한다. - Phase 또는 Milestone 후보가 여럿이면 요청 문장, 변경 경로 직접성, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 기준으로 1순위와 2순위를 추천하고 필요한 후보 문서만 읽어 범위를 좁힌다. - 로드맵 current가 있고 활성 Phase/Milestone 밖 작업이면 `ROADMAP.md`의 Phase 흐름을 확인하고 전환, 신규 Phase/Milestone, 또는 기존 활성 범위 내 배치 필요성을 보고한다. - 사용자가 선택한 Milestone의 작업, 구현, 계획 작성을 명시했더라도 `구현 잠금`이 완전히 해제되어 있지 않으면 계획 작성을 이어가지 않는다. Milestone 전체에서 에이전트가 확정할 수 없는 결정 항목이 더 이상 없을 때만 roadmap update 흐름으로 `구현 잠금` 상태를 `해제`로 갱신할 수 있다. - 제품 선택, 우선순위 결정처럼 에이전트가 확정할 수 없는 항목은 구현 계획의 실행 checklist로 쓰지 않는다. 그런 항목이 남아 있으면 plan 생성을 멈추고 `구현 잠금 > 결정 필요`로 분리한다. - 기능 Task에 `검증:`이 있으면 구현 계획의 같은 plan item 안에 해당 검증을 포함한다. 검증이 명시되지 않은 기능 Task에는 억지 검증 항목을 만들지 말고, 필요한 일반 빌드/회귀 확인만 최종 검증에 둔다. - 선택한 활성 Milestone 범위에 속하는 구현 계획이면 `{task_group}`을 `m-`로 정한다. ``는 선택한 Milestone 경로의 파일명에서 `.md`를 제거한 값이다. - 같은 Milestone에서 split work가 필요하면 기존 split 규칙 그대로 `agent-task/m-//` 아래에 계획 파일을 만든다. - Milestone 기능 Task 완료를 목표로 하는 계획이면 `Roadmap Targets` 섹션에 활성 Milestone 경로와 완료 대상 Task id를 고정한다. 이 섹션은 `complete.log`의 `Roadmap Completion` 근거로 복사되어 `update-roadmap`이 해당 Task만 체크하는 anchor가 된다. 이 섹션은 `{task_group}`이 해당 Milestone slug의 `m-`일 때만 쓴다. - Milestone 작업이 아니거나, Milestone 안의 조사/하위 구현처럼 특정 기능 Task 완료를 주장하지 않는 계획이면 `Roadmap Targets` 섹션을 쓰지 않는다. 섹션이 없으면 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. ## 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. - [ ] **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//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//.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. ## Step 3 - Determine GXX Grade GXX is an output of analysis, not an input. Determine lane and grade only after Step 2 is fully complete. - [ ] **Assess change scope** — count affected files, interface impact, call-site count, and the amount of source/test/review context that must stay loaded together. - [ ] **Check risk factors** — mark any that apply: behavior promised outside edited files, persisted-state rule, permission boundary, shared-state risk, irreversible behavior. - [ ] **Evaluate test confidence** — judge whether existing tests sufficiently verify the changed behavior. - [ ] **Decide lane** — apply `Routing rules` as a gate. Use `local` only when all local allowlist conditions are true; otherwise use `cloud`. Ignore previous loop lane. - [ ] **Decide GNN** — assign grade within the selected lane as scope, ambiguity, irreversibility, and blast radius increase. Grade is complexity-based, not model-name-based; both `local-G10` and `cloud-G01` are valid when lane evidence supports them. Do not increment GNN solely because a previous loop failed. ## Step 4 - Archive Existing Active Files Before writing new active files for the chosen active task directory: - 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`. - Count existing `agent-task/{task_name}/plan_*.log`; call it `N`. If `PLAN-*-G??.md` exists in that same directory, rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_N.log`. - Count existing `agent-task/{task_name}/code_review_*.log`; call it `M`. If `CODE_REVIEW-*-G??.md` exists in that same directory, rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_M.log`. - Count existing `agent-task/{task_name}/user_review_*.log`; call it `U`. If `USER_REVIEW.md` exists in that same directory and the linked Milestone decision is resolved for replanning, rename `USER_REVIEW.md` to `user_review_U.log`. The new plan number is the count of `plan_*.log` after archiving. ## Step 5 - Write Plan File Header line must be exactly: ```markdown ``` 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. - `배경`: 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: ```markdown ## Roadmap Targets - Milestone: `agent-roadmap/phase//milestones/.md` - Milestone link: [Milestone 문서](agent-roadmap/phase//milestones/.md) - Task ids: - ``: - Completion mode: check-on-pass ``` - `Agent UI Completion`: include this section only when the plan implements agent-ui definition/frame/component changes in code and code-review PASS should move specific agent-ui documents to `status: 구현됨`. Omit it for non-agent-ui work, `direct-sync` work handled entirely by `sync-agent-ui`, and `milestone-required` work whose status update is intentionally deferred to Milestone 종료 검토. Format exactly: ```markdown ## Agent UI Completion - Mode: review-pass-status-update - Agent UI docs: - `agent-ui/definition/views//index.md` - Required code evidence: - ``: - Required implementation verification: - ``: PASS expected before review - Review finalization validation: - `validate-agent-ui scope=`: PASS expected after status/evidence update - Status updates on PASS: - `agent-ui/definition/views//index.md`: `계획` -> `구현됨` ``` - `분석 결과`: record the findings from Step 2 and 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. - `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//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. - `테스트 커버리지 공백`: 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. - `범위 결정 근거`: 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. - `빌드 등급`: state the decided lane and GNN grade with a one-line rationale. - `구현 체크리스트`: 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. - 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."** Each plan item must include: - `문제`: 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. 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. Quality rules: - Exact line numbers in every Before snippet. - Use the language's required override annotation/keyword wherever an abstract method is implemented. - Include full import statements for new packages. - List all call sites for renamed/removed symbols. - Never write "add tests as needed"; decide up front. - Do not cite files you did not read. - Be concise. Write the minimum words needed to convey the decision or fact. No preamble, no restatement of context already in the plan, no closing summaries. Test policy: | Change | Test requirement | |--------|------------------| | Bug fix | Regression test required | | New public API | Normal + boundary tests required | | API rename | Existing test call-site updates usually enough | | Internal refactor | Existing tests may be enough | | Concurrency logic | Race/ordering test recommended | Verification fidelity rules: - 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 ` or the project-equivalent check. - Before a remote/field/external verification command assumes a checkout, binary, config, runtime identity, or listening port, the plan must include a preflight command that proves those assumptions or a setup command that makes them true. - Do not download, generate, or leave verification tools inside the repository. Temporary tools belong outside the repo, such as under `/tmp`, and must not become task artifacts. - For search commands whose output order may vary, specify deterministic options in the plan, for example `rg --sort path`. - `검증 결과` must contain actual stdout/stderr, not summarized or reconstructed output. If output is too long, record the saved output file path and the exact command used to create it. - If mobile/UI verification has no progress for 2 minutes or times out, stop blind retries; collect focused stdout plus screenshot/window/UI-tree evidence when available, or record why capture is impossible. - If the plan's pass condition says all leftovers must be intentional exceptions, any `변경 필요` item forces FAIL until resolved or explicitly reclassified with evidence. - Decide in the plan whether Go test cache output is acceptable. If fresh execution matters, use `go test -count=1 ...`. ## Step 6 - Write Review Stub Use the template below exactly. Fill `{…}` placeholders from the plan; everything else is fixed and must not be changed by the implementing agent. Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the review stub's `사용자 리뷰 요청` section. ```markdown # Code Review Reference - {TAG} > **[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. > Follow the ownership table at the bottom of this file for which sections you own. ## 개요 date={YYYY-MM-DD} task={task_name}, plan={N}, tag={TAG} {copy the plan's Roadmap Targets section exactly if present; omit this block if the plan has no Roadmap Targets} {copy the plan's Archive Evidence Snapshot section exactly if present; omit this block if the plan has no Archive Evidence Snapshot} ## 이 파일을 읽는 리뷰 에이전트에게 > **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. 각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. 리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. 1. 판정을 append한다. 2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다. 3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. 4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. 5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. --- ## 구현 항목별 완료 여부 | 항목 | 완료 여부 | |------|---------| | [{TAG}-1] {item description} | [ ] | | [{TAG}-2] {item description} | [ ] | ## 구현 체크리스트 {copy the plan's 구현 체크리스트 items exactly, preserving order and checkbox text} ## Agent UI Completion > Include this section only when the plan has `Agent UI Completion`; otherwise omit it entirely. > **[IMPLEMENTING AGENT]** Fill actual code evidence and implementation verification output for the listed docs. > **[REVIEW AGENT ONLY]** On PASS, update only the listed agent-ui docs to `구현됨`, add the listed code evidence, run `validate-agent-ui`, and copy this section into `complete.log`. - Mode: review-pass-status-update - Agent UI docs: - `agent-ui/definition/views//index.md` - Actual code evidence: - [ ] ``: - Implementation verification evidence: - [ ] ``: - Status updates requested on PASS: - [ ] `agent-ui/definition/views//index.md`: `계획` -> `구현됨` - Review finalization: - [ ] Review agent updated the listed agent-ui docs and code evidence. - [ ] Review agent ran `validate-agent-ui scope=` after the status/evidence update. ## 코드리뷰 전용 체크리스트 > **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. > 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. - [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. - [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. - [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. - [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. - [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. - [ ] 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. - [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. - [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. - [ ] 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로 이동한다. ## 계획 대비 변경 사항 _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ ## 주요 설계 결정 _구현 에이전트가 주요 설계 결정 사항을 기록한다._ ## 사용자 리뷰 요청 _기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._ - 상태: 없음 - 사유 유형: 없음 - 연결 대상: 없음 - 결정 필요: 없음 - 차단 근거: 없음 - 실행한 검증/명령: 없음 - 자동 후속 불가 이유: 없음 - 재개 조건: 없음 ## 리뷰어를 위한 체크포인트 {pre-filled from plan — one bullet per review focus area} ## 검증 결과 _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ 필수 규칙: - 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. - 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. - `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. - 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. - mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다. ### {TAG}-1 중간 검증 ``` $ {verification command from plan} (output) ``` ### 최종 검증 ``` $ {final verification command from plan} (output) ``` --- > **[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. ``` Sections and their ownership: | 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) | | 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` | | 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | | 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only; final checkbox is mandatory before saving | | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | | 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content | | 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation; do not ask the user directly during implementation; environment/secret/service blockers, generic scope changes, and evidence gaps are not user-review requests | | 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan | | 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry | | 코드리뷰 결과 | Review agent appends | Not included in stub | ## Naming | Tag | Use for | |-----|---------| | `API` | Public API changes | | `REFACTOR` | Internal refactoring | | `TEST` | Test additions/fixes | | `REVIEW_` | Follow-up fixes after review | ## Final Checklist - `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under the active task directory `agent-task/{task_name}/`. - `.gitignore` has the Agent-Ops managed gitignore block that unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`, so active files and archived `*.log` task artifacts are trackable even when the project ignores `*.log`. - 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-/` as the task group; non-roadmap task groups do not start with `m-`. - Both first lines match ``. - Previous active files, if any, were archived with correct numeric suffixes. - If resuming from `USER_REVIEW.md`, it was archived to `user_review_N.log` 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-` 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. - 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.