sync: agent-ops from agentic-framework v1.1.29

agent-ops/rules/common/rules-roadmap.md

@@ -21,6 +21,14 @@
 - 단순 "진행", "구현", "계획 작성" 요청은 잠금을 해제하지 않는다.
 - 잠금 해제는 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시한 경우에만 검토한다.
 
+## 필수 기능 item-id
+
+- Milestone 문서의 `필수 기능` 체크리스트는 `- [ ] [item-id] 설명` 형식을 사용한다.
+- item-id는 공백 없는 짧은 ASCII 토큰이며, 영문/숫자 segment 1~4개로 작성하고 segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
+- item-id는 해당 Milestone 안에서만 유일하면 된다.
+- 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 여러 Milestone 후보에서 같은 item-id가 발견되면 Milestone 이름이나 문서 경로로 대상을 확정한다.
+- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 항목을 우선 anchor로 삼고, 기존 item-id는 명시적 요청 없이 바꾸지 않는다.
+
 ## 작업 지점 분석
 
 - 현재 작업 지점이나 남은 작업 분석 요청은 `analyze-roadmap-position` 스킬로 처리한다.

agent-ops/skills/common/_templates/roadmap-milestone-template.md

@@ -30,7 +30,8 @@
 
 ## 필수 기능
 
-- [ ] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물>
+<!-- 필수 기능 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 공백 없는 짧은 ASCII 영문/숫자 segment 1~4개로 작성하고 segment 구분자는 -_+= 만 사용한다. 전체 길이는 32자 이하를 권장한다. 해당 Milestone 안에서만 유일하면 되고, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. -->
+- [ ] [item-id] <구현 세부가 아니라 이 Milestone에서 달성해야 할 capability 또는 산출물>
 
 ## 완료 기준
 

agent-ops/skills/common/analyze-roadmap-position/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze-roadmap-position
-version: 1.1.1
+version: 1.2.0
 description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확인 요청에 대해 활성 Milestone과 코드 상태를 함께 읽어 현재 작업 지점, Milestone 문서 링크, 남은 일을 추정하는 읽기 전용 스킬"
 ---
 
@@ -10,6 +10,7 @@ description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확
 
 현재 브랜치, 변경 파일, 코드 구조, 활성 Milestone 문서를 함께 분석해 지금 작업이 어느 Milestone에 걸쳐 있는지와 남은 작업 후보를 보고한다.
 결과에는 추정한 Milestone의 문서 링크를 항상 함께 출력한다.
+Milestone의 `필수 기능` 항목에 item-id가 있으면 남은 작업과 판단 근거에 함께 표시해 사용자가 짧은 id로 후속 지시를 할 수 있게 한다.
 `current.md`만 보고 현재 작업 위치를 단정하지 않고, 실제 코드 상태와 요청 내용을 근거로 판단한다.
 
 ## 언제 호출할지
@@ -48,6 +49,8 @@ description: "지금 작업이 뭐지?, 현재 작업 분석, 남은 작업 확
 
 3. **Milestone 매칭**
    - 활성 Milestone의 목표, 범위, 완료 기준, 범위 제외 항목과 변경 파일/요청 내용을 비교한다.
+   - 활성 Milestone의 `필수 기능` 체크리스트를 확인하고, 관련 항목에 item-id가 있으면 판단 근거와 남은 작업에 item-id를 함께 기록한다.
+   - 여러 Milestone 후보에서 같은 item-id가 보이면 item-id만으로 위치를 확정하지 말고 Milestone 이름과 문서 링크를 함께 제시한다.
    - 활성 Milestone의 `구현 잠금` 섹션과 상태를 함께 확인한다. 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획 전에 Milestone 구체화 업데이트가 필요하다고 보고한다.
    - 하나의 Milestone에 명확히 속하면 단일 후보로 보고한다.
    - 둘 이상의 Milestone에 걸치면 복수 후보로 보고하고, 어떤 파일이나 기능이 어느 Milestone에 닿는지 나눈다.
@@ -78,6 +81,7 @@ Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하
 - [ ] 활성 Milestone 문서의 목표와 범위 제외 항목을 확인했는가
 - [ ] 활성 Milestone 문서의 `구현 잠금` 섹션 존재 여부와 상태를 확인했는가
 - [ ] 추정 Milestone마다 문서 링크를 출력했는가
+- [ ] 관련 `필수 기능` 항목에 item-id가 있으면 결과에 함께 표시했는가
 - [ ] 변경 파일 또는 사용자 요청과 Milestone 판단 근거가 연결되어 있는가
 - [ ] 남은 작업을 `확인됨`, `추정됨`, `확인 필요`로 구분했는가
 - [ ] 로드맵 파일을 수정하지 않았는가
@@ -103,9 +107,9 @@ Milestone 문서 경로를 찾지 못한 경우에도 링크 항목을 생략하
 
 ## 남은 작업
 
-- 확인됨: <항목>
-- 추정됨: <항목>
-- 확인 필요: <항목>
+- 확인됨: [<item-id>] <항목>
+- 추정됨: [<item-id>] <항목>
+- 확인 필요: [<item-id 또는 신규 id 필요>] <항목>
 
 ## 읽은 주요 파일
 

agent-ops/skills/common/create-roadmap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-roadmap
-version: 1.5.1
+version: 1.6.0
 description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 문서, 활성 Milestone 창을 처음 생성하는 공통 스킬
 ---
 
@@ -58,6 +58,9 @@ agent-ops/
 - 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 `구현 잠금` 상태를 `잠금`으로 둔다.
 - `구현 잠금`에는 이 문서가 방향성/범위 정의인지, 구현 가능한 수준인지, 잠금 해제 조건과 잠금 중 금지 사항을 적는다.
 - `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 작성한다. 완료 근거가 명확한 항목만 `- [x]`로 표시한다.
+- `필수 기능`의 각 체크리스트 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
+- item-id는 영문/숫자 segment 1~4개로 작성하고, segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
+- item-id의 유일성 범위는 해당 Milestone 문서 안으로 제한하며, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 소문자 영문 중심의 의미 있는 단어를 우선하고, 숫자나 기호는 구분이나 충돌 방지가 필요할 때만 사용한다.
 - `필수 기능`의 하위 작업은 구현 세부가 아니라 capability를 판단하는 제품/운영/문서 수준의 확인 항목으로 제한한다.
 - `완료 기준`은 검증 가능한 조건의 체크리스트로 작성한다.
 - `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.
@@ -125,7 +128,7 @@ agent-ops/
    - 각 Milestone 문서는 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따른다.
    - 각 Milestone 문서에 `구현 잠금` 섹션을 포함한다.
    - 사용자가 해당 Milestone의 구현 구체화와 잠금 해제를 명시적으로 승인하지 않았으면 `구현 잠금` 상태는 `잠금`으로 작성한다.
-   - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ]` 체크리스트로 작성한다.
+   - `필수 기능`과 그 하위 항목은 capability 또는 산출물 수준의 `- [ ] [item-id] 설명` 체크리스트로 작성한다.
    - 완료 근거가 확인된 항목만 `- [x]`로 표시하고, 근거가 없으면 체크하지 않는다.
    - `완료 기준`도 검증 가능한 조건의 `- [ ]` 체크리스트로 작성한다.
    - 미래 Milestone은 확정된 방향과 capability만 `필수 기능`에 넣고, 불확실한 구현 세부는 `작업 컨텍스트`의 확인 필요 항목으로 둔다.
@@ -152,6 +155,7 @@ agent-ops/
 - [ ] 각 Milestone 문서가 `roadmap-milestone-template.md`의 섹션 순서와 형식을 따르는가
 - [ ] 각 Milestone 문서에 `구현 잠금` 섹션이 있고, 구현 구체화가 없으면 상태가 `잠금`인가
 - [ ] 각 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
+- [ ] 각 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가
 - [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가
 - [ ] 로딩 정책에 `구현 잠금`이 없거나 잠긴 Milestone의 구현/계획 시작 금지 규칙이 포함되었는가
 - [ ] `agent-ops/rules/common/rules.md`가 로드맵 디렉터리 존재 시 `rules-roadmap.md`를 읽도록 라우팅하는가
@@ -190,6 +194,6 @@ agent-ops/
 - Milestone 문서에서 `구현 잠금` 섹션을 생략하지 않는다.
 - 사용자의 명시적 구현 구체화/잠금 해제 승인 없이 새 Milestone을 `해제` 상태로 만들지 않는다.
 - Milestone을 구현 계획처럼 package/file/function 단위로 과도하게 구체화하지 않는다.
-- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 체크리스트로 작성한다.
+- 해야 할 capability 또는 산출물을 일반 불릿이나 설명 문장에 숨기지 않는다. `필수 기능` 또는 그 하위 항목의 item-id가 있는 체크리스트로 작성한다.
 - 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다.
 - `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다.

agent-ops/skills/common/update-roadmap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-roadmap
-version: 1.7.1
+version: 1.8.0
 description: 기존 전체 목표, Phase, 구현 구체화 잠금이 있는 순번 없는 Milestone 기반 한국어 로드맵을 갱신하고 신규 작업의 삽입 위치와 단위를 사용자 지정 또는 자동 판단으로 배치하며 current.md의 활성 Milestone 창을 동기화하는 공통 스킬
 ---
 
@@ -88,6 +88,9 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 이 Milestone은 구현 계획이 아니라 범위/방향성 게이트다. 코드 구현, `agent-task` 구현 계획, 세부 API/파일 구조 확정을 시작하지 않는다.
 - `구현 잠금`을 `해제`하려면 사용자가 Milestone 구체화 업데이트 또는 잠금 해제를 명시해야 하며, 책임 경계, API/프로토콜, 검증 기준, 선행 조건이 문서에 반영되어야 한다.
 - `필수 기능`은 구현 파일/함수 단위 작업 목록이 아니라 Milestone에서 달성해야 할 capability 또는 산출물 체크리스트로 유지한다.
+- `필수 기능`의 각 체크리스트 항목은 `- [ ] [item-id] 설명` 형식을 사용한다. item-id는 사람이 타이핑하고 LLM이 참조하기 쉬운 공백 없는 짧은 ASCII 토큰으로 작성한다.
+- item-id는 영문/숫자 segment 1~4개로 작성하고, segment 구분자는 `-`, `_`, `+`, `=`만 사용한다. 가능하면 1~3 segment를 우선하며, 전체 길이는 32자 이하를 권장한다.
+- item-id의 유일성 범위는 해당 Milestone 문서 안으로 제한하며, 다른 Milestone에서는 같은 item-id를 다시 사용할 수 있다. 기존 item-id는 사용자가 명시적으로 바꾸라고 하지 않는 한 보존하고, 새 항목에는 소문자 영문 중심의 의미 있는 id를 만든다.
 - `완료 기준`은 검증 가능한 조건의 체크리스트로 유지한다.
 - 일반 불릿이나 설명 문장에 숨어 있는 capability/산출물은 성격을 판단해 `필수 기능` 체크리스트 또는 기존 항목의 하위 체크리스트로 옮긴다.
 - `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 유지하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.
@@ -100,7 +103,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 중간에 Phase나 Milestone을 끼워 넣을 수 있도록 기존 항목의 이름과 파일명을 불필요하게 바꾸지 않는다.
 - 기존 프로젝트에 이미 순번 파일명이 있으면 대규모 rename을 하지 말고, 갱신 범위에 포함된 새 항목부터 순번 없는 형식을 적용한다.
 - 새 작업은 습관적으로 새 Milestone으로 만들거나 목록 맨 앞/뒤에 붙이지 않는다.
-- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
+- 사용자가 특정 Milestone 앞/뒤, 특정 Phase 안, 필수 기능 목록 내 위치, 기존 태스크 item-id, 또는 기존 태스크 앞/뒤/아래를 지정하면 목표와 범위 제외 항목에 충돌하지 않는 한 그 위치를 우선한다.
 - 사용자가 위치를 지정하지 않으면 `ROADMAP.md`의 Phase 흐름, 기존 Milestone 목표, 기존 필수 기능/태스크, 선후 의존성, 활성 Milestone 창, 완료 기준을 보고 가장 자연스러운 위치를 자동으로 판단한다.
 - 자동 배치한 경우 결과 보고에 선택한 삽입 단위, Phase/Milestone/태스크 위치, 판단 근거를 짧게 남긴다.
 
@@ -119,6 +122,8 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 잠긴 Milestone 안에 새 작업을 추가할 때는 구현 태스크가 아니라 capability, 결정 안건, 선행 조건, 완료 기준 후보로 작성한다.
 - `구현 잠금`이 없거나 잠긴 Milestone에 대해 사용자가 "진행", "구현", "계획 작성"을 요청하면 로드맵을 우회하지 않는다. 먼저 Milestone 문서 구체화 업데이트와 잠금 해제를 요청한다.
 - 위치 지정이 있으면 anchor의 레벨을 먼저 확인한다. `<anchor-task> 아래`처럼 하위 위치가 명시되면 기존 태스크 하위 항목으로 넣고, `<anchor-task> 앞/뒤`면 같은 목록 레벨의 형제 항목으로 넣는다.
+- 사용자가 item-id를 언급하면 해당 Milestone의 `필수 기능` 체크리스트에서 정확히 일치하는 item-id를 우선 매칭한다. 중복되거나 없으면 임의로 고르지 말고 확인한다.
+- 여러 Milestone 후보에서 같은 item-id가 발견되면 item-id만으로 확정하지 말고 Milestone 이름이나 문서 경로를 확인한다.
 - 위치는 지정됐지만 단위가 명시되지 않은 경우, anchor 레벨과 작업 성격을 함께 보고 새 Milestone, 태스크, 하위 작업 중 하나를 선택한다.
 - 위치 지정이 `<phase-name> 안` 또는 `<milestone-name> 안`처럼 컨테이너만 지정된 경우, 잠금 해제된 Milestone에서 작업 내용이 기존 태스크의 세부 구현이면 해당 컨테이너 안에서 가장 관련 있는 태스크 아래에 넣을 수 있다. 이 경우 결과 보고에 "위치는 지정된 컨테이너를 따랐고, 단위는 하위 작업으로 판단"처럼 남긴다.
 - 위치 지정이 `<anchor-milestone> 앞/뒤` 또는 `<anchor-task> 앞/뒤`처럼 순서 anchor인 경우, 같은 레벨의 앞/뒤 배치를 유지한다. 작업 성격상 다른 레벨이 더 적절해 보여도 조용히 재배치하지 말고 사용자에게 확인한다.
@@ -166,6 +171,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
    - 대상 또는 후보 Milestone 문서의 `구현 잠금` 상태와 해제 조건을 확인한다.
    - `구현 잠금`이 없거나 잠긴 Milestone에 대한 구현, 구현 계획, 세부 API/파일 구조 확정 요청이면 수정으로 진행하지 않고 잠금 상태와 필요한 구체화 업데이트를 사용자에게 보고한다.
    - 대상 Milestone 문서가 표준 템플릿 섹션 순서와 체크리스트 형식을 따르는지 확인한다.
+   - 대상 Milestone 문서의 `필수 기능` item-id 목록을 확인하고, 중복 또는 누락이 갱신 범위에 있으면 보정 대상으로 기록한다.
    - 신규 작업과 이름, 산출물, 코드 경계, 완료 기준이 겹치는 기존 태스크가 있는지 확인한다.
 
 3. **신규 작업 삽입 단위와 위치 판단**
@@ -201,7 +207,9 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
    - 새 Milestone은 사용자가 구현 구체화와 잠금 해제를 명시하지 않는 한 `구현 잠금` 상태를 `잠금`으로 작성한다.
    - 기존 Milestone에 새 태스크를 넣는 경우 `필수 기능` 체크리스트에 사용자 지정 또는 자동 판단 위치로 삽입하고, 근거 없이 목록 맨 앞이나 맨 뒤에 붙이지 않는다.
    - 잠금 해제된 Milestone에서 기존 태스크의 하위 작업으로 넣는 경우 부모 태스크 아래의 하위 체크리스트로 작성하고, 부모 태스크의 의미가 바뀌면 부모 문장도 필요한 만큼만 보완한다.
-   - 기존 `필수 기능`이 일반 불릿이면 상태 근거를 보존해 `- [ ]` 또는 `- [x]` 체크리스트로 변환한다.
+   - 새로 추가하거나 형식 보정 범위에 포함된 `필수 기능` 항목은 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 형식으로 작성한다.
+   - 기존 `필수 기능`이 일반 불릿이면 상태 근거를 보존해 `- [ ] [item-id] 설명` 또는 `- [x] [item-id] 설명` 체크리스트로 변환한다.
+   - 기존 `필수 기능` 체크리스트에 item-id가 있으면 사용자가 명시적으로 바꾸라고 하지 않는 한 유지한다. item-id가 없는 항목을 갱신 범위에서 보정할 때는 해당 Milestone 안에서 중복되지 않는 id를 붙인다.
    - 기존 `완료 기준`이 일반 불릿이면 검증 조건 단위의 체크리스트로 변환한다.
    - 상태 값은 `계획`, `진행 중`, `완료`, `보류`, `폐기` 중 하나만 사용한다.
    - 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다.
@@ -232,6 +240,7 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - [ ] `구현 잠금`이 없거나 잠긴 Milestone에 구현 태스크, `agent-task` 계획, 세부 API/파일 구조 확정을 추가하지 않았는가
 - [ ] 잠금 해제한 경우 사용자 승인 또는 구체화 근거를 결과 보고에 남겼는가
 - [ ] 갱신 대상 Milestone 문서의 `필수 기능`과 `완료 기준`이 체크리스트 형식인가
+- [ ] 갱신 대상 Milestone 문서의 `필수 기능` 체크리스트 항목이 `- [ ] [item-id] 설명` 형식이고 item-id가 해당 Milestone 안에서 유일한가
 - [ ] 신규 작업이 사용자 지정 위치를 따랐거나, 위치 미지정 시 자동 배치 근거가 남아 있는가
 - [ ] 신규 작업의 삽입 단위가 작업 성격과 기존 태스크 포함 관계에 맞는가
 - [ ] 자동 배치 위치가 Phase/Milestone 목표, 범위 제외 항목, 선후 의존성과 충돌하지 않는가
@@ -286,5 +295,6 @@ Milestone은 구현 전 방향성, 범위, 선행 조건, 브레이킹 포인트
 - 사용자가 지정한 앞/뒤/아래 anchor 또는 대상 Phase/Milestone 컨테이너를 무시하지 않는다.
 - Milestone 목표와 범위 제외 항목을 무시하고 태스크 체크리스트만 갱신하지 않는다.
 - 해야 할 작업을 `필수 기능` 체크리스트 밖의 설명 문장에 숨기지 않는다.
+- 사용자가 명시하지 않은 기존 `필수 기능` item-id를 바꾸지 않는다.
 - 갱신 대상 Milestone의 형식이 다르다는 이유로 기존 내용이나 완료 체크 근거를 삭제하지 않는다.
 - 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다.