Inside the ADR Authoring Mission: Agents, Observations, Gates

Harry has made the business case for capturing the why behind architectural decisions; I want to open the hood. I lead the Missions team at StudioX, and the ADR Authoring Bot is not a monolithic "AI writer" — it is a Mission: a small org chart of specialist agents coordinated by a reasoning core, every step of which you can watch as it happens. This piece is the honest architecture, including the parts that are read-only and the one place a human has to say yes.

A Mission, not a model call

In StudioX, a Mission takes a goal in plain language, reasons about it, delegates work to specialist agents, and returns a result — with every decision traced. It runs inside your perimeter, on your own tools. The ADR Mission's goal is simple to state: "A decision was reached in this thread / this transcript / this PR — capture it as a structured ADR."

Two tiers do the work. Tier 1, the reasoning core, is the project manager. It reads the request and the roster of available agents and decides, one round at a time, which single agent should act next, accumulating results until it judges the record complete. Tier 2, the agent planner, takes the goal handed to a chosen agent, discovers what that agent can actually do, decomposes the goal into ordered steps, and executes them. Nothing here is a hard-coded pipeline — routing, planning, and the final "are we done" check are all model decisions, which is why the same Mission handles a two-message Slack decision and a forty-comment PR debate without a branch of custom code.

The roster

Each specialist agent is backed by its own StudioX bot with its own knowledge base, so knowledge stays isolated — the agent that reads pull requests never accidentally answers from the ADR archive. For the ADR Mission the roster is small and legible:

• Capture Agent — pulls the raw material: the chat thread, the meeting transcript, the PR description and its review comments. This is read-only. It ingests; it does not write anything back to your systems.
• History Agent — searches the existing ADR archive (a StudioX knowledge base of every prior record) to find decisions this one supersedes, conflicts with, or depends on. Also read-only.
• Drafting / Report Agent — synthesizes context, decision, alternatives considered, and consequences into the structured ADR. Because its name carries "report," the Mission persists its output as a first-class report record automatically.

Watching it reason: observations

The property that makes a Mission trustworthy is that you never have to take its word. As the reasoning core routes and each agent plans and executes, every phase streams to the Explain rail over Server-Sent Events — routing decisions, capability discovery, each planned step, the validation of that step, and the final answer check, in true execution order. StudioX calls these observations, and for the ADR use case they are the audit trail of the audit trail: you can see that the "we chose Postgres over DynamoDB for transactional guarantees" line in the draft came from a specific PR comment, not from the model's imagination. Every step is validated by a separate model call, and a step that refused or returned the wrong kind of content is retried once — so a flaky tool fetch does not silently produce a hollow record.

Where the tools come from: instant MCP servers

The Capture Agent has to reach into GitHub, Slack, and whatever records your calls. In StudioX those connections are instant MCP servers: tools registered at runtime rather than built as integration projects. A generic agent discovers the available tools from the MCP servers when it runs, so the day you add a transcript source, the Mission can read it immediately — no code change, no redeploy. This is why the same Mission adapts to your stack instead of forcing you onto ours, and it is the same mechanism explored across our business applications.

The one gate that matters: decision queue and human-in-the-loop

Reading is safe; writing to your source of truth is not. Capturing and drafting are read-only, so they run autonomously. But committing the finished ADR — opening the PR against your docs repo, publishing to the wiki — is exactly the kind of irreversible action a human should authorize. So the Mission's final synthesis ends not by claiming it filed the record, but by emitting a [REQUEST_APPROVAL] block. The route layer turns that into a decision queue row and emails the reviewer a magic-link approve/reject URL; in chat, the marker becomes an "awaiting approval" status. Nothing lands in your repo until a person clicks approve. That is human-in-the-loop by construction, not by policy.

The portal surface ([REQUEST_PORTAL]) is where a team browses the growing ADR archive as a searchable, structured collection — the durable enterprise knowledge that Harry described going missing.

That is the whole machine: a reasoning core, three legible agents, observations you can audit, runtime tools, and a single approval gate. For the business case see why it matters; to watch it run against a real quarter of decisions, read in practice.