Agent Routing & Orchestration — FullStack Pilot

This file defines how Claude Code routes queries to specialist agents across the Angular / .NET / SQL Server / Azure stack and how agents coordinate with each other.

Agent Roster

Stack Specialists (one trio per plugin)

Pipeline Agents (pilot-core)

Persona Agents (pilot-core)

Optimised for a specific enterprise role. Each has different permissions and output formats.

Routing Table

Match user intent to the first agent that fits. When multiple match, the first row wins.

Feature & Architecture Requests

Review Requests

Fix Requests (after a review finding)

Production Support / Incidents

@fsp-incident-responder vs @fullstack-support: Use @fsp-incident-responder when the engineer is in active incident response mode and needs a root-cause analysis, a proposed fix branch, a rollback plan, and a shift-handoff note in a single workflow. Use @fullstack-support for quick layer-classification triage when you already know it will route to a single specialist.

Meta Workflows

Cross-Agent Coordination

When to Use Subagents

Use subagents for:

• Parallel research across multiple layers (e.g., scouting Angular and .NET simultaneously)
• Protecting the main context window from large file reads (@fsp-scout for briefs)
• Independent tasks that do not need prior-step output (e.g., lint + migration check in parallel)

Do not use subagents for:

• Single-step lookups where a direct tool call (Grep, Glob, Read) suffices
• Tasks under 3 tool calls — the spawn overhead is not worth it

Subagent Pattern — Cross-Layer Feature

@fullstack-implementor receives work item
  → spawns @fsp-scout for each layer (parallel)
  → reads context briefs from .claude/pilot/context/
  → delegates SQL changes to @sql-implementor
  → delegates .NET changes to @dotnet-implementor
  → delegates Angular changes to @angular-implementor
  → handles cross-layer glue (API client regeneration, contract alignment) directly
  → runs /fsp-verify before declaring done

Handoff Format

When routing to a specialist, always include:

## Handoff → @<agent>
Layer:    <angular | dotnet | sql | azure>
Finding:  <rule-id or description>
File:     <path:line>
Context:  <1-2 sentences of why>
Ruled out: <other layers / agents considered>

MCP-First Principle

All agents must prefer MCP tool reads over direct file reads to reduce token consumption.

When no MCP tool covers the need, fall back to: Grep → Glob → Read (smallest scope first).

Skill Load Order

Agents load skills in dependency order before starting work. Never start implementation without checking whether a relevant skill exists in the plugin manifest.

Default Order for Implementors

1. stack-detection — understand what stacks are active (skip if stack-profile.json is current)
2. Domain skill(s) — e.g. angular-signals-and-state, dotnet-cqrs, sql-schema-design
3. api-design-standards — if the work touches a REST API boundary
4. architecture-decision-records — if the work might override a prior decision

Default Order for Reviewers / Support

1. Domain skill(s) — all relevant to the files under review
2. audit-orchestration — if the review scope includes security findings

Autonomous Loop Caps

When running any fix or build loop autonomously:

• Hard cap: 10 iterations per loop. Stop at 10 regardless of remaining errors. Report what was fixed, what remains, and the next recommended action.
• Never force-push, never reset --hard, never drop migrations — even inside a loop.
• Every loop iteration that modifies files must end with a git status check.
• If a loop hits the cap, write a .claude/loop-stopped.md with the iteration count and remaining issues before exiting.

Hard Rules

These apply to every agent without exception:

1. No changes to live environments. Agents produce branch changes and stop. Deploy only after human review.
2. No force-push ever. git push --force and git push -f are blocked by the bash-guard hook. Do not attempt to bypass it.
3. No DROP TABLE, DELETE without WHERE, or destructive migrations in non-feature branches. The dangerous-patterns hook blocks them. Investigation only — no silent fixes.
4. Never silently return a degraded result when a read budget is insufficient. Stop, state what more is needed, and wait.
5. Reviewer and support agents never modify files. disallowedTools: Write, Edit is enforced in their manifests and by CI.
6. Pipeline artifacts are files, not chat. Specs, plans, scout briefs, and QA reports are written to .claude/pilot/ and handed off by path.

Persona Agent Priority

When multiple agents could match an intent, resolve as follows:

Escalation Paths

Skill Load Order Additions (Persona Agents)

• @fsp-feature-builder: stack-detection → api-design-standards → domain skills → cross-stack-review last
• @fsp-incident-responder: incident-correlation first → incident-response-runbook → session-handoff → domain skills
• @fsp-tpo-intake: no skills at start; spec-validation only when PR/diff is provided

Conflict Resolution

1. Architecture questions win over implementation — "How should we structure the payment module?" → @fsp-architect, not @dotnet-implementor
2. Specific beats general — "Optimize this EF query" → @sql-support, not @fullstack-support
3. Security concerns are always surfaced — even when another agent is primary, flag security findings for the appropriate reviewer
4. Triage before fix — for production symptoms, @fullstack-support classifies the layer before any implementor is engaged
5. Persona beats general — when the user identifies themselves as a Developer, Support Engineer, or TPO, route to the persona agent, not the pipeline agent