@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: design-dialogue
+description: Guides structured design conversations for complex engineering tasks
+---
+
+# Design Dialogue Skill
+
+**Standard workflow only.** If `task_complexity` is `simple` and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate design-dialogue. Return to the Express Workflow section.
+
+Activate this skill when beginning Phase 1 of Maestro orchestration. Use the plan mode tool from `get_runtime_context` (loaded at session start, step 0). If your runtime provides a Plan Mode surface, enter it now by calling `enter_plan_mode`. If Plan Mode is unavailable or the transition fails, continue without it and use the user-prompt tool from runtime context with `type: 'yesno'` for design approvals and `type: 'choice'` for approach selection. This skill provides the structured methodology for conducting design conversations that converge on approved architectural designs.
+
+**User confirmation sequence**: Phase 1 entry may trigger a Plan Mode confirmation when `enter_plan_mode` is available. That confirmation is expected; do not treat it as redundant or skip it. If your runtime does not provide Plan Mode, move directly into the depth selector and approval prompts.
+
+## Design Depth Gate
+
+Before asking any design questions, present the user with a depth selector to control the level of reasoning rigour applied throughout the design phase. Use `ask_user` with `type: 'choice'` to offer three modes. Lead with Standard as the recommended default.
+
+**Modes:**
+
+- **Quick** — Current reasoning behavior. One question per topic, pros/cons on approaches, standard design sections. No enrichment steps, no decision matrix, no reasoning annotations. Choose this when you already have clarity and want to move fast. (The depth selector prompt itself is the only new conversational step — once Quick is selected, all subsequent behavior matches pre-change behavior exactly.)
+- **Standard** (Recommended) — Adds assumption surfacing after each answer and a decision matrix during approach evaluation. Design sections gain rationale annotations tying decisions to project context. The default for most work.
+- **Deep** — Full treatment. Follow-up probing into implications, assumption surfacing with confirmation, trade-off narration on each choice, decision matrix with scoring, rationale annotations, per-decision alternatives, and full requirement traceability. Choose this for high-stakes or ambiguous tasks.
+
+**Depth propagation**: Remember the user's chosen depth mode and apply it consistently to all subsequent steps in this skill. The depth mode is not re-prompted — it is set once and carried forward. If the user's answer to the depth prompt is ambiguous, default to Standard.
+
+**Depth vs. complexity**: Depth and complexity guidance (simple/medium/complex) are orthogonal. Complexity controls which sections appear and word count per section. Depth controls reasoning richness within each section. They compose independently — a user may select Deep depth on a Simple complexity task or Quick depth on a Complex task. Both are valid choices.
+
+**Frontmatter**: Record the chosen depth in the design document frontmatter as `design_depth: quick | standard | deep`. Also record `task_complexity: simple | medium | complex` in the design document frontmatter after `design_depth`.
+
+**First-Turn Contract**: On the first turn, Maestro presents the complexity classification result (classified per the complexity classification section in the orchestrator) and the depth selector with a complexity-informed recommendation. For `simple` tasks, auto-select Quick and inform the user: "This looks straightforward — using Quick depth. Say 'deeper' if you want more analysis." For `medium` tasks, recommend Standard. For `complex` tasks, recommend Standard or Deep. The first actual design question moves to the second turn.
+
+## Repository Grounding Protocol
+
+Before you start narrowing the architecture for work that touches an existing codebase, decide whether the task is already grounded.
+
+Use the built-in `codebase_investigator` when any of the following are true:
+- The request targets an existing project or subsystem
+- The current architecture, impacted modules, or integration seams are unclear
+- You need concrete validation commands, conventions, or ownership boundaries before presenting approaches
+
+Ask the investigator for:
+- The current architecture slice relevant to the task
+- The most likely impacted modules and files
+- Existing naming, layering, and testing conventions to preserve
+- Integration points and dependency edges the design must respect
+- Validation commands already used by the repo
+- Parallelization or file-conflict risks that should shape the later implementation plan
+
+Skip `codebase_investigator` for greenfield tasks, documentation-only work, or scopes that are already well understood from direct file reads in the current turn.
+
+Use the investigator's output to:
+- Tailor follow-up questions to the actual codebase
+- Avoid proposing approaches that conflict with existing boundaries
+- Cite concrete modules/files when explaining trade-offs
+
+## Question Framework
+
+### Principles
+- Ask one question at a time — never batch multiple questions
+- Prefer multiple choice format with 2-4 options over open-ended questions
+- For every choice presented, include brief pros and cons so the user can make an informed decision — never present bare options without trade-off context
+- Lead with your recommended option and explain the rationale
+- Wait for user response before proceeding to next question
+- Adapt follow-up questions based on previous answers
+
+### Required Coverage Areas
+
+Ask questions in this order to progressively narrow the design space:
+
+1. **Problem Scope & Boundaries**
+   - What specific problem are we solving?
+   - What is explicitly out of scope?
+   - What are the expected inputs and outputs?
+
+2. **Technical Constraints & Limitations**
+   - Existing technology stack and infrastructure
+   - Compatibility requirements with existing systems
+   - Performance budgets (latency, throughput, resource limits)
+   - Team expertise and familiarity
+
+3. **Technology Preferences**
+   - Language and framework preferences
+   - Database and storage requirements
+   - Third-party service dependencies
+   - Build and deployment toolchain
+
+4. **Quality Requirements**
+   - Performance targets (response time, concurrent users)
+   - Security requirements (authentication, authorization, data protection)
+   - Scalability expectations (growth projections, peak loads)
+   - Reliability requirements (uptime, disaster recovery)
+
+5. **Deployment Context**
+   - Target environment (cloud provider, on-premise, hybrid)
+   - CI/CD pipeline requirements
+   - Monitoring and observability needs
+   - Operational constraints (team size, on-call, maintenance windows)
+
+### Coverage Scaling by Complexity
+
+Scale question coverage based on `task_complexity`:
+- **simple**: Ask questions from Area 1 (Problem Scope & Boundaries) only. Skip Areas 2-5.
+- **medium**: Ask questions from Areas 1-3 (Scope, Constraints, Tech Preferences). Skip Areas 4-5.
+- **complex**: Ask questions from all 5 areas (current behavior).
+
+### Question Format
+
+Prompt the user for a choice using the user-prompt tool from runtime context. Use `type: 'choice'` for structured selections with 2-4 options. Each option should have a short label (1-5 words) and a description explaining when it makes sense and its trade-offs. Include your recommendation rationale in the question text so the user has context before choosing.
+### Enrichment Protocol
+
+After the user answers each question, apply depth-gated enrichment steps before advancing to the next topic:
+
+| Step | Quick | Standard | Deep |
+|------|-------|----------|------|
+| Accept answer and move on | Yes | Yes | Yes |
+| Surface assumptions made from the answer | No | Yes | Yes |
+| Ask user to confirm/correct assumptions | No | Yes | Yes |
+| Probe implications with a follow-up question | No | No | Yes |
+| Narrate trade-offs of the choice before moving on | No | No | Yes |
+
+**Quick mode**: No enrichment steps. Accept the answer and proceed to the next question. Current behavior preserved.
+
+**Standard mode**: After each user answer, state the assumptions you are making based on their response in 1-2 sentences, then ask the user to confirm or correct before proceeding. Example flow: question → answer → "Based on your answer, I'm assuming X and Y — correct?" → confirmation → next question.
+
+**Deep mode**: After each user answer: (a) state and confirm assumptions as in Standard mode, (b) narrate the trade-offs of the choice in 1-2 sentences ("That choice means we gain A but give up B"), (c) if the answer has non-obvious implications (e.g., a technology choice that constrains future scaling options or creates a vendor lock-in dependency), ask one follow-up probing question before moving to the next topic. Cap at one follow-up per question.
+
+**Adaptive elision**: If the user's answer is concrete, specific, and requires no inference (e.g., "What language?" → "TypeScript, same as the rest of the repo"), the assumption surfacing and trade-off narration steps may be skipped even in Deep mode. Only apply enrichment when there are genuine assumptions to surface or trade-offs to narrate. Do not elide when the answer implies unstated architectural trade-offs even if the answer itself is short (e.g., "REST" implies choices about state management, versioning, and contract evolution that are worth surfacing).
+
+## Approach Presentation
+
+### When to Present Approaches
+Present 2-3 architectural approaches after gathering sufficient requirements (typically after covering scope, constraints, and technology preferences).
+
+If `codebase_investigator` was used, present approaches only after incorporating its findings into the trade-off analysis. Do not treat the existing codebase structure as optional context.
+
+### Approach Format
+
+For each approach, provide:
+
+```
+### Approach [N]: [Descriptive Name]
+
+**Summary**: [2-3 sentence overview]
+
+**Architecture**:
+[Component diagram or description showing key components and their relationships]
+
+**Pros**:
+- [Concrete advantage with context]
+- [Another advantage]
+
+**Cons**:
+- [Concrete disadvantage with context]
+- [Another disadvantage]
+
+**Best When**: [Specific conditions where this approach excels]
+
+**Risk Level**: Low | Medium | High
+```
+
+### Presentation Rules
+- Always lead with your recommended approach
+- Explain why the recommended approach best fits the gathered requirements
+- Highlight the key differentiator between approaches
+- After presenting all approaches, explicitly ask the user to choose
+- Accept user's choice without pushback, even if it differs from your recommendation
+
+### Recommendation Philosophy
+- **Always identify the ideal long-term solution** — the approach that is architecturally sound, maintainable, and future-proof. Present it clearly so the user understands what "right" looks like.
+- **When the long-term solution requires large-scale changes** that are disproportionate to the task at hand, also present a pragmatic alternative that accomplishes the goal without major disruption. Be explicit about the trade-off: "The ideal solution is X (because...), but a pragmatic path is Y (because the scope of X is disproportionate to the current need)."
+- **Never default to the quick fix without surfacing the long-term option.** The user should always know what they're trading away. But equally, never recommend a large-scale refactor when the task can be accomplished safely with a targeted change.
+- **Label each approach honestly**: which is the long-term investment, which is the pragmatic path, and which (if any) is a stopgap that will create debt.
+
+### Decision Matrix
+
+In Standard and Deep modes, after presenting the 2-3 approaches with narrative pros/cons, also present a decision matrix that scores each approach against the gathered requirements. In Quick mode, skip the matrix.
+
+**Criteria derivation**: Derive 3-6 scoring criteria from the requirements and constraints gathered during the question phase. Use the user's stated priorities to assign weights (sum to 100%). If the user has not explicitly stated priorities, infer relative weights from the emphasis given during the question phase; equal weighting is acceptable as a last resort. If fewer than 3 meaningful criteria emerge, skip the matrix and use narrative-only recommendation.
+
+**Scoring scale**: Score each approach on each criterion using a 1-5 scale: 1=poor fit, 3=adequate, 5=strong fit. Include a brief justification (1 sentence) in each cell.
+
+**Matrix format**:
+
+| Criterion | Weight | Approach A | Approach B | Approach C (if applicable) |
+|-----------|--------|------------|------------|------------|
+| [Criterion from requirements] | [%] | [1-5]: [justification] | [1-5]: [justification] | [1-5]: [justification] |
+| **Weighted Total** | | [score] | [score] | [score] |
+
+**Tie-breaking**: If approaches score within 1 point of each other in weighted totals, present the near-tie explicitly and use narrative judgment to break the tie, citing the single most decisive factor. Do not present a matrix-driven recommendation as definitive when the scores don't clearly differentiate.
+
+**Non-differentiating criteria**: Criteria that score identically across all approaches may be noted but should be excluded from the matrix to keep it focused on differentiating factors. If removing non-differentiating criteria leaves fewer than 2 rows, skip the matrix and use narrative-only recommendation.
+
+## Design Convergence Protocol
+
+### Section-by-Section Presentation
+
+Present the design document in sections, validating each before proceeding. Scale the number of sections to the task's complexity, but always present at least the **minimum set**.
+
+**Minimum sections (always required, regardless of task complexity):**
+1. Problem Statement
+2. Approach (Selected Approach, Alternatives Considered)
+3. Risk Assessment
+
+**Full presentation order** (use for medium-to-complex tasks; matches `templates/design-document.md` structure):
+1. Problem Statement
+2. Requirements (Functional, Non-Functional, Constraints)
+3. Approach (Selected Approach, Alternatives Considered, Decision Matrix)
+4. Architecture (Component Diagram, Data Flow, Key Interfaces)
+5. Agent Team
+6. Risk Assessment
+7. Success Criteria
+
+**Complexity guidance:**
+- **Simple** (static sites, single-file scripts, config changes): present the 3 minimum sections. Keep each to 100-150 words.
+- **Medium** (multi-component features, API endpoints, integrations): present sections 1-3 and 6, plus up to 1 other section that surfaces meaningful trade-offs (cap at 5 total). 150-250 words each.
+- **Complex** (new subsystems, cross-cutting refactors, multi-service architectures): present all 7 sections at 200-300 words each.
+
+Never skip Problem Statement, Approach, or Risk Assessment. If you believe other sections add no value for the task, omit them — but state which sections you are skipping and why before presenting the first section.
+
+### Validation Format
+
+After each section, prompt the user for approval using the user-prompt tool from runtime context with `type: 'yesno'`. Do not rely on a separate assistant message for the section content. The prompt body itself must include the section title and the full section summary (200-300 words) so the user can review the material directly in the approval prompt. End with: "Does this section accurately capture our discussion? Any changes needed before I proceed to [next section name]?"
+
+### Revision Protocol
+- If user requests changes, revise the section and re-present
+- Re-present revised content inside the next approval prompt as well; never ask for approval on a section summary the user cannot see in the prompt
+- Track which sections are approved vs pending
+- Do not proceed to the next section until current section is approved
+- If a later section reveals issues with an earlier section, flag the conflict and propose resolution
+
+### Section Reasoning Guide
+
+Apply depth-gated reasoning enrichment to design section content during the convergence phase:
+
+| Element | Quick | Standard | Deep |
+|---------|-------|----------|------|
+| Pros/cons on approaches | Yes | Yes | Yes |
+| Recommendation narrative | Yes | Yes | Yes |
+| Decision matrix scoring approaches | No | Yes | Yes |
+| Rationale annotations on section decisions | No | Yes | Yes |
+| Per-decision alternatives considered | No | No | Yes |
+| Requirement traceability (`Traces To`) | No | No | Yes |
+
+**Quick mode**: No reasoning annotations. Present sections as-is — current behavior preserved.
+
+**Rationale annotations (Standard + Deep)**: For each key design decision within a section, include an inline explanation of why it was chosen, tied to specific project context from the question phase. A key decision is one that, if changed, would require reworking other parts of the design — routine or cosmetic choices (naming, formatting) are not key. Format: `[decision] — *[rationale referencing specific requirements, constraints, or user-stated preferences]*`
+
+**Per-decision alternatives (Deep only)**: For key sub-decisions (choices within a section that affect the design's shape), briefly note what was considered and rejected. Format: `[decision] *(considered: [alternative A] — rejected because [reason]; [alternative B] — rejected because [reason])*`
+
+**Requirement traceability (Deep only)**: Tag each key decision with `Traces To: REQ-N` referencing the numbered requirement it satisfies from the design document's Requirements section. Every requirement (functional and non-functional) should be traceable to at least one design decision. If the Requirements section was omitted due to complexity guidance (simple tasks), skip requirement traceability markers — rationale annotations and per-decision alternatives still apply.
+
+**Uniform application**: Apply the chosen depth mode's reasoning rules uniformly to every section in the convergence phase. Do not selectively skip reasoning on some sections unless the adaptive elision rule applies (the decision is self-evident and requires no justification).
+
+## Design Document Generation
+
+### Output Location
+
+The write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0):
+
+- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there. After `exit_plan_mode` approval in Phase 2, copy it to the permanent location.
+- **Plan Mode not active or not available**: Write directly to the permanent location. If your runtime does not provide Plan Mode, track design progress using the plan-update mechanism from runtime context and use the user-prompt tool from runtime context for section approvals and final signoff.
+
+Permanent location: `<state_dir>/plans/YYYY-MM-DD-<topic-slug>-design.md` (where `<state_dir>` resolves from `MAESTRO_STATE_DIR`, default `docs/maestro`).
+
+Where:
+- `YYYY-MM-DD` is the current date
+- `<topic-slug>` is a lowercase, hyphenated summary of the task (e.g., `user-auth-system`, `data-pipeline-refactor`)
+
+### Document Structure
+Use the `design-document` template loaded via `get_skill_content`. Include the `design_depth` field in the frontmatter, set to the depth mode chosen during the Design Depth Gate.
+
+### Completion Criteria
+The design document is complete when:
+- All sections have been presented and approved by the user
+- The agent team composition matches the task requirements
+- Phase dependencies are clearly mapped
+- Success criteria are measurable and specific
+- The user has given explicit final approval of the complete document
+
+### Post-Generation
+After writing the design document:
+1. Confirm the file path to the user
+2. Summarize key decisions made during the dialogue
+3. Ask if the user is ready to proceed to implementation planning (Phase 2)

package/plugins/maestro/src/skills/shared/execution/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: execution
+description: Phase execution methodology for orchestration workflows with error handling and completion protocols
+---
+
+# Execution Skill
+
+Activate this skill during Phase 3 (Execution) of Maestro orchestration. This skill defines how Maestro executes implementation phases through native subagent delegation.
+
+## Execution Mode Gate
+
+### Step 0 — Express bypass (early return)
+
+If `workflow_mode` is `express` in the current session, STOP HERE. Do not proceed
+to the execution mode gate. Do not prompt the user. Do not resolve execution mode.
+Express always dispatches sequentially. Return to the Express Workflow and continue
+from the delegation step.
+
+<HARD-GATE>
+This gate MUST resolve before ANY delegation proceeds. Do not skip it. Do not defer it. Do not begin delegating to subagents until execution_mode is recorded in session state. If you reach a delegation step and execution_mode is not set, STOP and return here.
+</HARD-GATE>
+
+### Step 1 — Read the configured mode
+
+Read `MAESTRO_EXECUTION_MODE` (default: `ask`).
+
+- If `parallel`: call `update_session` with `{ execution_mode: 'parallel', execution_backend: 'native' }` to record in session state. Skip to delegation.
+- If `sequential`: call `update_session` with `{ execution_mode: 'sequential', execution_backend: 'native' }` to record in session state. Skip to delegation.
+- If `ask`: proceed to Step 2.
+
+### Step 2 — Analyze the implementation plan
+
+Before prompting the user, analyze the approved plan to generate a recommendation:
+
+1. Count total phases in the plan
+2. Count phases marked `parallel: true` (parallelizable phases)
+3. Count distinct parallel batches (groups of parallelizable phases at the same dependency depth)
+4. Count sequential-only phases (phases with `blocked_by` dependencies that prevent parallelization)
+5. Cross-check file ownership across all phases. If any two phases share a file in their `files` arrays, those phases CANNOT be parallel-eligible — subtract them from the parallelizable count. Report each overlap as an Overlapping-file Warning in the prompt.
+
+6. If `validate_plan` was called during planning and returned a `parallelization_profile`, use its `parallel_eligible` and `effective_batches` counts as the authoritative source for items 1-5 above. These are computed from actual dependency depths and override any manual flag-based counts. If `parallelization_profile` is not available, use the counts from items 1-5 as-is.
+
+Record these counts — they feed into the prompt.
+
+### Step 3 — Determine the recommendation
+
+- If parallelizable phases ≤ 1 → auto-select **sequential**. Call `update_session` with `{ execution_mode: 'sequential', execution_backend: 'native' }`. Inform the user: "All phases are sequential — no parallel batches available." Skip to delegation. Do NOT prompt with a choice. Do NOT call `ask_user`. Do NOT present options. (Parallelism requires at least 2 phases at the same dependency depth; a single parallel-eligible phase has nothing to batch with.)
+
+<ANTI-PATTERN>
+WRONG — 1 parallel-eligible phase but user still prompted:
+  Parallel-eligible Phases: 1
+  → Presented choice: "Sequential (Recommended)" / "Parallel"
+
+When parallelizable phases ≤ 1, there is NO choice to make. Auto-select sequential
+and skip directly to delegation. Do not show a picker.
+</ANTI-PATTERN>
+
+- If parallelizable phases > 50% of total phases → recommend **parallel**
+- If parallelizable phases ≤ 50% but > 1 → recommend **sequential** (limited benefit)
+- The recommended option appears first in the `ask_user` options list with "(Recommended)" appended to its label. The non-recommended option MUST NOT include "(Recommended)" in its label.
+
+### Step 4 — Prompt the user
+
+Call `ask_user` with `type: 'choice'` using exactly one of these option sets:
+
+**When recommending parallel:**
+  options:
+    - label: "Parallel (Recommended)"
+      description: "Spawn child agents for each ready batch where file ownership does not overlap."
+    - label: "Sequential (High Precision)"
+      description: "Spawn one child agent at a time in dependency order."
+
+**When recommending sequential:**
+  options:
+    - label: "Sequential (Recommended)"
+      description: "Spawn one child agent at a time in dependency order."
+    - label: "Parallel"
+      description: "Spawn child agents for each ready batch where file ownership does not overlap."
+
+<ANTI-PATTERN>
+WRONG — Both options labeled "(Recommended)":
+  options:
+    - label: "Parallel (Recommended)"
+    - label: "Sequential (High Precision) (Recommended)"
+
+Only ONE option receives the "(Recommended)" suffix. Never both.
+</ANTI-PATTERN>
+
+Prompt the user for a choice using the user-prompt tool from runtime context. Replace `[N]`, `[M]`, and `[B]` with actual counts from Step 2. The prompt should convey the execution mode analysis and offer two options as described above.
+### Step 5 — Record and proceed
+
+1. Call `update_session` with the selected `execution_mode` and `execution_backend: native`
+2. The tool atomically persists both fields
+3. Use the selected mode for the remainder of the session unless the user changes it
+
+### Mode-specific behavior
+
+- If `parallel` is selected and a ready batch has only one phase, execute it sequentially
+- If `sequential` is selected, preserve plan order even when phases are parallel-safe
+
+### Safety fallback
+
+If `execution_mode` is not present in session state at the point where delegation is about to begin, STOP. Do not default to sequential. Return to this gate and resolve it. This catches any edge case where the gate was skipped.
+
+## State File Access
+
+When MCP state tools (`get_session_status`, `update_session`, `transition_phase`) are available, prefer them for state operations. They provide structured I/O and atomic transitions.
+
+When MCP tools are not available, state lives inside `<MAESTRO_STATE_DIR>` and is accessible through `read_file` and `write_file`.
+
+Helper scripts remain available for shell-injected command prompts:
+
+```bash
+node <runtime-script-root>/read-state.js <relative-path>
+node <runtime-script-root>/read-active-session.js
+```
+
+## Hook Lifecycle During Execution
+
+Hooks fire automatically at agent boundaries. The orchestrator does not invoke them directly.
+
+The hooks system tracks which agent is currently executing. Before each agent dispatch, a hook resolves the active agent identity from the required `Agent:` header first, then falls back to legacy env/regex detection, and injects compact session context. After completion, a hook validates that the response contains both `Task Report` and `Downstream Context`; it requests one retry on the first malformed response.
+
+The hook state directory under `/tmp/maestro-hooks/<session-id>/` is transient and separate from orchestration state.
+
+## Sequential Execution Protocol
+
+For a sequential phase:
+
+1. Verify all `blocked_by` dependencies are completed
+2. Mark the phase `in_progress`
+3. Update `current_phase`
+4. Set `current_batch: null`
+5. Update the progress-tracking tool (use the tool names from `get_runtime_context`) before delegation
+6. Delegate to the assigned agent with the required header and full context
+7. Parse the returned handoff
+8. Update session state
+9. Mark the phase `completed` or `failed`
+10. Update the progress-tracking tool after the state update
+
+## Native Parallel Execution Protocol
+
+Use native parallel execution only for sibling phases at the same dependency depth with non-overlapping file ownership.
+
+### Batch Rules
+
+1. Verify all blocking phases for every phase in the batch are completed
+2. Slice the ready batch into the current dispatch chunk using `MAESTRO_MAX_CONCURRENT`
+3. Mark only the current chunk phases `in_progress`
+4. Set `current_batch` in session state for that chunk
+5. Write one in-progress todo item for the chunk
+6. In the next turn, emit only agent tool calls for that chunk
+7. Do not mix shell commands, validation commands, file writes, or narration between those agent calls
+8. `MAESTRO_MAX_CONCURRENT=0` means emit the entire ready batch in one turn
+
+### Native Constraints
+
+- The runtime only parallelizes contiguous agent calls in one turn
+- Native subagents currently run without user approval gates
+- `ask_user` remains available; a batch may pause while waiting for user input
+- If execution is interrupted, restart unfinished `in_progress` phases on resume instead of attempting to restore in-flight subagent interactions
+
+## Progress Context
+
+Include the following in every delegation query body:
+
+```text
+Progress: Phase [N] of [M]: [Phase Name]
+Session: [session_id]
+```
+
+For native parallel batches, also include the batch identifier in the required header:
+
+```text
+Agent: <agent_name>
+Phase: <id>/<total>
+Batch: <batch_id>
+Session: <session_id>
+```
+
+## Error Handling Protocol
+
+Record all errors in session state with:
+
+- `agent`
+- `timestamp`
+- `type`
+- `message`
+- `resolution`
+
+### Retry Logic
+
+- Maximum retries per phase: `MAESTRO_MAX_RETRIES` (default `2`)
+- First failure: analyze, adjust context/scope, retry automatically
+- Subsequent failures up to the limit: continue retrying with clearer constraints
+- Limit exceeded: mark the phase `failed` and escalate to the user
+
+Increment `retry_count` on each retry.
+
+### Recovery Protocol
+
+When a subagent terminates early, times out, returns malformed output, or when `delegation.constraints.result_surface` is `deferred` and the agent's text cannot be retrieved:
+
+1. **Poll**: For deferred-result runtimes (Codex), call the runtime's wait tool (`wait_agent` equivalent) with a bounded timeout. For synchronous runtimes, the initial dispatch return IS the result.
+2. **Detect drift**: Call `scan_phase_changes(session_id, phase_id)`. If the returned `candidates.created` or `candidates.modified` arrays are non-empty, the agent produced filesystem output without a handoff.
+3. **Ask the user to confirm**: Using the runtime's user-prompt tool, present the scan candidates and ask the user to confirm which files belong to this phase. For a parallel batch, include the `planned_files` from each phase's session state to assist attribution. If the scan surfaces files beyond any phase's `planned_files`, raise a blocker and surface the ambiguity to the user rather than silently attributing.
+4. **Reconcile**: Call `reconcile_phase(session_id, phase_id, files_created, files_modified, files_deleted, downstream_context, reason)` with the user-confirmed manifest. This clears `requires_reconciliation`.
+5. **Retry or advance**: If the user chose to retry the agent, re-delegate with the original scope plus the scan results as context. If the user accepted the work as delivered, advance to the next phase.
+
+Record all recovery events in session state with `{agent, timestamp, type: 'recovery', resolution: 'retry'|'reconciled'|'aborted'}`.
+
+### File Conflict Handling
+
+When a subagent reports a file conflict:
+
+1. Stop execution immediately
+2. Record the conflicting files and phases
+3. Do not attempt automatic merge resolution
+4. Ask the user how to proceed
+
+## Subagent Output Processing
+
+Native subagent results are wrapped. Do not assume the handoff begins at byte 0.
+
+### Parsing Rules
+
+1. Locate `## Task Report` (or `# Task Report`) inside the returned text
+2. Locate `## Downstream Context` (or `# Downstream Context`) inside the returned text
+3. Parse:
+   - status
+   - files created / modified / deleted
+   - downstream context fields
+   - validation result
+   - reported errors
+4. Persist the full raw output plus the parsed fields into session state
+
+### State Update Sequence
+
+After processing each handoff:
+
+1. Update the phase file manifests
+2. Update `downstream_context`
+3. Append any errors
+4. Aggregate token usage
+5. If validation passed, mark the phase `completed`
+6. If validation failed, trigger retry logic
+7. Update `updated`
+8. Advance or clear `current_batch` as each chunk finishes
+
+## Completion Protocol
+
+When all phases are completed:
+
+1. Verify there are no `failed` or `pending` phases
+2. Confirm plan deliverables are accounted for
+3. Run the final code-review gate for non-documentation changes
+4. Archive the session through `session-management`
+5. Present a final summary with deliverables, files changed, token usage, deviations, and review status