# 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.
- Canonical model profiles store host-specific names (`codex_model`, `copilot_model`) because Codex and Copilot use different model naming surfaces; keep `default_model` as compatibility fallback.
- Canonical model profiles also track `copilot_multiplier` for planning/cost metadata, but runtime generated files remain unchanged in schema (no extra runtime fields).
- Copilot tools in runtime agents must remain namespaced (for example `search/codebase`, `edit/editFiles`) to preserve existing host style.

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.
4. Use `code_reviewer` for focused read-only review of a defined snippet, diff, commit, branch, or PR.
5. Use `test_writer` for targeted manual test checklists, smoke scenarios, and regression coverage plans.

## 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/`
- memory hygiene / operational handoff -> `skills/mcp-memory-operator/`
- 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 -> Code Reviewer
  - after a patch is complete and reviewable.
- Code Reviewer -> Test Writer
  - when findings include test gaps, regression risks, or manual validation needs.
- Test Writer -> Implementer
  - only when the user explicitly asks to implement automated tests or fix code.
- 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.