// Agent delegation best practices for constructing effective subagent prompts with proper scoping
Guides structured design conversations for complex engineering tasks
Phase execution methodology for orchestration workflows with error handling and completion protocols
Generates detailed implementation plans from finalized designs
Manages orchestration session state, tracking, and resumption
Run the Maestro debugging workflow for investigation-heavy tasks
Resume an interrupted Maestro session using the existing active-session file and shared phase tracking
| name | delegation |
| description | Agent delegation best practices for constructing effective subagent prompts with proper scoping |
Activate this skill when delegating work to subagents during orchestration execution. This skill provides the templates, rules, and patterns for constructing effective delegation prompts that produce consistent, high-quality results.
Before constructing any delegation prompt, inject the shared agent base protocol:
agent-base-protocol via get_skill_contentfilesystem-safety-protocol via get_skill_contentblocked_by, read phases[].downstream_context from session state and include it in the promptdownstream_context is missing, include an explicit placeholder noting the missing dependency context (never omit silently)The injected protocol ensures every agent follows consistent pre-work procedures and output formatting regardless of their specialization.
Every delegation prompt must include a context chain that connects the current phase to prior work:
Phase Context: Include Downstream Context blocks from all completed phases that the current phase depends on (identified via blocked_by relationships in the implementation plan and sourced from session state phases[].downstream_context):
Context from completed phases:
- Phase [N] ([agent]): [Downstream Context summary]
- Interfaces introduced: [list with file locations]
- Patterns established: [list]
- Integration points: [specific files, functions, endpoints]
- Warnings: [list]
Accumulated Patterns: Naming conventions, directory organization patterns, and architectural decisions established by earlier phases. This ensures phase 5 does not contradict patterns set in phase 2.
File Manifest: Complete list of files created or modified in prior phases, so the agent knows what already exists and can import from or extend those files.
Missing Context Fallback: If a blocked dependency has no stored downstream context, include a visible placeholder entry in the prompt:
- Phase [N] ([agent]): Downstream Context missing in session state — verify dependency output before implementation
Every delegation prompt must declare who will consume the agent's output:
Your output will be consumed by: [downstream agent name(s)] who need [specific information they require]
This primes the agent to structure their Downstream Context section for maximum utility to the next agent in the chain.
Before constructing any delegation prompt, resolve configurable parameters:
temperature, max_turns, timeout_mins, tools)MAESTRO_DISABLED_AGENTS, do not construct a delegation prompt — report to the orchestrator that the agent is disabledEvery delegation to a subagent must follow this structure:
Task: [One-line description of what to accomplish]
Progress: Phase [N] of [M]: [Phase Name]
Files to modify:
- /absolute/path/to/file1.ext: [Specific change required]
- /absolute/path/to/file2.ext: [Specific change required]
Files to create:
- /absolute/path/to/new-file.ext: [Purpose and key contents]
Deliverables:
- [Concrete output 1]
- [Concrete output 2]
Validation: [command to run after completion, e.g., "npm run lint && npm run test"]
Context:
[Relevant information from the design document or previous phases]
Do NOT:
- [Explicit exclusion 1]
- [Explicit exclusion 2]
- Modify any files not listed above
Always provide absolute file paths in delegation prompts. Never use relative paths or expect agents to search for files.
Define exactly what the agent should produce. Vague instructions like "implement the feature" lead to inconsistent results. Instead: "Create UserService class with createUser(), getUserById(), and deleteUser() methods implementing the IUserService interface."
Include the exact command(s) to run after completion. The agent should run these and report results. Examples:
npm run lint && npm run testcargo build && cargo testgo vet ./... && go test ./...python -m pytest tests/Never include interactive CLI commands in delegation prompts. Subagents run autonomously without user input. Interactive commands will hang indefinitely.
WRONG — Delegation prompt includes interactive scaffolding: "Run `npx create-next-app@latest . --typescript --tailwind`" "Run `npm init` to create package.json"CORRECT — Delegation prompt specifies direct file creation: "Create package.json with the following content: ..." "Create tsconfig.json, tailwind.config.ts, and src/app/layout.tsx directly"
Explicitly state what the agent must NOT do:
| Task Domain | Agent | Key Capability |
|---|---|---|
| System architecture, component design | architect | Read-only analysis, architecture patterns |
| Cloud architecture, multi-region topology | cloud-architect | Read-only cloud/IaC architecture |
| Enterprise integration architecture | solutions-architect | Read-only cross-team architecture |
| API contracts, endpoint design | api-designer | Read-only, REST/GraphQL expertise |
| Feature implementation, coding | coder | Full read/write/shell access |
| Code quality assessment | code-reviewer | Read-only, verified findings |
| Database schema, queries, ETL | data-engineer | Full read/write/shell access |
| RDBMS tuning, indexes, migration safety | database-administrator | Read + shell for database analysis |
| DB2 operations and tuning | db2-dba | Read + shell for DB2-specific work |
| Bug investigation, root cause | debugger | Read + shell for investigation |
| CI/CD, infrastructure, deployment | devops-engineer | Full read/write/shell access |
| Internal platforms, paved paths | platform-engineer | Full platform implementation access |
| B2B APIs, ETL, message brokers | integration-engineer | Full integration implementation access |
| SLOs, runbooks, reliability | site-reliability-engineer | Read + shell reliability analysis |
| Metrics, logs, traces, dashboards | observability-engineer | Full observability implementation access |
| Performance analysis, profiling | performance-engineer | Read + shell for profiling |
| Code restructuring, modernization | refactor | Read/write/shell, skill activation |
| Security assessment, vulnerability | security-engineer | Read + shell for scanning |
| Test creation, TDD, coverage | tester | Full read/write/shell access |
| Documentation, READMEs, guides | technical-writer | Read/write, no shell |
| Release notes, changelogs, rollout | release-manager | Read/write for release artifacts |
| Technical SEO auditing | seo-specialist | Read + shell + web search/fetch |
| Marketing copy, content writing | copywriter | Read/write |
| Content planning, strategy | content-strategist | Read + web search/fetch |
| User experience design | ux-designer | Read/write + web search |
| WCAG compliance auditing | accessibility-specialist | Read + shell + web search |
| Requirements, product strategy | product-manager | Read/write + web search |
| Tracking, measurement | analytics-engineer | Full read/write/shell access |
| Internationalization | i18n-specialist | Full read/write/shell access |
| Design tokens, theming | design-system-engineer | Full read/write/shell access |
| Legal, regulatory compliance | compliance-reviewer | Read + web search/fetch |
| Mobile platform work | mobile-engineer | Full mobile implementation access |
| Model training and inference integration | ml-engineer | Full ML implementation access |
| Model operations and model CI/CD | mlops-engineer | Full MLOps implementation access |
| Prompt design, few-shot, RAG tuning | prompt-engineer | Read/write prompt and eval design |
| Mainframe COBOL, JCL, CICS/IMS | cobol-engineer | Full mainframe implementation access |
| IBM HLASM for z/OS | hlasm-assembler-specialist | Full assembly implementation access |
| IBM i RPG/CL, DB2 for i | ibm-i-specialist | Full IBM i implementation access |
| z/OS systems programming, JCL, RACF | zos-sysprog | Read + shell for z/OS system work |
Delegate to the assigned agent using the dispatch pattern from get_runtime_context (loaded at session start, step 0). Every Maestro agent in the Agent Roster carries its frontmatter configuration:
temperature: Controls output determinism (e.g., coder uses 0.2 for precise code)max_turns: Prevents runaway sessions (e.g., 25 turns for implementation agents)tools: Restricts the agent to its authorized tool surface (e.g., read-only agents cannot use file-writing tools)Using a generic/default agent tool bypasses all of this — it uses default temperature, has no turn limit, no tool restrictions, and no specialized methodology. Never use a generic agent tool for Maestro phase delegations.
Every delegation must include the required header fields:
Agent: <agent_name>
Phase: <id>/<total>
Batch: <batch_id> (or "single" for sequential)
Session: <session_id>
Sequential dispatch: Invoke the agent using your runtime's dispatch mechanism with the full delegation prompt.
Parallel dispatch: Emit contiguous agent dispatch calls in a single turn for all agents in the ready batch. Each call includes the same header format with the shared batch ID.
Call get_agent with the agent name (as it appears in the implementation plan or Agent Roster) to load the agent methodology body, declared tool restrictions, and the runtime-specific tool_name. Use the returned tool_name as the dispatch target when invoking the agent tool. Runtime-local agent files remain registration stubs only; do not rely on them for the full methodology body.
Parallel delegation uses the runtime's native subagent scheduler. The orchestrator emits contiguous agent tool calls inside a single turn; it does not write prompt files, spawn subprocesses, or call shell-based dispatch helpers.
For each agent in a ready batch:
Agent: <agent_name>Phase: <id>/<total>Batch: <batch_id>Session: <session_id>Native parallel batches may pause if an agent asks a follow-up question. Scope prompts tightly enough that questions are rare.
Maestro enforces tool permissions at two levels:
Level 1: Native enforcement (primary)
Tool permissions are enforced natively via each agent's registered frontmatter stub. Use the tools array returned by get_agent when you mirror that restriction in the prompt. This works for both sequential and parallel delegation.
Level 2: Prompt-based enforcement (defense-in-depth)
Native tool permissions remain the primary boundary. As defense-in-depth, every delegation prompt should still include an explicit tool restriction block so the agent sees its allowed surface in plain language.
agent-base-protocol via get_skill_content)filesystem-safety-protocol via get_skill_content)The tool restriction block template:
TOOL RESTRICTIONS (MANDATORY):
You are authorized to use ONLY the following tools: [list from agent frontmatter].
Do NOT use any tools not listed above. Specifically:
- Do NOT use `write_file` or `replace` unless explicitly authorized above
- Do NOT use `run_shell_command` unless explicitly authorized above
- Do NOT create, modify, or delete files unless authorized above
Violation of these restrictions constitutes a security boundary breach.
Populate the tool list from the tools array returned by get_agent for the delegated agent.
The file writing rules block template:
FILE WRITING RULES (MANDATORY):
Use ONLY `write_file` to create files and `replace` to modify files.
Do NOT use `run_shell_command` with cat, echo, printf, heredocs, or shell redirection (>, >>) to write file content.
Shell interpretation corrupts YAML, Markdown, and special characters. This rule has NO exceptions.
This block reinforces the Agent Base Protocol's File Writing Rule directly in every delegation prompt, ensuring agents see the prohibition even if they skim the injected protocols.
When delegating to multiple agents in parallel, ensure no two agents are assigned the same file. Each file must have exactly one owner in a parallel batch.
All agents in a parallel batch must complete before:
Maestro hooks fire at agent boundaries during delegation, providing context injection and output validation. Understanding hook behavior is essential for constructing correct delegation prompts.
Before each agent dispatch, a hook tracks which agent is currently executing:
Agent: <agent_name> header in the delegation promptMAESTRO_CURRENT_AGENT from the environment, then regex-based detection of patterns like delegate to <agent> or @<agent>The detected agent name is persisted to ${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/active-agent and cleared by the post-delegation hook on every allowed response (both successful validation and retry allow-through). On deny (malformed output), the active agent is preserved to enable re-validation on retry.
When an active orchestration session exists, the pre-delegation hook parses <MAESTRO_STATE_DIR>/state/active-session.md and injects a compact context line into the agent's turn:
Active session: current_phase=3, status=in_progress
This gives delegated agents awareness of where they sit in the orchestration workflow without requiring explicit context in every delegation prompt. The injection is automatic and requires no action from the orchestrator.
After completion, the post-delegation hook validates that every subagent response contains both required handoff sections:
## Task Report (or # Task Report)## Downstream Context (or # Downstream Context)If either heading is missing:
stop_hook_active=true, mapped to stopHookActive in JS): The hook allows the malformed response through to prevent infinite retry loops, logging a warning.This enforcement is the runtime complement to the Output Handoff Contract defined in the agent-base-protocol. Delegation prompts do not need to re-state the retry mechanism — the hook handles it transparently.
Exception: The TechLead/orchestrator agent is excluded from validation. Only delegated subagents are subject to format enforcement.
Read delegation.constraints from get_runtime_context before constructing any agent dispatch. Apply constraints to the dispatch:
fork_full_context_incompatible_with: list of field names. If the runtime is invoking a fork-style delegation with full-history inheritance, do NOT pass any of these fields. For Codex, this means omitting agent_type, model, and reasoning_effort whenever fork_context: true or fork_turns: "all" is used.result_surface: "synchronous": the parent receives the child's full text response in the dispatch return value. Parse the Task Report and Downstream Context directly from that text.result_surface: "deferred": the parent receives only identifiers. The parent MUST poll for completion (wait_agent or equivalent) with a bounded timeout. On timeout or empty return, invoke the Recovery Protocol in the execution skill.child_cannot_prompt_user: true: child agents cannot call the user-prompt tool. All user questions must surface through the Blocker Protocol below.MANDATORY when delegation.constraints.child_cannot_prompt_user is true (Codex today). RECOMMENDED uniformly so the orchestrator remains the single approval point across runtimes.
Every agent's Task Report may include a ## Blockers section, placed between ## Task Report and ## Downstream Context:
## Blockers
- BLOCKER: [question the agent cannot resolve]
Context: [why this question arose]
Required to proceed: [what answer unlocks continuation]
When parsing an agent response:
## Blockers is present and non-empty, do NOT call transition_phase. Keep the phase in_progress.An agent that returns neither a handoff nor a blocker is considered incomplete. Invoke the Recovery Protocol in the execution skill.
coder, data-engineer, devops-engineer)Validation: [build command] && [lint command] && [test command]
refactor)Validation: [build command] && [test command]
Verify: No behavior changes — all existing tests must still pass
tester)Validation: [test command]
Verify: All new tests pass, report coverage metrics
architect, api-designer, code-reviewer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist, content-strategist, compliance-reviewer)Validation: N/A (assessment-only — no write tools)
Verify: Findings reference specific files and line numbers
technical-writer, copywriter)Validation: Verify all links resolve, code examples are syntactically valid
ux-designer, product-manager)Validation: N/A (design and requirements artifacts)
Verify: Deliverables reference user needs and acceptance criteria
analytics-engineer, i18n-specialist, design-system-engineer)Validation: [build command] && [lint command] && [test command]
Verify: Domain-specific integration validated (tracking fires, locales render, tokens apply)