jaktestowac/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:

| Role | Scope | Tools | | --- | --- | --- | | Orchestrator | Delegates, synthesizes, never implements | read, agent, search, edit | | Explorer | Gathers facts, returns findings, writes no product code | read, search, web, edit | | Planner | Turns findings into a prioritized plan | read, search, edit | | Implementer | Writes and runs code within the plan | vscode, execute, read, edit, search | | Reviewer | Judges the output, did not write it | read, search, edit | | Runner and verifier | Executes, diagnoses, reports status | vscode, execute, read, edit, search |

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.

Phase 5: Write the README

Every pack needs one, with frontmatter carrying a description for the README generator. It contains:

• what the pack does, in one paragraph
• an agent-and-role table
• the typical flow, including which steps run in parallel
• installation: copy the *.agent.md files into the user prompts directory or .github/agents/
• prerequisites: MCP servers, specs, environments
• the output contract
• a pointer to a lighter variant if one exists

Phase 6: Validate

npm run lint       # frontmatter, orchestration, plugin sync
npm run generate   # regenerate the README tables
npm run check      # verify the README is in sync

Then run the pack against a real task. The failures that only appear in a live run:

• an orchestrator that starts implementing when a subagent returns something incomplete
• a subagent that lacks a tool it needs and reports success anyway
• a handoff prompt too vague for the subagent to act on
• two agents doing the same work because their scopes overlap
• a packet whose Gaps section is always empty, which means the agents are not using it

Use ./resources/orchestration-quality-checklist.md before shipping.

Common Failure Modes

• an orchestrator that implements, filling its context and defeating the split
• a handoff naming an agent that does not exist in the pack, which is the lint's hard error
• agent names duplicated across packs, so installing two packs breaks both
• every agent granted every tool, removing the safety the split provides
• subagents returning free-form prose in different shapes
• a reviewer that also implements, so the review approves its own work
• five agents where two would do
• no README, so nobody can install it or knows the Playwright MCP prerequisite
• artifacts written to the repository root instead of .ai-outputs/

Resource Map

• ./resources/orchestration-pack.template.md - a complete minimal pack: orchestrator plus two subagents plus README, ready to copy
• ./resources/handoff-packet.md - the output contract, section by section, with a worked example and the common ways it degrades
• ./resources/orchestration-quality-checklist.md - pre-ship checks covering naming, tools, handoffs, contract, and the live-run failures

Related Skills

• creating-custom-agents - when one agent is the right answer, or for writing each agent file in the pack
• creating-skills - when the expertise belongs in a skill the agents reference rather than in an agent body
• creating-prompts - when the entry point should be a prompt that routes to the orchestrator
• creating-plugins - when the pack should ship as an installable plugin
• creating-instructions - for conventions that should apply to every agent rather than one

Definition of Done

This skill is complete when:

• a pack is justified: at least two of the Phase 0 conditions hold, and a single agent was genuinely considered
• every role has a scope no other role has
• the orchestrator delegates only, and is the only agent with 'agent'
• every handoffs[].agent and agents[] entry exactly matches a name: in the same pack
• agent names are unique across every pack in the repository
• tool grants are minimal per role, and agents that run commands have 'execute'
• every subagent returns the same handoff packet shape, including a Gaps section
• artifacts are written to .ai-outputs/
• the README covers agents, flow, installation, prerequisites, and the output contract
• npm run lint, npm run generate, and npm run check pass
• the pack has been run against a real task, not only linted