Agent Team Codex

Codex CLI의 stable multi-agent 기능을 사용해 작업을 병렬 분배하는 운영 스킬입니다. Codex의 default/explorer/worker 역할을 기준으로 실행하며 특정 모델을 강제하지 않습니다.

Prerequisites

현재 Codex에서 subagent 도구가 노출되는지 확인합니다. 현행 Codex는 [agents].enabled 기본값이 true입니다.
사용자가 명시적으로 비활성화한 경우 그 선택을 존중하고 메인 컨텍스트에서 Wave를 순차 실행합니다.
동시성 상한을 사용자가 조정하려는 경우에만 현재 설정명을 사용합니다:

[agents]
max_concurrent_threads_per_session = 6

사용자 정의 .toml agent는 필요하지 않습니다. 고유한 sandbox·MCP·모델 계약이 입증된 경우에만 별도 opt-in으로 추가합니다.

Source-only internal module resolution (mandatory)

code-reviewer와 조건부 orchestrator는 이 하네스가 내부 정책으로 읽는 source-only 모듈입니다. 등록된 스킬이나 slash command로 호출하지 않습니다.

각 선택된 모듈을 다음 순서로 해석하고 처음 확인된 exact SKILL.md 파일 하나를 읽습니다.

현재 프로젝트의 skills/{name}/SKILL.md가 실제로 있으면 그 exact 파일.
없으면 Codex active root의 ~/.codex/skills/{name}/SKILL.md exact 파일 (명시 opt-in 설치 지원).
둘 다 없으면 Codex 전역 ~/.codex/SKILLS-CATALOG.md에서 정확한 모듈명 행을 찾습니다. 행이 하나일 때만 읽을 경로에 적힌 절대 SKILL.md를 그대로 읽고, 누락·중복 행은 fail-closed입니다. 기본 경로가 보통 .olympus/source-skills 아래여도 직접 조합하거나 추측하지 않습니다.
module_root는 읽은 SKILL.md의 부모입니다. 모듈의 references/, scripts/, commands/는 모두 이 루트에서 해석합니다.
Step 6 코드 리뷰에 도달했을 때만 code_reviewer_root를 만듭니다. hard file lock, 외부 ledger, 크로스-CLI 혼합이 실제로 필요해 MCP 분기를 선택한 뒤에만 orchestrator_root를 만들고 ${orchestrator_root}/commands/workpm-mcp.md를 읽습니다.

이 exact 파일 읽기는 내부 모듈 로드입니다. 런타임 Skill 목록/레지스트리를 근거로 호출하거나 모듈 이름을 slash command로 실행하지 않습니다.

code-reviewer를 읽지 못하면 codex review 1회와 explorer의 bounded 품질·보안·타입 체크만 실행하고 policy module: NOT RUN (native fallback), gate DEGRADED를 기록합니다. orchestrator/MCP를 읽지 못하면 파일 소유권을 직렬화할 수 있는 경우에만 메인 순차 경로로 축소하고 MCP: NOT RUN을 기록합니다. hard lock이 필수이면 해당 Wave는 BLOCKED입니다. 어느 누락도 PASS로 처리하지 않습니다.

Modes

1) 섹션 모드

입력에 docs/plan/*/sections/index.md 또는 zephermine 산출물이 있는 경우 (archive/ 경로 제외)
섹션 의존성을 Wave로 분리해 병렬 실행

2) 자유 모드

일반 작업 요청(예: "auth 리팩토링 + 테스트")
파일/모듈 기준으로 태스크를 직접 분해 후 병렬 실행

조건부 MCP 정책 분기

기본 경로는 Codex native agent이며, agent가 없으면 메인 컨텍스트 순차 실행입니다. hard file lock, 외부 task ledger, 크로스-CLI 혼합 중 하나가 실제 요구사항일 때만 MCP 분기를 선택하고, 그때 위 resolver로 orchestrator 모듈과 ${orchestrator_root}/commands/workpm-mcp.md를 읽습니다. 선택 전에는 모듈·서버·활동 로그 도구를 로드하지 않습니다.

Workflow

Step 0: 산출물 검토 (PM 게이트)

Claude 버전 agent-team의 Step 0과 동일한 역할. 설계 없이 구현을 시작하지 않는다.

섹션 모드에서 필수 확인:

plan.md — 전체 구현 방향 파악
sections/index.md — 의존성 그래프 → Wave 분리 기준
flow-diagrams/ — 공정 도면 존재 여부 (있으면 각 worker에게 담당 노드 배분)
보조 문서 매핑:
- api-spec.md → API 관련 worker에게 전달
- mcp-spec.md → MCP 서버·도구 관련 worker에게 전달
- db-schema.md → DB 관련 worker에게 전달
- design-system.md → 프론트엔드 worker에게 전달
완료 기준 계약 — checklist.md 확인(없으면 섹션 AC에서 기계적으로 생성), checklist-status.md 장부 생성 또는 재개. 형식·상태·증거 규칙은 젭마인 references/acceptance-checklist-guide.md

자유 모드에서는 건너뜀.

Step 1: 작업 분해

목표를 3~8개의 독립 태스크로 분할
태스크별 담당 파일 범위를 고정
의존성 있는 태스크는 후행 Wave로 배치

상세 규칙: references/role-mapping.md

Step 2: 역할 매칭

explorer: 분석, 리스크 점검, 편집 금지
worker: 구현/수정/테스트
default: 조율, 병합 판단, 최종 보고

Step 3: 에이전트 스폰

Codex 프롬프트에서 자연어로 spawn 지시를 보냅니다. 템플릿은 references/prompt-templates.md를 사용합니다.

스폰 전 한 번: 소유권 기준점을 기록합니다. git stash create 출력 SHA(빈 출력이면 git rev-parse HEAD)와 git ls-files --others --exclude-standard의 기존 untracked 목록을 Lead가 activity log의 ## Ownership baseline에 적습니다. 작업 중에는 커밋하지 않으므로 Step 7의 충돌 확인은 커밋 이력이 아니라 이 기준점과 비교합니다. git stash create는 작업 트리를 바꾸지 않고, 작업 전부터 있던 미커밋 수정을 기준점에 포함합니다.

핵심 규칙:

각 worker는 파일 소유권 범위를 벗어나지 않음
explorer는 코드 수정 금지
충돌 가능성이 있으면 즉시 default가 재분배
각 worker는 담당 AC ID 목록을 받고, 변경 파일·테스트·계획 이탈·남은 위험과 AC별 ID | 증거 | 상태 제안을 반환하고, Lead만 conversations/{YYYY-MM-DD}-team-poseidon.md와 공유 implementation-notes.md를 기록

Step 4: 모니터링

진행 중 실패 태스크를 우선 확인
실패 원인을 한 번에 하나씩 재시도
3회 이상 반복 실패 시 아키텍처 이슈로 분류 후 사용자 보고

Step 5: Activity Log Summary

통합 전 활동 로그 요약:

Lead가 기록한 conversations/{YYYY-MM-DD}-team-poseidon.md 읽기
에이전트별 활동 통계: 완료 보고 수, 에러 수, 파일 수
orchestrator source module과 MCP command를 성공적으로 읽고 실제 분기를 시작한 경우에만 orchestrator_get_activity_log로 JSONL 로그도 확인. 그 외에는 MCP: NOT SELECTED 또는 MCP: NOT RUN으로 기록
요약을 최종 보고에 포함

Step 6: 코드 리뷰 게이트

구현 완료 후, 통합 전 품질 검증:

Step 6 진입 후 전역 카탈로그의 code-reviewer 행을 해석하고 ${code_reviewer_root}/SKILL.md의 Codex native 경로와 포세이돈 정책 레이어를 읽습니다. 등록 스킬로 호출하지 않습니다. 보안 감사 reference가 필요한 범위만 ${code_reviewer_root}/references/security-audit.md를 추가로 읽습니다.
native-first로 codex review --uncommitted 또는 적절한 base review를 실행하고, 필요한 보강 검토를 explorer 에이전트에게 위임합니다:
- 각 worker가 생성한 파일의 품질, 보안, 타입 안전성 확인
- Acceptance Criteria 대조 (Step 0에서 추출한 마스터 체크리스트)
- flow-diagrams 노드 매핑 (있는 경우) — 담당 노드가 구현되었는지
source module 미가용 시 native review + 위 세 항목만 bounded fallback으로 실행하고 policy module: NOT RUN, review gate: DEGRADED를 보고합니다.
미통과 항목 → 해당 worker 재spawn하여 수정 (최대 2회)
2회 후에도 미통과 → 사용자 보고

Step 7: 통합 게이트 (완료 권한 — 필수)

I-1: 병렬 구현 후 "함수가 존재하는가"를 Grep/Read로 확인하는 코드-존재 검증은 자기 판단이며, 컴파일/통합되지 않는 코드도 통과시킬 수 있다. 빌드/타입체크는 선택이 아니다.

파일 충돌 여부 확인 — 변경 파일 = git diff --name-only {기준점 SHA} ∪ (git ls-files --others --exclude-standard − 기준점의 기존 untracked). 각 파일을 담당 worker 소유와 worker가 반환한 변경 파일에 대조해, 같은 Wave의 둘 이상이 소유하면 CONFLICT(다른 Wave가 순차로 고친 공유 파일은 SHARED — 각자 맡은 부분만 바꿨는지 diff 확인), Lead 기록(activity log·checklist-status.md·implementation-notes.md)은 제외하고, 소유자가 없으면 UNOWNED(조립 지점에서 기준점 대비 diff에 - 줄 없이 등록 줄만 추가된 경우 제외), 아무도 보고하지 않았으면 UNREPORTED로 표시합니다. 근거 없는 변경은 revert하고, 필요한 변경은 소유에 추가해 activity log에 기록합니다
사전 점검(PRE-CHECK, 완료 권한 아님): 코드-존재 / Acceptance Criteria grep 대조 — 빠뜨린 작업 식별용일 뿐, 이것만으로 완료 선언 금지. AC는 proved/weak/missing/contradicted로 채점(028 완료 계약)해 Lead가 checklist-status.md에 증거와 함께 기록 — 코드는 있으나 동작 증거가 약하면 weak로 분리(존재=완료 둔갑 방지). 또한 경계면 정합성 교차 비교(웹앱: API 응답 shape↔훅 타입·경로↔href·엔드포인트↔훅 1:1 / 비웹: 해당 경계 / 없으면 skip) — 빌드 통과가 숨기는 런타임 mismatch를 게이트 전에 정적으로 거른다(양쪽 동시 읽기)
병합 결과에 대해 통합 게이트를 1회 실행 (이 게이트만이 완료 권한):
1. 빌드 / 타입체크
2. 전체 테스트 스위트 1회 실행 (병합된 결과 대상)
3. (가능하면) 통합/E2E 1회 실행
게이트 결과에 따라:
- 전부 통과하고 checklist-status.md의 모든 행이 proved(게이트 뒤 재확인) → 완료 선언 가능. 아니면 "M/N proved, 남은 ID"로 보고
- 실패 → 해당 worker 재spawn하여 수정 후 게이트 재실행
- 빌드/테스트 도구가 없으면 그 사실을 명시하고 사용자에게 수동 확인을 요청 (자동 PASS 금지)
남은 리스크/미해결 항목 정리

Guard: 게이트 미통과 상태로 완료 선언 금지; 빌드/테스트 도구가 없으면 명시하고 수동 확인 요청(자동 PASS 금지).

Output Format

최종 보고는 아래 포맷을 따릅니다:

Codex Agent Team 실행 결과
- 완료 태스크: N개
- 실패 태스크: N개
- 마스터 체크리스트: M/N 통과 (XX%)
- 주요 변경 파일: ...
- 테스트 결과: 통과 N / 실패 N
- 내부 모듈: code-reviewer {LOADED|NOT RUN}, orchestrator MCP {NOT SELECTED|LOADED|NOT RUN}
- 잔여 리스크: ...

👉 다음 단계 (선택):
  /argos               → 감리 (설계 대비 구현 검증, Phase 0~6)
  /aphrodite           → 디자인 정교화 (design-system.md가 있는 UI 프로젝트)
  /minos          → Playwright 자동 테스트 + Healer 루프
  /review              → 코드 리뷰
  /commit              → 변경사항 커밋

Troubleshooting

subagent 도구가 보이지 않음

codex features list와 현재 [agents].enabled 설정을 확인합니다.
현행 버전인데 도구가 없으면 Codex를 갱신하고 세션을 다시 시작합니다.
사용자가 agents를 껐거나 갱신할 수 없으면 메인 컨텍스트 순차 실행으로 계속합니다.

에이전트 충돌(같은 파일 동시 수정)

파일 소유권을 다시 나눠 재스폰
공통 모듈은 별도 single-owner 태스크로 분리

스레드 과다로 품질 저하

max_concurrent_threads_per_session을 줄여 재실행 (예: 6 → 4)
explorer를 1개로 고정하고 worker 수만 조절

References

역할/소유권 규칙: references/role-mapping.md
스폰 프롬프트 템플릿: references/prompt-templates.md

agent-team-codex

SKILL.mdskills/agent-team-codex/SKILL.md