| name | cycle-orchestrator |
| description | 다중 worker cycle 자동화 (Phase 0 ticket 작성 → Phase 1 분석 → Phase 2 결정 → Phase 3 구현 → Phase 4 회귀 → Phase 5 종료). cycle 2026-05-06 학습 — 24 ticket × 5 worker 패턴 라이브러리화. 사용자가 "cycle 시작", "사용자 N 작업 묶음 ticket 으로 분해해줘", "cycle 자동화" 등 요청 시. - 3 항목 이상 작업 묶음 / 다중 worker 동시 진행 / 호환성 / 큰 리팩토링 |
cycle-orchestrator
목적
server-exporter 의 다중 worker cycle 메인 오케스트레이터. cycle 2026-05-06 학습 — 사용자 9 작업 항목 → 24 ticket 분해 → 5 worker 동시 진행 → 23 [DONE] + 1 [SKIP] 패턴 라이브러리화.
호출 시점
- 사용자 요청이 3 항목 이상 작업 묶음 (status / 호환성 / vault / vendor 추가 / 학습 등)
- 다중 worker 동시 진행 요구
- 호환성 cycle / 큰 리팩토링 / schema 변경
- 사용자 명시: "cycle 시작", "이 9 가지 작업 ticket 으로 분해", "다음 N cycle 잡아"
5 Phase 파이프라인
flowchart LR
P0([Phase 0<br/>ticket 작성]):::ok
P1([Phase 1<br/>분석<br/>read-only N worker 동시]):::ok
P2([Phase 2<br/>사용자 결정]):::warn
P3([Phase 3<br/>구현<br/>N worker 동시]):::ok
P4([Phase 4<br/>회귀<br/>pytest mock]):::ok
P5([Phase 5<br/>cycle 종료<br/>학습 + ADR]):::ok
P0 --> P1 --> P2 --> P3 --> P4 --> P5
classDef ok fill:#dfd,stroke:#3c3,stroke-width:2px,color:#000
classDef warn fill:#ffd,stroke:#c93,stroke-width:2px,color:#000
Phase 0: ticket 작성 (메인 세션 = orchestrator)
write-cold-start-ticket skill 적용:
- 디렉터리
docs/ai/tickets/<YYYY-MM-DD>-<주제>/ 생성
- INDEX.md / SESSION-HANDOFF.md / DEPENDENCIES.md / SESSION-PROMPTS.md 초안
- 사용자 N 작업 항목 → M-X# (영역 × round) 분해
- fixes/M-X#.md 6 절 cold-start 형식 모두 채움 (rule 25 R7-A — Agent 위임 가능, 단 메인이 실측 검증)
- NEXT_ACTIONS.md 진입점 추가
- commit:
docs: [<cycle> Session-0 DONE] N ticket 분해
Phase 1: 분석 (N worker — 의존 0 ticket 동시)
DEPENDENCIES.md 의 "진행 가능 ticket" list 부터:
- 영역별 read-only 분석 (envelope / 외부 계약 / vault / 호환성 매트릭스 등)
- M-X1 패턴 (영역별 첫 round)
- 동시 N=5 (1 worker = 1 영역 또는 인접 영역 묶음)
- 각 worker: ticket 6 절 모두 채움 + commit 마커
[SUB-N DONE]
Phase 2: 사용자 결정 (메인 세션 단독)
P1 출력 종합:
- 결정 포인트 list (M-X2 패턴 — 의도 결정)
- AI 추천 default 명시 (자율 진행 권한 적용 시)
- 사용자 명시 승인 필요 항목 (rule 92 R5 schema / rule 50 R2 vendor / rule 27 R6 vault decrypt 캐시)
Phase 3: 구현 (N worker — 결정 후 ticket 동시)
- M-X3 패턴 (영역별 코드 변경)
- Additive only (rule 92 R2 + rule 96 R1-B)
- 정본 4종 (envelope / sections / field_dictionary / build_status) 변경 시 docs/19 + docs/20 + 회귀 mock 동반 갱신 (rule 13 R7 + R8)
- pytest mock fixture N건 추가
- commit 마커
[SUB-N DONE]
Phase 4: 회귀 (메인 세션 또는 별도 worker)
- pytest tests/ -v
- 영향 vendor baseline 회귀
- verify_harness_consistency.py
- envelope shape 보존 (rule 96 R1-B) —
envelope_change_check.py
- 정본 4종 동기화 (rule 13 R7) —
pre_commit_docs20_sync_check.py
- status 4 시나리오 (rule 13 R8) —
pre_commit_status_logic_check.py
Phase 5: cycle 종료 (메인 세션 — M-G1/G2 패턴)
- HARNESS-RETROSPECTIVE.md 작성 (cycle 학습 N개)
- ADR 작성 (rule 70 R8 trigger 시)
- rule / skill / agent / hook 보강 (M-G2 패턴)
- NEXT_ACTIONS.md 갱신 (P2/P3 후보 list)
- PROJECT_MAP fingerprint 갱신
- final commit + push (github + gitlab 동시)
입력
- 사용자 N 작업 항목 list (자유 형식)
- cycle 주제 / 시작일
- worker 동시 진행 수 (default N=5)
출력
- 디렉터리
docs/ai/tickets/<YYYY-MM-DD>-<주제>/ (Phase 0 산출물)
- M-X# ticket 분해 결과 (Phase 0)
- Phase 1 분석 결과 + Phase 2 결정 포인트 (메인 종합)
- Phase 3 구현 commit list
- Phase 4 회귀 결과
- Phase 5 학습 / ADR / NEXT_ACTIONS
다중 worker 운영 (rule 25 + 26 정신)
| 항목 | 정책 |
|---|
| 오너십 표 | DEPENDENCIES.md 또는 SESSION-HANDOFF.md 의무 |
| 진입 prompt | SESSION-PROMPTS.md (worker N별 cold-start) |
| commit 패턴 | pathspec (git add <file> — git add . 금지) |
| commit 마커 | [<ticket-id> DONE] 또는 [SUB-N DONE] |
| 공용 파일 | 순차 편집 (schema / vault / Jenkinsfile) — rule 26 R4 |
| 의심 발견 | FAILURE_PATTERNS.md append-only |
| Agent 보고 | 메인이 실측 검증 (rule 25 R7-A) |
사용자 결정 trigger (Phase 2 의무)
다음 발생 시 Phase 2 진입 (Phase 3 자율 진행 차단):
- schema 변경 (sections.yml / field_dictionary.yml — rule 92 R5)
- envelope shape 변경 (rule 13 R5 / rule 96 R1-B)
- 새 vendor 추가 (rule 50 R2)
- vault decrypt 캐시 도입 (rule 27 R6)
- 의도 / 동작 변경 (예: status enum 4종 도입)
→ AI 추천 default 명시 + 사용자 승인 대기.
cycle 학습 누적 (M-G1 패턴)
매 cycle 종료 시 HARNESS-RETROSPECTIVE.md 의무:
- 학습 N개 (각 학습 = 1 rule / skill / agent / hook 후보)
- P1/P2/P3 분류
- M-G2 에서 P1 즉시 반영, P2/P3 NEXT_ACTIONS 등재
- ADR 작성 (rule 70 R8 trigger 해당 시)
관련
- rule 25 (parallel-agents)
- rule 26 (multi-session-guide)
- rule 70 R8 (ADR trigger)
- rule 91 (task-impact-preview)
- rule 92 R5 (schema 변경 사용자 승인)
- rule 96 R1-B (envelope shape 보존)
- skill: write-cold-start-ticket (Phase 0 도구), task-impact-preview (각 ticket 영향 분석), measure-reality-snapshot (Phase 1 실측), update-evidence-docs (Phase 5 정본 갱신)
- agent: ticket-decomposer (Phase 0 sub), wave-coordinator (3-channel 큰 변경 sub)
- hook: pre_commit_ticket_consistency.py (cold-start 6 절 advisory)
- 정본: cycle 2026-05-06-multi-session-compatibility (24 ticket 라이브러리)
