Skip to main content

D104 — Tiered agent roster, code-graph MCP, and compressed reporting (pilot)

Architecture decision record. Status, thematic clusters, and how to record a new ADR: the decision log index. Full problem analysis, design alternatives, and the rollout plan across the other repos under ~/Code/stables/monorepo: the design spec, docs/superpowers/specs/2026-07-31-token-optimization-design.md.

Status: Accepted (pilot — stables-core-app is first; template rollout to the other repos follows a measured trial) · Date: 2026-07-31

Context​

Agent sessions in this repo were burning tokens (cost + context-window headroom) in four identifiable places: subagents had no explicit tiering and inherited the session model even for mechanical work; the mandatory multi-persona-review protocol ran up to 10 full session-model reviews per task (2 passes × 5 personas); symbol and dependency questions were answered by grep sweeps and bulk file reads into agent contexts, with no code-graph tool to answer them cheaply; and CLAUDE.md's hand-written section (~213 lines) largely duplicated the agent-workflow skill's operating-model narrative, while subagent reports flowed back as verbose prose the director quoted forward instead of digesting. Target: ≥50% reduction in tokens per representative task, weighting cost and context-window pressure about equally.

Decision​

Adopt the stables-agent-kit plugin — a new sibling repo (github.com/stablesxyz/stables-agent-kit, Claude Code plugin-marketplace layout, external to this repo) — as the shared source of:

  • A seven-agent roster with explicitly pinned models: explorer / junior-dev on haiku, senior-dev / qa-engineer on sonnet, staff-engineer / architect on opus, and principal inheriting the session model, dispatched only for one of three triggers (an architectural call the architect flags as genuinely unresolved, arbitration when qa-engineer findings conflict, or an explicit user request).
  • The generic agent-dispatch skill (roster, task-type → agent matrix, escalation ladder, four-slot dispatch prompt template) and the new compressed-reporting skill (the report schemas: explorer report, finding ledger, decision memo).

Within stables-core-app:

  • agent-workflow restructured from an abstract director narrative into a concrete dispatch playbook that activates alongside the kit's agent-dispatch and adds only what is repo-specific: tool routing (Serena for symbols, Graphify for module/impact graphs, Laravel Boost for runtime facts), the gates, docs-sync, and RLS/concurrency cautions.
  • multi-persona-review restructured from 2 passes × 5 session-model personas to tiered QA: Pass 1 fans the diff out to five parallel qa-engineer (sonnet) dispatches, one per persona lens (Sr. Software Architect, Sr. Backend Engineer, Sr. UX Designer/Engineer, Principal Product Manager, Sr. Security Engineer); the director merges the finding ledgers and dispatches fixes to the matching tier; Pass 2 is a single qa-engineer re-verification dispatch scoped to the fixes and the files they touched, not a second full five-lens sweep.
  • CLAUDE.md's hand-written section slimmed from ~213 to ~60 lines — skill-activation pointers, the non-negotiables list, the new dispatch-first + director-digest rules, and environment basics; the duplicated operating-model prose is gone in favor of a pointer to agent-workflow.
  • Two new MCP servers, registered in the committed .mcp.json and wired behind idempotent make targets: Serena (LSP/Intelephense — type-accurate symbol definitions/references) and Graphify (tree-sitter graph traversal — file/symbol neighborhoods, dependency paths; module-level impact is approximated by file-level traversal; heuristic, name-matched edges). make setup-agents bootstraps a new machine in one idempotent pass (installs uv if missing, installs Serena + Graphify, generates laravel-ide-helper stubs, builds the codemap, verifies each server responds); make agents-doctor diagnoses; make codemap refreshes the Graphify index; make ide-helper regenerates the Intelephense stubs.

Consequences​

  • One-file model changes. Pinning a roster agent to a different model is a one-file edit in the kit repo, propagated to every repo that consumes the plugin — no per-repo drift.
  • Graphify is orientation only. Its call/dependency edges are heuristic (name-matched); they scope impact and orient exploration, but proof that a symbol is actually referenced still comes from Serena or reading the code.
  • Stub staleness is a new failure mode. make ide-helper must run after any Composer dependency change, or Serena's Intelephense backing goes facade-blind (unresolved facades/Eloquent magic) until the stubs are regenerated.
  • The review protocol changed shape, not rigor. Every finding is still fixed / refuted with evidence / deferred only with explicit user sign-off, and gates still re-run after fixes — the change is which dispatches do the reviewing and how many of them run at the session model.
  • Docs-sync surfaces moved together with this ADR, per the same-change rule: the skills-package README table (packages/stables/skills/README.md) and the wiki pages describing the review protocol and operating model (How a change ships, the engineering index).
  • Rollout is staged, not simultaneous. stables-core-app pilots the full restructure; 2–3 real tasks are measured before the template (kit plugin reference + .mcp.json + Makefile targets + slim-CLAUDE.md skeleton) rolls to the other repos under ~/Code/stables/monorepo (stables-core-web, stables-core-infra, stables-core-web-backoffice, stables-insights, stables-ops, stables-web-abilities, then the rest).
  • Success is measured, not yet certified live. The ≥50% token-reduction target and the claim that tiered QA surfaces the same-or-more findings at a fraction of the cost are pending a representative before/after task comparison — tracked against the spec's success criteria, not asserted here as already proven (docs/tracking/token-optimization-pilot-measurement.md).
  • The plugin marketplace tracks the kit repo's main branch directly, not a pinned release/tag; stables-agent-kit is org-private, so this is an accepted risk (ruled 2026-07-31), not an oversight. MCP servers are approved per-developer, interactively, on first use rather than auto-enabled (enableAllProjectMcpServers is deliberately unset).
  • qa-engineer's Bash grant is tool-level unrestricted — agent frontmatter cannot pattern-scope commands, so the "read-only, never edits" guarantee is enforced at the prompt level, not the tool level; the compensating controls are that the director reviews every diff and qa-engineer runs in a sandboxed session.

← Decision log index