toki/agentic-framework
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

document roadmap runtime boundary

Browse source
This commit is contained in:
toki 2026-05-27 17:16:37 +09:00
parent 1c355c073b
commit 1a1cad62ce
9 changed files with 206 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
README.md
View file

@ -8,7 +8,7 @@ AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-o
이 저장소는 `agent-ops/` 공통 파일의 원본 저장소입니다. 루트의 `.agent-ops-source` 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다.
현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.68`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.
현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.77`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다.
## 빠른 시작
@ -74,11 +74,13 @@ agent-ops/
<skill-name>/SKILL.md
project/
<skill-name>/SKILL.md
roadmap/
ROADMAP.md
current.md
milestones/<milestone-slug>.md
archive/YYYY/MM/<milestone-slug>.md
agent-roadmap/
ROADMAP.md
current.md
phase/<phase-slug>/PHASE.md
phase/<phase-slug>/milestones/<milestone-slug>.md
archive/phase/<phase-slug>/PHASE.md
archive/phase/<phase-slug>/milestones/<milestone-slug>.md
```
`agent-roadmap/`은 `create-roadmap` 실행 시 생성됩니다.
@ -131,7 +133,7 @@ agent-ops는 AI-first 작업 프레임워크입니다. 규칙, 스킬, 로드맵
| `create-skill` | 새 공통 또는 프로젝트 스킬 생성 |
| `create-readme` | AI가 다음 작업에 활용할 수 있는 표준형 README 생성 |
| `create-roadmap` | 한국어 기반 Goal/Phase/Milestone 로드맵 생성 |
| `update-roadmap` | 기존 로드맵 상태, Milestone, Phase, 한국어 문서 형식 갱신과 과거 Milestone 아카이빙 |
| `update-roadmap` | 로드맵 변경 제안, 문서 형식 갱신, Core/MCP action이 없는 경우의 file-based fallback 갱신 |
| `analyze-roadmap-position` | "지금 작업이 뭐지?" 같은 질문에 전체 로드맵상 현재 Phase/Milestone 좌표를 빠르게 표시 |
| `plan` | 구현 작업용 `PLAN-*-G??.md`와 `CODE_REVIEW-*-G??.md` 초안 생성 |
| `code-review` | plan-code-review 루프의 리뷰, 판정, archive, 후속 plan 생성 |
@ -147,13 +149,15 @@ agent-ops는 AI-first 작업 프레임워크입니다. 규칙, 스킬, 로드맵
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.
로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 따릅니다. 해야 할 작업은 Milestone 문서의 `필수 기능` 체크리스트로, 완료 판단 조건은 `완료 기준` 체크리스트로 관리합니다.
로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 따릅니다. 해야 할 작업은 Milestone 문서의 `기능` 체크리스트로 관리하고, 완료 판단 조건은 필요한 Task 안의 `검증:` 문구로 흡수합니다.
로드맵 스킬은 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당합니다. Core/MCP가 있는 프로젝트에서는 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리합니다.
현재 작업 지점 답변은 `agent-ops/skills/common/_templates/roadmap-position-report-template.md` 형식을 따릅니다.
로드맵 현지점 확인에서는 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽습니다.
완료 또는 폐기되어 현재 후보에서 제외할 과거 Milestone은 `agent-roadmap/archive/YYYY/MM/`로 이동합니다. 이때 `ROADMAP.md`에는 `아카이브 Milestone 요약`만 남기고, 아카이브된 Milestone 문서는 아카이빙 당시 기록 스냅샷으로 보존하며 최신 스킬 규약에 맞춰 재포맷하지 않습니다.
완료 또는 폐기되어 현재 후보에서 제외할 과거 Phase/Milestone은 `agent-roadmap/archive/phase/<phase-slug>/`로 이동합니다. 이때 활성 `ROADMAP.md` 또는 `PHASE.md`에는 archive 링크와 짧은 요약만 남기고, 아카이브된 문서는 당시 기록 스냅샷으로 보존하며 최신 스킬 규약에 맞춰 재포맷하지 않습니다.
## 적용

2
agent-ops/.version
View file

@ -1 +1 @@
1.1.75
1.1.78

21
agent-ops/GUIDE.md
View file

@ -46,13 +46,6 @@ agent-ops/
│ │ └── <domain-name>/rules.md
│ └── private/ # 개인 규칙 (git 제외, 선택)
│ └── rules.md
├── roadmap/ # 프로젝트 로드맵 (create-roadmap 실행 시 생성)
│ ├── ROADMAP.md
│ ├── current.md
│ ├── milestones/
│ │ └── <milestone-slug>.md
│ └── archive/
│ └── YYYY/MM/<milestone-slug>.md
└── skills/
├── common/ # 공통 스킬 (수정 금지)
│ ├── router.md # 공통 스킬 라우터
@ -70,24 +63,32 @@ agent-ops/
│ ├── create-skill/SKILL.md # 스킬 생성
│ ├── create-readme/SKILL.md # README 생성
│ ├── create-roadmap/SKILL.md # Goal/Phase/Milestone 로드맵 생성
│ ├── update-roadmap/SKILL.md # 로드맵 상태/마일스톤 갱신과 아카이빙
│ ├── update-roadmap/SKILL.md # 로드맵 변경 제안과 file-based fallback 갱신
│ ├── analyze-roadmap-position/SKILL.md # 로드맵 현지점 확인
│ └── update-domain-rule/SKILL.md # 도메인 규칙 수정
└── project/ # 프로젝트 스킬 (수정 가능)
└── <skill-name>/SKILL.md
agent-roadmap/ # 프로젝트 로드맵 (create-roadmap 실행 시 생성)
├── ROADMAP.md
├── current.md
├── phase/<phase-slug>/PHASE.md
├── phase/<phase-slug>/milestones/<milestone-slug>.md
└── archive/phase/<phase-slug>/...
```
로드맵 문서는 사람이 함께 검토하고 수정하는 협업 문서이므로 전체 구성과 설명 문장을 기본 한국어로 작성합니다. Goal, Phase, Milestone, API 같은 일반 개발 용어와 파일명, 경로, slug 같은 식별자는 영어 또는 숫자를 유지할 수 있습니다.
Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다.
로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 기준으로 작성합니다. 해야 할 작업은 Milestone 문서의 `필수 기능` 체크리스트로 두고, 완료 여부를 검증하는 조건은 `완료 기준` 체크리스트로 둡니다.
로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 기준으로 작성합니다. 해야 할 작업은 Milestone 문서의 `기능` 체크리스트로 두고, 완료 여부를 검증하는 조건은 필요한 Task 안의 `검증:` 문구로 둡니다.
로드맵 스킬은 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당합니다. Core/MCP가 있는 프로젝트에서는 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리합니다.
Milestone의 `구현 잠금`은 승인 절차가 아니라 사용자 결정이 필요한지 표시하는 상태 기록입니다. 제품 방향, 범위, 우선순위, 설계 경계처럼 사용자 결정이 필요한 항목이 있으면 `잠금`으로 두고 `결정 필요` 체크리스트에 질문을 적습니다. 작업에 필요한 결정이 이미 정해져 에이전트가 실행만 하면 되는 Milestone은 `해제`로 둡니다.
현재 작업 지점 답변은 `agent-ops/skills/common/_templates/roadmap-position-report-template.md` 형식을 기준으로 작성합니다.
완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Milestone은 `agent-roadmap/archive/YYYY/MM/`로 이동합니다. 이때 `ROADMAP.md`에는 `아카이브 Milestone 요약`만 남기고, 아카이브 문서는 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 읽습니다.
완료 또는 폐기되어 현재 작업 후보에서 제외할 과거 Phase/Milestone은 `agent-roadmap/archive/phase/<phase-slug>/`로 이동합니다. 이때 활성 `ROADMAP.md` 또는 `PHASE.md`에는 archive 링크와 짧은 요약만 남기고, 아카이브 문서는 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 읽습니다.
---

7
agent-ops/rules/common/philosophy.md
View file

@ -52,9 +52,10 @@
- 스킬 그룹끼리는 다른 그룹의 내부 절차를 자동 호출하거나 전제하지 않는다.
- 그룹 간 연결은 사용자 명령, 런타임 이벤트, 또는 판별 가능한 파일 상태로만 한다.
- 구현 작업 그룹은 `plan`과 `code-review`의 PLAN/CODE_REVIEW 루프를 소유한다.
- 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 Phase/Milestone 상태, 구현 잠금, archive 흐름을 소유한다.
- `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 `update-roadmap` 흐름으로 넘긴다.
- cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹과 런타임의 책임이다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다.
- 로드맵 그룹은 `create-roadmap`과 `update-roadmap`의 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신 흐름을 소유한다.
- Phase/Milestone 상태 전환, 구현 잠금 동기화, archive 이동, 완료 이벤트 반영처럼 결정적으로 판별 가능한 action은 NomadCode Core 또는 런타임이 있으면 그쪽 책임으로 둔다.
- `code-review`가 남긴 PASS 완료 이벤트를 로드맵에 반영할지, 언제 반영할지는 런타임이 판단하고 Core/MCP action이 있으면 그쪽으로, 없으면 `update-roadmap` file-based fallback 흐름으로 넘긴다.
- cross-project 잠금이나 `.agent-roadmap-sync` 같은 workspace-level 상태는 로드맵 그룹, Core, 런타임의 공동 경계다. `plan`과 `code-review`에 의존성 동기화 규칙을 넣지 않는다.
- 새 스킬을 만들기 전에 기존 그룹의 자연스러운 입력, 상태 전환, 후처리 지점에 넣을 수 있는지 먼저 본다. 다만 다른 그룹 경계를 침범해야 하면 런타임 이벤트로 분리한다.
## 로드맵

19
agent-ops/rules/common/rules-roadmap.md
View file

@ -12,6 +12,13 @@
- 진행중 Phase 안에서 완료된 Milestone은 활성 `PHASE.md`에 짧은 archive 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.
- archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
## Runtime Action Boundary
- 로드맵 스킬은 기본적으로 로드맵 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당한다.
- Core/MCP가 있는 프로젝트에서는 Phase/Milestone 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리한다.
- Core/MCP가 없거나 아직 해당 action을 제공하지 않는 프로젝트에서만 `update-roadmap` 스킬이 file-based fallback으로 직접 문서를 갱신한다.
- `update-roadmap`은 fallback 갱신을 수행하더라도 런타임 action 경계를 문서화하고, Core/MCP로 넘길 수 있는 입력과 결과를 함께 남긴다.
## 로딩
- 세션 최초 1회 `agent-roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다.
@ -28,7 +35,7 @@
- 활성 Phase는 `agent-roadmap/phase/**/PHASE.md`만 대상으로 한다.
- 활성 Milestone은 `agent-roadmap/phase/**/milestones/*.md`만 대상으로 한다.
- `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 `[검토중]`으로 둔다.
- "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 `update-roadmap` 스킬로 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
- "로드맵에 추가", "마일스톤에 추가"처럼 target 없는 신규 작업 추가 요청은 `update-roadmap` 스킬로 배치 제안 또는 file-based fallback 갱신을 처리하고, Phase/Milestone/Epic/Task 배치를 자동 판단한다.
- target 없는 신규 추가 요청은 먼저 요청 규모를 `phase`, `milestone`, `epic`, `task`, `subtask`, `context` 중 가장 작은 충분한 단위로 판정한다.
- target 없는 신규 추가 요청은 활성 창만으로 결정하지 말고 필요한 경우 `ROADMAP.md`의 Phase 흐름과 관련 Phase/Milestone 문서를 비교한다.
- 배치는 Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다.
@ -67,7 +74,7 @@
## 프로젝트 간 잠금
- 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 파일이 없어도 `update-roadmap`이 디렉터리와 파일을 만든다.
- 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`은 프로젝트 간 Milestone 잠금 인덱스다. 외부 의존 잠금을 생성하거나 동기화해야 하면 Core/MCP가 있으면 그쪽 action이 만들고, 없으면 `update-roadmap` file-based fallback이 디렉터리와 파일을 만든다.
- entry는 `id`, `locked`, `rely-on[].target`, `rely-on[].status`, `rely-on[].note`만 사용한다.
- `locks.yaml`은 root sequence block style을 기본으로 작성한다. 예: `- id: ...` 아래에 `locked`, `rely-on`을 둔다.
- `id`는 기본적으로 `<잠긴-project>:<잠긴-milestone-slug>`로 만든다.
@ -84,8 +91,8 @@
- 같은 `id` entry를 upsert할 때 기존 `rely-on` 항목을 삭제하지 않는다. 같은 `rely-on.target`만 status/note를 갱신하고, 없는 target은 추가하며, `locked` 경로가 바뀐 경우에만 `locked`를 갱신한다.
- `locks.yaml`이 있고 Milestone을 갱신하거나 archive할 때는 대상 Milestone identity로 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" both "<locks-file>"`를 먼저 실행한다.
- find 결과가 `none`이면 결과 보고의 `Workspace 잠금`에 `관련 lock 없음`을 남긴다. 외부 의존 잠금 생성/동기화 요청이 아니라면 `locks.yaml`을 새로 만들거나 수정하지 않는다.
- `update-roadmap`이 갱신한 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 Milestone 상태 기준으로 `status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다.
- `update-roadmap`이 갱신하거나 선택한 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 런타임이 별도 `update-roadmap` 호출로 처리한다.
- Core/MCP action 또는 `update-roadmap` fallback이 갱신한 Milestone identity가 어느 entry의 `rely-on.target`과 일치하면 Milestone 상태 기준으로 `status`를 동기화한다. `[검토중]` 또는 `[완료]`이면 `enable`, 그 외 상태면 `disable`이다.
- Core/MCP action 또는 `update-roadmap` fallback이 갱신하거나 선택한 Milestone identity가 어느 entry의 `locked`와 일치하면 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 모든 조건이 충족되어도 잠금 해제 실행은 Core/MCP 또는 런타임의 별도 action으로 처리한다.
- archive 모드에서는 파일 이동 전에 대상 Milestone의 활성 경로 identity를 보존하고, 그 identity로 `--find-milestone "<identity>" both "<locks-file>"`를 먼저 실행한다. 보존한 identity가 어느 entry의 `rely-on.target`과 일치하고 Milestone 상태가 `[완료]`이면 archive 이동 전에 해당 `rely-on.status`를 `enable`로 바꾼다.
- archive 모드에서 보존한 identity가 어느 entry의 `locked`와 일치하면 archive 이동 전에 모든 `rely-on.status`가 `enable`인지 결과 보고에 남긴다. 미충족이어도 archive 자체는 막지 않고 `Workspace 잠금: 미충족`으로 보고한다.
- 잠금 해제 조건 충족 여부만 확인할 때는 `agent-ops/skills/common/check-roadmap-dependency/SKILL.md`를 읽는다. lock id가 없으면 해당 스킬은 `agent-ops/bin/roadmap-dependency-checker.sh --find-milestone "<identity>" "<direction>" "<locks-file>"`로 현재 Milestone이 `locked`인지 `rely-on.target`인지 양방향으로 찾은 뒤 `agent-ops/bin/roadmap-dependency-checker.sh "<lock-id>" "<locks-file>"`를 사용한다.
@ -114,7 +121,7 @@
- `m-<milestone-slug>`는 Milestone 기반 작업 전용 예약 prefix이며, 일반 작업 task group은 `m-`으로 시작하지 않는다.
- 런타임은 파일 내부가 아니라 task group 이름만으로 Milestone 기반 작업 여부를 판별한다.
- `code-review`에서 `m-<milestone-slug>` 작업이 PASS되면 roadmap을 직접 수정하거나 `update-roadmap`을 직접 호출하지 않는다.
- 런타임은 PASS 완료 이벤트의 task group에서 `m-<milestone-slug>`를 판별하고, 상태 체크 후 `update-roadmap` 흐름으로 Milestone 업데이트를 호출한다.
- 런타임은 PASS 완료 이벤트의 task group에서 `m-<milestone-slug>`를 판별하고, 상태 체크 후 Core/MCP action으로 Milestone 업데이트를 호출한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback 흐름을 호출한다.
- 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 `agent-task/archive/YYYY/MM/m-<milestone-slug>/...`를 `agent-task/m-<milestone-slug>/...` 형태의 `origin-task`로 정규화해 전달한다.
- 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다.
- `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 `m-<milestone-slug>` task group에서 follow-up plan/review를 이어가지만, code-review의 user-review gate가 트리거되면 `USER_REVIEW.md`를 남기고 사용자 판단을 기다린다.
@ -137,7 +144,7 @@
## 아카이브
- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 `update-roadmap` 스킬로 아카이빙한다.
- 완료 또는 폐기되어 현재 작업 후보에서 제외할 Phase/Milestone은 Core/MCP action으로 아카이빙한다. Core/MCP action이 없으면 `update-roadmap` file-based fallback으로 아카이빙한다.
- `[검토중]` Phase/Milestone은 archive 대상이 아니며, 사용자 승인 전까지 활성 경로에 남긴다.
- Phase 아카이브 대상은 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`와 같은 scaffold로 이동한다.
- Milestone 아카이브 대상은 `agent-roadmap/archive/phase/<phase-slug>/milestones/<milestone-slug>.md`로 이동한다.

42
agent-roadmap/ROADMAP.md Normal file
View file

@ -0,0 +1,42 @@
# Agent-Ops Roadmap
## 전체 목표
Agent Context Framework는 여러 프로젝트가 공통 agent-ops 규칙과 스킬을 공유하되, 에이전트가 필요한 문서만 읽고 안정적으로 작업하도록 만드는 공통 운영 프레임워크다.
로드맵 운영은 장기 기억과 작업 방향을 제공하는 문서 계층으로 유지하고, 상태 전환, 업데이트, archive, 의존성 동기화 같은 action은 NomadCode Core와 MCP 제어 표면으로 이관하는 방향으로 진화한다.
## Phase 흐름
위에서 아래로 진행된 순서와 예정 흐름을 나타낸다.
완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다.
검토중 또는 진행중 Phase는 계획 Phase보다 위에 두어, 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Phase는 아직 구현 가능한 계획이 아니므로 계획 Phase보다 아래에 둔다.
- [진행중] Roadmap Runtime Boundary
- 경로: `agent-roadmap/phase/roadmap-runtime-boundary/PHASE.md`
- 요약: roadmap 스킬을 작성/제안 계층으로 재정의하고, action 책임을 NomadCode Core와 MCP-first 외부 제어 표면으로 넘기는 공통 방향을 정리한다.
## 로딩 정책
- 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다.
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다.
- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- `current.md`의 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
- `current.md`의 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
- `current.md`는 `agent-roadmap/archive/**` 경로를 활성 항목으로 포함하지 않는다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
- 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다.
- `[스케치]` Phase/Milestone은 방향성, 문제의식, 후보 범위, 미정 질문을 기록하는 컨셉 상태이며 구현 계획 생성 대상이 아니다.
- `[스케치]` 항목은 `승격 조건`을 정리해 `[계획]`으로 전환한 뒤 구현 계획을 만든다.
- 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 `[완료]`로 전환한다.
- 완료된 Phase는 `agent-roadmap/archive/phase/<phase-slug>/PHASE.md`로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
- 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 `agent-roadmap/archive/phase/<phase-slug>/milestones/`로 이동한다.
- archive `PHASE.md`는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 `milestones/`만 있을 수 있다.
- `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`의 archive 링크를 따라가서 읽는다.
- 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 코드 구현, `agent-task` 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다.
- 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다.
- Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 `구현 잠금` 상태를 `해제`로 둔다.

28
agent-roadmap/current.md Normal file
View file

@ -0,0 +1,28 @@
# 현재 로드맵 컨텍스트
## 활성 Phase
- [진행중] Roadmap Runtime Boundary
- 경로: `agent-roadmap/phase/roadmap-runtime-boundary/PHASE.md`
## 활성 Milestone
- [계획] Roadmap Skill And MCP Boundary
- Phase: `agent-roadmap/phase/roadmap-runtime-boundary/PHASE.md`
- 경로: `agent-roadmap/phase/roadmap-runtime-boundary/milestones/roadmap-skill-mcp-boundary.md`
## 선택 규칙
- 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
- 활성 Phase는 `agent-roadmap/phase/<phase-slug>/PHASE.md`를 가리킨다.
- 활성 Milestone은 `agent-roadmap/phase/<phase-slug>/milestones/<milestone-slug>.md`를 가리킨다.
- 활성 항목은 아카이브 경로를 포함하지 않는다.
- `[검토중]` 항목은 사용자 완료 확인 전까지 활성 항목으로 남길 수 있다.
- `[스케치]` 항목은 활성 후보로 남길 수 있지만 구현 계획 생성 대상은 아니며, `[계획]` 승격 조건을 정리하는 대상으로만 다룬다.
- `[완료]` 또는 `[폐기]` 항목은 archive 링크를 남긴 뒤 활성 항목에서 제거한다.
- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다.
- 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다.
- 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
- 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다.
- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다.
- 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다.

26
agent-roadmap/phase/roadmap-runtime-boundary/PHASE.md Normal file
View file

@ -0,0 +1,26 @@
# Phase: Roadmap Runtime Boundary
## 상태
[진행중]
## 목표
로드맵 스킬이 직접 상태를 바꾸는 운영 방식에서 벗어나, 스킬은 의미 해석과 문서 작성, 변경 제안에 집중하고 action은 NomadCode Core와 MCP-first 제어 표면이 소유하도록 공통 경계를 재정의한다. 이 Phase가 끝나면 agent-ops common skills는 런타임 action owner가 아니라 proposal authoring layer로 읽히며, 외부 agent 제어는 MCP adapter를 통해 NomadCode Core로 전달되는 방향이 명확해진다.
## Milestone 흐름
완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.
스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다.
- [계획] Roadmap Skill And MCP Boundary
- 경로: `agent-roadmap/phase/roadmap-runtime-boundary/milestones/roadmap-skill-mcp-boundary.md`
- 요약: roadmap skill, NomadCode Core, MCP adapter, local fallback 사이의 책임 경계를 정리하고 공통 스킬 변경의 기준을 만든다.
## Phase 경계
- 이 Phase는 agent-ops 공통 문서와 스킬의 책임 경계를 다룬다.
- NomadCode Core의 실제 API, DB, worker, MCP server 구현은 NomadCode roadmap과 codebase에서 다룬다.
- IOP의 모델 라우팅, MCP/tool policy, output validation, RAG, context compression은 agent-ops 또는 NomadCode roadmap action runtime의 소유가 아니다.
- 공통 스킬은 NomadCode가 없는 프로젝트에서도 읽힐 수 있으므로, MCP/Core가 없을 때의 local proposal 또는 file-based fallback과 한계를 명시한다.

68
agent-roadmap/phase/roadmap-runtime-boundary/milestones/roadmap-skill-mcp-boundary.md Normal file
View file

@ -0,0 +1,68 @@
# Milestone: Roadmap Skill And MCP Boundary
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/roadmap-runtime-boundary/PHASE.md`
## 목표
로드맵 관련 공통 스킬의 책임을 작성, 해석, 후보 제안으로 낮추고, 업데이트, 상태 전환, archive, dependency lock, completion event 반영 같은 action은 NomadCode Core와 MCP-first 외부 제어 표면이 맡도록 기준을 정리한다. 이 Milestone은 agentic-framework의 공통 스킬 개편과 NomadCode의 roadmap control plane 구현 사이를 잇는 계약 문서다.
## 상태
[계획]
## 승격 조건
- 없음
## 구현 잠금
- 상태: 해제
- 결정 필요: 없음
## 범위
- roadmap skill과 runtime/Core/MCP 사이의 책임 경계 정리
- `create-roadmap`, `update-roadmap`, `analyze-roadmap-position`, `check-roadmap-dependency`의 향후 축소 기준 정의
- NomadCode Core가 소유할 action 목록과 MCP adapter가 노출할 외부 제어 표면 정의
- MCP/Core가 없는 프로젝트에서 사용할 local proposal 또는 file-based fallback 원칙 정의
- common rules, router, templates, README/GUIDE가 같은 계약을 말하도록 갱신하는 기준 정리
## 기능
### Epic: [boundary] Skill and runtime boundary
roadmap 운영에서 LLM이 맡을 의미 판단과 런타임이 맡을 결정적 action을 분리한다.
- [ ] [skill-authoring] roadmap 스킬을 의미 해석, 문서 초안, 변경 제안, 사용자 결정 질문 생성 계층으로 재정의한다.
- [ ] [runtime-actions] 파일 생성/수정/이동, 상태 전환, archive, current 동기화, completion event 반영, dependency lock sync를 NomadCode Core action으로 분리한다.
- [ ] [mcp-surface] 외부 agent 제어 표면을 MCP-first adapter로 정의하고, HTTP API는 NomadCode UI, webhook, internal integration용으로 남기는 기준을 문서화한다.
- [ ] [fallback-mode] NomadCode Core 또는 MCP가 없는 프로젝트에서 스킬이 local proposal 또는 승인된 file-based fallback을 수행할 수 있지만, 최종 지향점의 action owner는 아님을 명시한다.
- [ ] [contract-sync] common rules, router, roadmap templates, README/GUIDE, 관련 스킬 출력 형식이 같은 경계를 말하도록 갱신한다. 검증: `rg --sort path "agent-roadmap|필수 기능|완료 기준|archive/YYYY" agent-ops README.md`에서 의도하지 않은 구형 계약이 남지 않는다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- NomadCode Core의 실제 HTTP/MCP endpoint 구현
- NomadCode DB schema와 queue worker 구현
- IOP 모델 런타임, 모델 라우팅, MCP/tool policy, output validation 구현
- 외부 provider projection 세부 구현
## 작업 컨텍스트
- 관련 경로: `agent-ops/skills/common/create-roadmap/SKILL.md`, `agent-ops/skills/common/update-roadmap/SKILL.md`, `agent-ops/skills/common/analyze-roadmap-position/SKILL.md`, `agent-ops/skills/common/check-roadmap-dependency/SKILL.md`, `agent-ops/rules/common/rules-roadmap.md`, `agent-ops/rules/common/philosophy.md`
- 표준선(선택): 스킬은 사람과 LLM의 의미 판단을 돕는 authoring/proposal layer이고, action은 NomadCode Core가 검증 가능한 상태 전이로 처리한다. MCP는 Core를 외부 agent에게 여는 adapter이며 Core 자체가 아니다.
- 선행 작업: 로드맵 스킬 운영 복잡도 평가, NomadCode Core/MCP-first 방향성 합의
- 후속 작업: common roadmap skills 축소, NomadCode roadmap control plane 구현, MCP tool contract 작성
- 확인 필요: 없음