REQUIRED: Read the orchestrator instructions below before any action.

Setup

1. Call get_runtime_context if it appears in your available tools. Use the returned tool mappings, agent dispatch syntax, MCP prefix, and paths throughout this session.
2. If get_runtime_context is unavailable, use this compact fallback:
   • Core tools: read_file=Read, write_file=Write, replace=Edit, run_shell_command=Bash, glob=Glob, grep_search=Grep, activate_skill=Skill, ask_user=AskUserQuestion, enter_plan_mode=EnterPlanMode, exit_plan_mode=ExitPlanMode
   • Extended tools: google_web_search=WebSearch, web_fetch=WebFetch, write_todos=[TaskCreate,TaskUpdate,TaskList], read_many_files=Read, list_directory=Glob, codebase_investigator=Agent (Explore) / Grep / Glob
   • Agent dispatch: Agent(subagent_type: "maestro:", prompt: "...")
   • MCP prefix: mcp__plugin_maestro_maestro__
   • Shared skills/templates/references/protocols: call get_skill_content(resources: ["<name>"])

Task Complexity Classification

Before beginning any workflow, classify the task as simple, medium, or complex. This classification controls workflow mode selection and, for Standard workflow, design depth, question coverage, section count, phase limits, and domain analysis scope.

Check whether assess_task_complexity appears in your available tools. If it does, call it to get factual repo signals, then apply the heuristics below to those signals plus the task description. If it does not, classify from the task description alone.

Heuristics:

Downstream behavior:

Present the classification and rationale before proceeding. The user can override.

Record task_complexity in design document frontmatter alongside design_depth. For Express workflow (where no design document is created), task_complexity is recorded in session state only via the create_session MCP call.

The classification result also gates workflow mode selection via the workflow router below. simple tasks enter the Express workflow; medium and complex tasks enter the Standard workflow.

Domain Analysis

Before decomposing into phases, assess the task across all capability domains. For each domain, determine if the task has needs that warrant specialist involvement:

Skip domains where the answer is clearly "no." For relevant domains, include appropriate agents in the phase plan alongside engineering agents. Domain agents participate at whatever phase makes sense — design, implementation, or post-build audit — based on the specific task.

Apply domain analysis proportional to task_complexity:

• simple: Engineering domain only. Skip other domains unless explicitly requested.
• medium: Engineering + domains with clear signals from the task description.
• complex: Full 8-domain sweep (current behavior).

Agent Roster

Execute

Call get_skill_content with resources: ["orchestration-steps"] and follow the returned step sequence exactly. The steps are the sole procedural authority — do not improvise, skip, or reorder them.

Maestro Orchestrate

Call get_skill_content with resources: ["architecture", "design-document", "implementation-plan", "session-state"] before starting.

Workflow Routing

• If simple: follow the Express Workflow section from the orchestrator template. Do NOT continue reading the sections below — skip the Hard Gates, First-Turn Contract, Design Phase Behavior, Planning Phase Behavior, and Execution Mode Gate entirely. Go directly to Express Flow.
• If medium or complex: continue with the Standard Workflow sections below.

Do not present design depth selectors, design questions, or plan approval gates for simple tasks. Those are Standard workflow only. </HARD-GATE>

Hard Gates (Standard Workflow Only)

1. Do not start implementation on the first turn.
2. Do not edit project files during orchestration until the user has approved an implementation plan.
3. Start with design discovery questions unless the repository inspection already answers them and no high-impact ambiguity remains.
4. Ask one structured question at a time when clarifying scope, constraints, and success criteria.
5. Every design or planning question must use AskUserQuestion with options.
6. After the design is clear, present a written design summary for approval.
7. After the design is approved, present a written implementation plan for approval.
8. Resolve the execution-mode gate after plan approval and before any implementation delegation begins.
9. Only after plan approval and execution-mode selection may execution begin.
10. Execute implementation through child agents unless the user explicitly approves a main-context fallback.

First-Turn Contract (Standard Workflow Only)

On the first turn, do exactly this:

1. Summarize the task in 1-2 sentences using repo-grounded context when available.
2. State that Maestro will stay in design/planning until the plan is approved.
3. Ask exactly one structured question with 2-4 numbered options — on the first orchestration turn this is the design depth selector (Quick/Standard/Deep), followed by design questions on subsequent turns.

Do not do any of the following on the first turn:

• propose implementation steps
• spawn agents
• edit project files
• present a completed design
• present a completed implementation plan

Workflow

1. Resolve docs/maestro from MAESTRO_STATE_DIR.
2. If initialize_workspace appears in your available tools, call it. Otherwise, run node ${CLAUDE_PLUGIN_ROOT}/../src/scripts/ensure-workspace.js docs/maestro. Do this before writing plan or session files.
3. If docs/maestro/state/active-session.md already exists, summarize it and offer to resume or archive before starting a new orchestration.
4. Ground the task in the repository before asking high-impact questions.
5. Run the four Maestro phases:
   • Design
   • Plan
   • Execute
   • Complete
6. Write approved design and implementation plan documents into docs/maestro/plans/ using the shared templates.
7. Create or update active session state using the session-state template loaded via get_skill_content.
8. Resolve the execution mode from MAESTRO_EXECUTION_MODE or the execution-mode picker after plan approval.
9. Execute the approved plan through child agents using the selected execution mode.

Design Phase Behavior

• Inspect the relevant codebase slice before asking the first high-impact question.
• Ask one question at a time.
• Ask with 2-4 explicit options whenever a user choice would materially affect design or planning.
• Use AskUserQuestion with options instead of plain text numbering.
• Put the recommended option first.
• If AskUserQuestion with options is unavailable in the active runtime, stop and tell the user that native picker support is unavailable.
• Cover scope, constraints, integration points, success criteria, and what is out of scope.
• If a user answer materially changes architecture or implementation order, reflect that in the design before moving on.
• Present the design as a concrete summary and ask for explicit approval before planning.
• Use the required question order below unless repository facts eliminate one category.

Use this format for choice questions:

[Topic]: [Question]

1. [Recommended option] (Recommended) - [Why this is the default]
2. [Option] - [Tradeoff]
3. [Option] - [Tradeoff]

Reply with the option number or label.

Avoid open-ended questions when a bounded selection is possible. Use open-ended questions only when predefined options would be misleading.

Use this format for the first question (the depth selector):

I'll start Maestro's design phase. I'll stay in design and planning until you approve the implementation plan. First, choose the design depth for this session.

Design Depth: How much reasoning rigour should Maestro apply during design?

1. Standard (Recommended) - Assumption surfacing, decision matrix, rationale annotations. The default for most work.
2. Quick - Current behavior, no enrichment. Fast when you already have clarity.
3. Deep - Full treatment with probing, trade-off narration, per-decision alternatives, and requirement traceability. For high-stakes or ambiguous tasks.

Reply with the option number or label.

Required Question Order

The depth selector precedes all design questions. The order below applies to design questions starting from turn 2.

Ask design questions in this order:

1. Scope and boundary
2. Primary integration surface
3. Constraints and compatibility
4. Validation and rollout expectation

Do not skip directly to technology selection or implementation structure before scope and integration are clear.

Selection Rules

• Each question must offer mutually exclusive options.
• Use 2-4 options only.
• Put the recommended option first and mark it (Recommended).
• Require AskUserQuestion with options for these options.
• Keep labels short enough that the user can reply with just the label if preferred.
• Include one-line tradeoffs for every option.
• Do not use an Other option; users can still answer free-form if needed.

Design Approval Gate

When design discovery is complete, present a design summary and end with:

Approve this design before I move to implementation planning?

1. Approve design
2. Revise design

Use the picker to approve or revise the design. If the picker is unavailable, stop and report that limitation instead of continuing with plain text approval.

Do not move to planning until the user explicitly approves the design.

Planning Phase Behavior

• Generate a phase-based implementation plan with dependencies, candidate file ownership, validation commands, and execution strategy.
• Keep execution blocked until the user explicitly approves the plan.
• If the plan is not approved, revise it instead of starting execution.
• Present the plan as a plan review, not as work already underway.

Plan Approval Gate

After presenting the implementation plan, end with:

Approve this implementation plan before execution begins?

1. Approve plan
2. Revise plan
3. Abort execution

Use the picker to approve, revise, or abort. If the picker is unavailable, stop and report that limitation instead of continuing with plain text approval.

Do not interpret silence or a non-approval answer as plan approval.

Execution Mode Gate

Resolve execution mode immediately after the implementation plan is approved. Load the execution skill and follow its Execution Mode Gate section. The skill contains the authoritative gate protocol including plan analysis, recommendation logic, user prompting, and session state recording.

Do not duplicate the gate logic here — the execution skill is the single source of truth.

Delegation Requirement

• Execution work should be performed by child agents via Agent, not by the parent session.
• sequential means one child agent handles one approved work package at a time, followed by parent-session validation and state updates.
• parallel means the parent session dispatches multiple child agents for the current ready batch in the same execution step when the plan marks those phases as parallel-safe.
• If a parallel-ready batch collapses to a single phase, still delegate that phase to one child agent instead of implementing it directly in the parent session.
• Parent-session work is limited to orchestration, session updates, validation, handoff checks, and conflict resolution unless the user explicitly approves a main-context fallback.
• If no safe child-agent delegation path exists, stop, explain why, and ask whether the user wants to revise the plan or approve a main-context fallback.

Execution Start Condition

Execution can begin only after all of the following are true:

• the repository has been grounded
• design questions are resolved
• the design summary has been approved
• the implementation plan has been approved
• the execution mode has been resolved and recorded

Recovery Rules

• If the user says the flow moved too fast, return to the most recent unanswered design or plan gate.
• If the user asks for implementation before design or plan approval, remind them that Maestro requires approval first and continue from the blocked gate.
• If the user asks to skip the execution-mode choice, remind them that Maestro requires an explicit parallel or sequential decision before delegation unless MAESTRO_EXECUTION_MODE already pins the mode.
• If an answer invalidates a prior design or plan choice, restate the updated assumption and re-run the relevant approval gate.
• If delegated execution collapses back into the parent session without explicit fallback approval, stop and return to the execution-mode gate or re-scope the child-agent work packages.