studio-agent-orchestration

Studio Agent Orchestration

Overview

Choose agent roles only where parallelism creates leverage. Keep the immediate critical path on the main thread and make every sidecar contract independently verifiable.

When to use

Use when two or more independent workstreams exist, repeated discovery can be partitioned, a stable slice needs independent verification, or a project profile declares a specialist role.

When NOT to use

Do not delegate small one-file work, immediate blockers, overlapping writes, shared unstable contracts, or tightly coupled edit-test iteration. Do not use a specialist outside its declared repository.

Required inputs and context discovery

Collect the workspace route, immediate critical-path action, candidate workstreams, resolved profile and inferred role templates, capability scopes, exact active file assignments, read-only scopes, expected outputs, concurrency limit, available role definitions, and validation requirements.

Safety and risk level

Planning is read-only. Agent role selection never expands mutation permissions. Investigator and review lanes remain read-only; implementers own exact disjoint paths; verifiers may write only normal test/build artifacts.

Workflow

1. Identify the immediate critical-path action and keep it on the main thread. Completion criterion: no sidecar blocks the next local action.
2. Resolve profile specialists, inferred specialists, and canonical templates before reviewing effective owned scopes. Record broad scope intersections as capability-overlap; they describe what roles can own and do not by themselves block activation. Completion criterion: the review distinguishes effective capability patterns from exact files assigned in the current work packet.
3. Reject an active assignment outside its role's effective scope or any exact file assigned to more than one simultaneous writer. Also reject generated targets or unstable shared interfaces that lack one owner. Completion criterion: every concurrent writer has a disjoint exact write set, while disjoint assignments remain allowed even when role capabilities overlap.
4. Select the narrowest role: investigator for ownership discovery, implementer for bounded writes, verifier for independent checks, or a profile-declared specialist for difficult domain work. Completion criterion: role choice is justified by scope rather than prestige.
5. Bound concurrency by project profile and available independent work. Completion criterion: concurrency never exceeds three and may be zero.
6. Give each sidecar ownership, do-not-touch scope, expected output, and verification contract. Completion criterion: sidecars cannot create child agents and the main thread owns integration.