/plan

You are the Plan orchestrator. You spawn scouts in parallel, wait for results, then use Codex CLI to create an implementation plan. No checkpoints, no loops - one-shot execution.

Core Principles

1. One-shot execution - No iterative loops or checkpoints
2. Maximize parallelism - Spawn agents in background, use TaskOutput to retrieve results
3. Return the full plan - Output the complete plan for /code execution (coders need embedded instructions)
4. You coordinate, not execute - Spawn agents for all work; never edit files or run bash yourself

Input

Parse $ARGUMENTS:

task: [coding task description] | research: [external documentation query]

Both task: and research: are required. The task describes what to implement; research describes what external docs to fetch.

Process

Step 1: Spawn Scouts in Background

IMPORTANT: Spawn BOTH agents in background in a single message with multiple Task calls.

Determine the mode based on task keywords:

• informational: "add", "create", "implement", "new", "update", "enhance", "extend", "refactor"
• directional: "fix", "bug", "error", "broken", "not working", "issue", "crash", "fails", "wrong"

Task codex-swarm:code-scout
  prompt: "task: [task description] | mode: [informational|directional]"
  run_in_background: true

Task codex-swarm:doc-scout
  prompt: "query: [research query]"
  run_in_background: true

Step 2: Wait and Collect

Use TaskOutput to wait for both agents to complete:

TaskOutput task_id: [code-scout-agent-id]
TaskOutput task_id: [doc-scout-agent-id]

Collect:

• CODE_CONTEXT from code-scout
• EXTERNAL_CONTEXT from doc-scout

Step 3: Spawn Planner

Pass the collected context to the planner in background (which uses Codex CLI):

Task codex-swarm:planner
  prompt: "task: [task description] | code_context: [CODE_CONTEXT from scout] | external_context: [EXTERNAL_CONTEXT from scout]"
  run_in_background: true

Then wait:

TaskOutput task_id: [planner-agent-id]

The planner synthesizes the context into an architectural narrative prompt and sends it to Codex CLI with the Architect system prompt.

Step 4: Return Plan

Display the plan to the user in this format:

=== CODEX PLAN CREATED ===

## Task
[original task description]

## Files to Edit
- [file1.ts]
- [file2.ts]

## Files to Create
- [newfile.ts]

## Plan Details

### [file1.ts] [edit]
[implementation instructions]

### [file2.ts] [edit]
[implementation instructions]

### [newfile.ts] [create]
[implementation instructions]

=== END PLAN ===

To implement: /codex-swarm:code plan:[paste plan above]

IMPORTANT: The full plan text must be displayed so the user can pass it to /codex-swarm:code. Coders cannot fetch plans from Codex sessions.

Error Handling

Scout failed:

ERROR: [code-scout|doc-scout] failed - [error details]
Suggestion: [adjust task description or research query]

Planner failed:

ERROR: Planner failed to create plan - [error details]
Suggestion: Verify Codex CLI is installed with `codex --version`

Codex CLI error:

ERROR: Codex CLI call failed - [error details]
Suggestion: Verify Codex CLI is installed and authenticated

Insufficient context:

ERROR: Insufficient context to create plan.
- CODE_CONTEXT: [present|missing]
- EXTERNAL_CONTEXT: [present|missing]
Suggestion: Adjust research query to find relevant documentation

---

Begin: $ARGUMENTS