nomadcode/agent-ops/skills/common/prepare-milestone-workspace/SKILL.md

name	description
prepare-milestone-workspace	계획 상태의 Milestone을 명시 workspace의 Git Flow feature worktree로 준비하거나, 사용자가 지정한 현재 workspace에서 대상 feature branch를 생성·재사용해 선택한 한 개·범위·남은 모든 Epic을 검토된 작업으로 변환하고 전체 준비 배리어 뒤 dispatcher를 시작할 때 사용한다. "../sample-feature-worktree 위치에 X 작업 준비해", "현재 워크스페이스에서 현 마일스톤 시작해", "현 마일스톤에 두 번째 에픽 작업 시작해", "X 마일스톤에 1,2번째 에픽까지 작업 시작해", "현 마일스톤에 남은 에픽 작업들 시작해" 요청에서 사용한다.

Prepare Milestone Workspace

<workspace>에 <milestone> 작업 준비해는 workspace 생성 모드로, 현|<이름> 마일스톤에 <범위> Epic 작업 시작해는 현재 workspace 실행 모드로 해석한다. 두 모드 모두 정합성 확인부터 선택 Epic 준비와 dispatcher 전환까지 수행한다.

목적

계획 가능한 Milestone 하나를 검증된 feature/<milestone-slug> workspace로 전환한다. 현재 workspace 실행 모드에서 사용자가 지정한 workspace가 Git Flow develop branch이면 그 자리에서 대상 feature branch를 생성·전환하고, 이미 대상 feature branch이면 재사용한다. 선택 Epic 전체가 준비된 뒤에만 구현 dispatcher를 시작한다. 의미 정합성은 roadmap 스킬이, branch/worktree/current와 batch lifecycle은 번들 스크립트가 소유한다.

입력

• target-milestone: 활성 Milestone 이름, id, slug 또는 경로 (필수)
• workspace: 생성 모드에서는 feature worktree 절대 경로 또는 develop repository root 기준 상대 경로가 필수다. 현재 workspace 실행 모드에서는 현재 repository root를 사용한다.
• execution-catalog: 런타임이 주입한 agent-model 실행 카탈로그 경로. AGENT_TASK_EXECUTION_CATALOG로 대신 주입할 수 있다. (필수)
• planner-target: 카탈로그에 선언된 Epic materialize/refine 실행 target id. AGENT_TASK_PLANNER_TARGET로 대신 주입할 수 있다. (필수)
• review-target: 카탈로그에 선언된 review 실행 target id. AGENT_TASK_REVIEW_TARGET로 주입하거나 생략하면 planner-target과 같다. (선택)
• target-epics: remaining, first-incomplete, 정확한 Epic id/title의 comma list, 또는 문서 순서의 1-based inclusive range N..M. 생략하면 first-incomplete를 사용한다. (선택)
• retry: 기록된 attention/recovery 조건을 사용자가 해소한 뒤 batch를 재개할 때만 사용한다. (선택)

생성 모드의 첫 번째 위치 표현(<workspace>)은 workspace로, 두 번째 표현(<milestone>)은 대상 Milestone으로 각각 확정한다. 상대 workspace는 develop repository root 기준으로 해석한다. 현재 workspace 실행 모드의 현 마일스톤은 그 workspace의 current.md가 가리키는 단일 Milestone으로 확정하고, 이름을 지정하면 같은 current.md와 정확히 일치해야 한다. branch 이름으로 target을 선택하지 않는다. 두 번째 Epic은 2..2, 두 번째 Epic까지와 1,2번째 Epic까지는 1..2, 세 번째부터 네 번째 Epic까지는 3..4, 남은 Epic은 문서 순서의 미완료 Epic 전체를 선택하는 remaining으로 변환한다.

사전 조건

• 생성 모드는 clean Git Flow develop checkout과 정확히 [계획]인 Milestone을 요구한다.
• 현재 workspace 실행 모드는 일치하는 local current.md와 clean/upstream-synced workspace를 요구하고 Milestone [계획] 또는 [진행중]을 허용한다. 현재 branch가 target slug와 일치하는 feature/<milestone-slug>이면 재사용하고, Git Flow develop branch이면 같은 workspace에서 target feature branch를 생성·전환한다. 기록된 active batch 재개만 상태 소유 변경을 허용한다.
• 두 모드 모두 구현 잠금: 해제, 결정 필요: 없음이어야 한다.
• sync-milestone-workstate mode=consistency-check가 ready여야 한다.
• remote와 gitflow.branch.develop, gitflow.prefix.feature를 확인할 수 있어야 한다.
• 선택 target의 카탈로그 검증과 비대화식 one-shot capability probe가 branch 생성 전에 성공해야 한다.

절차

1. 대상과 정합성을 고정한다

   • agent-roadmap/current.md를 선택 근거로만 사용하고 target이 명시됐으면 target을 우선한다.
   • sync-milestone-workstate mode=consistency-check를 먼저 실행한다.
   • 기계적으로 고칠 수 있는 drift는 보고된 owner 스킬로 갱신하고 commit/push한 뒤 consistency check를 다시 실행한다.
   • 사용자만 결정할 수 있는 drift는 roadmap-sdd mode=review-ready의 agent-roadmap/sdd/<phase-slug>/<milestone-slug>/USER_REVIEW.md로 남기고 commit/push한 뒤 USER_REVIEW로 멈춘다. pre-plan 문제에 agent-task/**/USER_REVIEW.md를 만들지 않는다.

2. 실행 모드를 선택한다

   • workspace 위치를 명시한 준비 요청은 생성 모드로 실행한다.

python3 agent-ops/skills/common/prepare-milestone-workspace/scripts/prepare_workspace.py \
  --repo "$REPO" \
  --milestone "$MILESTONE" \
  --workspace "$WORKSPACE" \
  --epics "$EPICS" \
  --execution-catalog "$EXECUTION_CATALOG" \
  --planner-target "$PLANNER_TARGET" \
  --review-target "$REVIEW_TARGET"

• agent, model, 실행 명령과 provider별 옵션은 스킬이나 스크립트에 고정하지 않고 주입된 카탈로그 target에서 가져온다.
• 스크립트는 develop HEAD와 remote develop의 일치, target probe, branch 충돌, worktree 소유권을 mutation 전에 검사한다.
• branch는 Milestone id가 아니라 파일 basename을 사용한 feature/<milestone-slug>다.
• 기존 branch/worktree는 정확히 같은 branch·경로이고 clean할 때만 재개한다.
• remote branch 생성 뒤 후속 단계가 실패해도 branch/worktree를 자동 삭제하지 않는다.
• Epic 작업 시작해 요청은 현재 workspace 실행 모드로 foreground 실행한다.

python3 agent-ops/skills/common/prepare-milestone-workspace/scripts/prepare_workspace.py \
  --existing-workspace \
  --workspace "$CURRENT_WORKSPACE" \
  --milestone "$MILESTONE" \
  --epics "$EPICS" \
  --execution-catalog "$EXECUTION_CATALOG" \
  --planner-target "$PLANNER_TARGET" \
  --review-target "$REVIEW_TARGET"

• 현재 workspace가 Git Flow develop branch이면 별도 worktree를 만들지 않고 그 workspace에서 target feature branch를 생성·전환한다.
• 현재 workspace가 target feature branch도 develop branch도 아니거나 current.md target이 다르면 다른 worktree를 탐색하지 않고 FAILED로 멈춘다.
• remaining에 미완료 Epic이 없으면 agent/dispatcher를 시작하지 않고 완료 event로 종료한다.
• 두 모드 모두 실행 중 caller LLM이 timer polling, ps, state 파일 검사 또는 중복 실행을 하지 않는다.

3. 선택 Epic batch를 준비한다

   • WORKSPACE_READY 뒤 스크립트가 선택 Epic을 문서 순서대로 하나씩 prepare-epic-work-items에 전달한다.
   • 각 Epic은 별도 fresh one-shot context를 사용한다. 앞선 Epic의 EPIC_WORK_ITEMS_READY plan은 같은 batch의 다음 Epic 준비 동안 유지한다.
   • 두 개 이상이면 마지막 Epic 준비 뒤 fresh cross-Epic review를 한 번 수행해 scope union, dependency, write set, metadata, routing과 검증을 교정하고 push한다.
   • USER_REVIEW, AGENT_RECOVERY_REQUIRED, AGENT_TRACKING, FAILED가 발생하면 batch를 멈추고 dispatcher를 시작하지 않는다.

4. 전체 준비 배리어 뒤 dispatcher로 전환한다

   • 모든 선택 Epic이 EPIC_WORK_ITEMS_READY 또는 EPIC_COMPLETED이고 deterministic batch validation과 모든 push가 끝난 경우에만 MILESTONE_WORK_ITEMS_READY를 낸다.
   • active plan이 있으면 공통 orchestrate-agent-task-loop dispatcher에 런타임 카탈로그를 주입하고 같은 task group m-<milestone-slug>에 --dry-run을 먼저 실행한 뒤 live를 정확히 한 번 시작한다.
   • 모든 선택 Epic이 EPIC_COMPLETED이면 dispatcher를 생략한다.
   • foreground dispatcher가 종료될 때까지 caller는 timer polling이나 상태 파일 검사를 하지 않는다. batch/dispatcher PID와 start token은 git common dir 상태에 기록해 재진입 중복 실행을 막는다.

lifecycle event

• PREFLIGHT_READY: mutation 전 검증 완료
• FEATURE_BRANCH_PUSHED: remote feature branch 준비 완료
• WORKSPACE_READY: worktree와 local current 준비 완료
• MILESTONE_WORK_ITEMS_READY: 선택 Epic 전체 준비와 cross-Epic 검증·push 완료
• DISPATCHER_DRY_RUN_FINISHED, DISPATCHER_STARTED, DISPATCHER_TRACKING, DISPATCHER_BLOCKED
• MILESTONE_PREPARATION_COMPLETED: 선택 Epic 구현과 workstate sync까지 완료, 또는 all-direct라 dispatcher 생략
• USER_REVIEW: 사전 정합화 또는 연결된 Epic 준비에서 사용자 결정이 필요해 정상 정지
• FAILED: 안전하게 계속할 수 없음

실행 결과 검증

• 생성 모드와 현재 workspace 실행 모드 모두 최종 branch가 gitflow.prefix.feature + milestone file slug인가
• branch가 remote에 존재하고 upstream이 연결됐는가
• 요청 workspace가 정확히 해당 branch의 clean worktree인가
• workspace-local agent-roadmap/current.md가 대상 Milestone만 가리키는가
• 선택 Epic의 Task id 합집합 밖 active pair가 없는가
• 복수 Epic이면 cross-Epic review와 push가 완료됐는가
• dispatcher dry-run이 live보다 먼저이고 MILESTONE_WORK_ITEMS_READY 전에는 live가 시작되지 않았는가
• state와 locator가 repository 문서가 아니라 git common dir 아래에 있는가
• 검증 실패 시: branch/worktree를 삭제하지 않고 FAILED event와 복구 조건을 보고한다.

출력 형식

Milestone workspace preparation
- milestone: <path>
- branch: <feature/milestone-slug>
- workspace: <absolute path>
- epics: <selected Epic ids in document order>
- event: <MILESTONE_PREPARATION_COMPLETED | USER_REVIEW | AGENT_RECOVERY_REQUIRED | DISPATCHER_BLOCKED | FAILED>
- next: <completed | user action | recovery condition>

금지 사항

• [계획]이 아니거나 잠긴 Milestone의 branch를 만들지 않는다.
• consistency check의 refresh-required를 ready로 간주하지 않는다.
• 사용자 소유 변경이 있는 develop checkout이나 기존 workspace를 덮어쓰지 않는다.
• 현재 workspace 실행 모드에서 Git Flow develop branch는 target feature branch로 전환한다. 그 외 target이 다른 feature/topic branch나 다른 current.md를 자동 전환하지 않는다.
• 선택 Epic 중 하나라도 attention/terminal failure 상태면 dispatcher를 시작하지 않는다.
• 복수 Epic batch에서 개별 EPIC_WORK_ITEMS_READY만 보고 dispatcher를 먼저 시작하지 않는다.
• git push --force, destructive rollback, branch/worktree 자동 삭제를 하지 않는다.
• caller LLM이 주기적으로 process나 상태 파일을 모니터링하지 않는다.