/multi-plan

description: "Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan."

Plan - Multi-Model Collaborative Planning

Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan.

$ARGUMENTS

---

Core Protocols

• **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language
• **Mandatory Parallel**: Codex/Gemini calls MUST use `run_in_background: true` (including single model calls, to avoid blocking main thread)
• **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude
• **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated
• **Planning Only**: This command allows reading context and writing to `.claude/plan/*` plan files, but **NEVER modify production code**

---

Multi-Model Call Specification

**Call Syntax** (parallel: use `run_in_background: true`):

Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement>
Context: <retrieved project context>
</TASK>
OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "Brief description"
})

**Model Parameter Notes**:

• `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex

**Role Prompts**:

| Phase | Codex | Gemini | |-------|-------|--------| | Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` | | Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |

**Session Reuse**: Each call returns `SESSION_ID: xxx` (typically output by wrapper), **MUST save** for subsequent `/ccg:execute` use.

**Wait for Background Tasks** (max timeout 600000ms = 10 minutes):

TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })

**IMPORTANT**:

• Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout
• If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**
• If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task**

---

Execution Workflow

**Planning Task**: $ARGUMENTS

Phase 1: Full Context Retrieval

`[Mode: Research]`

1.1 Prompt Enhancement (MUST execute first)

**If ace-tool MCP is available**, call `mcp__ace-tool__enhance_prompt` tool:

mcp__ace-tool__enhance_prompt({
  prompt: "$ARGUMENTS",
  conversation_history: "<last 5-10 conversation turns>",
  project_root_path: "$PWD"
})

Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases.

**If ace-tool MCP is NOT available**: Skip this step and use the original `$ARGUMENTS` as-is for all subsequent phases.

1.2 Context Retrieval

**If ace-tool MCP is available**, call `mcp__ace-tool__search_context` tool:

mcp__ace-tool__search_context({
  query: "<semantic query based on enhanced requirement>",
  project_root_path: "$PWD"
})

• Build semantic query using natural language (Where/What/How)
• **NEVER answer based on assumptions**

**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback: 1. **Glob**: Find relevant files by pattern (e.g., `Glob("**/*.ts")`, `Glob("src/**/*.py")`) 2. **Grep**: Search for key symbols, function names, class definitions (e.g., `Grep("className|functionName")`) 3. **Read**: Read the discovered files to gather complete context 4. **Task (Explore agent)**: For deeper exploration, use `Task` with `subagent_type: "Explore"` to search across the codebase

1.3 Completeness Check

• Must obtain **complete definitions and signatures** for relevant classes, functions, variables
• If context insufficient, trigger **recursive retrieval**
• Prioritize output: entry file + line number + key symbol name; add minimal code snippets only when necessary to resolve ambiguity

1.4 Requirement Alignment

• If requirements still have ambiguity, **MUST** output guiding questions for user
• Until requirement boundaries are clear (no omissions, no redundancy)

Phase 2: Multi-Model Collaborative Analysis

`[Mode: Analysis]`

2.1 Distribute Inputs

**Parallel call** Codex and Gemini (`run_in_background: true`):

Distribute **original requirement** (without preset opinions) to both models:

1. **Codex Backend Analysis**:

• ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
• Focus: Technical feasibility, architecture impact, performance considerations, potential risks
• OUTPUT: Multi-perspective solutions + pros/cons analysis

2. **Gemini Frontend Analysis**:

• ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
• Focus: UI/UX impact, user experience, visual design
• OUTPUT: Multi-perspective solutions + pros/cons analysis

Wait for both models' complete results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).

2.2 Cross-Validation

Integrate perspectives and iterate for optimization:

1. **Identify consensus** (strong signal) 2. **Identify divergence** (needs weighing) 3. **Complementary strengths**: Backend logic follows Codex, Frontend design follows Gemini 4. **Logical reasoning**: Eliminate logical gaps in solutions

2.3 (Optional but Recommended) Dual-Model Plan Draft

To reduce risk of omissions in Claude's synthesized plan, can parallel have both models output "plan drafts" (still **NOT allowed** to modify files):

1. **Codex Plan Draft** (Backend authority):

• ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
• OUTPUT