Spectral topology preflight

Spectral Topology Pre-flight

Why

Production multi-agent LLM systems fail at 41-87% rates from coordination defects, not from capability (Nechepurenko & Shuvalov, arxiv 2605.03310). Parks & Alharthi (arxiv 2605.11453) provide the first pre-inference diagnostic: spectral analysis of the team's communication operator predicts robustness (perfect rank correlation r_s = 1.0), consensus (r_s = 0.5), and drift (r_s = −1.0, inverted) before any agent runs. Cheap to compute, large effect on dispatch quality.

How

Given a proposed team graph (agents = nodes, communication paths = edges):

1. Get the signature from the tested implementation — do NOT hand-compute it. The linear algebra (build the row-stochastic operator P, form the successor representation M = (I − γP)⁻¹, and take its eigenvalues / condition number / spectral gap) is already implemented and unit-tested. Call the exported topologySignature(topology, n, gamma) in src/learn/generators/team-generator.ts — pass the topology archetype ('pipeline' | 'leader-worker' | 'mesh' | 'ring' | 'tree' | 'bipartite' | 'critique-route'), the agent count n, and optionally gamma (defaults to 0.9). It returns { rho, delta, kappa, gamma } computed from the closed-form spectra in Parks & Alharthi Appendix A. When you are generating the whole team, generateTeam(...) in the same module produces the signature for you as part of its result. Never estimate or fabricate ρ, Δ, or κ by hand — LLMs cannot reliably invert matrices or compute eigenvalues; always source the numbers from the function.
2. Interpret the three diagnostics returned in the signature:
   • κ (condition number of M) — robustness signal. Lower = more robust.
   • Δ (spectral gap of P) — consensus signal. Larger = faster consensus.
   • ρ (spectral radius of P) — drift signal. Smaller = less drift (inverted from κ).
3. Compare against per-task-class thresholds:
   • For "deep-reason" tasks: prefer small κ, large Δ — robustness matters
   • For "exploration" tasks: prefer larger ρ — drift is exploration, not failure
   • For "consensus" tasks: prefer large Δ above all else
4. Emit the signature — coordination_signature: { rho, delta, kappa, verdict, recommendation? }. Verdict is pass / warn / fail. On fail, recommendation suggests a topology edit (drop/add edge, switch chain↔star↔mesh).

Platform-constraint check (added v1.0.1)

Before recommending a topology change, verify the runtime can actually instantiate it. Spawn-only runtimes (Claude Code subagents, some serverless dispatch pools) cannot implement ring, mesh, or critique-route between workers — those runtimes only support star (one parent dispatches to N children; children return-result without inter-peer messaging). In a spawn-only runtime, the spectral menu collapses: ring/mesh/critique-route can only be simulated by the parent brokering messages between rounds, not wired directly between workers.

If the dispatcher is spawn-only, the skill's recommendation must describe what the parent brokers between rounds, not what edges to wire between workers. Concretely, when recommending against a star topology in a spawn-only runtime:

• "Switch to mesh" → "Broker mesh through parent: dispatch round 1 as star fan-out, parent gathers, dispatches round 2 with peers' draft outputs in each child's brief."
• "Switch to ring" → "Broker ring through parent: dispatch sequentially with each child receiving the prior child's output. (Loses parallelism.)"
• "Switch to critique-route" → "Broker critique loop through parent: dispatch a critic agent per round whose verdict shapes the next dispatch."

When the runtime supports inter-agent messaging (MCP servers with peer routing, custom orchestration), the spectral recommendations apply directly. Always check the runtime before recommending.

Output schema

{
  "topology": "chain|star|mesh|fully-connected|pipeline|leader-worker|hierarchical-fast-slow",
  "agent_count": 4,
  "coordination_signature": {
    "rho": 0.87,
    "delta": 0.42,
    "kappa": 12.3
  },
  "task_class": "deep-reason",
  "verdict": "warn",
  "recommendation": "drop the leader-to-worker-4 edge; the redundancy is uncalled-for and inflates κ"
}

When to skip

• Single-agent dispatch (no graph to analyse).
• Team has already been pre-flighted in this session and topology hasn't changed.
• Team is fixed by external constraints and the pre-flight result can't be acted on.

Integration

• Source the signature from topologySignature(topology, n, gamma) (or generateTeam(...)) in src/learn/generators/team-generator.ts — never hand-derive the (ρ, Δ, κ) numbers. The function is the single tested source of truth for the operator, its successor representation, and their spectra.
• Output should be emitted into the generated TEAM.md frontmatter as coordination_signature: … per arxiv 2605.11453 — so the team file carries its own diagnostic identity.
• sc-dev-team, mayor-coordinator, sling-dispatch — invoke before launching the team.
• team-control, uc-lab — long-running missions should re-run pre-flight when topology evolves.

Cross-references

• Rosetta concept #8 (Constraint Drift) — pre-flight is the upstream check against coordination drift
• College: agent-systems / multi-agent-orchestration / agent-spectral-topology
• Related skills: mayor-coordinator (consumer of the verdict), sling-dispatch (consumer)