KeiSeiKit-1.0/README.md

# KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code

## From the author

Hello.

Transformers are statistically wired to lie. It is not a bug, it is the core operation: they pick the next token by sampling a probability distribution conditioned on whatever context happens to fit the window. They cannot reliably hold long context, they will drag a hallucination picked up three thousand tokens ago into a confident final sentence, and they may deliver a brilliant insight right next to a fabricated citation. This is not fixable inside the model — it is mathematically baked in from the moment of tokenization onward.

This kit is my humble attempt to build scaffolding *around* those errors. Not to fix the transformer, but to make it behave a little closer to my own working logic: catch the common failure modes before they reach a commit, give it external memory that survives session boundaries, give it a rhythm resembling human work (day sessions → overnight consolidation → morning report), and let parallel agents coordinate through a shared state instead of stepping on each other.

I work across 4 to 8 parallel Claude terminals most days. The problems I hit are mundane: forgetting between sessions, repeating the same mistake on the third try, parallel agents clobbering each other's files, a hallucinated API name shipped to production. None of these are solvable by a better prompt. They are solvable by structure around the prompt.

Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, constructor-pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and sleep-sync (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly REM-style consolidation).

**Why Rust, not Python.** Transformers write Python confidently and wrongly. Five minutes to a plausible-looking function, two hours to debug why `dict.get("key", None) or []` silently swallowed an empty list, or why an async context manager leaked a file handle across a retry loop. Rust's type system catches whole categories of those errors at compile-time — the model literally cannot ship a `None`-vs-`[]` confusion, a missing `.await`, or an unhandled `Result`, because the compiler refuses. For an LLM-written codebase this is not aesthetic preference, it is survival. Every Rust primitive here is one category of hallucination the transformer is no longer allowed to commit.

It is not a product. It helps me personally. If it resonates with you, let me know. If enough feedback comes in, there will be a next version — more primitives, more patterns against the "forgetful" transformer. But that needs input; without it, I just keep using this quietly myself.

Forks and PRs welcome from everyone, not only from those who write code. If you hit a problem with Claude Code and have an idea for solving it, open an issue with the description. A well-formulated problem is already half the solution.

Hope it is a small Kei for someone to make vibecoding better.

And double sorry if I'm repeating someone — I never tried other kits, since this one is just all my rules stacked in one place. I can't always tell what I have seen somewhere and what came from my own head — so treat this as just my sample, not a claim of originality.

Thanks.

---

## 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-linux-x64
    └── ...                # per-platform binaries
```

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.20 — S3 backend currently MVP stub). 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 | stub — local only until v0.15 | Manifest-based local cache ONLY; no upload to S3/R2/MinIO yet. Requires `KEI_STORE_ALLOW_S3_STUB=1` (explicit opt-in so you don't accidentally believe your data is in the cloud). `aws-sdk-s3` integration planned for v0.15. |

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.13.0 — memory-repo backend abstraction (GitHub / Forgejo / Gitea / Filesystem / S3) |
| `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.

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