From 21037225e362eb2acffba4ec9df0fb00744003e9 Mon Sep 17 00:00:00 2001 From: toki Date: Tue, 19 May 2026 09:54:21 +0900 Subject: [PATCH] update agent-ops configs and skills --- .clinerules | 16 ++ .cursorrules | 10 +- AGENTS.md | 10 +- CLAUDE.md | 10 +- GEMINI.md | 10 +- agent-ops/.version | 2 +- agent-ops/bin/entry-files.sh | 24 +++ agent-ops/bin/init-agent-ops.sh | 104 +++++++++ agent-ops/bin/sync.sh | 38 +--- agent-ops/skills/common/code-review/SKILL.md | 180 ++++++++++++---- .../templates/complete-log-template.md | 31 +++ .../skills/common/create-domain-rule/SKILL.md | 17 +- .../skills/common/init-agent-ops/SKILL.md | 55 +++-- agent-ops/skills/common/plan/SKILL.md | 197 ++++++++++++++---- agent-ops/skills/common/sync-pull/SKILL.md | 2 +- agent-ops/skills/common/sync-push/SKILL.md | 21 +- 16 files changed, 574 insertions(+), 153 deletions(-) create mode 100644 .clinerules create mode 100644 agent-ops/bin/entry-files.sh create mode 100755 agent-ops/bin/init-agent-ops.sh create mode 100644 agent-ops/skills/common/code-review/templates/complete-log-template.md diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..ae124ac --- /dev/null +++ b/.clinerules @@ -0,0 +1,16 @@ +# 공통 규칙 + +- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다. +- 코드 변경 전 관련 domain rule을 먼저 확인한다. +- 요청 범위를 넘는 변경을 하지 않는다. +- 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. + +`agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. + +아래 성격의 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 작업 최초 1회 읽고 수행한다. 자동으로 수행하지 않는다. +- agent-ops 초기화 +- domain rule 생성 +- skill 생성 +- git commit / push +- agent-ops 업데이트 / 진입 파일 재적용 diff --git a/.cursorrules b/.cursorrules index 6648b75..ae124ac 100644 --- a/.cursorrules +++ b/.cursorrules @@ -4,13 +4,13 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. -아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +`agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. + +아래 성격의 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 작업 최초 1회 읽고 수행한다. 자동으로 수행하지 않는다. - agent-ops 초기화 - domain rule 생성 - skill 생성 -- git commit / git push +- git commit / push - agent-ops 업데이트 / 진입 파일 재적용 - -`agent-ops/rules/project/rules.md`와 -`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/AGENTS.md b/AGENTS.md index 6648b75..ae124ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,13 +4,13 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. -아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +`agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. + +아래 성격의 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 작업 최초 1회 읽고 수행한다. 자동으로 수행하지 않는다. - agent-ops 초기화 - domain rule 생성 - skill 생성 -- git commit / git push +- git commit / push - agent-ops 업데이트 / 진입 파일 재적용 - -`agent-ops/rules/project/rules.md`와 -`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/CLAUDE.md b/CLAUDE.md index 6648b75..ae124ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,13 +4,13 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. -아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +`agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. + +아래 성격의 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 작업 최초 1회 읽고 수행한다. 자동으로 수행하지 않는다. - agent-ops 초기화 - domain rule 생성 - skill 생성 -- git commit / git push +- git commit / push - agent-ops 업데이트 / 진입 파일 재적용 - -`agent-ops/rules/project/rules.md`와 -`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/GEMINI.md b/GEMINI.md index 6648b75..ae124ac 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -4,13 +4,13 @@ - 코드 변경 전 관련 domain rule을 먼저 확인한다. - 요청 범위를 넘는 변경을 하지 않는다. - 불확실하면 단정하지 말고 후보를 제시한다. +- `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. -아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다. +`agent-ops/rules/project/rules.md`와 `agent-ops/rules/private/rules.md`는 세션 최초 1회 읽는다. 파일이 없으면 무시한다. + +아래 성격의 요청은 사용자가 명시적으로 요청한 경우에만 `agent-ops/skills/common/router.md`를 작업 최초 1회 읽고 수행한다. 자동으로 수행하지 않는다. - agent-ops 초기화 - domain rule 생성 - skill 생성 -- git commit / git push +- git commit / push - agent-ops 업데이트 / 진입 파일 재적용 - -`agent-ops/rules/project/rules.md`와 -`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다. diff --git a/agent-ops/.version b/agent-ops/.version index 2bf1ca5..e9bc149 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.7 +1.1.14 diff --git a/agent-ops/bin/entry-files.sh b/agent-ops/bin/entry-files.sh new file mode 100644 index 0000000..dfb6f90 --- /dev/null +++ b/agent-ops/bin/entry-files.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash + +# Shared entry-point file list for init/sync scripts. +AGENT_OPS_ENTRY_FILES=("GEMINI.md" "CLAUDE.md" "AGENTS.md" ".cursorrules" ".clinerules") + +apply_agent_ops_entry_files() { + local rules_md="$1" + local target_root="$2" + + if [[ ! -f "$rules_md" ]]; then + if [[ -n "${YELLOW:-}" && -n "${RESET:-}" ]]; then + echo -e "${YELLOW} rules.md 없음, 진입 파일 재적용 건너뜀${RESET}" + else + echo " rules.md 없음, 진입 파일 재적용 건너뜀" + fi + return + fi + + local f + for f in "${AGENT_OPS_ENTRY_FILES[@]}"; do + cp "$rules_md" "$target_root/$f" + echo " 진입 파일 적용: $f" + done +} diff --git a/agent-ops/bin/init-agent-ops.sh b/agent-ops/bin/init-agent-ops.sh new file mode 100755 index 0000000..449c410 --- /dev/null +++ b/agent-ops/bin/init-agent-ops.sh @@ -0,0 +1,104 @@ +#!/bin/bash + +# agent-ops/bin/init-agent-ops.sh +# 프로젝트에 agent-ops 스캐폴드를 초기화하는 스크립트 + +set -e + +SCRIPT_DIR=$(realpath "$(dirname "$0")") +SOURCE_DIR=$(realpath "$SCRIPT_DIR/..") +source "$SCRIPT_DIR/entry-files.sh" + +if [ -z "$1" ]; then + echo "Usage: $0 " + exit 1 +fi + +TARGET_DIR=$(realpath "$1") +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" + +# 1. 대상 폴더 생성 +mkdir -p "$TARGET_DIR/agent-ops/rules/project/domain" +mkdir -p "$TARGET_DIR/agent-ops/rules/private" +mkdir -p "$TARGET_DIR/agent-ops/skills/project" + +# 2. 공통 요소 복사 (프로젝트 전용 설정은 제외) +cp "$SOURCE_DIR/.version" "$TARGET_DIR/agent-ops/" +rm -rf "$TARGET_DIR/agent-ops/bin" +cp -r "$SOURCE_DIR/bin" "$TARGET_DIR/agent-ops/" +cp -r "$SOURCE_DIR/rules/common" "$TARGET_DIR/agent-ops/rules/" +cp -r "$SOURCE_DIR/skills/common" "$TARGET_DIR/agent-ops/skills/" + +# 3. 에이전트 진입 파일 생성 (common/rules.md 복사) +COMMON_RULES="$SOURCE_DIR/rules/common/rules.md" +apply_agent_ops_entry_files "$COMMON_RULES" "$TARGET_DIR" + +# 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 + echo "" >> "$TOUCH_GITIGNORE" + echo "# Agent-Ops Private Rules" >> "$TOUCH_GITIGNORE" + echo "agent-ops/rules/private/" >> "$TOUCH_GITIGNORE" +fi + +echo "Successfully initialized agent-ops in $TARGET_DIR" +echo "Note: agent-ops/rules/project and agent-ops/skills/project are initialized as empty." diff --git a/agent-ops/bin/sync.sh b/agent-ops/bin/sync.sh index d65e10e..632853d 100755 --- a/agent-ops/bin/sync.sh +++ b/agent-ops/bin/sync.sh @@ -9,6 +9,9 @@ PROJECT_ROOT="$(cd "$AGENT_OPS_DIR/.." && pwd)" # ── 색상 ───────────────────────────────────────────────────────────────────── RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; RESET='\033[0m' +# ── 진입 파일 공통 관리 ────────────────────────────────────────────────────── +source "$SCRIPT_DIR/entry-files.sh" + # ── 대상 경로 해석 (폴더명 / 상대경로 / 절대경로) ──────────────────────────── resolve_target() { local input="$1" @@ -68,34 +71,6 @@ sync_common() { sync_folder "$src/bin" "$dst/bin" } -# ── rules.md 내용을 진입 파일들에 반영 ─────────────────────────────────────── -apply_entry_files() { - local rules_md="$1" - local target_root="$2" - - if [[ ! -f "$rules_md" ]]; then - echo -e "${YELLOW} rules.md 없음, 진입 파일 재적용 건너뜀${RESET}" - return - fi - - # 기본 자동 생성/갱신 대상 - local default_files=("CLAUDE.md" "GEMINI.md" ".cursorrules" "AGENTS.md") - # 존재할 때만 갱신 - local optional_files=(".clinerules") - - for f in "${default_files[@]}"; do - cp "$rules_md" "$target_root/$f" - echo " 진입 파일 적용: $f" - done - - for f in "${optional_files[@]}"; do - if [[ -f "$target_root/$f" ]]; then - cp "$rules_md" "$target_root/$f" - echo " 진입 파일 적용: $f" - fi - done -} - # ── 사용법 ──────────────────────────────────────────────────────────────────── usage() { echo "사용법: $0 [--pull] " @@ -144,10 +119,10 @@ if [[ "$PULL_MODE" == "1" ]]; then echo " 현재 버전: $SRC_VER | framework 버전: $DST_VER" sync_common "$DST_AO" "$SRC_AO" cp "$DST_AO/.version" "$SRC_AO/.version" - apply_entry_files "$DST_AO/rules/common/rules.md" "$PROJECT_ROOT" + apply_agent_ops_entry_files "$DST_AO/rules/common/rules.md" "$PROJECT_ROOT" cd "$PROJECT_ROOT" git add agent-ops/rules/common agent-ops/skills/common agent-ops/bin agent-ops/.version \ - CLAUDE.md GEMINI.md .cursorrules AGENTS.md + "${AGENT_OPS_ENTRY_FILES[@]}" git commit -m "sync: pull from agentic-framework v$DST_VER" git push echo -e "${GREEN}✓ 완료 (pull v$DST_VER)${RESET}" @@ -161,12 +136,13 @@ if [[ "$IS_FRAMEWORK" == "1" ]]; then if [[ ! -d "$DST_AO" ]]; then echo " 최초 진행: agent-ops 전체 복사" cp -r "$SRC_AO" "$TARGET/" + apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" echo -e "${YELLOW} init-agent-ops 스킬로 초기화를 진행하세요.${RESET}" else echo " 이후 진행: common/ 동기화" sync_common "$SRC_AO" "$DST_AO" cp "$SRC_AO/.version" "$DST_AO/.version" - apply_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" + apply_agent_ops_entry_files "$SRC_AO/rules/common/rules.md" "$TARGET" fi echo -e "${GREEN}✓ 완료 → $(basename "$TARGET")${RESET}" exit 0 diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index 7ae784b..f2429db 100644 --- a/agent-ops/skills/common/code-review/SKILL.md +++ b/agent-ops/skills/common/code-review/SKILL.md @@ -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 and moves the completed task under agent-task/archive/YYYY/MM/. 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,38 +12,69 @@ 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. + +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.md` + `CODE_REVIEW.md` | Ready for review | -| `complete.log` + `*.log` files | Task complete (PASS) | +| `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), 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 | 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`, move `agent-task/{task_name}/` to `agent-task/archive/YYYY/MM/{task_name}/`, then complete the review-only checklist in the final archive path. + - `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, required next-state file writes, review-only checklist updates, and PASS task-directory archive moves 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.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 | +| 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 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. @@ -53,14 +84,17 @@ 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 `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: @@ -69,6 +103,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 the applicable dedicated checklist items in the archived `code_review_*.log` during Step 7, after archive, next-state writes, and PASS task-directory moves are done. + Severity semantics: | Verdict | Meaning | Follow-up plan | @@ -79,51 +115,72 @@ 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.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. ## Step 6 - Post-Review Actions -For `PASS`, write `agent-task/{task_name}/complete.log` before reporting: +For `PASS`, write `agent-task/{task_name}/complete.log` before reporting. -Required fields in `complete.log`: -- `완료 일시`: date completed. -- `요약`: one-line task description and loop count. -- `루프 이력`: table of plan/code_review log pairs with their verdict. -- `최종 리뷰 요약`: bullet list of what was implemented. -- `잔여 Nit`: any Nit-only findings recorded but not acted on (omit section if none). +Complete log template: -Then report: +- Template path: `agent-ops/skills/common/code-review/templates/complete-log-template.md` +- Copy the template's section order and fill every placeholder from the archived plan/review logs and final verdict. +- Do not leave placeholders in `complete.log`. +- Use `없음` for empty `잔여 Nit` or `후속 작업`. +- A PASS `complete.log` must not contain unresolved Required or Suggested issues. Nit-only leftovers may be recorded under `잔여 Nit`. + +After Step 7, report: - Verdict. - Archive filenames. -- `complete.log` written; task complete. +- Final task archive path under `agent-task/archive/YYYY/MM/`. -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_`. +- 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. -`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 # 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} @@ -132,11 +189,15 @@ task={task_name}, plan={N}, tag={TAG} ## 이 파일을 읽는 리뷰 에이전트에게 각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료 후 반드시 아래 순서로 아카이브하세요. +Review 완료 후 반드시 아래 순서로 아카이브하세요. -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` 작성 후 `agent-task/archive/YYYY/MM/{task_name}/`로 task 디렉터리 이동. WARN/FAIL인 경우 새 routed plan + review 스텁 작성. + +어떤 판정에서도 아카이브를 건너뛰지 마세요. PASS/WARN/FAIL 모두 `코드리뷰 결과` append 후 active plan/review 파일을 먼저 아카이브하고, 그 다음 `complete.log` 또는 다음 plan/review 파일을 작성해야 합니다. +PASS에서는 `agent-ops/skills/common/code-review/templates/complete-log-template.md`의 섹션 순서와 필수 항목을 기준으로 `complete.log`를 작성하세요. 작성 후 현재 날짜의 `YYYY/MM` 기준으로 task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고, 최종 archive 경로의 `code_review_*.log`에서 `코드리뷰 전용 체크리스트`를 갱신한 다음 보고하세요. +WARN/FAIL에서는 다음 상태 파일 작성 후 현재 task 경로의 archived `code_review_*.log`에서 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 체크한 다음 보고하세요. --- @@ -147,6 +208,23 @@ 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이면 `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`를 작성하지 않는다. + ## 계획 대비 변경 사항 _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ @@ -163,6 +241,11 @@ _구현 에이전트가 주요 설계 결정 사항을 기록한다._ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. + ### {TAG}-1 중간 검증 ``` $ {verification command from plan} @@ -174,6 +257,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: @@ -182,19 +271,34 @@ 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, Move PASS Task, And Report + +After Step 6: + +- If verdict is `PASS`, determine archive month from the current completion date as `YYYY/MM`, create `agent-task/archive/YYYY/MM/` if missing, then move `agent-task/{task_name}/` to `agent-task/archive/YYYY/MM/{task_name}/`. +- Do not overwrite an existing archive directory. If `agent-task/archive/YYYY/MM/{task_name}/` already exists, append the next numeric suffix: `agent-task/archive/YYYY/MM/{task_name}_1/`, `agent-task/archive/YYYY/MM/{task_name}_2/`, and so on. +- For `PASS`, open the moved `agent-task/archive/YYYY/MM/{final_task_dir}/code_review_{review_lane}_GNN_N.log`. +- For `WARN` or `FAIL`, open `agent-task/{task_name}/code_review_{review_lane}_GNN_N.log`. +- Check every applicable item in `코드리뷰 전용 체크리스트`; leave mutually exclusive verdict items unchecked. +- If any applicable item cannot be checked, finish the missing archive, `complete.log`, task-directory move, 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, applicable checked review-only checklist, required next-state files, and for `PASS` the final task archive move. + +Report Required/Suggested counts, archive names, and the final task archive path for `PASS` or new plan path for `WARN`/`FAIL`. ## 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 | @@ -208,11 +312,13 @@ Report Required/Suggested counts, archive names, and the new plan path. - Name exact stale symbols or missing tests. - Do not write vague praise or style opinions without a rule. - Every dimension gets Pass/Warn/Fail. +- For follow-up plans about verification trust, specify deterministic commands, for example `rg --sort path`, and forbid repo-local tool artifacts. ## 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`. +- PASS: `complete.log` written from `agent-ops/skills/common/code-review/templates/complete-log-template.md`, then task directory moved under `agent-task/archive/YYYY/MM/`. +- 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 applicable review-agent-only finalization checklist was completed before reporting. diff --git a/agent-ops/skills/common/code-review/templates/complete-log-template.md b/agent-ops/skills/common/code-review/templates/complete-log-template.md new file mode 100644 index 0000000..a4e8fa0 --- /dev/null +++ b/agent-ops/skills/common/code-review/templates/complete-log-template.md @@ -0,0 +1,31 @@ +# Complete - {task_name} + +## 완료 일시 + +{YYYY-MM-DD or ISO-8601} + +## 요약 + +{one-line task summary, loop count, and final verdict} + +## 루프 이력 + +| Plan | Review | Verdict | 메모 | +|------|--------|---------|------| +| `plan_{build_lane}_GNN_N.log` | `code_review_{review_lane}_GNN_N.log` | PASS/WARN/FAIL | {main outcome or follow-up reason} | + +## 구현/정리 내용 + +- {implemented or cleaned-up change} + +## 최종 검증 + +- `{command}` - {PASS/FAIL/BLOCKED}; {actual output summary or saved output path} + +## 잔여 Nit + +- 없음 + +## 후속 작업 + +- 없음 diff --git a/agent-ops/skills/common/create-domain-rule/SKILL.md b/agent-ops/skills/common/create-domain-rule/SKILL.md index 5e553c1..dedb8e2 100644 --- a/agent-ops/skills/common/create-domain-rule/SKILL.md +++ b/agent-ops/skills/common/create-domain-rule/SKILL.md @@ -10,7 +10,7 @@ description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 `agent-ops/rules/project/domain//rules.md` 파일을 올바른 형식으로 생성한다. 실제 프로젝트 폴더 구조를 분석하여 경로와 구성 요소를 자동으로 채운다. -생성 후 `rules/project/rules.md`의 도메인 매핑 테이블에 항목을 추가한다. +생성 후 `rules/project/rules.md`의 도메인 룰 로딩 안내와 도메인 매핑 테이블을 갱신한다. ## 언제 호출할지 @@ -61,12 +61,19 @@ description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 5. **rules/project/rules.md 업데이트** - `agent-ops/rules/project/rules.md` 를 읽는다 + - `## 도메인 룰 로딩` 섹션이 없으면 `## 도메인 매핑` 바로 위에 아래 형식으로 추가한다 + ``` + ## 도메인 룰 로딩 + + - 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다. + - 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다. + ``` - 도메인 매핑 테이블에 아래 형식으로 추가한다 ``` - | `` | `agent-ops/rules/project/domain//rules.md` | + | `` | | `agent-ops/rules/project/domain//rules.md` | ``` - 경로 패턴은 실제 포함 경로를 기준으로 작성한다 - - 기존 테이블 항목을 삭제하거나 재정렬하지 않는다 + - 기존 로딩 섹션과 테이블 항목을 삭제하거나 재정렬하지 않는다 6. **결과 보고** - 생성한 파일 경로 @@ -80,6 +87,7 @@ description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 - Domain Rule 경로: agent-ops/rules/project/domain//rules.md - 도메인 유형: +- 도메인 룰 로딩 섹션: <추가함 | 이미 존재함> - rules/project/rules.md 추가 경로 패턴: ## TODO 항목 (확인 필요) @@ -90,6 +98,7 @@ description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 - [ ] `agent-ops/rules/project/domain//rules.md` 파일이 생성되었는가 - [ ] 생성된 파일이 `domain-rule-template.md`의 모든 섹션(목적, 포함 경로, 제외 경로, 주요 구성 요소, 유지할 패턴, 경계, 금지 사항)을 포함하는가 +- [ ] `rules/project/rules.md`에 도메인 룰 로딩 섹션이 존재하는가 - [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 해당 도메인 항목이 추가되었는가 - [ ] 포함 경로에 기재된 경로가 실제로 프로젝트에 존재하는가 - 검증 실패 시: 누락된 섹션 또는 잘못된 경로를 사용자에게 알리고 해당 부분만 보완한다 @@ -99,6 +108,6 @@ description: 새로운 도메인 rules.md 파일을 생성하기 위한 범용 - 이미 존재하는 rules.md 를 덮어쓰지 않는다 - 실제 존재하지 않는 경로를 포함 경로에 넣지 않는다 - 추측으로 패턴이나 금지 사항을 채우지 않는다 — 확인된 내용만 기재한다 -- rules/project/rules.md 의 기존 항목을 삭제하거나 재정렬하지 않는다 +- rules/project/rules.md 의 기존 로딩 섹션과 테이블 항목을 삭제하거나 재정렬하지 않는다 - 하나의 domain rule 에 여러 독립 도메인의 책임을 묶지 않는다 - 코드 변경을 수행하지 않는다 — 이 skill 은 rule 파일 생성만 담당한다 diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md index c105459..af2b836 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` 등)이 있는지 확인 ## 핵심 원칙 @@ -60,21 +62,26 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 | 파일 | 방법 | |------|------| -| `CLAUDE.md`,`GEMINI.md`,`AGENTS.md`, `.cursorrules`, `.clinerules` 등 진입 파일 | `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사 후 `rules/common/rules.md` 삭제 | +| `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.clinerules` 등 진입 파일 | `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사 | | `agent-ops/.version` | 공통 관리 레포의 VERSION 파일을 그대로 복사 (프레임워크 버전 추적용) | +| `agent-ops/bin/` | 공통 스크립트 전체 복사 (진입 파일 목록의 단일 기준인 `entry-files.sh` 포함) | | `agent-ops/rules/common/` | 공통 폴더 전체 복사 (수정 금지) | | `agent-ops/skills/common/` | 공통 폴더 전체 복사 (수정 금지) | | `agent-ops/rules/project/rules.md` | 프로젝트 분석 후 생성 | | `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/**` 읽기/검색 제외 설정 생성, 있으면 덮어쓰지 않고 수동 병합 안내 | 에이전트별 파일명: +실제 생성/동기화 대상 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다. + | 에이전트 | 파일명 | |---------|--------| -| Claude | `CLAUDE.md` | | Gemini | `GEMINI.md` | +| Claude | `CLAUDE.md` | | Kilo Code / OpenCode | `AGENTS.md` | | Cursor | `.cursorrules` | | Cline | `.clinerules` | @@ -149,32 +156,44 @@ common/rules.md와 내용이 중복되지 않도록 한다. 도메인은 실제 폴더, 모듈, 패키지, 책임 경계와 연결되어야 한다. +## 실행 (Execution) + +지정한 대상 디렉토리에 agent-ops 스캐폴드를 생성한다. + +```bash +./agent-ops/bin/init-agent-ops.sh +``` + ## 실행 절차 1. **상태 판별** - 프로젝트 구조, 모듈 경계, agent-ops 파일 유무를 분석하여 신규/운영중을 판별한다 2. **에이전트 진입 파일 생성** - - `rules/common/rules.md`를 에이전트별 파일명으로 프로젝트 루트에 복사한다 - - 복사 후 `rules/common/rules.md`를 삭제한다 + - `rules/common/rules.md`를 `agent-ops/bin/entry-files.sh`의 파일 목록으로 프로젝트 루트에 복사한다 -3. **agent-ops 폴더 구조 복사** - - 공통 관리 레포의 `agent-ops/` 공통 폴더(rules/common, skills/common)를 복사한다 +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/` 공통 폴더(bin, 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 제안, 주의사항을 출력한다 ## 출력 형식 @@ -204,16 +223,20 @@ common/rules.md와 내용이 중복되지 않도록 한다. ## 실행 결과 검증 -- [ ] 진입 파일이 프로젝트 루트에 존재하고, 내용이 `rules/common/rules.md`와 일치하는가 +- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 프로젝트 루트에 존재하고, 내용이 초기화에 사용한 `rules/common/rules.md`와 일치하는가 - [ ] `agent-ops/rules/project/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 fefbf5f..897de37 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -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 and moves PASS tasks under agent-task/archive/YYYY/MM/. --- # Plan @@ -10,63 +10,114 @@ 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, complete.log, and PASS task-directory archive move 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. + +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. 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) | +| `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.md`: +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 | +| 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. | -`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`. +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 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. +- [ ] **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 - 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 + - 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.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 +128,18 @@ 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 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 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. +- `최종 검증`: 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: @@ -93,6 +151,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. @@ -101,6 +161,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 +173,18 @@ Test policy: | Internal refactor | Existing tests may be enough | | Concurrency logic | Race/ordering test recommended | -## Step 5 - Write CODE_REVIEW.md Stub +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 ` 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. @@ -121,6 +193,12 @@ 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 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} @@ -129,11 +207,15 @@ task={task_name}, plan={N}, tag={TAG} ## 이 파일을 읽는 리뷰 에이전트에게 각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료 후 반드시 아래 순서로 아카이브하세요. +review 완료 후 반드시 아래 순서로 아카이브하세요. -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` 작성 후 `agent-task/archive/YYYY/MM/{task_name}/`로 task 디렉터리 이동. WARN/FAIL인 경우 새 routed plan + review 스텁 작성. + +어떤 판정에서도 아카이브를 건너뛰지 마세요. PASS/WARN/FAIL 모두 `코드리뷰 결과` append 후 active plan/review 파일을 먼저 아카이브하고, 그 다음 `complete.log` 또는 다음 plan/review 파일을 작성해야 합니다. +PASS에서는 `agent-ops/skills/common/code-review/templates/complete-log-template.md`의 섹션 순서와 필수 항목을 기준으로 `complete.log`를 작성하세요. 작성 후 현재 날짜의 `YYYY/MM` 기준으로 task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고, 최종 archive 경로의 `code_review_*.log`에서 `코드리뷰 전용 체크리스트`를 갱신한 다음 보고하세요. +WARN/FAIL에서는 다음 상태 파일 작성 후 현재 task 경로의 archived `code_review_*.log`에서 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 체크한 다음 보고하세요. --- @@ -144,6 +226,23 @@ 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이면 `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`를 작성하지 않는다. + ## 계획 대비 변경 사항 _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ @@ -160,6 +259,11 @@ _구현 에이전트가 주요 설계 결정 사항을 기록한다._ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. + ### {TAG}-1 중간 검증 ``` $ {verification command from plan} @@ -171,18 +275,26 @@ $ {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: -| 섹션 | 소유자 | 설명 | -|------|--------|------| -| 헤더 주석, 개요(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, 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 @@ -195,8 +307,11 @@ 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}/`. +- 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. -- `CODE_REVIEW.md` completion table lists every plan item. +- 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. diff --git a/agent-ops/skills/common/sync-pull/SKILL.md b/agent-ops/skills/common/sync-pull/SKILL.md index 9afcdb1..adc2c42 100644 --- a/agent-ops/skills/common/sync-pull/SKILL.md +++ b/agent-ops/skills/common/sync-pull/SKILL.md @@ -29,7 +29,7 @@ agent-ops/bin/sync.sh --pull - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가 -- [ ] 진입 파일(CLAUDE.md 등)이 갱신됐는가 +- [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가 ## 금지 사항 diff --git a/agent-ops/skills/common/sync-push/SKILL.md b/agent-ops/skills/common/sync-push/SKILL.md index 7f18074..04884a1 100644 --- a/agent-ops/skills/common/sync-push/SKILL.md +++ b/agent-ops/skills/common/sync-push/SKILL.md @@ -1,13 +1,16 @@ --- name: sync-push -description: 현재 프로젝트의 agent-ops를 agentic-framework로 올린다. "agent-ops 싱크해", "agent-ops 동기화해", "agentic-framework에 올려줘" 요청 시 사용한다. +description: 현재 프로젝트의 agent-ops를 agentic-framework로 올리거나, agentic-framework의 공통 agent-ops를 대상 프로젝트로 push한다. "agent-ops 싱크해", "agent-ops 동기화해", "agentic-framework에 올려줘" 요청 시 사용한다. --- # sync-push ## 목적 -`agent-ops/bin/sync.sh`를 호출해 현재 프로젝트 → agentic-framework 방향으로 agent-ops를 올린다. +`agent-ops/bin/sync.sh`를 호출해 agent-ops 공통 파일을 push 방향으로 동기화한다. + +- 일반 프로젝트에서는 현재 프로젝트 → agentic-framework 방향으로 올린다. +- agentic-framework 원본 프로젝트에서는 agentic-framework → 대상 프로젝트 방향으로 보낸다. ## 언제 호출할지 @@ -28,6 +31,19 @@ description: 현재 프로젝트의 agent-ops를 agentic-framework로 올린다. 1. 사용자 요청에서 target 프로젝트명 또는 경로를 추출한다 2. **명시된 경우**: `agent-ops/bin/sync.sh ` 실행 3. **명시되지 않은 경우**: 사용자에게 대상 프로젝트 입력을 요청한다 +4. `sync.sh`는 현재 agentic-framework의 `agent-ops/rules/common/rules.md` 내용을 대상 프로젝트 루트의 진입 파일에 덮어쓴다 + +덮어쓰기 대상은 `init-agent-ops` 초기 세팅과 동일하며, 실제 목록은 `agent-ops/bin/entry-files.sh`의 `AGENT_OPS_ENTRY_FILES`를 단일 기준으로 사용한다. + +| 에이전트 | 파일명 | +|---------|--------| +| Gemini | `GEMINI.md` | +| Claude | `CLAUDE.md` | +| Kilo Code / OpenCode | `AGENTS.md` | +| Cursor | `.cursorrules` | +| Cline | `.clinerules` | + +대상 프로젝트에 기존 진입 파일이 있어도 보존하거나 병합하지 않고 `agent-ops/rules/common/rules.md` 내용으로 교체한다. ```bash agent-ops/bin/sync.sh @@ -37,6 +53,7 @@ agent-ops/bin/sync.sh - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다 +- [ ] agentic-framework에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 agentic-framework의 `agent-ops/rules/common/rules.md`와 일치하는가 ## 금지 사항