Workflow CLI Specification 목적 Workflow CLI는 Agent와 사람이 Repository의 개발 Workflow를 안전하게 실행하기 위한 단일 인터페이스입니다. Agent는 다음 정보만 사용합니다. • Command • Description • Argument • Example • Result • 다음에 가능한 행동 Agent는 다음 구현에 접근하지 않습니다. • git • gh • GitHub API • branch 생성과 삭제 • commit과 push • rebase와 restack • force push 정책 • Git worktree 관리 방식 • Merge Queue 구현 • 외부 Task API • CI provider • 배포 provider CLI가 Git과 외부 시스템을 조작하는 신뢰 가능한 기계적 경계가 됩니다. 기본 형식은 다음과 같습니다. bash ./tools/workflow [subcommand] [arguments] Command Command 책임 start SubTask와 전용 Worktree 시작 check 현재 Worktree의 변경 검증 review 코드 게시와 PR Review lifecycle 관리 stack SubTask 코드 의존성 관리 sync Worktree, branch, Stack과 원격 상태 동기화 status Workflow 상태와 다음 행동 조회 gate 사람만 수행할 수 있는 의사결정 Worktree 계약 모든 활성 SubTask는 독립적인 Git worktree를 가집니다. text Repository │ ├─ main checkout │ └─ managed worktrees ├─ sk-101 → feature/sk-101 ├─ sk-102 → feature/sk-102 └─ sk-103 → feature/sk-103 하나의 SubTask는 정확히 하나의 관리되는 Worktree와 연결됩니다. text SubTask = 1 Worktree = 1 Branch = 1 PR Agent는 Repository의 기본 checkout이나 다른 SubTask의 Worktree에서 현재 SubTask의 파일을 수정하지 않습니다. start가 Worktree를 보장합니다 workflow start는 다음 작업을 하나의 동작으로 수행합니다. • SubTask 발급 • branch 준비 • 전용 worktree 생성 • SubTask와 worktree 연결 • 선행 SubTask 관계 반영 • Agent가 작업할 경로 반환 Agent가 직접 git worktree add나 git checkout을 수행하지 않습니다. 결과에는 항상 작업 경로가 포함됩니다. json { "type": "success", "data": { "task": "TASK-42", "subtask": "sk-102", "branch": "feature/sk-102", "workspace": { "path": "/repo-managed/sk-102" }, "state": "DEVELOPMENT", "next": [ "check" ] } } Agent는 이후 파일 읽기와 수정을 workspace.path 안에서 수행합니다. Worktree의 실제 저장 위치 규칙은 CLI 내부 구현이며 Agent 계약에 포함하지 않습니다. Worktree 격리 Workflow는 다음 조건을 보장합니다. • 서로 다른 SubTask가 같은 Worktree를 공유하지 않습니다. • 서로 다른 활성 SubTask가 같은 branch를 사용하지 않습니다. • Stack의 부모와 자식도 각각 별도의 Worktree를 가집니다. • 한 Worktree의 sync가 다른 Worktree의 작업 파일을 변경하지 않습니다. • 기본 main checkout을 Agent 작업 때문에 변경하지 않습니다. • 원격 변경을 이유로 다른 SubTask의 로컬 작업을 덮어쓰지 않습니다. 예: text main └─ sk-101 ├─ sk-102 └─ sk-103 물리적인 작업 공간은 다음처럼 분리됩니다. text worktree(sk-101) worktree(sk-102) worktree(sk-103) sk-102와 sk-103은 같은 부모를 사용하더라도 서로의 작업 공간에 영향을 주지 않습니다. Worktree 검증 현재 SubTask를 변경하는 Command는 실행 위치가 관리되는 Worktree인지 확인합니다. 대상 Command: • check • review open • review update • stack • sync 잘못된 위치에서 실행하면 작업을 수행하지 않습니다. json { "type": "failure", "data": { "code": "WORKTREE_REQUIRED", "message": "이 작업은 관리되는 SubTask Worktree에서 실행해야 합니다.", "next": [ "status --subtask sk-102" ] } } status는 Worktree 밖에서도 실행할 수 있습니다. Agent가 작업 경로를 잃어버린 경우 status --subtask로 다시 조회할 수 있습니다. Worktree 종료 SubTask가 main에 통합되면 Workflow가 Worktree 종료 가능 여부를 관리합니다. 다음 조건이 충족되기 전에는 작업 공간을 제거하지 않습니다. • SubTask 통합 완료 • 게시되지 않은 로컬 변경 없음 • 필요한 후속 Stack 동기화 완료 안전하게 제거할 수 없는 Worktree는 자동으로 삭제하지 않습니다. Agent가 별도의 git worktree remove를 실행할 필요는 없습니다. Result Schema 모든 구조화된 결과는 다음 형태를 사용합니다. 성공: json { "type": "success", "data": {} } 실패: json { "type": "failure", "data": { "code": "STATE_CONFLICT", "message": "...", "next": [] } } type은 다음 값만 가집니다. • success • failure Command별 결과는 모두 data에 위치합니다. workflow start 새로운 SubTask와 전용 Worktree를 시작합니다. Syntax bash ./tools/workflow start \ --task TASK-42 \ --type feature \ --title "추천 정책 선택 경계 추가" 미통합 선행 SubTask가 있다면 다음과 같이 실행합니다. bash ./tools/workflow start \ --task TASK-42 \ --type feature \ --title "신규 추천 정책 구현" \ --requires sk-101 Arguments Argument 필수 설명 --task O 외부 Task ID --type O 변경 유형 --title O SubTask의 변경 의도 --requires X 직접 필요한 미통합 선행 SubTask --json X JSON 결과 반환 기능 • 외부 Task 검증 • SubTask ID 발급 • 외부 하위 작업 연결 • SubTask metadata 생성 • 기준 코드 상태 확인 • branch 생성 • 전용 Worktree 생성 • dependency 설정 • 작업 경로 반환 독립적인 SubTask는 최신 원격 main을 기준으로 시작합니다. 미통합 선행 SubTask가 있다면 해당 SubTask의 코드를 기반으로 branch를 구성하되, 별도의 Worktree를 생성합니다. 같은 SubTask로 다시 호출하면 중복 Worktree를 만들지 않고 기존 관리 상태를 반환합니다. workflow check 현재 Worktree의 변경을 Repository 정책에 따라 검증합니다. Syntax bash ./tools/workflow check Arguments Argument 필수 설명 --json X JSON 결과 반환 기능 • 현재 Worktree 검증 • 현재 SubTask 확인 • 변경된 코드 확인 • Repository 필수 검사 실행 • 선행 코드 상태 확인 • 게시 가능 여부 반환 check는 파일이나 Git 상태를 변경하지 않습니다. workflow review review는 SubTask의 원격 게시와 PR Review lifecycle 전체를 담당합니다. text review open review show review update review comment review reply review resolve workflow review open 현재 Worktree의 변경을 처음 게시하고 Draft PR을 생성합니다. Syntax bash ./tools/workflow review open \ --body-file pr.md \ --risk normal Arguments Argument 필수 설명 --body-file O PR 본문 --risk O 위험도 --json X JSON 결과 반환 기능 • 현재 Worktree 확인 • 최신 check 확인 • 현재 변경을 게시 가능한 Git 상태로 기록 • 원격 branch 게시 • Draft PR 생성 • PR 제목 생성 • PR 본문 적용 • Task와 SubTask 연결 • Risk metadata 적용 • dependency와 PR base 적용 • CI 시작 Agent는 staging, commit, push를 직접 수행하지 않습니다. 현재 Worktree의 변경을 원격 Review revision으로 만드는 기계적인 Git 처리는 review open이 담당합니다. workflow review update Review 이후 수정한 Worktree를 다시 게시합니다. Syntax bash ./tools/workflow review update \ --revision rv-7 본문을 함께 변경할 수 있습니다. bash ./tools/workflow review update \ --revision rv-7 \ --body-file pr.md Arguments Argument 필수 설명 --revision O 마지막으로 확인한 Review revision --body-file X 변경할 PR 본문 --json X JSON 결과 반환 기능 • Worktree 확인 • revision 일치 여부 확인 • 최신 check 확인 • Worktree 변경 기록 • 원격 branch 갱신 • PR 갱신 • CI 재실행 • 새로운 Review revision 생성 Agent는 commit과 push를 직접 수행하지 않습니다. 다른 작업으로 revision이 바뀌었다면 갱신을 거부합니다. workflow review show 현재 Review 상태를 조회합니다. Syntax bash ./tools/workflow review show bash ./tools/workflow review show --diff Arguments Argument 필수 설명 --diff X Review 대상 변경 포함 --threads X 반환할 Thread 범위 --json X JSON 결과 반환 반환 정보 • PR 제목과 본문 • Review revision • diff • Risk • CI • Draft 또는 Ready 상태 • 사람 승인 • [R], [C], [A] thread • 작성자 • 코드 위치 • 해결 상태 • 다음 행동 workflow review comment 새로운 Review 의견을 추가합니다. Review 등급은 다음 값을 사용합니다. • [R]: 반영이 필요한 문제 • [C]: 우선 고려할 개선 • [A]: 선택적인 개선 String bash ./tools/workflow review comment \ --revision rv-8 \ --level R \ --body "fallback 경로에서 기존 동작이 유지되지 않습니다." File bash ./tools/workflow review comment \ --revision rv-8 \ --level R \ --body-file comment.md Inline bash ./tools/workflow review comment \ --revision rv-8 \ --level R \ --path src/main/... \ --line 42 \ --body "이 조건에서 기존 fallback 경로가 실행되지 않습니다." Arguments Argument 필수 설명 --revision O Review revision --level O 의견 등급 --body 조건부 문자열 본문 --body-file 조건부 파일 본문 --path X 대상 파일 --line X 대상 코드 위치 --json X JSON 결과 반환 --body와 --body-file 중 정확히 하나만 사용합니다. Agent 의견에는 CLI가 [Agent] 정보를 추가합니다. workflow review reply Review thread에 답변합니다. String bash ./tools/workflow review reply \ --revision rv-8 \ --thread thread-31 \ --body "수정하고 회귀 테스트를 추가했습니다." File bash ./tools/workflow review reply \ --revision rv-8 \ --thread thread-31 \ --body-file reply.md Arguments Argument 필수 설명 --revision O 현재 Review revision --thread O 대상 thread --body 조건부 문자열 답변 --body-file 조건부 파일 답변 --json X JSON 결과 반환 --body와 --body-file 중 정확히 하나만 사용합니다. reply는 thread 상태를 임의로 해결하지 않습니다. workflow review resolve 처리가 끝난 Review thread를 해결 상태로 변경합니다. bash ./tools/workflow review resolve \ --revision rv-8 \ --thread thread-31 Agent에게 해결 권한이 없는 사람 Review는 종료하지 않습니다. json { "type": "failure", "data": { "code": "HUMAN_REQUIRED", "message": "사람 리뷰어의 확인이 필요합니다.", "next": [ "human_review" ] } } workflow stack 현재 SubTask의 직접 코드 의존성을 변경합니다. 설정 bash ./tools/workflow stack --requires sk-101 제거 bash ./tools/workflow stack --clear 기능 • 현재 관리 Worktree 검증 • 선행 SubTask 검증 • dependency 변경 • branch 기반 관계 변경 • PR base 변경 • 필요한 restack • Review revision 영향 판단 • 재검증 필요 여부 반환 Agent는 branch를 직접 checkout하거나 rebase하지 않습니다. workflow sync 현재 Worktree를 신뢰 가능한 원격 상태와 동기화합니다. bash ./tools/workflow sync 기능 • 현재 Worktree 검증 • 최신 원격 main 확인 • 선행 SubTask 상태 확인 • 필요한 restack 수행 • 부모가 merge된 경우 최신 main 기준으로 정리 • PR base 동기화 • Stack metadata 동기화 • Review revision 영향 확인 자동으로 해결할 수 없는 충돌은 중단합니다. json { "type": "failure", "data": { "code": "SYNC_CONFLICT", "message": "자동으로 동기화할 수 없는 코드 충돌이 있습니다.", "workspace": { "path": "/repo-managed/sk-102" }, "next": [ "resolve_conflict" ] } } Agent가 수정해야 하는 경우에도 수정은 해당 Worktree 안에서 수행합니다. workflow status 현재 Workflow 상태를 조회합니다. 현재 Worktree bash ./tools/workflow status 특정 SubTask bash ./tools/workflow status --subtask sk-102 외부 Task bash ./tools/workflow status --task TASK-42 Arguments Argument 필수 설명 --subtask X 특정 SubTask --task X 외부 Task --json X JSON 결과 반환 반환 정보 • Task • SubTask • Worktree 경로 • Branch • dependency • Review • Review revision • Review thread • CI • 사람 승인 • Merge Queue • main 통합 • 배포 상태 • 공개 상태 • 차단 조건 • 다음 행동 예: json { "type": "success", "data": { "task": "TASK-42", "subtask": "sk-102", "workspace": { "path": "/repo-managed/sk-102" }, "branch": "feature/sk-102", "state": "REVIEW", "blocked_by": [ "human_approval" ], "next": [ { "actor": "human", "command": "gate approve sk-102" } ] } } workflow gate gate는 사람이 내려야 하는 결정을 기록합니다. Agent는 실행할 수 없습니다. bash ./tools/workflow gate ready sk-102 ./tools/workflow gate approve sk-102 ./tools/workflow gate deploy ./tools/workflow gate release • ready: 사람 Review를 시작할 수 있다고 판단 • approve: 코드 변경 승인 • deploy: High 배포 후보의 production 진행 승인 • release: 외부 공개 시작 승인 자동 기능 다음 작업은 Agent용 Command로 노출하지 않습니다. • branch 생성과 삭제 • Git worktree 생성과 제거 • 파일 staging • commit 생성 • push • force push 정책 • rebase와 restack • PR base 변경 • Merge Queue 등록 • squash merge • Normal 배포 시작 • Canary 진행 • 외부 공개 승인 이후 점진 확대 • 외부 Task 상태 동기화 이 작업들은 Workflow가 현재 상태와 공개 Command의 의도에 따라 수행합니다. Agent 기본 Workflow Agent가 작업을 시작하면 start가 별도 Worktree를 준비합니다. text workflow start │ ▼ workspace.path 반환 │ ▼ Agent가 해당 Worktree에서 작업 │ ├─ 코드 수정 │ ├─ workflow check │ └─ workflow review open │ ▼ Remote Review │ ┌─────────┴─────────┐ │ │ AI Review Human Review │ │ └─────────┬─────────┘ ▼ 같은 Worktree에서 수정 │ workflow check │ workflow review update │ reply / resolve / show Stack을 사용하는 경우에도 각 Agent 작업은 물리적으로 격리됩니다. text main └─ sk-101 ├─ sk-102 └─ sk-103 Workspaces ├─ worktree(sk-101) ├─ worktree(sk-102) └─ worktree(sk-103) 따라서 한 Agent가 sk-102를 수정하는 동안 다른 Agent가 sk-103을 수정해도 작업 디렉터리와 branch 상태가 충돌하지 않습니다. 핵심 보장 Workflow CLI는 Agent에게 다음 환경을 보장합니다. start 이후에는 하나의 SubTask에 하나의 격리된 Worktree가 존재합니다. Agent는 반환된 Worktree에서 코드만 수정하면 됩니다. Git 상태를 Repository 전체 관점에서 해석하고 안전하게 변경하는 책임은 Workflow가 가집니다. 이 원칙에 따라 Agent는 checkout, branch, commit, push, rebase, worktree 같은 Git lifecycle을 알 필요가 없습니다.