From 3e413adc498df07533503ff1eec2ec371a7a243c Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 25 May 2026 12:36:12 +0900 Subject: [PATCH] sync: to agentic-framework v1.1.51 --- agent-ops/.version | 2 +- agent-ops/rules/common/philosophy.md | 82 +++++++++++++++++++ agent-ops/rules/common/rules-roadmap.md | 6 +- agent-ops/rules/common/rules.md | 1 + agent-ops/skills/common/code-review/SKILL.md | 25 +++--- agent-ops/skills/common/plan/SKILL.md | 9 +- .../skills/common/update-roadmap/SKILL.md | 16 ++-- 7 files changed, 114 insertions(+), 27 deletions(-) create mode 100644 agent-ops/rules/common/philosophy.md diff --git a/agent-ops/.version b/agent-ops/.version index da44c7f..3baec79 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.50 +1.1.51 diff --git a/agent-ops/rules/common/philosophy.md b/agent-ops/rules/common/philosophy.md new file mode 100644 index 0000000..80a2f45 --- /dev/null +++ b/agent-ops/rules/common/philosophy.md @@ -0,0 +1,82 @@ +# Agent-Ops 철학 + +이 문서는 agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 고칠 때만 읽어. +일반 구현 작업에서는 읽지 마. + +## 핵심 + +- agent-ops는 AI agent가 작업하기 위한 규칙이자 가이드다. +- 사람 문서처럼 장황하게 설명하지 말고, agent가 바로 실행할 수 있게 써. +- 필요한 컨텍스트만 읽게 만들어. 모든 문서를 항상 읽게 만들지 마. +- 애매한 형식을 만들지 마. 경로, 상태, id, 입력, 출력은 판별 가능해야 한다. +- 문서는 짧고 단단해야 한다. 길어서 이해되는 문서보다 짧아서 헷갈리지 않는 문서가 낫다. + +## 문서 작성 + +- 규칙과 스킬은 핵심만 써. +- 같은 말을 여러 문서에 반복하지 마. 한 곳에 두고 링크해. +- 설명보다 조건, 입력, 행동, 금지 사항을 우선해. +- "적절히", "필요하면", "가능하면" 같은 말은 판별 기준이 없으면 쓰지 마. +- 예외가 있으면 예외 조건을 같이 써. +- 긴 배경 설명은 README나 별도 참조 문서로 보내고, 실행 문서에는 실행 규칙만 남겨. +- 반말이어도 된다. 명확한 명령형이 더 좋다. + +## 라우팅 + +- 라우팅은 얕아야 한다. +- 1홉은 진입 파일에서 공통/프로젝트 규칙을 읽는 단계다. +- 2홉은 규칙에서 domain rule, roadmap rule, router를 따라가는 단계다. +- 3홉은 router에서 SKILL.md를 읽는 단계다. +- 4홉은 skill이 템플릿이나 참조 문서를 추가로 읽는 단계다. +- 4홉 이상이 필요하면 구조가 과하게 쪼개졌는지 먼저 의심해. 필요하면 앞 문서에 바로 가는 링크를 추가해. +- 깊은 링크 체인을 만들지 말고, 필요한 문서가 무엇인지 앞 문서에서 바로 보이게 해. +- 일반 작업마다 router, 모든 skill, 전체 roadmap, archive를 읽게 만들지 마. + +## LLM과 런타임 + +- LLM은 의미 판단, 범위 판단, 요약, 설계 선택을 맡는다. +- 런타임은 파일명, 폴더명, 상태값, exit code처럼 결정적으로 판별 가능한 일을 맡는다. +- LLM 없이 처리할 수 있는 구간은 파일 규약으로 빼. +- 런타임 신호는 문서 본문보다 경로와 이름에 둬. +- 런타임 신호를 만들 때는 agent가 본문을 읽지 않아도 판별 가능해야 한다. +- `m-` 같은 prefix는 런타임 판별을 위한 신호다. +- code-review는 PASS 산출물을 만들고 완료 이벤트 메타데이터를 남긴다. +- roadmap 반영 여부와 호출 타이밍은 런타임이 완료 이벤트를 보고 판단한다. + +## 로드맵 + +- roadmap은 장기 기억이고, agent-task는 실행 상태다. +- current는 현재 작업 하나가 아니라 활성 Phase/Milestone 후보 창이다. +- Phase와 Milestone은 큰 방향과 완료 기준을 담는다. +- 구현 계획은 agent-task의 PLAN/CODE_REVIEW 루프에 둔다. +- 완료 후보는 바로 archive하지 말고 `[검토중]`으로 둔다. +- archive는 일반 작업에서 읽지 않는다. 과거 근거가 필요할 때만 링크를 따라 읽는다. + +## 스킬 + +- skill은 절차 문서다. +- skill 하나에 책임 하나만 둬. +- skill이 다른 skill을 자동으로 깊게 호출하는 구조를 만들지 마. +- skill 본문은 실행에 필요한 규칙만 둬. +- 템플릿은 출력 형식이 흔들릴 때만 둬. +- 스킬 업데이트 시 router, rules, template, 출력 형식이 같은 계약을 말하는지 같이 확인해. + +## 좋은 구조 + +- 진입 파일은 최소 규칙만 둔다. +- common rules는 공통 시작점만 둔다. +- project rules는 프로젝트 특화 판단만 둔다. +- domain rules는 특정 코드 영역 규칙만 둔다. +- skills는 반복 작업 절차만 둔다. +- roadmap은 장기 목표와 완료 기준만 둔다. +- agent-task는 실행 중인 작업 상태와 완료 산출물만 둔다. + +## 경고 신호 + +- 같은 내용을 세 군데 이상 설명하고 있다. +- 어떤 문서를 읽어야 할지 문서 안에서 다시 찾아야 한다. +- 상태값이 사람은 이해하지만 런타임은 판별하기 어렵다. +- skill이 너무 많은 예외를 품고 있다. +- README가 내부 규칙 문서처럼 길어지고 있다. +- archive를 일반 작업 컨텍스트로 끌어오고 있다. +- LLM이 파일명만 봐도 될 일을 본문까지 읽어 판단하고 있다. diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index 5674175..ef4427f 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -75,8 +75,10 @@ - split 작업은 기존 규칙 그대로 `agent-task/m-//` 아래에 둔다. - `m-`는 Milestone 기반 작업 전용 예약 prefix이며, 일반 작업 task group은 `m-`으로 시작하지 않는다. - 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다. -- `code-review`에서 `m-` 작업이 PASS되면 활성 `agent-ops/roadmap/phase/*/milestones/.md`가 정확히 하나인지 확인한 뒤 `update-roadmap` 흐름으로 Milestone 업데이트를 요청한다. -- 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다. +- `code-review`에서 `m-` 작업이 PASS되면 roadmap을 직접 수정하거나 `update-roadmap`을 직접 호출하지 않는다. +- 런타임은 PASS 완료 이벤트의 task group에서 `m-`를 판별하고, 상태 체크 후 `update-roadmap` 흐름으로 Milestone 업데이트를 호출한다. +- 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 `agent-task/archive/YYYY/MM/m-/...`를 `agent-task/m-/...` 형태의 `origin-task`로 정규화해 전달한다. +- 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다. - `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않고 같은 `m-` task group에서 follow-up plan/review를 이어간다. ## 완료 리뷰 diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index 0fd81a0..5b5fb32 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -7,6 +7,7 @@ - 불확실하면 단정하지 말고 후보를 제시한다. - `agent-task/archive/**`는 사용자가 명시적으로 요청한 경우에만 읽는다. - `agent-ops/roadmap/` 디렉터리가 있는 프로젝트에서도 `agent-ops/roadmap/archive/**`는 일반 작업에서 읽지 않는다. 로드맵 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `agent-ops/rules/common/rules-roadmap.md`의 archive 접근 규칙을 따른다. +- agent-ops 구조, 규칙, 스킬, 로드맵, 런타임 책임 경계를 설계하거나 수정할 때만 `agent-ops/rules/common/philosophy.md`를 읽는다. **세션 최초 1회 아래 파일을 순서대로 반드시 읽는다.** 파일이나 디렉터리가 없는 항목은 건너뛴다. 그외에 스킵은 금지한다. diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index ddc59d3..b961ac0 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, 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, moves the task to archive, and routes m- milestone task groups to update-roadmap; WARN/FAIL immediately writes follow-up PLAN/CODE_REVIEW files. Never stop after verdict append. +description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, 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, moves the task to archive, and reports m-prefixed completion metadata for runtime; WARN/FAIL immediately writes follow-up PLAN/CODE_REVIEW files. Never stop after verdict append. --- # Code Review @@ -19,7 +19,7 @@ plan skill -> implementation -> code-review skill - Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`. - Finalize every selected active review: append one verdict, archive the active review and plan files, then create exactly one next state before reporting. -- Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-`, route the completed evidence to `update-roadmap`; `WARN` or `FAIL` writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`. +- 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` writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`. - Do not ask for confirmation before WARN/FAIL follow-up files. If details are uncertain, 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, resume at Step 5 and finish finalization first. @@ -56,10 +56,11 @@ Multi-plan runtime contract: Milestone task group contract: - `agent-task/m-/` is reserved for Milestone-linked work created by the plan skill. -- Do not treat normal task groups that do not start with `m-` as roadmap update targets. +- Do not treat normal task groups that do not start with `m-` as runtime milestone completion targets. - For a selected task path, parse only the first path segment as `{task_group}`. If it matches `^m-[a-z0-9][a-z0-9-]*$`, strip `m-` to get ``. -- Resolve the target Milestone by matching exactly one active file at `agent-ops/roadmap/phase/*/milestones/.md`. Do not search `agent-ops/roadmap/archive/**` for routing. -- If no active Milestone or multiple active Milestones match, do not guess. Finish code review finalization and report that roadmap update needs manual target selection. +- Do not read or modify `agent-ops/roadmap/**` for milestone routing during code-review finalization. +- Do not call `update-roadmap` from this skill. The runtime consumes the PASS completion event, checks current state, resolves the active Milestone, and calls `update-roadmap` if needed. +- For `m-` PASS tasks, report the original active task path, final archive path, complete log path, task group, and milestone slug so the runtime has deterministic event inputs. Review routing rules: @@ -216,7 +217,7 @@ task={task_name}, plan={N}, tag={TAG} 1. 판정을 append한다. 2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다. 3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 다음 active plan/review 파일을 즉시 작성한다. -4. PASS이고 task group이 `m-`이면 `update-roadmap` 요청 또는 target 불명확 보고를 완료한다. +4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. 5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. --- @@ -243,7 +244,7 @@ task={task_name}, plan={N}, tag={TAG} - [ ] 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이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. -- [ ] PASS이고 task group이 `m-`이면 active Milestone 경로를 폴더명으로 해석하고 `update-roadmap` 요청 또는 target 불명확 보고를 완료한다. +- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. - [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. - [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. @@ -307,17 +308,17 @@ After Step 6: - If verdict is `PASS`, determine archive month from the current completion date as `YYYY/MM`, create the needed archive parent directories, then move the selected active task directory `agent-task/{task_name}/` to `agent-task/archive/YYYY/MM/{task_name}/`. For split work, the selected active task directory is the subtask directory, and the archive must preserve the task group path, e.g. `agent-task/refactoring/01_core/` moves to `agent-task/archive/YYYY/MM/refactoring/01_core/`. - Do not overwrite an existing archive directory. If `agent-task/archive/YYYY/MM/{task_name}/` already exists, append the next numeric suffix to the final path segment: single-plan `agent-task/archive/YYYY/MM/{task_group}_1/`, split-plan `agent-task/archive/YYYY/MM/{task_group}/{subtask_dir}_1/`, and so on. - After moving a split subtask, remove the active parent `agent-task/{task_group}/` only if it is empty. If sibling subtask directories or other files remain, leave the parent task group in place. -- If verdict is `PASS` and `{task_group}` matches `m-`, resolve `agent-ops/roadmap/phase/*/milestones/.md` after the task archive move. If exactly one active Milestone matches, run the `update-roadmap` flow with `origin-task=agent-task/{task_name}` from the original active task path and evidence from the PASS verdict, `complete.log`, and final archive path. Include archived plan/review log paths as evidence links; do not require them for target routing. Let `update-roadmap` update the Milestone Task/criteria and decide whether the Milestone should move to `[검토중]`. -- If the `m-` target has zero or multiple active Milestone matches, do not read archive roadmap files or guess from content. Report the unresolved roadmap target after completing code-review finalization. +- If verdict is `PASS` and `{task_group}` matches `m-`, do not resolve the roadmap target and do not call `update-roadmap`. Report completion event metadata after the task archive move: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=`, final archive path, `complete.log` path, and archived plan/review log paths. +- The runtime consumes that completion event, checks current state, resolves `agent-ops/roadmap/phase/*/milestones/.md`, and calls `update-roadmap` if needed. - `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-` task group when the original task was Milestone-linked. - For `PASS`, open the moved `agent-task/archive/YYYY/MM/{final_task_name}/code_review_{review_lane}_GNN_N.log`, where `{final_task_name}` is the archived task path, including `{task_group}/` for split work. - 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, for `PASS` the final task archive move, and for `m-*` PASS tasks the roadmap update request or unresolved-target report. +- Only report after the archived review log has the verdict, applicable checked review-only checklist, required next-state files, for `PASS` the final task archive move, and for `m-*` PASS tasks the completion event metadata. -Report Required/Suggested counts, archive names, the final task archive path for `PASS` or new plan path for `WARN`/`FAIL`, and any `m-*` roadmap routing result. +Report Required/Suggested counts, archive names, the final task archive path for `PASS` or new plan path for `WARN`/`FAIL`, and any `m-*` runtime completion event metadata. ## Review Dimensions @@ -346,7 +347,7 @@ Report Required/Suggested counts, archive names, the final task archive path for - `plan_{build_lane}_GNN_M.log` exists. - No active `.md` files remain after PASS. - 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/` with task-group path preserved for split work. -- PASS milestone task group: `m-` was routed to `update-roadmap`, or unresolved target was reported without guessing. +- 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: 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/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 0815986..2a7fba3 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-{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. Milestone-linked work uses a reserved m-prefixed task group so code-review can route PASS results to update-roadmap. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding. +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. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding. --- # Plan @@ -13,6 +13,7 @@ Create the planning artifacts for the implementation loop: plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md code-review skill -> verdict + archive, complete.log, and PASS task-directory archive move or new follow-up plan/review files +runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call ``` ## Workflow Contract @@ -62,7 +63,7 @@ Task directory naming rules: - A normal single-plan task uses `agent-task/{task_group}/` with a short snake_case category name, e.g. `agent-task/refactoring/`. - If the plan is based on a selected active Milestone, use `agent-task/m-/` as the task group. Do not include the Phase slug, Epic id, Task id, or a separate task slug in the task group. - `m-` is a reserved top-level task group namespace for Milestone-linked work. Non-roadmap tasks must not use `m-`. -- Runtime routing for `m-*` reads only the top-level `{task_group}` name. It resolves `` by matching exactly one active file at `agent-ops/roadmap/phase/*/milestones/.md`; archive paths are not target candidates. +- Runtime completion-event routing for `m-*` reads only the top-level `{task_group}` name. It resolves `` by matching exactly one active file at `agent-ops/roadmap/phase/*/milestones/.md`; archive paths are not target candidates. - When split gates require decomposition, create one shared category folder and multiple subtask directories under it. Each subtask 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 `agent-task/{task_group}/{subtask_dir}/` folders, not multiple plan files inside one folder. - Multi-plan subtask directory names must start with a stable two-digit task index. The index must increase across sibling subtask directories for sorting, but it is not a serial execution dependency. @@ -276,7 +277,7 @@ task={task_name}, plan={N}, tag={TAG} 1. 판정을 append한다. 2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다. 3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 다음 active plan/review 파일을 즉시 작성한다. -4. PASS이고 task group이 `m-`이면 `update-roadmap` 요청 또는 target 불명확 보고를 완료한다. +4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. 5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. --- @@ -303,7 +304,7 @@ task={task_name}, plan={N}, tag={TAG} - [ ] 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이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. -- [ ] PASS이고 task group이 `m-`이면 active Milestone 경로를 폴더명으로 해석하고 `update-roadmap` 요청 또는 target 불명확 보고를 완료한다. +- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. - [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. - [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index 30ca174..c22280d 100644 --- a/agent-ops/skills/common/update-roadmap/SKILL.md +++ b/agent-ops/skills/common/update-roadmap/SKILL.md @@ -1,7 +1,7 @@ --- name: update-roadmap version: 1.17.0 -description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, m- task group PASS 반영, 완료 후보 검토중 전환, 승인된 archive 이동을 처리한다. +description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동을 처리한다. --- # 로드맵 업데이트 @@ -23,7 +23,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `필수 - Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때 - Phase 완료, 보류, 폐기, 신규 추가가 필요할 때 - 완료 또는 폐기된 Phase/Milestone을 archive로 이동해야 할 때 -- `code-review`가 `m-` task group의 PASS 결과를 Milestone에 반영해야 할 때 +- 런타임이 `m-` task group의 PASS 완료 이벤트를 Milestone에 반영해야 할 때 - 특정 기능이나 작업을 새 Milestone, 기존 Milestone의 Epic, 기존 Epic의 Task 중 적절한 위치에 추가해야 할 때 - 활성 Phase/Milestone 창에 포함할 목록이 달라졌을 때 - 기존 로드맵을 `phase//PHASE.md` scaffold로 마이그레이션하거나 표준화해야 할 때 @@ -43,7 +43,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `필수 - `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택) - `review-state`: 완료 리뷰 상태. `요청됨` / `승인됨` / `보완 필요` / `보류` / `폐기` 중 하나 (선택) - `review-comment`: 완료 리뷰에 남길 사용자 확인, 보완, 보류, 폐기 방향성 (선택) -- `origin-task`: `agent-task/m-` 또는 `agent-task/m-/` 형식의 원래 active task 경로. archive 이동 후 호출하더라도 routing에는 이 원래 경로를 사용한다 (선택) +- `origin-task`: 런타임 완료 이벤트가 전달한 `agent-task/m-` 또는 `agent-task/m-/` 형식의 원래 active task 경로. 이벤트가 최종 archive 경로만 갖고 있으면 런타임이 이 형식으로 정규화해 전달한다 (선택) - `archive-date`: Phase/Milestone 아카이브 날짜. 없으면 현재 날짜를 사용한다 (선택) ## 표준 구조 @@ -125,10 +125,10 @@ agent-ops/roadmap/ ## Milestone task group 연동 -- `origin-task`에서 `agent-task/` 다음 첫 path segment가 `m-`이면 Milestone 기반 plan/review 완료에서 온 요청으로 본다. `origin-task`는 archive 이동 전 active task 경로를 우선 사용한다. +- 런타임 완료 이벤트의 `origin-task`에서 `agent-task/` 다음 첫 path segment가 `m-`이면 Milestone 기반 plan/review 완료에서 온 요청으로 본다. `origin-task`는 archive 이동 전 active task 경로 또는 런타임이 그 형태로 정규화한 경로를 사용한다. - ``는 활성 `agent-ops/roadmap/phase/*/milestones/.md`에서 정확히 하나만 찾아야 한다. archive Milestone은 target 후보가 아니다. - target이 없거나 둘 이상이면 Milestone 내용을 추정해 수정하지 말고 target 불명확으로 보고한다. -- target이 확정되면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 해당 Milestone의 Epic/Task와 완료 기준을 갱신한다. target routing 자체는 파일 내용이 아니라 `m-` task group으로만 결정한다. +- target이 확정되면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 해당 Milestone의 Epic/Task와 완료 기준을 갱신한다. target routing 자체는 완료 이벤트의 `m-` task group으로만 결정한다. - 갱신 후 필수 Epic/Task와 완료 기준이 모두 충족되면 `[검토중]` 전환과 `완료 리뷰` 요청 규칙을 적용한다. ## 삽입 단위 정책 @@ -213,7 +213,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 1. **갱신 범위 결정** - 요청에서 mode, 대상 Phase/Milestone, placement, placement-unit을 추론한다. - - `origin-task`의 task group이 `m-`이면 `target-milestone`을 활성 Milestone 경로 매칭으로 확정한다. + - 런타임 완료 이벤트의 `origin-task` task group이 `m-`이면 `target-milestone`을 활성 Milestone 경로 매칭으로 확정한다. - 구조 전환, 템플릿 보정, current 동기화는 `sync`로 본다. - 사용자 승인 이후의 완료/폐기 이동은 `archive`로 본다. - 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다. @@ -273,7 +273,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 자동 배치한 경우 비교한 후보와 선택 근거 - current.md 활성 창 변경 사항 - 완료 리뷰 상태와 사용자 확인 필요 항목 - - `origin-task`가 `m-`이면 원래 active task 경로와 매칭된 target Milestone 또는 target 불명확 사유 + - 런타임 완료 이벤트의 `origin-task`가 `m-`이면 원래 active task 경로와 매칭된 target Milestone 또는 target 불명확 사유 - archive 모드이면 이동 경로와 남긴 링크 - 확인 필요로 남긴 항목 @@ -303,7 +303,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 템플릿 보정: - 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약> - 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기> -- m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확> +- runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확> - 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약> - 아카이브: <변경 없음 | 이동 경로와 남긴 링크> - 상태: <변경 없음 | 이전 -> 이후>