KeiSeiKit-1.0/docs/ARCHITECTURE.md

Architecture

How agents, blocks, manifests, the assembler, and cross-tool bridges fit together.

---

The build pipeline

  Manifest (_manifests/<name>.toml)          <-- source of truth
         |
         |   [assembler/src/*.rs]              <-- Rust binary
         v
  Generated agent (.claude/agents/<name>.md)  <-- regenerated, never hand-edited
         ^
         |                                     [hook: assemble-agents]
  Block edit (_blocks/<block>.md)             <-- triggers rebuild of ALL agents

10 hooks enforce the pipeline (7 pipeline + 3 session-audit):

• assemble-agents (PostToolUse, Write/Edit) — rebuilds the affected agent(s) whenever a manifest or a block changes. No manual rebuild needed.
• assemble-validate (PreToolUse, Bash) — blocks git commit inside ~/.claude if any manifest fails validation. Keeps the repo in a buildable state at all times.
• no-hand-edit-agents (PreToolUse, Edit/Write) — refuses edits to any .md under ~/.claude/agents/ that starts with the <!-- GENERATED --> marker, pointing you at the manifest instead. Override with AGENT_MIGRATION=1 for emergencies only.
• tomd-preread (PreToolUse, Read) — auto-converts opaque binary formats (.docx, .doc, .xlsx, .pptx, .csv) to markdown via the tomd primitive and redirects Claude to read the cached .md instead.
• agent-fork-logger (PreToolUse, Agent) — RULE 0.12 advisory: logs every Agent subagent invocation to the kei-ledger SQLite DB so the orchestrator can validate the fork bundle. Never blocks; silent no-op if kei-ledger is absent.
• orchestrator-dirty-check (PreToolUse, Agent) — RULE 0.13 advisory: stderr-warns when git status --porcelain of the current repo is non-empty before spawning a sub-agent, so orchestrators don't compound uncommitted output across parallel agents. Never blocks; bypass with ORCHESTRATOR_DIRTY_OK=1 (per-call) or ORCHESTRATOR_META=1 (meta-orchestrator).
• site-wysiwyd-check (PostToolUse, Edit/Write) — on frontend-source edits (.tsx, .vue, .svelte, .astro, .css, .html, .jsx, .ts) in a project with a live dev server (.keisei/dev-server.pid), takes a Playwright screenshot via mock-render and diffs against .keisei/target.png via visual-diff. Advisory-only — drift is reported to stderr, never blocks.
• session-end-dump (Stop event) — RULE 0.14 self-audit: archives the session JSONL trace and ingests it into kei-memory.
• milestone-commit-hook (PostToolUse, Bash) — RULE 0.14 self-audit: appends a one-line session summary to ~/.claude/memory/audit-backlog.md on every feat:/refactor:/merge commit.
• error-spike-detector (PostToolUse, any tool) — RULE 0.14 self-audit: tags + logs the pattern when 3+ errors occur within the last 20 tool calls.

Creating a new agent

Run the wizard in Claude Code:

/new-agent

You'll be asked (via multiple option-picker batches, not free-text) — each batch groups several click-only questions into a single AskUserQuestion call:

1. Project stack (Rust CLI / axum / SwiftUI / Flutter / FastAPI / Next.js / React-Vite / Vue-Nuxt / SvelteKit / Astro / Go / Embedded / Python ML)
2. Deploy target (local-only / EC2 / Cloudflare / Modal / Docker / none)
3. Uses paid APIs? (Yes / No)
4. Contains ML? (Yes / No)
5. Has credentials? (Yes / No)
6. Uses scrapers? (None / Free-tier / Paid tier)

Then one free-text prompt for slug + description + path + gotchas. The wizard composes the manifest, validates it, assembles the .md, and prints a two-step git-commit command you can run or edit first.

Adding custom blocks

Blocks are plain markdown in ~/.claude/agents/_blocks/. To add one:

1. touch ~/.claude/agents/_blocks/stack-mystack.md and write the block.
2. Reference it in a manifest's blocks = [...] list.
3. The PostToolUse hook rebuilds the affected agent(s) automatically.

Blocks should be 10-50 lines, single-concern, and readable in isolation. If a block exceeds ~60 lines, split it into two.

Adding custom manifests

Copy _templates/specialist.toml.template and fill the placeholders, OR run /new-agent and answer the wizard. Either way, the assembler validates the manifest and generates the .md on write.

Agents overview

All kit agents are namespaced under kei-* so they won't collide with your own agents (e.g. your personal validator or critic) living in ~/.claude/agents/.

Agent	Role
kei-code-implementer	Write production code, Constructor Pattern enforced, Test-First discipline
kei-infra-implementer	Deploy scripts, CI/CD, secrets management, cost-aware paid infra
kei-ml-implementer	Training scripts, inference code, Modal jobs, exact param counts
kei-critic	Read-only anti-pattern / bug / security / perf / debt finder
kei-validator	Fact-checker; verifies API existence, version compat, citations, doc claims
kei-security-auditor	Risk-classified security audit with variant analysis + supply chain check
kei-architect	Read-only structural analysis; dep graph, patterns, coupling
kei-researcher	Generic web + codebase research, evidence-graded findings
kei-ml-researcher	ML literature, benchmarks, reproducibility, tooling-reuse search
kei-cost-guardian	Pre-launch GO/NO-GO for paid compute (Modal, AWS, fal.ai, Apify, etc.)
kei-modal-runner	Modal compute orchestrator with KILL GUARD (never stops running jobs)
kei-fal-ai-runner	fal.ai image/video/3D generation expert

Cross-tool bridges

KeiSeiKit ships 11 verified tool-bridge templates under _bridges/. Render them into any project and the same Constructor-Pattern ruleset is visible to every AI coding tool you use — no drift, one source of truth.

Tools covered:

Tool	Output file
Cursor (legacy)	.cursorrules
Cursor (modern MDC)	.cursor/rules/main.mdc
Codex CLI / Warp / Zed / Antigravity fallback	AGENTS.md
GitHub Copilot	.github/copilot-instructions.md
Windsurf	.windsurf/rules/main.md
JetBrains Junie	.junie/guidelines.md
Continue.dev	.continue/rules/main.md
Google Antigravity / Gemini CLI	GEMINI.md
Aider	CONVENTIONS.md + .aider.conf.yml
Replit Agent	replit.md

Three ways to generate:

1. At install time — ./install.sh --with-bridges renders all 11 into $PWD after the normal install completes. Skipped if $PWD is the KeiSeiKit repo itself.
2. From the /new-agent wizard — Phase 8 asks click-only whether to generate all 11, just AGENTS.md, or skip.
3. Manually, any time — ~/.claude/agents/_bridges/emit.sh <project-dir> (the install copies _bridges/ into your agent fleet dir). Add --only <output-path> to restrict to a single file.

All paths are idempotent: existing bridge files in the project are skipped, never overwritten. See _bridges/README.md for the full template→output-path table.

Meta-composer

/compose-solution is the meta-creator: tell it what you want to solve in one free-text paragraph, it decomposes the task, greps existing blocks / skills / manifests / primitives / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, block, or pipeline invocation. Every decision except the intake is a click (option-picker), never free-text.

Example: "I want a hook that blocks rm -rf ~/ in any Bash call" → Phase 2 decomposes into (pattern-match, severity, event, wiki entry) → Phase 3 greps hooks/, _blocks/, _primitives/ for prior art → Phase 5 proposes hook = PreToolUse:Bash + pattern + exit 2 → Phase 7 hands off to /escalate-recurrence with severity and event pre-filled.

Phase 6 is the feedback loop: when a component has no prior art, the skill drafts a new _blocks/<slug>.md and — on your click — persists it. Next time /compose-solution (or /new-agent) runs, that block is discoverable. Every session leaves the kit a little smarter; the report prints _blocks/ count before → after so the growth is visible.

See skills/compose-solution/SKILL.md and its phase files (phase-1-intake.md through phase-7-assemble.md) for the full 7-phase pipeline.

Regenerating counts

Every number in the README / INSTALL.md (crates / skills / hooks / blocks / primitives / profile sizes) is wrapped in an HTML-comment marker — <!-- count:NAME -->24<!-- /count:NAME --> — and regenerated from sources of truth (_primitives/MANIFEST.toml, _primitives/_rust/Cargo.toml, filesystem walks). No more drift when a primitive or skill is added.

./scripts/regen-counts.sh            # rewrite README.md in place
./scripts/regen-counts.sh --check    # exit 1 if drift detected (no writes)

Pre-commit gate: scripts/precommit-counts-check.sh — wire it into your hook manager (or symlink into .git/hooks/pre-commit) to block commits when README counts drift from the sources.

Workflow-file editing protocol

Every .github/workflows/*.yml edit is defended by three gates. The v0.20.1 incident (a real-but-wrong-semantic SHA pin on dtolnay/rust-toolchain broke CI for 30 minutes before discovery) motivated formalising them.

• scripts/lint-workflows.sh — runs actionlint over every workflow file. Catches syntax errors, expression typos, dead if: branches, and shell-injection risks. If the binary isn't on PATH, the script prints an install hint and exits 0 (advisory). Install with bash scripts/install-actionlint.sh or brew install actionlint.
• scripts/validate-workflow-shas.sh — extracts every uses: <repo>@<sha40> pin from .github/workflows/*.yml + .github/dependabot.yml and runs git ls-remote https://github.com/<repo>.git <sha>. A fabricated or force-pushed-out-of-existence SHA exits 1 with SHA MISSING:. Network errors are soft ([UNVERIFIED]). Tag refs like @v4 or @stable are skipped (policy decision). Add trailing comment # validate-workflow-shas: skip=<reason> on a line to intentionally skip it.
• CI job workflow-lint — runs both scripts on every push and PR. Finishes in well under 30 s.
• Optional pre-commit hook: ln -sf ../../scripts/pre-commit-workflow-lint.sh .git/hooks/pre-commit — runs the two scripts only when a workflow file is staged.

SHA-pinning third-party actions defeats tag re-point attacks (CVE-2025-30066 class), but only if the SHA you wrote is real AND means what you think it means. actionlint catches the first class of mistake; validate-workflow-shas.sh catches the second. Together they close the window between local edit and CI-fail.