Orchestration

Canonical home for Marqo's agent-orchestration docs: how leads run teams, how teammates iterate, how reviewers gate, and what we'd like to improve.

Read by role

Who you are	Start here
Lead session (you typed a `/skill` and are now running a team)	`team-lead-protocol.md`
Implementer teammate (`code-implementer`, `css-implementer`, `search-tuner`)	`iteration-patterns.md` §Pattern B + your agent definition under `.claude/agents/`
Reviewer teammate (`code-verifier`, `css-verifier`, `search-verifier`, `qc-investigator`)	`code-review-guide.md` + `review-severity-rubric.md`
Deciding whether to spawn a team or work inline	`inline-vs-team-criteria.md`
Looking for known limitations / gaps	`followups.md`
Considering an orchestration improvement	`roadmap-ideas.md` — then propose via PR
Investigating recurring friction	`2026-06-session-manual-interventions.md` — corpus mined by the self-improvement loop (roadmap-ideas §5)

team-lead-protocol.md — what the lead does, must not do, and how to run the team (tier-2 reference per roadmap-ideas.md §1; domain skills point at this doc rather than duplicate lead instructions).
iteration-patterns.md — A/B/C/D/E pattern taxonomy (full Workflow / inline-iterate / pair-driven / persistent reviewer / B→D mode-switch) with the empirical lessons from each.
inline-vs-team-criteria.md — decision rubric: should this work go inline-as-lead, or warrant spawning a team?
stack-upkeep.md — keeping stacked PRs healthy across squash merges: boundary rebases, the clean-cherry-pick hazard, shared-hunk byte-sync, retarget choreography.
code-review-guide.md — general-dev review playbook (the playbook arg default for general-feature-pr).
review-severity-rubric.md — P0–P3 + SCOPE_CREEP severity definitions used by every reviewer.

followups.md — deferred items from shipped uplift PRs. When code changes close one, mark it RESOLVED here with the closing PR.
roadmap-ideas.md — forward-looking proposals not yet committed. New ideas land here first; once approved, they graduate into a feature PR + the relevant active-guidance doc.
2026-06-session-manual-interventions.md — 21-entry log of places automation/orchestration failed in the June 10–11 uplift run and a human (or lead-via-direct-action) had to step in. The self-improvement loop (roadmap-ideas.md §5) will consume files like this. Future session logs land alongside with the same filename pattern.

archive/2026-06-10-holistic-review.md — June 2026 design review of the substrate as it then was. Some claims drift as the substrate evolves; verify against current code before acting.
archive/2026-06-10-uplift-collation.md — synthesis across the orch-impl-b PR series (June 10) that fed PRs #3482, #3486, #3498, #3499, #3500, #3501.

Idea stage. Add a numbered item to roadmap-ideas.md with the open design questions called out. No code yet.
Approved. Promote into a feature PR that touches the active-guidance doc(s) AND any code/skill/agent-def the change implies. Close any superseded followups.md entries with the PR number.
Shipped. Add an entry to the next session's manual-interventions log if the change came with friction worth capturing for the self-improvement loop.

Filenames: kebab-case (e.g. review-severity-rubric.md, not review_severity_rubric.md). Date-prefix archive snapshots (2026-06-10-…).
Cross-links: use repo-root-absolute (docs/dev/orchestration/foo.md) in callers outside this directory, and relative (foo.md, archive/2026-06-10-foo.md) inside it.
Hand-written endpoint tables / API references: see roadmap-ideas.md §6 — don't duplicate generated schemas in here; link to them.