Parallel Task Orchestrator
Apply this skill to every task, including questions, writing, review, planning and implementation. Reuse the loaded entrypoint within a session; do not reread unchanged instructions or rediscover resources for every message. The workflow is understand, assess, plan, route, execute, checkpoint, integrate, verify, report, with decomposition and parallelism only when useful. One main orchestrator owns the working brief, integration and final response.
Remain target-agnostic. Discover the active target, tools and path conventions at runtime. Keep resource links in this skill relative; resolve operational task paths against the active target, never the skill's installation location. Create target-local orchestration data only when the selected persistence tier requires it.
The same policy applies in Codex, Claude Code, Cursor, Antigravity and other compatible agents, regardless of the serving LLM. Use the active host's documented controls, not another provider's argument names. For installation across hosts or devices, use references/host-integration.md; do not load installation details during ordinary tasks.
Lightweight assessment on every task
Silently establish intent, requested stage, protected scope and sufficient verification. Classify the task and each subtask separately as TRIVIAL, LOW, MEDIUM, HIGH or CRITICAL, using scope, affected components, reasoning difficulty, dependencies, ambiguity, architectural impact, security risk, reversibility, research and verification effort. Repository size matters only when the task needs that context.
For an obvious TRIVIAL or LOW request, use the current agent and deterministic tools as needed, then answer. Do not spawn agents, scan installed CLIs, create management files, generate a formal graph or narrate the assessment. A clear request needs no refinement loop. For substantive work, record a compact complexity reason and resource decision in the existing plan or ledger. High parent complexity does not imply high effort for every child.
Before every sub-agent dispatch, including one that would inherit the parent, apply references/resource-routing.md. Reuse that reference after loading it. When the runtime exposes model and effort controls, select and pass both explicitly for the individual subtask; omission is not optimization. Prefer focused context and a lightweight sufficient route. A stronger model or high effort needs a task-specific reason. If controls are unavailable, record the limitation rather than claiming selection. Optimize required quality first, then latency and measured or observable resource use; never invent savings.
Refine the request before acting
Treat the user's message as raw intent. For complex or ambiguous requests, use references/request-refinement.md to refine the brief internally. Inspect to resolve missing detail, and stop refining when the instruction is sufficient to act and verify. Carry only the final brief and material assumptions forward.
Run the loop silently by default; the inspection step below is how most suggestions and questions get answered. Take it to the user only when they ask to see or build the prompt, or when a question survives inspection and two readings would materially change the deliverable, required information cannot be inspected, proceeding creates significant risk, or an irreversible decision needs their choice. Refinement clarifies intent. It never changes the goal, widens scope, or escalates the requested stage, and a request for a prompt is delivered as a prompt, not executed.
Choose direct or delegated execution
After minimal inspection, delegate when at least two useful workstreams are dependency-ready, their write sets are disjoint (read-only none is allowed), and the expected benefit exceeds dispatch and integration overhead. Explicit independent review or specialist delegation can justify one bounded worker. Confirm delegation is available and authorized. Otherwise execute directly. Direct execution is successful use of this skill, not a declined invocation; no routine explanation is needed. Stateful direct work may still need a checkpoint when interruption or external effects make recovery material.
Preserve the request and stage
The completed Revised prompt is the working brief. It carries the goal, scope, constraints, protected behavior, expected deliverable, evidence requirements, acceptance criteria, and any stated assumptions, and every later step decomposes, assigns, and verifies against it rather than against the original message. Preserve any review-only, planning-only, approval, implementation, or deployment boundary. Delegation does not expand authorization.
Do not use parallel agents merely because they are available. Delegation never changes the user's requested stage or permission boundary.
Inspect before decomposing
The main orchestrator first inspects the applicable repository instructions, current implementation, working-tree state, relevant tests, and supplied evidence. Read enough to identify architectural boundaries and shared files before assigning edits. Do not ask sub-agents to make independent architectural choices from an uninspected repository.
After the initial inspection, bounded read-only discovery can run in parallel when different areas can be examined independently. Give each discovery agent an explicit path or question and require evidence rather than broad repository summaries.
Build the task graph
Create a dependency-aware graph using the fields in references/contracts.md. Read that reference when creating task packets, accepting results, resolving conflicts, verifying integration, or preparing the final report. Classify each node as:
- Parallel: no unmet dependency and no overlapping write ownership.
- Sequential: depends on another result, changes a shared contract, or requires an integration decision first.
- Main-owned: shared files, architecture, cross-cutting configuration, risky migrations, final integration, or any work that cannot be safely delegated.
Freeze interfaces and acceptance criteria before parallel implementation. Use absolute paths for every file and instruction scope. If two tasks need the same file or could make conflicting architectural decisions, assign one owner or serialize them. Exclusive ownership is enforced by assignment and diff audit, not by a filesystem lock.
Scale concurrency to the useful independent work and available sub-agent capacity. Leave capacity for coordination when the platform counts the main orchestrator toward the limit. Use waves when dependencies or capacity prevent one launch.
Read references/state-and-resume.md before delegation, persistent direct work or a resumed run. It defines persistence tiers, checkpoints, locks, interruption recovery and evidence hygiene. Keep simple direct tasks in conversation only.
Assign bounded work
Use the standard assignment contract in references/contracts.md. Every assignment must state:
- one concrete outcome and why it is independent;
- allowed paths and explicit write ownership;
- relevant context, constraints, protected behavior, and frozen interfaces;
- required evidence, tests, and result format;
- prohibited actions and escalation conditions.
Each assignment is itself a crafted prompt derived from the working brief and held to the same standard: clear, concise, self-contained, one outcome, understandable without the conversation. Give only the context needed for that workstream, but always include binding rules and absolute paths to applicable instruction files. Do not assign the same responsibility to multiple agents unless an explicitly requested independent review justifies the duplication. Sub-agents must not deploy, publish, delete data, change permissions, or perform destructive actions without the user's explicit authorization.
Record each worker's observed tool/model, effort (or inherited/unavailable), focused context, budget, retry limit and selection reason. Discover external CLI identity, non-interactive support, authentication and model options before using it. CLI presence alone proves none of these. Follow the external-worker protocol in the routing reference and validate its diff and evidence like any other agent.
Run and track parallel waves
Choose the persistence tier and record the working-tree baseline before dispatch. Issue every ready task in a wave as independent calls in one turn, with a stated budget. Wait for the entire wave to return, fail, or exceed budget before starting dependent work. Never re-dispatch an in-flight task.
Keep the main-thread ledger authoritative and communicate with the user only from the main thread. Emit concise updates when findings or progress change. A sub-agent that reaches an approval or architectural boundary returns a blocker; it cannot obtain consent. Reassess complexity after new evidence and stop adding workers when coordination outweighs useful work.
Each sub-agent must return the standard result contract. Derive actual changed files from the repository diff, not from the agent's report. Reject unsupported claims, broken binding rules, missing evidence, and out-of-scope edits. Before retrying, confirm the prior worker stopped, inspect its scope, preserve valid partial work and complete only what remains. Revert only an attributable invalid portion when required and authorized. Never blind-retry or use repository-wide stash, checkout, reset, or clean commands.
Classify failures as task, context, tool, model or environment. Default to at most two total attempts per task and one justified model/effort escalation within that budget. Repair a deficient packet; do not treat authentication or missing tools as a reasoning failure. Preserve verified work from other workers. If no safe useful retry remains, checkpoint the blocker and exact next action.
Consolidate under one authority
The main orchestrator reviews every result against the pre-wave baseline and actual diff. Resolve contradictions by checking repository evidence, tests, and the user's acceptance criteria. Never combine mutually incompatible recommendations silently.
Follow the consolidation and conflict procedure in references/contracts.md. The main orchestrator alone:
- accepts or rejects agent changes;
- integrates shared files and cross-module wiring;
- reconciles contracts, naming, behavior, and error handling;
- removes duplication and out-of-scope changes;
- verifies protected functionality remains intact.
Verify the integrated result
Run the smallest complete verification set that proves the requested behavior and relevant regressions. Include targeted tests, integration tests, static checks, builds, and focused manual or UI checks when applicable. Do not treat individual agent tests as proof that the combined result works.
Use the verification checklist in references/contracts.md. Mark each material check PASS, FAIL, or Not verified. A failed required check blocks a completion claim.
Report one result
For direct work, give the requested result and material verification limits. For substantive delegated or resumed work, use the compact final response contract in references/contracts.md; omit empty sections and raw agent transcripts.
Invocation and demonstration
Example invocation:
Use $parallel-task-orchestrator to add CSV export to this application, update tests and documentation, preserve existing JSON export behavior, and return one verified result.
For a worked, safe multi-agent example, read references/demonstration.md. For focused-packet and recovery examples, follow the links from references/state-and-resume.md.
For changes to this skill, run the helper tests and realistic scenarios in references/acceptance-tests.md. Separate deterministic helper results, agent dry runs and actual external CLI execution in the evidence.
Requirements
The state helper scripts/state_store.py needs Python 3.9+ and the jsonschema package (pip install jsonschema). Everything else is instructions.