# Plan Workflow

The plan workflow reads `task.md` (or directly user input) and produces `plan.md` — a technical implementation plan.

## Inputs

- `session_folder` (required) — should typically contain `task.md`.
- `plan_builder_provider` — which LLM provider the builder uses. Accepts `"claude"`, `"gemini"`, `"codex"`, or `"random"` (picks one at random). Defaults to `"claude"`.
- `branch_count` — number of parallel plan drafts to generate before merging. Defaults to 1 (no branching).
- `max_revisions` — how many times the builder can revise after a NEEDS_WORK review. Defaults to 2. Set to 0 to skip review entirely.
- `instructions` — optional free-text guidance injected into the builder's prompt. Passed to all builder calls (single-branch, multi-branch, and final-from-merger) but not to sub-agents or resume calls.

## Orchestration

The orchestrator (`create_plan.py`) has two modes depending on `branch_count`:

**Single branch** (default) — the builder writes one plan draft directly.

**Multi-branch** — the orchestrator creates `branches/plan_a/`, `plan_b/`, etc., copies `task.md` into each, and runs builders in parallel. A merger agent reviews all branch drafts, compares approaches, flags contradictions, and synthesizes feedback. The builder then writes the final plan informed by that synthesis.

After the initial draft, the plan enters a **review loop**. Two review agents (rules checker and completeness checker) run in parallel. If either returns NEEDS_WORK, their feedback goes back to the builder for revision. This repeats up to `max_revisions` times. A formatter agent standardizes the final output to match the template.

## Agents

**Builder** (`plan_builder.py`, model L) — writes and revises the plan. Supports resume via session ID for revision loops. When multi-branch is used, receives merger feedback to build the final draft.

**Rules Checker** (`agents/plan_rules_checker.py`, model L, read-only) — checks the plan against relevant project rules. Reports specific violations: which rule, where in the plan, what's wrong.

**Completeness Checker** (`agents/plan_completeness_checker.py`, model M, read-only) — checks the plan against task requirements. Reports what's missing or incomplete.

**Merger** (`agents/plan_merger.py`, model L) — reviews multiple branch plans. Compares what each got right, what each got wrong, where they conflict. Produces synthesis feedback for the builder. Only used when `branch_count` >= 2.

**Formatter** (`agents/plan_formatter.py`, model M) — restructures the plan to match the template (Summary, Decisions, Files, Implementation Order, Verification) without changing content. Runs as the final step.
