KeiSeiKit-1.0/README.md

# KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code

**A structural layer over Claude Code, Cursor, Continue, and Zed that catches the failure modes LLMs introduce at commit time — not after they ship.**

Drop-in toolkit: portable agent personas, tool-use hooks that refuse known-bad actions, click-through skill wizards, a Rust primitive library for the tasks Python ships wrongly, and a portable "brain" directory (USB / git / S3) that mounts into any MCP-capable client via one command.

## Why it exists

LLMs are statistically wired to produce plausible-but-wrong output. Context windows drop prior decisions, confident citations turn out to be fabricated, parallel terminals clobber each other's files, the same mistake lands on the third try because the retrospective from the first never reached the second session. None of that is solvable by better prompts — it is solvable by structure *around* the prompt.

KeiSeiKit is that structure: persistent agent memory across sessions, pre-commit hooks at every tool boundary, typed handoff artifacts between agents, a deterministic manifest-to-agent build, and nightly REM-style consolidation via a cloud cron. Constructor Pattern throughout — one file per concern, every abstraction replaceable.

**Rust-first by design.** Every primitive that can be Rust, is Rust. Type-system guarantees remove entire classes of hallucination at compile time: no `None`-vs-`[]` confusions, no missing `.await`, no unhandled `Result`. For LLM-authored code this is not a style preference but a survival constraint.

---

## At a glance

KeiSeiKit is scaffolding **around** Claude Code (and now Cursor / Continue / Zed via MCP). You still write your own agents, skills, and commits — the kit gives you the structure that keeps them coherent across sessions, machines, and parallel terminals.

The shipped building blocks, in plain terms:

- **Agents** assembled from reusable **blocks** (behavioural rules, stack profiles, deploy targets) so the same `kei-critic` persona works identically on every machine that installs the kit.
- **Hooks** at every tool-use boundary that refuse known-bad actions (pushing patent IP to github, hand-editing generated files, shipping an unverified citation) before they reach a commit.
- **Skills** that drive real work end-to-end via click-based `AskUserQuestion` wizards — spin up a project, compose a solution, scaffold CI, audit a session, set up nightly consolidation.
- **Rust primitives** covering the things Python ships wrongly: SQL migrations, changelog generation, config linting, cost ledgers, artifact handoff, firewall diffs, conflict scanners, and an offline markdown knowledge graph.
- **Exobrain mode** (v0.18+): a portable `brain` directory you can mount into any MCP-capable client via `keisei attach <path>` or `keisei mount <path>` (auto-attach-all). USB stick or cloud bucket — same memory + artifacts + personas across every client you run.
- **Sleep-sync** (v0.11+): your session traces push to a private git repo; a cloud-agent cron job does overnight REM-style pattern extraction; morning `git pull` shows the report.

## What it solves

| Problem you hit with vanilla Claude Code | What the kit adds |
|---|---|
| Every session starts cold — prior decisions forgotten | `kei-memory` session traces + cloud REM consolidation + `/self-audit` retrospective |
| Same mistake twice | `RULE 0.10 recurrence-escalate` skill + hook codifies it (rule file + wiki + block/enforce/warn/remind hook) |
| 4-8 parallel Claude terminals clobber each other | `kei-ledger` fork-tracking + `orchestrator-dirty-check` hook + `RULE 0.13` (orchestrator owns git) |
| Hallucinated API / fabricated citation shipped | `genesis-leak-guard` + `secrets-guard` + `citation-verify` hooks; Rust primitives replace Python where `None`-vs-`[]`-class bugs matter |
| Single-client lock-in (Claude Code OR Cursor OR Zed) | `keisei` CLI + 4 adapters — one brain, every client |
| No audit trail across branches | `kei-ledger` SQLite agent-fork history + `kei-store` memory-repo abstraction (GitHub / Forgejo / Gitea / FS / S3) |
| Drift between declared config and running state | `firewall-diff`, `ssh-check`, `kei-ci-lint`, `assemble-validate` hook |

Not a replacement for Claude Code — a persistent structural layer over it.

---

## What it is

KeiSeiKit is a comprehensive drop-in toolkit for [Claude Code](https://claude.com/claude-code). It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent `.md` files from TOML manifests deterministically, <!-- count:HOOKS -->10<!-- /count:HOOKS --> pre-wired PreToolUse/PostToolUse hooks (three of them dedicated to RULE 0.14 session self-audit), <!-- count:SKILLS -->39<!-- /count:SKILLS --> portable skills (including an interactive `/new-agent` wizard, 10 hub-and-spoke pipelines, and the `/self-audit` retrospective skill), **<!-- count:RUST_CRATES -->25<!-- /count:RUST_CRATES --> Rust primitive crates**, <!-- count:SHELL_PRIMITIVES -->13<!-- /count:SHELL_PRIMITIVES --> opt-in shell primitives (plus 3 always-copied sleep-sync helpers), and <!-- count:BRIDGES -->11<!-- /count:BRIDGES --> cross-tool bridge templates. Everything follows a Constructor Pattern: one file per concern, manifests as single source of truth, and the generated agent files are regenerated on every relevant edit.

The kit is MIT-licensed and fully generic — install it on a fresh machine and you get a sane <!-- count:AGENTS -->12<!-- /count:AGENTS -->-agent fleet (implementers, critics, researchers, cost-guardians, and more — all namespaced under `kei-*` so they won't collide with your own same-named agents), a wizard for spinning up new project specialists, 10 pipeline skills that combine primitives end-to-end (`/compose-solution`, `/site-create`, `/schema-design`, `/observability-setup`, `/auth-setup`, `/api-design`, `/ci-scaffold`, `/test-matrix`, `/docs-scaffold`, `/new-project`, `/vm-provision`), and a build pipeline that keeps every agent derivable from its manifest.

## Prerequisites

**Hard** (needed for every install, regardless of profile):

- **Rust** (stable toolchain) — the assembler Cargo workspace is always built
- **jq** — used by the shell hooks for JSON parsing (`brew install jq` / `apt install jq`)
- **Claude Code** — the agents, hooks, and skills target Claude Code's agent / skill / hook surface

**Soft** (only needed if the chosen profile pulls the primitive in — see the profile table below):

- **pandoc** — `tomd` uses it for `.docx` / `.pptx` / `.html` (needed for `core` / `full` profile)
- **Node + Playwright** — for the 3 browser-driven frontend primitives `design-scrape`, `live-preview`, `mock-render` (`frontend` / `full` profile); install with `npm i -g playwright && playwright install chromium`
- **sqlite3 CLI** — optional for manual DB inspection of `kei-ledger` / `kei-migrate` (their binaries embed SQLite via `rusqlite`; `ops` / `dev` profile)
- **hcloud / vultr-cli** — wrapped by `provision-hetzner` / `provision-vultr` (`ops` profile)
- **yq v4** (mikefarah/yq Go impl) — required by `kei-ci-lint` (`dev` profile)

`install.sh` checks only the deps relevant to the selected profile and soft-warns once per missing tool.

## Install

```bash
git clone <your-fork-of-this-repo> KeiSeiKit
cd KeiSeiKit
./install.sh                      # profile=minimal (default, no primitives)
```

`install.sh` is idempotent. It:

1. Creates `~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}`, `~/.claude/hooks`, `~/.claude/skills`
2. Copies all blocks + bridges (overwrites — these are SSoT from the kit)
3. Copies primitives ONLY for the selected profile (default: `minimal` = none). Tracks installed set in `~/.claude/agents/_primitives/.installed`.
4. Copies generic manifests (skips if you already have a manifest with that name)
5. Builds the Rust assembler (`cargo build --release` in `_assembler/`)
6. If any Rust primitive is in the selected profile: writes a scoped workspace `Cargo.toml` listing ONLY the installed crates, then `cargo build --release`
7. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
8. Copies the <!-- count:HOOKS -->10<!-- /count:HOOKS --> hooks and <!-- count:SKILLS -->39<!-- /count:SKILLS --> skills

After install, the only remaining step is merging `settings-snippet.json` into your `~/.claude/settings.json` to activate the hooks. You can do this automatically with `./install.sh --activate-hooks` or answer `y` at the end-of-install TTY prompt.

### Interactive install

Run `./install.sh` with no profile flag on a TTY and you get a menu:

- `whiptail` or `dialog` detected → curses-style TUI (radiolist for profile, checklist for custom)
- neither available → plain-text numbered picker (`1-7` + a `custom` option)

After the profile is chosen, an **Install Plan** screen summarizes what will be copied, which soft-deps are present (`jq`, `pandoc`, `playwright`, `cargo`, `hcloud`, `vultr-cli`, `yq`, `sqlite3`, `curl`), and the rough time + disk footprint — then asks `Proceed? [Y/n]`. Pass `--yes` to skip the confirm screen (the menu still runs). Pass `--no-execute` to parse menu + confirm and exit without copying anything (useful for dry-run). The menu is **skipped automatically** when any selection flag is passed (`--profile`, `--add`, `--remove`, `--list`) or when stdin/stdout is not a TTY (CI runs default to `minimal` exactly as before).

## Install profiles

By default `./install.sh` is **minimal** — agents + hooks + skills + bridges, no primitives. Fastest (~5s) and zero Rust compile for primitives. You opt into primitives via `--profile=<name>` or one-at-a-time via `--add=<name>`.

| Profile | Primitives added | Install time | Disk (approx) |
|---|---|---|---|
| `minimal` (default) | none | ~5s | ~2 MB |
| `core` | `tomd` | ~5s | ~2 MB |
| `frontend` | <!-- count:PROFILE_FRONTEND -->8<!-- /count:PROFILE_FRONTEND --> site tools: `mock-render`, `visual-diff`, `tokens-sync`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode` | ~60s | ~80 MB |
| `ops` | <!-- count:PROFILE_OPS -->8<!-- /count:PROFILE_OPS --> infra tools: `kei-ledger`, `ssh-check`, `firewall-diff`, `provision-hetzner`, `provision-vultr`, `harden-base`, `metrics-scrape`, `log-ship` | ~90s | ~50 MB |
| `dev` | <!-- count:PROFILE_DEV -->10<!-- /count:PROFILE_DEV --> dev tools: `kei-migrate`, `kei-changelog`, `kei-ci-lint`, `kei-docs-scaffold`, `kei-memory`, `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, `kei-store`, `kei-artifact` | ~60s | ~40 MB |
| `full` | everything (<!-- count:PROFILE_FULL -->38<!-- /count:PROFILE_FULL --> primitives) | ~5 min | ~200 MB |

Examples:

```bash
./install.sh                        # minimal (no primitives)
./install.sh --profile=frontend     # minimal + <!-- count:PROFILE_FRONTEND -->8<!-- /count:PROFILE_FRONTEND --> site tools
./install.sh --profile=full         # everything (old default behaviour)
./install.sh --add=kei-ledger       # add a single primitive on top of current install
./install.sh --add=kei-ledger,ssh-check
./install.sh --add=ops              # a profile name works too — unions its members in
./install.sh --list                 # show each primitive: name | kind | installed? | description
./install.sh --remove=kei-migrate   # remove one (rebuilds scoped rust workspace if needed)
```

Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<name>]` entry per primitive plus a `[profile]` block. Edit the manifest to define new profiles without touching `install.sh`.

> **Migrating from a full install:** if you're re-running `install.sh` after an earlier version that installed all primitives unconditionally, the new default (`minimal`) will REMOVE them. To preserve the old behaviour explicitly, pass `--profile=full` (currently <!-- count:PROFILE_FULL -->38<!-- /count:PROFILE_FULL --> primitives).

> **Re-install disclaimer:** `install.sh` is idempotent for clean state but **overwrites kit-owned `_blocks/`, `_primitives/`, `_bridges/`, `_templates/`, `_assembler/`, `hooks/`, and `skills/` on re-run** — local modifications under those directories are backed up to `<dir>.bak-TIMESTAMP/` (or, for shared hook files, to `<file>.bak-TIMESTAMP`). User-owned `_manifests/*.toml` are never overwritten.

### MCP server binary (zero-install path, v0.18)

From v0.18 each GitHub release ships a **single static binary** of the `@keisei/mcp-server` package for five platforms — no Node, no `npm install`. Drop the binary anywhere (USB stick, S3 bucket, Downloads folder) and run it. This is Phase 1 of the "exobrain" distribution goal: any MCP-capable client can mount KeiSeiKit from read-only media.

| Platform | Asset name |
|---|---|
| Linux x64 | `kei-mcp-server-linux-x64` |
| Linux arm64 | `kei-mcp-server-linux-arm64` |
| macOS x64 | `kei-mcp-server-darwin-x64` |
| macOS arm64 | `kei-mcp-server-darwin-arm64` |
| Windows x64 | `kei-mcp-server-windows-x64.exe` |

```bash
# Linux / macOS
curl -L -o kei-mcp-server \
  https://github.com/<your-fork>/KeiSeiKit/releases/latest/download/kei-mcp-server-darwin-arm64
chmod +x kei-mcp-server
# macOS only — clear Gatekeeper quarantine on the downloaded binary:
xattr -d com.apple.quarantine ./kei-mcp-server 2>/dev/null || true
./kei-mcp-server --stdio
```

Every asset has a matching `<name>.sha256` for integrity verification. Build details and local cross-compile recipes: `_ts_packages/packages/mcp-server/BUILD.md`.

If you drop the binary at `~/.claude/agents/_primitives/_rust/target/release/kei-mcp-server-<os>-<arch>[.exe]` (the same layout `install.sh` uses for Rust primitives), re-running `install.sh` will detect it and skip any bun/npm build step. Set `KEI_SKIP_MCP_BUILD=1` to force-skip that step regardless of detection.

### The `keisei` CLI — multi-client exobrain mount (v0.19+)

The `keisei` Rust crate is the entry-point that turns a **brain directory** (portable, filesystem-backed AI state — memory + artifacts + manifests + MCP server binaries) into an attachment on one or more AI clients in a single command. Brain layout:

```
<brain-root>/
├── manifest.toml          # schema_version, brain name, path pointers
├── memory/                # kei-memory git store (session traces, audit backlog)
├── artifacts/             # kei-artifact SQLite (typed handoff bundles)
├── manifests/             # user persona TOML library
└── bin/
    ├── kei-mcp-server-darwin-arm64
    ├── kei-mcp-server-darwin-x64
    ├── kei-mcp-server-linux-x64
    ├── kei-mcp-server-linux-arm64
    └── kei-mcp-server-windows-x64.exe
```

**`manifest.toml` — schema v2 (recommended, v0.20+)** dispatches to the right binary for the host at attach time:

```toml
[brain]
schema_version = 2
name = "my-brain"
created = "2026-04-22T00:00:00Z"

[paths.mcp_server]
darwin-arm64  = "bin/kei-mcp-server-darwin-arm64"
darwin-x64    = "bin/kei-mcp-server-darwin-x64"
linux-x64     = "bin/kei-mcp-server-linux-x64"
linux-arm64   = "bin/kei-mcp-server-linux-arm64"
windows-x64   = "bin/kei-mcp-server-windows-x64.exe"
```

A single brain on USB/iCloud now serves every host automatically. Schema v1 (single-string `mcp_server = "bin/..."`) is still accepted for backward-compat.

Four CLI commands:

| Command | What it does |
|---|---|
| `keisei attach <brain-path> [--client=X]` | Mount brain into a single detected client (default: first detected) |
| `keisei mount <brain-path>` | Auto-attach to **every** detected client (Claude Code, Cursor, Continue, Zed) in one call |
| `keisei detach` | Unmount — strips `mcpServers.keisei` from every client's config, deletes marker |
| `keisei list-adapters` | Tabular status of every adapter: name / detected / config path |
| `keisei status` | Show currently-attached brain, client list, health (does `mcp_server` binary still exist?) |

Use cases:

- **Laptop travel.** Brain lives on USB / iCloud Drive. Plug in at home → `keisei mount /Volumes/MyBrain` attaches to Claude Code + Cursor simultaneously. Unplug → `keisei detach` clears everything.
- **Team shared persona library.** Commit a brain repo to your private Forgejo/GitHub. Every developer clones it, runs `keisei mount ./team-brain`, same 30-agent persona library active in their Claude Code.
- **Cloud brain.** Point `keisei attach s3://my-bucket/brain/` at an S3-backed brain synced via `kei-store` (v0.21 — real S3 / R2 / MinIO backend behind the `s3` feature flag). Memory follows you to any machine with network.
- **Experimental personas in isolation.** Spin up a test brain via `cp -r ~/production-brain ~/experimental-brain`, `keisei attach ~/experimental-brain`. Iterate without touching production state.

Security hardening (v0.19.0):

- Brain `mcp_server` path **must be relative + inside the brain root** (rejects `/usr/bin/curl`, `../../etc/shadow`, `..\..\..\System32\`)
- Brain `name` validated against `^[a-z][a-z0-9_-]{0,63}$` regex
- Brain root rejected if it's a symlink (prevents USB → `$HOME` pivot)
- Adapters **refuse to clobber** existing `mcpServers.<name>` entries — you get an explicit `NameConflict` error, not silent overwrite
- All config writes go through `fsx::write_atomic_json` (Windows-safe via `tempfile::NamedTempFile::persist`)

Known deferred to v0.19.1: supply-chain hardening (commit `bun.lock`, SHA-pin GitHub Actions), marker file perms 0600, terminal-escape sanitization in status output, manifest size bound.

## Runtime hook controls

Every kit-shipped hook (v0.14.2+) honours two env vars so you can silence noise or isolate a failure without editing `~/.claude/settings.json`:

- `KEI_DISABLED_HOOKS` — comma- or space-list of hook base names (no `.sh`), e.g. `KEI_DISABLED_HOOKS=site-wysiwyd-check,milestone-commit-hook`. The literal `all` disables every hook.
- `KEI_HOOK_PROFILE` — one of `full` (default), `advisory-off`, `minimal`, `off`.

| Profile | What stays on |
|---|---|
| `full` (default) | Every hook |
| `advisory-off` | Disables pure-stderr advisories (`recurrence-suggest`, `citation-verify`, `error-spike-detector`, `milestone-commit-hook`). Safety gates stay on. |
| `minimal` | Only safety-critical: `no-github-push`, `genesis-leak-guard`, `no-hand-edit-agents`, `secrets-guard`, `assemble-validate`, `git-pre-commit-genesis`. Everything else off. |
| `off` | Every hook off — escape hatch for debugging hook interactions. |

```bash
# One-session disable of a single noisy hook:
export KEI_DISABLED_HOOKS=site-wysiwyd-check

# Permanent quieter profile (paste into ~/.zshrc / ~/.bashrc):
export KEI_HOOK_PROFILE=advisory-off

# Full re-enable:
unset KEI_DISABLED_HOOKS KEI_HOOK_PROFILE
```

Interactive wizard: run `/hooks-control` — click-only picker that shows current state and emits the `export` / `unset` command for you to paste. The skill never executes anything itself.

## What you get

| Category | Count | Examples |
|---|---:|---|
| Behavioral blocks | <!-- count:BLOCKS -->79<!-- /count:BLOCKS --> | `baseline`, `evidence-grading`, `rule-math-first`, `stack-rust-axum`, `stack-react-vite`, `stack-sveltekit`, `stack-astro`, `deploy-modal`, `api-fal-ai`, ... |
| Generic agents (manifests) | <!-- count:AGENTS -->12<!-- /count:AGENTS --> | `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, `kei-cost-guardian`, `kei-modal-runner`, ... |
| Hooks (PreToolUse / PostToolUse) | <!-- count:HOOKS -->10<!-- /count:HOOKS --> | `assemble-agents`, `assemble-validate`, `no-hand-edit-agents`, `tomd-preread`, `agent-fork-logger`, `orchestrator-dirty-check`, `site-wysiwyd-check`, `session-end-dump`, `milestone-commit-hook`, `error-spike-detector` |
| Portable skills | <!-- count:SKILLS -->39<!-- /count:SKILLS --> | `compose-solution`, `new-agent`, `new-project`, `site-create`, `schema-design`, `observability-setup`, `auth-setup`, `api-design`, `ci-scaffold`, `test-matrix`, `docs-scaffold`, `vm-provision`, ... |
| Primitives (Rust crates, opt-in) | <!-- count:RUST_CRATES -->25<!-- /count:RUST_CRATES --> | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync`, `kei-memory`, `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, `kei-store`, `kei-router`, `kei-sage`, `kei-task`, `kei-chat-store`, `kei-crossdomain`, `kei-search-core`, `kei-content-store`, `kei-social-store`, `kei-curator`, `kei-auth` |
| Primitives (shell, opt-in via profile) | <!-- count:SHELL_PRIMITIVES -->13<!-- /count:SHELL_PRIMITIVES --> | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
| Shell helpers (always copied) | 3 | `kei-sleep-setup`, `kei-sleep-sync`, `kei-sleep-queue` (dormant until you run `/sleep-setup`) |
| Cross-tool bridges | <!-- count:BRIDGES -->11<!-- /count:BRIDGES --> | Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit |

Of the <!-- count:BLOCKS -->79<!-- /count:BLOCKS --> blocks, the **8 base blocks** (`baseline`, `evidence-grading`, `memory-protocol`, `rule-pre-dev-gate`, `rule-test-first`, `rule-error-budget`, `rule-double-audit`, `rule-math-first`) are referenced directly by the <!-- count:AGENTS -->12<!-- /count:AGENTS --> shipped manifests. The remaining blocks (`stack-*`, `deploy-*`, `api-*`, `scraper-*`, `domain-*`) are a library consumed by the `/new-agent` wizard and the hub-and-spoke pipeline skills: when you compose a project specialist or spin up a site, the wizard / pipeline picks the appropriate blocks and emits artefacts that reference them.

**Cognitive mode blocks** (`_blocks/mode-*.md`) are composable behavioural skews — `mode-skeptic`, `mode-devils-advocate`, `mode-minimalist`, `mode-maximalist`, `mode-first-principles`. Add any combination to an agent's manifest `blocks = [...]` list to stack the mode. Modes compose: `mode-skeptic` + `mode-minimalist` gives you an adversarial pruner; `mode-devils-advocate` + `mode-first-principles` gives a constraint-driven steel-manner. See `_blocks/README.md` for the full list.

## 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.

## Pipelines

Hub-and-spoke skills that combine primitives into end-to-end flows. Each one is an option-picker-first, free-text-last wizard; every phase has a verify-criterion.

| Skill | One-line purpose |
|---|---|
| `/compose-solution` | Meta-composer: decompose any task, grep prior art, propose math-first architecture, assemble the right artefact (agent / skill / hook / block) |
| `/new-project` | Bootstrap a project specialist agent + repo skeleton + bridges + ledger row |
| `/new-agent` | Interactive 6-question wizard that builds a project-specialist manifest and its `.md` |
| `/site-create` | Frontend stack pick → design tokens → scaffold → WYSIWYD loop (mock-render, visual-diff, tokens-sync) |
| `/schema-design` | DB schema design → migrations → `kei-migrate` apply (PG/SQLite/MySQL autodetect) |
| `/observability-setup` | Pick metrics + logs stack → scrape + ship config (`metrics-scrape`, `log-ship`) |
| `/auth-setup` | Pick auth model (session / JWT / OAuth2) → emit routes + middleware + token rotation |
| `/api-design` | Contract-first: pick REST vs GraphQL vs gRPC, emit types + handlers + tests |
| `/ci-scaffold` | GitHub Actions / Forgejo Actions workflow skeleton + `kei-ci-lint` pre-commit |
| `/test-matrix` | Test stack matrix: unit / integration / e2e / visual; pick stack, emit skeleton |
| `/docs-scaffold` | Doc site skeleton (mdbook / docusaurus / astro-starlight) + `kei-changelog` generator |
| `/vm-provision` | VM provider pick → `provision-*` primitive → `harden-base` + `ssh-check` + `firewall-diff` verification |

All pipelines share a single discovery layer: `/compose-solution` Phase 3's prior-art grep covers `_blocks/`, `_manifests/`, `_primitives/` (shell + Rust), `skills/`, `_bridges/`, `hooks/` — so any pipeline can reuse primitives without re-inventing them.

## Session self-audit (RULE 0.14)

KeiSeiKit auto-analyzes sessions on 3 triggers:

- **Stop event** — session ended; `session-end-dump.sh` archives the JSONL trace and ingests it into `kei-memory`.
- **Milestone commits** — `git commit -m "feat:"` / `"refactor:"` / `git merge`; `milestone-commit-hook.sh` appends a one-line session summary to `~/.claude/memory/audit-backlog.md`.
- **Error spike** — 3+ errors in the last 20 tool calls; `error-spike-detector.sh` tags the pattern and logs it.

Findings surface via click-only `AskUserQuestion`, routing to `/escalate-recurrence` (codify rule + wiki + hook), `/debug-deep` (5-phase RCA), or the audit backlog (log-only). **Silent-first**: the first 10 sessions log only — prompts activate from session 11 onward so the memory store has a useful baseline before it interrupts you. Counter lives in `~/.claude/memory/audit-backlog.md` as `<!-- session_count: N -->`.

Manual trigger: `/self-audit` skill (same flow, invoked on demand).

Requires the `kei-memory` primitive. Included in the `dev` and `full` profiles; otherwise add via `./install.sh --add=kei-memory`.

## Cloud REM sync (sleep layer, v0.11.0)

Run a nightly "sleep" cycle on Anthropic's cloud — no laptop, no infra, no DevOps.

**How it works:**
- Each session: your Mac pushes trace JSONL to a private git repo you control
- 03:00 local time: a remote Claude Code agent clones the repo, analyzes the last 24h of traces, writes `reports/sleep-YYYY-MM-DD.md`, and commits back
- Next morning: `git pull` and read the consolidated findings

**Setup (one-time, ~5 min):**

1. Create an empty private repo on GitHub / GitLab / Bitbucket / self-hosted Forgejo
2. In Claude Code run `/sleep-setup`
3. The wizard generates an SSH deploy key → you paste it into the repo's deploy-key settings with WRITE access
4. The wizard emits a ready-to-paste `/schedule create` command, converted to your local 03:00 in UTC

After that, the sleep cycle runs every night automatically. The morning report is yours to read — nothing is auto-injected back into any session.

**Requires** the `kei-memory` primitive (shipped in the `dev` and `full` profiles; add via `./install.sh --add=kei-memory` otherwise). Sleep-sync scripts themselves are installed unconditionally and stay dormant until you opt in via `/sleep-setup`.

Opt in at install time with `./install.sh --with-sleep-sync` (TTY-only). Governed by RULE 0.15 in `~/.claude/rules/sleep-layer.md`.

### Sleep on it (incubation, v0.12.0)

Defer a hard question or research task to the nightly remote agent: run `/sleep-on-it`, fill in one free-text field plus three clicks (type / priority / format), submit. The task lands in `sync-repo/sleep-queue/` and the nightly agent processes it before REM consolidation.

Priority maps to a wall-clock budget. Pick the one that matches the task's difficulty:

| Priority | Budget | When to pick |
|---|---|---|
| Quick | 15 min, this night | Simple questions, fast lookups |
| Standard | 60 min, this night | Default, medium research |
| Deep | 4 hours, this night | Serious derivations, thorough prior-art |
| Marathon | Full night (up to 8 h), **1 task only** | Hard equations, full autonomy; Phase B REM skipped that night |
| Weekly batch | 60 min, next Sunday UTC | Non-urgent research |

Checkpointing: Standard / Deep / Marathon runs commit a `.partial.md` every 20–30 minutes, so if the cloud session is cut short you still get the partial on morning pull.

Typical use:
- "Should I use CfC for memory re-ranker?" → deep-research → architectural recommendation by morning
- "Compare SvelteKit vs Astro vs Next.js App Router for the kit's landing" → comparative study
- "Derive closed form for the CfC attractor on Stiefel V(p,k=2)" → marathon mode, full night of autonomous derivation
- "What patterns in audit-backlog have highest impact?" → pattern analysis

Results in `sync-repo/sleep-results/<uuid>.md`, linked from the next morning's REM report. Biological analog: the REM-sleep "sleep on it" effect (Wagner et al. 2004, *Nature*). Queue mutations go through the `kei-sleep-queue` helper.

### Deep-sleep NREM consolidation (v0.13.0)

A third nightly phase — **Phase C** — runs after REM on a user-chosen cadence (default: every 7 days). Biological analog: NREM slow-wave-sleep system consolidation. The remote agent scans your memory-repo for conflicts across rules, hooks, `_blocks/`, and memory (contradictory directives, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations) and produces a structured refactor plan.

Two output modes, chosen once in `/sleep-setup` Phase 3b:

- **Plan only** (default) — markdown report in `sync-repo/sleep-deep/YYYY-MM-DD-plan.md`. Read in the morning, decide what to merge by hand.
- **Plan + fork** — same plan plus an auto-resolve review markdown (`YYYY-MM-DD-autoresolve.md`) listing the auto-resolvable conflicts with WHY / EXAMPLE / TRADEOFF per item. You open each file in an editor, apply the suggested change, commit on a `deep-sleep/YYYY-MM-DD` branch, then let the graph-check gate verify the wikilinks still resolve.

> v0.14.1 retraction: earlier README claimed a `git apply`-ready patch. The engine cannot synthesise real unified-diff hunks without reading the source files — that would risk fabricated edits (RULE 0.4). The autoresolve file is now plain markdown reviewed and applied by hand; the "fork" path only automates the rename/move class of ops, not content edits.

**Zero-conflict guarantee:** any conflict the engine marks `requires_human_decision` is EXCLUDED from the auto-resolve markdown and listed plainly in the plan. No silent auto-apply of ambiguous changes.

**Store backends** (picked in Phase 3b, consumed via the new `kei-store` trait):

| Backend | Status | Notes |
|---|---|---|
| GitHub private | production | SSH deploy key or PAT; default |
| Forgejo self-hosted | production | Same wire protocol as GitHub |
| Gitea self-hosted | production | Same wire protocol |
| Filesystem only | production | Local `.git`; no push; fastest |
| S3 / R2 / MinIO | production (v0.21, behind `s3` feature) | Real GetObject / PutObject / ListObjectsV2 via `aws-sdk-s3`. Build with `cargo build -p kei-store --features s3` and set `[s3] bucket = "..."` in `store-config.toml`. AWS default credential chain (env vars → `~/.aws/credentials` → IMDS). Custom endpoint for R2 / MinIO / Wasabi via `KEI_STORE_S3_ENDPOINT` env or `s3.endpoint` TOML field. Binary grows ~5 MB when the feature is on. Omit the feature OR omit `s3.bucket` to fall back to the v0.14 local-manifest stub (still gated by `KEI_STORE_ALLOW_S3_STUB=1`). |

Requires the new `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, and `kei-store` primitives (shipped in the `dev` and `full` profiles). Governed by the Phase C extension of RULE 0.15 in `~/.claude/rules/sleep-layer.md`.

## Primitives (Rust)

`_primitives/_rust/` is a Cargo workspace with <!-- count:RUST_CRATES -->25<!-- /count:RUST_CRATES --> single-binary crates (v0.13.0 added 4 deep-sleep primitives; v0.14.0 added <!-- count:LBM_PORTS -->10<!-- /count:LBM_PORTS --> LBM-port MCP crates; v0.14.2 removed `genesis-scan` — internal-only tool, not shipped publicly). `install.sh` builds `--release` for the subset selected by the active profile and drops binaries at `~/.claude/agents/_primitives/_rust/target/release/<name>`.

| Crate | Purpose |
|---|---|
| `kei-ledger` | Agent-fork lifecycle SQLite (`fork` / `done` / `fail`); SSoT for RULE 0.12 |
| `kei-migrate` | Universal DB migration runner — Postgres / SQLite / MySQL autodetect from `DATABASE_URL` |
| `kei-changelog` | Git-cliff-style `CHANGELOG.md` generator from Conventional Commits |
| `ssh-check` | `sshd_config` linter — flags weak ciphers, PermitRootLogin yes, password auth, etc. |
| `firewall-diff` | `ufw` intended-vs-running diff — catches drift between declared policy and live kernel rules |
| `mock-render` | Playwright wrapper — takes screenshots with SHA-locked PNGs (WYSIWYD: What You See Is What You Deploy) |
| `visual-diff` | Pixel diff with tolerance — used in `/site-create` screenshot-regression loop |
| `tokens-sync` | Design tokens JSON → Tailwind config extend + CSS variables under `:root` |
| `kei-memory` | Session retrospective + recurring pattern detector; offline-first analyzer powering RULE 0.14 self-audit |
| `kei-conflict-scan` | v0.13.0 — deep-sleep conflict scanner across rules/hooks/blocks/orphans/CP violations |
| `kei-refactor-engine` | v0.13.0 — consumes `kei-conflict-scan` JSON; emits plan markdown + auto-resolve review markdown (NOT a unified diff; v0.14.1 retraction) |
| `kei-graph-check` | v0.13.0 — post-refactor wikilink + handoff + block-ref resolver gate |
| `kei-store` | v0.21.0 — memory-repo backend abstraction (GitHub / Forgejo / Gitea / Filesystem / S3). S3 backend is a real `aws-sdk-s3` client when built with `--features s3` (supports AWS / R2 / MinIO / Wasabi); otherwise falls back to the v0.14 local-manifest stub. |
| `keisei` | v0.19.0 — exobrain multi-client CLI — `attach` / `mount` / `detach` / `status` / `list-adapters`. Mounts a portable brain into every detected AI client in one shot. Supported clients: Claude Code, Cursor, Continue, Zed. `mount` fan-outs to all detected adapters; `detach` round-trips cleanly and preserves the user's other MCP/context-server entries. Marker SSoT is `~/.claude/keisei-attached.toml` (schema v2 — list of attachments; v1 auto-migrated). |

## Primitives (shell)

`_primitives/*.sh` is the shell-primitive layer. Installed at `~/.claude/agents/_primitives/` by `install.sh` with `chmod +x`.

| Primitive | Purpose |
|---|---|
| `tomd` | Universal non-native-format → markdown (PDF, DOCX, XLSX, PPTX, CSV, images with OCR, code) |
| `design-scrape` | Scrape a live URL's DOM + computed styles + asset manifest into a structured JSON blob |
| `live-preview` | `start` / `stop` / `status` dev server wrapper — writes `.keisei/dev-server.pid` for hook discovery |
| `figma-tokens` | Figma API → design tokens JSON (consumed by `tokens-sync`) |
| `frontend-inspect` | Pointer a running dev server, dump DOM tree + accessibility tree + CSS cascade for a given selector |
| `screenshot-decode` | OCR + layout extraction from a screenshot (used when design source is a PNG, not code) |
| `metrics-scrape` | Pull Prometheus / OpenMetrics endpoints, normalize, diff against baseline |
| `log-ship` | Tail structured logs, forward to Loki / CloudWatch / journald with rate limits |
| `provision-hetzner` | Hetzner Cloud API provisioner — server create + cloud-init + ready-wait |
| `provision-vultr` | Vultr API provisioner — same shape as Hetzner |
| `harden-base` | Post-provision baseline hardening — fail2ban, ufw, unattended-upgrades, no-root-ssh |
| `kei-ci-lint` | Pre-commit / pre-push CI lint — runs the minimum-viable checks locally before push |
| `kei-docs-scaffold` | One-shot doc site skeleton emitter (mdbook / docusaurus / astro-starlight) |

## Architecture

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

<!-- count:HOOKS -->10<!-- /count:HOOKS --> hooks enforce the pipeline (6 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.

## Regenerating counts

Every number above (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.

## 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 <!-- count:BRIDGES -->11<!-- /count:BRIDGES --> 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 <!-- count:BRIDGES -->11<!-- /count:BRIDGES --> 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 <!-- count:BRIDGES -->11<!-- /count:BRIDGES -->, 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.

## License

MIT. See `LICENSE` in this directory.