Skip to content

jaktestowac/awesome-copilot-for-testers / plugins/creating-orchestration-packs/skills/creating-orchestration-packs

creating-orchestration-packs

Verified

Creates agent orchestration packs: cooperating `.agent.md` files with an orchestrator, subagents, matched handoffs, minimal tool grants, and a shared handoff packet contract. Use when one agent role is too broad for a job, when a workflow needs explore, plan, implement, review, and verify as separate roles, or when a pack fails the orchestration lint because a handoff target does not resolve.

resources/orchestration-quality-checklist.md

View on GitHub
# Orchestration Pack Quality Checklist

Run before shipping a pack.

## Justification

- [ ] At least two Phase 0 conditions hold: different tool needs, fresh context per phase, genuine parallelism, review independence, or length
- [ ] A single custom agent was considered and rejected for a stated reason
- [ ] Every agent has a scope no other agent in the pack has
- [ ] No role exists only because the workflow diagram had a box for it

The last one catches the three-agent pack for a two-step job.

## Naming

- [ ] Every `name:` is unique across **every** pack in `agent-orchestration/`, not only within this one
- [ ] Names are suffixed or scoped where a collision is plausible
- [ ] The folder name describes the workflow, not the domain
- [ ] Agent names read as roles ("Test Planner"), not as commands ("Plan Tests")

Check for collisions:

```bash
grep -rh '^name:' agent-orchestration/ | sort | uniq -d
```

Any output is a collision that will break for a user who installs both packs.

## Wiring

- [ ] Every `handoffs[].agent` exactly matches a `name:` in this pack
- [ ] Every `agents[]` entry exactly matches a `name:` in this pack
- [ ] Matches are exact: spaces, capitalization, parentheses, ampersands
- [ ] Only the orchestrator declares non-empty `agents:`
- [ ] Subagents declare `agents: []` and `user-invocable: false`
- [ ] The orchestrator declares `user-invocable: true`
- [ ] `npm run lint` passes

`scripts/lint-orchestration.js` hard-fails on an unresolved handoff. It cannot check that the handoff prompt is useful; that is the live-run test below.

## Tools

- [ ] Each grant is the minimum the role needs
- [ ] Only the orchestrator has `'agent'`
- [ ] Every agent that runs commands or tests has `'execute'`
- [ ] Every agent that writes a file, including its own artifact, has `'edit'`
- [ ] No explorer or analyst has `'execute'`
- [ ] Any `'playwright/*'` grant is matched by an MCP prerequisite in the README
- [ ] Uses the grouped vocabulary: `'vscode'`, `'execute'`, `'read'`, `'edit'`, `'search'`, `'web'`, `'agent'`, `'todo'`

The `'edit'` case catches people out: an analyst that writes `.ai-outputs/summary.md` needs it even though it writes no product code.

## Output contract

- [ ] Every subagent's body names the Handoff Packet sections
- [ ] The sections are identical across every subagent
- [ ] `Gaps` is required, and the body says uncertainty goes there rather than into a hedge
- [ ] `Artifacts` requires paths
- [ ] Artifacts are written to `.ai-outputs/`
- [ ] The orchestrator's body says what its final summary contains
- [ ] The orchestrator is instructed to send an incomplete packet back rather than fill it in

## Scope boundaries

- [ ] The orchestrator's body states plainly that it does not implement
- [ ] Any reviewer role is separate from the implementer role
- [ ] Each agent has a "what this does NOT do" statement
- [ ] No agent is instructed to merge, push, or deploy unless that is the pack's declared purpose

## README

- [ ] Frontmatter carries a `description` for the README generator
- [ ] Agent-and-role table
- [ ] Typical flow, naming which steps run in parallel
- [ ] Installation instructions covering both the user prompts directory and `.github/agents/`
- [ ] Prerequisites: MCP servers, specs, environments, accounts
- [ ] The output contract
- [ ] A link to a lighter variant if one exists

## Repository checks

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

All three pass before the pull request.

## The live run

Lint proves the wiring resolves. Only a run proves the pack works. Run it against a real task and watch for:

- [ ] **The orchestrator stayed out of the work.** If it started implementing, either a subagent returned something too thin or the orchestrator's instruction is too weak.
- [ ] **Every subagent returned a complete packet.** An always-empty `Gaps` section across the run means the contract is decorative.
- [ ] **No two agents did the same work.** Overlapping scopes show up as duplicated findings.
- [ ] **Every handoff prompt was actionable.** A subagent that had to ask what it was for has a prompt problem, not a capability problem.
- [ ] **The parallel steps were genuinely independent.** If one waited on the other's output, they were not parallel.
- [ ] **The final summary is usable.** Someone who did not watch the run can act on it.
- [ ] **Artifacts landed in `.ai-outputs/`**, not in the repository root.

Record what the run exposed. A pack that has never been run is a pack whose roles were cut on a guess.

## Smells that mean a rewrite

- an orchestrator whose body contains implementation instructions
- a subagent granted every tool "to be safe"
- two agents whose descriptions are hard to tell apart
- a handoff prompt that just restates the agent's name
- five agents where the work is genuinely two phases
- a pack with no README, so it cannot be installed
- agent names that duplicate another pack's
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall