# Local orchestration playbook for portable subagents

This playbook contains repository-specific workflow guidance that must not be embedded in portable subagent runtime files.

## Boundary: portable vs local

- Portable subagents (`.codex/agents/*.toml`, `.copilot/agents/*.agent.md`): role behavior only, reusable across repositories.
- `AGENTS.md`: concise and stable governance minima for this repository tree.
- This playbook: repository-local orchestration and handoff conventions.
- Local skills (`skills/*`): specialized workflows and domain execution details.

Do not duplicate this playbook in runtime agent files or general README files.

## Routing order in this repository

1. Use `explorer` for scoped read-first discovery when boundaries are unclear.
2. Use `technical_analyst` for multi-source technical analysis with explicit evidence and trade-offs.
3. Use `implementer` only when acceptance criteria and scope are clear enough for a reviewable patch.

## Repository-specialized skills first

When task shape is explicit, route to local specialist skills as primary owners:

- multi-source technical analysis -> `skills/mcp-technical-analyst/`
- multi-phase coordination -> `skills/mcp-master-orchestrator/`
- domain execution -> relevant specialist skill under `skills/`

Portable subagents are role baselines; they do not replace specialist local workflows.

## Practical handoff rules

- Explorer -> Technical Analyst
  - when a timeline, source matrix, or causality chain is required.
- Explorer/Technical Analyst -> Implementer
  - when there is enough evidence to constrain a small and testable change.
- Implementer -> Technical Analyst
  - when unresolved architectural ambiguity blocks safe implementation.

## Parallelism and scope discipline

- Prefer one active role focus at a time for high-risk changes.
- Keep patches small and avoid cross-cutting redesign in one step.
- Escalate to human review when decisions are strategic or irreversible.