Orchestration

Planning & re-planning

How a goal becomes a phased plan, and what re-plans it.

The planning agent (Claude API + plan templates) turns a described goal into a structured plan. Backed by PlanConversation + PlanMessage (kinds: proposal, question, follow-up, clarification) and a proposed_plan_json.

Planning flow
  1. 1

    Open plan chat

    /projects/{p}/plans/create

    Describe the goal in Studio.

  2. 2

    Architect run proposes

    POST /cli-runs/{uuid}/plan-proposal

    A planning agent run posts a proposal.

  3. 3

    Proposal parsed

    ProposalParser builds Plan → Phases → Tasks.

  4. 4

    Review & edit

    /plans/{plan}/edit

    Adjust phases and tasks in the plan editor.

  5. 5

    Activate

    bootstrap_epic

    Plan → active; the epic branch is pinned and bootstrapped, then level-0 tasks dispatch.

  6. Loops back until the verdict is approved

Plan lifecycle

Plans move through draft → active → completed → archived, with paused and cancelled as side states. Only an active plan is dispatchable: pausing halts new dispatch, auto-review and merge until resumed; cancelling abandons it; completing/archiving requires every task terminal. See the Epic & release page for what active triggers on the git side.

Re-planning flow
  1. 1

    Trigger

    MAESTRO:SUBTASK{...}

    A plan edit, a scope change, or an executing agent emitting a subtask directive.

  2. 2

    Re-run / subtask

    POST /cli-runs/{uuid}/subtask

    Architect re-run or a routed child task is created.

  3. 3

    Plan updated

    New or changed phases and tasks; affected tasks re-dispatched.

  4. Loops back until the verdict is approved