iop/agent-ops/skills/common/plan/SKILL.md

name

description

plan

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. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding. The code-review skill archives both files after review and moves PASS tasks under agent-task/archive/YYYY/MM/.

Plan

Purpose

Create the planning artifacts for the implementation loop:

plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub
implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md
code-review skill -> verdict + archive, complete.log, and PASS task-directory archive move or new follow-up plan/review files

Workflow Contract

This skill intentionally uses routed active files under agent-task/{task_name}/ as the state protocol. Do not change this filename contract unless the paired code-review skill is updated together.

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.

Task directory naming rules:

• A single-plan task uses agent-task/{task_name}/ with a short snake_case task name.
• Prefer splitting before writing. A single-plan task is allowed only when the work is one coherent implementation unit with one primary ownership boundary, no prerequisite subtask, and a reviewable blast radius.
• If the work can be decomposed by dependency, ownership boundary, subsystem, API-vs-call-site phase, test strategy, or independently reviewable risk, split it into multiple task directories. Each 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 multiple folders, not multiple plan files inside one folder.
• Multi-plan task directory names must start with a stable two-digit task index. The index must increase across sibling task directories for sorting, but it is not a serial execution dependency.
• Use NN_{task_name} for a task with no runtime dependencies, e.g. 01_core, 04_docs, 05_ui.
• Use NN+PP[,QQ...]_{task_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 task directory.
• The first _ after the index or dependency list starts {task_name}. {task_name} stays short snake_case and may contain additional underscores.
• Runtime scheduling reads only the directory name: _ means depends_on=[]; + means depends_on is the comma-separated index list between + and the first _.
• 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+{task_name} without predecessor indices.
• Example: split a common core plus two app integrations 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 as 01_schema, 02+01_migration, 03+02_api.
• Example: split independent docs/UI plus an integration 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 directory names verbatim; do not normalize, reinterpret, or choose execution order by agent judgment.

Split-first gates:

• Before choosing a single plan, explicitly ask: "Could this be split into smaller independently reviewable implementation units?" If yes, split.
• Split when a plan would require both shared API/foundation changes and broad call-site rollout. Put the API/foundation in an earlier task and the rollout in dependent task(s).
• Split when a plan 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 different risk profiles.
• Split when a likely failure in one part would force rewriting unrelated parts of the plan.
• Single-plan bias is acceptable only for narrow fixes, one-file/small-file-cluster refactors, or tightly coupled changes where splitting would create artificial coordination overhead.

Routing rules:

• Build defaults to local when the plan is explicit, tests are runnable, and failure is review-detectable.
• Use cloud for weak tests, broad API/call-site impact, ambiguity, storage/concurrency/protocol/auth risk, or prior local failure.
• Use cloud-G07 or higher for terminal-agent work: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks. Merely running deterministic tests such as go test does not make a task terminal-agent work.
• Use cloud-G07 or higher when acceptance depends on a real interactive external tool, TUI, PTY, browser, screen repaint/cursor stream, or bin-level smoke output. This is mandatory when unit tests pass but the real smoke/integration command fails.
• Use cloud-G07 or higher when a prior review found verification trust failure, reconstructed command output, or claimed stdout/stderr that does not match a rerun.
• Keep high-risk design judgment on cloud with a higher grade; the runtime may map cloud-GNN to frontier-class models.
• Review may be local for narrow/low-risk checks and cloud for multi-file/API/test-meaning reviews, security/auth, storage/migration, concurrency, protocol/schema, cross-domain, or repeated Required issues.
• Raise GNN with scope, ambiguity, missing tests, irreversible behavior, and blast radius; 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 + filled CODE_REVIEW-*-G??.md	Ready for code-review skill
complete.log + *.log files	Task complete (PASS), before final task-directory archive move
agent-task/archive/YYYY/MM/{task_name}/complete.log + *.log files	Archived completed task (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 name.

Otherwise, glob agent-task/*/PLAN-*-G??.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 directory, use that directory. Otherwise list paths and ask which task to use; do not choose by agent judgment.

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.

Use short snake_case task names, e.g. api_refactor.

Before writing a single plan, record why the split-first gates did not require multiple task directories. When the work must be split into multiple plans, choose directory names using the task directory naming rules above. Do not put multiple active plan files in one task directory.

Step 2 - Analyze Before Writing

Complete all items below before creating any files. Work through them in order; do not proceed to the next step until every checkbox is done.

• Read all source files in full — read every source file the change will touch, whole file. No partial reads.
• Read all test files in full — read every test file that exercises the changed behavior.
• Assess test coverage — for each behavior change, explicitly record whether existing tests cover it.
• Assess split boundaries — identify dependency boundaries, ownership boundaries, API-vs-call-site phases, and independently verifiable subwork. If any split-first gate applies, write multiple task directories instead of one plan.
• 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, and call-site count.
• Check risk factors — mark any that apply: concurrency, storage/migration, protocol/schema, auth, irreversible behavior.
• Evaluate test confidence — judge whether existing tests sufficiently verify the changed behavior.
• Decide lane — use local if the plan is explicit and tests are sufficient; use cloud if any of the following apply:
  • Tests are weak or do not cover the changed behavior
  • Broad API/call-site impact
  • Concurrency, storage, protocol, or auth risk
  • Prior local build failure on this task
  • Terminal-agent work: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, or terminal benchmark-style tasks
  • Real bin/smoke/integration verification failed after unit tests passed
  • Interactive TUI/PTY/browser/external CLI automation or screen-rendered output is part of the success condition
  • A prior review marked verification trust Fail/Warn because recorded command output did not match a rerun
• Decide GNN — assign a higher grade as scope, ambiguity, irreversibility, and blast radius increase. Grade is complexity-based, not model-name-based.

Step 4 - Archive Existing Active Files

Before writing new active files for the chosen task:

• Count existing agent-task/{task_name}/plan_*.log; call it N. If PLAN-*-G??.md exists, 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, rename CODE_REVIEW-{review_lane}-GNN.md to code_review_{review_lane}_GNN_M.log.

The new plan number is the count of plan_*.log after archiving.

Step 5 - Write Plan File

Header line must be exactly:

<!-- task={task_name} plan={N} tag={TAG} -->

Required sections:

• Title.
• 이 파일을 읽는 구현 에이전트에게: open with a bold warning that filling in implementation-owned sections of CODE_REVIEW-*-G??.md is a mandatory final step — the task is NOT complete until every implementation-owned section of that file is filled. Tell the implementer to work from the implementation checklist, complete every checklist item in both the plan and review stub, run intermediate/final verification, and fill implementation-owned CODE_REVIEW-*-G??.md sections with actual implementation notes and command output. Explicitly state that the implementing agent must NOT execute the archiving instructions in the review file's 이 파일을 읽는 리뷰 에이전트에게 section and must NOT modify or check the 코드리뷰 전용 체크리스트 — those instructions/checklists are for the code-review skill only.
• 배경: 2-4 sentences explaining why the work is needed.
• 분석 결과: 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 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 whether the split-first gates were evaluated. For a single plan, explain why the work is still one coherent reviewable unit. For multi-plan output, list each sibling task directory and dependency relationship.
  • 범위 결정 근거: 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 plan item, one item for all intermediate/final verification, 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. 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 directory name is the runtime source of truth. If a plan has a NN+PP[,QQ...]_... directory name, 의존 관계 및 구현 순서 must echo the decoded predecessor task directories that must produce complete.log before implementation starts, and it must not add dependencies that are absent from the directory name.

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 <tool> or the project-equivalent check.
• 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 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.

<!-- task={task_name} plan={N} tag={TAG} -->

# 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.
> Do not modify or check the `코드리뷰 전용 체크리스트`; it is owned by the review agent only.
> 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}

## 이 파일을 읽는 리뷰 에이전트에게

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.

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` 작성 후 task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 다음 active plan/review 파일을 즉시 작성한다.
4. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [{TAG}-1] {item description} | [ ] |
| [{TAG}-2] {item description} | [ ] |

## 구현 체크리스트

{copy the plan's 구현 체크리스트 items exactly, preserving order and checkbox text}

## 코드리뷰 전용 체크리스트

> **[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`로 아카이브한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.

## 계획 대비 변경 사항

_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._

## 주요 설계 결정

_구현 에이전트가 주요 설계 결정 사항을 기록한다._

## 리뷰어를 위한 체크포인트

{pre-filled from plan — one bullet per review focus area}

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._

필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.

### {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 the review-agent-only checklist 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)
구현 항목별 완료 여부 (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
리뷰어를 위한 체크포인트	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_<TAG>	Follow-up fixes after review

Final Checklist

• PLAN-{build_lane}-GNN.md and CODE_REVIEW-{review_lane}-GNN.md both exist under agent-task/{task_name}/.
• Split work, if any, uses one task directory per plan/review pair with names like 01_core, 02+01_edge_integration, 03+01_node_integration; dependency details live in the directory name as NN+PP[,QQ...]_task_name.
• Both first lines match <!-- task={task_name} plan={N} tag={TAG} -->.
• Previous active files, if any, were archived with correct numeric suffixes.
• 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 review stub has a clearly marked 코드리뷰 전용 체크리스트 owned only by the review agent.
• Routed review file completion table lists every plan item.