diff --git a/.gitignore b/.gitignore index 994eedc..4870ab8 100644 --- a/.gitignore +++ b/.gitignore @@ -20,4 +20,5 @@ ehthumbs.db !agent-task/**/ !agent-task/**/*.md !agent-task/**/*.log +agent-roadmap/current.md # END Agent-Ops managed gitignore diff --git a/README.md b/README.md index 7a9ca07..2fd8208 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ AI 에이전트가 매 작업마다 필요한 컨텍스트만 읽도록 `agent-o 이 저장소는 `agent-ops/` 공통 파일의 원본 저장소입니다. 루트의 `.agent-ops-source` 마커가 있으므로 공통 규칙, 공통 스킬, 동기화 스크립트는 이 저장소에서 수정하고 다른 프로젝트로 배포합니다. -현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.77`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다. +현재 프레임워크 버전은 `agent-ops/.version`에 기록되며, 이 README를 갱신한 시점의 버전은 `1.1.126`입니다. 이 저장소는 애플리케이션 런타임이 아니라 문서와 셸 스크립트 중심의 프레임워크라서 별도의 빌드나 테스트 설정 파일은 없습니다. ## 빠른 시작 @@ -76,7 +76,7 @@ agent-ops/ /SKILL.md agent-roadmap/ ROADMAP.md - current.md + current.md # local, git ignored phase//PHASE.md phase//milestones/.md archive/phase//PHASE.md @@ -111,7 +111,7 @@ agent-roadmap/ 스킬성 요청은 사용자가 명시적으로 요청했을 때 `agent-ops/skills/common/router.md`를 읽고, 매핑된 `SKILL.md` 하나를 실행합니다. 일반 작업마다 router와 모든 스킬을 자동으로 읽지 않습니다. -현재 작업 지점 질문은 `analyze-roadmap-position` 스킬이 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름을 읽고 `로드맵 > Phase > Milestone` breadcrumb로 빠르게 표시합니다. 기본 동작에서는 코드, git 상태, diff를 읽지 않습니다. +현재 작업 지점 질문은 `analyze-roadmap-position` 스킬이 로컬 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름을 읽고 `로드맵 > Phase > Milestone` breadcrumb로 빠르게 표시합니다. 기본 동작에서는 코드, git 상태, diff를 읽지 않습니다. `agent-roadmap/archive/**`는 완료 또는 폐기되어 현재 작업 후보에서 제외한 과거 Milestone 기록입니다. 일반 작업과 로드맵 분석에서는 읽지 않고, 사용자가 과거 기록 확인이나 복원을 명시적으로 요청한 경우에만 참조합니다. @@ -149,13 +149,13 @@ 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 문서의 `기능` 체크리스트로 관리하고, 완료 판단 조건은 필요한 Task 안의 `검증:` 문구로 흡수합니다. +로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 따릅니다. 로컬 `agent-roadmap/current.md`는 `roadmap-current-template.md` 형식으로 만들며 git 추적 대상이 아닙니다. 해야 할 작업은 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의 제목/목표/상태만 기본으로 읽습니다. +로드맵 현지점 확인에서는 로컬 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 Phase의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽습니다. 완료 또는 폐기되어 현재 후보에서 제외할 과거 Phase/Milestone은 `agent-roadmap/archive/phase//`로 이동합니다. 이때 활성 `ROADMAP.md` 또는 `PHASE.md`에는 archive 링크와 짧은 요약만 남기고, 아카이브된 문서는 당시 기록 스냅샷으로 보존하며 최신 스킬 규약에 맞춰 재포맷하지 않습니다. @@ -184,7 +184,7 @@ Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 ` | 일반 프로젝트 | `agent-ops/bin/sync.sh` | 현재 프로젝트의 공통 변경을 sibling 공통 원본 repo로 push | | 일반 프로젝트 | `agent-ops/bin/sync.sh --pull agentic-framework` | 공통 원본 repo의 공통 파일을 현재 프로젝트로 pull | -push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `entry-files.sh`에 정의된 진입 파일로 제한됩니다. 단, `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 push에서는 대상 프로젝트의 AI ignore / permission 파일을 덮어쓰지 않고 누락된 표준 설정만 보강하며, 버전을 올리지 않고 현재 `agent-ops/.version` 값을 그대로 전파합니다. 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 AI ignore / permission 파일을 보강하거나 stage하지 않으며, 공통 변경이 있으면 버전을 한 단계 올립니다. +push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `entry-files.sh`에 정의된 진입 파일로 제한됩니다. 단, `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 push에서는 대상 프로젝트의 AI ignore / permission 파일을 덮어쓰지 않고 누락된 표준 설정만 보강하며, 이미 추적 중인 `agent-roadmap/current.md`는 파일을 보존한 채 git 추적에서 제거합니다. 버전을 올리지 않고 현재 `agent-ops/.version` 값을 그대로 전파합니다. 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 AI ignore / permission 파일을 보강하거나 stage하지 않으며, 공통 변경이 있으면 버전을 한 단계 올립니다. ## 관리 원칙 @@ -194,6 +194,7 @@ push 대상은 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, - 공통 파일 변경 후에는 `agent-ops/.version`을 함께 관리하고 동기화합니다. - 이 프로젝트에서 작업을 하나 완료할 때마다 `agent-ops/bin/bump-version.sh`로 `agent-ops/.version`을 한 단계 올립니다. 단, 현재 프로젝트 루트에 `.agent-ops-source`가 있고 다른 프로젝트로 agent-ops push 동기화만 수행하는 작업에서는 버전을 올리지 않습니다. - `agent-ops/rules/private/`는 개인 규칙 영역이며 대상 프로젝트의 `.gitignore`에 추가됩니다. +- `agent-roadmap/current.md`는 브랜치별 로컬 로드맵 포인터이며 `.gitignore`로 추적 제외합니다. 초기 형식은 `agent-ops/skills/common/_templates/roadmap-current-template.md`를 사용합니다. ## 작업 맥락 diff --git a/agent-ops/.version b/agent-ops/.version index 59aa759..5bd0c3a 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.124 +1.1.126 diff --git a/agent-ops/GUIDE.md b/agent-ops/GUIDE.md index 2122bbd..28ae82f 100644 --- a/agent-ops/GUIDE.md +++ b/agent-ops/GUIDE.md @@ -70,7 +70,7 @@ agent-ops/ └── /SKILL.md agent-roadmap/ # 프로젝트 로드맵 (create-roadmap 실행 시 생성) ├── ROADMAP.md -├── current.md +├── current.md # local, git ignored ├── phase//PHASE.md ├── phase//milestones/.md └── archive/phase//... @@ -80,7 +80,7 @@ agent-roadmap/ # 프로젝트 로드맵 (create-roadm Phase와 Milestone에는 순번을 강제하지 않습니다. 진행 순서는 `ROADMAP.md`에 적힌 위에서 아래 순서로 봅니다. 새 작업을 추가할 때는 사용자가 지정한 위치를 우선하고, 단위 지정이 없으면 작업 성격을 보고 새 Milestone, 기존 Milestone의 태스크, 기존 태스크의 하위 작업 중 적절한 단위로 배치합니다. -로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 기준으로 작성합니다. 해야 할 작업은 Milestone 문서의 `기능` 체크리스트로 두고, 완료 여부를 검증하는 조건은 필요한 Task 안의 `검증:` 문구로 둡니다. +로드맵 문서는 `agent-ops/skills/common/_templates/roadmap-template.md`, `roadmap-current-template.md`, `roadmap-milestone-template.md` 형식을 기준으로 작성합니다. 로컬 `agent-roadmap/current.md`는 `roadmap-current-template.md` 형식으로 만들며 git 추적 대상이 아닙니다. 해야 할 작업은 Milestone 문서의 `기능` 체크리스트로 두고, 완료 여부를 검증하는 조건은 필요한 Task 안의 `검증:` 문구로 둡니다. 로드맵 스킬은 문서 작성, 의미 판단, 배치 제안, file-based fallback 갱신을 담당합니다. Core/MCP가 있는 프로젝트에서는 상태 전환, archive 이동, 외부 의존 lock 동기화, 완료 이벤트 반영 같은 action을 Core/MCP 또는 런타임이 처리합니다. diff --git a/agent-ops/bin/ai-ignore.sh b/agent-ops/bin/ai-ignore.sh index 17112a0..964ba95 100755 --- a/agent-ops/bin/ai-ignore.sh +++ b/agent-ops/bin/ai-ignore.sh @@ -3,6 +3,7 @@ # Shared AI ignore / permission defaults for init and sync flows. AGENT_OPS_TASK_ARCHIVE_IGNORE_PATTERN="agent-task/archive/**" AGENT_ROADMAP_ARCHIVE_IGNORE_PATTERN="agent-roadmap/archive/**" +AGENT_ROADMAP_CURRENT_LOCAL_PATTERN="agent-roadmap/current.md" AGENT_OPS_AI_IGNORE_BLOCK_BEGIN="# BEGIN Agent-Ops managed ignore" AGENT_OPS_AI_IGNORE_BLOCK_END="# END Agent-Ops managed ignore" AGENT_OPS_GITIGNORE_BLOCK_BEGIN="# BEGIN Agent-Ops managed gitignore" @@ -21,13 +22,15 @@ agent_ops_ensure_gitignore_task_artifact_block() { tmp="$(mktemp "$file.tmp.XXXXXX")" awk \ -v begin="$AGENT_OPS_GITIGNORE_BLOCK_BEGIN" \ - -v end="$AGENT_OPS_GITIGNORE_BLOCK_END" ' + -v end="$AGENT_OPS_GITIGNORE_BLOCK_END" \ + -v current="$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" ' $0 == begin { print begin print "!agent-task/" print "!agent-task/**/" print "!agent-task/**/*.md" print "!agent-task/**/*.log" + print current print end in_block = 1 next @@ -48,6 +51,7 @@ agent_ops_ensure_gitignore_task_artifact_block() { printf "%s\n" "!agent-task/**/" >> "$file" printf "%s\n" "!agent-task/**/*.md" >> "$file" printf "%s\n" "!agent-task/**/*.log" >> "$file" + printf "%s\n" "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" >> "$file" printf "%s\n" "$AGENT_OPS_GITIGNORE_BLOCK_END" >> "$file" fi } diff --git a/agent-ops/bin/sync.sh b/agent-ops/bin/sync.sh index a1a7592..21b7eca 100755 --- a/agent-ops/bin/sync.sh +++ b/agent-ops/bin/sync.sh @@ -156,6 +156,11 @@ commit_and_push_agent_ops_scope() { cd "$repo" mapfile -t paths < <(agent_ops_git_paths "$include_ai_config") git add -- "${paths[@]}" + if git ls-files --error-unmatch "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" >/dev/null 2>&1 \ + && grep -qxF "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" ".gitignore" 2>/dev/null; then + git rm --cached --quiet --ignore-unmatch "$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN" + paths+=("$AGENT_ROADMAP_CURRENT_LOCAL_PATTERN") + fi if git diff --cached --quiet -- "${paths[@]}"; then echo " agent-ops 변경 없음: commit 건너뜀" diff --git a/agent-ops/rules/common/philosophy.md b/agent-ops/rules/common/philosophy.md index 89f7df5..b1b41f7 100644 --- a/agent-ops/rules/common/philosophy.md +++ b/agent-ops/rules/common/philosophy.md @@ -61,7 +61,7 @@ ## 로드맵 - roadmap은 장기 기억이고, agent-task는 실행 상태다. -- current는 현재 작업 하나가 아니라 활성 Phase/Milestone 후보 창이다. +- current는 현재 작업 하나가 아니라 브랜치별 로컬 활성 Phase/Milestone 후보 창이다. - Phase와 Milestone은 큰 방향과 기능 단위를 담는다. - 구현 계획은 agent-task의 PLAN/CODE_REVIEW 루프에 둔다. - 완료 후보는 바로 archive하지 말고 `[검토중]`으로 둔다. diff --git a/agent-ops/rules/common/rules-roadmap.md b/agent-ops/rules/common/rules-roadmap.md index d59c512..0e0da16 100644 --- a/agent-ops/rules/common/rules-roadmap.md +++ b/agent-ops/rules/common/rules-roadmap.md @@ -21,17 +21,21 @@ ## 로딩 -- 세션 최초 1회 `agent-roadmap/current.md`를 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다. +- 세션 최초 1회 `agent-roadmap/current.md`가 있으면 읽고 활성 Phase, 활성 Milestone의 이름, 경로, 선택 규칙만 짧게 기억한다. +- `agent-roadmap/current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. +- `current.md`가 없고 로드맵 기반 계획 또는 갱신이 필요하면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만들거나 `ROADMAP.md`와 활성 `PHASE.md`에서 후보를 고른다. +- 읽기 전용 로드맵 현지점 확인에서는 `current.md`가 없어도 만들지 않고, 로컬 current 없음으로 보고한 뒤 `ROADMAP.md`의 Phase 흐름만 보여준다. - 일반 작업에서는 `ROADMAP.md`를 읽지 않는다. - 일반 작업에서는 `agent-roadmap/archive/**`를 읽지 않는다. - 기능 추가, 구조 변경, 구현 계획 전에는 요청과 변경 파일에 맞는 활성 Phase와 활성 Milestone 문서를 읽는다. -- 로드맵 현지점 확인은 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽는다. +- 로드맵 현지점 확인은 로컬 `current.md`, `ROADMAP.md`의 Phase 흐름, 활성 `PHASE.md`의 Milestone 흐름, 활성 Milestone의 제목/목표/상태만 기본으로 읽는다. - `ROADMAP.md`는 로드맵 생성/갱신, Phase 추가/삭제/전환, 전체 구조 변경, 활성 범위 밖 작업 확인 때만 읽는다. - 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 필요한 archive 문서만 읽는다. ## Phase와 Milestone 선택 - `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다. +- `current.md`는 공유 진행 상태가 아니며, 공유해야 할 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 남긴다. - 활성 Phase는 `agent-roadmap/phase/**/PHASE.md`만 대상으로 한다. - 활성 Milestone은 `agent-roadmap/phase/**/milestones/*.md`만 대상으로 한다. - `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 승인 전까지 `[검토중]`으로 둔다. @@ -81,8 +85,8 @@ - `locked`와 `rely-on[].target`은 `:agent-roadmap/phase//milestones/.md` 형식으로 기록한다. - Milestone 경로가 `agent-roadmap/...` 상대 경로이면 현재 프로젝트명을 prefix로 붙인다. workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 `agent-roadmap/...` 경로를 붙인다. - `locked`는 잠긴 Milestone, `rely-on.target`은 선행 조건 Milestone이다. 둘 다 같은 workspace의 어느 활성 Phase 하위 Milestone이어도 된다. 의존 대상이 `current.md`에 있어야 한다고 가정하지 않는다. -- "현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다. -- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 `current.md` 단일 후보 순서로 확정한다. +- "현재 마일스톤은 X 프로젝트 작업 뒤에 진행", "X 프로젝트 때문에 현재 작업 잠금", "의존성 설정해"처럼 잠긴 Milestone을 생략한 외부 의존 잠금 요청은 현재 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 삼는다. +- 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 `current.md`가 있을 때의 단일 후보 순서로 확정한다. - 정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 `-` 하나로 치환, 앞뒤 `-` 제거 후 Milestone 파일 slug와 정규화한 제목에 대조한다. - 의존 대상 탐색은 대상 프로젝트의 `agent-roadmap/phase/*/milestones/*.md` 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다. - 후보가 없거나 둘 이상이면 locks.yaml을 만들거나 고치지 말고 사용자에게 대상 Milestone 선택을 요청한다. @@ -150,5 +154,5 @@ - Milestone 아카이브 대상은 `agent-roadmap/archive/phase//milestones/.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 선택이나 위치 분석의 후보로 삼지 않는다. +- 아카이브된 Phase/Milestone은 로컬 `current.md`에 남기지 않고, 일반 Phase/Milestone 선택이나 위치 분석의 후보로 삼지 않는다. - 아카이브 문서는 과거 기록 스냅샷으로 보고, 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다. diff --git a/agent-ops/skills/common/_templates/roadmap-current-template.md b/agent-ops/skills/common/_templates/roadmap-current-template.md index 3169df9..3e4b94b 100644 --- a/agent-ops/skills/common/_templates/roadmap-current-template.md +++ b/agent-ops/skills/common/_templates/roadmap-current-template.md @@ -14,6 +14,7 @@ ## 선택 규칙 - 이 문서는 활성 Phase와 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. +- 이 문서는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. - 활성 Phase는 `agent-roadmap/phase//PHASE.md`를 가리킨다. - 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. - 활성 항목은 아카이브 경로를 포함하지 않는다. 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 ac7f9f5..ea057ea 100644 --- a/agent-ops/skills/common/_templates/roadmap-position-report-template.md +++ b/agent-ops/skills/common/_templates/roadmap-position-report-template.md @@ -1,6 +1,6 @@ # 로드맵 현지점 -- [current.md](agent-roadmap/current.md) +- [local current.md](agent-roadmap/current.md) - [로드맵: ](agent-roadmap/ROADMAP.md) - [Phase: ](agent-roadmap/phase//PHASE.md) diff --git a/agent-ops/skills/common/_templates/roadmap-template.md b/agent-ops/skills/common/_templates/roadmap-template.md index a8ecce3..b42dd53 100644 --- a/agent-ops/skills/common/_templates/roadmap-template.md +++ b/agent-ops/skills/common/_templates/roadmap-template.md @@ -20,6 +20,7 @@ - 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다. - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다. - `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다. +- `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. 로드맵 기반 계획/갱신에서 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 생성해 사용하고, 읽기 전용 현지점 확인에서는 생성하지 않는다. - `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - `current.md`의 활성 Phase는 `agent-roadmap/phase//PHASE.md`를 가리킨다. - `current.md`의 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. diff --git a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md index 44d8728..a8990e6 100644 --- a/agent-ops/skills/common/analyze-roadmap-position/SKILL.md +++ b/agent-ops/skills/common/analyze-roadmap-position/SKILL.md @@ -23,9 +23,9 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - [ ] `agent-ops/skills/common/_templates/roadmap-position-report-template.md`를 읽어 최신 답변 템플릿 확인 - [ ] `agent-roadmap/` 디렉터리 존재 여부 확인 -- [ ] `agent-roadmap/current.md` 존재 여부 확인 +- [ ] 로컬 `agent-roadmap/current.md` 존재 여부 확인 - [ ] 로드맵이 있으면 `ROADMAP.md`의 `Phase 흐름`을 확인 -- [ ] `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인 +- [ ] 로컬 `current.md`의 활성 Phase와 활성 Milestone 이름, 상태, 경로 확인 - [ ] 활성 Phase 문서의 `Milestone 흐름` 확인 - [ ] 활성 Milestone 문서의 제목, `목표`, `상태`만 확인 @@ -34,8 +34,8 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA 1. `agent-roadmap/` 존재 여부를 확인한다. - 없으면 로드맵 없음으로 짧게 보고하고 멈춘다. 2. `agent-ops/skills/common/_templates/roadmap-position-report-template.md`를 읽는다. -3. `agent-roadmap/current.md`를 확인한다. - - 없으면 current 없음으로 보고하고, `ROADMAP.md`가 있으면 `Phase 흐름`만 보여준다. +3. 로컬 `agent-roadmap/current.md`를 확인한다. + - 없으면 로컬 current 없음으로 보고하고, `ROADMAP.md`가 있으면 `Phase 흐름`만 보여준다. 4. `ROADMAP.md`의 `Phase 흐름`을 읽어 전체 Phase 목록을 만든다. - 각 Phase는 상태, 이름, 링크만 남긴다. - current의 활성 Phase와 일치하는 항목에 `← 현재` 표시를 붙인다. @@ -50,7 +50,7 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA ## 실행 결과 검증 - [ ] `roadmap-position-report-template.md`의 출력 구조를 유지했는가 -- [ ] `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태만 기본으로 읽었는가 +- [ ] 로컬 `current.md`, `ROADMAP.md`, 활성 `PHASE.md`, 활성 Milestone의 제목/목표/상태만 기본으로 읽었는가 - [ ] 완료 또는 archive Phase/Milestone은 링크만 표시하고 archive 문서를 읽지 않았는가 - [ ] current가 여러 Milestone을 가리키면 모두 `현재 후보`로 표시했는가 - [ ] 코드 파일, 테스트 파일, `git status`, `git diff`를 기본 동작에서 읽지 않았는가 @@ -70,5 +70,5 @@ description: "여러 레포를 전환할 때 코드/git 분석 없이 전체 ROA - 기본 동작에서 코드 파일, 테스트 파일, `git status`, `git diff`를 읽지 않는다. - 기본 동작에서 Milestone의 `기능` 체크리스트를 감사하지 않는다. - 완료 여부, 남은 작업, 코드와 문서의 동기화 상태를 evidence 기반으로 판정하지 않는다. -- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, `current.md`, Phase, Milestone 문서를 수정하지 않는다. +- 사용자가 명시하지 않은 상태에서 `ROADMAP.md`, 로컬 `current.md`, Phase, Milestone 문서를 수정하지 않는다. - 사용자가 과거 기록 확인을 명시하지 않으면 `agent-roadmap/archive/**`를 읽지 않는다. diff --git a/agent-ops/skills/common/check-roadmap-dependency/SKILL.md b/agent-ops/skills/common/check-roadmap-dependency/SKILL.md index 50c6531..d11ae00 100644 --- a/agent-ops/skills/common/check-roadmap-dependency/SKILL.md +++ b/agent-ops/skills/common/check-roadmap-dependency/SKILL.md @@ -22,14 +22,14 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep ## 입력 - `lock-id`: 확인할 lock entry id. 예: `oto:oto-agent-registration`. 명시되면 이 id만 판별한다 (선택) -- `target-milestone`: 확인할 Milestone path 또는 `:agent-roadmap/phase/.../milestones/.md`. 없으면 현재 프로젝트 `current.md`의 활성 Milestone 단일 후보를 사용한다 (선택) +- `target-milestone`: 확인할 Milestone path 또는 `:agent-roadmap/phase/.../milestones/.md`. 없으면 현재 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보를 사용한다 (선택) - `direction`: `locked` / `rely-on` / `both`. 기본값은 `both`다. `locked`는 대상 Milestone이 잠긴 entry만, `rely-on`은 대상 Milestone을 선행 조건으로 삼는 entry만 확인한다 (선택) - `locks-file`: 기본값은 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`이며, 다른 파일을 검사할 때만 지정한다 (선택) ## 먼저 확인할 것 - [ ] `agent-ops/bin/roadmap-dependency-checker.sh`가 있는지 확인한다. -- [ ] `lock-id`가 명시되었거나 `target-milestone` 또는 현재 프로젝트 `current.md`의 활성 Milestone 하나로 Milestone identity를 추론 가능한지 확인한다. +- [ ] `lock-id`가 명시되었거나 `target-milestone` 또는 현재 프로젝트 로컬 `current.md`의 활성 Milestone 하나로 Milestone identity를 추론 가능한지 확인한다. - [ ] 기본 경로 또는 지정된 `locks-file`을 읽을 수 있는지 확인한다. ## 실행 절차 @@ -39,7 +39,7 @@ Milestone identity 역검색과 개별 lock 판별은 `agent-ops/bin/roadmap-dep - `locks-file`이 명시되지 않았으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 사용한다. - `locks-file`이 없거나 읽을 수 없으면 결과를 `error`로 보고한다. 이를 미충족 의존성으로 해석하지 않는다. - `lock-id`가 있으면 그 id만 판별한다. - - `lock-id`가 없으면 `target-milestone` 또는 현재 프로젝트 `agent-roadmap/current.md`의 활성 Milestone 단일 후보로 Milestone identity를 만든다. + - `lock-id`가 없으면 `target-milestone` 또는 현재 프로젝트 로컬 `agent-roadmap/current.md`의 활성 Milestone 단일 후보로 Milestone identity를 만든다. - Milestone identity는 `:agent-roadmap/phase//milestones/.md` 형식이다. - `target-milestone`이 `agent-roadmap/...` 상대 경로이면 현재 프로젝트명을 prefix로 붙인다. - `target-milestone`이 workspace 하위 절대/상대 경로이면 workspace 바로 아래 디렉터리명을 project로 삼고, 그 뒤 `agent-roadmap/...` 경로를 붙인다. diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index 010b23b..777c6e1 100644 --- a/agent-ops/skills/common/code-review/SKILL.md +++ b/agent-ops/skills/common/code-review/SKILL.md @@ -195,7 +195,7 @@ Verdict consistency: ## Step 5 - Archive Active Files -Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Before the archive order, ensure `.gitignore` has the Agent-Ops managed gitignore block for task artifacts before writing `*.log` outputs. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, and `!agent-task/**/*.log`. +Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Before the archive order, ensure `.gitignore` has the Agent-Ops managed gitignore block for task artifacts before writing `*.log` outputs. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, and `agent-roadmap/current.md`. Archive order is fixed: @@ -309,7 +309,7 @@ task={task_name}, plan={N}, tag={TAG} - [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. - [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. - [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. -- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. - [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. - [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. - [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. @@ -435,7 +435,7 @@ Report Required/Suggested counts, archive names, the final task archive path for - `code_review_{review_lane}_GNN_N.log` exists with verdict appended. - `plan_{build_lane}_GNN_M.log` exists. -- `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log`; generated task artifacts are not ignored by `git check-ignore`. +- `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`; generated task artifacts are not ignored by `git check-ignore`. - No active `.md` files remain after PASS or user-review-resolved PASS. - 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. diff --git a/agent-ops/skills/common/create-readme/SKILL.md b/agent-ops/skills/common/create-readme/SKILL.md index 2437a93..074a18b 100644 --- a/agent-ops/skills/common/create-readme/SKILL.md +++ b/agent-ops/skills/common/create-readme/SKILL.md @@ -76,7 +76,7 @@ README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 - README 상단에는 프로젝트가 무엇을 해결하는지와 현재 사용할 수 있는 범위를 먼저 쓴다. - AI가 작업을 이어받을 때 필요한 경로, 명령, 검증 방법, 주요 문서를 명확한 제목과 표로 정리한다. - `agent-ops/`가 있으면 규칙, 로드맵, 스킬 문서를 참고 문서나 작업 맥락에 연결한다. -- `agent-roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다. +- 로컬 `agent-roadmap/current.md`가 있으면 README에 현재 작업 위치를 복사하지 말고, 로드맵을 확인할 문서 경로만 적는다. - README는 제품 소개 문서이면서 작업 진입점이다. 마케팅 문구보다 실행 가능한 정보와 프로젝트 경계를 우선한다. - README의 자연어 설명은 한국어 중심으로 작성한다. - 단, README, API, CLI, SDK, runtime, build, test, lint, deploy, workflow, migration, integration처럼 개발자가 흔히 쓰는 영어 표현과 제품명, 기술명, 패키지명, 명령, 경로, 코드 식별자는 자연스럽게 영어로 유지한다. @@ -88,7 +88,7 @@ README는 프로젝트 특성에 맞게 필요한 섹션만 사용하되, 기본 - [ ] 루트 `README.md` 존재 여부와 기존 내용 확인 - [ ] `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `docker-compose.yml` 등 실행/검증 명령 근거 확인 - [ ] `agent-ops/rules/project/rules.md`가 있으면 프로젝트 개요, 기술 스택, 도메인 매핑 확인 -- [ ] `agent-roadmap/ROADMAP.md` 또는 `agent-roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인 +- [ ] `agent-roadmap/ROADMAP.md` 또는 로컬 `agent-roadmap/current.md`가 있으면 제품 방향과 활성 Milestone 문서 경로만 확인 - [ ] 주요 소스 디렉터리와 테스트 디렉터리를 `rg --files`로 가볍게 확인 ## 실행 절차 diff --git a/agent-ops/skills/common/create-roadmap/SKILL.md b/agent-ops/skills/common/create-roadmap/SKILL.md index 33322f0..dc26686 100644 --- a/agent-ops/skills/common/create-roadmap/SKILL.md +++ b/agent-ops/skills/common/create-roadmap/SKILL.md @@ -1,7 +1,7 @@ --- name: create-roadmap version: 1.15.0 -description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬 +description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬 --- # 로드맵 생성 @@ -9,7 +9,7 @@ description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaf ## 목적 `agent-roadmap/` 하위에 `Roadmap -> Phase -> Milestone` 기반 한국어 로드맵 구조를 처음 생성한다. -전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다. +전체 로드맵은 전체 방향과 Phase index만 담당하고, 일반 작업에서는 브랜치별 로컬 `current.md`의 활성 Phase/Milestone 링크와 관련 문서만 읽도록 만든다. Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서다. Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다. @@ -32,7 +32,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능 ```text agent-roadmap/ ROADMAP.md - current.md + current.md # local, git ignored phase/ / PHASE.md @@ -49,7 +49,7 @@ agent-roadmap/ | 파일 | 역할 | |------|------| | `agent-roadmap/ROADMAP.md` | 전체 목표와 Phase 흐름만 담는 최상위 지도. 로드맵 생성/갱신/Phase 전환 때만 읽는다 | -| `agent-roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 얇은 포인터 | +| `agent-roadmap/current.md` | 활성 Phase와 활성 Milestone 후보, 선택 규칙을 담는 브랜치별 로컬 포인터 | | `agent-roadmap/phase//PHASE.md` | Phase 목표, 상태, Milestone 흐름, Phase 경계를 담는 문서 | | `agent-roadmap/phase//milestones/.md` | 일반 작업 시 읽는 Milestone 단위 목표, 스케치 승격 조건, 구현 잠금, 범위, 기능 Epic/Task 체크리스트, 범위 제외 항목 | | `agent-roadmap/archive/phase//...` | 완료 또는 폐기되어 현재 후보에서 제외한 과거 Phase/Milestone. 일반 작업에서는 읽지 않는다 | @@ -61,6 +61,7 @@ agent-roadmap/ - `PHASE.md`는 `agent-ops/skills/common/_templates/roadmap-phase-template.md` 형식을 따른다. - Milestone 문서는 `agent-ops/skills/common/_templates/roadmap-milestone-template.md` 형식을 따른다. - `ROADMAP.md`에는 Milestone 상세 체크리스트를 넣지 않는다. +- `current.md`는 git 추적 대상이 아니며, 예시 파일을 `agent-roadmap/`에 따로 만들지 않는다. - `current.md`는 활성 Phase/Milestone 후보만 담고, 개인별 현재 작업 위치나 완료 상태를 적지 않는다. - archive 경로는 `current.md`의 활성 항목에 넣지 않는다. @@ -97,7 +98,7 @@ agent-roadmap/ ## 먼저 확인할 것 -- [ ] `agent-roadmap/ROADMAP.md` 또는 `agent-roadmap/current.md`가 이미 존재하는지 확인 +- [ ] `agent-roadmap/ROADMAP.md` 또는 로컬 `agent-roadmap/current.md`가 이미 존재하는지 확인 - [ ] 이미 존재하면 덮어쓰지 말고 `update-roadmap` 스킬 사용을 안내 - [ ] `README.md`, `agent-ops/GUIDE.md`, `agent-ops/rules/project/rules.md` 등 프로젝트 방향을 설명하는 문서를 확인 - [ ] `rg --files`로 현재 프로젝트의 주요 구조를 가볍게 확인 @@ -122,17 +123,18 @@ agent-roadmap/ - Milestone 내부에서 여러 기능 묶음이 필요하면 Epic으로 선언하고, Epic 아래 flat Task 체크리스트를 둔다. 4. **파일 생성** - - `ROADMAP.md`, `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다. + - `ROADMAP.md`, 로컬 `current.md`, 각 Phase의 `PHASE.md`, 각 Milestone 문서를 템플릿 순서대로 생성한다. - 활성 Phase와 활성 Milestone은 `current.md`에 모두 기록한다. + - `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다. - `ROADMAP.md`의 Phase 흐름에는 완료/검토중/진행중/계획/스케치 Phase 모두를 위에서 아래 순서로 두고, 계획 Phase는 진행중 Phase보다 아래에, 스케치 Phase는 계획 Phase보다 아래에 둔다. - 완료된 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/`만 둘 수 있다. - - 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다. + - 외부 의존 잠금이 있으면 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`을 생성하거나 기존 entry를 upsert한다. 의존 대상이 명시 경로, slug, 제목, 문서 힌트, 로컬 current 단일 후보 중 하나로 확정되지 않으면 lock entry를 만들지 않고 TODO로 남긴다. 5. **검증** - 생성한 링크가 실제 파일을 가리키는지 확인한다. - - `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다. + - 로컬 `current.md` 활성 항목에 `agent-roadmap/archive/**` 경로가 없는지 확인한다. - Epic heading과 Task 체크리스트 id가 형식을 따르는지 확인한다. - 상태 표기가 `[진행중]`처럼 공백 없는 표준값인지 확인한다. - `[스케치]` Milestone에 `승격 조건` 섹션이 있고 `구현 잠금`이 `잠금`인지 확인한다. @@ -144,7 +146,7 @@ agent-roadmap/ ## 생성 완료 - 로드맵: agent-roadmap/ROADMAP.md -- 현재 컨텍스트: agent-roadmap/current.md +- 로컬 현재 컨텍스트: agent-roadmap/current.md - Phase 문서: - Milestone 문서: - 활성 Phase: @@ -167,7 +169,8 @@ agent-roadmap/ - 기존 `agent-roadmap/` 파일을 덮어쓰지 않는다. - 일반 작업마다 전체 `ROADMAP.md`를 읽도록 규칙을 만들지 않는다. -- `current.md`에 `agent-roadmap/archive/**` 경로를 넣지 않는다. +- 로컬 `current.md`에 `agent-roadmap/archive/**` 경로를 넣지 않는다. +- `agent-roadmap/current.md`를 git 추적 대상으로 만들지 않는다. - Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다. - `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 넣지 않는다. - Epic과 Task를 별도 파일로 분리하지 않는다. diff --git a/agent-ops/skills/common/init-agent-ops/SKILL.md b/agent-ops/skills/common/init-agent-ops/SKILL.md index c9a8822..03c0b78 100644 --- a/agent-ops/skills/common/init-agent-ops/SKILL.md +++ b/agent-ops/skills/common/init-agent-ops/SKILL.md @@ -73,7 +73,7 @@ description: 프로젝트 상태를 판별하고 agent-ops 기본 스캐폴드 | `agent-ops/rules/project/domain//rules.md` | 도메인 분석 후 생성 | | `agent-ops/rules/private/` | 폴더만 생성 (내용은 개인이 작성) | | `.gitignore`에 `agent-ops/rules/private/` 추가 | git 추적 제외 | -| `.gitignore`의 Agent-Ops 관리 block | `*.log` 같은 전역 ignore가 있어도 `agent-task/**/*.md`, `agent-task/**/*.log` task 산출물이 추적되도록 unignore 예외 추가 | +| `.gitignore`의 Agent-Ops 관리 block | `*.log` 같은 전역 ignore가 있어도 `agent-task/**/*.md`, `agent-task/**/*.log` task 산출물이 추적되도록 unignore하고 `agent-roadmap/current.md`는 로컬 포인터로 ignore | | `agent-test/local/rules.md` | `init-agent-ops.sh`가 최소 내용으로 생성 | | `agent-test/local/project-smoke.md` | 도메인이 아직 없으면 `init-agent-ops.sh`가 fallback baseline으로 생성 | | `agent-test/local/-smoke.md` | domain rule 생성 후 각 도메인별 기본 smoke 테스트 뼈대로 생성 | @@ -192,7 +192,7 @@ common/rules.md와 내용이 중복되지 않도록 한다. - 기존 `.claude/settings.json`이나 `opencode.json`에 `agent-roadmap/archive/**` hard read/glob deny가 있으면 init-agent-ops 표준에 맞게 제거한다 - 대상 루트에 `.agent-ops-source`가 있으면 AI ignore / permission 파일은 보강하지 않는다 - `agent-task/archive/**`와 `agent-roadmap/archive/**` ignore 항목은 `.gitignore`에 추가하지 않는다 - - `.gitignore`에는 Agent-Ops 관리 block으로 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log` 예외만 추가하거나 갱신한다 + - `.gitignore`에는 Agent-Ops 관리 block으로 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`만 추가하거나 갱신한다 4. **agent-ops 폴더 구조 복사** - 공통 관리 레포의 `agent-ops/` 공통 폴더(bin, rules/common, skills/common)를 복사한다 @@ -255,7 +255,7 @@ common/rules.md와 내용이 중복되지 않도록 한다. - [ ] 생성된 domain rules.md가 `domain-rule-template.md` 형식을 따르는가 - [ ] `rules/project/rules.md`의 도메인 매핑 테이블에 생성된 도메인이 모두 등록되어 있는가 - [ ] `.gitignore`에 `agent-ops/rules/private/` 항목이 추가되어 있는가 -- [ ] `.gitignore`에 Agent-Ops 관리 block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`가 포함되어 있는가 +- [ ] `.gitignore`에 Agent-Ops 관리 block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가 - [ ] `agent-test/local/rules.md`가 생성되었는가 - [ ] 생성되었거나 기존에 있던 모든 domain rule에 대응하는 `agent-test/local/-smoke.md`가 있는가 - [ ] domain rule이 아직 없으면 `agent-test/local/project-smoke.md` fallback이 있는가 diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index b904196..dff5086 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -144,7 +144,8 @@ If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G 로드맵 확인: -- `agent-roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다. +- `agent-roadmap/current.md`는 브랜치별 로컬 포인터다. 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다. +- `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 수준 구현 단계를 확정하지 않는다. @@ -160,7 +161,7 @@ If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G - 같은 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-`일 때만 쓴다. - Milestone 작업이 아니거나, Milestone 안의 조사/하위 구현처럼 특정 기능 Task 완료를 주장하지 않는 계획이면 `Roadmap Targets` 섹션을 쓰지 않는다. 섹션이 없으면 PASS 후에도 roadmap Task 체크를 하지 않는다. -- roadmap/current 파일이 없으면 기존 task routing 규칙대로 진행한다. +- `agent-roadmap/` 디렉터리가 없으면 기존 task routing 규칙대로 진행한다. Use short snake_case task group names for non-roadmap work, e.g. `api_refactor`. @@ -168,7 +169,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 `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, 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. @@ -206,7 +207,7 @@ GXX is an output of analysis, not an input. Determine lane and grade only after Before writing new active files for the chosen active task directory: -- Ensure `.gitignore` has the Agent-Ops managed gitignore block for task artifacts before renaming any active file to `*.log`. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, and `!agent-task/**/*.log`. +- Ensure `.gitignore` has the Agent-Ops managed gitignore block before renaming any active file to `*.log` or creating local `agent-roadmap/current.md`. Prefer `source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore`; if the helper is unavailable, add or update a block containing `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, and `agent-roadmap/current.md`. - Count existing `agent-task/{task_name}/plan_*.log`; call it `N`. If `PLAN-*-G??.md` exists in that same directory, rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_N.log`. - Count existing `agent-task/{task_name}/code_review_*.log`; call it `M`. If `CODE_REVIEW-*-G??.md` exists in that same directory, rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_M.log`. - Count existing `agent-task/{task_name}/user_review_*.log`; call it `U`. If `USER_REVIEW.md` exists in that same directory and the user explicitly decided to resume planning, rename `USER_REVIEW.md` to `user_review_U.log`. @@ -354,7 +355,7 @@ task={task_name}, plan={N}, tag={TAG} - [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. - [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. - [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. -- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. - [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. - [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. - [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. @@ -444,7 +445,7 @@ Sections and their ownership: ## Final Checklist - `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under the active task directory `agent-task/{task_name}/`. -- `.gitignore` has the Agent-Ops managed gitignore block that unignores `agent-task/**/*.md` and `agent-task/**/*.log`, so active files and archived `*.log` task artifacts are trackable even when the project ignores `*.log`. +- `.gitignore` has the Agent-Ops managed gitignore block that unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`, so active files and archived `*.log` task artifacts are trackable even when the project ignores `*.log`. - Single-plan work stores active files directly under `agent-task/{task_group}/`. - Split work, if any, uses one shared `agent-task/{task_group}/` parent and one subtask directory per plan/review pair with names like `01_core`, `02+01_edge_integration`, `03+01_node_integration`; dependency details live in the subtask directory name as `NN+PP[,QQ...]_subtask_name`. - Milestone-linked work uses `agent-task/m-/` as the task group; non-roadmap task groups do not start with `m-`. diff --git a/agent-ops/skills/common/sync-pull/SKILL.md b/agent-ops/skills/common/sync-pull/SKILL.md index d3fbfb9..920a731 100644 --- a/agent-ops/skills/common/sync-pull/SKILL.md +++ b/agent-ops/skills/common/sync-pull/SKILL.md @@ -31,7 +31,8 @@ agent-ops/bin/sync.sh --pull - [ ] sync.sh 가 오류 없이 완료됐는가 - [ ] 현재 프로젝트 버전이 framework 버전과 일치하는가 - [ ] `agent-ops/bin/entry-files.sh`의 모든 진입 파일이 갱신됐고, 내용이 framework의 `agent-ops/rules/common/rules.md`와 일치하는가 -- [ ] `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`가 포함되어 있는가 +- [ ] `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가 +- [ ] `agent-roadmap/current.md`가 있으면 파일은 보존되고 git 추적 대상에서는 제거됐는가 - [ ] `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가 - [ ] `.claude/settings.json`, `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가 - [ ] 현재 프로젝트에 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가 diff --git a/agent-ops/skills/common/sync-push/SKILL.md b/agent-ops/skills/common/sync-push/SKILL.md index 5b59d19..3acebf7 100644 --- a/agent-ops/skills/common/sync-push/SKILL.md +++ b/agent-ops/skills/common/sync-push/SKILL.md @@ -63,7 +63,7 @@ description: 현재 프로젝트의 agent-ops를 공통 원본 repo로 올리거 - 이 절차는 `.agent-ops-source`가 있는 공통 원본 repo에서 대상 프로젝트로 push할 때와 `--pull`로 공통 원본 repo에서 현재 프로젝트로 내려받을 때만 적용한다. - 일반 프로젝트에서 공통 원본 repo로 올리는 push에서는 `.gitignore`와 AI ignore / permission 파일을 수정하거나 stage하지 않는다. -- `.gitignore`는 사용자 영역을 수정하지 않고 아래 관리 block만 추가하거나 교체한다. 이 예외는 `*.log` 같은 전역 ignore가 있어도 plan/review/archive task 산출물이 git에 잡히도록 한다. +- `.gitignore`는 사용자 영역을 수정하지 않고 아래 관리 block만 추가하거나 교체한다. 이 예외는 `*.log` 같은 전역 ignore가 있어도 plan/review/archive task 산출물이 git에 잡히도록 하고, `agent-roadmap/current.md`는 브랜치별 로컬 포인터로 남긴다. ```text # BEGIN Agent-Ops managed gitignore @@ -71,6 +71,7 @@ description: 현재 프로젝트의 agent-ops를 공통 원본 repo로 올리거 !agent-task/**/ !agent-task/**/*.md !agent-task/**/*.log +agent-roadmap/current.md # END Agent-Ops managed gitignore ``` @@ -93,7 +94,7 @@ agent-roadmap/archive/** agent-ops/bin/sync.sh [target] ``` -푸시 대상 path는 항상 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `AGENT_OPS_ENTRY_FILES`의 진입 파일로 제한한다. `.gitignore`와 AI ignore / permission 파일은 `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 경우에만 대상 repo에서 추가 stage한다. +푸시 대상 path는 항상 `agent-ops/.version`, `agent-ops/bin`, `agent-ops/rules/common`, `agent-ops/skills/common`, `AGENT_OPS_ENTRY_FILES`의 진입 파일로 제한한다. 예외적으로 `agent-roadmap/current.md`가 이미 추적 중이고 `.gitignore`에 로컬 current ignore가 있으면 파일을 보존한 채 git 추적에서 제거하는 삭제만 함께 commit할 수 있다. `.gitignore`와 AI ignore / permission 파일은 `.agent-ops-source`가 있는 공통 원본 repo에서 일반 프로젝트로 내려보내는 경우에만 대상 repo에서 추가 stage한다. ## 실행 결과 검증 @@ -101,7 +102,8 @@ agent-ops/bin/sync.sh [target] - [ ] 버전 충돌 경고가 없었는가 — 있었다면 사용자에게 수동 머지 필요함을 알린다 - [ ] 대상 repo의 `agent-ops/rules/common/rules.md`가 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md`와 일치하는가 - [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `agent-ops/bin/entry-files.sh`의 모든 진입 파일 내용이 현재 공통 원본 repo의 `agent-ops/rules/common/rules.md`와 일치하는가 -- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`가 포함되어 있는가 +- [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.gitignore`에 Agent-Ops 관리 gitignore block이 있고 `!agent-task/`, `!agent-task/**/`, `!agent-task/**/*.md`, `!agent-task/**/*.log`, `agent-roadmap/current.md`가 포함되어 있는가 +- [ ] 대상 프로젝트에서 `agent-roadmap/current.md`가 있으면 파일은 보존되고 git 추적 대상에서는 제거됐는가 - [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.geminiignore`, `.aiexclude`, `.cursorignore`, `.clineignore`에 Agent-Ops 관리 block이 있고 그 안에 `agent-task/archive/**`와 `agent-roadmap/archive/**`가 포함되어 있는가 - [ ] 공통 원본 repo에서 대상 프로젝트로 push한 경우, `.claude/settings.json`과 `opencode.json`에 `agent-task/archive/**` hard deny가 있고 `agent-roadmap/archive/**` hard read/glob deny가 남아 있지 않은가 - [ ] 대상 프로젝트에 기존 `agent-roadmap/archive/**` hard deny가 있으면 init-agent-ops 표준에 맞게 제거했는가 diff --git a/agent-ops/skills/common/update-roadmap/SKILL.md b/agent-ops/skills/common/update-roadmap/SKILL.md index dade419..dc2ade1 100644 --- a/agent-ops/skills/common/update-roadmap/SKILL.md +++ b/agent-ops/skills/common/update-roadmap/SKILL.md @@ -1,7 +1,7 @@ --- name: update-roadmap version: 1.21.0 -description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다. +description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 로컬 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 승인된 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다. --- # 로드맵 업데이트 @@ -11,7 +11,7 @@ description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/ 기존 `agent-roadmap/` 구조를 현재 프로젝트 방향과 진행 상태에 맞게 갱신한다. 표준 구조는 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md`다. archive도 같은 Phase scaffold를 유지하며 `archive/phase//...` 아래에 둔다. -로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, `current.md`의 활성 Phase와 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다. +로드맵 전체를 매 작업마다 읽지 않도록 유지하면서, 브랜치별 로컬 `current.md`의 활성 Phase와 활성 Milestone 창이 실제 작업 후보 목록으로 동작하게 한다. Milestone은 구현 계획이 아니라 방향성, 범위, 위험, 확인 필요 사항을 기록하는 협업 문서로 유지한다. Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능` 안에서 관리한다. 별도 `완료 기준` 섹션은 만들지 않고, 검증이 필요한 기능에만 같은 Task 안의 `검증:` 문구로 통합한다. @@ -55,7 +55,7 @@ Epic과 Task는 별도 파일로 분리하지 않고 Milestone 문서의 `기능 ```text agent-roadmap/ ROADMAP.md - current.md + current.md # local, git ignored phase/ / PHASE.md @@ -76,7 +76,8 @@ agent-roadmap/ - 진행중 Phase 안에서 완료된 Milestone은 `archive/phase//milestones/.md`로 이동하고, 활성 `PHASE.md`에는 짧은 archive 링크를 남긴다. - archive `PHASE.md`는 Phase 자체가 완료/폐기될 때만 만든다. 진행중 Phase의 완료 Milestone만 archive된 경우에는 archive Phase 디렉터리에 `milestones/`만 있을 수 있다. - ``와 ``는 소문자 영문, 숫자, 하이픈만 사용한다. -- `current.md`는 활성 Phase와 활성 Milestone을 모두 가리킨다. +- `current.md`는 브랜치별 로컬 포인터이며 활성 Phase와 활성 Milestone을 모두 가리킨다. +- `current.md`는 git 추적 대상이 아니며, 공유 진행 상태는 `ROADMAP.md`, `PHASE.md`, Milestone 문서, `.agent-roadmap-sync/locks.yaml`에 기록한다. - `current.md`에는 archive 경로를 넣지 않는다. - `current.md`에는 `[완료]` 또는 `[폐기]` Phase/Milestone을 남기지 않는다. 완료 후보는 사용자 승인 전까지 `[검토중]`으로 둔다. @@ -100,7 +101,8 @@ agent-roadmap/ ## 로딩 원칙 -- 일반 갱신은 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다. +- 일반 갱신은 로컬 `current.md`, 관련 활성 Phase, 관련 활성 Milestone을 우선 읽는다. +- `current.md`가 없고 활성 창 갱신이 필요하면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 로컬 파일을 만든다. - `ROADMAP.md`는 Phase 흐름, 전체 구조, 활성 범위 밖 작업, 전체 재계획, archive 링크 갱신이 필요할 때 읽는다. - `agent-roadmap/archive/**`는 일반 작업이나 sync에서 읽지 않는다. - archive 모드에서 이동 대상이 아직 활성 경로에 있으면 그 대상 문서는 읽을 수 있다. @@ -136,7 +138,7 @@ agent-roadmap/ 2. 사용자가 명시한 프로젝트와 Milestone slug 3. 사용자가 명시한 프로젝트와 Milestone 제목의 정규화 일치 4. 잠긴 Milestone 문서의 `선행 Milestone: ...`, `관련 Milestone: ...`, `외부 의존 잠금: ...`에 적힌 slug/제목 힌트 - 5. 프로젝트명만 있고 Milestone 힌트가 없을 때만 해당 프로젝트 `current.md`의 활성 Milestone 단일 후보 + 5. 프로젝트명만 있고 Milestone 힌트가 없을 때만 해당 프로젝트 로컬 `current.md`의 활성 Milestone 단일 후보 - 정규화 비교는 소문자 변환, backtick/따옴표 제거, 영문/숫자가 아닌 연속 문자를 `-` 하나로 치환, 앞뒤 `-` 제거 후 비교한다. 정규화한 힌트는 Milestone 파일 slug와 정규화한 제목 둘 다에 대조한다. - 2-4번 탐색은 대상 프로젝트의 `agent-roadmap/phase/*/milestones/*.md` 활성 문서만 대상으로 한다. archive 문서는 사용자가 archive 경로를 명시한 경우 외에는 읽거나 후보로 삼지 않는다. - 후보가 없거나 둘 이상이면 `locks.yaml`을 만들거나 고치지 말고 사용자에게 대상 Milestone 선택을 요청한다. @@ -194,7 +196,7 @@ agent-roadmap/ - ` 앞/뒤`는 같은 Epic 안의 형제 Task로 넣는다. - ` 아래`는 해당 Task의 설명 또는 `검증:`을 보강한다. 구현 세부나 테스트만 따로 떼어낸 하위 체크박스는 Milestone `기능` 아래에 만들지 않는다. - ` 안`은 새 Milestone 또는 기존 Milestone/Epic/Task 중 작업 성격에 맞는 단위로 배치한다. -- 위치 지정이 없으면 `auto`로 본다. `current.md`의 활성 창만으로 결정하지 않고, 필요한 경우 `ROADMAP.md`의 Phase 흐름까지 확인해 완료/검토중/진행중/계획/스케치 Phase를 비교한다. +- 위치 지정이 없으면 `auto`로 본다. 로컬 `current.md`의 활성 창만으로 결정하지 않고, 필요한 경우 `ROADMAP.md`의 Phase 흐름까지 확인해 완료/검토중/진행중/계획/스케치 Phase를 비교한다. - target 없는 신규 추가 요청은 요청 문장, 관련 파일/도메인 힌트, Phase 목표, Milestone 목표, 기존 Epic/Task, 선후 의존성, 상태, 활성 창을 비교해 가장 자연스러운 위치를 자동 판단한다. - 자동 배치 후보가 여러 개이면 1순위와 2순위 후보를 비교하고, 선택한 Phase/Milestone/Epic/Task와 밀린 후보의 이유를 짧게 남긴다. - 관련성이 비슷하면 `[진행중]` Milestone을 `[계획]` Milestone보다 우선하되, `[검토중]` Milestone은 리뷰 보완 요청이 아닌 신규 작업의 기본 배치 대상으로 삼지 않는다. @@ -219,7 +221,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 조사, 결정, 보류 질문이면 작업 컨텍스트/TODO 규모다. 3. **레벨별 탐색** - - Phase 후보를 먼저 찾는다. `current.md`의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 `ROADMAP.md`의 Phase 흐름도 본다. + - Phase 후보를 먼저 찾는다. 로컬 `current.md`의 활성 Phase를 우선 보되, target이 없거나 활성 범위 밖 가능성이 있으면 `ROADMAP.md`의 Phase 흐름도 본다. - 선택한 Phase 안에서 Milestone 후보를 찾는다. 활성 Milestone을 우선 보되, 요청이 계획 Milestone 목표와 더 직접 맞으면 계획 Milestone도 후보로 둔다. - 선택한 Milestone 안에서 Epic 후보를 찾는다. `기능`의 Epic heading, 목표 설명, Task 묶음을 비교한다. 기존 문서가 `필수 기능`을 쓰면 갱신 시 `기능`으로 정규화한다. - 선택한 Epic 안에서 Task 후보를 찾는다. item-id, 문장 의미, Task 안의 검증 문구, 관련 경로를 비교한다. @@ -246,7 +248,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - find 결과가 `none`이면 `Workspace 잠금: 관련 lock 없음`으로 보고한다. - 대상 파일을 `agent-roadmap/phase//milestones/.md`에서 `agent-roadmap/archive/phase//milestones/.md`로 이동한다. - 활성 `PHASE.md`의 Milestone 흐름에는 `[완료]` 또는 `[폐기]` 항목을 남기고, 경로는 archive 경로로 바꾼다. -- `current.md`의 활성 Milestone에서는 제거한다. +- 로컬 `current.md`의 활성 Milestone에서는 제거한다. - `ROADMAP.md`는 Phase 상태나 경로가 바뀌지 않으면 수정하지 않는다. - 이동한 archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다. @@ -257,7 +259,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - `agent-roadmap/phase//PHASE.md`를 `agent-roadmap/archive/phase//PHASE.md`로 이동한다. - 해당 Phase의 하위 Milestone도 `archive/phase//milestones/` 아래로 이동한다. - `ROADMAP.md`의 Phase 흐름에는 해당 Phase 항목을 남기고, 상태와 경로를 archive `PHASE.md`로 바꾼다. -- `current.md`의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다. +- 로컬 `current.md`의 활성 Phase와 활성 Milestone에서는 해당 Phase와 하위 Milestone을 제거한다. - archive 문서는 스냅샷으로 보존하고 최신 템플릿에 맞춰 재포맷하지 않는다. ## 실행 절차 @@ -272,8 +274,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - "로드맵에 추가"처럼 target이 없는 신규 작업 요청은 `placement=auto`, `placement-unit=auto`, `new-feature=<요청 내용>`으로 본다. - 외부 의존 잠금 요청이면 `workspace-lock` 갱신으로 본다. - 외부 의존 잠금 요청이 아니어도, 갱신 대상 Milestone이 `구현 잠금: 잠금`이고 외부 의존 잠금/선행 Milestone 컨텍스트가 있으면 `workspace-lock` 동기화 후보로 본다. - - 외부 의존 잠금 요청에서 "현재 마일스톤" 또는 target 생략 표현이 있으면 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 확정한다. - - 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 `current.md` 단일 후보 순서로 확정한다. + - 외부 의존 잠금 요청에서 "현재 마일스톤" 또는 target 생략 표현이 있으면 로컬 `current.md`의 활성 Milestone 단일 후보를 잠긴 대상으로 확정한다. + - 의존 대상은 명시 경로, 명시 slug, 명시 제목, 잠긴 Milestone 문서의 선행 Milestone 힌트, 대상 프로젝트 로컬 `current.md` 단일 후보 순서로 확정한다. - 잠긴 대상 또는 의존 대상 후보가 없거나 둘 이상이면 `locks.yaml`을 수정하지 말고 사용자에게 Milestone 선택을 요청한다. 2. **요청 정규화와 규모 판정** @@ -282,12 +284,12 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 동일/유사 항목이 이미 있으면 신규 추가가 아니라 업데이트 후보로 기록한다. 3. **레벨별 후보 탐색** - - `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다. + - 로컬 `current.md`의 활성 Phase와 활성 Milestone 후보를 확인한다. - target이 명시된 경우 대상 Phase의 `PHASE.md`를 읽고 Milestone 흐름과 Phase 경계를 확인한다. - target이 없거나 활성 창 밖 배치 가능성이 있으면 `ROADMAP.md`의 Phase 흐름을 확인하고, 관련성이 높은 Phase 문서를 읽는다. - 대상 또는 후보 Milestone 문서의 목표, 상태, 승격 조건, 범위, 기능 Task, 완료 리뷰, 범위 제외, 구현 잠금을 확인한다. 기존 문서에 `필수 기능`/`완료 기준`이 분리되어 있으면 갱신 범위에서 `기능` Task로 흡수할 후보를 기록한다. - Phase -> Milestone -> Epic -> Task 순서로 내려가며 같은 레벨의 동일/유사 후보를 먼저 찾는다. - - `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다. + - 로컬 `current.md`에 archive 경로가 있으면 읽지 말고 제거 대상으로 기록한다. - 필요한 경우에만 `ROADMAP.md`를 읽어 전체 Phase 흐름을 확인한다. 4. **스케치 승격 판단** @@ -300,7 +302,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 5. **변경 내용 작성** - `ROADMAP.md`는 전체 목표, Phase 흐름, 로딩 정책이 바뀔 때만 수정한다. - - `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다. + - 로컬 `current.md`는 활성 Phase/Milestone 창이 바뀔 때 수정한다. + - `.gitignore`의 Agent-Ops 관리 block에 `agent-roadmap/current.md`가 있는지 확인하고 없으면 추가한다. - `PHASE.md`는 Phase 목표, 상태, Milestone 흐름, Phase 경계가 바뀔 때 수정한다. - Milestone 문서는 목표, 상태, 승격 조건, 구현 잠금, 범위, Epic/Task, Task 안의 검증 문구, 완료 리뷰, 범위 제외, 작업 컨텍스트가 바뀔 때 수정한다. - 동일/유사 후보가 있으면 기존 항목을 업데이트하고 중복 항목을 만들지 않는다. @@ -311,7 +314,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 새 항목은 레벨별 탐색에서 적절한 기존 후보가 없을 때만 만든다. - 완료 체크는 evidence가 있을 때만 `[x]`로 바꾼다. - 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이면 Milestone 상태를 `[검토중]`으로 바꾸고 `완료 리뷰`에 리뷰 요청과 근거를 남긴다. - - `[검토중]` 전환만으로 archive 이동, `current.md` 제거, archive 링크 변경을 수행하지 않는다. + - `[검토중]` 전환만으로 archive 이동, 로컬 `current.md` 제거, archive 링크 변경을 수행하지 않는다. - 사용자 승인 근거가 있으면 `[검토중]`을 `[완료]`로 전환하고 archive 모드를 수행할 수 있다. - `locks.yaml`이 있으면 갱신 대상 Milestone identity로 `--find-milestone "" both ""`를 실행해 이 Milestone이 `locked`인지, `rely-on.target`인지, 관련 lock이 없는지 확인한다. - archive 모드이면 파일 이동 전 active Milestone identity를 보존하고, 그 identity로 `--find-milestone "" both ""`를 먼저 실행한다. @@ -326,9 +329,10 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - archive 모드에서 보존한 active Milestone identity와 일치하는 `locked` entry도 archive 이동 전에 모든 `rely-on.status`가 `enable`인지 확인하고 결과 보고에 남긴다. 6. **검증** - - `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다. - - `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다. - - `current.md`의 활성 항목이 `[완료]` 또는 `[폐기]` 상태로 남아 있지 않은지 확인한다. + - 로컬 `current.md`의 활성 Phase/Milestone 경로가 실제 파일을 가리키는지 확인한다. + - 로컬 `current.md`의 활성 항목이 archive 경로를 가리키지 않는지 확인한다. + - 로컬 `current.md`의 활성 항목이 `[완료]` 또는 `[폐기]` 상태로 남아 있지 않은지 확인한다. + - `agent-roadmap/current.md`가 git 추적 대상으로 남아 있지 않은지 확인한다. - `ROADMAP.md`의 Phase 경로가 실제 `PHASE.md` 파일을 가리키는지 확인한다. - 각 `PHASE.md`의 Milestone 경로가 실제 파일을 가리키는지 확인한다. - 상태 표기가 표준값인지 확인한다. @@ -356,7 +360,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 변경된 Phase / Milestone / 상태 - 신규 작업의 삽입 단위와 배치 위치 - 자동 배치한 경우 비교한 후보와 선택 근거 - - current.md 활성 창 변경 사항 + - 로컬 current.md 활성 창 변경 사항 - 완료 리뷰 상태와 사용자 확인 필요 항목 - 런타임 완료 이벤트의 `origin-task`가 `m-`이면 원래 active task 경로와 매칭된 target Milestone, `Roadmap Completion` Task ids 또는 no-op 사유 - archive 모드이면 이동 경로와 남긴 링크 @@ -370,7 +374,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 모드: - 수정 파일: - agent-roadmap/ROADMAP.md - - agent-roadmap/current.md + - agent-roadmap/current.md (local) - agent-roadmap/phase//PHASE.md - agent-roadmap/phase//milestones/.md - agent-roadmap/archive/phase//... (archive 모드) @@ -385,7 +389,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - 신규/업데이트 판정: <신규 생성 | 기존 항목 업데이트 | 변경 없음> - <동일/유사 후보 근거> - 배치: <사용자 지정 위치 반영 | 자동 배치 위치와 근거 | 변경 없음> - 배치 후보: <자동 배치 시 1순위/2순위 후보와 선택/제외 근거 | 해당 없음> -- 템플릿 보정: +- 템플릿 보정: - 구현 잠금: <잠금 유지 | 잠금 추가 | 해제 | 변경 없음>; 결정 필요: <없음 | 항목 요약> - 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약> - 완료 리뷰: <변경 없음 | 요청됨 | 승인됨 | 보완 필요 | 보류 | 폐기> @@ -407,8 +411,9 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다 - evidence 없이 Phase, Milestone, Epic, Task를 `[완료]` 또는 `[검토중]`으로 처리하지 않는다. - 전체 `ROADMAP.md`를 모든 작업의 필수 로딩 파일로 만들지 않는다. - `ROADMAP.md`에 Milestone 상세 작업 체크리스트를 남기지 않는다. -- `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다. -- `current.md`에 `agent-roadmap/archive/**` 경로를 남기지 않는다. +- 로컬 `current.md`에 개인별 현재 작업 위치나 완료 상태를 남기지 않는다. +- 로컬 `current.md`에 `agent-roadmap/archive/**` 경로를 남기지 않는다. +- `agent-roadmap/current.md`를 git 추적 대상으로 만들지 않는다. - archive 문서를 명시 요청 없이 읽거나 최신 템플릿으로 재포맷하지 않는다. - 완료된 Phase/Milestone 기록을 삭제하지 않는다. - Epic과 Task를 별도 파일로 분리하지 않는다. diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index 4952bd9..42f4b15 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -21,6 +21,7 @@ Agent Context Framework는 여러 프로젝트가 공통 agent-ops 규칙과 스 - 일반 작업에서는 `agent-roadmap/ROADMAP.md`를 매번 읽지 않는다. - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-roadmap/current.md`를 먼저 읽는다. - `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다. +- `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다. 로드맵 기반 계획/갱신에서 없으면 `agent-ops/skills/common/_templates/roadmap-current-template.md` 형식으로 생성해 사용하고, 읽기 전용 현지점 확인에서는 생성하지 않는다. - `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - `current.md`의 활성 Phase는 `agent-roadmap/phase//PHASE.md`를 가리킨다. - `current.md`의 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. diff --git a/agent-roadmap/current.md b/agent-roadmap/current.md deleted file mode 100644 index f565ba0..0000000 --- a/agent-roadmap/current.md +++ /dev/null @@ -1,28 +0,0 @@ -# 현재 로드맵 컨텍스트 - -## 활성 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.md`를 가리킨다. -- 활성 Milestone은 `agent-roadmap/phase//milestones/.md`를 가리킨다. -- 활성 항목은 아카이브 경로를 포함하지 않는다. -- `[검토중]` 항목은 사용자 완료 확인 전까지 활성 항목으로 남길 수 있다. -- `[스케치]` 항목은 활성 후보로 남길 수 있지만 구현 계획 생성 대상은 아니며, `[계획]` 승격 조건을 정리하는 대상으로만 다룬다. -- `[완료]` 또는 `[폐기]` 항목은 archive 링크를 남긴 뒤 활성 항목에서 제거한다. -- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Phase와 Milestone을 선택하고 같은 세션에서 1회 읽는다. -- 활성 Phase 또는 Milestone 둘 이상에 걸치면 필요한 문서를 모두 읽고 작업 범위를 좁힌다. -- 활성 범위 밖의 작업이면 `agent-roadmap/ROADMAP.md`의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. -- 완료된 과거 내용이 필요할 때만 `ROADMAP.md` 또는 `PHASE.md`에 있는 archive 링크를 따라가서 읽는다. -- 선택된 Milestone의 `구현 잠금` 섹션이 없거나 상태가 `잠금`이면 구현이나 구현 계획을 시작하기 전에 현재 요청에 직접 영향을 주는 `결정 필요` 항목만 확인한다. 관련 결정이 없고 표준선으로 처리 가능하면 잠금을 유지한 채 진행할 수 있으며, Milestone 전체에서 사용자만 결정할 항목이 더 이상 없을 때만 `구현 잠금` 상태를 `해제`로 둔다. -- 선택된 Milestone 상태가 `[스케치]`이면 `구현 잠금` 상태와 관계없이 구현이나 구현 계획을 시작하지 않고 `[계획]` 승격 필요를 보고한다.