The Architect Agent (Nerve Center Only)

Tier 3 · Everything Built 7 min read

The architect agent was built to solve a specific problem: the Nerve Center v5 codebase was changing fast, across parallel agents, with no gate between “built” and “merged.” Without some layer that understood the NC5 architecture and could review diffs against intent, the codebase would accumulate contradictions. The architect agent is that layer. It is also, specifically, only that layer — not a general-purpose code reviewer for every project.

What It Does

The architect has four main responsibilities, each implemented as a module in agents/architect/:

PRD gate (prd_gate.py). A deterministic, zero-cost check that runs on every commit to NC5. It validates that the change has a written-intent record: a PRD exists and is fresh (within 14 days). The freshness bound matters. A PRD from April satisfying a June commit is the kind of drift that lets old requirements govern new code. CHANGELOG 2026-06-05: “caught live: NC5’s April PRD would have satisfied the gate forever.” The 14-day window forces explicit renewal.

Significance classifier (significance.py). Reads a diff and classifies whether it’s significant enough to require a full review. Trivial changes (dependency bumps, comment edits, test fixture updates) don’t need Opus time. Changes that touch the bridge, the structured stream, the session model, or the cockpit’s core rendering do.

Intent verify (intent_verify.py). An independent agent that re-derives JD’s intent from the PRD, recent commits, and the WORKPLAN, then verifies the diff actually delivers that intent. This runs in the pre-push stage via qa-ship.sh. The key word is “independent”: it doesn’t just ask the author whether the PR does what it says — it re-reads the source of intent and checks the diff against that.

Code review (review.py). A full Opus-backed review of the diff against the NC5 architecture: is this change coherent with the system’s patterns? Does it introduce regressions in the structured stream? Does it touch the bridge in a way that could affect running sessions? The review is emitted to the PR (or to Telegram, depending on the trigger).

Signoff (signoff.py). Writes a structured signoff record. If the review passes, the architect signs off. If not, it returns a findings list with file citations.

The Enforcement Chain

The architect’s rulings became enforced (not advisory) with Phase 2 enforcement on 2026-06-05:

E1: Pre-commit hook on the NC5 repo. Runs significance classification and PRD gate on every local commit. If the change is significant, the gate fires. A live dogfood test: “gate classified its own CI change significant, spawned real Opus review, APPROVED with file-cited reasons.”
E2: prd_gate.py — deterministic written-intent check in the commit-msg hook.
E3: intent_verify.py — runs in qa-ship.sh at the pre-push stage.
CI job: architect-gate runs as a required GitHub Actions check on NC5 PRs. A PR that fails the architect gate cannot merge. This is enforced via enforce_admins branch protection — even JD can’t merge a failing gate without an explicit bypass.

The Scope Rule

This is important enough to quote directly from CLAUDE.md:

“The architect agent fires ONLY for nerve-center-related products. For everything else (e.g. the MBA Office software stack, standalone client apps), do NOT invoke the architect — use industry-standard QA + visual testing instead.”

The reason: the architect’s review code carries NC5-specific assumptions. It knows the bridge protocol, the structured-stream event format, the cockpit rendering pipeline. When it reviews a Next.js app that doesn’t use any of those patterns, it applies NC5 priors to a system they don’t apply to. This isn’t a quality problem — it’s a context problem. The architect would wrongly flag NC5-specific patterns as missing in a system that never had them.

The incident that made this a rule: 2026-06-02, build and QA agents were spawning live cockpit sessions to smoke-test features. Those messages landed in JD’s real CEO chat permanently — they cannot be removed. The architect gate rule was written alongside the “no live session writes for QA” rule, as part of the same clarification about which tool belongs to which scope.

For non-NC5 products, the standard is: Playwright visual tests against the PRD’s user-story acceptance criteria. No architect invocation.

What the system_index Is

system_index.py is the architect’s map of the NC5 codebase. It enumerates:

All API routes and their expected shape
The bridge protocol (event types, the structured stream format)
The cockpit rendering pipeline (clean render → raw toggle)
The session model (spawn, resume, dead-session detection)

When the architect reviews a diff, it loads the relevant sections of system_index as context. A change to bridge/transcript.py triggers the bridge section; a change to src/app/chat/page.tsx triggers the rendering section. This is what makes the review NC5-coherent rather than generic.

The Trade-Off

The architect gate adds latency to the NC5 ship cycle. The pre-commit hook adds a few seconds; the pre-push intent-verify adds an Opus call (seconds to minutes depending on diff complexity). That’s the cost of having a gate.

The benefit is concrete: the gate caught the April-PRD freshness issue, caught its own CI change correctly, and was designed to catch the class of “build agent ships something incoherent with the system model” that the 2026-05-31 audit found in NC5’s own codebase. Gates that catch real things at the cost of seconds are worth the trade.

Next: Tracker: CEO Accountability — the agent that keeps the org honest about what shipped versus what’s still open.