Part 2 of 8 — the agent topology, the one source of truth they share, and the round-trip that turns a request into a story and a story into updated docs.
The system is deliberately small: a thin Orchestrator that talks to people, and two specialist subagents — the Analyst and the Librarian — that do the real work. All three read from a single shared catalog: the living documentation of the system, which is both the Librarian's product and the Analyst's reference material.
A thin orchestrator routes to two specialists. The catalog is the shared brain — it physically lives in the GitHub repo the Librarian maintains, and the Analyst reads it for every elicitation.
The Orchestrator is the agent the user actually talks to. Its job is narrow on purpose: understand what the person wants, hold the thread of the conversation, and route to the right specialist. "Help me turn this idea into a story" goes to the Analyst. "Is the fund dashboard documented? Update it." goes to the Librarian. "What would change if we added a second approval tier?" fans out to both.
Keep it thin. The temptation is to let the front door accumulate logic until it becomes a third, muddled specialist. Resist it. The Orchestrator decides who should act and carries context between turns; it does not itself draft stories or edit docs. Everything valuable — the elicitation judgment, the documentation conventions — lives in the two specialists, where it can be reasoned about and improved in isolation.
The Analyst is the requirements engineer. It takes a vague request and does what a strong human analyst does — only it never skips a step and it has the entire catalog in working memory. Its loop:
grill-me skill (chapter 5).The Analyst owns the Jira side of the world. Its durable output is a backlog of stories that are decidable and testable — and a trail showing exactly which question produced each decision.
The Librarian is the documentation custodian. It treats the catalog the way a good engineer treats a codebase: every change is reviewed, every entity has an owner and a freshness date, and drift is a bug to be filed and fixed. Its loop runs in the other direction from the Analyst's:
The Librarian owns the GitHub side. Its product is a catalog you can actually believe — chapter 4 is devoted entirely to how it keeps that promise.
The piece that makes the architecture more than two disconnected bots is the catalog they share. It is not a database the agents query with SQL; it is a set of human-readable, version-controlled documents — the subject of chapter 3 — that both agents reason over directly.
This shared dependency is the whole point. Because the Analyst grills new requests against the same catalog the Librarian keeps current, the quality of elicitation rises every time documentation improves. And because the Librarian reconciles the catalog whenever an Analyst-authored story ships, the documentation improves every time the team delivers. The vicious loop from chapter 1 — vagueness and rot protecting each other — is inverted into a virtuous one.
Tie the roles together with the journey of one request — the "promotion spend visibility" ask from chapter 1:
One request, both halves of the loop: the Analyst pulls knowledge out of the catalog to write a good story; the Librarian pushes knowledge back in when the story ships.
The architecture is three roles and one shared, living catalog, wired to Jira and GitHub through MCP. Everything else in the guide fills this skeleton in: the catalog's contents (chapter 3), how the Librarian keeps it alive (chapter 4), how the Analyst grills a requirement (chapter 5), the concrete Jira and GitHub wiring (chapter 6), the Claude Code implementation (chapter 7), and how to adopt it without it becoming shelfware (chapter 8).
We start with the brain itself — the entity catalog — because everything else is in service of keeping it good.