Zephermine

Zephermine

Zephyr(제퍼: 산들바람/서풍, 부드럽고 빠른 흐름) + Minerva(미네르바: 지혜·전략·판단)의 합성어. 바람처럼 가볍고 빠르게 상황을 읽고, 미네르바처럼 논리적으로 설계해 실행 가능한 계획으로 만드는 능력을 뜻합니다. softaworks/gepetto 스킬을 벤치마킹하여 커스터마이징한 버전입니다.

Orchestrates a multi-step planning process: Research → Interview → Spec Synthesis → Team Analysis → Plan → External Review → Sections → Verify

네이티브 plan mode와의 구분: 현재 CLI가 제공하는 plan mode는 "이 작업을 어떻게 구현할까"를 다루는 단일 작업용 계획 승인 게이트이고, 젭마인은 다운스트림(포세이돈·아르고스·미노스·제우스·견적)이 소비하는 디스크 아티팩트(plan.md, sections/, flow-diagrams/, qa-scenarios)를 만드는 설계 파이프라인입니다. 단일 버그픽스·소규모 리팩토링은 plan mode, 기능/제품 단위 설계는 젭마인. Antigravity에서는 가벼운 구현 계획은 /plan, 누락 요구를 집중 인터뷰로 좁히는 일은 /grill-me가 먼저입니다. 그 결과만 필요하면 젭마인을 시작하지 않습니다. spec.md, 도메인 사전, API/DB, flow, sections, operation/QA 시나리오까지 디스크에 남겨 downstream이 소비해야 할 때만 젭마인을 사용합니다. slash command를 프로그램적으로 호출한다고 가정하지 않으며, 현재 plan mode가 쓰기·승인 전용이면 그 안에서 젭마인을 실행하지 않습니다. 사용자가 만든 네이티브 계획·인터뷰 결과는 쓰기 가능한 모드에서 입력으로 이어받습니다.

CRITICAL: First Actions

BEFORE anything else, do these in order:

1. Print Intro

간결하게 진행 순서만 출력:

젭마인(Zephermine) 시작
순서: Research → Blindspot → Interview → Spec(+Domain Dictionary v1) → Persona/Journey → Team Review(+Dictionary v3) → Plan → External Review → DB Schema → API Spec → Flow Diagrams → Sections → Operation Scenarios → QA Scenarios → Skill Discovery

2. Resolve Spec File Path

Check if user provided @file at invocation AND it's a spec file (ends with .md).

경로가 제공된 경우: 그대로 사용

경로가 없는 경우: 사용자 대화에서 주제를 추론하여 자동 경로 생성 후 바로 진행:

1. 대화 컨텍스트에서 기능/프로젝트명 추출 (예: "UI 재설계" → ui-redesign)
2. 기본 경로 패턴: docs/plan/{feature-name}/spec.md
3. 사용자에게 경로만 간단히 확인:

   계획 경로: docs/plan/ui-redesign/spec.md
   이 경로로 진행합니다. (변경하려면 알려주세요)
   

4. 확인을 기다리지 않고 바로 다음 단계 진행 (사용자가 변경 요청하면 그때 수정)

주제를 추론할 수 없는 경우에만 간단히 질문:

어떤 기능을 계획할까요? (예: "로그인 리팩토링", "결제 시스템")

3. Setup Planning Session

Determine session state by checking existing files:

1. Set planning_dir = parent directory of the spec file

2. If planning_dir doesn't exist, create it automatically

3. Archive 기존 산출물 — planning_dir이 이미 존재하고 spec.md가 있는 완료된 계획이면:

   a. {planning_dir}/archive/ 디렉토리 생성 (없으면)
   b. 기존 파일 전체 → {planning_dir}/archive/{YYYY-MM-DD-HHMM}/ 로 이동 (Bash mv)
      - archive/ 폴더 자체는 이동하지 않음
   c. planning_dir을 클린 상태로 시작
   

   resume 모드일 때는 archive 하지 않음 — 이어서 작업할 때는 기존 파일을 유지. 사용자가 "새로 시작"이라고 명시하거나, 모든 단계가 완료된 상태에서 재실행할 때만 archive.

4. Set initial_file = the spec file path

5. If spec file doesn't exist, create an empty template:

   # Feature Spec
   
   ## Overview
   [Describe what you want to build]
   
   ## Requirements
   - [Requirement 1]
   - [Requirement 2]
   

6. Scan for existing planning files (research-decision.md, research.md, research/, unknowns.md, interview.md, spec.md, team-review.md, domain-dictionary-delta.md, plan.md, api-spec.md, db-schema.md, integration-notes.md, design-system.md, operation-scenarios.md, qa-scenarios.md, team-reviews/, reviews/, flow-diagrams/, sections/)

   마스터 사전(docs/domain-dictionary.md)은 프로젝트 단일이므로 planning_dir 스캔에서 제외. planning_dir에는 변경 이력 델타만 보관.

7. Import upstream artifacts — 사전 파이프라인 산출물이 있으면 컨텍스트로 로드:

   • docs/athena/*.md (excluding archive/) → Athena Go/No-Go 판정, 스코프 조정, MVP 범위
   • docs/hermes/*.md (excluding archive/) → Hermes 사업 분석 (BMC, TAM/SAM, GTM)
   • 있으면: interview-protocol.md Phase C의 기정 사실(given context)로 활용, 사업 관련 질문 생략
   • 없으면: 무시하고 정상 진행

8. Determine mode and resume point:

도메인사전 Resume 보정 규칙 (위 테이블과 별도, Resume 시 항상 점검):

판정 방법: <planning_dir>/domain-dictionary-delta.md의 ## v1 → v2, ## v2 → v3 섹션 존재 여부로 진행 단계 추정. 델타가 없으면 마스터 사전이 어떤 버전인지 모르므로 안전하게 v1부터 다시 실행.

이 보정은 사용자가 Resume할 때 사전이 누락된 채로 다음 Phase가 진행되는 것을 막습니다. Resume에서 Step 8/10/11의 사전 부산물을 보정하기 전에도 전역 카탈로그에서 domain-dictionary 모듈을 다시 해석합니다. 이전 세션이 기록한 경로나 런타임 등록 상태를 그대로 신뢰하지 않으며, 모듈을 읽지 못하면 보정 Step을 BLOCKED로 둡니다.

9. Create or update the current runtime's task ledger from the detected state. Use a native task-list tool only when the runtime exposes one; otherwise record the remaining steps in the planning index and continue without inventing a vendor-specific tool call.

Print status:

Planning directory: {planning_dir}
Mode: {mode}

If resuming:

Resuming from step {N}
To start fresh, delete the planning directory files.

Logging Format

═══════════════════════════════════════════════════════════════
STEP {N}/26: {STEP_NAME}
═══════════════════════════════════════════════════════════════
{details}
Step {N} complete: {summary}
───────────────────────────────────────────────────────────────

Question Tool Compatibility

Question tools differ by CLI. To avoid Invalid tool parameters, use plain text numbered questions by default.

• Use structured question tools only for short bounded choices.
• Structured calls must use max 3 questions per call, and each question should have 2-3 short options.
• Do not send open-ended interview prompts through a structured question tool.
• Do not use structured multi-selection fields unless the current CLI explicitly supports them. Otherwise, show a numbered checklist and ask the user to answer with multiple numbers.
• If a structured question tool fails once, immediately fall back to plain text and do not retry the same payload.

Default no-stop policy:

• Do not ask preference questions that can be inferred from the spec, codebase, research, or existing project conventions.
• Ask only when the answer could materially change architecture, data model, security boundary, UX flow, rollout strategy, legal/compliance handling, or an irreversible external action.
• If the question is non-blocking, choose the conservative default, mark it as [inferred] in the relevant artifact, and continue.
• Put non-blocking uncertainty in unknowns.md, interview.md, integration-notes.md, or the final Open Questions section instead of stopping the workflow.

This applies most strongly to Step 6 critical unknowns, Step 11 unresolved domain/dictionary conflicts, and Step 15 only when the user explicitly requested a review gate.

Native Delegation Contract

Use semantic roles instead of hardcoded tool calls, agent files, or models:

• Every delegated work item must have either one unique output file or a return-only contract.
• Main/Lead owns shared state and integration artifacts, including research.md, team-review.md, plan.md, integration-notes.md, domain dictionaries, manifests, and indexes.
• Workers must not edit another worker's output or shared state. Main/Lead reads completed outputs and performs all merges.
• If native delegation is unavailable, execute the same bounded work items sequentially in the main context. Preserve the same output ownership and budgets.
• Use the runtime's configured default model. Do not hardcode model names in delegation instructions.

Source-only internal module resolution (mandatory)

domain-dictionary, flow-verifier, mermaid-diagrams, 조건부 frontend-design은 젭마인 내부 단계가 읽는 source-only 모듈입니다. 사용자 호출용 스킬이나 등록된 slash command로 실행하지 않습니다.

각 모듈을 다음 우선순위로 해석하고, 처음 확인된 정확한 SKILL.md 파일 하나를 사용합니다.

1. 현재 프로젝트에 skills/{name}/SKILL.md가 실제로 있으면 그 exact 파일을 읽습니다 (소스 저장소 개발 경로).
2. 없으면 현재 런타임 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 설치 지원).
3. 둘 다 없으면 현재 런타임의 전역 카탈로그를 엽니다: 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 아래여도 경로를 조합하거나 추측하지 않습니다.
4. module_root는 읽은 SKILL.md의 부모 디렉터리입니다. 모듈이 지시하는 references/, scripts/, commands/는 모두 이 루트에서만 해석합니다.
5. 모듈은 소비 단계에 도달했을 때만 지연 로드합니다. Step 8/10/11은 domain_dictionary_root, Step 18은 flow_verifier_root와 mermaid_diagrams_root를 사용합니다. UI design-system 분기에서만 frontend_design_root를 사용합니다.

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

사전과 도면의 세 소비 경로는 설계 산출물의 필수 계약입니다. exact 파일, 카탈로그의 유일한 행, 읽을 경로, 필수 reference 중 하나라도 없거나 읽을 수 없으면 해당 Step을 BLOCKED: source module unavailable로 기록하고 중단합니다. placeholder 사전·도면·인덱스를 만들어 통과시키거나 다음 Step을 PASS 처리하지 않습니다. 핵심 용어 수처럼 모듈 계약 자체가 허용한 비적용 조건만 NOT APPLICABLE로 기록할 수 있으며, 모듈 미발견을 비적용으로 바꾸면 안 됩니다.

frontend-design은 UI design-system 분기의 보조 모듈입니다. 해석 실패 시 이 가이드의 bounded anti-slop 규칙만 적용하고 frontend-design: NOT RUN (native fallback)을 기록합니다. fallback을 모듈 PASS로 표시하지 않습니다.

Workflow

26단계는 6 Phase로 그룹화됩니다. 5A. Blindspot Pass는 Step 5와 6 사이의 보조 단계이며, 기존 Step 번호는 변경하지 않습니다. Phase는 단순 라벨이며 다른 스킬이 "Phase X 후 호출"로 참조할 때 사용합니다.

도메인사전은 Step이 아니라 Step의 부산물입니다. Step 8 끝에서 v1 초안, Step 10 끝에서 전문가 입력으로 v2 자동 병합, Step 11 끝에서 충돌만 확인하고 v3 확정. 별도 단계가 추가되지 않으며, 각 Step 본문 끝의 평범한 단락으로 처리됩니다.

Phase 1: Discovery

리서치와 인터뷰로 도메인을 파악하는 단계.

4. Research Decision

See research-protocol.md.

1. Read the spec file
2. Extract potential research topics (technologies, patterns, integrations)
3. Auto-select research scope from the spec, local repo, and risk level
4. Ask only if the research choice changes scope/cost/compliance and no conservative default exists
5. Record selected and skipped research types in <planning_dir>/research-decision.md

5. Execute Research

See research-protocol.md.

Based on decisions from step 4, launch bounded artifact-writer work items:

• Codebase: one writer → <planning_dir>/research/codebase.md — 요청 기능이 이미 구현됐는지 먼저 확인(codemap/index.md → 핵심어 grep → README/docs). 이미 있으면 신규 설계가 아니라 개선으로 분류해 spec/plan 머리에 "기존: {위치}/{경계}" 명시(재구현 방지).
• GitHub/Web/Academic/Competitor: one writer and one unique file per research type under <planning_dir>/research/; use web search only where available
• Concurrency cap: max 2 research work items at a time; if API Error: Overloaded/rate limit occurs, retry the failed item once with concurrency 1 and half budget

Writers return only 1-2 line summaries. Main/Lead combines <planning_dir>/research/*.md → <planning_dir>/research.md.

Skip Step 5 only when Step 4 auto-selection finds no useful research target. Record that decision in research-decision.md.

5A. Blindspot Pass

Before the interview, convert research findings into an unknowns map. Write <planning_dir>/unknowns.md with:

• Known knowns: explicit requirements already stated by the user or discovered in existing code/docs
• Known unknowns: decisions the user has not made yet
• Unknown knowns: likely implicit preferences, conventions, taste, or "obvious once seen" expectations
• Unknown unknowns: risks, hidden dependencies, edge cases, domain assumptions, or validation gaps the user may not know to ask about
• Architecture-changing questions: 3-7 questions where the answer could change data models, APIs, security boundaries, UX flow, or rollout strategy

Use unknowns.md to drive Step 6. Ask the highest-impact architecture-changing question first, one question at a time when a single answer could materially redirect the plan. If there are no critical blockers, synthesize inferred answers and continue without a live interview.

6. Detailed Interview

See interview-protocol.md

Run in main context. Informed by: initial spec + research findings + unknowns.md. Use the Question Tool Compatibility and Default no-stop policy above.

7. Save Interview Transcript

Write Q&A or inferred assumptions to <planning_dir>/interview.md. Include Soft Gate summaries even when no live questions were asked.

Phase 2: Spec

Spec과 Persona를 합성하고, 도메인사전 v1 초안을 자동 생성하는 단계.

8. Write Initial Spec (Spec Synthesis)

Combine into <planning_dir>/spec.md:

• Initial input + research findings + interview answers + Test Scenarios

필수 포함: Context Map 섹션 — interview.md의 Soft Gate 1 결과 또는 inferred summary에서 가져옴:

## Context Map

### 공유 전제
- 목표: {궁극적 목표}
- 산업: {산업} | 범위: {MVP/풀/리뉴얼}
- 성공 기준: {성공의 정의}

### 이해관계자
| 역할 | 설명 | 관련 섹션 |
|------|------|-----------|
| {역할} | {설명} | (Step 19에서 backfill) |

### 에코시스템 맵
| 시스템 | 대상 | 연동 방식 | 관련 섹션 |
|--------|------|-----------|-----------|
| {시스템} | {대상} | {내장/외부API/제외} | (Step 19에서 backfill) |

### 기존 환경
{기술 스택, 기존 코드, 인프라 요약}

필수 포함: Problem Statement 섹션 — interview.md의 Soft Gate 2 결과 또는 inferred summary에서 가져옴:

## Problem Statement

| # | 핵심 문제 | 영향 | 우선순위 | 해결 섹션 |
|---|-----------|------|----------|-----------|
| P1 | {문제} | {영향} | 🔴 필수 | (Step 19에서 backfill) |
| P2 | {문제} | {영향} | 🟠 중요 | (Step 19에서 backfill) |

Context Map과 Problem Statement의 '관련 섹션'/'해결 섹션' 열은 Step 19에서 backfill됩니다. 이 두 섹션은 다운스트림(섹션 분할, argos 감리)에서 추적성 검증의 앵커로 사용됩니다.

필수 포함: Risk Assessment 섹션

조건부 생성: Design System — 인터뷰 Phase S-1(디자인 비전)이 수집되었거나 spec/research/unknowns에서 추론 가능한 경우: See design-system-guide.md UI 분기에 진입하면 위 resolver로 frontend-design을 지연 해석해 frontend_design_root를 만들고, 가이드가 지정한 blacklist reference를 그 루트에서 읽습니다. <planning_dir>/design-system.md 생성. UI/프론트엔드가 없는 프로젝트는 NOT APPLICABLE로 기록합니다.

필수 포함: Test Scenarios 섹션 — 각 주요 기능마다 정상/에러/엣지 케이스. See test-scenario-guide.md

Step 8 끝부산물 — 도메인사전 v1 초안 생성 (사용자 개입 없음): spec.md 작성 직후 위 resolver로 domain-dictionary 행의 정확한 SKILL.md를 읽고, ${domain_dictionary_root}/references/global-sync.md를 읽은 뒤 컨텍스트 모드 계약을 직접 수행합니다. 등록 스킬 또는 이름 기반 slash command를 호출하지 않습니다. 입력은 spec.md + interview.md입니다. 글로벌 사전(~/.agent-memory/domain-dictionaries/{도메인}.md, AGENT_DOMAIN_DICTIONARY_HOME override 가능)이 있으면 명확히 맞는 후보 용어만 자동 시드하고, 애매한 후보는 [inferred-skip]로 델타에 기록합니다. 글로벌이 비어있으면 사용자 개입 없이 프로젝트 사전만 만듭니다. 산출물은 마스터(docs/domain-dictionary.md, 신규 또는 갱신)와 델타 (<planning_dir>/domain-dictionary-delta.md)입니다. 모듈을 성공적으로 읽은 뒤 핵심 용어가 5개 미만이면 계약에 따라 NOT APPLICABLE: fewer than 5 core terms를 델타에 기록하고 진행합니다. 모듈을 읽지 못한 상태는 건너뛰기가 아니라 위의 BLOCKED입니다.

9. User Persona & Journey Map

See persona-journey-guide.md

인터뷰와 리서치 결과를 기반으로 페르소나(2~4개)와 여정맵 생성. UI/프론트엔드가 없는 프로젝트는 자동 건너뜀.

출력: <planning_dir>/personas-and-journeys.md

Phase 3: Domain

전문가 분석으로 도메인을 깊이 이해하고, 사전을 v3까지 확정하는 단계.

10. Multi-Expert Team Analysis

See team-review-protocol.md

⚠️ CONTEXT MANAGEMENT: This step runs 6 bounded work items. Consider /compact before launching.

Default execution profile: time-boxed standard mode. Deep domain research runs only when the feature is clearly domain-heavy (regulated industry, safety-critical workflow, payment/medical/finance/logistics/manufacturing integrations) or the user explicitly asks for deep research.

Phase A — 4개 병렬: UX / Architecture / Red Team / Domain Research

• Domain Researcher first performs domain-complexity triage.
• Low-complexity projects write a short domain-research.md stub without web search.
• Medium/high-complexity projects use bounded, non-duplicative research only. Do not redo Step 5.

Phase B — 2개 병렬 (Phase A 완료 후): Domain Process Expert / Domain Technical Expert

• Domain experts do not perform fresh web research by default.
• They synthesize spec.md, interview.md, research.md, domain-research.md, and docs/domain-dictionary.md.
• External AI domain experts are time-boxed; timeout/failure falls back to the runtime's artifact-writer, then to sequential main-context execution or a warning stub.

Phase B 실행: Codex/Antigravity 외부 CLI가 가용하면 분배하고, 없거나 실패하면 현재 CLI의 artifact-writer 역할로 실행합니다.

CRITICAL — Work-item return protocol: Each writer owns one unique file and returns ONLY a 2-3 line summary. Main/Lead alone writes team-review.md and dictionary merges.

도메인사전 컨텍스트 주입: 6명 전문가 모두에게 Step 8에서 생성된 사전 v1을 컨텍스트로 전달합니다. 전문가들은 같은 어휘로 분석하며, 분석 중 발견한 신규 용어/정의 다듬음/모호성을 결과물 끝 ## Dictionary Updates 섹션에 기록합니다. 자세한 프롬프트는 team-review-protocol.md 참조.

Results → <planning_dir>/team-reviews/ (개별 6개) + <planning_dir>/team-review.md (통합).

Step 10 끝부산물 — 도메인사전 v2 자동 병합 (사용자 개입 없음): Step 8에서 읽은 domain-dictionary 계약을 유지한 상태에서 6개 전문가의 ## Dictionary Updates 섹션을 추출하여 v1 → v2로 자동 병합. ADD(신규 추가)/REFINE(정의 다듬음)/MERGE(동의어 통합)는 자동 적용, CONFLICT(전문가 간 의견 갈림)는 자동 병합하지 않고 Step 11로 미룸. 갱신 대상: docs/domain-dictionary.md + <planning_dir>/domain-dictionary-delta.md.

11. Domain Conflict Resolution and Dictionary Finalization

See domain-confirmation-guide.md

Step 11은 자동 통합이 기본입니다.

일반 도메인 전문가 제안, ADD/REFINE/MERGE 사전 변경, 명확한 글로벌 사전 후보는 보수적 기준으로 자동 채택 또는 보류하고 이유를 기록합니다. 사용자에게 묻는 경우는 다음뿐입니다.

1. 충돌 용어 — DB/API/타입/화면 문구에 들어갈 핵심 용어가 둘 이상으로 갈리고, 자동 통일이 이후 산출물을 크게 바꿀 때
2. 정책성 제안 — 보안, 개인정보, 결제, 법적 책임, 운영 프로세스를 바꾸는 제안일 때
3. 글로벌 사전 반영 — 전역 사전에 쓰기 작업을 해야 하는데 프로젝트 특수 용어인지 범용 용어인지 판단이 불가능할 때

질문이 필요하면 한 번에 하나만 묻습니다. 그 외 항목은 accepted-by-default, deferred-by-default, inferred-skip 중 하나로 <planning_dir>/domain-dictionary-delta.md와 team-review.md에 기록하고 계속 진행합니다.

Step 11 끝부산물 — 도메인사전 v3 최종화: 로드한 domain-dictionary 계약에 따라 마스터(docs/domain-dictionary.md)를 v3로 확정, 델타에 최종 변경 이력 기록, 글로벌 반영 항목은 출처 메타데이터와 함께 추가합니다. 전역 쓰기가 애매하면 전역 반영을 건너뛰고 프로젝트 사전만 확정합니다.

Phase 4 이후로 이 사전은 변경되지 않습니다. Plan, DB Schema, API Spec, Sections는 모두 v3을 따릅니다.

Phase 4: Plan

전략 후보 비교·선택 → 상세 구현 계획 수립 + 외부 LLM 리뷰 + 사용자 검토 단계.

12. Generate Implementation Plan (전략 후보 비교 → 선택 → 작성)

Inputs: spec.md + team-review.md + domain-process-analysis.md + domain-technical-analysis.md

단일 계획을 선형으로 바로 쓰지 않는다. 넓은 설계 결정은 후보를 만들어 채점한 뒤 고른다(Tree of Thoughts). plan.md 하나를 바로 쓰면 외부 리뷰(Step 13)는 "그 하나"를 다듬을 뿐, 더 나은 접근 자체를 놓친다.

12a. 전략 후보 2-3개 생성 — 서로 다른 접근이어야 한다(동일 계획의 변주 금지). 예: 점진적 스트랭글러 vs 빅뱅 재작성, 모놀리식 우선 vs 모듈 경계 우선, 자체 구현 vs 외부 의존. 분기의 독립성을 위해 return-only read-only-analysis 작업으로 각 후보를 생성하는 것을 권장(앵커링 방지). 각 후보는 6-10줄 개요: 핵심 접근, 주요 컴포넌트, 시퀀싱, 가정. Main/Lead만 후보를 채점·통합하고 plan.md를 작성합니다.

12b. 루브릭 채점 — 후보를 아래 기준으로 1-5점 채점(표로 출력). 감이 아니라 근거 한 줄씩. 채점 없이 후보만 나열하고 끝내지 않는다.

12c. 선택 + 작성 — 최고점 후보를 채택하되, 차점 후보의 더 나은 아이디어는 흡수(graft)한다. 동점이거나 트레이드오프가 첨예하면 그 사실을 명시. 선택한 전략으로 상세 계획을 작성 → <planning_dir>/plan.md. Address all "Critical Findings", Step 11에서 채택된 항목만 반영. Write for an unfamiliar reader — fully self-contained document.

plan.md 필수 머리 섹션 — ## 전략 선택 (Strategy Decision): 채택 전략 + 채점표 + 기각한 후보와 사유 + (해당 시) 남은 트레이드오프를 기록한다. 이는 외부 리뷰(Step 13)·감리(argos)가 "왜 이 접근인가"를 검증하는 앵커이며, 후속 세션이 결정을 되짚을 수 있게 한다.

13. External Review

See external-review.md

Run the Antigravity and Codex external CLI review processes in parallel when available. Treat them as independent review processes, not native delegation workers. Each process writes only its unique file under <planning_dir>/reviews/; Main/Lead owns feedback integration and all edits to plan.md.

14. Integrate External Feedback

Analyze <planning_dir>/reviews/. You are the authority on what to integrate.

1. Write <planning_dir>/integration-notes.md (통합/미통합 이유 기록)
2. Update <planning_dir>/plan.md with integrated changes

15. Integrated Plan Checkpoint

Do not stop for plan approval by default. Write <planning_dir>/integration-notes.md, update <planning_dir>/plan.md, and continue to Step 16.

Stop here only when:

• the user explicitly asked for a plan review gate before detailed design
• the external reviews expose an unresolved critical contradiction
• the remaining decision would materially change architecture, data model, security boundary, UX flow, rollout strategy, or compliance handling

When stopping is required, ask one plain-text question that names the blocking decision and the recommended default.

Phase 5: Design

DB 스키마, API, 공정 도면, 섹션을 모두 도메인사전 v3에 따라 작성하는 단계.

16. Generate Database Schema

See schema-design-guide.md

Inputs: domain-process-analysis.md + domain-technical-analysis.md + plan.md Output: <planning_dir>/db-schema.md (ERD + DDL + Design Rationale + Index Strategy) Process: DB 감지 → 엔티티 추출 → 관계 분석 → DB 특성 반영 → 정규화 → ERD/DDL/인덱스

DB가 없는 프로젝트(CLI, 라이브러리, 정적사이트)는 자동 건너뜀.

17. Generate API Specification

See api-spec-guide.md

plan.md + db-schema.md에서 API 엔드포인트 추출 → <planning_dir>/api-spec.md 생성. 각 엔드포인트: Method + Path, Request/Response 스키마, Auth, Frontend Caller 포함. API 없는 프로젝트(정적사이트, CLI)는 자동 건너뜀.

18. Generate Process Flow Diagrams (공정 도면) — MANDATORY

See flow-diagrams-guide.md

⚠️ 이 단계는 건너뛸 수 없습니다. 공정 도면이 없으면 다이달로스(workpm)가 기준선 없이 시공하게 됩니다.

Step 18 진입 시 위 resolver로 flow-verifier와 mermaid-diagrams의 정확한 SKILL.md를 모두 읽습니다. plan 모드와 Mermaid 문법 계약을 직접 적용하며 등록 스킬이나 slash command를 호출하지 않습니다. 어느 모듈도 읽지 못하면 Step 18은 BLOCKED이고 Step 19로 진행하지 않습니다.

plan.md + api-spec.md + domain-process-analysis.md에서 핵심 프로세스 추출 → Mermaid flowchart 작성. 각 프로세스를 별도 artifact-writer 작업으로 생성 → <planning_dir>/flow-diagrams/{process-name}.mmd에 저장. Main/Lead만 flow-diagrams/index.md를 작성합니다. 출력: {process-name}.mmd 파일들 + flow-diagrams/index.md

19. Create Section Index

⚠️ GATE CHECK: flow-verifier와 mermaid-diagrams 상태가 모두 LOADED이고 flow-diagrams/index.md가 존재하는지 확인 → 아니면 Step 18로 돌아가거나 BLOCKED 보고.

See section-index.md

Read plan.md. Identify natural section boundaries → create <planning_dir>/sections/index.md. CRITICAL: index.md MUST start with a SECTION_MANIFEST block.

CPS Backfill: SECTION_MANIFEST 생성 후, 반드시:

1. 에코시스템 커버리지 체크 — spec.md의 Context Map → 에코시스템 맵의 모든 시스템이 섹션에서 커버되는지 확인. See section-index.md Ecosystem Coverage Check.
2. spec.md backfill — Context Map의 '관련 섹션' 열과 Problem Statement의 '해결 섹션' 열을 실제 섹션명으로 업데이트.

Phase 6: Validation

섹션 파일 작성, 운영/QA 시나리오, 후속 스킬 발견, 최종 보고 단계.

20. Write Section Files — Parallel Artifact Writers

See section-splitting.md

1. Parse sections/index.md의 SECTION_MANIFEST
2. 의존성 레이어별로 섹션을 묶고, 한 번에 최대 3개 artifact-writer 작업만 병렬 실행. 각 writer는 할당된 섹션 파일 하나만 쓰기
3. Overloaded/timeout이 나면 실패한 섹션만 단일 writer 작업으로 재시도
4. 각 섹션 파일은 완전 자립형 (Background, Requirements, Dependencies, Reference Libraries, Implementation, Test Scenarios, Implementation Strategy, Quality Gate, Risk & Rollback, Acceptance Criteria, Files 포함)

Wait for each batch to complete before launching the next batch.

21. Generate Operation Scenarios — Artifact Writer

See operation-qa-guide.md

출력: <planning_dir>/operation-scenarios.md (역할 정의 + 메뉴별 시나리오 + E2E 시나리오 + 화면 흐름도) 이 파일만 쓰는 artifact-writer로 실행하고, 위임 불가 시 메인 컨텍스트에서 순차 작성합니다.

22. Generate QA Scenarios Document — Artifact Writer

See operation-qa-guide.md

운영 시나리오를 기반으로 QA 테스트 케이스 생성 → <planning_dir>/qa-scenarios.md (메뉴별 테스트 + E2E + 통합 테스트 + Summary) 이 파일만 쓰는 artifact-writer로 실행하고, 위임 불가 시 메인 컨텍스트에서 순차 작성합니다.

23. Final Status

Verify all files were created successfully:

• research-decision.md and unknowns.md (Discovery trace)
• All section files from SECTION_MANIFEST
• spec.md에 ## Context Map과 ## Problem Statement 섹션이 있는지 확인
• Context Map/Problem Statement의 '관련 섹션'/'해결 섹션' 열이 backfill되었는지 확인
• flow-diagrams/*.mmd + flow-diagrams/index.md (필수 — 없으면 Step 18 미실행)
• api-spec.md (API가 있는 프로젝트)
• db-schema.md (DB가 있는 프로젝트)
• design-system.md + personas-and-journeys.md (UI가 있는 프로젝트)
• operation-scenarios.md + qa-scenarios.md
• team-reviews/domain-research.md + domain-process-analysis.md + domain-technical-analysis.md
• docs/domain-dictionary.md + <planning_dir>/domain-dictionary-delta.md, 또는 모듈 계약이 허용한 5개 미만 용어의 명시적 NOT APPLICABLE delta
• 내부 모듈 상태: domain-dictionary, flow-verifier, mermaid-diagrams, 조건부 frontend-design 각각 LOADED/NOT APPLICABLE/BLOCKED 중 하나 (BLOCKED가 있으면 Planning Complete 금지)

24. Output Summary

ZEPHERMINE: Planning Complete

Generated: research-decision/unknowns/research/interview/spec/domain-dictionary/
           personas-and-journeys/team-review/plan/
           api-spec/db-schema/design-system/integration-notes/
           operation-scenarios/qa-scenarios.md
           + team-reviews/ + reviews/ + flow-diagrams/ + sections/

Implementation options:
  A. /agent-team <planning_dir> → 섹션 기반 병렬 구현 (권장)
  B. /chronos <planning_dir>    → 자율 반복 구현 루프
  C. Manual: sections/index.md  → 순서대로 수동 구현
  D. /argos <planning_dir>      → 감리 (설계 대비 구현 검증)

Design (design-system.md가 생성된 경우):
  /aphrodite <planning_dir>     → 디자인 시스템 정교화 (DB 기반 팔레트/폰트/스타일 매칭)

Other options:
  /estimate <planning_dir>      → 개발 견적서 (비용 산정이 필요한 경우)

25. Discover Implementation Skills

1. plan.md와 sections/section-*.md에서 기술 스택 키워드 추출
2. Glob("skills/*/SKILL.md")로 이미 설치된 스킬 확인 + 키워드 매칭
3. 미매칭 주요 키워드(최대 5개): npx skills find "{keyword}"
4. 이미 설치된 관련 스킬 + 새로 설치 가능한 스킬 목록 출력
5. 설치는 묻지 않고 권장 목록만 출력합니다. npx skills add ... 같은 전역 설치 명령은 사용자가 명시적으로 설치를 요청한 경우에만 실행합니다.

검색 결과가 없거나 모든 관련 스킬이 설치되어 있으면 자동 건너뛰기.

26. 감리 안내

✅ 젭마인 설계 완료!

📦 산출물: operation-scenarios.md, qa-scenarios.md, sections/

👉 다음 단계 (선택):
  /aphrodite           → 디자인 시스템 정교화 (design-system.md가 있는 UI 프로젝트에서 권장)
  /agent-team          → 섹션 기반 병렬 구현 (Codex에서는 agent-team-codex로 해석, 권장)
  /chronos             → 자율 반복 구현 루프
  수동 구현             → 직접 코딩
  /argos <planning_dir> → 구현 후 감리 (설계 대비 준공검사)

📎 참고: docs/workflow-guide.md

참고: 검증(감리)은 설계사와 감리의 역할 분리 원칙에 따라 /argos로 독립되었습니다.

References