From 382b8db34d619a38a2697bdc9dd11300d1f72552 Mon Sep 17 00:00:00 2001 From: toki Date: Tue, 16 Jun 2026 10:54:34 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.140 --- .clinerules | 1 + .cursorrules | 1 + AGENTS.md | 1 + CLAUDE.md | 1 + GEMINI.md | 1 + agent-ops/.version | 2 +- agent-ops/rules/common/rules-roadmap.md | 24 +- agent-ops/rules/common/rules.md | 1 + .../_templates/roadmap-current-template.md | 1 + .../_templates/roadmap-milestone-template.md | 6 + .../roadmap-position-report-template.md | 2 + .../common/_templates/roadmap-sdd-template.md | 85 ++++++++ .../roadmap-sdd-user-review-template.md | 37 ++++ .../common/_templates/roadmap-template.md | 3 + .../common/analyze-roadmap-position/SKILL.md | 8 +- agent-ops/skills/common/code-review/SKILL.md | 8 +- .../templates/complete-log-template.md | 9 + .../skills/common/create-roadmap/SKILL.md | 24 +- agent-ops/skills/common/plan/SKILL.md | 20 +- agent-ops/skills/common/roadmap-sdd/SKILL.md | 206 ++++++++++++++++++ agent-ops/skills/common/router.md | 7 + .../skills/common/update-roadmap/SKILL.md | 38 +++- 22 files changed, 474 insertions(+), 12 deletions(-) create mode 100644 agent-ops/skills/common/_templates/roadmap-sdd-template.md create mode 100644 agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md create mode 100644 agent-ops/skills/common/roadmap-sdd/SKILL.md diff --git a/.clinerules b/.clinerules index a6ece7e..94dffdd 100644 --- a/.clinerules +++ b/.clinerules @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/.cursorrules b/.cursorrules index a6ece7e..94dffdd 100644 --- a/.cursorrules +++ b/.cursorrules @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/AGENTS.md b/AGENTS.md index a6ece7e..94dffdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/CLAUDE.md b/CLAUDE.md index a6ece7e..94dffdd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/GEMINI.md b/GEMINI.md index a6ece7e..94dffdd 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/agent-ops/.version b/agent-ops/.version index 88cf65e..d24bae7 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.137 +1.1.140 diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index 0e0da16..a6a2035 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -11,6 +11,9 @@ - 완료된 Phase는 scaffold 그대로 `agent-roadmap/archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 `archive/phase//milestones/` 아래에 둔다. - 진행중 Phase 안에서 완료된 Milestone은 활성 `PHASE.md`에 짧은 archive 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase//milestones/`로 이동한다. - archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. +- 큰 Milestone의 설계 게이트는 `agent-roadmap/sdd///SDD.md`에 둔다. +- SDD 사용자 리뷰가 필요하면 같은 디렉터리에 `USER_REVIEW.md`를 둔다. 해결된 리뷰는 `user_review_N.log`로 남긴다. +- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd///`로 이동한다. ## Runtime Action Boundary @@ -28,7 +31,8 @@ - 일반 작업에서는 `ROADMAP.md`를 읽지 않는다. - 일반 작업에서는 `agent-roadmap/archive/**`를 읽지 않는다. - 기능 추가, 구조 변경, 구현 계획 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다. -- 로드맵 현지점 확인은 로컬 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽는다. +- 선택한 Milestone의 `구현 잠금`에 `SDD: 필요`가 있으면 `agent-roadmap/sdd///SDD.md`와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부를 확인한다. +- 로드맵 현지점 확인은 로컬 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태를 기본으로 읽고, `SDD: 필요`이면 SDD 상태/잠금/사용자 리뷰 요약도 함께 확인한다. - `ROADMAP.md`는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다. - 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다. @@ -72,6 +76,10 @@ - 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선이나 구현 가정으로 기록한다. - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. - 선택한 Milestone에 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 사용자에게 확인한다. +- `구현 잠금`은 SDD gate를 포함할 수 있다. `SDD: 필요`이면 SDD 상태가 `[승인됨]`이고 `SDD 잠금`이 `해제`이며 SDD `USER_REVIEW.md`가 없어야 구현 잠금 해제 후보가 된다. +- SDD 사용자 리뷰는 채팅 질문으로 직접 처리하지 않고 `agent-roadmap/sdd///USER_REVIEW.md`에 남긴다. 사용자의 답변이 반영되면 `user_review_N.log`로 이동한다. +- SDD가 필요한데 문서가 없거나 gate 정보가 부족하면 `plan` 스킬은 `roadmap-sdd` pre-plan gate로 SDD 작성/확인을 먼저 수행한다. 그 결과 SDD 잠금이 남거나 SDD 사용자 리뷰가 열려 있으면 구현 계획을 만들지 않는다. +- SDD가 불필요한 Milestone은 `SDD: 불필요`과 짧은 사유를 `구현 잠금`에 남긴다. - 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 표준선으로 처리 가능한 작업을 막지 않는다. - 잠금 상태를 바꾸더라도 `기능` Task를 자동 완료 처리하지 않는다. - `[스케치]` 상태의 Milestone은 `구현 잠금`이 `해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 `[계획]`으로 승격해야 한다. @@ -102,6 +110,18 @@ - 잠금 해제 조건 충족 여부만 확인할 때는 `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 "" ""`를 사용한다. - checker exit code는 `0=true`, `1=false`, `2=설정/입력/파싱 오류`로 해석한다. +## SDD 게이트 + +- SDD는 큰 Milestone의 설계 계약을 로드맵에 녹이는 하위 문서다. 별도 작업 관리 체계로 쓰지 않는다. +- SDD 작성, 갱신, gate 확인, 사용자 리뷰 대기, 잠금 해제는 `agent-ops/skills/common/roadmap-sdd/SKILL.md`를 따른다. +- SDD는 cross-repo 계약, 외부 provider 쓰기, 상태 머신, idempotency/retry/identity map, API/proto/config/env/schema, field smoke, 사용자 승인 gate에 영향을 주는 Milestone에만 강제한다. +- 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task의 `검증:`만으로 닫히는 작업에는 SDD를 강제하지 않는다. +- SDD 문서는 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 표준 섹션, 순서, 필수 표 컬럼을 유지해야 한다. +- SDD의 `Acceptance Scenarios`는 Milestone 기능 Task id와 연결되어야 한다. +- SDD의 `Evidence Map`은 plan/code-review/complete.log의 `Spec Targets`와 `Spec Completion`으로 검증 가능해야 한다. +- 외부 API 또는 프로젝트 간 호출 계약 원문은 `agent-contract/`에 두고 SDD에는 링크만 남긴다. +- SDD 전체 검토를 사용자에게 던지지 않는다. 사용자만 결정할 source of truth, 상태 전이, 책임 경계, 권한, 비용, 데이터 보존, 실패 처리만 `USER_REVIEW.md`로 분리한다. + ## Epic과 Task id - Milestone 문서의 실행 체크리스트는 `기능` 섹션 하나로 작성한다. 새 Milestone이나 갱신 범위에 포함된 Milestone에는 별도 `완료 기준` 섹션을 만들지 않는다. @@ -126,6 +146,7 @@ - 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다. - `code-review`에서 `m-` 작업이 PASS되면 roadmap을 직접 수정하거나 `update-roadmap`을 직접 호출하지 않는다. - 런타임은 PASS 완료 이벤트의 task group에서 `m-`를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback 흐름을 호출한다. 단, Milestone 기능 Task 체크는 `complete.log`에 `Roadmap Completion` 섹션과 명시 Task id가 있을 때만 수행하고, 섹션이 없으면 no-op으로 둔다. +- SDD 대상 Milestone은 런타임 완료 이벤트의 `complete.log`에 `Spec Completion`이 있어야 roadmap Task 체크 후보가 된다. SDD `Evidence Map`은 `Spec Completion` 검증 기준이며 단독 대체 근거가 아니다. 단, 사용자가 명시적으로 evidence를 전달한 수동 `update-roadmap` 갱신에서는 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다. - 런타임 완료 이벤트가 최종 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`를 남기고 사용자 판단을 기다린다. @@ -152,6 +173,7 @@ - `[검토중]` Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다. - Phase 아카이브 대상은 `agent-roadmap/archive/phase//PHASE.md`와 같은 scaffold로 이동한다. - Milestone 아카이브 대상은 `agent-roadmap/archive/phase//milestones/.md`로 이동한다. +- 활성 SDD가 있으면 `agent-roadmap/archive/sdd///`로 함께 이동한다. SDD `USER_REVIEW.md`가 남아 있으면 먼저 해결한다. - Milestone 아카이브 전에는 이동 전 활성 경로 identity로 `.agent-roadmap-sync/locks.yaml`을 확인한다. 해당 identity가 `rely-on.target`이면 `[완료]` 상태에서 `enable`로 동기화하고, 해당 identity가 `locked`이면 의존 조건 충족 여부를 보고하며, 어느 쪽에도 없으면 `관련 lock 없음`으로 보고한다. - 아카이빙할 때는 활성 `ROADMAP.md` 또는 활성 `PHASE.md`에 archive 문서 링크와 짧은 요약만 남긴다. - 아카이브된 Phase/Milestone은 로컬 `current.md`에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다. diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index a6ece7e..94dffdd 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -33,6 +33,7 @@ - agent-contract 생성/갱신, 계약 문서 작성/정리, 제공/소비 계약 포인터 관리 - README 생성 - 로드맵/마일스톤 생성·갱신 +- SDD 작성/갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제 - 로드맵 현지점 / 현재 작업 지점 확인 - 계획 작성 / plan 생성 - 코드 리뷰 / review 진행 diff --git a/agent-ops/skills/common/_templates/roadmap-current-template.md b/agent-ops/skills/common/_templates/roadmap-current-template.md index 3e4b94b..a380ba6 100644 --- a/agent-ops/skills/common/_templates/roadmap-current-template.md +++ b/agent-ops/skills/common/_templates/roadmap-current-template.md @@ -26,4 +26,5 @@ - 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. - 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다. - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다. +- 선택된 Milestone에 `SDD: 필요`가 있으면 `agent-roadmap/sdd///SDD.md`가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD `USER_REVIEW.md`가 없어야 구현이나 구현 계획을 시작한다. - 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다. diff --git a/agent-ops/skills/common/_templates/roadmap-milestone-template.md b/agent-ops/skills/common/_templates/roadmap-milestone-template.md index 669bc84..c698411 100644 --- a/agent-ops/skills/common/_templates/roadmap-milestone-template.md +++ b/agent-ops/skills/common/_templates/roadmap-milestone-template.md @@ -32,6 +32,12 @@ ## 구현 잠금 - 상태: <잠금 | 해제> +- SDD: <필요 | 불필요> +- SDD 문서: <없음 | `agent-roadmap/sdd///SDD.md`> +- SDD 사유: <필요/불필요 판정 근거 한 줄> +- 잠금 해제 조건: <없음 | 아래 체크리스트> + - [ ] + - [ ] - 결정 필요: <없음 | 아래 체크리스트> - [ ] <사용자만 결정할 수 있는 제품/범위/우선순위/책임 경계 질문> diff --git a/agent-ops/skills/common/_templates/roadmap-position-report-template.md b/agent-ops/skills/common/_templates/roadmap-position-report-template.md index ea057ea..818148b 100644 --- a/agent-ops/skills/common/_templates/roadmap-position-report-template.md +++ b/agent-ops/skills/common/_templates/roadmap-position-report-template.md @@ -6,8 +6,10 @@ - [Phase: ](agent-roadmap/phase//PHASE.md) - [Milestone: ](agent-roadmap/phase//milestones/.md) - [<상태>] <목표 또는 역할 한 줄> + - SDD: <불필요 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 확인 필요> - [Milestone: ](agent-roadmap/phase//milestones/.md) - [<상태>] <목표 또는 역할 한 줄> + - SDD: <불필요 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 확인 필요> ## 전체 Phase 흐름 diff --git a/agent-ops/skills/common/_templates/roadmap-sdd-template.md b/agent-ops/skills/common/_templates/roadmap-sdd-template.md new file mode 100644 index 0000000..0559e00 --- /dev/null +++ b/agent-ops/skills/common/_templates/roadmap-sdd-template.md @@ -0,0 +1,85 @@ +# SDD: + +## 위치 + +- Milestone: `agent-roadmap/phase//milestones/.md` +- Phase: `agent-roadmap/phase//PHASE.md` + +## 상태 + +[<초안 | 검토중 | 승인됨 | 대체됨 | 폐기>] + +## SDD 잠금 + +- 상태: <잠금 | 해제> +- 사용자 리뷰: <없음 | `USER_REVIEW.md`> +- 잠금 항목: + - [ ] [D01] <사용자만 결정할 source of truth, 상태 전이, 책임 경계, 범위, 권한, 비용, 실패 처리 항목> + +## 문제 / 비목표 + +- 문제: <이 SDD가 고정해야 하는 큰 작업의 모호함> +- 비목표: + - <이번 Milestone에서 의도적으로 다루지 않는 설계 범위> + +## Source of Truth + +| 영역 | 기준 | 메모 | +|------|------|------| +| Roadmap | `` | <장기 원장, 상태 반영 기준> | +| Code | `` | <구현 source of truth> | +| External Provider | <없음 또는 provider> | | +| User Decision | <없음 또는 D-id> | <사용자 결정이 필요한 기준> | + +## State Machine + +| 상태 | 진입 조건 | 다음 상태 | 근거 | +|------|-----------|-----------|------| +| | | | | + +## Interface Contract + +- 계약 원문: <없음 또는 `agent-contract/...` 링크> +- 입력: + - : <의미> +- 출력: + - : <의미> +- 금지: + - <하면 안 되는 동작> + +## Acceptance Scenarios + +| ID | Milestone Task | Given | When | Then | +|----|----------------|-------|------|------| +| S01 | `` | <상태/입력> | <행동> | <관찰 가능한 결과> | + +## Evidence Map + +| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 | +|----------|-------------------|------------------|---------------------------| +| S01 | | `agent-task/m-/...` | | + +## Cross-repo Dependencies + +- 없음 + + + +## Drift Check + +- [ ] Milestone 기능 Task와 Acceptance Scenario가 일치한다. +- [ ] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다. +- [ ] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다. +- [ ] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다. + +## 사용자 리뷰 이력 + +- 없음 + +## 작업 컨텍스트 + +- 표준선: <기존 구조, 도메인 rule, 플랫폼 관례> +- 후속 SDD: <없음 또는 SDD 경로> diff --git a/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md b/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md new file mode 100644 index 0000000..fc4f47b --- /dev/null +++ b/agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md @@ -0,0 +1,37 @@ +# SDD User Review + +## 상태 + +요청됨 + +## 검토 대상 + +- SDD: `agent-roadmap/sdd///SDD.md` +- Milestone: `agent-roadmap/phase//milestones/.md` + +## 사용자 결정 항목 + +### [D01] <결정 제목> + +- 결정 필요: <사용자만 결정할 질문> +- 추천안: +- 대안: <없음 또는 대안> +- 영향: <이 결정이 상태 전이, provider 쓰기, 권한, 비용, scope, 실패 처리에 미치는 영향> +- 적용 위치: + - SDD: `
` + - Milestone: `` + +## 승인 항목 + +- [ ] 위 결정 항목을 승인했다. +- [ ] SDD 잠금 해제를 승인했다. + +## 답변 기록 + +- 없음 + +## 해결 조건 + +- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다. +- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다. +- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다. diff --git a/agent-ops/skills/common/_templates/roadmap-template.md b/agent-ops/skills/common/_templates/roadmap-template.md index b42dd53..c3b6df1 100644 --- a/agent-ops/skills/common/_templates/roadmap-template.md +++ b/agent-ops/skills/common/_templates/roadmap-template.md @@ -29,6 +29,8 @@ - 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. - 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다. - 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다. +- 큰 Milestone의 설계 게이트는 `agent-roadmap/sdd///SDD.md`에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다. +- SDD 사용자 리뷰가 필요하면 `agent-roadmap/sdd///USER_REVIEW.md`로 남기며, 해결 후 `user_review_N.log`로 보존한다. - `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다. - `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다. - 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 `[완료]`로 전환한다. @@ -38,5 +40,6 @@ - `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다. - 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. - 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. +- 선택된 Milestone에 `SDD: 필요`가 있으면 SDD 상태가 `[승인됨]`이고 SDD 잠금이 해제되었으며 SDD 사용자 리뷰가 없어야 구현 계획을 만들 수 있다. - 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다. - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다. diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index a8990e6..62a701a 100644 --- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md +++ b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md @@ -27,7 +27,7 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - [ ] 로드맵이 있으면 `ROADMAP.md`의 `Phase 흐름`을 확인 - [ ] 로컬 `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인 - [ ] 활성 Phase 문서의 `Milestone 흐름` 확인 -- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`만 확인 +- [ ] 활성 Milestone 문서의 제목, `목표`, `상태`, `구현 잠금`의 SDD 요약만 확인 ## 실행 절차 @@ -43,14 +43,15 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA 5. current의 활성 Phase 경로를 열고 `Milestone 흐름`을 읽는다. - 각 Milestone은 상태, 이름, 링크만 남긴다. - current의 활성 Milestone과 일치하는 항목에 `← 현재 후보` 표시를 붙인다. -6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`만 읽는다. +6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 요약만 읽는다. + - `SDD: 필요`이면 SDD 경로와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부만 확인한다. - `기능`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`는 사용자가 명시적으로 요청한 경우에만 읽는다. 7. 결과를 템플릿 형식 그대로 출력한다. ## 실행 결과 검증 - [ ] `roadmap-position-report-template.md`의 출력 구조를 유지했는가 -- [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태만 기본으로 읽었는가 +- [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 요약만 기본으로 읽었는가 - [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가 - [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가 - [ ] 코드 파일, 테스트 파일, `git status`, `git diff`를 기본 동작에서 읽지 않았는가 @@ -63,6 +64,7 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다. - current가 여러 Milestone을 가리키면 breadcrumb와 Milestone 흐름에 모두 표시한다. - 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓴다. +- 현재 후보에 `SDD: 필요`가 있으면 역할 태그에 `SDD 잠금`, `SDD 사용자 리뷰`, `SDD 승인됨` 중 하나를 붙인다. - 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다. ## 금지 사항 diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index ba444f2..90fff3b 100644 --- a/agent-ops/skills/common/code-review/SKILL.md +++ b/agent-ops/skills/common/code-review/SKILL.md @@ -153,6 +153,7 @@ Before writing the verdict: - Compare actual source files against every planned checklist item. - Compare the plan `구현 체크리스트` and review stub `구현 체크리스트`; repair non-behavioral drift when implementation remains judgeable. +- If the plan or review stub has `Spec Targets`, read the referenced SDD and compare implementation evidence against the listed Acceptance Scenario ids and Evidence Map. - Directly repair obvious non-behavioral source nits when safe: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change. - 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; repair clear artifact drift when evidence supports completion. @@ -170,7 +171,7 @@ Append `코드리뷰 결과` to the active `CODE_REVIEW-*-G??.md`. Required fields: - `종합 판정`: exactly `PASS`, `WARN`, or `FAIL`. -- `차원별 평가`: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, plan deviation, verification trust. +- `차원별 평가`: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, plan deviation, verification trust. If `Spec Targets` exists, also include spec conformance. - `발견된 문제`: `없음`, or bullets using `Required`, `Suggested`, or `Nit` with `file:line` and a concrete fix. - `다음 단계`: keep only the matching PASS, WARN/FAIL follow-up, or USER_REVIEW line. @@ -218,6 +219,7 @@ Complete log template: - Do not leave placeholders in `complete.log`. - If the task did not close through `USER_REVIEW.md`, remove the optional user-review row from the `루프 이력` table. - If the archived plan or review log contains `Roadmap Targets`, copy it into `complete.log` as `Roadmap Completion`. Include the Milestone path, completed Task ids, archived plan/review log paths, and verification evidence. If there is no `Roadmap Targets` section, remove the optional `Roadmap Completion` template section entirely and do not invent roadmap targets. +- If the archived plan or review log contains `Spec Targets`, copy it into `complete.log` as `Spec Completion`. Include the SDD path, completed Acceptance Scenario ids, archived plan/review log paths, and verification evidence. If there is no `Spec Targets` section, remove the optional `Spec Completion` template section entirely. - 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`. @@ -255,6 +257,7 @@ If the user-review gate does not trigger, write new routed plan/review files usi - The follow-up plan's implementer instructions and review stub must forbid direct user prompts and 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. - If the archived plan had `Roadmap Targets` and the follow-up still works toward the same Milestone Task completion, copy that section into the follow-up plan and review stub. If the follow-up intentionally no longer claims roadmap Task completion, omit the section and explain why in the follow-up plan `범위 결정 근거`. +- If the archived plan had `Spec Targets` and the follow-up still works toward the same SDD Acceptance Scenario completion, copy that section into the follow-up plan and review stub. If the follow-up no longer claims scenario completion, omit it and explain why in `범위 결정 근거`. Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent): @@ -278,6 +281,7 @@ date={YYYY-MM-DD} task={task_name}, plan={N}, tag={TAG} {copy the follow-up plan's Roadmap Targets section exactly if present; omit this block if the follow-up plan has no Roadmap Targets} +{copy the follow-up plan's Spec Targets section exactly if present; omit this block if the follow-up plan has no Spec Targets} ## 이 파일을 읽는 리뷰 에이전트에게 @@ -383,6 +387,7 @@ Sections and their ownership: |------|--------|------| | 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하거나 실행하지 않음 | | Roadmap Targets | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음; PASS 시 code-review가 `complete.log`의 `Roadmap Completion`으로 복사 | +| Spec Targets | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음; PASS 시 code-review가 `complete.log`의 `Spec Completion`으로 복사 | | 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 | | 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 | | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | @@ -445,6 +450,7 @@ Report Required/Suggested counts, archive names, the final task archive path for - PASS or user-review-resolved 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-` completion event metadata was reported for runtime; roadmap was not modified by code-review. - PASS with `Roadmap Targets`: `complete.log` contains `Roadmap Completion` with Milestone path, Task ids, archived plan/review evidence, and verification evidence. +- PASS with `Spec Targets`: `complete.log` contains `Spec Completion` with SDD path, Acceptance Scenario ids, archived plan/review evidence, and verification evidence. - PASS without `Roadmap Targets`: `complete.log` omits `Roadmap Completion` and reported metadata says `roadmap-completion=none`. - 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`. 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 index cadf8d7..21c7b71 100644 --- a/agent-ops/skills/common/code-review/templates/complete-log-template.md +++ b/agent-ops/skills/common/code-review/templates/complete-log-template.md @@ -32,6 +32,15 @@ - `{task-id}`: PASS; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}` - Not completed task ids: 없음 +## Spec Completion + +{optional; include only when archived plan/review had Spec Targets. Remove this entire section when there are no Spec Targets.} + +- SDD: `{agent-roadmap/sdd///SDD.md}` +- Completed scenario ids: + - `{scenario-id}`: PASS; task=`{task-id}`; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}` +- Not completed scenario ids: 없음 + ## 잔여 Nit - 없음 diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md index dc26686..ee604e5 100644 --- a/agent-ops/skills/common/create-roadmap/SKILL.md +++ b/agent-ops/skills/common/create-roadmap/SKILL.md @@ -38,12 +38,21 @@ agent-roadmap/ PHASE.md milestones/ .md + sdd/ + / + / + SDD.md + USER_REVIEW.md archive/ phase/ / PHASE.md milestones/ .md + sdd/ + / + / + SDD.md ``` | 파일 | 역할 | @@ -52,7 +61,10 @@ agent-roadmap/ | `agent-roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 브랜치별 로컬 포인터 | | `agent-roadmap/phase//PHASE.md` | Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서 | | `agent-roadmap/phase//milestones/.md` | 일반 작업 시 읽는 Milestone 단위 목표, 스케치 승격 조건, 구현 잠금, 범위, 기능 Epic/Task 체크리스트, 범위 제외 항목 | +| `agent-roadmap/sdd///SDD.md` | 큰 Milestone의 source of truth, 상태 전이, interface, acceptance scenario, evidence map을 담는 설계 게이트 | +| `agent-roadmap/sdd///USER_REVIEW.md` | SDD에서 사용자만 결정할 항목이 있을 때 열리는 파일 기반 리뷰 gate | | `agent-roadmap/archive/phase//...` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다 | +| `agent-roadmap/archive/sdd///...` | 완료 또는 폐기된 Milestone의 SDD 스냅샷과 해결된 사용자 리뷰 로그 | ## 템플릿 @@ -60,6 +72,8 @@ agent-roadmap/ - `current.md`는 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식을 따른다. - `PHASE.md`는 `agent-ops/skills/common/_templates/roadmap-phase-template.md` 형식을 따른다. - Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 따른다. +- SDD 본문은 `agent-ops/skills/common/_templates/roadmap-sdd-template.md` 형식을 따른다. +- SDD 사용자 리뷰는 `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md` 형식을 따른다. - `ROADMAP.md`에는 Milestone 상세 체크리스트를 넣지 않는다. - `current.md`는 git 추적 대상이 아니며, 예시 파일을 `agent-roadmap/`에 따로 만들지 않는다. - `current.md`는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다. @@ -86,7 +100,10 @@ agent-roadmap/ - 새 Milestone은 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `구현 잠금`을 `잠금`으로 둔다. - 새 `[스케치]` Milestone은 `구현 잠금`을 `잠금`으로 둔다. - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. -- `구현 잠금`에는 상태와 `결정 필요` 체크리스트만 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다. +- `구현 잠금`에는 상태, SDD 필요 여부, 잠금 해제 조건, `결정 필요` 체크리스트를 적는다. 결정할 항목이 없으면 `결정 필요: 없음`으로 적는다. +- SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향. +- SDD가 불필요한 기준: 단일 repo 내부의 작은 리팩터링, 문서 정리, 테스트 보강, 작은 UI 보강, Milestone Task `검증:`만으로 닫히는 작업. +- SDD가 필요한 Milestone은 `SDD 문서` 경로를 `agent-roadmap/sdd///SDD.md`로 적고, SDD 잠금이 해제될 때까지 `구현 잠금`을 `잠금`으로 둔다. - 새 Milestone이 다른 프로젝트 Milestone 완료 전까지 잠겨야 하면 `구현 잠금`을 `잠금`으로 두고 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`에 entry를 만든다. 의존 대상 확정과 entry 형식은 `update-roadmap`의 프로젝트 간 잠금 규칙을 따른다. - `기능`은 Epic heading과 Task 체크리스트로 작성한다. - Epic heading은 `### Epic: [epic-id] <이름>` 형식으로 작성한다. @@ -103,6 +120,7 @@ agent-roadmap/ - [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인 - [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인 - [ ] `roadmap-template.md`, `roadmap-current-template.md`, `roadmap-phase-template.md`, `roadmap-milestone-template.md`를 읽어 최신 형식 확인 +- [ ] SDD가 필요한 Milestone 후보가 있으면 `roadmap-sdd-template.md`와 `roadmap-sdd-user-review-template.md` 위치를 확인 - [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `agent-ops/rules/common/rules-roadmap.md`를 읽도록 라우팅하는지 확인 ## 실행 절차 @@ -130,6 +148,7 @@ agent-roadmap/ - 완료된 Phase가 초기 구조에 포함되어야 하는 경우 `archive/phase//PHASE.md`로 만들고 `ROADMAP.md`에서 archive 경로를 가리킨다. - 완료된 Milestone이 진행중 Phase에 포함되어야 하는 경우 `archive/phase//milestones/.md`로 만들고 해당 활성 `PHASE.md`에서 archive 경로를 가리킨다. - archive `PHASE.md`는 Phase 자체가 완료/폐기된 경우에만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 둘 수 있다. + - SDD가 필요한 Milestone은 `구현 잠금`에 SDD 경로와 잠금 해제 조건을 적는다. SDD 본문은 사용자가 요청했거나 바로 구현 전 gate가 필요한 경우에만 만든다. - 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, 로컬 current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다. 5. **검증** @@ -138,6 +157,8 @@ agent-roadmap/ - Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다. - 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다. - `[스케치]` Milestone에 `승격 조건` 섹션이 있고 `구현 잠금`이 `잠금`인지 확인한다. + - 각 Milestone의 `구현 잠금`에 `SDD: 필요|불필요`와 판정 사유가 있는지 확인한다. + - `SDD: 필요` Milestone은 SDD 경로와 잠금 해제 조건이 있는지 확인한다. - Milestone 문서에 `완료 리뷰` 섹션이 있는지 확인한다. ## 출력 형식 @@ -152,6 +173,7 @@ agent-roadmap/ - 활성 Phase: - 활성 Milestone: - 구현 잠금: <잠금 Milestone N개 | 해제 Milestone N개> +- SDD gate: <필요 N개 | 불필요 N개 | 작성 N개 | 사용자 리뷰 N개> - Workspace 잠금: <생성/갱신 N개 | 없음> - 공통 로드맵 룰: <확인함 | 설치 필요 | 해당 없음> diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index 7d8dffa..7e02df2 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -150,7 +150,8 @@ If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G - `agent-roadmap/`이 있는데 `current.md`가 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만들거나, `ROADMAP.md`의 Phase 흐름과 관련 `PHASE.md`에서 후보를 고른 뒤 로컬 current를 채운다. current 없음만으로 일반 task routing으로 빠지지 않는다. - `current.md`가 `agent-roadmap/archive/**`를 가리키면 해당 문서는 읽지 말고 활성 Phase/Milestone이 아니라고 보고한다. - 선택한 Phase를 한 번 읽어 Phase 목표, Milestone 흐름, Phase 경계를 확인한다. -- 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. `승격 조건`은 `[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다. +- 선택한 Milestone을 한 번 읽어 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금, SDD 필요 여부를 확인한다. `승격 조건`은 `[스케치]`에서만 필수이며, `[계획]` 이상에서 섹션이 없으면 `없음`으로 본다. `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인하고, 그 결정 없이는 `PLAN-*-G??.md`, `CODE_REVIEW-*-G??.md`, file/API/package 수준 구현 단계를 확정하지 않는다. +- 선택한 Milestone에 `SDD: 필요`가 있으면 SDD 문서와 같은 디렉터리의 `USER_REVIEW.md` 존재 여부를 확인한다. SDD 문서가 없거나 gate 정보가 부족하면 같은 요청 안에서 `roadmap-sdd`의 `create` 또는 `check-gate` 절차를 pre-plan gate로 먼저 적용해 SDD와 Milestone 구현 잠금 정보를 보강한다. 사용자 결정이 필요한 항목이 나오면 `roadmap-sdd review-ready` 방식으로 `USER_REVIEW.md`를 남기고 plan 파일을 만들지 않는다. 기존 `USER_REVIEW.md`가 있거나 SDD 상태가 `[승인됨]`이 아니거나 `SDD 잠금`이 `잠금`이면 `resolve-review` 또는 SDD 잠금 해제가 필요하다고 보고하고 멈춘다. SDD가 `[승인됨]`, `SDD 잠금: 해제`, 사용자 리뷰 없음 상태일 때만 plan 파일을 만든다. - 선택한 Milestone에 legacy `필수 기능`/`완료 기준`이 분리되어 있으면 plan 작성 전에 roadmap preflight로 정규화한다. 흡수 가능한 기준은 관련 기능 Task 안의 선택적 `검증:` 또는 Task 설명으로 즉시 흡수하고, 어느 기능에도 붙지 않는 기준이 남으면 plan 파일을 만들지 말고 남은 기준과 필요한 사용자 판단을 구체적으로 보고한다. - 선택한 Phase 또는 Milestone 상태가 `[스케치]`이면 구현 계획 파일을 만들지 않는다. `[스케치]`는 컨셉 상태이므로 `update-roadmap`의 concretize 흐름으로 승격 조건, 결정 필요, 범위, 기능 Task를 정리해 `[계획]`으로 전환해야 한다고 보고한다. - Phase 또는 Milestone 후보가 여럿이면 요청 문장, 변경 경로 직접성, Milestone 상태, 구현 잠금, 선후 의존성, Phase/Milestone 흐름상 위치를 기준으로 1순위와 2순위를 추천하고 필요한 후보 문서만 읽어 범위를 좁힌다. @@ -162,6 +163,7 @@ If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G - 선택한 활성 Milestone 범위에 속하는 구현 계획이면 `{task_group}`을 `m-`로 정한다. ``는 선택한 Milestone 경로의 파일명에서 `.md`를 제거한 값이다. - 같은 Milestone에서 split work가 필요하면 기존 split 규칙 그대로 `agent-task/m-//` 아래에 계획 파일을 만든다. - Milestone 기능 Task 완료를 목표로 하는 계획이면 `Roadmap Targets` 섹션에 활성 Milestone 경로와 완료 대상 Task id를 고정한다. 이 섹션은 `complete.log`의 `Roadmap Completion` 근거로 복사되어 `update-roadmap`이 해당 Task만 체크하는 anchor가 된다. 이 섹션은 `{task_group}`이 해당 Milestone slug의 `m-`일 때만 쓴다. +- 승인된 SDD가 있는 Milestone 기능 Task 완료 계획이면 `Spec Targets` 섹션도 쓴다. SDD 경로, Acceptance Scenario id, Evidence Map 기대 근거를 고정한다. 이 섹션은 `complete.log`의 `Spec Completion` 근거로 복사된다. - Milestone 작업이 아니거나, Milestone 안의 조사/하위 구현처럼 특정 기능 Task 완료를 주장하지 않는 계획이면 `Roadmap Targets` 섹션을 쓰지 않는다. 섹션이 없으면 PASS 후에도 roadmap Task 체크를 하지 않는다. - `agent-roadmap/` 디렉터리가 없으면 기존 task routing 규칙대로 진행한다. @@ -171,7 +173,7 @@ Before choosing plan files or task directory names, apply the split decision pol ## Step 2 - Analyze Before Writing -Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed pre-plan file edits are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, plus `create-test` or `update-test` edits needed to make test rules usable for this plan. +Complete all items below before creating active plan/review files. Work through them in order; do not proceed to the next step until every checkbox is done. The only allowed pre-plan file edits are local `agent-roadmap/current.md` creation or `.gitignore` block repair needed for roadmap routing, `roadmap-sdd` pre-plan gate edits for a selected `SDD: 필요` Milestone, plus `create-test` or `update-test` edits needed to make test rules usable for this plan. - [ ] **Load test environment rules** — because implementation plans include verification, determine `test_env` before choosing verification commands. Use the user-specified environment when provided; otherwise use `local`. Check `agent-test//rules.md` and read it in full when present, even if it appears blank or skeleton. If it is absent, or present but structurally blank/skeleton, invoke `create-test` with `env=` when this repo can be edited, then re-read the generated or completed rules before writing the plan. If creation is not possible in the current task context, record the gap and fallback source; absence is not a user-review blocker by itself. - [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads. @@ -242,6 +244,16 @@ Required sections: - ``: - Completion mode: check-on-pass ``` +- `Spec Targets`: include this section only when the selected Milestone has an approved SDD and the plan claims completion for SDD acceptance scenarios. Omit it entirely when there is no SDD target. Format exactly: + +```markdown +## Spec Targets + +- SDD: `agent-roadmap/sdd///SDD.md` +- Acceptance scenarios: + - ``: task=``; evidence=`` +- Completion mode: spec-check-on-pass +``` - `분석 결과`: 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, test, and agent-test rule/profile file read during analysis, with path. - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test//rules.md` was present and read, every matched profile path read, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If agent-test is absent or unusable, explicitly say no agent-test rule was applied and whether `create-test` or `update-test` should later fill the gap. @@ -324,6 +336,7 @@ date={YYYY-MM-DD} task={task_name}, plan={N}, tag={TAG} {copy the plan's Roadmap Targets section exactly if present; omit this block if the plan has no Roadmap Targets} +{copy the plan's Spec Targets section exactly if present; omit this block if the plan has no Spec Targets} ## 이 파일을 읽는 리뷰 에이전트에게 @@ -429,6 +442,7 @@ Sections and their ownership: |---------|-------|------| | 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) | | Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS | +| Spec Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Spec Completion` only on PASS | | 구현 항목별 완료 여부 (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 | @@ -459,6 +473,8 @@ 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. - `Roadmap Targets` exists only when PASS should check explicit Milestone Task ids, the task group is `m-` for the listed Milestone path, and every listed Task id exists in the selected active Milestone. - If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too. +- If the selected Milestone has `SDD: 필요`, the SDD gate was checked before writing files. Missing or incomplete SDD was first routed through the `roadmap-sdd` pre-plan flow; active `USER_REVIEW.md`, non-approved SDD, or locked SDD blocks plan creation. +- `Spec Targets` exists only when the selected SDD is approved and the plan claims completion for explicit Acceptance Scenario ids. If `Spec Targets` exists in the plan, the review stub contains the identical section. - `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank state, matched profiles read, and any fallback verification source. - Dependent split plans record predecessor completion using active sibling `complete.log` or matching archived `complete.log`; ambiguous archive matches are not guessed. - Every plan item has problem, solution, checklist, test decision, and intermediate verification. diff --git a/agent-ops/skills/common/roadmap-sdd/SKILL.md b/agent-ops/skills/common/roadmap-sdd/SKILL.md new file mode 100644 index 0000000..2149613 --- /dev/null +++ b/agent-ops/skills/common/roadmap-sdd/SKILL.md @@ -0,0 +1,206 @@ +--- +name: roadmap-sdd +version: 1.0.0 +description: 로드맵 Milestone에 녹아 있는 SDD 설계 게이트를 판정, 생성, 갱신, 사용자 리뷰 대기, 잠금 해제, archive 처리할 때 사용한다. 사용자가 SDD, spec gate, 설계 게이트, SDD 필요 여부, SDD 승인 준비, SDD 사용자 리뷰, SDD 잠금 해제, SDD archive를 요청하거나, 큰 Milestone의 구현 잠금이 SDD 필요 상태일 때 사용한다. +--- + +# Roadmap SDD + +## 목적 + +큰 Milestone에서 로드맵만으로 부족한 계약, 상태 전이, 수용 시나리오, 검증 근거를 `agent-roadmap/sdd/` 아래에 기록한다. +SDD는 로드맵과 분리된 별도 운영물이 아니라 Milestone `구현 잠금`을 해제하기 위한 하위 설계 게이트다. + +## 모드 + +- `classify`: Milestone 또는 신규 작업 설명이 SDD 대상인지 판정한다. +- `create`: SDD 초안을 만든다. +- `update`: 기존 SDD를 갱신한다. +- `check-gate`: SDD 잠금, 사용자 리뷰, Acceptance Scenario, Evidence Map 연결성을 확인한다. +- `review-ready`: 사용자 결정이 필요한 항목을 `USER_REVIEW.md`로 만든다. +- `resolve-review`: 사용자의 답변을 SDD에 반영하고 `USER_REVIEW.md`를 `user_review_N.log`로 보낸다. +- `archive`: Milestone archive와 함께 SDD를 archive 경로로 이동할 준비 상태인지 확인한다. + +## 구조 + +```text +agent-roadmap/ + sdd/ + / + / + SDD.md + USER_REVIEW.md + user_review_0.log + archive/ + sdd/ + / + / + SDD.md + user_review_*.log +``` + +- `USER_REVIEW.md`는 필요한 경우에만 존재한다. +- `user_review_N.log`는 해결된 사용자 리뷰 기록이다. +- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd///`로 이동한다. +- SDD 경로는 같은 Milestone의 slug를 그대로 사용한다. 별도 SDD slug를 만들지 않는다. + +## 표준 형식 + +- `SDD.md`는 반드시 `agent-ops/skills/common/_templates/roadmap-sdd-template.md`의 top-level 섹션을 같은 순서로 사용한다. +- `Source of Truth`, `State Machine`, `Acceptance Scenarios`, `Evidence Map` 표는 템플릿의 컬럼을 유지한다. +- 값이 아직 없으면 섹션을 삭제하지 말고 `없음`, `확인 필요`, 또는 잠금 항목으로 남긴다. +- `update`는 기존 SDD의 내용을 갱신하더라도 표준 섹션과 순서를 유지한다. 누락된 표준 섹션이 있으면 먼저 복원한 뒤 변경을 반영한다. +- `check-gate`는 표준 섹션이나 필수 표 컬럼이 누락된 SDD를 `invalid`로 보고하고, plan gate 통과 대상으로 보지 않는다. +- SDD별 추가 설명은 `작업 컨텍스트` 또는 해당 표준 섹션 안에 넣고 임의 top-level 섹션을 늘리지 않는다. + +## SDD 대상 판정 + +아래 중 하나라도 해당하면 `SDD: 필요`로 판정한다. + +- cross-repo 계약 또는 프로젝트 간 source of truth가 있다. +- Plane, Jira, Mattermost 같은 외부 provider 상태를 변경한다. +- lifecycle, state machine, 사용자 승인 gate, archive 자동화, work item sync에 영향을 준다. +- idempotency, retry, identity map, revision 보존이 필요하다. +- API, proto, config, env, DB/schema, 이벤트 계약을 바꾼다. +- field smoke, 원격 runner, 사용자 소유 환경이 완료 근거의 일부다. +- 실패 처리 방식이 제품 판단, 보안, 비용, 권한, 데이터 보존에 영향을 준다. + +아래에만 해당하면 `SDD: 불필요`로 판정한다. + +- 단일 repo 내부의 작고 국소적인 리팩터링이다. +- 문서 정리, 테스트 보강, 작은 UI 보강이다. +- Milestone Task의 `검증:`과 일반 plan/code-review 루프만으로 완료 판단이 충분하다. +- 기존 SDD 또는 agent-contract를 그대로 소비하고 새 설계 결정이 없다. + +## Milestone 연결 + +SDD가 필요한 Milestone은 `구현 잠금`에 아래 필드를 둔다. + +```md +- 상태: 잠금 +- SDD: 필요 +- SDD 문서: `agent-roadmap/sdd///SDD.md` +- 잠금 해제 조건: + - [ ] SDD 잠금이 해제되어 있다 + - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다 + - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다 + - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다 +- 결정 필요: 없음 +``` + +SDD가 불필요한 Milestone은 사유를 남긴다. + +```md +- SDD: 불필요 +- SDD 사유: 단일 repo 내부 변경이며 외부 계약, 상태 머신, provider mutation이 없다. +``` + +## SDD 잠금 + +SDD 문서는 자체 잠금을 가진다. + +- `SDD 잠금: 잠금`이면 `plan`은 구현 계획을 만들지 않는다. +- `USER_REVIEW.md`가 존재하면 사용자 답변 전까지 SDD 잠금을 해제하지 않는다. +- 사용자 결정이 필요 없는 기술 세부는 agent가 코드, 규칙, 기존 계약을 근거로 채우고 잠금 항목으로 만들지 않는다. +- 모든 잠금 항목이 해결되고 사용자 리뷰가 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둔다. +- SDD 잠금이 해제되어야 Milestone `구현 잠금`도 해제 후보가 된다. + +사용자 리뷰가 필요한 항목: + +- source of truth 선택 +- 상태 전이 의미 변경 +- 사용자 승인, 검토, 폐기 흐름 변경 +- 외부 provider 쓰기 동작 추가 +- cross-repo 책임 경계 변경 +- scope 확대/축소 +- 보안, 비용, 데이터 보존, 권한 영향 +- 실패 시 처리 정책이 제품 판단인 경우 + +사용자 리뷰가 필요 없는 항목: + +- 기존 코드/문서/rule에서 답이 명확한 세부 +- 기존 agent-contract를 그대로 따르는 인터페이스 +- 일반 파일 구조, 테스트 명령, Evidence Map 작성 +- 구현자가 plan/code-review 루프에서 검증할 수 있는 기술 선택 + +## 실행 절차 + +### classify + +1. 관련 Milestone 또는 신규 작업 설명을 읽는다. +2. SDD 대상 판정 기준을 적용한다. +3. 결과를 `필요`, `불필요`, `불명확` 중 하나로 보고한다. +4. `필요`이면 Milestone `구현 잠금`에 SDD 경로와 잠금 해제 조건을 남기도록 안내하거나 갱신한다. + +### create + +1. `agent-ops/skills/common/_templates/roadmap-sdd-template.md`를 읽는다. +2. 대상 Milestone의 목표, 범위, 기능 Task, 범위 제외, 구현 잠금을 읽는다. +3. 필요하면 `agent-contract/index.md`를 읽고 매칭 계약 원문을 링크한다. 계약 본문을 SDD에 복제하지 않는다. +4. 표준 템플릿의 top-level 섹션, 섹션 순서, 필수 표 컬럼을 유지해 `agent-roadmap/sdd///SDD.md`를 만든다. +5. 사용자 결정이 필요한 항목이 있으면 `review-ready`를 수행한다. 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 둘 수 있다. + +### update + +1. 기존 SDD와 Milestone을 읽는다. +2. 변경 요청이 문제, source of truth, 상태 전이, interface, scenario, evidence 중 어디에 해당하는지 판정한다. +3. 표준 섹션 또는 필수 표 컬럼이 누락되어 있으면 먼저 복원한다. +4. 사용자 결정이 필요한 변경이면 SDD 잠금을 `잠금`으로 두고 `USER_REVIEW.md`를 갱신한다. +5. 기술 세부 보강이면 SDD 본문과 Evidence Map만 갱신한다. + +### check-gate + +1. Milestone `구현 잠금`의 `SDD` 필드를 확인한다. +2. `SDD: 불필요`이면 `not-required`로 보고한다. +3. `SDD: 필요`인데 SDD 문서가 없으면 `blocked`로 보고한다. +4. SDD가 표준 top-level 섹션 또는 필수 표 컬럼을 갖추지 못했으면 `invalid`로 보고한다. +5. SDD 상태가 `[승인됨]`이 아니거나 `SDD 잠금`이 `잠금`이면 `blocked`로 보고한다. +6. `USER_REVIEW.md`가 있으면 `blocked`로 보고한다. +7. Acceptance Scenario가 Milestone 기능 Task id와 연결되어 있는지 확인한다. +8. Evidence Map이 plan의 `Spec Targets`에 고정되고 완료 시 `Spec Completion`으로 검증될 수 있도록 scenario, task, evidence가 매핑되어 있는지 확인한다. +9. 모두 충족하면 `pass`로 보고한다. + +### review-ready + +1. `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md`를 읽는다. +2. 사용자만 결정할 항목만 추린다. +3. `agent-roadmap/sdd///USER_REVIEW.md`를 만든다. +4. SDD의 `SDD 잠금`을 `잠금`으로 둔다. +5. 채팅으로 즉시 선택지를 묻지 않고 파일 경로와 필요한 결정만 보고한다. + +### resolve-review + +1. `USER_REVIEW.md`와 SDD를 읽는다. +2. 사용자의 답변을 관련 SDD 섹션과 `사용자 리뷰 이력`에 반영한다. +3. `USER_REVIEW.md`를 `user_review_N.log`로 이동한다. +4. 남은 잠금 항목이 없으면 SDD 상태를 `[승인됨]`, SDD 잠금을 `해제`로 바꾼다. +5. SDD gate가 pass이면 Milestone `구현 잠금`을 해제할 수 있다고 보고한다. 직접 해제는 요청 또는 runtime/update-roadmap 흐름에 따른다. + +### archive + +1. Milestone이 `[완료]` 또는 `[폐기]`인지 확인한다. +2. 활성 SDD 디렉터리가 있으면 `agent-roadmap/archive/sdd///`로 이동한다. +3. 활성 `PHASE.md` 또는 Milestone archive 링크와 SDD archive 경로가 어긋나지 않는지 확인한다. +4. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다. + +## 출력 형식 + +```markdown +## SDD 결과 + +- mode: `` +- milestone: `` +- sdd: `` +- 결과: `` +- 잠금: `<해제 | 잠금 | 해당 없음>` +- 사용자 리뷰: `<없음 | USER_REVIEW.md | user_review_N.log>` +- 다음 단계: `<없음 | 사용자 리뷰 필요 | Milestone 구현 잠금 해제 가능 | SDD 작성 필요>` +``` + +## 금지 사항 + +- SDD 본문에 agent-contract 계약 원문을 복제하지 않는다. +- 사용자 결정이 필요한 항목을 chat 질문으로 바로 던지지 않는다. `USER_REVIEW.md`로 남긴다. +- 작은 작업에 SDD를 강제하지 않는다. +- `USER_REVIEW.md`가 남아 있는데 SDD 상태를 `[승인됨]`으로 두지 않는다. +- SDD gate가 막힌 Milestone에 대해 구현 plan을 만들지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 2a5df8c..04aa954 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -1,5 +1,11 @@ # 공통 스킬 라우터 +라우팅 우선순위: + +- SDD/spec gate 자체의 작성, 갱신, gate 확인, 사용자 리뷰, 잠금 해제는 `roadmap-sdd`로 보낸다. +- 로드맵/마일스톤 생성 또는 갱신 요청 안에 SDD 필요 여부와 gate 연결이 포함되면 `create-roadmap` 또는 `update-roadmap`을 진입점으로 삼고, 해당 흐름에서 `roadmap-sdd`를 preflight로 적용한다. +- 구현 계획 요청에서 선택 Milestone의 SDD 잠금이 감지되면 `plan`을 진입점으로 삼되, plan 작성 전에 `roadmap-sdd` pre-plan gate를 먼저 통과해야 한다. + | 요청 키워드 | SKILL.md | |------------|----------| | agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` | @@ -11,6 +17,7 @@ | README 작성해줘, README 만들어줘, 프로젝트 설명 문서 만들어줘 | `agent-ops/skills/common/create-readme/SKILL.md` | | 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | | 로드맵 업데이트, roadmap 갱신, 로드맵에 추가, 로드맵 작업 추가, 로드맵 기능 추가, 로드맵 Epic 추가, 로드맵 에픽 추가, 로드맵 Task 추가, 로드맵 태스크 추가, 로드맵 테스크 추가, 로드맵 TODO 추가, 마일스톤에 추가, 마일스톤 추가, 마일스톤 갱신, 마일스톤 아카이브, phase 추가, phase 변경, 페이즈 추가, 페이즈 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역 | `agent-ops/skills/common/update-roadmap/SKILL.md` | +| SDD 작성, SDD 생성, SDD 갱신, SDD 필요 여부, SDD gate 확인, SDD 사용자 리뷰, SDD 잠금 해제, SDD 승인 준비, SDD archive, spec gate, 설계 게이트 | `agent-ops/skills/common/roadmap-sdd/SKILL.md` | | 이 마일스톤은 X가 끝나야 가능해, A 전까지 B 잠가둬, 잠금 해제 조건은 X야, X 프로젝트 작업 뒤에 현재 마일스톤 진행, 의존성 설정해, 외부 의존 잠금 | `agent-ops/skills/common/update-roadmap/SKILL.md` | | roadmap dependency 확인, locks.yaml 판별, 외부 의존 잠금 확인, unlock-ready 판별, 잠금 해제 조건 충족 여부 확인, roadmap-dependency-checker.sh | `agent-ops/skills/common/check-roadmap-dependency/SKILL.md` | | 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 로드맵상 현 위치, 현재 마일스톤 위치, current 기준 breadcrumb | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` | diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index dc2ade1..f7f3b82 100644 --- a/agent-ops/skills/common/update-roadmap/SKILL.md +++ b/agent-ops/skills/common/update-roadmap/SKILL.md @@ -42,6 +42,9 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능 - `target-status`: 전환할 Phase/Milestone 상태. `[스케치]` / `[계획]` / `[진행중]` / `[검토중]` / `[완료]` / `[보류]` / `[폐기]` 중 하나 (선택) - `lock-state`: Milestone 구현 잠금 상태. `잠금` / `해제` 중 하나 (선택) - `decision-needed`: `구현 잠금`에 남길 사용자만 결정할 수 있는 질문 목록 (선택) +- `sdd-state`: Milestone SDD gate. `필요` / `불필요` / `확인 필요` 중 하나 (선택) +- `sdd-path`: SDD 문서 경로. 기본값은 `agent-roadmap/sdd///SDD.md` (선택) +- `sdd-review`: SDD 사용자 리뷰 상태. `없음` / `요청됨` / `해결됨` 중 하나 (선택) - `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택) - `complete-log`: 런타임 완료 이벤트가 전달한 `complete.log` 경로. `Roadmap Completion` 섹션이 있을 때만 Milestone 기능 Task 체크에 사용한다 (선택) - `review-state`: 완료 리뷰 상태. `요청됨` / `승인됨` / `보완 필요` / `보류` / `폐기` 중 하나 (선택) @@ -61,12 +64,21 @@ agent-roadmap/ PHASE.md milestones/ .md + sdd/ + / + / + SDD.md + USER_REVIEW.md archive/ phase/ / PHASE.md milestones/ .md + sdd/ + / + / + SDD.md ``` - `ROADMAP.md`는 전체 목표와 Phase 흐름만 담는다. @@ -75,6 +87,9 @@ agent-roadmap/ - 완료된 Phase는 `archive/phase//PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다. - 진행중 Phase 안에서 완료된 Milestone은 `archive/phase//milestones/.md`로 이동하고, 활성 `PHASE.md`에는 짧은 archive 링크를 남긴다. - archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우에는 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. +- 큰 Milestone의 SDD는 `agent-roadmap/sdd///SDD.md`에 둔다. +- SDD 사용자 리뷰는 같은 디렉터리의 `USER_REVIEW.md`로 두고, 해결 후 `user_review_N.log`로 남긴다. +- 완료 또는 폐기된 Milestone의 SDD는 `agent-roadmap/archive/sdd///`로 이동한다. - ``와 ``는 소문자 영문, 숫자, 하이픈만 사용한다. - `current.md`는 브랜치별 로컬 포인터이며 활성 Phase와 활성 Milestone을 모두 가리킨다. - `current.md`는 git 추적 대상이 아니며, 공유 진행 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 기록한다. @@ -114,6 +129,8 @@ agent-roadmap/ - `current.md`: `agent-ops/skills/common/_templates/roadmap-current-template.md` - `PHASE.md`: `agent-ops/skills/common/_templates/roadmap-phase-template.md` - Milestone: `agent-ops/skills/common/_templates/roadmap-milestone-template.md` +- SDD: `agent-ops/skills/common/_templates/roadmap-sdd-template.md` +- SDD 사용자 리뷰: `agent-ops/skills/common/_templates/roadmap-sdd-user-review-template.md` ## 구현 잠금 @@ -121,6 +138,10 @@ agent-roadmap/ - 사용자만 결정할 수 있는 제품 방향, 범위, 우선순위, 책임 경계가 남아 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적는다. - 기존 구조, 도메인 rule, 플랫폼 관례, 업계 표준으로 합리적으로 정할 수 있는 항목은 `결정 필요`가 아니라 `작업 컨텍스트`의 표준선으로 기록한다. - Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `해제`로 둔다. +- SDD gate가 필요한 Milestone은 `구현 잠금`에 `SDD: 필요`, SDD 경로, 잠금 해제 조건을 남기고 SDD 잠금이 해제될 때까지 `잠금`으로 둔다. +- SDD gate가 불필요한 Milestone은 `SDD: 불필요`과 짧은 사유를 남긴다. +- SDD가 필요한 기준: cross-repo 계약, 외부 provider 쓰기, 상태 머신/lifecycle, idempotency/retry/identity map, API/proto/config/env/schema 변경, field smoke, 사용자 승인 gate 영향. +- SDD 사용자 리뷰가 필요한 결정은 chat으로 즉시 묻지 않고 `agent-roadmap/sdd///USER_REVIEW.md`에 남긴다. - 잠금 상태 변경은 Milestone 완료 판정이 아니므로 `기능` Task를 자동 완료 처리하지 않는다. - `[스케치]` Milestone은 `구현 잠금`이 `해제`로 보이더라도 구현 계획과 코드 구현 대상이 아니다. 먼저 승격 조건을 충족해 `[계획]`으로 전환한다. @@ -172,6 +193,7 @@ agent-roadmap/ - target이 없거나 둘 이상이면 Milestone 내용을 추정해 수정하지 말고 target 불명확으로 보고한다. - target이 확정되어도 `complete-log` 입력이 없거나 해당 파일에 `Roadmap Completion` 섹션이 없으면 Milestone 기능 Task를 체크하지 않고 no-op으로 보고한다. 일반 `m-*` 완료 이벤트만으로 Task를 추정해 체크하지 않는다. - `Roadmap Completion` 섹션이 있으면 Milestone 경로가 target과 일치하는지, Completed task ids의 각 id가 해당 Milestone의 기존 기능 Task id 하나와 정확히 일치하는지 확인한다. 하나라도 일치하지 않으면 수정하지 말고 target 불일치로 보고한다. +- target Milestone이 `SDD: 필요`이면 런타임 완료 이벤트의 `complete-log`에 `Spec Completion` 섹션이 있어야 한다. SDD `Evidence Map`은 `Spec Completion`이 무엇을 증명해야 하는지 판단하는 기준이며, 런타임 완료 이벤트에서는 단독 대체 근거로 쓰지 않는다. 사용자가 `update-roadmap` 요청에 별도 evidence를 명시해 수동 반영을 요구한 경우에만 Evidence Map 충족 근거를 보조 근거로 사용할 수 있다. 근거가 없으면 `Roadmap Completion`이 있어도 Task를 체크하지 않고 SDD evidence 부족으로 보고한다. - 일치하면 PASS evidence, `complete.log`, final archive path, archived plan/review log 경로, code-review 결과 요약을 근거로 `Roadmap Completion`에 적힌 기능 Task만 `[x]`로 갱신한다. target routing 자체는 완료 이벤트의 `m-` task group과 `complete.log`의 `Roadmap Completion` 섹션으로 결정한다. - 갱신 후 모든 기능 Task와 Task 안에 명시된 검증이 충족되면 `[검토중]` 전환과 `완료 리뷰` 요청 규칙을 적용한다. - target Milestone이 `[스케치]`이면 완료 이벤트를 반영하지 말고 상태 불일치로 보고한다. `[스케치]`는 Milestone 기반 `agent-task` 완료 이벤트의 target이 될 수 없다. @@ -247,6 +269,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 보존한 identity가 `.agent-roadmap-sync/locks.yaml`의 `locked`에 있으면 archive 이동 전에 의존 조건 충족 여부를 결과 보고에 남긴다. - find 결과가 `none`이면 `Workspace 잠금: 관련 lock 없음`으로 보고한다. - 대상 파일을 `agent-roadmap/phase//milestones/.md`에서 `agent-roadmap/archive/phase//milestones/.md`로 이동한다. +- 활성 SDD 디렉터리 `agent-roadmap/sdd///`가 있으면 `agent-roadmap/archive/sdd///`로 이동한다. `USER_REVIEW.md`가 남아 있으면 archive하지 말고 해결 필요로 보고한다. - 활성 `PHASE.md`의 Milestone 흐름에는 `[완료]` 또는 `[폐기]` 항목을 남기고, 경로는 archive 경로로 바꾼다. - 로컬 `current.md`의 활성 Milestone에서는 제거한다. - `ROADMAP.md`는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다. @@ -267,7 +290,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 1. **갱신 범위 결정** - 요청에서 mode, 대상 Phase/Milestone, placement, placement-unit을 추론한다. - 런타임 완료 이벤트의 `origin-task` task group이 `m-`이면 `target-milestone`을 활성 Milestone 경로 매칭으로 확정한다. - - 런타임 완료 이벤트가 `complete-log`를 전달하면 파일을 읽고 `Roadmap Completion` 섹션 유무와 Completed task ids를 확인한다. 섹션이 없으면 Milestone 기능 Task 체크는 no-op이다. + - 런타임 완료 이벤트가 `complete-log`를 전달하면 파일을 읽고 `Roadmap Completion` 섹션 유무와 Completed task ids를 확인한다. 섹션이 없으면 Milestone 기능 Task 체크는 no-op이다. SDD 대상 Milestone이면 `Spec Completion`도 확인한다. - 구조 전환, 템플릿 보정, current 동기화는 `sync`로 본다. - 사용자 승인 이후의 완료/폐기 이동은 `archive`로 본다. - 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다. @@ -287,7 +310,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 로컬 `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다. - target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다. - target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다. - - 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다. + - 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. SDD가 필요한 Milestone이면 SDD 경로와 사용자 리뷰 상태도 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다. - Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다. - 로컬 `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다. - 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다. @@ -295,7 +318,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 4. **스케치 승격 판단** - `target-status=[계획]`, `mode=concretize`, 또는 사용자가 "구체화", "계획으로 올려"처럼 요청하면 `[스케치] -> [계획]` 승격 검토로 본다. - 대상이 `[스케치]`가 아니면 일반 상태 갱신이나 Milestone 갱신으로 처리한다. - - 대상이 `[스케치]`이면 `승격 조건`, `구현 잠금`, `목표`, `범위`, `기능`, `작업 컨텍스트`를 확인한다. + - 대상이 `[스케치]`이면 `승격 조건`, `구현 잠금`, SDD 필요 여부, `목표`, `범위`, `기능`, `작업 컨텍스트`를 확인한다. - `승격 조건` 체크리스트가 남아 있거나 구현 계획에 직접 필요한 사용자 결정이 남아 있으면 상태를 `[스케치]`로 유지하고, 부족한 항목을 `승격 조건` 또는 `결정 필요`에 보강한다. - 구현 가능한 목표, 범위, 기능 Task, 직접 결정 항목, 후속 구현 단위가 정리되면 상태를 `[계획]`으로 전환하고, `승격 조건`은 충족 요약으로 남기거나 `- 없음`으로 정리한다. - 승격은 구현 완료가 아니므로 `기능` Task를 자동 완료 처리하지 않는다. @@ -306,6 +329,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다. - `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다. - Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, Task 안의 검증 문구, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다. + - 신규 또는 갱신 Milestone이 SDD 대상이면 `구현 잠금`에 `SDD: 필요`, SDD 경로, 잠금 해제 조건을 남긴다. SDD 본문 작성은 `roadmap-sdd` 스킬 책임이다. + - SDD 대상이 아니면 `구현 잠금`에 `SDD: 불필요`와 짧은 사유를 남긴다. - 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다. - 새 Milestone은 해당 Phase의 `milestones/` 아래에 만든다. - 새 `[스케치]` Milestone은 `승격 조건` 섹션을 포함하고 `구현 잠금`은 `잠금`으로 둔다. @@ -341,6 +366,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - `[스케치] -> [계획]` 전환을 수행했다면 승격 조건 해소 근거가 Milestone 내용이나 결과 보고에 남았는지 확인한다. - `[검토중]` Milestone이 archive 경로로 이동되지 않았는지 확인한다. - 모든 기능 Task와 Task 안에 명시된 검증이 `[x]`인 Milestone에는 `완료 리뷰` 섹션과 사용자 리뷰 요청이 있는지 확인한다. + - 각 Milestone의 `구현 잠금`에 SDD 필요 여부와 사유가 있는지 확인한다. + - `SDD: 필요` Milestone은 SDD 경로, 잠금 해제 조건, SDD 사용자 리뷰 상태가 일관되는지 확인한다. - Epic heading과 Task id 형식이 맞는지 확인한다. - 요청 규모가 판정되었고 결과 보고에 남았는지 확인한다. - 동일/유사 기존 항목을 검색했고 신규/업데이트 판정이 결과 보고에 남았는지 확인한다. @@ -362,6 +389,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 자동 배치한 경우 비교한 후보와 선택 근거 - 로컬 current.md 활성 창 변경 사항 - 완료 리뷰 상태와 사용자 확인 필요 항목 + - SDD gate 상태와 사용자 리뷰 필요 여부 - 런타임 완료 이벤트의 `origin-task`가 `m-`이면 원래 active task 경로와 매칭된 target Milestone, `Roadmap Completion` Task ids 또는 no-op 사유 - archive 모드이면 이동 경로와 남긴 링크 - 확인 필요로 남긴 항목 @@ -377,7 +405,10 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - agent-roadmap/current.md (local) - agent-roadmap/phase//PHASE.md - agent-roadmap/phase//milestones/.md + - agent-roadmap/sdd///SDD.md (SDD 작성/갱신 시) + - agent-roadmap/sdd///USER_REVIEW.md (SDD 사용자 리뷰 요청 시) - agent-roadmap/archive/phase//... (archive 모드) + - agent-roadmap/archive/sdd///... (SDD archive 시) ## 변경 사항 @@ -391,6 +422,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음> - 템플릿 보정: - 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약> +- SDD gate: <불필요 | 필요-작성 전 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 변경 없음> - 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약> - 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기> - runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>