From 9e70401972227fb646e4b20797f92007a9327296 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 28 May 2026 05:35:51 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.79 --- agent-ops/.version | 2 +- agent-ops/rules/common/philosophy.md | 7 +++-- agent-ops/rules/common/rules-roadmap.md | 19 ++++++++---- ...lementation-user-review-request-section.md | 10 +++++++ agent-ops/skills/common/code-review/SKILL.md | 29 +++++++++++++++++-- .../templates/user-review-template.md | 4 +-- agent-ops/skills/common/plan/SKILL.md | 26 +++++++++++++++-- 7 files changed, 81 insertions(+), 16 deletions(-) create mode 100644 agent-ops/skills/common/_templates/implementation-user-review-request-section.md diff --git a/agent-ops/.version b/agent-ops/.version index c24ccab9..65ca0f8a 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.75 +1.1.79 diff --git a/agent-ops/rules/common/philosophy.md b/agent-ops/rules/common/philosophy.md index 29dd29de..89f7df54 100644 --- a/agent-ops/rules/common/philosophy.md +++ b/agent-ops/rules/common/philosophy.md @@ -52,9 +52,10 @@ - 스킬 그룹끼리는 다른 그룹의 내부 절차를 자동 호출하거나 전제하지 않는다. - 그룹 간 연결은 사용자 명령, 런타임 이벤트, 또는 판별 가능한 파일 상태로만 한다. - 구현 작업 그룹은 `plan`과 `code-review`의 PLAN/CODE_REVIEW 루프를 소유한다. -- 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 Phase/Milestone 상태, 구현 잠금, archive 흐름을 소유한다. -- `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 `update-roadmap` 흐름으로 넘긴다. -- cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹과 런타임의 책임이다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다. +- 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신 흐름을 소유한다. +- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 NomadCode Core 또는 런타임이 있으면 그쪽 책임으로 둔다. +- `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 Core/MCP action이 있으면 그쪽으로, 없으면 `update-roadmap` file-based fallback 흐름으로 넘긴다. +- cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹, Core, 런타임의 공동 경계다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다. - 새 스킬을 만들기 전에 기존 그룹의 자연스러운 입력, 상태 전환, 후처리 지점에 넣을 수 있는지 먼저 본다. 다만 다른 그룹 경계를 침범해야 하면 런타임 이벤트로 분리한다. ## 로드맵 diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index c7bf03c6..28733a7c 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -12,6 +12,13 @@ - 진행중 Phase 안에서 완료된 Milestone은 활성 `PHASE.md`에 짧은 archive 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase//milestones/`로 이동한다. - archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. +## Runtime Action Boundary + +- 로드맵 스킬은 기본적으로 로드맵 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당한다. +- Core/MCP가 있는 프로젝트에서는 Phase/Milestone 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리한다. +- Core/MCP가 없거나 아직 해당 action을 제공하지 않는 프로젝트에서만 `update-roadmap` 스킬이 file-based fallback으로 직접 문서를 갱신한다. +- `update-roadmap`은 fallback 갱신을 수행하더라도 런타임 action 경계를 문서화하고, Core/MCP로 넘길 수 있는 입력과 결과를 함께 남긴다. + ## 로딩 - 세션 최초 1회 `agent-roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다. @@ -28,7 +35,7 @@ - 활성 Phase는 `agent-roadmap/phase/**/PHASE.md`만 대상으로 한다. - 활성 Milestone은 `agent-roadmap/phase/**/milestones/*.md`만 대상으로 한다. - `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 `[검토중]`으로 둔다. -- "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 `update-roadmap` 스킬로 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다. +- "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 `update-roadmap` 스킬로 배치 제안 또는 file-based fallback 갱신을 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다. - target 없는 신규 추가 요청은 먼저 요청 규모를 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위로 판정한다. - target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 `ROADMAP.md`의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다. - 배치는 Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다. @@ -67,7 +74,7 @@ ## 프로젝트 간 잠금 -- 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 파일이 없어도 `update-roadmap`이 디렉터리와 파일을 만든다. +- 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 Core/MCP가 있으면 그쪽 action이 만들고, 없으면 `update-roadmap` file-based fallback이 디렉터리와 파일을 만든다. - entry는 `id`, `locked`, `rely-on[].target`, `rely-on[].status`, `rely-on[].note`만 사용한다. - `locks.yaml`은 root sequence block style을 기본으로 작성한다. 예: `- id: ...` 아래에 `locked`, `rely-on`을 둔다. - `id`는 기본적으로 `<잠긴-project>:<잠긴-milestone-slug>`로 만든다. @@ -84,8 +91,8 @@ - 같은 `id` entry를 upsert할 때 기존 `rely-on` 항목을 삭제하지 않는다. 같은 `rely-on.target`만 status/note를 갱신하고, 없는 target은 추가하며, `locked` 경로가 바뀐 경우에만 `locked`를 갱신한다. - `locks.yaml`이 있고 Milestone을 갱신하거나 archive할 때는 대상 Milestone identity로 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "" both ""`를 먼저 실행한다. - find 결과가 `none`이면 결과 보고의 `Workspace 잠금`에 `관련 lock 없음`을 남긴다. 외부 의존 잠금 생성/동기화 요청이 아니라면 `locks.yaml`을 새로 만들거나 수정하지 않는다. -- `update-roadmap`이 갱신한 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 Milestone 상태 기준으로 `status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다. -- `update-roadmap`이 갱신하거나 선택한 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 런타임이 별도 `update-roadmap` 호출로 처리한다. +- Core/MCP action 또는 `update-roadmap` fallback이 갱신한 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 Milestone 상태 기준으로 `status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다. +- Core/MCP action 또는 `update-roadmap` fallback이 갱신하거나 선택한 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 Core/MCP 또는 런타임의 별도 action으로 처리한다. - archive 모드에서는 파일 이동 전에 대상 Milestone의 활성 경로 identity를 보존하고, 그 identity로 `--find-milestone "" both ""`를 먼저 실행한다. 보존한 identity가 어느 entry의 `rely-on.target`과 일치하고 Milestone 상태가 `[완료]`이면 archive 이동 전에 해당 `rely-on.status`를 `enable`로 바꾼다. - archive 모드에서 보존한 identity가 어느 entry의 `locked`와 일치하면 archive 이동 전에 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 미충족이어도 archive 자체는 막지 않고 `Workspace 잠금: 미충족`으로 보고한다. - 잠금 해제 조건 충족 여부만 확인할 때는 `agent-ops/skills/common/check-roadmap-dependency/SKILL.md`를 읽는다. lock id가 없으면 해당 스킬은 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "" "" ""`로 현재 Milestone이 `locked`인지 `rely-on.target`인지 양방향으로 찾은 뒤 `agent-ops/bin/roadmap-dependency-checker.sh "" ""`를 사용한다. @@ -114,7 +121,7 @@ - `m-`는 Milestone 기반 작업 전용 예약 prefix이며, 일반 작업 task group은 `m-`으로 시작하지 않는다. - 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다. - `code-review`에서 `m-` 작업이 PASS되면 roadmap을 직접 수정하거나 `update-roadmap`을 직접 호출하지 않는다. -- 런타임은 PASS 완료 이벤트의 task group에서 `m-`를 판별하고, 상태 체크 후 `update-roadmap` 흐름으로 Milestone 업데이트를 호출한다. +- 런타임은 PASS 완료 이벤트의 task group에서 `m-`를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback 흐름을 호출한다. - 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 `agent-task/archive/YYYY/MM/m-/...`를 `agent-task/m-/...` 형태의 `origin-task`로 정규화해 전달한다. - 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다. - `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 `m-` task group에서 follow-up plan/review를 이어가지만, code-review의 user-review gate가 트리거되면 `USER_REVIEW.md`를 남기고 사용자 판단을 기다린다. @@ -137,7 +144,7 @@ ## 아카이브 -- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 `update-roadmap` 스킬로 아카이빙한다. +- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 Core/MCP action으로 아카이빙한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback으로 아카이빙한다. - `[검토중]` Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다. - Phase 아카이브 대상은 `agent-roadmap/archive/phase//PHASE.md`와 같은 scaffold로 이동한다. - Milestone 아카이브 대상은 `agent-roadmap/archive/phase//milestones/.md`로 이동한다. diff --git a/agent-ops/skills/common/_templates/implementation-user-review-request-section.md b/agent-ops/skills/common/_templates/implementation-user-review-request-section.md new file mode 100644 index 00000000..998a3b2e --- /dev/null +++ b/agent-ops/skills/common/_templates/implementation-user-review-request-section.md @@ -0,0 +1,10 @@ +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 재개 조건: 없음 diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index 2b82775f..2233edc9 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: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state: PASS writes complete.log and moves the task to archive; WARN/FAIL writes follow-up PLAN/CODE_REVIEW files unless the user-review gate requires USER_REVIEW.md; user review resolution that closes the task writes complete.log before archive. Never stop after verdict append or user-review closure without writing the required next-state artifact. +description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, implementation-time 사용자 리뷰 요청, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state: PASS writes complete.log and moves the task to archive; WARN/FAIL writes follow-up PLAN/CODE_REVIEW files unless the user-review gate requires USER_REVIEW.md; user review resolution that closes the task writes complete.log before archive. Never stop after verdict append or user-review closure without writing the required next-state artifact. --- # Code Review @@ -15,11 +15,14 @@ plan skill -> implementation -> code-review skill +----- issues found: new routed plan/review files ``` +Implementation may stop early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. Code-review validates that request and, when justified, writes `USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`. + ## Core Loop Rules - Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` or `USER_REVIEW.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`. - Finalize every selected active state: for `CODE_REVIEW-*-G??.md`, append one verdict, archive the active review and plan files, then create exactly one next state; for `USER_REVIEW.md` completion, update the stop state, write `complete.log`, and archive the task. Do not report before finalization is complete. - Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-`, report completion metadata for the runtime event. `WARN` or `FAIL` normally writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`; if the user-review gate triggers, write `USER_REVIEW.md` instead. A completed `USER_REVIEW.md` uses the same terminal `complete.log` and archive path as `PASS`. +- A filled implementation-owned `사용자 리뷰 요청` is a review input, not a next state by itself. If it is a genuine user-only decision, external environment prerequisite, or scope conflict, the user-review gate triggers and this skill writes `USER_REVIEW.md`; if it is vague, unsupported, or repo-fixable, write a normal WARN/FAIL follow-up plan instead. - Do not ask for confirmation before WARN/FAIL follow-up files unless the user-review gate triggers. If details are uncertain but the gate does not trigger, write the smallest concrete follow-up plan with file references and verification commands. - Recovery: if a prior turn appended a verdict without archive or next-state files, or resolved `USER_REVIEW.md` without `complete.log`, resume at the matching finalization step and finish the missing artifacts first. @@ -30,7 +33,9 @@ plan skill -> implementation -> code-review skill - Compute `review-number` as `count(agent-task/{task_name}/code_review_*.log) + 1` before archiving the active review. - If `review-number >= 5` and the verdict is `WARN` or `FAIL`, stop the automatic loop and write `USER_REVIEW.md`. - If `review-number == 1`, the verdict is `FAIL`, and the blocking issue is a test environment problem rather than a repo-fixable implementation issue, stop the automatic loop and write `USER_REVIEW.md`. +- If the active review file has a filled `사용자 리뷰 요청` with `상태` other than `없음`, and the blocker is a user-only decision, external environment prerequisite, or scope conflict that the repository cannot safely resolve by code changes alone, stop the automatic loop and write `USER_REVIEW.md`. - Treat a first-review failure as a test environment problem only with evidence: missing SDK/tool/runtime, unavailable external service, absent secret/credential, unsupported OS/device/interactive environment, or another prerequisite outside the repository. Record the exact command and stdout/stderr. Before claiming a tool is missing, require `command -v ` or the project-equivalent check. +- Treat an implementation-owned `사용자 리뷰 요청` as valid only with specific decision questions, evidence, attempted commands/output or a reason commands could not run, and clear resume conditions. Vague uncertainty, repo-owned setup bugs, and ordinary incomplete implementation become normal WARN/FAIL follow-up plans instead. - Do not classify repo-owned setup bugs as environment problems. If a manifest, bootstrap script, test fixture, or documented project entrypoint should provide the dependency, write a normal follow-up plan instead. - `USER_REVIEW.md` is created from `agent-ops/skills/common/code-review/templates/user-review-template.md`, filled with the archived loop history, current archived plan/review paths, verdict, loop count, blocking evidence, and user decision options. @@ -96,6 +101,7 @@ Directory states: | State | Meaning | |-------|---------| | `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub or placeholders | Implementation is pending/incomplete; review should fail completeness if invoked | +| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation is blocked on user input; review validates the request and writes `USER_REVIEW.md` if justified | | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill | | `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move | | `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan | @@ -146,6 +152,7 @@ Before writing the verdict: - If a checklist item contains integrated verification for a feature, treat that feature item as incomplete until both implementation evidence and the matching verification output are present. Do not accept a separate unchecked completion-criteria item as a substitute. - 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. +- Read the `사용자 리뷰 요청` section. If `상태` is not `없음`, validate the exact decision needed, blocker evidence, command output or not-run reason, and resume condition before deciding whether the user-review gate triggers. - 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. @@ -211,7 +218,7 @@ For `WARN` or `FAIL`, apply the user-review gate before writing follow-up files. If the user-review gate triggers: - Write `agent-task/{task_name}/USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`. -- Fill every placeholder. Use `loop-limit` or `environment-blocked` as the reason type. +- Fill every placeholder. Use `loop-limit`, `environment-blocked`, or `implementation-blocked` as the reason type. - Include all available archived loop history in chronological order, the current archived plan/review log paths, the final verdict, review number, issue summary, blocking evidence, and the exact user decision needed. - Do not write a new active `PLAN-{build_lane}-GNN.md` or `CODE_REVIEW-{review_lane}-GNN.md`. - Do not write `complete.log`. @@ -234,6 +241,8 @@ If the user-review gate does not trigger, write new routed plan/review files usi - `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. +- The follow-up plan's implementer instructions and review stub must include the implementation-time `사용자 리뷰 요청` stop path so the next implementer can act without reading the plan skill. +- Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the follow-up review stub's `사용자 리뷰 요청` section. Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent): @@ -246,6 +255,7 @@ Routed review stub template (fill `{…}` placeholders; everything else is fixed > The task is NOT complete until every implementation-owned section below is filled in. > Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. > Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. > Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. > Follow the ownership table at the bottom of this file for which sections you own. @@ -305,6 +315,17 @@ _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 _구현 에이전트가 주요 설계 결정 사항을 기록한다._ +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 재개 조건: 없음 + ## 리뷰어를 위한 체크포인트 {pre-filled from plan — one bullet per review focus area} @@ -317,6 +338,7 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 - 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. - 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. - `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. ### {TAG}-1 중간 검증 ``` @@ -346,6 +368,7 @@ Sections and their ownership: | 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 | | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | | 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 | +| 사용자 리뷰 요청 | 구현 에이전트가 채움 | 진행에 사용자 입력이 필요하지 않으면 `상태: 없음` 유지; 필요하면 결정 항목, 근거, 명령 출력, 재개 조건을 기록 | | 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 | | 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움; 명령 변경은 `계획 대비 변경 사항`에 기록 | | 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 | @@ -402,6 +425,8 @@ Report Required/Suggested counts, archive names, the final task archive path for - PASS milestone task group: `m-` completion event metadata was reported for runtime; roadmap was not modified by code-review. - PASS split: empty active parent `agent-task/{task_group}/` removed after the subtask move; non-empty parent left in place. - WARN/FAIL without user-review gate: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers and matching `구현 체크리스트`; no `complete.log`. +- Follow-up review stubs include the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. - USER_REVIEW: `USER_REVIEW.md` exists from template, no active `PLAN-*.md` or `CODE_REVIEW-*.md` remains, and no `complete.log` was written. +- Implementation-requested USER_REVIEW: archived review log preserves the filled `사용자 리뷰 요청` evidence and the generated `USER_REVIEW.md` records the exact user decision needed. - USER_REVIEW resolved as PASS: archived task contains both resolved `USER_REVIEW.md` and `complete.log`. - The applicable review-agent-only finalization checklist was completed before reporting. diff --git a/agent-ops/skills/common/code-review/templates/user-review-template.md b/agent-ops/skills/common/code-review/templates/user-review-template.md index 38226c8e..70ff03b2 100644 --- a/agent-ops/skills/common/code-review/templates/user-review-template.md +++ b/agent-ops/skills/common/code-review/templates/user-review-template.md @@ -10,7 +10,7 @@ USER_REVIEW ## 사유 -- 유형: {loop-limit or environment-blocked} +- 유형: {loop-limit, environment-blocked, or implementation-blocked} - 현재 리뷰 회차: {review-number} - 최종 판정: {WARN or FAIL} - 요약: {why automatic follow-up stopped} @@ -29,7 +29,7 @@ USER_REVIEW - 현재 archive review: `{current-archived-review-log}` - 검증 명령: `{command or 없음}` - 실제 출력: {stdout/stderr excerpt or saved output path} -- 환경 판단 근거: {why this is outside repo-fixable scope, or 없음} +- 차단 판단 근거: {why this needs user decision or is outside repo-fixable scope, or 없음} ## 사용자 결정 필요 diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 78cd2a16..151d20bf 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -11,13 +11,15 @@ Create the planning artifacts for the implementation loop: ```text plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub -implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md +implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md, or blocked-state user-review request recorded in the review stub code-review skill -> verdict + archive, complete.log, and PASS/user-review-resolved task-directory archive move, new follow-up plan/review files, or USER_REVIEW.md runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call ``` `code-review` may stop the automatic loop with `USER_REVIEW.md` when repeated non-PASS reviews or first-review test environment blockers require a user decision. Plan creation after `USER_REVIEW.md` requires an explicit user decision. If the user decision closes the task as complete/PASS, code-review resolves `USER_REVIEW.md`, writes `complete.log`, and archives the task instead of creating a new plan. +The plan file and review stub must be self-sufficient for implementation agents that do not read this skill. If implementation discovers a user-only decision, external environment prerequisite, or scope conflict that blocks safe progress, the implementing agent records a `사용자 리뷰 요청` in the active `CODE_REVIEW-*-G??.md`, leaves active files in place, and reports ready for review. The code-review skill validates that request and writes `USER_REVIEW.md` when the stop is justified. Use `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` as the shared section template. + ## Workflow Contract This skill intentionally uses routed active files under an active task directory as the state protocol. Do not change this directory or filename contract unless the paired code-review skill is updated together. @@ -42,6 +44,7 @@ Filename rules: Role boundary rules: - Implementing agents fill implementation-owned `CODE_REVIEW-*-G??.md` sections, keep active files in place, and report ready for review. +- If implementation cannot continue without user input, implementing agents fill the review stub's `사용자 리뷰 요청` section with the exact decision needed, evidence, commands/output, and resume condition, then stop with active files in place. - Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, review-only checklist) is code-review-skill only. Split decision policy: @@ -99,6 +102,7 @@ Directory states: |-------|---------| | `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` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation is blocked on user input; ready for code-review to validate and create `USER_REVIEW.md` if justified | | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill | | `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move | | `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan | @@ -206,8 +210,9 @@ Header line must be exactly: Required sections: - Title. -- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only. +- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only. Also state that if implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, the implementer must fill the review stub's `사용자 리뷰 요청` section with exact evidence and stop for code-review; the implementer does not create `USER_REVIEW.md`, archive logs, or write `complete.log`. - `배경`: 2-4 sentences explaining why the work is needed. +- `사용자 리뷰 요청 흐름`: state that implementation-time blockers are recorded in the active review stub's `사용자 리뷰 요청` section, copied from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; code-review owns validation and the actual `USER_REVIEW.md` file write. - `분석 결과`: 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. @@ -266,6 +271,7 @@ Verification fidelity rules: ## 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. +Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the review stub's `사용자 리뷰 요청` section. ```markdown @@ -276,6 +282,7 @@ Use the template below exactly. Fill `{…}` placeholders from the plan; everyth > The task is NOT complete until every implementation-owned section below is filled in. > Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. > Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. > Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. > Follow the ownership table at the bottom of this file for which sections you own. @@ -335,6 +342,17 @@ _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 _구현 에이전트가 주요 설계 결정 사항을 기록한다._ +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 재개 조건: 없음 + ## 리뷰어를 위한 체크포인트 {pre-filled from plan — one bullet per review focus area} @@ -347,6 +365,7 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 - 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. - 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. - `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. ### {TAG}-1 중간 검증 ``` @@ -376,6 +395,7 @@ Sections and their ownership: | 구현 체크리스트 (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 | +| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required to proceed; when filled, include exact decision, evidence, commands/output, and resume condition | | 리뷰어를 위한 체크포인트 | 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 | @@ -400,5 +420,7 @@ Sections and their ownership: - If resuming from `USER_REVIEW.md`, it was archived to `user_review_N.log` and the user decision was recorded in the new plan. - 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 plan's implementer instructions and review stub both explain the implementation-time `사용자 리뷰 요청` stop path. +- The review stub includes the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. - The review stub has a clearly marked `코드리뷰 전용 체크리스트` owned only by the review agent. - Routed review file completion table lists every plan item.