# 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 artifact 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 artifact 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 artifact builder's prompt. Passed to all artifact 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 artifact builder writes one plan draft directly.

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

After the initial draft, the plan enters a **review loop**. A reviewer checks everything that matters — completeness against the task, rule compliance, and architectural soundness. If it returns NEEDS_WORK, the feedback goes back to the artifact builder for revision. This repeats up to `max_revisions` times.

## Agents

**Artifact Builder** (`shared/artifact_builder.py`, stage `plan`, model L) — writes and revises the plan. Supports resume via session ID for revision loops. When multi-branch is used, merger feedback is folded into instructions for the artifact builder's final draft.

**Reviewer** (`agents/plan_reviewer.py`, model L, read-only) — reviews the plan against the task and project rules. Returns APPROVED or NEEDS_WORK with specific issues.

**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 artifact builder. Only used when `branch_count` >= 2.

