role-orchestrator

Provides: Delegation routing, agent selection, quality gates, escalation rules, and compaction recovery for orchestrating subagents.

Quick Reference

Delegate when work is independent, specialized, read-only discovery, or too large for one focused pass.

Do it directly when the task is small, local, or easier than writing a precise delegation prompt.

Quality rule: review every delegated result before acting on it.

Never: run two read-write delegations at once, or assume a subagent inherited your skills and store context.

Host tools: Before delegating in Pi, read the Pi tool mapping and use its native task and todo forms instead of the OpenCode-style examples in the templates. If store tools are unavailable, omit store calls and keep complete context in TODO descriptions or the conversation. Do not create substitute repository files.

Routing

Escalate to pattern-orchestration-complex when two or more of these hold: 4+ files affected, more than 60 minutes, multiple sequential phases, cross-cutting or security-critical changes, unclear approach, or architectural decisions required.

Agent Selection

Match the work to the cheapest agent that can do it reliably:

Explorer constraints: Explorer is read-only with bash denied. Do not put shell commands or execution instructions in an Explorer prompt; it has only grep, glob, list, and read. Ask for a summary plus file paths and line ranges, never full file contents. If you need the content, read the identified ranges yourself afterwards.

Read the Explorer delegation template and the standard delegation template for the exact call shapes.

Delegation Contents

Every delegation states the skills to load, the requirements, and verifiable success criteria. Subagents do not inherit your loaded skills or store items, so name them explicitly.

Match skills to the task: role-developer and standards-code for implementation, standards-security or role-security-auditor for security-critical work, role-qa-engineer and standards-testing for tests, role-architect for structure, role-code-review for review, role-technical-writer for docs, pattern-task-breakdown for planning, standards-analysis for problem decomposition and trade-off analysis.

For context continuity across phases, extract session_id from the first result and pass it to later delegations. Read the multi-phase delegation shape.

Quality Gate

After every delegated task, check:

• Did it answer the exact question, or complete the exact requirement?
• Are file paths, commands, and assumptions concrete rather than plausible?
• Did it respect read and write boundaries and avoid forbidden actions?
• Are tests or verification results present where needed?
• Do the findings require user approval before implementation?

When a result fails: give targeted feedback once, escalate to a more capable agent once, then split the task or ask the user. Do not loop a third time on the same framing.

Compaction Recovery

Subagents can hit context compaction mid-task. Detect it from a compaction marker in the result, explicit statements about lost context, incomplete work despite a full response, or requirements silently dropped.

To recover:

• Reuse the original session_id to keep the surviving context.
• Force a store reload. Store items are not restored after compaction.
• Summarize progress rather than repeating the original prompt, so work is not duplicated.
• Limit to two automatic recovery attempts, then escalate to the user or split the task.

Read the compaction recovery template for the exact call shape.

The same applies to your own context. Call storeread() with no ID to list available items, then load only the relevant ones, which restores continuity without bloating context. Do this at the start of a session, after a compaction, when the user references past work or decisions, and before planning multi-session work.

TODO and Store Usage

Use TODO only for genuinely multi-step work. Mark items in_progress when starting and completed immediately on finishing, and keep completed items rather than deleting them.

Use storewrite and storepatch for durable plans, decisions, schemas, and context that must survive compaction. Do not store scratch notes.

Store items are never auto-loaded. When you see Load store: or [store:<id>], call storeread({ id: "<id>" }) before proceeding, and verify subagents did the same. Read the store and TODO call shapes for the exact code, and see pattern-task-breakdown for the canonical prompt_drafts shape.

For long plans, store plain task prompts and TODO descriptions rather than client-specific tool blocks, so any agent can execute them.

Checklist

Before finishing orchestration:

• Each delegation named its skills, requirements, and success criteria
• Every delegated output was reviewed, not accepted on faith
• Read-write delegations ran serially
• All TODO items are updated or intentionally left open
• Verification ran, or skipped checks are stated with reasons
• The user gets a concise final summary in chat, with no new summary files

Integration with Other Skills

With pattern-orchestration-complex: load it when two or more complexity indicators are present, and follow its workflow instead of direct delegation.

With pattern-task-breakdown: produce the plan that feeds TODOs and stored prompt_drafts. Skip it for one or two step tasks.

With tool-store: detailed store operations and durable decision records.

With role-code-review and role-qa-engineer: delegate the independent verification pass.