agentic-framework/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.

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, 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.

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.
• 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)
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	List paths and ask which task to use

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.

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.
• 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
• 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 CODE_REVIEW-*-G??.md is a mandatory final step — the task is NOT complete until every section of that file is filled. Tell the implementer to complete checklists, run intermediate/final verification, and fill every CODE_REVIEW-*-G??.md section 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 — those instructions (renaming to *.log, writing complete.log) 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 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.
• 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.

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 section below is filled in.
> 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. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log` (N = 기존 code_review_*.log 수)
2. `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log` (M = 기존 plan_*.log 수)
3. PASS인 경우 `complete.log` 작성 후 종료. WARN/FAIL인 경우 새 routed plan + review 스텁 작성.

---

## 구현 항목별 완료 여부

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

## 계획 대비 변경 사항

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

## 주요 설계 결정

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

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

{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 section: completion table, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.

Sections and their ownership:

Section	Owner	Note
Header comment, 개요, 리뷰 에이전트 지시	Fixed at stub creation	Implementing agent must not modify or execute these (archive + complete.log are review-agent only)
구현 항목별 완료 여부 (item names)	Fixed at stub creation	Implementing agent checks [ ] → [x] only
계획 대비 변경 사항, 주요 설계 결정	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}/.
• 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.
• Routed review file completion table lists every plan item.