Instruction file imported from Peter-N91/hve-squad-demo3 (.github/instructions/squad-routing.instructions.md). Copyright stays with the author.

Squad Routing Conventions

These conventions define how the Squad Coordinator classifies a user request and selects which roles to dispatch. The coordinator reads the routing table at the start of every turn, matches the request against the patterns, and dispatches the assigned roles at the indicated autonomy tier.

Routing decides who acts. The roster (squad-roster.instructions.md) decides which agent fills each role, and the state conventions (squad-state.instructions.md) decide how outcomes persist.

Routing File

The routing table lives at .copilot-tracking/squad/routing.md. The coordinator creates it on first use from the default rules below and updates it only through the Squad Scribe.

The file begins with YAML frontmatter and a single H1 title, then a routing table. Each row maps a request pattern to one or more roles, an autonomy tier, and a parallel-eligible flag.

Routing Schema

The routing table uses these columns:

Autonomy Tiers

• auto — The role proceeds and returns findings without pausing; suitable for read-only research and review.
• confirm — The role drafts an action or plan and the coordinator confirms before any change lands.
• escalate — The coordinator stops and routes the decision to the user before dispatching (see Escalation).
• auto-validated — Opt-in tier defined in .github/instructions/squad/squad-autonomous.instructions.md. Runs an implementation role and the council in a bounded re-validation loop (max 2 cycles) on a single turn. Engaged through the /squad prompt input mode=autonomous. Never downgrades confirm for cost-impacting or irreversible-write actions and always escalates on the mandatory triggers listed in the autonomous conventions (Stop verdicts, Risk: High findings from security/cost/RAI, compliance violations, irreversible writes).

Default Routing Rules

The coordinator seeds routing.md with these defaults. Each rule references a real deployed HVE Core agent through its squad role. Adjust per project, but keep every rule pointing at an agent that exists in the roster.

Filtering to the Active Roster

The seeded routing.md contains only the rules whose role exists in the project's team.md. When a profile (see Squad Profiles in squad-roster.instructions.md) seeds a subset of the cast, the Squad Scribe drops every routing row whose role is not on the seeded team. This keeps routing consistent with the chosen squad: the coordinator never matches a request to a role the project did not hire.

When a request matches a pattern whose role is absent from the active roster, the coordinator escalates (see Escalation) and offers to add the role or switch profiles rather than dispatching a role that is not on the team.

Dispatch Rules

• Match the most specific pattern first. When several patterns match, prefer the one whose role most directly owns the requested outcome.
• Dispatch all parallel-eligible roles for a turn concurrently; run non-parallel roles (such as planning and implementation) sequentially.
• Resolve every matched role through the roster before dispatch. If a role maps to thin charter needed, escalate rather than guessing a substitute.
• Apply cost-first model selection: prefer the fast tier for read-heavy auto roles and reserve the default tier for reasoning-heavy confirm roles.

Implementation Gate

Before dispatching an implementation-tier role (any role at confirm or auto-validated tier whose pattern indicates implementation, build, deploy, or merge), the coordinator checks .copilot-tracking/squad/decisions.md for the latest ## Council Verdict entry on the matching topic id.

The coordinator first confirms the methodology artifacts exist on disk. Implementation may not begin "cold":

• A research artifact exists under .copilot-tracking/research/ for the topic. If missing, dispatch researcher first.
• A plan artifact exists under .copilot-tracking/plans/ for the topic. If missing, dispatch lead (planning) first.
• A non-Stop Council Verdict exists for the topic when the request crosses two or more council-member domains. If missing, run the council row first.

When any precondition is unmet, the coordinator dispatches the missing stage (or escalates) instead of implementing. It never produces the missing research, plan, or verdict itself. With the preconditions met, the gate behavior is:

• When no Council Verdict exists for the topic and the request crosses two or more council-member domains (architecture, security, cost, product-fit, RAI), the coordinator runs the council row before the implementer.
• When the latest verdict is Go or Go-With-Conditions, the coordinator dispatches the implementer and passes the consolidated conditions as inputs.
• When the latest verdict is Stop, the coordinator escalates instead of dispatching. The user may explicitly override Stop, in which case the coordinator records the override through the Scribe before any implementer dispatches.

The gate enforces the council protocol from .github/instructions/squad/squad-council.instructions.md and the autonomous loop from .github/instructions/squad/squad-autonomous.instructions.md at routing time.

Review Follow-Through

The methodology does not end at implementation. After any implementation-tier role lands a change, the coordinator dispatches tester (review) as the closing stage before it reports the work complete — in every mode (interactive, autonomous, and autopilot). Review is an auto-tier, non-destructive read, so it runs without a separate gate. This makes the methodology symmetric: research and plan precede implementation, and review follows it, so Research → Plan → Implement → Review is enforced end-to-end.

• Resolve tester to the matching review agent per the roster Selection Cue — for example Code Review Full for a pre-PR review, or Implementation Validator for an implementation-vs-design check — and fold its findings into the turn summary.
• Every profile carries tester through the methodology spine (see squad-roster.instructions.md), so the review stage is always available. When a user has explicitly removed tester from the roster, the coordinator reports that the change closed unreviewed and recommends re-adding the role rather than silently skipping review.

Escalation

The coordinator escalates to the user, rather than dispatching, when any of these hold:

• The matched rule is at the escalate tier.
• No routing pattern matches the request with reasonable confidence.
• A matched role resolves to thin charter needed in the roster.
• Two rules conflict and no pattern is clearly more specific.

On escalation, the coordinator states the ambiguity, lists the candidate roles, and asks the user to choose before any role acts.