Planning

Planning Protocol

Overview

Define how to analyze context, make design decisions, and decompose work into tasks.

Two modes:

• Interactive: Orchestrator conducts Deep Interview for decisions
• Auto: Planner agent makes decisions based on context alone (--auto or --skip-interview)

Phase 1: Read Context

Read session files in order:

1. session.json - goal and metadata
2. context.json - summary, key files, patterns from explorers
3. exploration/*.md - detailed findings as needed

Phase 2: Complexity Analysis

Analyze goal and context to determine interview depth:

Note: User can request more rounds via adaptive check. No upper limit.

Phase 3: Deep Interview (Interactive Mode)

Skip if: --auto or --skip-interview flag set

Interview Structure

Each round asks 4-5 questions using AskUserQuestion (max 4 questions per call).

Context-Aware Options (CRITICAL)

Options marked [...] MUST be generated from exploration context, NOT generic templates.

See references/context-aware-options.md for:

• Generation process from context.json and exploration/*.md
• Option generation rules by question type
• Context-aware vs generic examples
• Validation checklist

Data-Driven Interview Questions

Interview questions must be generated from exploration data, not generic templates.

Question Generation Rules

BAD (generic): "어떤 아키텍처 패턴을 사용할까요?" GOOD (data-driven): "graph/service.go가 2곳에서 사용됩니다. 두 곳 모두 동시에 변경할까요?"

Formula: [탐색에서 발견한 사실] + [그로 인한 설계 선택지] + [각 선택지의 trade-off]

Interview Question → Design Section Mapping

Interview Rounds

Rounds are adjusted based on complexity assessment:

Note: User can request additional rounds via adaptive check. No upper limit.

See references/interview-rounds.md for:

• Detailed question templates for each round
• Domain-specific question templates
• Adaptive check pattern
• Decision recording format

Phase 4: Document Design

IMPORTANT: Design documents go to PROJECT directory.

WORKING_DIR=$(bun $SCRIPTS/session-get.js --session ${CLAUDE_SESSION_ID} --field working_dir)
DESIGN_PATH="$WORKING_DIR/docs/plans/$(date +%Y-%m-%d)-{goal-slug}-design.md"

Write comprehensive design.md including:

• Overview and approach selection
• Interview decisions with rationale (from Phase 3)
• Architecture and components
• Error handling strategy
• Testing strategy
• Scope (in/out)

See references/design-template.md for complete template.

Self-Containedness Check

After writing the design document, the planner performs a self-containedness check:

• Context Orientation만 읽고 이 프로젝트가 뭔지 알 수 있는가?
• 모든 Criterion에 실행 명령과 기대 출력이 있는가?
• Impact Analysis의 모든 소비자에 대한 처리 방안이 있는가?
• 문서에 없는 결정을 worker가 내려야 하는 상황이 있는가?
• "기능 동일", "정상 동작" 같은 주관적 표현이 없는가?

If any check fails, fix the design document before proceeding to Codex doc-review.

Phase 4.5: Codex Doc-Review

After writing the design document, validate it via Codex doc-review.

bun $SCRIPTS/codex-verify.js \
  --mode doc-review \
  --design "$DESIGN_PATH" \
  --goal "${GOAL}" \
  --output /tmp/codex-doc-${CLAUDE_SESSION_ID}.json

Result Handling:

Retry Budget

Convergence Detection

Track error counts across attempts to detect trends:

• Converging: Error count decreasing across attempts (fixes are working)
• Oscillating: Error count fluctuating up and down (fixes introduce new issues)
• Diverging: Error count increasing across attempts (fixes make things worse)

On each FAIL, record the error count from doc_issues. Compare with previous attempts:

Attempt 1: 5 errors
Attempt 2: 3 errors  → converging (continue)
Attempt 3: 4 errors  → oscillating (warn, continue)
Attempt 4: 2 errors  → converging (continue)
Attempt 5: 2 errors  → stalled (max retries reached → auto-pass)

Interactive Mode (default)

1. Show doc_issues to user via AskUserQuestion
2. User confirms fix direction
3. Edit design document
4. Re-run doc-review
5. Track convergence: compare error count with previous attempt
6. Repeat until PASS, user skips, or max retries (5) reached
7. On max retries → execute auto-pass protocol

Auto Mode (--auto)

1. Read doc_issues from result
2. Auto-fix design document
3. Re-run doc-review
4. Track convergence: compare error count with previous attempt
5. Repeat until PASS or max retries (3) reached
6. On max retries → execute auto-pass protocol

Auto-Pass Protocol

When max retries reached without achieving PASS:

1. Run codex-autopass.js --session ${CLAUDE_SESSION_ID}
2. Script creates a PASS result file at /tmp/codex-doc-${CLAUDE_SESSION_ID}.json
3. Append a "Known Doc-Review Issues (Auto-Passed)" section to the design document listing unresolved issues
4. Proceed to Phase 5 (Task Decomposition)

The auto-pass section in the design document serves as a record that doc-review did not fully pass, allowing workers and verifier to be aware of known gaps.

CLI Error: Retry once on execution failure. On repeated failure, report to user.

Note: A PreToolUse gate blocks session-update.js --phase EXECUTION without a passing Codex doc-review result at /tmp/codex-doc-${CLAUDE_SESSION_ID}.json.

Phase 5: Decompose Tasks

Write Execution Strategy (Post-Review)

After doc-review passes, add the Execution Strategy section to the design document. This section was intentionally excluded from the initial design to allow doc-review to validate the pure design first.

See references/design-template.md for the Execution Strategy (Post-Review) template.

Task Guidelines

Create Tasks with Scripts

Use task-create.js for each task. Always include a final verify task.

See references/task-examples.md for:

• Complete script command examples
• Task decomposition patterns by feature type
• Dependency graph examples

Output Summary

Return planning summary with:

• Complexity assessment and interview rounds completed
• Key decisions from interview (table format)
• Task graph showing IDs, subjects, dependencies, complexity
• Files created (design doc, task files)

Flag Reference

Additional Resources

Reference Files

• references/brainstorm-protocol.md - Interactive question flow and approach exploration
• references/context-aware-options.md - Context-aware option generation rules and examples
• references/design-template.md - Complete design document template
• references/interview-rounds.md - Detailed interview round templates for all complexity levels
• references/task-examples.md - Task decomposition examples with script commands

Converted and distributed by TomeVault — claim your Tome and manage your conversions.