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

name

description

plan

Analyze the current repository and write a detailed PLAN.md for implementation work. Also writes the CODE_REVIEW.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 PLAN.md and does the coding. The code-review skill archives both files after review.

Plan

Purpose

Create the planning artifacts for the implementation loop:

plan skill -> PLAN.md + CODE_REVIEW.md stub
implementation -> code changes + filled CODE_REVIEW.md
code-review skill -> verdict + archive, or new follow-up PLAN.md

Workflow Contract

This skill intentionally uses agent-task/{task_name}/PLAN.md and agent-task/{task_name}/CODE_REVIEW.md as the state protocol between planning, implementation, and review. Do not change these paths or filenames unless the paired plan and code-review skills are updated together. This convention is not project-specific; it is the workflow contract for this skill loop.

Directory states:

State	Meaning
PLAN.md only	Invalid; plan skill always writes both files
PLAN.md + CODE_REVIEW.md stub	Implementation is pending/in progress
PLAN.md + filled CODE_REVIEW.md	Ready for code-review skill
complete.log + *.log files	Task complete (PASS)
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.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	List paths and ask which task to use

PLAN.md is the loop entry point. A missing PLAN.md 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.

Step 2 - Analyze Before Writing

Complete these before creating files:

• Read every source file the change will touch, whole file.
• Read every test file that exercises changed behavior.
• For each behavior change, note whether existing tests cover it.
• Grep renamed/removed symbols for all call sites and import chains.
• Check package manifests/dependency files before adding dependencies.
• Anticipate compile issues: missing overrides, type mismatches, broken imports.
• Confirm final verification commands work in this repository layout.

Step 3 - 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.md exists, rename it to plan_N.log.
• Count existing agent-task/{task_name}/code_review_*.log; call it M. If CODE_REVIEW.md exists, rename it to code_review_M.log.

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

Step 4 - Write PLAN.md

Header line must be exactly:

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

Required sections:

• Title.
• 이 파일을 읽는 구현 에이전트에게: tell the implementer to complete checklists, run intermediate/final verification, and fill every CODE_REVIEW.md section with actual implementation notes and command output.
• 배경: 2-4 sentences explaining why the work is needed.
• One item per change: ### [TAG-1] Title, TAG-2, etc.
• 수정 파일 요약: table mapping files to item ids.
• 최종 검증: runnable commands and expected outcome.

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.

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.

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

Step 5 - Write CODE_REVIEW.md 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}

## 개요

date={YYYY-MM-DD}
task={task_name}, plan={N}, tag={TAG}

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

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료 후 반드시 아래 순서로 아카이브하세요.

1. `CODE_REVIEW.md` → `code_review_N.log` (N = 기존 code_review_*.log 수)
2. `PLAN.md` → `plan_M.log` (M = 기존 plan_*.log 수)
3. PASS인 경우 `complete.log` 작성 후 종료. WARN/FAIL인 경우 새 `PLAN.md` + `CODE_REVIEW.md` 스텁 작성.

---

## 구현 항목별 완료 여부

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

## 계획 대비 변경 사항

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

## 주요 설계 결정

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

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

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

## 검증 결과

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

### {TAG}-1 중간 검증

$ {verification command from plan} (output)

### 최종 검증

$ {final verification command from plan} (output)

Sections and their ownership:

섹션	소유자	설명
헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시	스텁 생성 시 고정	구현 에이전트가 수정하지 않음
구현 항목별 완료 여부 (항목명)	스텁 생성 시 고정	[ ] → [x] 체크만 구현 에이전트가 수행
계획 대비 변경 사항, 주요 설계 결정	구현 에이전트가 채움	placeholder 텍스트를 실제 내용으로 교체
리뷰어를 위한 체크포인트	스텁 생성 시 고정	계획에서 추출한 리뷰 포인트
검증 결과 (섹션 제목 + 명령)	스텁 생성 시 고정	실행 출력만 구현 에이전트가 채움
코드리뷰 결과	리뷰 에이전트가 append	스텁에 포함하지 않음

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.md and CODE_REVIEW.md both exist under agent-task/{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.
• CODE_REVIEW.md completion table lists every plan item.