polyphony

Overview of polyphony skill

polyphony is a multi-agent orchestration skill for running parallel agent work in container-isolated workspaces. Each session gets its own Docker container and git branch, which makes it useful when you want concurrent execution without branch collisions, shared-state bugs, or messy cleanup.

What polyphony is for

Use the polyphony skill when the job is bigger than a single prompt but still benefits from structured delegation: parallel feature work, isolated validation, issue triage, or running several agent paths against the same codebase. It is designed for users who care about clean execution, reproducible task routing, and safer multi-agent coordination.

Why it stands out

The main differentiator in polyphony is isolation-first workflow design. Instead of asking an agent to “do everything,” it separates task discovery, routing, provisioning, runtime, and verification so each worker operates in a controlled workspace. That makes the polyphony for Multi-Agent Systems approach more practical when you need independent tests and cleaner landing behavior.

Best fit and tradeoffs

polyphony fits best if your environment already supports Docker or OrbStack and you want default-on orchestration rather than a one-off prompt pattern. It is less useful if you only need a single chat response, cannot run containers, or want minimal setup with no repository-aware workflow.

How to Use polyphony skill

Install and load polyphony

Install the polyphony skill in your skills directory, then use it from the host workflow that supports skill loading. The repository notes it is intended to be loaded automatically when container isolation is available, and it is the default for /spawn-team. If your setup differs, verify that Docker access, branch creation, and workspace mounts are available before relying on the skill.

Start from the right files

For polyphony usage, begin with skills/polyphony/SKILL.md, then read the linked or mentioned context in the same order the skill uses internally: task lifecycle, architecture, prerequisites, configuration, and any repository-specific references embedded in the file. Since this repo has no helper scripts or extra reference folders, the core behavior lives in the skill file itself, so reading it closely matters.

Turn a rough goal into a usable prompt

A strong polyphony prompt should include: the target repo, the number of parallel agents you want, the type of work each agent should own, the branch or PR expectation, and any constraints on tests, credentials, or cleanup. For example, instead of “fix this project,” ask for “split the issue into three isolated agent tasks: reproduce, patch, and verify, using separate Docker workspaces and reporting landing status per branch.”

What to specify for better output

Give the skill concrete routing signals: task priority, dependencies, whether work must be read-only first, which environments are safe to provision, and what counts as verification. This helps the orchestrator choose better RunSpecs and reduces wasted container spins. For a polyphony guide, the most useful input is not more prose; it is clearer task boundaries.

polyphony skill FAQ

Is polyphony only for Docker setups?

Yes, practically speaking. The polyphony skill assumes container isolation is available, so Docker or OrbStack support is the main adoption gate. If you cannot provision containers, the workflow loses most of its value.

Is polyphony different from a normal prompt?

Yes. A normal prompt asks an agent to act; polyphony defines how multiple agent runs are claimed, routed, provisioned, verified, and landed. That structure is the point of the polyphony skill, especially when independent branches and clean execution matter more than speed alone.

Can beginners use polyphony?

Yes, if they can already run containers and read a skill file. The main learning curve is not prompt writing; it is understanding that polyphony expects task decomposition and environment readiness. Beginners usually get better results when they start with one small task and one clear verification target.

When should I not use polyphony?

Do not use polyphony for quick one-off questions, lightweight edits, or environments without Docker. It is also a poor fit when the task is ambiguous and you have not yet defined what each agent should own, because the orchestration overhead can exceed the benefit.

How to Improve polyphony skill

Give the router better task boundaries

The biggest quality gain in polyphony comes from clearer task decomposition. State which work is exploratory, which work changes code, and which work only verifies. If you want parallelism, define the division explicitly instead of asking the system to infer it from a vague goal.

Include constraints that affect workspace behavior

Mention branch naming rules, network limits, test runtime expectations, and whether secrets or mounted identities are required. Because polyphony uses isolated containers and independent branches, these constraints directly affect provisioning and whether the run can complete without manual intervention.

Ask for verification, not just implementation

A common failure mode is stopping at “the code changed.” Better polyphony usage asks for reproduction steps, test commands, and landing criteria for each agent path. This is especially important when multiple workers may converge on different solutions and you need a reliable merge decision.

Iterate after the first run

If the first output is too broad, narrow the task and rerun with a single success criterion. If the result is too fragmented, reduce the number of parallel agents and add stronger dependencies between stages. For polyphony, improvement usually comes from sharper orchestration inputs, not from longer prompts.