From fbb7875cc712364906b3162451a4465b48a64b03 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 6 Jul 2026 10:24:02 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.163 --- agent-ops/.version | 2 +- agent-ops/rules/common/rules-roadmap.md | 5 +- .../roadmap-position-report-template.md | 52 +++++++++++-------- .../common/analyze-roadmap-position/SKILL.md | 29 ++++++++--- 4 files changed, 57 insertions(+), 31 deletions(-) diff --git a/agent-ops/.version b/agent-ops/.version index 38dfb5f..19cc93e 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.162 +1.1.163 diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index b60a39c..5cc3852 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -18,8 +18,9 @@ ## 링크 표기 - 사용자에게 보여주는 답변과 활성 로드맵 문서의 문서 포인터는 raw path만 쓰지 말고 `[표시 제목](상대경로)` Markdown 링크로 쓴다. -- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase//PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다. -- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase//PHASE.md)`. +- 로드맵 문서 안의 링크 target은 링크를 작성하는 Markdown 파일 위치 기준 상대경로로 쓴다. 예: `ROADMAP.md`에서는 `[PHASE.md](phase/example-phase/PHASE.md)`, Phase 문서에서는 `[Milestone](milestones/example-milestone.md)`, Milestone 문서에서는 `[ROADMAP.md](../../../ROADMAP.md)`와 `[PHASE.md](../PHASE.md)`를 쓴다. +- 채팅 결과 보고처럼 저장 위치가 없는 출력은 repo root 기준 상대경로를 쓸 수 있다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`. +- 채팅 결과에 로드맵 문서에서 읽은 링크를 재사용할 때는 원본 Markdown 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다. 예: `agent-roadmap/current.md`에서 읽은 `(phase/foo/PHASE.md)`는 채팅 출력에서 `(agent-roadmap/phase/foo/PHASE.md)`로, `agent-roadmap/phase/foo/PHASE.md`에서 읽은 `(milestones/bar.md)`는 `(agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다. - 실제 활성 로드맵 문서에는 ``, ``, `` 같은 placeholder가 들어간 링크 target을 남기지 않는다. 템플릿 placeholder는 문서 생성/갱신 시 실제 파일 위치 기준 상대경로 또는 `없음`으로 치환한다. - 기존 raw path 또는 backtick path는 읽기 입력으로 허용한다. 갱신 범위에 포함된 활성 문서 포인터만 Markdown 링크로 보정하고, archive 스냅샷은 링크 표기만을 이유로 재포맷하지 않는다. - `.agent-roadmap-sync/locks.yaml`의 `locked`, `rely-on.target`, Milestone identity(`:agent-roadmap/...`)처럼 machine-readable 계약 값은 raw 값을 유지할 수 있다. 사용자-facing 설명에는 가능하면 별도 Markdown 문서 링크를 함께 붙인다. 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 09a042e..03db469 100644 --- a/agent-ops/skills/common/_templates/roadmap-position-report-template.md +++ b/agent-ops/skills/common/_templates/roadmap-position-report-template.md @@ -1,31 +1,41 @@ # 로드맵 현지점 - +- local current: {없음 | [current.md](agent-roadmap/current.md)} -- [local current.md](agent-roadmap/current.md) + -- [로드맵: ](agent-roadmap/ROADMAP.md) - - [Phase: ](agent-roadmap/phase//PHASE.md) - - [Milestone: ](agent-roadmap/phase//milestones/.md) - - [<상태>] <목표 또는 역할 한 줄> - - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | [SDD.md](agent-roadmap/sdd///SDD.md) (파일 없음)> - - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md)> - - [Milestone: ](agent-roadmap/phase//milestones/.md) - - [<상태>] <목표 또는 역할 한 줄> - - SDD: <없음 | [SDD.md](agent-roadmap/sdd///SDD.md) | [SDD.md](agent-roadmap/sdd///SDD.md) (파일 없음)> - - 사용자 리뷰: <없음 | [USER_REVIEW.md](agent-roadmap/sdd///USER_REVIEW.md)> +## Breadcrumb + +- [로드맵: {roadmap-name}](agent-roadmap/ROADMAP.md) + - Phase: {PHASE_LINK} + - Milestone: {MILESTONE_LINK} + - [{상태}] {목표 또는 역할 한 줄} + - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)} + - 사용자 리뷰: {없음 | USER_REVIEW_LINK} + - Milestone: {MILESTONE_LINK} + - [{상태}] {목표 또는 역할 한 줄} + - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)} + - 사용자 리뷰: {없음 | USER_REVIEW_LINK} ## 전체 Phase 흐름 -- [<상태>] []() -- [<상태>] [<현재 Phase 이름>]() ← 현재 -- [<상태>] []() +- [{상태}] {PHASE_LINK} +- [{상태}] {PHASE_LINK} ← 현재 +- [{상태}] {PHASE_LINK} ## 현재 Phase의 Milestone 흐름 -- [<상태>] []() ← 현재 후보, <역할 태그> - - SDD: <없음 | [SDD.md]() | [SDD.md]() (파일 없음)> - - 사용자 리뷰: <없음 | [USER_REVIEW.md]()> -- [<상태>] []() ← 현재 후보, <역할 태그> - - SDD: <없음 | [SDD.md]() | [SDD.md]() (파일 없음)> - - 사용자 리뷰: <없음 | [USER_REVIEW.md]()> +- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그} + - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)} + - 사용자 리뷰: {없음 | USER_REVIEW_LINK} +- [{상태}] {MILESTONE_LINK} ← 현재 후보, {역할 태그} + - SDD: {없음 | SDD_LINK | SDD_LINK (파일 없음)} + - 사용자 리뷰: {없음 | USER_REVIEW_LINK} diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index 34a8862..572941e 100644 --- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md +++ b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md @@ -44,14 +44,26 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - 각 Milestone은 상태, 이름, 링크만 남긴다. - current의 활성 Milestone과 일치하는 항목에 `← 현재 후보` 표시를 붙인다. 6. current의 활성 Milestone 문서를 열고 제목, `목표`, `상태`, `구현 잠금`의 SDD 문서 링크/경로만 읽는다. - - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: [SDD.md]()`로 출력한다. - - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: [SDD.md]() (파일 없음)` 형식으로 출력한다. + - `SDD 문서` 링크/경로가 있고 해당 `SDD.md` 파일이 존재하면 Milestone 아래에 `SDD: SDD_LINK`로 출력한다. + - `SDD 문서` 링크/경로는 있으나 해당 파일이 없으면 Milestone 아래에 `SDD: SDD_LINK (파일 없음)` 형식으로 출력한다. - `SDD 문서` 링크/경로가 없거나 `SDD: 불필요`이면 Milestone 아래에 `SDD: 없음`으로 출력한다. - - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: [USER_REVIEW.md]()`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다. + - `SDD.md`와 같은 디렉터리에 `USER_REVIEW.md`가 있으면 Milestone 아래에 `사용자 리뷰: USER_REVIEW_LINK`로 출력하고, 없으면 `사용자 리뷰: 없음`으로 출력한다. - SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않는다. 필요한 독자는 출력된 SDD 링크를 열어 확인하게 한다. - SDD 본문은 읽지 않는다. - `기능`, `완료 리뷰`, `범위 제외`, `작업 컨텍스트`는 사용자가 명시적으로 요청한 경우에만 읽는다. -7. 결과를 템플릿 형식 그대로 출력한다. +7. 결과를 템플릿의 섹션 순서와 필드 의미에 맞춰 출력한다. 템플릿의 placeholder, 선택지 표기, HTML 주석은 출력하지 않는다. + +## 링크 정규화 + +- 출력 링크는 채팅 결과이므로 항상 repo root 기준 상대경로를 target으로 쓴다. 예: `[PHASE.md](agent-roadmap/phase/example-phase/PHASE.md)`. +- `current.md`, `ROADMAP.md`, `PHASE.md`, Milestone 문서에서 읽은 Markdown 링크는 그대로 복사하지 않는다. 반드시 링크가 들어 있던 원본 파일 위치 기준으로 target을 해석한 뒤 repo root 기준 상대경로로 다시 쓴다. +- 예: `agent-roadmap/current.md`의 `[PHASE.md](phase/foo/PHASE.md)`는 출력에서 `[PHASE.md](agent-roadmap/phase/foo/PHASE.md)`로 쓴다. +- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Milestone](milestones/bar.md)`는 출력에서 `[Milestone](agent-roadmap/phase/foo/milestones/bar.md)`로 쓴다. +- 예: `agent-roadmap/phase/foo/PHASE.md`의 `[Archive](../../archive/phase/foo/milestones/bar.md)`는 출력에서 `[Archive](agent-roadmap/archive/phase/foo/milestones/bar.md)`로 쓴다. archive 문서는 읽지 않고 링크만 표시한다. +- 링크 label은 사람이 이해할 수 있는 이름을 쓰고, target에는 ``, ``, ``, ``, ``, `` 또는 `{PHASE_LINK}` 같은 placeholder를 남기지 않는다. +- 템플릿의 `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}`는 실제 `[제목](repo-root-relative-path)` Markdown 링크로 치환한다. +- 대상 경로를 확정할 수 없으면 Markdown 링크를 만들지 말고 `링크 없음: <사유>`로 표시한다. raw path만 단독으로 출력하거나 깨진 링크를 만들지 않는다. +- 출력 전 자체 점검으로 `](<`, `](...<...>)`, `{PHASE_LINK}` 같은 placeholder 링크가 남아 있지 않은지 확인한다. ## 실행 결과 검증 @@ -59,6 +71,8 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태/SDD 문서 링크/경로만 기본으로 읽었는가 - [ ] 현재 후보 Milestone 아래에 SDD와 사용자 리뷰를 링크 또는 `없음`으로 출력했는가 - [ ] Phase, Milestone, SDD, 사용자 리뷰 등 모든 문서 포인터가 raw path만 남지 않고 Markdown 링크로 출력되었는가 +- [ ] 문서에서 읽은 file-location-relative 링크를 채팅 출력용 repo root 상대 링크로 정규화했는가 +- [ ] 출력에 placeholder 링크 target이나 `(제목)[링크]`처럼 뒤집힌 Markdown 문법이 남지 않았는가 - [ ] SDD 상태, 잠금, 승인 여부를 역할 태그나 상태 요약으로 출력하지 않았는가 - [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가 - [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가 @@ -68,14 +82,15 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA ## 출력 형식 - 템플릿 경로: `agent-ops/skills/common/_templates/roadmap-position-report-template.md` -- 템플릿을 그대로 복사해 placeholder를 채운다. -- 출력에는 ``, ``, ``, `` placeholder를 그대로 남기지 않고 실제 repo root 기준 상대 링크 target으로 치환한다. +- 템플릿의 섹션 순서와 필드 의미를 따른다. placeholder 줄을 그대로 복사하지 말고, 실제 항목 수에 맞춰 행을 생성한다. +- 출력에는 ``, ``, ``, ``, `{PHASE_LINK}`, `{MILESTONE_LINK}`, `{SDD_LINK}`, `{USER_REVIEW_LINK}` placeholder를 그대로 남기지 않고 실제 repo root 기준 상대 링크 target으로 치환한다. - 섹션 제목과 필드명을 임의로 번역, 축약, 삭제하지 않는다. - current가 여러 Milestone을 가리키면 breadcrumb와 Milestone 흐름에 모두 표시한다. - 현재 후보의 역할 태그는 `선행 스케치`, `다음 구현 계획`, `검토 후보`, `보류 후보`처럼 짧게 쓰되 SDD 상태를 역할 태그에 넣지 않는다. - 현재 후보에 `SDD 문서` 링크/경로가 있으면 Milestone 아래에 SDD 링크를 배치한다. `USER_REVIEW.md`가 있으면 그 링크도 SDD 아래에 배치한다. -- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `[SDD.md]() (파일 없음)`처럼 링크와 상태를 함께 쓴다. +- 문서 포인터는 항상 `[표시 제목](상대경로)` Markdown 링크로 출력한다. 파일이 없어도 raw path만 쓰지 말고 `SDD_LINK (파일 없음)`처럼 링크와 상태를 함께 쓴다. - 로드맵이 없는 프로젝트에서는 로드맵 없음으로 짧게 보고하고 템플릿을 억지로 채우지 않는다. +- 로컬 `current.md`가 없으면 `local current: 없음`으로 출력하고, `[current.md](agent-roadmap/current.md)` 링크를 만들지 않는다. ## 금지 사항