execution — Claude Code skill: what it does, how to install
Controls implementation phase execution in Maestro orchestration workflows using native subagent delegation.
Apache-2.0 ★ 489 updated 2026-10-26
npx skills add josstei/maestro-orchestrate --skill execution -a claude-codeWhat execution does
The skill activates during Phase 3 of Maestro orchestration to guide plan execution. It enforces an execution mode gate that records either sequential or parallel mode into the session state before any subagent work begins. When MAESTRO_EXECUTION_MODE is set to ask, it inspects the plan structure, dependency depths, and file ownership.
Phases that touch identical files cannot run at the same time, so the skill strips them from parallel batches. If only one phase is ready, it skips user prompting and executes sequentially. Parallel runs chunk tasks using MAESTRO_MAX_CONCURRENT and emit child agent tool calls in a single turn without interleaved shell operations.
Subagents dispatched natively run without per-action approval prompts. If a session gets interrupted, unfinished phases marked in_progress restart from scratch upon resume.
What it helps with
- Select sequential or parallel phase execution modes
- Block concurrent execution on overlapping file targets
- Dispatch ready batches across native subagents
- Handle interrupted phases when resuming an orchestration run
Example prompts for the agent
- Execute the approved Maestro plan phases
- Dispatch the next ready batch using native subagents
- /maestro:execute
How to install execution
1Skills CLI (Vercel)
npx skills add josstei/maestro-orchestrate --skill execution -a claude-code2Manually: put the files in place
~/.claude/skills/execution/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/execution/
1Skills CLI (Vercel)
npx skills add josstei/maestro-orchestrate --skill execution -a codex2Manually: put the files in place
.agents/skills/execution/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add josstei/maestro-orchestrate --skill execution -a cursor2Manually: put the files in place
.cursor/skills/execution/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install josstei/maestro-orchestrate antigravity/src/skills/shared/execution2Manually: put the files in place
.github/skills/execution/SKILL.md1Skills CLI (Vercel)
npx skills add josstei/maestro-orchestrate --skill execution -a gemini-cli2Platform CLI
gemini skills install https://github.com/josstei/maestro-orchestrate --path antigravity/src/skills/shared/executionManually: put the files in place
.devin/skills/execution/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about execution
How to install execution in Claude Code?
Run npx skills add josstei/maestro-orchestrate --skill execution -a claude-code in your terminal. This writes the skill definition to ~/.claude/skills/execution/SKILL.md.
What does the execution skill do?
It manages phase transitions, verifies dependency resolution, checks file ownership collisions, and coordinates subagent handoffs during plan execution.
When does the skill force sequential execution?
It automatically enforces sequential execution if workflow_mode is set to express, if shared files conflict between tasks, or if one or fewer parallelizable phases remain.
Source text
SKILL.md · Apache-2.0
---
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. Do not default to sequential.
</HARD-GATE>
### Recording the mode
If no session exists yet (orchestrate step 21, or `/maestro:execute` before session creation), pass `execution_mode` to `create_session`, which sets `execution_backend: 'native'` itself. If a session already exists (resume), call `update_session` with `{ execution_mode, execution_backend: 'native' }`.
### Step 1 — Read the configured mode
Read `MAESTRO_EXECUTION_MODE` (default: `ask`).
- If `parallel`: record `parallel` (see Recording the mode). Skip to delegation.
- If `sequential`: record `sequential` (see Recording the mode). 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 Step 4 question.
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**. Record `sequential` (see Recording the mode). 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` as a single-choice prompt 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 using the user-prompt tool from runtime context; in the question text, state the Step 2 counts (parallelizable phases out of total, number of batches) and any overlapping-file warnings.
### Step 5 — Record and proceed
1. Record the selected `execution_mode` (see Recording the mode)
2. 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
## 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
## Error Handling Protocol
Record all errors in session state using the session-management Error Recording Format.
### 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
### Recovery Protocol
When a subagent terminates early, times out, returns malformed output, or when `delegation.constraints.result_surface` is `deferred` or `notified` 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 notified-result runtimes (Antigravity), the child's final response arrives as a message; there is nothing to poll, so if it never arrives, list the runtime's subagents (`manage_subagents` with `Action: "list"`) to check whether the child is still running. 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
© josstei · Apache-2.0 · josstei/maestro-orchestrate