Agent Systems — User Guide

A genuine agent system — it has its own CLAUDE.md that turns Claude into a wiki maintainer — but it isn't one of the systems below and you don't run it from here. Open its own library-wiki/ folder as a separate Claude Code project (its work/ sibling folder holds your source PDFs and documents, topic-named by folder) and tell it things like “ingest new sources from ../work/”, “what have I read about devops?”, or “what spans devops and itil?”. It turns raw sources into summaries, entities, concepts, and cross-topic connections in its own wiki/ folder — on your schedule, in batches.

How it connects to this repo: /nai-paper-ingest is the only thing here that writes to it — and only to work/, never to wiki/. Six other subagents (tech-radar, company-research, option-verifier, ea-context-reviewer, review-scoper, spec-context-scoper) read its wiki/ pages, matched by topics frontmatter, and never write there — see one offline knowledge base, six agents for the full detail.

Dispatches three subagents in parallel — calendar-briefing (today's meetings), email-triage (inbox, creates Gmail drafts, never sends), and tech-radar in scan mode — then synthesizes cross-cutting "top of mind" bullets and optionally a 2–3 line deep-dive on one meeting via company-research.

Output: 05 Briefings/<YYYY-MM-DD>.md plus an HTML cockpit at 05 Briefings/<YYYY-MM-DD>.html — that page, not the chat, is where you work through the day. Email drafts wait for your review/send in Gmail itself.

Counts what this workspace actually contains — .claude/agents/, .claude/commands/, .cursor/skills/ (Cursor mirrors of the /nai-* commands), MCP servers in .mcp.json, and the hook events and permission rules in .claude/settings.json — by running scripts/cohort-census/census.py, or by replicating the same read-only scan by hand if Python 3 isn't available. It then asks you the five things a script can't know: which systems are in real recurring use, roughly how many hours/week that reclaims against 01 Preparation/tasks-eating-time.md, the highest autonomy level actually run, your best build, and your best failure. Skip is a valid answer to every one.

Output: a ready-to-submit markdown block shown in chat, written to a file only if you name one. Names and counts only — never file contents, prompt text, or any data an agent has touched; that boundary is what makes the census safe to share. Posting it to the cohort channel stays your call.

Regenerates one documentation target, routed to one of three lanes: an architecture page surveyed from the agent and command files it documents, an editorial page (this guide, the feature overview, the index, CLAUDE.md, the convention docs) whose existing claims are checked rather than rewritten, or a blog post rendered from an existing markdown draft. doc-scoper inventories the sources and detects create vs. update; doc-surveyor or doc-renderer writes a staged page; doc-checker then adversarially re-opens every citation and verdicts CONFIRMED / UNSUPPORTED, once, with no loop — the same shape as /nai-review.

Output: 12 Documentation/runs/<target>/report.md plus the staged page under proposed/. A page is promoted into docs/ automatically only if all three hold: it is new, every verdict is CONFIRMED, and every publish-guard line passes. Anything that would overwrite a page already live stops and waits for you — promoting it afterwards is a separate, deliberate act.

Checks nai-analysis for activity since the last check — a comment or decision from someone other than the issue's owner, or a brand-new issue from anyone but you — and sends one push notification summarizing what's new. Silent if there's nothing new; this is the on-demand twin of an hourly scheduled check that calls the same script.

Pulls one issue from the nai-analysis app, writes it as that agent's input file, and runs /nai-option-study or /nai-review on it exactly as if you'd run it by hand. Once the deliverable is ready it stops and asks for explicit confirmation before posting the write-up back onto the issue as a comment — comments on that app can't be edited or deleted once posted, so this gate is not skippable. It never edits issue content or changes status.

Two research waves via tech-radar (broad scan, then deep cited briefs on the top 2–3 candidates) feed newsletter-writer, which has no web access by design — every claim in the issue has to trace back to research.md.

Output: 07 Newsletter/<YYYY-MM>/research.md, issue.md (paste this), issue.html (styled preview).

07 Newsletter/voice-profile.md bootstraps once on the first run, then is hand-edited only — the agent reads it, never overwrites it. Correct it via the voice interview (Prompts/prompt-voice.md), not by deleting and re-bootstrapping.

Drop 08 Option Studies/inputs/<slug>/request.md (required) and an ea/ folder of EA-repository exports (optional — thinner context is fine, the study says so). The option-recommender proposes 2–4 options; the option-verifier checks each against cited real-world evidence and verdicts PASS / THIN / FAIL. Failed options loop back — at most 3 rounds — after which anything still failing is flagged, never silently dropped. The recommender has no web access on purpose, so it can't grade its own homework.

Output: studies/<slug>/option-study.md (the deliverable) plus context-review.md, a full round log, and an option-study.html cockpit.

Reads one GitHub issue on this repo (not nai-analysis) and checks whether it links to a research paper — a direct PDF, or a landing page one hop away (arXiv, DOI, and a handful of major publishers by default). The paper-ingester subagent resolves the actual PDF, downloads it, and files it into H:\Geteilte Ablagen\knowledge\work\<Topic>\ — the personal research library's own source folders, picked up later by a separate, manually-triggered library-wiki batch ingest. This command never writes into that wiki itself, and posts exactly one confirmation comment on the issue; it never edits the issue's content or closes it.

Output: nothing inside this repo — the filed PDF lives outside it, and the only trace here is the GitHub comment. No markdown deliverable, no cockpit.

Runs monthly, independently of the quarterly close — German Lohnsteuer-Anmeldung frequency is set independently of UStVA frequency. Drop the payslip export into 06 Tax Agent/inputs/payroll/ named with the period (e.g. 2026-07-payslip.pdf) and run it right after the payslip drops. Its only input is that file; if it's absent the agent flags the month rather than inventing figures.

Output: 06 Tax Agent/payroll/<YYYY-MM>/payroll-summary.md — a short note, no cockpit. Nothing to file from this run alone; it records the month for /nai-tax-theo to pick up when the quarter closes.

Drop 09 Review Packs/inputs/<slug>/subject/ (required — the material under review), optional criteria.md, optional ea/ for landscape context. finding-drafter writes findings, each anchored to a verbatim quote from a dropped file — no quote, no finding, just an open question. finding-checker then adversarially re-opens every citation and verdicts CONFIRMED / UNSUPPORTED, once, with no loop: a finding with no evidence has no "better version" to iterate toward.

Output: packs/<slug>/review-pack.md (the deliverable) plus review-brief.md, drafter/checker working files, and a review-pack.html cockpit. No agent in this system touches the web.

Drop 10 Spec Drafts/inputs/<slug>/instances/ (required — the model instance files, any format) and optionally existing-spec.md beside it, whose presence alone switches the run from drafting a spec from scratch to drafting only the delta against it — no need to say which mode you want. spec-rule-drafter writes rules, each anchored to a verbatim quote from a dropped instance file and tagged NEW / CHANGED / REMOVED — no quote, no rule, just an open question. spec-rule-checker then adversarially re-opens every citation and verdicts CONFIRMED / UNSUPPORTED, once, with no loop — the same shape as /nai-review.

Output: drafts/<slug>/spec-draft.md (the deliverable) plus scoping-brief.md, drafter/checker working files, and a spec-draft.html cockpit. No agent in this system touches the web.

Quarterly UStVA + loan close for Nink Future GmbH (set once in 06 Tax Agent/inputs/config.yaml). One-time setup: copy config.example.yaml and loan.example.yaml into place and fill them in — both are gitignored.

Each month (payroll): drop the payslip export into 06 Tax Agent/inputs/payroll/ and run /nai-payroll-theodora — no Qonto connector needed, that command never touches the bank. Lohnsteuer is collected monthly and only rolled up here.

Each quarter (VAT + loan): confirm all three months of the quarter have already been run through /nai-payroll-theodora — this command reads their output and refuses to compute a partial Lohnsteuer figure if one is missing. Then enable the Qonto connector and run the command. Review <period>/tax-pack.md — figures, UStVA by Kennziffer, a CFO checklist, and the filing deadline — then file (ELSTER) and pay yourself. Disable Qonto again afterward.