Creating Orchestration Packs

Creating Orchestration Packs

Use this skill when a job is too big for one custom agent and splitting it into cooperating roles would produce better work rather than just more files.

A pack is a folder of .agent.md files plus a README, living under agent-orchestration/. One agent orchestrates and delegates; the rest do the work and return a structured handoff packet. The orchestrator synthesizes.

The value comes from the same place it comes from in human teams: an agent with a narrow scope and a clear output contract does better work than one asked to do everything. The cost is coordination, and a pack that costs more coordination than it saves is worse than a single good agent.

When to Use

• a workflow has genuinely distinct phases with different tool needs
• one agent's instruction file has grown into several unrelated roles
• explore, plan, implement, review, and verify would each benefit from a fresh, narrow context
• two branches of work could run in parallel and be merged
• an existing pack fails npm run lint because a handoff target does not resolve

Operating Principles

• A role earns its file. Each agent has a scope another agent does not, or it should be merged.
• The orchestrator delegates and never implements. The moment it writes code, its context fills and the pack collapses into one agent with extra steps.
• Every handoff target resolves. handoffs[].agent and agents[] entries must exactly match a name: in the same pack. CI enforces this.
• Tools are granted per role, minimally. An explorer that cannot write files cannot accidentally write files.
• One output contract, shared by every agent. Mixed return shapes make the orchestrator's synthesis unreliable.
• Names are unique across packs, because users install more than one.

Workflow

Phase 0: Check that a pack is the right shape

A pack is justified when at least two of these hold:

• the phases need different tools, and granting the union to one agent would be over-privileged
• a phase benefits from a fresh context rather than one carrying everything before it
• two phases could genuinely run in parallel
• a review step is more useful when it did not write the thing it reviews
• the workflow is long enough that one agent would lose the early instructions by the end

When only one holds, write a single custom agent instead and hand off to creating-custom-agents. A three-agent pack for a two-step job is coordination overhead with no return.

Phase 1: Cut the roles

Split by what the role needs and what it produces, not by topic.

The pattern that works, from the packs already in this repository:

Two rules that decide the cut:

• the reviewer must not be the implementer, or the review is a self-assessment
• explorers write findings, never product code, which is why their grant excludes execute

Phase 2: Grant tools per role

Use the canonical grouped vocabulary: 'vscode', 'execute', 'read', 'edit', 'search', 'web', 'agent', 'todo', plus 'playwright/*' for Playwright MCP.

The lint applies heuristic checks and warns when:

• an agent told to run tests or commands has no 'execute'
• an agent told to write files or documents has no 'edit'

Note that 'edit' is needed by nearly every agent in practice, because agents write their handoff artifacts to disk. An explorer that returns a summary file needs 'edit' even though it writes no product code.

Only the orchestrator gets 'agent'. A subagent that can spawn subagents produces a tree nobody can follow.

Declare a Playwright MCP dependency in the README. An agent with 'playwright/*' and no configured MCP server fails in a way that looks like a pack defect.

Phase 3: Wire the handoffs

The orchestrator declares both lists:

agents:
  - OpenAPI Explorer
  - Test Planner
handoffs:
  - label: Explore OpenAPI
    agent: OpenAPI Explorer
    prompt: Analyze the OpenAPI spec and return a Handoff Packet.
    send: false

The rule CI enforces, in scripts/lint-orchestration.js: every handoffs[].agent and every agents[] entry must exactly match a name: declared by an agent in the same pack. Exact match, including spaces, capitalization, and punctuation. FE Explorer (Playwright MCP) and FE Explorer are different agents, and the second one does not exist.

Subagents declare agents: [] and user-invocable: false. Only the orchestrator is entered directly.

Phase 4: Fix the output contract

Every subagent returns the same shape. Without this, the orchestrator is synthesizing across incompatible outputs and its summary becomes guesswork.

The house contract is the Handoff Packet:

• Objective - what this agent was asked to do
• Inputs - what it received and what it went and found
• Findings - what it learned
• Decisions - what it chose, and why
• Artifacts - files written, with paths
• Gaps - what it could not determine
• Risks - what the next agent should watch for
• Next action - what it recommends happens next

Gaps is the one that carries weight. Without it, a subagent that could not determine something produces a confident summary and the orchestrator propagates the confidence.

Artifacts go to .ai-outputs/, per the repository convention.