NAI OS

How the agent systems work

Start from what you type. End at how it is built.

The systems in this workspace look like a pile of different things and are really one pattern repeated — that pattern has its own page now. This page is the map one level up: the big picture, then each system, each shared idea, and the web applications and external agent system this all connects to, each on its own page.

The big picture

Four layers. Every command sits in the top three; everything they dispatch or reach lands in the bottom two. The orchestrator/subagent/tool pattern each command shares now has its own page — this is the map one level up: what's a command, what's a bridge, what's a subagent, what's a tool.

systems bridges subagents tools external agent systems
%%{init: {'theme':'neutral'}}%%
block-beta
columns 5
c1["/nai-chief-of-staff"] c9["/nai-cohort-census"] c8["/nai-document"] c3["/nai-newsletter"] c4["/nai-option-study"]
c7["/nai-paper-ingest"] c2b["/nai-payroll-theodora"] c5["/nai-review"] c6["/nai-spec-drafter"] c2["/nai-tax-theo"]
space space space bridge["/nai-issue-to-agent"] checkAct["/nai-issue-check"]
sub["The subagent pool"] space space space space
toolOther["Other tools<br/>web · mailbox · bank · files"] space presto["Prestolex<br/>(no connections)"] onto["nai-onto<br/>(no connections yet)"] toolNink["nai-analysis"]
libwiki["library-wiki (external)<br/>own CLAUDE.md, own repo"] space space space space

c1 --> sub
c2 --> sub
c2b --> sub
c3 --> sub
c4 --> sub
c5 --> sub
c6 --> sub
c7 --> sub
c8 --> sub
c9 --> toolOther
sub --> toolOther
bridge --> toolNink
checkAct --> toolNink
toolOther --> libwiki

classDef command fill:#dcefe9,stroke:#0f6f63,stroke-width:2px
classDef bridgecls fill:#fdf3e0,stroke:#8a5a00,stroke-width:2px
classDef subcls fill:#fff,stroke:#555,stroke-width:2px
classDef toolcls fill:#f4f1ea,stroke:#8a7a5a,stroke-width:2px
classDef externalcls fill:#ece5f7,stroke:#6b3fa0,stroke-width:2px
class c1,c2,c2b,c3,c4,c5,c6,c7,c8,c9 command
class bridge,checkAct bridgecls
class sub subcls
class toolOther,toolNink,onto,presto toolcls
class libwiki externalcls
Systems (green, top) each dispatch into the shared subagent pool — with one exception: /nai-cohort-census dispatches nothing, because counting files is deterministic enough to belong in a script rather than a prompt, so it reaches the file tools directly. Bridges (orange) are the two commands that reach nai-analysis directly instead of through the subagent pool: /nai-issue-to-agent dispatches a whole other system before it writes back (its own page has that detail), while /nai-issue-check has no orchestrator wave at all — it only ever reads, on a cron plus on demand. Subagents (white) is one box standing in for the whole pool — the full breakdown is its own page. Tools (tan) is where every side effect actually happens: ordinary subagents only ever reach the general-purpose tools on the left; nai-analysis on the right is reachable only through the two bridges above it, never from the subagent pool directly. library-wiki (purple, bottom) is a genuine agent system — it has its own CLAUDE.md and runs its own ingest/query/lint behaviors — but it isn't one of the systems above: it lives in its own repository, is invoked by opening it directly in its own Claude Code session, and connects to this workspace only on disk, through the shared work/ and wiki/ folders paper-ingester writes into and six other subagents read from. Prestolex and nai-onto sit beside nai-analysis in the same tan as their neighbor, because each is the same kind of thing — a web application in its own repository, something an agent could reach rather than an agent system in its own right. Both are drawn with no lines at all for the one difference that matters here: nothing in this workspace reaches them, and they reach nothing here — for Prestolex that is by design, for nai-onto simply not yet. Full pattern: its own page →. Full tool list: the tools roster →. Full detail on the library itself: one offline knowledge base, six agents →; on the three apps: nai-onto → · nai-analysis → · Prestolex →.

The systems

The pattern above, repeated. The layers are always the same; only the job changes.

/nai-chief-of-staff

Calendar, inbox, and radar into one morning briefing. Drafts, never sends.

/nai-cohort-census

Counts this repo's own agents, commands, and guardrails, then asks you the rest. Names and counts only; never submits.

/nai-document

Surveys this workspace from its own agent files. Every claim quoted and checked once — no loop. Stages every page; only promotes what passes.

/nai-newsletter

Cited research in two waves, then a writer that cannot browse.

/nai-option-study

Architecture options, verified against real-world use in a bounded loop. You decide.

/nai-paper-ingest

Detects a paper link in a GitHub issue on this repo — direct or one hop away — and files the resolved PDF into the research library. One comment, never a cockpit.

/nai-payroll-theodora

One month's Lohnsteuer, collected independently of the quarter. Small, no cockpit.

/nai-review

Review findings with quoted evidence, every citation checked once — no loop. You deliver.

/nai-spec-drafter

A grammar drafted from dropped model instances, every citation checked once — no loop. You decide whether to adopt it.

/nai-tax-theo

A closed quarter pulled from the bank into a UStVA pack. Prepares; you file and pay.

The subagent & tools rosters

The systems above dispatch a shared pool of subagents between them, and every one of those subagents reaches the outside world through a short, explicit tool list — including one thing, nai-analysis, that no subagent's tool list ever includes. The subagent roster below lists all 25 subagents, including /nai-document's four doc-* subagents (doc-scoper, doc-surveyor, doc-renderer, doc-checker). The tools roster maps the same pool by capability; run /nai-document tools when tool lists change and that page needs a refresh.

The subagent roster

Every subagent, what each does, and a click-to-trace commands→subagents map.

The tools roster

Every tool by category — web, mailbox, bank, files — and the separate, orchestrator-only route into nai-analysis.

Bridge to Web Application

Two more commands run the same orchestrator/tools shape as the systems above, but neither dispatches subagents of its own — both exist to reach nai-analysis directly. /nai-issue-to-agent's middle wave is an entire other system, dispatched whole. /nai-issue-check is the plainer of the two: no orchestrator wave at all, just a script and a decision whether to notify — and unlike the bridge beside it, it never writes to nai-analysis at all.

/nai-issue-to-agent

Feeds one nai-analysis issue to /nai-option-study or /nai-review, then STOPs for confirmation before posting the write-up back as a comment.

/nai-issue-check

Hourly cron plus on-demand check for new client comments, decisions, or issues — one push notification if anything's new, silence otherwise.

Web Applications

Three more things aren't part of the pattern above at all: real products rather than slash-command dispatches, each in its own separate repository. nai-analysis is what both bridge commands above reach into; nai-onto and Prestolex are unrelated to the systems on this page entirely.

nai-analysis

A live Next.js + Supabase app for client-confidential architecture decisions. Built with GSD, not the orchestrator/subagent/tool pattern.

nai-onto

Collaborative ontology modeling — classes, relations, instances, graphs, scripting, and the same model as .nai code or over MCP. Next.js + Supabase, same GSD discipline, live at nai-onto.vercel.app.

Prestolex

An AI-refereed party word game — console screen, phones as answer pads, Claude as referee. Next.js + Supabase + Stripe, same GSD discipline, live at prestolex.vercel.app.

Common Concepts & Insights

The ideas that cut across every system above — the shared pattern, the shapes of verification, where the safety boundaries live, and what building one of these costs — now live on their own page.

Common Concepts & Insights →

Nine cross-cutting write-ups, from the orchestrator/subagent/tool pattern to what the nai- rename cost.

Start the tour/nai-chief-of-staff