NAI OS

The subagent roster

All 25 subagents in one map: what each does, what it may touch, and which command dispatches it.

The pattern page describes the subagent layer in the abstract: “one job, own context.” This page is the concrete version — the actual roster, surveyed from the files themselves. Every row below is one file in .claude/agents/, quoted from its own description: frontmatter and shown with the exact tools: line that decides what it can reach; every line in the map below is one dispatch step written out in a file under .claude/commands/. Most subagents belong to exactly one command. Two don't: tech-radar is dispatched by both /nai-chief-of-staff (“tech-radar — scan mode (say "mode: scan" in the dispatch)”) and /nai-newsletter, which runs it twice — once in scan mode, then “tech-radar in on-demand mode for each — in parallel, one Agent call per topic in a single message”; cockpit-writer is dispatched by five commands as their last step, turning whatever markdown the system just wrote into one self-contained HTML review surface.

Commands → subagents

The map below is dense — 9 commands, 25 subagents, 30 usages. Click a box to trace just its connections; click it again, or click empty space, to clear.

command (.claude/commands) subagent (.claude/agents) dispatched every run conditional

%%{init: {'theme':'neutral', 'flowchart':{'htmlLabels':false,'nodeSpacing':22,'rankSpacing':260}}}%%
flowchart LR
    c1["/nai-chief-of-staff"]
    c2["/nai-tax-theo"]
    c2b["/nai-payroll-theodora"]
    c3["/nai-newsletter"]
    c4["/nai-option-study"]
    c5["/nai-review"]
    c6["/nai-spec-drafter"]
    c7["/nai-paper-ingest"]
    c8["/nai-document"]

    a1["calendar-briefing"]
    a2["email-triage"]
    a3["tech-radar"]
    a4["company-research"]
    a5["cockpit-writer"]
    a6["qonto-collector"]
    a7["payroll-lohnsteuer"]
    a8["loan-interest-vga"]
    a9["vat-worksheet"]
    a10["voice-profiler"]
    a11["newsletter-writer"]
    a12["ea-context-reviewer"]
    a13["option-recommender"]
    a14["option-verifier"]
    a15["review-scoper"]
    a16["finding-drafter"]
    a17["finding-checker"]
    a18["spec-context-scoper"]
    a19["spec-rule-drafter"]
    a20["spec-rule-checker"]
    a21["paper-ingester"]
    a22["doc-scoper"]
    a23["doc-surveyor"]
    a24["doc-renderer"]
    a25["doc-checker"]

    c1 --> a1
    c1 --> a2
    c1 --> a3
    c1 -.->|"optional"| a4
    c1 --> a5

    c2 --> a6
    c2 --> a8
    c2 --> a9
    c2 --> a5

    c2b --> a7

    c3 -.->|"first run only"| a10
    c3 --> a3
    c3 --> a11

    c4 --> a12
    c4 --> a13
    c4 --> a14
    c4 --> a5

    c5 --> a15
    c5 --> a16
    c5 --> a17
    c5 --> a5

    c6 --> a18
    c6 --> a19
    c6 --> a20
    c6 --> a5

    c7 --> a21

    c8 --> a22
    c8 -.->|"survey lane"| a23
    c8 -.->|"blog lane"| a24
    c8 --> a25

    classDef command fill:#dcefe9,stroke:#0f6f63,stroke-width:2px
    classDef subagent fill:#fdf3e0,stroke:#8a5a00,stroke-width:1.5px
    class c1,c2,c2b,c3,c4,c5,c6,c7,c8 command
    class a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a19,a20,a21,a22,a23,a24,a25 subagent

Every command (green, left) connected directly to the subagents it dispatches (orange, right) — no grouping boxes, so every line is one real usage, not a bundle. A subagent with lines from more than one command (tech-radar, cockpit-writer) is genuinely shared. The two dotted lines out of /nai-document are its lanes: “Survey: dispatch doc-surveyor” and “Blog: dispatch doc-renderer” — one run takes one of them, never both, and in the editorial lane “no generator runs.” Not pictured: /nai-issue-to-agent, /nai-issue-check and /nai-cohort-census dispatch no subagents of their own — see the note below. Click any box to isolate its connections.

Three commands are missing from the diagram on purpose, because none of them dispatches a subagent. /nai-issue-to-agent dispatches an entire other command instead: “Invoke the Skill tool for <agent> with args: <slug> — identical to running /nai-option-study <slug> or /nai-review <slug> by hand”, and that command then runs its own subagents exactly as shown above. Detail: its own page. /nai-issue-check runs a script and sends one notification — “Compose ONE PushNotification call summarizing all findings from this run (not one call per finding)” (its page). /nai-cohort-census prefers “the deterministic collector” — “Run python3 "scripts/cohort-census/census.py" . --name "<name>" (use $ARGUMENTS as the name if given, otherwise ask)” — plus a short interview, with no subagents at all.

The roster

Subagent	Dispatched by	`tools:` grant	What it does, from its own `description:`
calendar-briefing	/nai-chief-of-staff	`mcp__google-workspace__list_calendars, mcp__google-workspace__get_events, WebSearch, WebFetch`	“Briefs the user on today's calendar — meetings, attendees, external people/companies, and schedule friction.”
email-triage	/nai-chief-of-staff	`mcp__google-workspace__search_gmail_messages, mcp__google-workspace__get_gmail_message_content, mcp__google-workspace__draft_gmail_message`	“Triages the user's Gmail — ranks the top 5 priorities, flags likely spam/low-priority, and drafts suggested replies as Gmail drafts. Read + create-draft only; never sends or deletes.”
tech-radar	/nai-chief-of-staff, /nai-newsletter	`WebSearch, WebFetch, Read, Glob, Write`	“On-demand deep research and daily headline scanning in the enterprise-architecture / MBSE domain.”
company-research	/nai-chief-of-staff (optional)	`WebSearch, WebFetch, Read, Glob, Write`	“Researches a company (competitor, partner, or prospect) and produces a structured intelligence brief.”
cockpit-writer	/nai-chief-of-staff, /nai-tax-theo, /nai-option-study, /nai-review, /nai-spec-drafter	`Read, Write, Glob`	“Renders a completed run's markdown into one self-contained HTML review cockpit — headline figures, decisions first, detail collapsed.” … “Never computes a figure the markdown does not contain.”
qonto-collector	/nai-tax-theo	`mcp__claude_ai_Qonto__get_organization, mcp__claude_ai_Qonto__list_transactions, mcp__claude_ai_Qonto__list_transaction_attachments, mcp__claude_ai_Qonto__get_attachment, mcp__claude_ai_Qonto__list_client_invoices, mcp__claude_ai_Qonto__list_credit_notes, mcp__claude_ai_Qonto__list_supplier_invoices, mcp__claude_ai_Qonto__list_statements, mcp__claude_ai_Qonto__get_statement, Read, Write, Bash`	“Pulls a closed quarter from the live Qonto MCP (transactions, client & supplier invoices, credit notes), downloads every receipt PDF immediately, and flags deductible debits missing a receipt. Read-only; writes structured JSON + PDFs to the period folder.”
payroll-lohnsteuer	/nai-payroll-theodora	`Read, Write, Glob`	“Reads the month's dropped payslip export from 06 Tax Agent/inputs/payroll/ and extracts Lohnsteuer, the CEO's own KV contribution (employee_kv_eur), the employer KV subsidy (employer_kv_subsidy_eur), and gross/net salary into <folder>/working/payroll.json.”
loan-interest-vga	/nai-tax-theo	`Read, Write, mcp__claude_ai_Qonto__list_transactions`	“Computes the shareholder loan's quarterly interest from inputs/loan.yaml, matches Qonto transfers by loan reference, and runs a rule-based vGA / fremdüblich checklist. Flags for the Steuerberater; never rules on the tax position.”
vat-worksheet	/nai-tax-theo	`Read, Write`	“Reads the collected Qonto JSON and builds the UStVA worksheet mapped to real ELSTER Kennziffern” … “with line-by-line tie-out and deltas vs prior quarter.”
voice-profiler	/nai-newsletter (first run only)	`WebFetch, Read, Write, Glob`	“Builds a reusable writing-voice profile for Udo Nink by analysing the English articles on udonink.de. Runs once to bootstrap 07 Newsletter/voice-profile.md; the file is then hand-edited, not regenerated.”
newsletter-writer	/nai-newsletter	`Read, Write`	“Drafts a monthly English EA/MBSE newsletter issue in Udo Nink's voice from a research file and a voice profile. Writes markdown + styled HTML to the period folder. Never sends or publishes.”
ea-context-reviewer	/nai-option-study	`Read, Write, Glob`	“Reviews a project request against dropped enterprise-architecture repository exports and writes the context review an option study is grounded in. Runs once per study; the option loop iterates on options, not on this review.”
option-recommender	/nai-option-study	`Read, Write`	“Proposes 2–4 architecture/solution options with trade-offs from a study's context review, and revises them against the verifier's critique in later rounds. No web tools by design — evidence enters the study only through the verifier.”
option-verifier	/nai-option-study	`WebSearch, WebFetch, Read, Glob, Write`	“Verifies each recommended option in a study round against documented real-world use via cited web research, and verdicts it PASS, THIN, or FAIL with an actionable critique. Never rewrites, adds, or drops an option.”
review-scoper	/nai-review	`Read, Write, Glob`	“Inventories a dropped review subject, the criteria in force, and any EA context, and writes the review brief a review pack is grounded in. Runs once per pack; the findings and their verification build on this brief, not on re-reads of the raw drop.”
finding-drafter	/nai-review	`Read, Write, Glob`	“Drafts review findings for a review pack — each mapped to a criterion, given a severity, and anchored to a verbatim quote from a dropped file. Concerns without citable evidence become open questions, never findings. No web tools by design.”
finding-checker	/nai-review	`Read, Write, Grep`	“Adversarially checks every drafted finding in a review pack — re-opens the cited file, hunts for the quoted evidence, and verdicts CONFIRMED or UNSUPPORTED with a reason. Never edits, adds, or drops a finding; never re-derives a severity.”
spec-context-scoper	/nai-spec-drafter	`Read, Write, Glob`	“Inventories a dropped set of model instances and detects create vs. update mode, and writes the scoping brief a spec draft is grounded in. Runs once per draft; the rules and their verification build on this brief, not on re-reads of the raw drop.”
spec-rule-drafter	/nai-spec-drafter	`Read, Write, Glob`	“Drafts spec rules for a spec draft — each given a change-tag and anchored to a verbatim quote from a dropped instance file. Patterns without citable evidence become open questions, never rules. No web tools by design.”
spec-rule-checker	/nai-spec-drafter	`Read, Write, Grep`	“Adversarially checks every drafted rule in a spec draft — re-opens the cited instance file, hunts for the quoted evidence, and verdicts CONFIRMED or UNSUPPORTED with a reason. Never edits, adds, or drops a rule; never re-derives a change-tag.”
paper-ingester	/nai-paper-ingest	`Bash, Read, Glob, WebFetch`	“Resolves a candidate link from a GitHub issue to its actual PDF (direct link, arXiv abstract-page transform, or one hop via a landing page), downloads it, and files it into the right work/<Topic>/ folder for the personal research library. Never writes to the wiki itself”
doc-scoper	/nai-document	`Read, Write, Glob, Grep`	“Inventories the source files behind one documentation target, detects whether its page is being created or updated, and in the editorial lane extracts the page's checkable factual claims. Runs once per documentation run; the generators and the checker build on this brief, not on re-reads of the raw sources.”
doc-surveyor	/nai-document (survey lane)	`Read, Write, Glob`	“Regenerates one architecture page as an as-built survey of the agent and command files it documents, anchoring every factual assertion to a verbatim quote. Writes a staged page only; never publishes, and never writes prose it cannot cite.”
doc-renderer	/nai-document (blog lane)	`Read, Write`	“Renders one markdown blog draft into a styled, self-contained HTML page in the site's design language. A view only — it computes nothing, adds nothing, and every sentence on the page appears verbatim in the markdown.”
doc-checker	/nai-document	`Read, Write, Grep`	“Adversarially checks every claim in a documentation run — re-opens the cited file, hunts for the quoted evidence, and verdicts CONFIRMED or UNSUPPORTED with a reason. Never edits, adds, or drops a claim; never rewrites a page.”

Every row above comes straight from each agent's own description: and tools: frontmatter, and each command's actual dispatch steps — nothing here is a paraphrase from a design doc that could have drifted from what the code does. Two grants differ in kind from the rest. email-triage is the only one holding a tool that writes into a remote system, and it is fenced in prose as well as in the grant: “You may ONLY read messages and CREATE DRAFTS. You must NEVER send, reply-send, delete, trash, archive, or otherwise modify the mailbox.” paper-ingester is the only one that writes outside this repo — “Nothing written inside this repo. The only filesystem change is the one .pdf placed under H:\Geteilte Ablagen\knowledge\work\<Topic>\ per successfully filed candidate.”

The guardrails, and where each one lives

Enforced in	Guardrail, quoted
tech-radar.md cockpit-writer.md doc-surveyor.md	The standard boundary paragraph, carried verbatim in agent file after agent file: “Read-only against every remote system. You write files inside this repo only, and only the files named in `## Output`. You NEVER create, change, delete, or send anything in a remote system — you have no such tools and must not attempt it.”
calendar-briefing.md	“You have READ-ONLY access to the calendar via `mcp__google-workspace__list_calendars` and `mcp__google-workspace__get_events` — you NEVER create, modify, move, or delete events.”
email-triage.md	“You may ONLY read messages and CREATE DRAFTS. You must NEVER send, reply-send, delete, trash, archive, or otherwise modify the mailbox. You have no tools to do so, and you must not attempt it.”
qonto-collector.md	“`Bash` is granted for ONE purpose only: `curl`-downloading Qonto attachment URLs to the receipts folder. Do not use it for anything else.”
paper-ingester.md	“`Bash` is granted for exactly two purposes: `curl`-downloading a resolved PDF URL to a system temp path, and `mv`/cleanup to place the downloaded file into `work/<Topic>/` and remove the temp copy afterward.” And: “You never write to `wiki/` under the library. You never edit or delete an existing file under `work/`.”
paper-ingester.md	The one guardrail with a second, non-prose enforcement point: “This isn't prose-only: `.claude/settings.json` denies any `mv`/`cp`/`curl` Bash command whose arguments reference `library-wiki...wiki` at the permission layer, ahead of execution — a second, structural backstop under this instruction, not a replacement for following it.”
cockpit-writer.md	“You are a view, never a calculator. Every figure, date, and label you render must appear verbatim in a file you read.” And for the page it writes: “No CDN, no external font, no remote image, no `fetch`, no network of any kind.”
loan-interest-vga.md	“You FLAG risks; you NEVER decide whether the loan is fremdüblich, which tax rate applies, or whether a vGA exists — that is the Steuerberater's call. Never invent contract terms.”
vat-worksheet.md	“Compute ONLY from the collected source files. NEVER fabricate a figure. Ambiguous classification → put the line in "Unclassified — needs review", not a guessed Kennziffer.”
payroll-lohnsteuer.md	“NEVER invent a figure: if the payslip is missing or unreadable, flag it (see Missing input) and stop — do not guess.”
voice-profiler.md	“You write `07 Newsletter/voice-profile.md` only if it does not already exist — if it exists, STOP (see Missing input) and never overwrite a profile a human may have hand-corrected.”
newsletter-writer.md	“You have no web tools, by design. Everything you assert comes from the research file. If it is not in the research file, you cannot say it.”
option-recommender.md	“You have no web tools, by design. You cannot check whether an option is proven in the real world — that is the verifier's job, and the separation is what makes its gate mean something.”
option-verifier.md	“You never rewrite an option, never add one, and never drop one.” And: “Absence of evidence is a finding, never a reason to soften a verdict. A FAIL with an honest critique is worth more than a courtesy THIN.”
review-scoper.md (and the other two offline scopers)	“You have no web tools. Everything in your brief comes from the dropped files, plus whatever the research library (below) actually contains — never from memory.” `spec-context-scoper.md` carries the same sentence, and `ea-context-reviewer.md` the same rule for its review.
finding-drafter.md	“The evidence rule is absolute: no verbatim quote from a dropped file, no finding.”
spec-rule-drafter.md	The same rule, one noun changed: “The evidence rule is absolute: no verbatim quote from a dropped instance file, no rule.”
finding-checker.md	“You verdict findings; you never write them.” And: “Default to UNSUPPORTED when uncertain.”
spec-rule-checker.md	“You verdict rules; you never write them.” Its verdict arithmetic is stricter than the review pack's: “CONFIRMED only if every one of its citations independently holds.”
doc-scoper.md	“You never write into `docs/`. You never create or edit any file under `.claude/agents/` or `.claude/commands/`. You never author or rewrite prose for any page.”
doc-surveyor.md	“You never write into `docs/`. Your page goes to `12 Documentation/runs/<target>/proposed/` and the orchestrator decides whether it is ever published.”
doc-renderer.md	“You never author, edit, shorten, expand, correct, or reorder the author's prose. Not for grammar, not for clarity, not for length. Every sentence on the page appears verbatim in the markdown.”
doc-checker.md	“Your verdict is terminal: a claim you mark UNSUPPORTED is reported to the human, never sent back to be redrafted. Iterating would let the generator reword a claim until it slipped past you, which would destroy the citation discipline you exist to enforce.”

Some guardrails live one level up, in the command file rather than in any agent. The bound on the option-study loop is one: “You never run a fourth round. The bound is absolute”. So is the reason /nai-review and /nai-spec-drafter do not loop at all — “one adversarial verify pass, no loop. A finding whose evidence does not hold is flagged for the human, never sent back for redrafting”, and, in the spec drafter, “Like /nai-review, this system verifies with one adversarial pass, no loop.” And an entire system's web access can be settled in one command-file line: /nai-document says “It uses no web tools, and neither does any agent it dispatches.” Two more, from the tax side: the quarterly close states that “payroll-lohnsteuer is not dispatched here — its monthly collection happens via the standalone /nai-payroll-theodora command”, and the monthly run states why it renders nothing: “No cockpit. This is a small monthly utility run, not a CFO-facing review package”.

What a subagent hands back

Almost every agent file ends with a ## Return to orchestrator section, and almost every one of them is capped at a line or two. The documentation agents are the strictest — doc-checker's reads “Exactly one line:”, and doc-scoper's adds “Nothing else. No summary, no commentary.” cockpit-writer's says “One line, nothing more:”. The point is that the file on disk is the deliverable and the return line is only a pointer to it.

What that file is varies by agent, and the roster splits three ways. Most write into the repo, and name the path exactly: “Exactly one file: 09 Review Packs/packs/<slug>/working/findings.md”, “Exactly one file: 08 Option Studies/studies/<slug>/context-review.md”. The agents that brief the morning routine write nothing at all in that mode — calendar-briefing's output section reads “Return this block (nothing is written to disk):”, and tech-radar's scan mode the same: “Scan mode — return this block (nothing written to disk):”. And paper-ingester writes only outside the repo. The cockpits and staged pages are the visible end of that chain; the tools that make any of it reachable are on the tools roster.

Part of How the agent systems work. Sources of truth: .claude/agents/*.md · .claude/commands/*.md

NextThe tools roster →