toki/agentic-framework
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sync: from go-iop v1.1.8

Browse source
This commit is contained in:
toki 2026-05-05 11:13:29 +09:00
parent 14976fc9f1
commit dd776ccd5d
3 changed files with 116 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
agent-ops/.version
View file

@ -1 +1 @@
1.1.7
1.1.8

51
agent-ops/skills/common/code-review/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: code-review
description: Review completed implementation work in the current repository. Reads PLAN.md and CODE_REVIEW.md from the active task, reviews the actual changed source files, appends a verdict to CODE_REVIEW.md, then archives both files as .log. On PASS, writes complete.log summarising the full loop history. If Required or Suggested issues are found (FAIL or WARN), writes a new PLAN.md and CODE_REVIEW.md stub so the loop continues immediately. Nit-only findings may still PASS.
description: Review completed implementation work in the current repository. Reads PLAN-{build_lane}-GNN.md and CODE_REVIEW-{review_lane}-GNN.md from the active task, reviews the actual changed source files, appends a verdict to the review file, then archives both files as .log. On PASS, writes complete.log summarising the full loop history. If Required or Suggested issues are found (FAIL or WARN), writes new routed plan/review files so the loop continues immediately. Nit-only findings may still PASS.
---
# Code Review
@ -12,18 +12,30 @@ Review the implementation phase of the plan-code-review loop:
```text
plan skill -> implementation -> code-review skill
^ |
+----- issues found: new PLAN.md
+----- issues found: new routed plan/review files
```
## Workflow Contract
Active work must live at `agent-task/{task_name}/PLAN.md` and `agent-task/{task_name}/CODE_REVIEW.md`. These paths are the state protocol shared with the plan skill. Do not adapt them per repository unless the whole loop contract is intentionally changed in both skills.
Active work must live under `agent-task/{task_name}/` using routed filenames. This is the state protocol shared with the plan skill.
Filename rules:
- Plan file: `PLAN-{build_lane}-GNN.md`
- Review file: `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`; runtime maps lane+grade to current models externally.
Review routing rules:
- `local`: narrow, low-risk, or first-pass review where tests and scope are clear.
- `cloud`: multi-file, API/call-site impact, meaningful test judgment, plan deviation, weak verification, security/auth, storage/migration, concurrency, protocol/schema, cross-domain, or repeated Required issues.
Directory states:
| State | Meaning |
|-------|---------|
| `PLAN.md` + `CODE_REVIEW.md` | Ready for review |
| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` | Ready for review |
| `complete.log` + `*.log` files | Task complete (PASS) |
| Only `*.log` files (no `complete.log`) | Task terminated mid-loop or abandoned |
@ -31,11 +43,11 @@ The implementing agent never archives or deletes active files; archiving is this
## Step 1 - Find Active Task
Glob `agent-task/*/CODE_REVIEW.md`:
Glob `agent-task/*/CODE_REVIEW-*-G??.md`:
| Result | Action |
|--------|--------|
| Exactly one | Review that task; `PLAN.md` is expected beside it |
| Exactly one | Review that task; exactly one `PLAN-*-G??.md` is expected beside it |
| None | Nothing to review; stop and report |
| Multiple | List paths and ask which task to review |
@ -43,7 +55,7 @@ Glob `agent-task/*/CODE_REVIEW.md`:
Count `agent-task/{task_name}/code_review_*.log`:
- `0`: first review. Read `CODE_REVIEW.md`, `PLAN.md`, every planned source file, related tests, and files importing/imported by changed files up to 2 levels deep.
- `0`: first review. Read the active review file, active plan file, every planned source file, related tests, and files importing/imported by changed files up to 2 levels deep.
- `>=1`: follow-up review. Start with `git diff`, `git diff --cached`, and `git log --oneline -5`, then expand to related callers, implementers, tests, and any planned files missing from the diff.
The diff is the starting point, not the boundary. Follow behavior and API connections far enough to judge correctness.
@ -55,12 +67,12 @@ Before writing the verdict:
- Compare actual source files against every planned checklist item.
- Grep renamed/removed symbols for stale references.
- Confirm every required test exists, name matches, and assertions are meaningful.
- Cross-check claimed verification output in `CODE_REVIEW.md` against actual code and project commands.
- Cross-check claimed verification output in the active review file against actual code and project commands.
- For follow-up reviews, compare diff against the plan and scan for unplanned changes, debug prints, dead code, TODOs, formatting-only noise, and unrelated edits.
## Step 4 - Append Verdict
Append `코드리뷰 결과` to `CODE_REVIEW.md`.
Append `코드리뷰 결과` to the active `CODE_REVIEW-*-G??.md`.
Required fields:
@ -87,8 +99,8 @@ Issue severity:
Archive order is fixed:
1. Count existing `code_review_*.log` as `N`; rename `CODE_REVIEW.md` to `code_review_N.log`.
2. Count existing `plan_*.log` as `M`; rename `PLAN.md` to `plan_M.log`.
1. Count existing `code_review_*.log` as `N`; rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_N.log`.
2. Count existing `plan_*.log` as `M`; rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_M.log`.
After archiving, neither active `.md` file remains unless Step 6 writes a follow-up.
@ -109,15 +121,16 @@ Then report:
- Archive filenames.
- `complete.log` written; task complete.
For `WARN` or `FAIL`, write a new `PLAN.md` and `CODE_REVIEW.md` stub using the plan skill format:
For `WARN` or `FAIL`, write new routed plan/review files using the plan skill format:
- New plan number is the count of `plan_*.log` after archive.
- Header tag is `REVIEW_<PARENT_TAG>`.
- Choose lane/grade again; preserve the prior route only when it was adequate, otherwise raise `GNN` and/or move `local -> cloud`.
- `FAIL`: one plan item per Required issue.
- `WARN`: one grouped plan item for Suggested issues, plus related Nit issues if useful.
- Each plan item needs problem, solution with before/after when non-trivial, checklist, test decision, intermediate verification.
`CODE_REVIEW.md` stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent):
Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent):
```markdown
<!-- task={task_name} plan={N} tag={TAG} -->
@ -134,9 +147,9 @@ 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` 스텁 작성.
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 스텁 작성.
---
@ -211,8 +224,8 @@ Report Required/Suggested counts, archive names, and the new plan path.
## Final Checklist
- `code_review_N.log` exists with verdict appended.
- `plan_M.log` exists.
- `code_review_{review_lane}_GNN_N.log` exists with verdict appended.
- `plan_{build_lane}_GNN_M.log` exists.
- No active `.md` files remain after PASS.
- PASS: `complete.log` written with loop history, implementation summary, and residual Nits.
- WARN/FAIL: new active `PLAN.md` and `CODE_REVIEW.md` created with matching headers; no `complete.log`.
- WARN/FAIL: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers; no `complete.log`.

121
agent-ops/skills/common/plan/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: plan
description: 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.
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. 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
@ -10,22 +10,37 @@ description: Analyze the current repository and write a detailed PLAN.md for imp
Create the planning artifacts for the implementation loop:
```text
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
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 `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.
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.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 |
| `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 |
@ -33,7 +48,7 @@ Directory states:
If the user names the task explicitly, use that task name.
Otherwise, glob `agent-task/*/PLAN.md`:
Otherwise, glob `agent-task/*/PLAN-*-G??.md`:
| Result | Action |
|--------|--------|
@ -41,32 +56,46 @@ Otherwise, glob `agent-task/*/PLAN.md`:
| 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.
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 these before creating files:
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 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.
- [ ] **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.
## Step 3 - Archive Existing Active Files
## 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.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`.
- 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 4 - Write PLAN.md
## Step 5 - Write Plan File
Header line must be exactly:
@ -77,11 +106,17 @@ Header line must be exactly:
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.
- `이 파일을 읽는 구현 에이전트에게`: 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.
- `최종 검증`: runnable commands and expected outcome. The final line of this section must read exactly — **"모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 전체 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."**
Each plan item must include:
@ -101,6 +136,7 @@ Quality rules:
- 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:
@ -112,7 +148,7 @@ Test policy:
| Internal refactor | Existing tests may be enough |
| Concurrency logic | Race/ordering test recommended |
## Step 5 - Write CODE_REVIEW.md Stub
## 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.
@ -121,6 +157,10 @@ Use the template below exactly. Fill `{…}` placeholders from the plan; everyth
# 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}
@ -131,9 +171,9 @@ 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` 스텁 작성.
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 스텁 작성.
---
@ -171,18 +211,23 @@ $ {verification command from plan}
$ {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:
| 섹션 | 소유자 | 설명 |
|------|--------|------|
| 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음 |
| 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 |
| 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 |
| 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 |
| 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움 |
| 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 |
| 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 |
| 코드리뷰 결과 | Review agent appends | Not included in stub |
## Naming
@ -195,8 +240,8 @@ Sections and their ownership:
## Final Checklist
- `PLAN.md` and `CODE_REVIEW.md` both exist under `agent-task/{task_name}/`.
- `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.
- `CODE_REVIEW.md` completion table lists every plan item.
- Routed review file completion table lists every plan item.