From bbae5bb58d44c106a29ad7887f4cf59ea461851a Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 16:19:28 +0900 Subject: [PATCH] sync: agent-ops from agentic-framework v1.1.19 --- .clinerules | 1 + .cursorrules | 1 + AGENTS.md | 1 + CLAUDE.md | 1 + GEMINI.md | 1 + agent-ops/rules/common/rules.md | 1 + .../skills/common/create-roadmap/SKILL.md | 153 ++++++++++++++++++ agent-ops/skills/common/router.md | 2 + .../skills/common/update-roadmap/SKILL.md | 130 +++++++++++++++ 9 files changed, 291 insertions(+) create mode 100644 agent-ops/skills/common/create-roadmap/SKILL.md create mode 100644 agent-ops/skills/common/update-roadmap/SKILL.md diff --git a/.clinerules b/.clinerules index ae124ac..36fc7bb 100644 --- a/.clinerules +++ b/.clinerules @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/.cursorrules b/.cursorrules index ae124ac..36fc7bb 100644 --- a/.cursorrules +++ b/.cursorrules @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/AGENTS.md b/AGENTS.md index ae124ac..36fc7bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/CLAUDE.md b/CLAUDE.md index ae124ac..36fc7bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/GEMINI.md b/GEMINI.md index ae124ac..36fc7bb 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/agent-ops/rules/common/rules.md b/agent-ops/rules/common/rules.md index ae124ac..36fc7bb 100644 --- a/agent-ops/rules/common/rules.md +++ b/agent-ops/rules/common/rules.md @@ -12,5 +12,6 @@ - agent-ops 초기화 - domain rule 생성 - skill 생성 +- 로드맵/마일스톤 생성·갱신 - git commit / push - agent-ops 업데이트 / 진입 파일 재적용 diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md new file mode 100644 index 0000000..6c13607 --- /dev/null +++ b/agent-ops/skills/common/create-roadmap/SKILL.md @@ -0,0 +1,153 @@ +--- +name: create-roadmap +version: 1.0.0 +description: AI-first 개인/소규모 프로젝트의 전체 Goal, Phase, Milestone 기반 로드맵 파일과 현재 마일스톤 컨텍스트 로딩 규칙을 처음 생성하는 공통 스킬 +--- + +# Create Roadmap + +## 목적 + +`agent-ops/roadmap/` 하위에 Goal / Phase / Milestone 기반 로드맵 구조를 처음 생성한다. +전체 로드맵은 마일스톤 설계 시에만 읽고, 일반 작업에서는 현재 마일스톤 정의만 읽도록 컨텍스트 로딩 규칙을 만든다. + +## 언제 호출할지 + +- 프로젝트에 파일 기반 로드맵을 처음 만들 때 +- 사용자가 "로드맵 만들어줘", "마일스톤 설계해줘", "goal/phase 구조 잡아줘"라고 요청할 때 +- AI-first 개인/소규모 개발 프로젝트의 현재 방향성과 작업 기준을 구조화해야 할 때 +- 기존 README나 메모에 흩어진 계획을 `agent-ops/roadmap/` 구조로 분리할 때 + +## 입력 + +- `overall-goal`: 프로젝트 전체 Goal 한 줄 또는 짧은 문단 (선택, 없으면 README와 현재 구조에서 추론) +- `phase-hints`: 예상 Phase 목록 또는 단계 힌트 (선택) +- `milestone-hints`: 예상 Milestone 목록 또는 기능 힌트 (선택) +- `active-milestone`: 현재 진행 중인 Milestone 이름 또는 번호 (선택, 없으면 추론 후 사용자에게 확인) + +## 생성 구조 + +```text +agent-ops/ + roadmap/ + ROADMAP.md + current.md + milestones/ + M01-.md + M02-.md +``` + +| 파일 | 역할 | +|------|------| +| `agent-ops/roadmap/ROADMAP.md` | 전체 Goal, Phase 흐름, Milestone 인덱스. 로드맵 생성/갱신/Phase 전환 때만 읽는다 | +| `agent-ops/roadmap/current.md` | 현재 Phase와 Active Milestone 문서 경로를 가리키는 얇은 포인터 | +| `agent-ops/roadmap/milestones/MNN-.md` | 일반 작업 시 읽는 Milestone 단위 Goal, Scope, 기능 목록, Non-Goals | + +### current.md 형식 + +`agent-ops/roadmap/current.md`는 아래 형식을 유지한다. + +```markdown +# Current Roadmap Context + +- Active Phase: +- Active Milestone: +- Active Milestone File: agent-ops/roadmap/milestones/MNN-.md +``` + +## 먼저 확인할 것 + +- [ ] `agent-ops/roadmap/ROADMAP.md` 또는 `agent-ops/roadmap/current.md`가 이미 존재하는지 확인 +- [ ] 이미 존재하면 덮어쓰지 말고 `update-roadmap` 스킬 사용을 안내 +- [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인 +- [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인 +- [ ] `agent-ops/rules/project/rules.md`가 있으면 마일스톤 컨텍스트 로딩 섹션 추가 위치 확인 + +## 실행 절차 + +1. **기존 로드맵 확인** + - `agent-ops/roadmap/` 하위 기존 파일 존재 여부를 확인한다 + - 기존 로드맵이 있으면 새로 만들지 않고 `update-roadmap`을 사용하도록 안내한다 + - 일부 파일만 있으면 누락 파일을 보완할지, 기존 구조를 유지할지 사용자에게 짧게 확인한다 + +2. **프로젝트 방향 분석** + - README와 프로젝트 규칙에서 대상 사용자, 해결하려는 문제, 현재 구현 상태를 파악한다 + - 전체 코드를 정독하지 않는다. 로드맵 설계에 필요한 문서와 상위 구조만 확인한다 + - 불확실한 제품 방향은 단정하지 않고 "가정" 또는 ``로 남긴다 + +3. **Goal / Phase / Milestone 설계** + - 전체 Goal은 프로젝트가 궁극적으로 만들려는 결과를 1~3문장으로 작성한다 + - Phase는 큰 진화 단위로 나누고, 각 Phase에 Goal을 둔다 + - Milestone은 Phase 안에서 완료 판단이 가능한 단위로 나눈다 + - Milestone ID는 `M01`, `M02`처럼 2자리 번호를 사용하고 파일명은 `M01-.md`로 만든다 + - 상태 값은 `Planned`, `Active`, `Done`, `Paused`, `Dropped` 중 하나만 사용한다 + +4. **로드맵 파일 생성** + - `agent-ops/roadmap/ROADMAP.md`에는 전체 Goal, 현재 위치, Phase 개요, Milestone 인덱스, 로딩 정책을 작성한다 + - `agent-ops/roadmap/current.md`에는 정해진 `current.md 형식` 그대로 Active Phase와 Active Milestone 문서 경로만 작성한다 + - 각 Milestone 문서에는 아래 섹션을 포함한다 + - `Goal` + - `Phase` + - `Status` + - `Scope` + - `Required Features` + - `Success Criteria` + - `Non-Goals` + - `Context for Work` + - 미래 Milestone은 확정된 내용만 작성하고, 불확실한 기능은 TODO로 둔다 + +5. **마일스톤 컨텍스트 로딩 규칙 추가** + - `agent-ops/rules/project/rules.md`가 있으면 아래 섹션을 추가한다 + ```markdown + ## 마일스톤 컨텍스트 로딩 + + - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. + - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. + - 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. + ``` + - 같은 섹션이 이미 있으면 중복 추가하지 않고 필요한 문장만 보완한다 + - `agent-ops/rules/project/rules.md`가 없으면 파일을 새로 만들지 말고, 추가하지 못한 항목으로 보고한다 + +6. **결과 보고** + - 생성한 로드맵 파일 목록 + - Active Phase와 Active Milestone + - `rules/project/rules.md`에 추가한 로딩 규칙 여부 + - 확인이 필요한 TODO 또는 가정 + +## 실행 결과 검증 + +- [ ] `agent-ops/roadmap/ROADMAP.md`가 생성되었는가 +- [ ] `agent-ops/roadmap/current.md`가 Active Milestone 문서 경로를 정확히 가리키는가 +- [ ] `agent-ops/roadmap/milestones/` 하위에 Milestone 문서가 생성되었는가 +- [ ] 각 Milestone 문서가 필수 섹션을 포함하는가 +- [ ] `ROADMAP.md`에 전체 로드맵을 일반 작업마다 읽지 말라는 로딩 정책이 포함되었는가 +- [ ] `agent-ops/rules/project/rules.md`가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 추가되었는가 +- 검증 실패 시: 누락된 파일이나 섹션만 보완하고 기존 내용을 덮어쓰지 않는다 + +## 출력 형식 + +```markdown +## 생성 완료 + +- Roadmap: agent-ops/roadmap/ROADMAP.md +- Current Context: agent-ops/roadmap/current.md +- Active Milestone: agent-ops/roadmap/milestones/MNN-.md +- Project Rules 업데이트: <추가함 | 이미 존재함 | rules/project/rules.md 없음> + +## 현재 위치 + +- Phase: +- Milestone: + +## TODO 항목 + +- <확인이 필요한 가정 또는 미정 항목> (해당 시) +``` + +## 금지 사항 + +- 기존 `agent-ops/roadmap/` 파일을 덮어쓰지 않는다 +- 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다 +- Milestone 문서를 단순 TODO 목록으로만 만들지 않는다. 반드시 Goal, Scope, Success Criteria, Non-Goals를 포함한다 +- 확정되지 않은 제품 방향을 사실처럼 단정하지 않는다 +- `agent-ops/rules/common/`이나 `agent-ops/skills/common/`을 타겟 프로젝트에서 직접 수정하지 않는다 diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index daa9cd0..b3527e3 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -5,6 +5,8 @@ | agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘 | `agent-ops/skills/common/init-agent-ops/SKILL.md` | | domain rule 만들어줘, rules.md 생성, 새 도메인 규칙 | `agent-ops/skills/common/create-domain-rule/SKILL.md` | | skill 만들어줘, SKILL.md 생성, 새 스킬 추가 | `agent-ops/skills/common/create-skill/SKILL.md` | +| 로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘 | `agent-ops/skills/common/create-roadmap/SKILL.md` | +| 로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경 | `agent-ops/skills/common/update-roadmap/SKILL.md` | | 계획 세워줘, 구현 계획, PLAN.md, plan | `agent-ops/skills/common/plan/SKILL.md` | | 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` | | 커밋해줘, 푸시해줘, commit, push, 반영해줘 | `agent-ops/skills/common/commit-push/SKILL.md` | diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md new file mode 100644 index 0000000..c41a6f5 --- /dev/null +++ b/agent-ops/skills/common/update-roadmap/SKILL.md @@ -0,0 +1,130 @@ +--- +name: update-roadmap +version: 1.0.0 +description: 기존 Goal, Phase, Milestone 기반 로드맵을 갱신하고 current.md와 Active Milestone 정의를 동기화하는 공통 스킬 +--- + +# Update Roadmap + +## 목적 + +기존 `agent-ops/roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다. +로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`와 Active Milestone 문서가 실제 작업 기준으로 동작하게 한다. + +## 언제 호출할지 + +- 사용자가 "로드맵 업데이트", "마일스톤 갱신", "phase 변경", "현재 마일스톤 바꿔줘"라고 요청할 때 +- Milestone 완료, 보류, 폐기, 신규 추가가 필요할 때 +- Active Milestone의 Goal, Scope, Required Features, Success Criteria가 달라졌을 때 +- 실제 구현 상태와 로드맵 파일이 어긋난 것 같아 동기화가 필요할 때 + +## 입력 + +- `mode`: `status` / `milestone` / `phase` / `replan` / `sync` 중 하나 (선택, 요청에서 추론 가능) +- `target-milestone`: 갱신할 Milestone ID 또는 이름 (선택) +- `change-summary`: 반영할 방향 변경 또는 진행 상황 요약 (선택) +- `evidence`: 완료 판단에 사용할 파일, PR, 테스트, 커밋, 사용자 설명 (선택) + +## 모드 + +| mode | 사용 상황 | +|------|-----------| +| `status` | 기능 체크박스, Milestone 상태, 완료 기준만 갱신 | +| `milestone` | Milestone Goal, Scope, 기능 목록, Success Criteria 수정 | +| `phase` | Active Phase 또는 Active Milestone 전환 | +| `replan` | 전체 Phase/Milestone 흐름 재구성 | +| `sync` | 실제 프로젝트 상태와 로드맵 불일치 점검 후 보정 | + +## 먼저 확인할 것 + +- [ ] `agent-ops/roadmap/ROADMAP.md` 존재 여부 확인 +- [ ] `agent-ops/roadmap/current.md` 존재 여부 확인 +- [ ] `current.md`가 가리키는 Active Milestone 문서 존재 여부 확인 +- [ ] `current.md`가 정해진 형식을 유지하는지 확인 +- [ ] 로드맵 파일이 없으면 `create-roadmap` 스킬 사용을 안내하고 중단 +- [ ] 완료 상태로 바꾸는 경우 사용자의 명시 또는 확인 가능한 evidence가 있는지 확인 + +## 실행 절차 + +1. **갱신 범위 결정** + - 요청에서 mode와 target milestone을 추론한다 + - `status` 갱신이면 `current.md`와 대상 Milestone 문서를 우선 읽는다 + - Phase 전환, Milestone 추가/삭제, 순서 변경, 전체 재계획이면 `ROADMAP.md`도 읽는다 + - 불필요하게 모든 Milestone 문서를 읽지 않는다 + +2. **현재 로드맵 상태 파악** + - `ROADMAP.md`의 전체 Goal, Phase 개요, Milestone 인덱스를 확인한다 + - `current.md`의 Active Phase와 Active Milestone 포인터를 확인한다 + - 대상 Milestone 문서의 Goal, Scope, Required Features, Success Criteria, Non-Goals를 확인한다 + +3. **변경 내용 검증** + - 기능 완료 체크는 사용자 설명 또는 파일/테스트/커밋 등 확인 가능한 근거를 기준으로 한다 + - evidence 없이 완료 여부가 불확실하면 체크하지 않고 TODO 또는 확인 필요로 남긴다 + - 변경 요청이 전체 Goal 또는 Phase Goal과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다 + +4. **로드맵 파일 갱신** + - `ROADMAP.md`는 전체 Goal, Phase 개요, Milestone 인덱스, 현재 위치가 바뀔 때만 수정한다 + - `current.md`는 Active Phase 또는 Active Milestone이 바뀔 때 아래 형식으로 수정한다 + ```markdown + # Current Roadmap Context + + - Active Phase: + - Active Milestone: + - Active Milestone File: agent-ops/roadmap/milestones/MNN-.md + ``` + - Milestone 문서는 해당 Milestone의 Goal, Scope, Required Features, Success Criteria, Non-Goals, Context for Work가 바뀔 때 수정한다 + - 상태 값은 `Planned`, `Active`, `Done`, `Paused`, `Dropped` 중 하나만 사용한다 + - 완료된 Milestone의 기록은 삭제하지 않고 상태만 변경한다 + +5. **마일스톤 컨텍스트 로딩 규칙 점검** + - `agent-ops/rules/project/rules.md`가 있으면 `## 마일스톤 컨텍스트 로딩` 섹션이 있는지 확인한다 + - 없으면 `create-roadmap`과 동일한 로딩 규칙을 추가한다 + - 기존 섹션이 있으면 전체 `ROADMAP.md`를 일반 작업마다 읽도록 되어 있지 않은지 확인하고 보정한다 + +6. **결과 보고** + - 수정한 파일 목록 + - 변경된 Phase / Milestone / 상태 + - 체크하거나 추가/제거한 Required Features + - 확인 필요로 남긴 항목 + +## 실행 결과 검증 + +- [ ] `current.md`의 Active Milestone 경로가 실제 파일을 가리키는가 +- [ ] `current.md`가 `# Current Roadmap Context`, `Active Phase`, `Active Milestone`, `Active Milestone File` 형식을 유지하는가 +- [ ] `ROADMAP.md`의 현재 위치와 Milestone 인덱스가 `current.md`와 일치하는가 +- [ ] 대상 Milestone 문서의 상태가 `ROADMAP.md`의 Milestone 인덱스 상태와 일치하는가 +- [ ] 완료 처리한 기능에 사용자 설명 또는 확인 가능한 evidence가 있는가 +- [ ] `rules/project/rules.md`가 있는 경우 마일스톤 컨텍스트 로딩 섹션이 유지되는가 +- 검증 실패 시: 불일치한 파일만 다시 읽고 해당 항목만 수정한다 + +## 출력 형식 + +```markdown +## 업데이트 완료 + +- Mode: +- 수정 파일: + - agent-ops/roadmap/ROADMAP.md + - agent-ops/roadmap/current.md + - agent-ops/roadmap/milestones/MNN-.md + +## 변경 사항 + +- Phase: <변경 없음 | 이전 → 이후> +- Active Milestone: <변경 없음 | 이전 → 이후> +- Status: <변경 없음 | 이전 → 이후> +- Required Features: <추가/수정/완료/제거 요약> + +## TODO 항목 + +- <확인이 필요한 항목> (해당 시) +``` + +## 금지 사항 + +- 로드맵 파일이 없는데 새 구조를 임의로 만들지 않는다. 이 경우 `create-roadmap`을 사용한다 +- evidence 없이 기능이나 Milestone을 완료 처리하지 않는다 +- 전체 `ROADMAP.md`를 모든 작업의 필수 로딩 파일로 만들지 않는다 +- 완료된 Milestone 기록을 삭제하지 않는다 +- Milestone Goal과 Non-Goals를 무시하고 기능 목록만 갱신하지 않는다 +- 타겟 프로젝트에서 `agent-ops/rules/common/` 또는 `agent-ops/skills/common/`을 직접 수정하지 않는다