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
```

12 hooks enforce the pipeline (7 pipeline + 3 session-audit + 2 capability — `agent-capability-check` / `agent-capability-verify` wire the v0.24 substrate capability layer; see `hooks/` directory for details):

- **`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.

```bash
./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`](https://github.com/rhysd/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.