Agent Team — Zephermine 섹션 병렬 실행
포세이돈(Poseidon): 젭마인 산출물을 받아 체계적으로 구현합니다. 바다의 신 포세이돈이 파도(Wave)를 일으키듯, 섹션 의존성을 Wave 단위로 정렬하고 teammate들을 병렬로 출항시킵니다.
zephermine이 생성한 섹션(sections/)의 의존성 그래프를 분석하여 Wave 단위로 teammate에게 배정하고 병렬 실행합니다.
다이달로스 vs 포세이돈
| 상황 | 사용할 도구 |
|---|---|
| 젭마인 없이 바로 구현 시작 | 다이달로스 (/daedalus) — 직접 리서치 → 제안 → 구현 |
| 젭마인 산출물(sections/) 기반 구현 | 포세이돈 (/agent-team 또는 /poseidon) — 섹션 파싱 → Wave → 구현 |
Lead(PM) 핵심 원칙
다이달로스의 PM 철학을 포세이돈 Lead에도 적용합니다.
1. 업무 분장 — Lead는 작업 경계와 통합을 소유한다
정상 위임 경로에서 Lead는 업무 분장·의존성 조율·사용자 소통·결과 검증과 통합을 맡고, 구현과 관련 테스트는 작업자가 수행합니다. 작업이 하나이거나 서로 의존하면 한 작업자에게 묶거나 순차 배정합니다. 파일이 달라도 같은 계약·판단을 계속 공유해야 하면 억지로 나누지 않습니다. 독립적으로 완료·검증할 수 있고 병렬 이득이 있는 작업만 동시 배정합니다. 메인 직접 구현은 위임 불가·실패 등 아래에 명시된 순차 폴백이며 정상 업무 분장을 대체하지 않습니다.
2. 기억 외부화 — 기억력을 믿지 마라
대화가 길어지면 오래된 내용이 자동 압축된다. 중요한 결정이 나올 때마다 activity log에 즉시 기록한다.
3. 체크리스트 완수 — 모든 Acceptance Criteria가 통과할 때까지 끝이 아니다
젭마인 산출물에는 섹션별 Acceptance Criteria(체크리스트)와 flow-diagrams(공정 도면)이 있다.
teammate가 "완료"라고 보고해도 Lead가 직접 체크리스트를 대조하여 모든 항목이 통과할 때까지 반복한다.
완료 기준은 젭마인이 ID를 붙여 고정한 checklist.md(약속)이고, 이행은 Lead가 checklist-status.md 장부에 증거와 함께 기록한다.
형식·상태·증거 규칙의 정본은 젭마인 references/acceptance-checklist-guide.md이다. 대화로만 대조하면 컨텍스트가 압축될 때 함께 사라지므로 장부에 남긴다.
한 번 구현하고 끝내는 것은 PM이 아니라 실행자다.
Lead 운영 규율
Lead가 직접 하는 것:
- 젭마인 산출물 검토 (plan, sections, flow-diagrams, acceptance criteria)
- teammate 보고 수신 및 체크리스트 대조
- 의사결정 + activity log 기록
- teammate 배정/교체
- 미통과 항목 → teammate에게 재지시
- 명시된 순차 폴백에서만 작업자 역할을 겸한 직접 수행
작업자가 가용한 병렬 경로에서 Lead가 하지 않는 것:
- 작업자와 같은 파일을 동시에 수정
- 독립 작업자의 조사·테스트를 중복 실행
- 외부 검증 없이 완료 선언
자기검증 3질문 — Wave 완료 보고 시 반드시 자문:
- 가장 어려운 결정이 뭐였나?
- Acceptance Criteria 중 위험한 항목은?
- 도면과 실제 구현이 일치하는가?
팀원 관리 원칙
| 규칙 | 설명 |
|---|---|
| 파일 영역 분리 | 같은 파일을 두 teammate가 동시에 수정 금지 |
| idle 방치 | teammate idle 알림이 와도 task 진행 중이면 절대 개입 안 함 |
| 교체 정책 | 다음 Wave가 이전 작업과 무관하면 → 새 teammate. 연장선이면 유지 |
| 이름 규칙 | 교체 시 같은 이름 재사용 불가 |
CLI별 실행 모드
native-first 원칙 (learned/020): 실행 엔진은 각 CLI의 네이티브 멀티에이전트에 위임하고, orchestrator MCP는 네이티브가 없는 구버전 CLI의 폴백 + hard file-lock 정책 레이어로만 남긴다.
Antigravity /teamwork-preview 경계
- 별도
sections/·Wave·파일 소유권·자재검사 산출물이 필요 없는 일반 장기·다중 에이전트 작업은, 현재 플랜과 런타임에서 사용할 수 있으면 Antigravity 네이티브/teamwork-preview가 소유합니다. - 사용자가
/teamwork-preview를 명시적으로 시작했거나 현재 세션에 그 팀 상태가 이미 노출돼 있으면 이를 실행 엔진으로 사용하고, Poseidon은 섹션 파싱·Wave ledger·파일 소유권·검증 게이트만 덧붙입니다. - 이 스킬이 slash command를 프로그램적으로 호출할 수 있다고 가정하지 않습니다. 활성 팀 문맥이 없으면
공식
invoke_subagent/define_subagent로 같은 계약을 수행하고, 그 기능도 없으면 메인 순차 실행으로 축소합니다. /teamwork-preview의 플랜·가용성 조건을 우회하거나 유료 기능을 자동 활성화하지 않습니다.
| CLI | 읽기 전용 탐색·검토 | 구현·명령 실행 | 팀 조율 |
|---|---|---|---|
| Claude | 내장 Explore |
내장 general-purpose 또는 이름 있는 background teammate |
Agent Teams가 활성화된 경우 Agent + shared task list + SendMessage |
| Codex | 내장 explorer |
내장 worker (default는 범용 폴백) |
현재 세션에 노출된 spawn/message/wait/interrupt 도구 |
| Antigravity | 내장 research |
활성 /teamwork-preview 팀 또는 메인/쓰기 도구를 명시한 사용자 정의 서브에이전트 |
활성 팀 상태나 invoke_subagent 반환을 Lead가 Wave ledger에 반영 |
| Grok | 내장 explore |
내장 general-purpose |
subagent 호출 결과를 Lead가 Wave ledger에 반영 |
역할명은 의미 계약입니다. 읽기 전용 역할에는 파일 생성을 지시하지 않고, 구현 역할에는 담당 파일·검증 명령·완료 보고 형식을 함께 전달합니다. CLI별 도구 이름이나 인자 스키마가 달라지면 현재 런타임이 노출한 도구를 사용하며, 이 문서의 예시 이름을 억지로 호출하지 않습니다.
네이티브 위임이 없거나 실패하면 같은 Wave의 독립 작업을 메인 컨텍스트에서 순차 실행합니다. hard file lock, 외부 task ledger, 크로스-CLI 혼합이 실제로 필요할 때만 workpm-mcp를 선택합니다.
Source-only internal module resolution (mandatory)
code-reviewer와 조건부 orchestrator는 포세이돈이 내부 정책으로 읽는 source-only
모듈입니다. 등록된 스킬이나 slash command로 호출하지 않습니다.
각 선택된 모듈을 다음 순서로 해석하고 처음 확인된 exact SKILL.md 파일 하나를 읽습니다.
- 현재 프로젝트의
skills/{name}/SKILL.md가 실제로 있으면 그 exact 파일. - 없으면 현재 런타임 active root의 exact 파일: Claude/Grok은
~/.claude/skills/{name}/SKILL.md, Codex는~/.codex/skills/{name}/SKILL.md, Antigravity는~/.gemini/antigravity-cli/skills/{name}/SKILL.md(명시 opt-in 설치 지원). - 둘 다 없으면 현재 런타임 전역 카탈로그(Claude/Grok
~/.claude/SKILLS-CATALOG.md, Codex~/.codex/SKILLS-CATALOG.md, Antigravity~/.gemini/antigravity-cli/SKILLS-CATALOG.md)에서 정확한 모듈명 행을 찾습니다. 행이 하나일 때만읽을 경로의 절대SKILL.md를 읽고, 누락·중복 행은 fail-closed입니다. 기본 경로가.olympus/source-skills아래여도 조합하거나 추측하지 않습니다. module_root는 읽은SKILL.md의 부모입니다.references/,scripts/,commands/는 모두 이 루트에서 해석합니다.- Step 5 코드 리뷰 분기에 도달했을 때만
code_reviewer_root를 만듭니다. 실행 방식 변경 가설이 있으면orchestrator_root를 해석해${orchestrator_root}/references/execution-adjustment.md만 읽습니다. hard file lock, 외부 task ledger, 크로스-CLI 혼합이 실제로 필요해 MCP 분기를 선택한 뒤에만${orchestrator_root}/commands/workpm-mcp.md를 읽고 MCP 도구를 사용합니다.
이 exact 파일 읽기는 내부 모듈 로드입니다. 런타임 Skill 목록/레지스트리를 근거로 호출하거나 모듈 이름을 slash command로 실행하지 않습니다.
code-reviewer를 읽지 못해도 원래 worktree·index 기준점과 기존 untracked 제외를 유지합니다.
네이티브 review가 같은 범위를 표현하면 1회 실행하고 아래 bounded 항목을 보강합니다.
표현할 수 없거나 엔진이 없으면 native review: NOT RUN으로 남기고 읽기 전용 작업자가 같은
patch·파일 범위의 bounded 항목을 점검합니다(위임 불가면 메인 순차 검토).
모든 모듈 누락 경로는 policy module: NOT RUN (bounded fallback), 게이트 DEGRADED이며
source module PASS를 주장하지 않습니다. MCP 분기를 선택했는데 orchestrator/MCP를 읽지 못하면 편집을 직렬화할 수 있는 범위만 메인 순차
경로로 축소하고 MCP: NOT RUN을 기록합니다. hard lock이 필수이면 해당 Wave는 BLOCKED입니다.
누락된 모듈을 조용히 PASS 처리하지 않습니다.
실행 방식 비교 문서만 읽는 경로는 MCP: NOT SELECTED입니다. 그 문서를 읽지 못하면
adjustment: not-run (module unavailable)을 남기고 기존 구현 수정·검증을 수행합니다.
CLI 감지 방법
Phase 0 시작 시 제품명보다 현재 도구 레지스트리를 우선합니다.
- 읽기 전용 탐색 역할과 쓰기 가능한 작업 역할을 구분할 수 있는지 확인합니다.
- 병렬 위임과 상태 회수가 모두 가능하면 네이티브 Wave 실행을 사용합니다.
- 위임만 가능하고 병렬·중간 메시지가 보장되지 않으면 bounded sub-wave 또는 순차 위임으로 축소합니다.
- 위임 도구가 없으면 메인 컨텍스트 순차 실행으로 계속합니다.
- 병렬성이 필수이고 네이티브 경로가 없을 때만
workpm-mcp를 제안합니다.
Prerequisites
Claude 모드
- Agent Teams는 실험 기능이며
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1일 때만 사용합니다. 스킬이 전역 설정을 자동 변경하지 않습니다. - Claude Code 2.1.178+는 세션당 implicit team을 사용합니다.
TeamCreate/TeamDelete는 호출하지 않고, 이름 있는 background teammate를Agent로 직접 생성합니다. 세션 종료 시 팀 정리는 런타임이 담당합니다. - teammate는 Lead의 permission mode를 상속합니다. 스폰 프롬프트에서
bypassPermissions를 지정하거나 권한을 우회하지 않습니다. 필요한 권한은 사용자가 Lead 세션에서 먼저 선택합니다. - Agent Teams가 꺼져 있으면 독립 조사에는 내장
Explore, 구현에는general-purpose를 사용하고, 병렬성이 없으면 순차 실행합니다.
추론 강도 선택 전략
런타임의 현재 모델과 사용자 설정을 상속합니다. 특정 vendor 모델을 스킬이 강제하지 않습니다.
| Wave 단계 | 팀원 역할 | 요구 강도 |
|---|---|---|
| Wave 0: 도메인 분석 | 아키텍처 조사, 기술 스택 평가, DB 스키마 설계 | 높은 추론 강도 |
| Wave N: 구현 | 기능 코딩, 파일 생성, 테스트 작성 | 균형형 실행 |
| 최종 자재검사 | 네이티브 읽기 전용 리뷰 + code-reviewer 정책 | 높은 추론 강도 |
| Wave N: 테스트 실행 | 테스트 러너, 린트, 타입 체크 | 빠른 실행 |
| 최종 검증 | AC 대조, 공정 점검 | 높은 추론 강도 |
위임 프롬프트에는 역할, 담당 범위, 입력 아티팩트, 쓰기 허용 여부, 검증 명령, 반환 형식만 넣습니다. 모델 지정은 사용자가 요청했거나 런타임 설정이 명시적으로 제공된 경우에만 사용합니다.
Wave 완료 후 테스트 검증 (필수)
각 Wave 구현 완료 시, 담당 작업자의 관련 테스트 증거를 Lead가 확인한다. 별도 환경이나 독립 검증이 필요한 경우에만 검증 작업자를 배정한다:
- 기존 관련 테스트: 변경 및 후속 Wave가 소비할 계약을 다루는 테스트 결과 확인. 같은 코드에 유효한 증거가 있으면 재사용
- 린트/타입 체크: 변경 범위에 필요한 프로젝트 검사 실행. 전체 테스트 스위트는 모든 Wave가 합쳐진 최종 통합 게이트에서 실행
- 실패 시: 실패 명령·출력·부분 변경으로 원인 판별 → 구현 결함 수정·환경 복구 또는 아래 실행 방식 비교 → 재실행 (최대 3회; 더 작은 기존 상한 우선)
- 반복 실패: 근거를 다시 확인하고 남은 상한 안에서만 재시도. 소진하면 미완료 보고하며 작업자 교체로 횟수를 초기화하지 않음
문맥·작업 분할·도구 순서가 원인이라는 근거가 있으면 위 resolver로 orchestrator_root를 정하고
${orchestrator_root}/references/execution-adjustment.md를 읽습니다. Lead가 현재 태스크의 변경
가설·같은 조건의 재실행·채택을 소유합니다. 단순 구현 결함이나 정상 Wave에는 비교를 추가하지 않습니다.
에러 복구 전략
| 상황 | 조치 |
|---|---|
| 팀원이 잘못된 파일 수정 | 소유권 기준점 대비 변경 목록(verification-protocol.md 3단계)으로 확인 → revert 지시 |
| 테스트 반복 실패 | 원인 재분류 → 근거 있는 실행 변경은 공통 비교 계약 적용. 기존 상한 소진 시 미완료 보고 |
| 자재검사 2회 미통과 | 리뷰 지적과 실패 근거 보고. 작업자 교체로 재시도 상한을 초기화하지 않음 |
| 팀원 무응답 (1분+) | shutdown → 재스폰 (최대 2회) |
Codex 모드
- Codex의 내장
explorer/worker/default를 사용합니다. 사용자 정의.tomlagent는 이 스킬의 필수 조건이 아닙니다. - subagent는 현재 세션의 sandbox와 approval policy를 상속합니다. 스킬이
--yolo, 승인 우회, sandbox 해제를 권장하거나 설정하지 않습니다.
Antigravity 모드
- 일반 장기 팀 작업이고 Olympus 섹션·Wave·소유권·검증 산출물이 필요 없으면 가용한
/teamwork-preview를 우선합니다. 이미 활성화된 팀 문맥은 실행 엔진으로 재사용하며 중첩 PM/팀을 만들지 않습니다. - Antigravity TUI의
/agents패널과 현재 세션의 도구 목록에서 내장research와 사용 가능한 사용자 정의 에이전트를 확인합니다. - 읽기 전용 조사는
research, 구현은 메인 또는 쓰기 도구를 명시한 사용자 정의 서브에이전트에 맡깁니다. - 공식
invoke_subagent와 필요 시define_subagent를 사용합니다. 메시지·상태·중단 기능은 현재 런타임이 실제 노출한 도구만 사용하고 이름을 추측하지 않습니다. - 구현 근거는 읽을 수 있는 섹션·프로젝트 설정·인접 코드·테스트의 정확한 경로와 필수 계약으로 전달합니다. 병렬 실행이 불가하면 Wave 내 순차 위임으로 축소합니다.
Grok 모드
- Grok Build는 네이티브
general-purpose,explore,plan서브에이전트를 제공. Olympus source-only 프롬프트는 기본 설치하지 않음 - 일반 구현은
general-purpose, 읽기 전용 탐색은explore를 사용합니다. 명명형 어댑터는 고유 런타임 계약이 있을 때만 명시 opt-in합니다. - 자식 결과는 요약으로 회수되므로 완료 판정은 실제 파일·테스트 결과로 교차 검증합니다. 동시성은 런타임 제한과 독립 작업 수 중 더 작은 값으로 제한합니다.
공통
- zephermine 계획 산출물 (sections/index.md + section-NN-*.md 파일들)
Team Name
팀 이름은 **포세이돈(Poseidon)**으로 고정합니다. teammate 생성 시 이 팀명을 사용하세요.
공식 호출명: /agent-team (별칭: /poseidon, 포세이돈, Poseidon)
포세이돈은 바다의 신이며, 파도(Wave)를 다스리는 존재입니다. 섹션 의존성 그래프를 Wave 단위로 정렬해 teammate들을 병렬 출항시키는 이 스킬의 본성과 일치합니다.
CRITICAL: First Actions
1. Print Intro
포세이돈(Poseidon) 출항
모드 판별 후 표시:
[섹션 모드] 순서: 산출물 검토 → Parse → Wave Plan → Tasks → Execute → Review → Verify(반복) → Activity Log → Report
[자유 모드] 순서: Analyze → Wave Plan → Tasks → Execute → Review → Verify(반복) → Report
2. Determine Mode
두 가지 모드를 자동 판별:
섹션 모드 (zephermine 산출물 있음)
$ARGUMENTS로 planning_dir가 제공되었거나docs/plan/*/sections/index.md가 존재하면 (archive/ 경로 제외)- → 섹션 모드로 진행 (Step 0~8 워크플로우)
자유 모드 (사용자 지시만 있음)
- planning_dir이 없고, sections/index.md도 없으면
- 사용자의 대화 컨텍스트에서 작업 지시를 추출
- → 자유 모드로 진행 (Lead가 직접 분석 → 분배)
섹션 모드: "agent-team docs/plan/my-feature" → sections/ 파싱 → Wave 실행
자유 모드: "이 3개 파일 리팩토링해줘. 에이전트팀 진행하자" → Lead가 분석 → 분배
3. Setup (모드별 분기)
섹션 모드 Setup
sections/index.md존재 확인SECTION_MANIFEST블록 파싱 확인- 최소 1개 이상
section-NN-*.md파일 존재 확인 - → **Step 1 (Parse Sections)**로 진행
자유 모드 Setup
- 사용자 지시에서 작업 목표 추출
- 관련 코드베이스 탐색 (Glob, Grep, Read)
- 작업을 독립적인 태스크로 분해 (파일/모듈/기능 단위)
- 각 태스크의 의존성 판별 → Wave 그룹핑
- 구현 컨텍스트 매칭 (expert-matching.md 참조)
- **Step 2 (Build Wave Plan)**의 사용자 확인 출력으로 합류
- planning_dir이 없으므로 태스크별 완료 기준을 같은 형식(
AC-<태스크번호>-k, 관찰 가능한 동작·검증)으로 정해 Step 2 실행 계획에 함께 출력하고, 이행 장부는 activity log의## Acceptance표로 둔다 (형식: 젭마인references/acceptance-checklist-guide.md) - 같은 실행 계획에
구현 중트립와이어 1~2개(틀리면 작업 전체가 헛수고가 되는 가정이 있으면 그 확인을 Wave 1 태스크로 두고 결과를 지표로)를 정하고, 장부는 activity log의## Tripwires표로 둔다 (형식: 젭마인references/tripwire-guide.md)
자유 모드 태스크 분해 원칙:
- 파일 충돌 없도록 담당 파일을 명확히 분리
- 태스크는 함께 판단·검증할 책임으로 묶고 파일 수나 최소 태스크 수를 맞추기 위해 나누지 않음
- 의존성이 없는 태스크도 병렬 이득과 현재 가용 슬롯을 확인해 Wave에 배치
- description에 구현 지시 + 담당 파일 + 관련 코드 컨텍스트 포함
Workflow
Pre-Step: 런타임 상태 확인
먼저 verification-protocol.md의 실행 식별과 재개에 따라 기존 activity log와 계획을 연결합니다. 현재 세션의 task·작업자 상태와 실제 파일·검증 증거를 대조한 뒤 미완료 작업만 배정합니다. 이전 세션의 팀 디렉터리를 수동 삭제하거나 정리 명령을 추측해 호출하지 않습니다. 런타임 상태를 조회할 수 없으면 기록과 파일로 확인하며, 같은 파일의 진행 중 작업을 중복 배정하지 않습니다.
Step 0: 산출물 검토 (PM 게이트)
Lead는 설계 도면을 확인하지 않고 공사를 시작하지 않는다.
See artifacts-review.md
젭마인 산출물을 PM 관점에서 검토합니다. 확인 항목:
plan.md— 전체 구현 방향 파악sections/index.md— SECTION_MANIFEST + 의존성 그래프flow-diagrams/— 공정 도면 존재 여부 (없으면 사용자 경고)- 보조 문서 (api-spec.md, db-schema.md 등) — teammate 전달 레퍼런스 등록
- 완료 기준 계약 —
checklist.md확인(없으면 섹션 AC에서 기계적으로 생성),checklist-status.md장부 생성 또는 재개 - 영향도 분석 (기존 코드가 있는 경우) — 교차 영향 파일 경고
- 트립와이어 —
plan.md### 트립와이어의구간이구현 중인 지표와위험 가정:확인 섹션을 확인해 Step 5A 판정 대상으로 등록. 없으면Tripwire: NOT APPLICABLE — plan.md에 없음을 activity log에 남김
Step 1: Parse Sections
See section-parser.md
sections/index.md에서 다음을 추출:
- SECTION_MANIFEST 블록 → 섹션 목록
- Dependency Graph 테이블 → 의존성 관계
- 각
section-NN-*.md파일의 존재 여부 확인
프로세스 도면 매핑: sections/index.md에 Flow Diagram Mapping 테이블이 있으면 섹션↔도면 노드 매핑을 추출하여 Step 2, Step 4에 반영.
구현 컨텍스트 매칭: See expert-matching.md — 각 섹션의 파일 패턴으로 프로젝트 근거·역할·검증 계약을 구성.
Step 2: Build Wave Plan
의존성 그래프를 위상 정렬(Kahn's Algorithm)하여 Wave 그룹으로 분류:
- 의존성이 없는 섹션 → Wave 1
- Wave 1에만 의존하는 섹션 → Wave 2
- 반복... 순환 의존성 발견 시 경고 후 사용자 보고
- 동시 작업자 수는 독립 작업 수·현재 런타임의 가용 슬롯·기존 예산 안에서 정합니다. 상한을 넘으면 sub-wave로 분할합니다.
- 섹션 수와 작업자 수를 1:1로 맞추지 않습니다. 관련 섹션은 같은 작업자가 이어받을 수 있지만 섹션별 AC·소유권·의존성과 Wave 경계 검증은 유지합니다.
사용자에게 실행 계획 출력:
═══════════════════════════════════════
포세이돈(Poseidon) 실행 계획
═══════════════════════════════════════
Wave 1 (병렬 3개):
- section-01-foundation [풀스택] (파일: src/core/**)
- section-02-config [풀스택] (파일: src/config/**)
Wave 2 (병렬 2개):
- section-04-api [백엔드 전문가] (→ 01, 03 완료 후) 📐 user-auth.mmd
- section-05-database [DB 전문가] (→ 01, 02 완료 후)
총 섹션: N개 | 총 Wave: M개 | 예상 teammate: K명
═══════════════════════════════════════
Wave Plan 출력 후 확인 없이 바로 Step 3으로 진행 (사용자가 이미 실행 요청한 상태).
Step 3: Create Tasks
See teammate-context-template.md
Claude 모드 (TaskCreate)
미완료 섹션을 TaskCreate로 등록하거나 기존 Task를 재사용하고 blockedBy 관계 설정. description에 아래 공통 전달 계약 포함.
Codex 모드 (spawn_agent)
Wave 단위로 agent spawn. prompt에 아래 공통 전달 계약 포함.
Antigravity 모드 (서브에이전트 위임)
Wave 단위로 기본/범용 서브에이전트를 호출하고 아래 공통 전달 계약을 위임 프롬프트로 전달.
Grok 모드 (spawn_subagent)
Wave 단위로 spawn. prompt에 아래 공통 전달 계약을 포함하고,
일반 구현의 subagent_type은 general-purpose를 사용.
공통 전달 계약: 대화 상속에 기대지 않고 프로젝트 루트·섹션·필요 참조의 정확한 절대경로, 목표, 담당 AC ID와 필수 제약, 파일 소유권, 선행 산출물 계약, 검증 명령·반환 형식을 명시합니다. 작업자가 공유 파일을 읽을 수 있으면 해당 파일을 직접 읽도록 하고 전체 본문을 재임베딩하지 않습니다. 파일 접근이 불가능할 때만 구현에 필요한 원문을 전달하고 누락 입력은 Lead에게 반환하게 합니다. 상세 형식은 위 템플릿을 따릅니다.
Step 4: Execute Waves
See wave-executor.md
새 실행의 Wave 1 시작 전 한 번: 소유권 기준점(git stash create SHA 또는 HEAD + 기존 untracked 목록)을 activity log에 기록 — verification-protocol.md 0단계. 재개는 같은 실행의 원래 기준점을 유지합니다.
각 Wave별 실행 사이클:
- 선행 Task의 blockedBy와 후속 소비 계약 해소 여부 확인. 누락·미검증 의존성의 소비자만 보류하고 독립 작업은 계속
- teammate/agent에게 지시 (담당 파일, 도면 노드, 파일 소유권 규칙 포함)
- 진행 상황 모니터링 (Claude: shared task list/메시지, Codex: 현재 wait 도구, Antigravity/Grok: subagent 반환 — 모든 요약을 체크리스트·파일 실존과 대조)
- 결과 수집 → Step 5의 후속 소비 경계 확인과 Step 5A 트립와이어 판정을 거쳐 준비된 다음 작업 배정. 모든 Wave가 끝나면 최종 코드 리뷰
teammate 지시 핵심 요소:
- 프로젝트 기반 역할·근거, 섹션 절대경로·필수 제약, 담당 파일 목록
- 담당 섹션의 AC ID 목록 — 완료 보고에 AC ID별 증거(테스트 이름·명령 결과)와 상태 제안을 포함
- 📐 프로세스 도면 경로 + 담당 노드 ID (도면 있는 경우)
- ⚠️ 파일 소유권 규칙 (다른 teammate 파일 수정 금지)
- 작업자는 변경 파일·테스트·이탈 사유를 반환하고, Lead만
conversations/{YYYY-MM-DD}-team-poseidon.md에 activity log를 기록
Step 5: Wave 경계 확인과 최종 Code Review Gate (자재검사)
각 Wave에서는 verification-protocol.md의 후속 Wave 소비 경계 확인만 수행합니다. 선행 산출물·관련 AC·검증 증거를 확인해 잘못된 계약이 다음 작업으로 전파되는 것을 막습니다. 매 Wave 전체 코드 리뷰를 반복하지 않습니다.
모든 Wave 구현이 끝나면 변경 범위 전체에 아래 최종 코드 리뷰를 한 번 수행합니다. 수정 후 재검토는 바뀐 부분과 영향 범위를 대상으로 합니다.
- 이 Step에 도달한 뒤 전역 카탈로그의
code-reviewer행을 해석하고${code_reviewer_root}/SKILL.md를 읽습니다. 이 모듈의 포세이돈 연동·정책 레이어를 적용하되, 등록 스킬을 호출하지 않습니다. 보안 감사 reference가 필요한 범위만${code_reviewer_root}/references/security-audit.md를 추가로 읽습니다. - 원래 worktree·index 기준점과 기존 untracked 제외를
review_scope: task로 전달하고, 같은 범위를 표현할 수 있는 리뷰 엔진을 native-first로 선택합니다. 표현할 수 없으면 모듈의 같은 범위 풀 경로를 사용합니다.- Claude: 내장
/review; 병렬화가 필요하면 읽기 전용 Explore 작업자에 로드한 gate 전달 - Codex:
/review또는codex review; 읽기 전용 explorer에 로드한 gate 전달 가능 - Antigravity: 읽기 전용
researchsubagent에 로드한 경로 C gate 전달 - Grok: bundled
review; 실패하면exploresubagent에 같은 gate 전달
- Claude: 내장
- source module을 읽지 못하면 위 resolver의 동일 범위 bounded fallback만 실행하고
policy module: NOT RUN,review gate: DEGRADED로 남깁니다. - 미통과 시 → 위 실패 원인 판별과 실행 방식 비교 분기를 거쳐 수정 → 재리뷰 (최대 2회; 비교도 같은 상한에 포함)
검수 항목: 기능/책임 단위 분리, 보안 취약점, 타입, SRP, DRY
Step 5A: Tripwire Check (Wave 경계 판정)
Wave 경계 확인 후, 다음 Wave를 시작하기 전에 Step 0에서 등록한 구현 중 지표를 판정한다. 판정 절차·기록 위치·행동의 정본은 젭마인 references/tripwire-guide.md의 ## 구현 중 판정이다. Wave가 끝날 때마다 보지 않으면 방향이 틀어진 채 남은 Wave가 그 위에 쌓인다.
- 지표 값을 계측 위치(
checklist-status.md, activity log 재지시 기록, 위험 가정 섹션의 테스트·평가 출력 등)에서 읽는다.출시 후만인 지표는 판정하지 않는다. 데이터가 모자라면 단계를 매기지 않고데이터 없음 — <사유>로 남긴다. - 계속 조건 → 다음 Wave. 초기 신호 → 다음 Wave로 가되 원인을 조사하고 그 지표를 작업자 완료 보고마다 확인.
- 수정 임계점·중단 검토 조건 → 다음 Wave를 시작하지 않고 사용자에게 보고한다(지표·값, plan.md 행동 표의 다시 채점할 후보·범위 조정안 또는
/athena --mode kill). 끝난 Wave의 작업자 증거는checklist-status.md에 반영하고 멈춘다. "다음 Wave에서 고치면 오를 것" 같은 이유로 단계를 낮추거나 진행을 결정하지 않는다 — 결정은 판정자(사람)가 한다. - 초기 신호 이상·데이터 없음이면 plan.md
#### 발동 기록(자유 모드: activity log## Tripwires)에 한 줄 덧붙인다. Lead만 쓰고 그 절 밖은 고치지 않는다(판정자가 확정한 재보정 값을 조건 표에 옮기는 것만 예외). 이미 닿은 단계는 재보정으로 없애지 않는다.
질문할 수 없는 호출자(제우스)에서는 3 대신 호출자 규칙을 따른다 — 제우스는 [ZEUS-AUTO:taste] 결정 장부에 기록하고 계속한다. 4의 발동 기록은 그대로 남긴다.
Step 6: Verify Results — 완료 기준 장부 대조
See verification-protocol.md
checklist-status.md의 모든 행이proved가 될 때까지 반복한다.
검증 루프:
while (checklist-status.md에 proved가 아닌 행 존재):
1. 파일 존재 검증 (Files to Create/Modify 전수 확인) ← 사전 점검
2. AC 대조 — 작업자 보고 증거를 확인해 장부 갱신 (코드 존재만이면 weak) ← 사전 점검
3. 도면 노드 검증 (flow-diagrams 존재 시) ← 사전 점검
4. 파일 소유권 검증 (0단계 기준점 대비 변경 ↔ 섹션 소유 ↔ 작업자 보고) ← 사전 점검
4b. 경계면 정합성 교차 비교 (웹앱: API 응답 shape↔훅 타입·경로↔href·엔드포인트↔훅 1:1 / 비웹: 해당 경계 / 없으면 skip) ← 사전 점검, verification-protocol.md 4.5단계
5. 통합 게이트 (유일한 완료 권한): 병합 결과에 빌드/타입체크 + 전체 테스트 1회 — 1~4b는 사전 점검일 뿐, 이 게이트 통과로만 완료 (자동 PASS 금지). 상세 verification-protocol.md 5단계
6. 통합 게이트 뒤 proved 행의 증거를 한 번 더 확인 (그 사이 관련 코드가 바뀐 행은 weak로 내리고 재확인)
미통과 → 해당 teammate에 재지시 → 대기 → 재검증 (최대 2회)
2회 후에도 미통과 → 사용자에게 보고 + 수동 개입 요청 (통과로 보고하지 않음 — 소진=미완)
완료 계약 (028): Acceptance Criteria 대조는 이분(통과/미통과)이 아니라 proved/weak/missing/contradicted로 채점해 장부에 기록한다. 코드는 있으나 동작 증거가 약한 항목은
weak로 따로 잡아, "파일 존재 = 완료"로 둔갑시키지 않는다.
Step 7: Activity Log Summary
모든 Wave 완료 후:
conversations/{YYYY-MM-DD}-team-poseidon.md읽기- teammate별 활동 통계 집계 (기록 수, 에러 수, 파일 수)
- source-only
orchestrator모듈과 MCP command를 성공적으로 읽고 실제 폴백을 시작한 경우에만orchestrator_get_activity_log로 JSONL 로그 확인. 선택하지 않았거나 로드 실패면MCP: NOT SELECTED/NOT RUN으로 기록 - 요약을 Final Report에 포함
Step 8: Final Report
═══════════════════════════════════════
포세이돈: 실행 완료
═══════════════════════════════════════
📋 완료 기준 (checklist-status.md): M/N proved (XX%) — 남은 ID: …
📐 도면 매칭: K개 노드 중 J개 구현 (YY%)
⏱️ 총 Wave: W개 | 검증 루프: R회
트립와이어: {Wave별 판정 — 계속/초기 신호/수정/중단 검토, 발동 지표·값 | NOT APPLICABLE}
내부 모듈: code-reviewer {LOADED|NOT RUN} | orchestrator MCP {NOT SELECTED|LOADED|NOT RUN}
섹션별 결과:
✅ section-01-foundation — 체크 3/3, 파일 3개
⚠️ section-03-api — 체크 4/5 (테스트 1건 미통과)
Lead 의사결정 로그: conversations/{date}-team-poseidon.md
═══════════════════════════════════════
실패 섹션의 재시도·메인 순차 폴백은 남은 동일 실패 예산 안에서만 수행합니다. 최종 보고 단계가 추가 시도권을 만들지 않습니다. 상한을 소진하면 미완료와 실패 근거를 보고합니다. Zeus 호출도 같은 상한을 따르며, 실패 섹션을 성공으로 표시하지 않습니다.
vs orchestrator
| 측면 | agent-team (이 스킬) | orchestrator (기존) |
|---|---|---|
| 설치 | 불필요 (4-CLI 네이티브 내장 — 구버전만 env var) | MCP 서버 빌드 필요 |
| 지원 CLI | Claude + Codex + Antigravity + Grok (네이티브) | 네이티브 멀티에이전트가 없는 구버전 CLI |
| 파일 충돌 방지 | 소유권 규칙 (soft) | MCP lock_file (hard) |
| 태스크 관리 | CLI별 네이티브 도구 | orchestrator MCP 도구 |
| 사용 조건 | zephermine 섹션 또는 자유 모드 | 폴백 또는 hard lock 필요 시 |
공존 원칙 (native-first): 실행은 항상 네이티브 우선. orchestrator는 ① 네이티브 멀티에이전트가 없는 구버전 CLI 폴백, ② hard file lock·크로스 CLI task ledger가 꼭 필요한 대규모 동시 편집 — 이 두 경우에만 정책 레이어로 사용.
Logging Format
═══════════════════════════════════════════════════════════════
STEP {N+1}/9: {STEP_NAME} (Step 0~8, 총 9단계)
═══════════════════════════════════════════════════════════════
{details}
Step {N} complete: {summary}
───────────────────────────────────────────────────────────────
표시 예: Step 0 →
STEP 1/9, Step 8 →STEP 9/9
Error Handling
| 상황 | 대응 |
|---|---|
| SECTION_MANIFEST 파싱 실패 | 사용자에게 index.md 형식 확인 요청 |
| 순환 의존성 발견 | 경고 출력 + 관련 섹션 목록 표시 |
| teammate 상태 변화 없음 | 런타임 상태와 담당 파일·테스트 증거 확인 → 작업 범위를 줄여 1회 재위임; permission mode는 변경하지 않음 |
| teammate/agent 실패 | 오류와 부분 변경을 확인 → 남은 동일 실패 예산 안에서 1회 재위임 또는 메인 순차 폴백. 소진 시 미완료 보고 |
| 파일 충돌 감지 | 두 teammate/agent가 같은 파일 수정 → Lead가 merge 또는 사용자에게 보고 |
| 컨텍스트 압축·한도 대응 | 실행 ID에 연결한 로그를 갱신하고 네이티브 재개. 실제 세션 교체가 필요할 때만 작업자를 안전하게 중단하고 로그 절대경로·다음 행동을 인계 |
| Codex spawn 실패 | 현재 세션의 multi-agent 가용성·thread cap·sandbox를 확인 → 범위를 줄여 재시도; 승인 우회 금지 |
| Codex wait 타임아웃 | 현재 interrupt 도구로 중단 → 부분 변경 확인 → 범위를 줄여 재spawn |
| Antigravity 에이전트 미인식 | TUI /agents와 현재 도구 목록으로 확인 → invoke_subagent가 없으면 Wave 내 메인 컨텍스트 순차 실행; hard lock 등이 필수일 때만 source-only resolver를 거친 orchestrator MCP 분기 |
| spawn_subagent 실패 (Grok) | grok inspect --json으로 네이티브 서브에이전트 레지스트리 확인 → 재spawn 1회 → 실패 시 사용자 보고 |
| 재시도 후에도 실패 | 남은 동일 실패 예산이 있으면 메인 순차 실행, 소진했으면 추가 실행 없이 미완료 보고 |
작업자 정리
모든 Wave 완료, 중단, 컨텍스트 한도 도달 시 현재 런타임이 제공하는 정상 종료·중단 절차를 사용합니다.
- Claude 2.1.178+: implicit team이므로
TeamDelete를 호출하지 않습니다. 실행 중 named teammate에 shutdown을 요청하고 세션 정리는 런타임에 맡깁니다. - Codex: 실행 중 thread만 현재 interrupt/stop 기능으로 중단합니다. 완료 thread의 정리는 런타임 UI나 현재 제공 기능을 따릅니다.
- Antigravity/Grok: 호출 단위 child가 반환되면 별도 팀 정리가 없습니다.
- 어떤 CLI에서도 런타임 상태 디렉터리를 수동 삭제하지 않습니다.
1. 실행 중 작업자 목록 확인
2. 필요한 결과가 회수됐는지 확인
3. 실행 중 작업자에 정상 종료 또는 interrupt 요청
4. Lead의 Wave ledger와 activity log를 최종 저장
다음 단계 안내
✅ 에이전트팀 구현 완료!
📊 결과: {통과/실패 요약}
👉 다음 단계 (선택):
/argos → 감리 (설계 대비 구현 검증, Phase 0~6)
/aphrodite → 디자인 정교화 (design-system.md가 있는 UI 프로젝트)
/minos → Playwright 자동 테스트 + Healer 루프
/review → 코드 리뷰 (품질/보안/성능)
/commit → 변경사항 커밋
📎 참고: docs/workflow-guide.md
References
| 파일 | 내용 |
|---|---|
| artifacts-review.md | Step 0 산출물 검토 상세 절차, 영향도 분석, 보조 문서 매핑 |
| section-parser.md | SECTION_MANIFEST 파싱 규칙, 도면 매핑 추출 |
| expert-matching.md | 섹션 파일 패턴 → 프로젝트 기반 구현 컨텍스트 매칭 |
| wave-executor.md | Wave 실행 사이클, teammate 지시 형식, 모니터링 루프, Codex agent 형식 |
| teammate-context-template.md | teammate/agent 프롬프트 전체 템플릿 |
| verification-protocol.md | 검증 5단계, 재시도 프로세스, 통과 기준 |