From 6bc218d8597a1c0414637db950390637f06334c3 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 17 May 2026 18:06:46 +0900 Subject: [PATCH] sync: from go-iop v1.1.12 --- agent-ops/.version | 2 +- agent-ops/bin/init-agent-ops.sh | 58 ++++++++++- agent-ops/rules/common/rules.md | 1 + agent-ops/skills/common/code-review/SKILL.md | 98 +++++++++++++++++-- .../skills/common/init-agent-ops/SKILL.md | 33 +++++-- agent-ops/skills/common/plan/SKILL.md | 62 ++++++++++-- 6 files changed, 227 insertions(+), 27 deletions(-) diff --git a/agent-ops/.version b/agent-ops/.version index 9ee1f78..ccad953 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.11 +1.1.12 diff --git a/agent-ops/bin/init-agent-ops.sh b/agent-ops/bin/init-agent-ops.sh index 3e473b5..d66e2ab 100755 --- a/agent-ops/bin/init-agent-ops.sh +++ b/agent-ops/bin/init-agent-ops.sh @@ -12,6 +12,17 @@ fi TARGET_DIR=$(realpath "$1") SOURCE_DIR=$(realpath "$(dirname "$0")/..") +ARCHIVE_IGNORE_PATTERN="agent-task/archive/**" + +append_unique_line() { + local file="$1" + local line="$2" + + touch "$file" + if ! grep -qxF "$line" "$file"; then + printf "%s\n" "$line" >> "$file" + fi +} echo "Initializing agent-ops in: $TARGET_DIR" echo "Source agent-ops: $SOURCE_DIR" @@ -34,7 +45,52 @@ cp "$COMMON_RULES" "$TARGET_DIR/AGENTS.md" cp "$COMMON_RULES" "$TARGET_DIR/.cursorrules" cp "$COMMON_RULES" "$TARGET_DIR/.clinerules" -# 4. .gitignore 설정 +# 4. AI ignore / permission 설정 +append_unique_line "$TARGET_DIR/.geminiignore" "$ARCHIVE_IGNORE_PATTERN" +append_unique_line "$TARGET_DIR/.aiexclude" "$ARCHIVE_IGNORE_PATTERN" +append_unique_line "$TARGET_DIR/.cursorignore" "$ARCHIVE_IGNORE_PATTERN" +append_unique_line "$TARGET_DIR/.clineignore" "$ARCHIVE_IGNORE_PATTERN" + +mkdir -p "$TARGET_DIR/.claude" +if [ ! -f "$TARGET_DIR/.claude/settings.json" ]; then + cat > "$TARGET_DIR/.claude/settings.json" <<'EOF' +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "deny": [ + "Read(./agent-task/archive/**)" + ] + } +} +EOF +elif ! grep -q "agent-task/archive" "$TARGET_DIR/.claude/settings.json"; then + echo "Note: .claude/settings.json exists; add Read(./agent-task/archive/**) manually." +fi + +if [ ! -f "$TARGET_DIR/opencode.json" ]; then + cat > "$TARGET_DIR/opencode.json" <<'EOF' +{ + "$schema": "https://opencode.ai/config.json", + "permission": { + "read": { + "agent-task/archive/**": "deny" + }, + "glob": { + "agent-task/archive/**": "deny" + } + }, + "watcher": { + "ignore": [ + "agent-task/archive/**" + ] + } +} +EOF +elif ! grep -q "agent-task/archive" "$TARGET_DIR/opencode.json"; then + echo "Note: opencode.json exists; add agent-task/archive/** read/glob deny and watcher ignore manually." +fi + +# 5. .gitignore 설정 TOUCH_GITIGNORE="$TARGET_DIR/.gitignore" touch "$TOUCH_GITIGNORE" if ! grep -q "agent-ops/rules/private/" "$TOUCH_GITIGNORE"; then diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 9bf989d..ae124ac 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -4,6 +4,7 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. `agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index 968e2f4..b00e88a 100644 --- a/agent-ops/skills/common/code-review/SKILL.md +++ b/agent-ops/skills/common/code-review/SKILL.md @@ -26,21 +26,39 @@ Filename rules: - `{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. +Multi-plan runtime contract: + +- Multi-plan work is represented as multiple task directories. Each directory owns exactly one normal active plan file and one normal active review file. +- Directory names may encode runtime scheduling metadata. Preserve them verbatim; do not normalize, reinterpret, or choose execution order by agent judgment. +- If the user/runtime names a task directory, review that directory even when other active review files exist. + 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. +- `cloud-G07` or higher is mandatory for terminal-agent follow-up 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. +- `cloud-G07` or higher is mandatory for follow-up plans when a local implementation failed a real bin/smoke/integration command after unit tests passed, when the success condition depends on an interactive TUI/PTY/browser/external CLI or screen repaint/cursor stream, or when verification trust is Fail because recorded stdout/stderr does not match a rerun. Directory states: | State | Meaning | |-------|---------| -| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` | Ready for review | +| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub or placeholders | Implementation is pending/incomplete; review should fail completeness if invoked | +| `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 | The implementing agent never archives or deletes active files; archiving is this skill's responsibility. +Finalization invariant: + +- Every review attempt that selects an active review file must end by archiving the active `CODE_REVIEW-*-G??.md` and `PLAN-*-G??.md` files. +- After archiving, exactly one next state is allowed: + - `PASS`: write `complete.log` and leave no active `.md` files. + - `WARN` or `FAIL`: write the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`; do not write `complete.log`. +- Never stop after appending a verdict. Do not report to the user until archive and the required next-state file writes are complete. +- If the review result feels ambiguous, choose `WARN` or `FAIL` according to the severity rules, archive the current files, and write the next plan/review pair. Ambiguity is not a reason to leave active files unarchived. + ## Step 1 - Find Active Task Glob `agent-task/*/CODE_REVIEW-*-G??.md`: @@ -49,7 +67,7 @@ Glob `agent-task/*/CODE_REVIEW-*-G??.md`: |--------|--------| | 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 | +| Multiple | If the user/runtime named a task directory, review that directory. Otherwise list paths and ask which task to review; do not choose by agent judgment. | ## Step 2 - Load Context @@ -65,6 +83,9 @@ The diff is the starting point, not the boundary. Follow behavior and API connec Before writing the verdict: - Compare actual source files against every planned checklist item. +- Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`; item text/order must match. +- Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item. +- Treat blank placeholder sections, missing actual implementation notes, missing checklist completion, or missing actual stdout/stderr in the active review file as a completeness or verification-trust failure. - Grep renamed/removed symbols for stale references. - Confirm every required test exists, name matches, and assertions are meaningful. - Cross-check claimed verification output in the active review file against actual code and project commands. @@ -81,6 +102,8 @@ Required fields: - `발견된 문제`: `없음`, or bullets using `Required`, `Suggested`, or `Nit` with `file:line` and a concrete fix. - `다음 단계`: keep only the matching PASS/WARN/FAIL line. +Do not check archive/next-state items in `코드리뷰 전용 체크리스트` during Step 4. Complete that dedicated checklist in the archived `code_review_*.log` during Step 7, after archive and next-state writes are done. + Severity semantics: | Verdict | Meaning | Follow-up plan | @@ -91,13 +114,19 @@ Severity semantics: Issue severity: -- `Required`: correctness, API contract, missing required test, or plan-completeness issue. +- `Required`: correctness, API contract, missing required test, plan-completeness issue, or incomplete/placeholder `CODE_REVIEW-*-G??.md` content required from the implementing agent. - `Suggested`: useful improvement that should enter the loop but does not block correctness. - `Nit`: tiny cleanup; may be recorded without forcing WARN. +Verdict consistency: + +- `PASS` requires all dimensions to be Pass and no Required/Suggested issues. Nit-only findings may still PASS only when every dimension remains Pass. +- Any Fail dimension or any Required issue forces `FAIL`. +- Any Warn dimension or any Suggested issue forces `WARN`, unless the only findings are explicitly Nit and every dimension remains Pass. + ## Step 5 - Archive Active Files -Archive order is fixed: +Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Archive order is fixed: 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`. @@ -115,7 +144,7 @@ Required fields in `complete.log`: - `최종 리뷰 요약`: bullet list of what was implemented. - `잔여 Nit`: any Nit-only findings recorded but not acted on (omit section if none). -Then report: +After Step 7, report: - Verdict. - Archive filenames. @@ -126,9 +155,16 @@ For `WARN` or `FAIL`, write new routed plan/review files using the plan skill fo - New plan number is the count of `plan_*.log` after archive. - Header tag is `REVIEW_`. - Choose lane/grade again; preserve the prior route only when it was adequate, otherwise raise `GNN` and/or move `local -> cloud`. +- Before choosing the follow-up route, apply this escalation gate: + - If the archived plan was `local-*` and the verdict is `FAIL` for correctness, completeness, test coverage, or verification trust, move the follow-up build lane to `cloud` unless the issue is trivially deterministic and review-detectable without live environment behavior. + - If the follow-up work is 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), use `cloud-G07` or higher. + - If unit tests passed but a real bin/smoke/integration command failed, use `cloud-G07` or higher. + - If the task depends on interactive TUI/PTY/browser/external CLI behavior, screen repaint/cursor stream parsing, or live command-palette state, use `cloud-G07` or higher. + - If recorded verification output was reconstructed, stale, or mismatched on rerun, use `cloud-G07` or higher and make verification trust recovery a plan item. - `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. +- The follow-up plan and review stub must contain matching `구현 체크리스트` item text/order, including the final mandatory `CODE_REVIEW-*-G??.md` completion item. Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent): @@ -137,6 +173,12 @@ Routed review stub template (fill `{…}` placeholders; everything else is fixed # 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} @@ -145,12 +187,15 @@ task={task_name}, plan={N}, tag={TAG} ## 이 파일을 읽는 리뷰 에이전트에게 각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료 후 반드시 아래 순서로 아카이브하세요. +Review 완료 후 반드시 아래 순서로 아카이브하세요. 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 스텁 작성. +어떤 판정에서도 아카이브를 건너뛰지 마세요. PASS/WARN/FAIL 모두 `코드리뷰 결과` append 후 active plan/review 파일을 먼저 아카이브하고, 그 다음 `complete.log` 또는 다음 plan/review 파일을 작성해야 합니다. +Archive와 다음 상태 파일 작성이 끝난 뒤, archived `code_review_*.log`의 `코드리뷰 전용 체크리스트`를 모두 체크한 다음 보고하세요. + --- ## 구현 항목별 완료 여부 @@ -160,6 +205,22 @@ task={task_name}, plan={N}, tag={TAG} | [{TAG}-1] {item description} | [ ] | | [{TAG}-2] {item description} | [ ] | +## 구현 체크리스트 + +{copy the follow-up 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이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. + ## 계획 대비 변경 사항 _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ @@ -192,6 +253,12 @@ $ {verification command from plan} $ {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: @@ -200,19 +267,31 @@ Sections and their ownership: |------|--------|------| | 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음 | | 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 | +| 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 | +| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | | 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 | | 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 | | 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움; 명령 변경은 `계획 대비 변경 사항`에 기록 | | 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 | -Report Required/Suggested counts, archive names, and the new plan path. +## Step 7 - Complete Review-Only Checklist And Report + +After Step 6: + +- Open the archived `code_review_{review_lane}_GNN_N.log`. +- Check every item in `코드리뷰 전용 체크리스트`. +- If any item cannot be checked, finish the missing archive, `complete.log`, or follow-up plan/review write first. +- Do not recreate an active review file just to update this checklist; update the archived `code_review_*.log`. +- Only report after the archived review log has the verdict, checked review-only checklist, and the required next-state files. + +Report Required/Suggested counts, archive names, and the `complete.log` path or new plan path. ## Review Dimensions | Dimension | Check | |-----------|-------| | Correctness | Logic, edge cases, concurrency, errors | -| Completeness | All planned checklist items done | +| Completeness | All planned checklist items done, including matching plan/review `구현 체크리스트` completion | | Test coverage | Required tests present and meaningful | | API contract | Call sites, compatibility, docs | | Code quality | No debug prints, dead code, leftover TODOs | @@ -234,4 +313,5 @@ Report Required/Suggested counts, archive names, and the new plan path. - `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-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.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 and matching `구현 체크리스트`; no `complete.log`. +- The review-agent-only finalization checklist was completed before reporting. diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md index 507c29c..83866f1 100644 --- a/agent-ops/skills/common/init-agent-ops/SKILL.md +++ b/agent-ops/skills/common/init-agent-ops/SKILL.md @@ -1,6 +1,6 @@ --- name: init-agent-ops -version: 1.1.0 +version: 1.1.1 description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드를 생성하기 위한 초기 규칙 --- @@ -12,10 +12,11 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 현재 프로젝트 상태를 분석하여 다음을 세팅한다. 1. 에이전트 진입 파일 -2. agent-ops 기본 폴더 구조 -3. rules/project/rules.md (프로젝트 특화 규칙, 분석 후 생성) -4. 초기 domain rule 초안 -5. 초기 skill (필요 시) +2. AI ignore / permission 기본 설정 +3. agent-ops 기본 폴더 구조 +4. rules/project/rules.md (프로젝트 특화 규칙, 분석 후 생성) +5. 초기 domain rule 초안 +6. 초기 skill (필요 시) "현재 프로젝트에 맞는 최소 스캐폴드" 생성을 우선한다. @@ -34,6 +35,7 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 - [ ] 프로젝트 루트에 기존 agent-ops 관련 파일(`CLAUDE.md`, `agent-ops/` 등)이 있는지 확인 - [ ] `.agent-ops-source` 파일이 있는지 확인 (공통 관리 레포 여부) - [ ] 기존 진입 파일(`CLAUDE.md`, `GEMINI.md` 등)이 있는지 확인 +- [ ] 기존 AI ignore / permission 파일(`.geminiignore`, `.aiexclude`, `.claude/settings.json`, `opencode.json` 등)이 있는지 확인 ## 핵심 원칙 @@ -68,6 +70,8 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 | `agent-ops/rules/project/domain//rules.md` | 도메인 분석 후 생성 | | `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) | | `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 | +| `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore` | `agent-task/archive/**` 한 줄 추가 | +| `.claude/settings.json`, `opencode.json` | 파일이 없으면 `agent-task/archive/**` 읽기/검색 제외 설정 생성, 있으면 덮어쓰지 않고 수동 병합 안내 | 에이전트별 파일명: @@ -166,23 +170,28 @@ common/rules.md와 내용이 중복되지 않도록 한다. - `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사한다 - 복사 후 `rules/common/rules.md`를 삭제한다 -3. **agent-ops 폴더 구조 복사** +3. **AI ignore / permission 기본 설정** + - `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`를 추가한다 + - `.claude/settings.json`, `opencode.json`이 없으면 archive 읽기/검색 제외 설정을 생성한다 + - `agent-task/archive/**` 제외는 `.gitignore`에 추가하지 않는다 + +4. **agent-ops 폴더 구조 복사** - 공통 관리 레포의 `agent-ops/` 공통 폴더(rules/common, skills/common)를 복사한다 - `agent-ops/.version` 파일을 복사한다 -4. **rules/project/rules.md 생성** +5. **rules/project/rules.md 생성** - 프로젝트를 분석하여 응답 언어, 프로젝트 개요, 기술 스택 등을 채운다 - common/rules.md와 내용이 중복되지 않도록 한다 -5. **도메인 분석 및 domain rule 생성** +6. **도메인 분석 및 domain rule 생성** - 신규 프로젝트: 핵심 domain placeholder 2~4개만 제안한다. domain rules를 과도하게 채우지 않는다 - 운영중 프로젝트: Core/Supporting/Generic 도메인을 식별하고 실제 경로를 반영한 초안을 생성한다 -6. **초기 skill 제안** +7. **초기 skill 제안** - 신규 프로젝트: 최소 2개만 제안한다 - 운영중 프로젝트: 반복 작업 기반으로 필요한 skill을 제안한다 -7. **결과 보고** +8. **결과 보고** - 상태 판별 결과, 생성된 파일 목록, 도메인 제안, skill 제안, 주의사항을 출력한다 ## 출력 형식 @@ -217,11 +226,15 @@ common/rules.md와 내용이 중복되지 않도록 한다. - [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가 - [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가 - [ ] `.gitignore`에 `agent-ops/rules/private/` 항목이 추가되어 있는가 +- [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 `agent-task/archive/**`가 포함되어 있는가 +- [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` 제외 설정이 있거나, 기존 파일 수동 병합 안내를 출력했는가 +- [ ] `.gitignore`에 `agent-task/archive/**`를 추가하지 않았는가 - 검증 실패 시: 누락된 파일/항목을 사용자에게 알리고 해당 부분만 보완한다 ## 금지 사항 - 진입 파일에 rules/common/rules.md 외 내용을 추가하지 않는다. +- `agent-task/archive/**` 제외를 `.gitignore`에 추가하지 않는다. - 실제 구조보다 앞선 추상 구조를 강요하지 않는다. - 처음부터 많은 domain / skill을 만들지 않는다. - rules/common/rules.md를 프로젝트에서 직접 수정하지 않는다. diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 87783bd..8020fc6 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -26,10 +26,24 @@ Filename rules: - `{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. +- If one plan is not enough, split the work 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 an execution-order index: `01_{task_name}`, `02_{task_name}`, `03_{task_name}`, and so on. +- If a later task cannot start until a specific current task is complete, mark that dependency immediately after the current task's index with `+`, not `_`: `01+{dependent_task_name}` means this task depends on completion of the `01_...` task. +- When multiple dependent tasks share the same predecessor, order them after the dependency marker: `01+01_{task_name}`, `01+02_{task_name}`. +- Directory names are runtime scheduling metadata. Preserve them verbatim; do not normalize, reinterpret, or choose execution order by agent judgment. +- Every split plan must include `의존 관계 및 구현 순서` and list predecessor task directories that must reach `complete.log` before implementation begins. + 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. @@ -54,12 +68,14 @@ Otherwise, glob `agent-task/*/PLAN-*-G??.md`: |--------|--------| | 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 | +| 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`. +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. @@ -85,6 +101,10 @@ GXX is an output of analysis, not an input. Determine lane and grade only after - 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 @@ -107,7 +127,7 @@ Header line must be exactly: 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. +- `이 파일을 읽는 구현 에이전트에게`: 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. @@ -115,9 +135,10 @@ Required sections: - `심볼 참조`: 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. +- `구현 체크리스트`: 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`의 전체 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."** +- `최종 검증`: 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: @@ -129,6 +150,8 @@ Each plan item must include: Include `의존 관계 및 구현 순서` only when order matters. +For split multi-plan work, `의존 관계 및 구현 순서` is mandatory in every generated plan. If a plan has a `NN+...` directory name, state which `NN_...` predecessor must produce `complete.log` before implementation starts. + Quality rules: - Exact line numbers in every Before snippet. @@ -170,7 +193,9 @@ 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. +> 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. ## 개요 @@ -181,12 +206,15 @@ task={task_name}, plan={N}, tag={TAG} ## 이 파일을 읽는 리뷰 에이전트에게 각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료 후 반드시 아래 순서로 아카이브하세요. +review 완료 후 반드시 아래 순서로 아카이브하세요. 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 스텁 작성. +어떤 판정에서도 아카이브를 건너뛰지 마세요. PASS/WARN/FAIL 모두 `코드리뷰 결과` append 후 active plan/review 파일을 먼저 아카이브하고, 그 다음 `complete.log` 또는 다음 plan/review 파일을 작성해야 합니다. +archive와 다음 상태 파일 작성이 끝난 뒤, archived `code_review_*.log`의 `코드리뷰 전용 체크리스트`를 모두 체크한 다음 보고하세요. + --- ## 구현 항목별 완료 여부 @@ -196,6 +224,22 @@ task={task_name}, plan={N}, tag={TAG} | [{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이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. + ## 계획 대비 변경 사항 _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ @@ -231,8 +275,9 @@ $ {final verification command from plan} --- -> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every section: completion table, changes from plan, design decisions, and verification 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: @@ -241,6 +286,8 @@ Sections and their ownership: |---------|-------|------| | 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 | +| 구현 체크리스트 (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 | @@ -258,7 +305,10 @@ Sections and their ownership: ## 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 `01_...`, `02_...`, or dependency-marked `NN+...` names. - Both first lines match ``. - 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.