Skip to content
Spectral Codex
GitHub
Decisions

ADR-078: Retire Spectral Agent

Context

ADR-007 established the Spectral Agent as the conversational interface through which customers interacted with the optimization platform — asking about scan results, troubleshooting failures, reviewing evaluation frameworks, and onboarding new workspaces. The agent was customer-facing; the World Agent (added later per ADR-058) and the then-separate Ops Agent were operator-only by design.

Under the in-band decision-support shift, three things change at once:

  1. The Spectral Agent’s prior responsibilities tie to retired primitives. Every specialist subagent (scan-analyst, onboarding-guide, framework-advisor, troubleshooter) operates on scans, changesets, evaluation frameworks, and onboarding flows — all retired per ADR-074 and ADR-075. The supervisor agent’s job (route customer questions to specialists, synthesize their findings) has no surviving subject matter.
  2. The customer’s relationship with their world inverts. The world and World Agent were previously operator-internal: customers reached the world’s effects through the Spectral Agent’s mediation. Under the shift, customers see their world directly — the world is the customer-facing container for their domains, each instance customer-scoped per (org, domain) (per ADR-086), and the Spectral dashboard surfaces it. There is no longer a Spectral Agent layer between customer and world.
  3. The World Agent’s role expands to span both audiences. Internally the World Agent gains code generation, eval-framework orchestration, override-pattern detection, and validation responsibilities (per ADR-081); externally the World Agent owns any customer-facing agent affordance the Spectral dashboard surfaces.

The Spectral Agent epic family (SPEC-244, SPEC-242, SPEC-415, SPEC-420, SPEC-423–426, SPEC-430, SPEC-417–419, SPEC-431) was pending a reframe decision in Phase 3 Session 3c. This ADR settles that decision in favor of retirement.

Decision

The Spectral Agent retires entirely. The four specialist subagents retire with it. The surviving agent topology is a single agent — the World Agent — which serves operators directly and owns any customer-facing agent affordance the Spectral dashboard surfaces (per D2).

D1 — Spectral Agent retires

The Spectral Agent — supervisor, specialist subagents (scan-analyst, onboarding-guide, framework-advisor, troubleshooter), and their tool surfaces — leaves the architecture. No replacement Spectral-Agent-equivalent is introduced. Conversation persistence machinery established for the Spectral Agent (per ADR-043) carries forward as substrate that the World Agent’s customer-facing surface uses when conversation-mediated interaction is appropriate.

D2 — World Agent owns customer-facing agent surfaces

Where the Spectral dashboard surfaces an agent-mediated affordance — explanation of a decision audit record, walk-through of a rule trace, conversational exploration of a world model — that affordance flows through the World Agent. The World Agent serves operators (its prior audience) and customers (its new audience) through the same runtime, with auth + scope determining what each caller can see and do.

The customer-facing surface’s specifics — which affordances the Spectral dashboard exposes, what tool surface the World Agent presents to customers vs operators, how scope filtering enforces tenant isolation on World Agent tools, conversation-persistence layout for customer-side conversations — are downstream design work deferred to Phase 3d. This ADR commits the World Agent to owning customer-facing surfaces; it does not specify the surfaces themselves.

D3 — Agent topology is a single agent

The surviving topology is one agent — the World Agent (spectral.worlds), serving operators directly. No second agent runtime exists. The LangGraph orchestrator pattern, the agent-tool-invocation framework-layer composition (ADR-060), and the channel-agnostic conversation primitives (ADR-007 surviving sections) govern that single agent.

D4 — What carries forward from ADR-007 as substrate

The framework choice (LangGraph + Deep Agents) carries forward, with the World Agent as its current consumer (the Operations Agent was removed per ADR-101). The supervisor + specialist pattern is available as a generic architectural pattern; whether the World Agent adopts a supervisor-plus-specialists shape is per-agent design (governed by ADR-058 + any future agent-design ADRs).

The following ADR-007 conventions stand and continue to govern the surviving agents:

  • Event-driven proactive conversations as a pattern (the specific events listed in ADR-007 — ScanCompletedEvent, AnomalyDetectedEvent, WorkspaceConfigChangedEvent — retire because they reference retired primitives, but the pattern itself is preserved for any future event-triggered World Agent or Ops Agent conversation).
  • Human-in-the-loop approval via LangGraph interrupt (AgentApproval records, WorkspaceAgentAuthorization pre-approval) as a generic pattern. Relevance to the in-band shift: decision modules are binding, so HIL approval is not part of /api/decide’s decision path, but the pattern remains available for World Agent authoring workflows.
  • Channel-agnostic conversation model and adapter pattern (web / Slack / email). Available for whichever agent’s customer-facing or operator-facing surface needs multi-channel reach.
  • LangGraph checkpointer state management and the dedicated langgraph PostgreSQL schema isolation. Substrate.
  • Closed-over-dependency tool architecture (factory functions accepting repository protocols, returning callables; framework-layer composition per ADR-060). Substrate.

Alternatives considered

Preserve Spectral Agent as a decision-debugging / explanation surface (Option A from the Phase 3c framing). Rejected. The audit record from POST /api/decide is dense (rule traces, suppression chains, predicate outputs, aggregation outcome, work-frame construction), and a conversational layer over it would make the dense record more legible. But the audit-record surface is the world’s surface — it concerns rules, world-model version, conformity, the binding contract — and that is World Agent territory under D2 of this ADR. Layering a Spectral Agent atop a World Agent’s surface would duplicate the agent runtime without adding distinct responsibilities. Where decision-debugging is wanted, the World Agent provides it directly; the Spectral dashboard’s structured decision-detail panels (the decision deep-dive surface, docs/design/annotated-screens/customer-4-decision-deep-dive.png) provide the UI affordance without agent mediation.

Preserve Spectral Agent as an internal-only operator aid (Option B from the Phase 3c framing). Rejected. The World Agent (per ADR-058 / ADR-081) already serves operators directly — authoring (rule curation, code-gen orchestration, conformity review, evolution patterns), plus the operational surfaces that need no separate agent. Adding another operator-facing agent would fragment the operator UX without a distinct responsibility.

Defer the retirement decision and leave the Spectral Agent epic family paused indefinitely. Rejected. The paused epics block downstream Linear scope decisions in Phase 4 (the epic family — SPEC-244, 242, 415, 420, 423–426, 430, 417–419, 431 — collectively spans ~9–10 issues that need a disposition). Deferral without a decision keeps these in limbo and forces every Phase 4 sweep to re-confront the question. Settling here closes the loop.

Carry the Spectral Agent forward with a fresh role (e.g., onboarding assistant for new customers). Rejected. Onboarding under the in-band shift is operator-side work — Spectral staff sets up new customer worlds via the Ops Agent or directly via operator UIs; customers don’t have a self-serve onboarding flow gated through an agent. The prior onboarding-guide specialist’s job (walking new customers through workspace setup with trace-ingestion guides) ties to retired primitives.

Consequences

  • ADR-007’s Spectral-Agent-specific content (lead-in framing, specialist subagent table, listed proactive events) is replaced with one-line pointers per the partial-supersession discipline. The framework choice, conversation model, approval pattern, state management, and tool architecture remain authoritative under ADR-007’s surviving sections, with ADR-058 / ADR-060 as the active consumers.
  • Linear scope changes in Phase 4 follow naturally: the Spectral Agent epic family (SPEC-244, SPEC-242, SPEC-415, SPEC-420, SPEC-423–426, SPEC-430, SPEC-417–419, SPEC-431 — approximately ten issues) closes with Fork-A-style closure-with-note.
  • Codex updates flow: system-design/control-plane/spectral-agent.mdx retires; system-design/agents/agent-architecture.mdx rewrites from the three-agent topology to the single-agent (World Agent) topology.
  • The World Agent’s customer-facing surface specifics — affordance set, tool surface, scope filtering, conversation persistence layout — are downstream design work in Phase 3d / future ADRs. This ADR establishes ownership; it does not specify the surfaces.
  • Conversation persistence machinery from ADR-043 (Conversation, AgentTask, AgentApproval, ConversationChannelBinding entities, the LangGraph checkpointer adapter, the dedicated langgraph schema) carries forward as substrate. Code paths specific to the Spectral Agent (specialist routing, the four named specialist subagents) become candidates for removal in Phase 4 build-plan work; conversation-substrate code stays.
  • The agent-architecture Codex page’s three-agent narrative (Spectral / World / Ops) collapses to the single World Agent. The “agents are analysts / explorers / proposers, not operators” framing (project memory) continues to hold; that framing pre-dates this ADR and is not affected.