b55c3d6ef3
Adds 6 missing pieces flagged by readme review:
1. ## About — author attribution + "not a product" positioning + "Why
Rust, not Python" (was removed in 1f3aaca, but load-bearing context
for new users). Keeps the product-oriented greeting intact above it.
2. ## Install — plugin vs classic two-path table up front; links to
PLUGIN.md (v0.16+ Anthropic plugin format was previously un-linked).
3. ## The nightly cycle at a glance — unified ASCII overview of the
three-phase sleep cycle (A incubation → B REM → C NREM), biological
analog, phase-interaction rules (marathon owns night, Phase C cadence,
morning report is human-only).
4. ### Deep-sleep NREM consolidation — 4-primitive pipeline diagram
(conflict-scan → refactor-engine → graph-check via kei-store) plus a
concrete example of a detected conflict.
5. ## Security model — 7 bullets covering memory-repo privacy, RULE 0.1,
secrets-guard, GitHub Actions SHA pinning, S3 SSRF guard, marker
0o600, exFAT/FAT32 warning. Plus battle-matrix mention.
6. ## Docs — link index to CHANGELOG / PLUGIN / USB-BRAIN guide / battle
tests (none of those four files were referenced from README before).
README.md: +83 lines (1221 → 1304).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1304 lines
87 KiB
Markdown
1304 lines
87 KiB
Markdown
# 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.
|
||
|
||
## About
|
||
|
||
Built by Denis Parfionovich (<parfionovich@keilab.io>) as a personal working environment — not a commercial product. The problems it solves are ones I hit every day across 4–8 parallel Claude Code terminals: 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.
|
||
|
||
**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.
|
||
|
||
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 the three-phase sleep layer (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly incubation + REM + NREM consolidation).
|
||
|
||
Treat this as **my sample, not a claim of originality.** I work from my own rules stacked in one place and cannot always tell what came from somewhere I have read and what came from my own head. 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 at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
Two install paths — pick whichever fits your Claude Code version:
|
||
|
||
| Path | Command | Best for |
|
||
|---|---|---|
|
||
| **Plugin** (v0.16+, recommended on Claude Code 2.1+) | `/plugin marketplace add KeiSei84/KeiSeiKit` then `/plugin install keisei@keisei-marketplace` | Agents + skills + hooks + MCP. Zero cargo build. See [PLUGIN.md](./PLUGIN.md). |
|
||
| **Classic** `./install.sh` | Below | Full kit incl. 25 Rust primitives + 13 shell primitives. Required for the `ops` / `dev` / `full` profiles. |
|
||
|
||
```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.
|
||
|
||
## Reference
|
||
|
||
Every shipped component, its real behaviour, and where to look in source. Each subsection documents the actual CLI surface as extracted from `_primitives/_rust/*/src/main.rs`, `_primitives/*.sh`, `hooks/*.sh`, and `skills/*/SKILL.md`. If a flag or subcommand is not listed here, it does not exist in the current build.
|
||
|
||
### Rust primitives
|
||
|
||
All 25 crates live under `_primitives/_rust/<name>/`. After `install.sh` runs, binaries land at `~/.claude/agents/_primitives/_rust/target/release/<name>`. Exit codes: `0` success, `1` usage/IO error, `2` validation/diff-found (per-tool; see each entry).
|
||
|
||
#### `kei-ledger` — agent-fork lifecycle ledger (RULE 0.12)
|
||
|
||
SQLite-backed append-only log of every non-trivial agent invocation. One row per fork; the orchestrator uses `validate` to check that the 6 required artefacts exist on the child branch before merging.
|
||
|
||
```
|
||
kei-ledger [--db <path>] <subcommand>
|
||
init — create ledger file + schema
|
||
fork <id> <branch> --spec-sha <sha> — log a new running agent
|
||
[--parent <id>] [--worktree <path>]
|
||
done <id> --summary <s> — mark running agent done
|
||
fail <id> --reason <r> — mark running agent failed
|
||
merged <id> — mark done/failed agent merged into parent
|
||
list [--status running|done|failed|merged] — dump history
|
||
tree <id> — parent → children tree from root id
|
||
validate <branch> [--repo-root <path>] — check 6-artefact bundle exists
|
||
(spec.md / plan.md / progress.json /
|
||
chatlog.md / handoffs.md / review.md)
|
||
```
|
||
|
||
State: `$KEI_LEDGER_DB` or `~/.claude/agents/ledger.sqlite`. `validate` exits 2 if artefacts missing.
|
||
|
||
#### `kei-migrate` — universal SQL migration runner
|
||
|
||
Postgres / SQLite / MySQL via a single `DATABASE_URL`. Up/down/status/create.
|
||
|
||
```
|
||
kei-migrate --database-url <url> [--dir <path=migrations>] <subcommand>
|
||
up — apply all pending migrations
|
||
down [n=1] — revert the last N migrations (needs <ts>_<name>.down.sql)
|
||
status — list applied vs pending
|
||
create <name> — scaffold <ts>_<name>.sql (+ .down.sql)
|
||
```
|
||
|
||
URL formats accepted: `postgres://...`, `sqlite:///abs/path.db` or `sqlite::memory:`, `mysql://...`. Reads `DATABASE_URL` env var as fallback.
|
||
|
||
#### `kei-changelog` — Conventional Commits → Markdown
|
||
|
||
Git-cliff-shaped generator. Walks a commit range, groups by conventional-commit type, prepends to `CHANGELOG.md` or emits to stdout.
|
||
|
||
```
|
||
kei-changelog [--from <ref>] [--to <ref=HEAD>] [--unreleased]
|
||
[--version <label=v0.1.0>] [--repo <path=.>]
|
||
[--update <file>]
|
||
```
|
||
|
||
`--update` prepends under `# CHANGELOG` header (idempotent — won't duplicate an existing identical block). Without `--update`, prints to stdout.
|
||
|
||
#### `ssh-check` — sshd_config linter
|
||
|
||
Reads `/etc/ssh/sshd_config` + every `sshd_config.d/*.conf`, merges via last-wins, scores against the KeiSeiKit hardened-baseline rule matrix.
|
||
|
||
```
|
||
ssh-check [--config <path=/etc/ssh/sshd_config>]
|
||
[--drop-in <dir=/etc/ssh/sshd_config.d>]
|
||
[--allow-user <name>]... [--json]
|
||
```
|
||
|
||
Repeatable `--allow-user` for extra accepted `AllowUsers` entries (default: `keiadmin`). Exits 2 if violations found.
|
||
|
||
#### `firewall-diff` — ufw intent-vs-live diff
|
||
|
||
Defensive-only — does NOT execute `ufw` itself. Takes an intent YAML + a captured `ufw status numbered` output (file or stdin) and reports drift.
|
||
|
||
```
|
||
firewall-diff --intent <yaml> (--status-file <path> | --stdin) [--json]
|
||
```
|
||
|
||
Exit 2 on any diff. Use via `ufw status numbered | firewall-diff --intent fw.yaml --stdin`.
|
||
|
||
#### `mock-render` — WYSIWYD screenshot-and-lock
|
||
|
||
Playwright-backed. Enforces the "What You See Is What's Deployed" invariant: every site section's source file is hashed, the hash is locked against a screenshot, and `verify` fails if the source drifts after lock.
|
||
|
||
```
|
||
mock-render screenshot <url> --out <png> [--viewport WxH]
|
||
mock-render lock --project <dir> --section <src> [--screenshot <png>]
|
||
mock-render verify --project <dir> --section <src>
|
||
mock-render status --project <dir>
|
||
```
|
||
|
||
Exit 2 on invariant violation (source hash changed since lock).
|
||
|
||
#### `visual-diff` — pixel PNG comparator
|
||
|
||
Used by `site-wysiwyd-check` hook to detect visual drift. Produces a red-overlay diff PNG when images differ beyond threshold.
|
||
|
||
```
|
||
visual-diff <a.png> <b.png> [--out <file=diff.png>] [--threshold <pct=1.0>]
|
||
```
|
||
|
||
Exit 2 if mismatch exceeds threshold. Prints percentage + diff-px count.
|
||
|
||
#### `tokens-sync` — design tokens → Tailwind + CSS vars
|
||
|
||
Single JSON file → Tailwind `theme.extend` config and CSS `:root` custom properties. Either or both output targets; at least one required.
|
||
|
||
```
|
||
tokens-sync <tokens.json> [--out-tailwind <path>] [--out-css <path>]
|
||
```
|
||
|
||
JSON minimum shape: `{ colors, fonts, spacing, radius }`.
|
||
|
||
#### `kei-memory` — session retrospective + pattern detector (RULE 0.14)
|
||
|
||
Offline TF-IDF / recurrence analyzer powering `/self-audit`. Ingests JSONL transcripts, surfaces cross-session patterns.
|
||
|
||
```
|
||
kei-memory [--db <path>] <subcommand>
|
||
ingest --session-id <id> --transcript <path.jsonl> [--prompt <text>]
|
||
analyze [--session <id>] [--last <n=1>] [--summary]
|
||
patterns [--cross-session] [--session <id>]
|
||
similar <prompt> [--limit <k=5>] — top-k past sessions by TF-IDF cosine
|
||
dump <session-id> — emit session events as markdown
|
||
stats — N sessions / N events / top tools
|
||
backlog [--add <s>] [--list] [--clear] — silent-first audit backlog
|
||
```
|
||
|
||
State: `$KEI_MEMORY_DB` or `~/.claude/memory/kei-memory.sqlite`.
|
||
|
||
#### `kei-conflict-scan` — deep-sleep conflict scanner (v0.13.0)
|
||
|
||
Scans a memory-repo clone for rule conflicts, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations.
|
||
|
||
```
|
||
kei-conflict-scan --path <root>
|
||
[--format json|human] [--only rules|hooks|blocks|orphans|cp]
|
||
[--exit-on-hit]
|
||
```
|
||
|
||
Emits JSON (default) or human table. Exit 2 only when `--exit-on-hit` AND hits found.
|
||
|
||
#### `kei-refactor-engine` — refactor-plan generator (v0.13.0)
|
||
|
||
Consumes `kei-conflict-scan` JSON, emits plan markdown + an auto-resolve review file (NOT a unified diff — v0.14.1 retraction).
|
||
|
||
```
|
||
kei-refactor-engine [--input <conflicts.json>|-] [--plan-only]
|
||
[--apply-to-branch <branch>]
|
||
[--plan-out <path>] [--patch-out <path>]
|
||
```
|
||
|
||
`--patch-out` writes a markdown review (kept name for backward-compat). `requires_human_decision` items excluded from auto-resolve, listed in plain plan.
|
||
|
||
#### `kei-graph-check` — post-refactor graph-integrity gate (v0.13.0)
|
||
|
||
Resolves wikilinks + handoff refs + block refs across a memory-repo clone. Used as a gate BEFORE orchestrator commits the deep-sleep fork branch.
|
||
|
||
```
|
||
kei-graph-check --path <root> [--after-diff <patch>] [--json]
|
||
```
|
||
|
||
`--after-diff` treats any `+++ /dev/null` removal or `# removed: <p>` header as a phantom-removed file. Exit 2 on any broken reference.
|
||
|
||
#### `kei-store` — memory-repo backend abstraction (v0.21)
|
||
|
||
Unifies GitHub / Forgejo / Gitea / Filesystem / S3 behind one `MemoryStore` trait. Real `aws-sdk-s3` when built with `--features s3`; otherwise falls back to a local-manifest stub (still behind `KEI_STORE_ALLOW_S3_STUB=1`).
|
||
|
||
```
|
||
kei-store [--config <path>] <subcommand>
|
||
init <backend> [--url <url>] — write store-config.toml scaffold
|
||
read <path> — fetch blob to stdout
|
||
write <path> <file> — upload local file
|
||
list <dir> — list names under dir
|
||
branch <name> — set active branch/prefix
|
||
commit --message <msg> — commit staged writes
|
||
push <branch> — push branch to remote
|
||
pull <branch> — pull branch from remote
|
||
status — print backend name
|
||
```
|
||
|
||
Config: `~/.claude/agents/_primitives/store-config.toml` (override with `--config`). S3 endpoint override: `KEI_STORE_S3_ENDPOINT` env or `s3.endpoint` TOML field. AWS default credential chain applies.
|
||
|
||
#### `kei-artifact` — typed artifact handoff store (v0.16)
|
||
|
||
JSON-Schema-validated blob store for inter-agent handoffs. Five built-in schemas: `spec`, `plan`, `patch`, `review`, `research`. Custom schemas registered at runtime auto-sync to the assembler via `schemas.json` export.
|
||
|
||
```
|
||
kei-artifact [--db <path>] <subcommand>
|
||
init — register 5 built-in schemas
|
||
register-schema --name <n> --path <schema.json>
|
||
list-schemas
|
||
export-schemas [--path <out>] — refresh assembler's schemas.json
|
||
emit --schema <n> --from <agent> --content <json> — write an artifact
|
||
[--meta key=val]... [--parent <id>]
|
||
get <id> [--format typed|raw]
|
||
list [--schema <n>] [--from <agent>] [--since <N>s]
|
||
validate <id> — re-validate against schema
|
||
chain <id> — walk parent-handoff chain
|
||
```
|
||
|
||
State: `$KEI_ARTIFACT_DB` or `~/.claude/artifacts/artifacts.sqlite`.
|
||
|
||
#### `kei-auth` — HMAC-signed token issuer (v0.14.1 security fix)
|
||
|
||
Issue / verify / revoke. Signing secret sourced from `KEI_AUTH_KEY` env var ONLY — the old `--key` CLI flag was removed in v0.14.1 because it leaked the secret through `/proc/<pid>/cmdline` and shell history.
|
||
|
||
```
|
||
kei-auth [--db <path>] <subcommand>
|
||
issue --user <u> --project <p> [--scope read|write|admin=read] [--ttl <sec=86400>]
|
||
verify <token>
|
||
revoke <token>
|
||
```
|
||
|
||
Key source (per RULE 0.8): `export KEI_AUTH_KEY="$(openssl rand -hex 32)"` or sourced from `~/.claude/secrets/.env`. State: `$KEI_AUTH_DB` or `~/.claude/auth/auth.sqlite`.
|
||
|
||
#### `kei-router` — natural-language → tool-call JSON
|
||
|
||
Rule-based NL router. Parses a short query into a structured tool-call JSON object. Used by the compose-solution skill as a first-pass dispatcher.
|
||
|
||
```
|
||
kei-router <query> [--forward]
|
||
```
|
||
|
||
`--forward` adds `_forward=true` hinting remote-MCP forwarding on fallback. Prints pretty JSON to stdout.
|
||
|
||
#### `kei-sage` — Obsidian-style knowledge vault
|
||
|
||
SQLite-backed FTS5 knowledge store with BFS-related and PageRank. Can import an Obsidian vault wholesale.
|
||
|
||
```
|
||
kei-sage [--db <path>] <subcommand>
|
||
import <vault> — import .md files with frontmatter
|
||
search <query> [--limit <n=20>] — FTS5 over title+content
|
||
related <key> [--depth <d=2>] — BFS from a vault path/key
|
||
rank [--limit <n=20>] — PageRank over wikilinks
|
||
add --title <t> [--content <c>] [--vault-path <p>] [--grade <g=E4>]
|
||
edit <id> [--title <t>] [--content <c>] [--grade <g>]
|
||
link <src> <dst> [--edge-type <t=related>]
|
||
```
|
||
|
||
State: `$KEI_VAULT_DB` or `~/.claude/sage/vault.sqlite`.
|
||
|
||
#### `kei-task` — task DAG CLI
|
||
|
||
SQLite task graph with dependencies, milestones, FTS search. Dep types arbitrary (`blocks`, `relates`, ...).
|
||
|
||
```
|
||
kei-task [--db <path>] <subcommand>
|
||
create <title> [--description <d>] [--priority low|medium|high=medium]
|
||
update <id> [--status <s>] [--title <t>]
|
||
add-dependency <from> <to> [--dep-type <t=blocks>]
|
||
graph — list all edges
|
||
dependency-chain <id> — topologically walk deps
|
||
search <query> [--limit <n=20>]
|
||
milestone <name> [--description <d>]
|
||
link-milestone <task-id> <milestone-id>
|
||
```
|
||
|
||
State: `$KEI_TASK_DB` or `~/.claude/task/task.sqlite`.
|
||
|
||
#### `kei-chat-store` — chat session archive
|
||
|
||
Session + message CRUD with token/cost accounting, FTS search, archive flag.
|
||
|
||
```
|
||
kei-chat-store [--db <path>] <subcommand>
|
||
start --project <p> [--title <t>] [--model <m>]
|
||
save --session-id <id> --role <user|assistant|system> <content>
|
||
[--tokens-in <n>] [--tokens-out <n>] [--cost <f>]
|
||
search <query> [--limit <n=20>]
|
||
archive <session-id>
|
||
stats — JSON summary
|
||
```
|
||
|
||
State: `$KEI_CHAT_DB` or `~/.claude/chat/chat.sqlite`.
|
||
|
||
#### `kei-crossdomain` — cross-domain link graph
|
||
|
||
Generic typed-edge graph for linking any URIs. Used to wire rules ↔ memory ↔ artefacts ↔ chats.
|
||
|
||
```
|
||
kei-crossdomain [--db <path>] <subcommand>
|
||
link <from> <to> [--edge-type <t=related>] [--weight <w=1.0>] [--evidence <g=E4>]
|
||
unlink <from> <to> [--edge-type <t=related>]
|
||
query <node> — all edges touching node
|
||
graph <start> [--depth <d=2>] — BFS
|
||
auto-link <node> — propose + add edges via heuristic
|
||
stats — count per edge type
|
||
```
|
||
|
||
State: `$KEI_CROSS_DB` or `~/.claude/cross/cross.sqlite`.
|
||
|
||
#### `kei-search-core` — research pipeline scaffold
|
||
|
||
Budget-bounded research runner. Current build ships a `StubFetcher` (real web fetch pluggable); runs the research-pipeline cubes end-to-end and persists results for markdown/JSON export.
|
||
|
||
```
|
||
kei-search-core [--db <path>] <subcommand>
|
||
run <prompt> [--budget <microusd=1_000_000>] — default budget = 1 USD
|
||
stop <id>
|
||
export <id> [--format md|json=md]
|
||
```
|
||
|
||
State: `$KEI_SEARCH_DB` or `~/.claude/search/research.sqlite`.
|
||
|
||
#### `kei-content-store` — creative asset + prompt registry
|
||
|
||
Register generated assets, prompts, campaigns; track prompt version history.
|
||
|
||
```
|
||
kei-content-store [--db <path>] <subcommand>
|
||
register-asset <title> [--file-path <p>] [--media-type <m>] [--provider <n>]
|
||
register-prompt <prompt-text> [--model <m>] [--prompt-type <t>]
|
||
create-campaign <name> [--description <d>]
|
||
attach-asset <campaign-id> <asset-id>
|
||
prompt-history <prompt-id>
|
||
```
|
||
|
||
State: `$KEI_CONTENT_DB` or `~/.claude/content/content.sqlite`.
|
||
|
||
#### `kei-social-store` — people + organisation CRM
|
||
|
||
Person/org registry with interaction log + relationship graph.
|
||
|
||
```
|
||
kei-social-store [--db <path>] <subcommand>
|
||
search-people <query> [--limit <n=20>]
|
||
add-person <name> [--email <e>] [--handle <h>] [--source <s=manual>]
|
||
add-org <name> [--org-type <t=company>]
|
||
log-interaction <person-id> <interaction-type> [--content <c>]
|
||
[--channel <ch=manual>] [--target-id <n>]
|
||
relationship-graph
|
||
```
|
||
|
||
State: `$KEI_SOCIAL_DB` or `~/.claude/social/social.sqlite`.
|
||
|
||
#### `kei-curator` — edge decay + orphan pruning
|
||
|
||
Operates on any of the `kei-sage` / `kei-crossdomain` SQLite databases. Periodic cleanup: exponential decay on edge weights, prune orphans.
|
||
|
||
```
|
||
kei-curator --db <path> <subcommand>
|
||
decay [--default-lambda <λ=0.05>] [--threshold <θ=0.1>]
|
||
prune-orphans
|
||
```
|
||
|
||
Requires an explicit `--db <path>` — there is no default.
|
||
|
||
#### `keisei` — exobrain multi-client CLI (v0.19+)
|
||
|
||
Entry-point that mounts a portable brain directory into one or more AI clients. See the dedicated deep-dive section below.
|
||
|
||
### Shell primitives
|
||
|
||
All 13 live under `_primitives/*.sh`. Installed with `chmod +x` at `~/.claude/agents/_primitives/`. Shell primitives are POSIX sh where feasible; two (`provision-hetzner`, `provision-vultr`, `harden-base`) use bash explicitly.
|
||
|
||
#### `tomd.sh` — universal format → markdown
|
||
|
||
Converts PDF / DOCX / DOC / HTML / PPTX / XLSX / CSV / images / source code to markdown. Used by the `tomd-preread` hook to auto-convert binary formats before Claude reads them. Deps: `pandoc`, `python3`, `jq`. Optional: `pymupdf4llm` (better PDF), `openpyxl` (XLSX tables), `tesseract` (OCR).
|
||
|
||
#### `design-scrape.sh` — Playwright site scrape
|
||
|
||
Scrapes a live URL into tokens + section map + desktop/mobile screenshots.
|
||
|
||
```
|
||
design-scrape <url> [--out <dir>]
|
||
```
|
||
|
||
Output: `<out>/desktop.png`, `<out>/mobile.png`, `<out>/tokens.json`, `<out>/structure.json`. Requires `npx` + Playwright chromium.
|
||
|
||
#### `live-preview.sh` — dev-server wrapper
|
||
|
||
Detects framework from `package.json`, runs `npm run dev`, writes PID to `.keisei/dev-server.pid` for the `site-wysiwyd-check` hook to discover.
|
||
|
||
```
|
||
live-preview start <dir>
|
||
live-preview stop [pid] — default: reads .keisei/dev-server.pid
|
||
live-preview status
|
||
```
|
||
|
||
#### `figma-tokens.sh` — Figma → tokens.json
|
||
|
||
Fetches Figma Variables + Styles via REST API, emits a `tokens.json` consumable by `tokens-sync`.
|
||
|
||
```
|
||
FIGMA_TOKEN=figd_xxx figma-tokens <file-key> [--out <path=tokens.json>]
|
||
```
|
||
|
||
Token MUST come from env (RULE 0.8). File-key is the segment after `/design/` or `/file/` in the Figma URL.
|
||
|
||
#### `frontend-inspect.sh` — project fingerprint
|
||
|
||
Reports framework (Astro / Next / SvelteKit / Vite-React / static / unknown), styling (tailwind4 / tailwind3 / css-modules / plain), package manager, component count, whether tests exist.
|
||
|
||
```
|
||
frontend-inspect [<dir>] [--json]
|
||
```
|
||
|
||
#### `screenshot-decode.sh` — vision-API screenshot → structured description
|
||
|
||
Posts a PNG + prompt to the Anthropic Messages API (claude-sonnet-4) and prints the text response.
|
||
|
||
```
|
||
ANTHROPIC_API_KEY=sk-ant-xxx screenshot-decode <png> [--prompt <text>]
|
||
```
|
||
|
||
Default prompt asks for token + layout + sections as JSON. API key MUST come from env (RULE 0.8).
|
||
|
||
#### `metrics-scrape.sh` — Prometheus /metrics scraper
|
||
|
||
Scrape + format / filter / alert-check. POSIX sh.
|
||
|
||
```
|
||
metrics-scrape <url> # table (default)
|
||
metrics-scrape <url> --format json # needs jq
|
||
metrics-scrape <url> --format alert-check --filter <re> --threshold <n>
|
||
metrics-scrape <url> --filter '^http_requests_total'
|
||
```
|
||
|
||
`alert-check` format exits non-zero if any filtered metric exceeds threshold.
|
||
|
||
#### `log-ship.sh` — structured log tee + forward
|
||
|
||
Pipes JSON-line logs from stdin to stdout and optionally forwards to Loki / Datadog / generic HTTP. Local tee ALWAYS happens, even if forward fails — observability must degrade gracefully.
|
||
|
||
```
|
||
cat log.jsonl | log-ship --target stdout
|
||
journalctl -o json | log-ship --target loki --endpoint http://loki:3100/loki/api/v1/push --label job=api
|
||
tail -f app.log | log-ship --target datadog --endpoint <dd-url>
|
||
cat log.jsonl | log-ship --target http --endpoint <url>
|
||
cat log.jsonl | log-ship --target stdout --validate
|
||
```
|
||
|
||
Env (no CLI token leak): `LOG_SHIP_DD_API_KEY`, `LOG_SHIP_BEARER`.
|
||
|
||
#### `provision-hetzner.sh` — Hetzner Cloud provisioner
|
||
|
||
Idempotent wrapper over `hcloud` CLI. Re-running `create <name>` on an existing server prints its IP and exits 0.
|
||
|
||
```
|
||
provision-hetzner create <name> [--type cx22|cax11] [--location fsn1]
|
||
[--image debian-12] [--ssh-key <id>]
|
||
[--firewall <name>] [--user-data <file>]
|
||
provision-hetzner status <name>
|
||
provision-hetzner destroy <name> [--force]
|
||
provision-hetzner list
|
||
```
|
||
|
||
Env (RULE 0.8): `HCLOUD_TOKEN`.
|
||
|
||
#### `provision-vultr.sh` — Vultr provisioner
|
||
|
||
Same shape as Hetzner. Uses `vultr-cli` v3.
|
||
|
||
```
|
||
provision-vultr create <label> [--plan vc2-1c-1gb] [--region ams]
|
||
[--os-id 2136] [--ssh-key <id>]
|
||
[--firewall <group-id>] [--user-data <file>]
|
||
provision-vultr status <label>
|
||
provision-vultr destroy <label> [--force]
|
||
provision-vultr list
|
||
```
|
||
|
||
Env (RULE 0.8): `VULTR_API_KEY`. Idempotency key is the human `label` field.
|
||
|
||
#### `harden-base.sh` — post-provision baseline hardening
|
||
|
||
Runs ON the target VPS. Ports generic patterns from Vortex `setup.sh` (apt, ssh drop-in, ufw, fail2ban, auditd, unattended-upgrades). Never reboots — surfaces `needrestart` hints only.
|
||
|
||
```
|
||
sudo bash harden-base.sh [--admin-user <name=keiadmin>] [--ssh-port <n=22>]
|
||
[--allow-port <n/proto>]... [--no-caddy]
|
||
[--no-reboot] [--skip apt|ssh|ufw|fail2ban|auditd|unattended]
|
||
```
|
||
|
||
Every step is test → configure → reload — re-running is safe.
|
||
|
||
#### `kei-ci-lint.sh` — GitHub/Forgejo Actions linter
|
||
|
||
7 rule suite (R1-R7): required fields, least-privilege permissions, OIDC-vs-long-lived-token, cache-hit hygiene, SHA pinning, deprecated-action flags, pwn-request pattern.
|
||
|
||
```
|
||
kei-ci-lint <file.yml> [file2.yml ...]
|
||
kei-ci-lint --dir .github/workflows [--warn]
|
||
kei-ci-lint --dir .forgejo/workflows
|
||
```
|
||
|
||
Requires `yq` v4+ (mikefarah/yq Go impl — not the Python one).
|
||
|
||
#### `kei-docs-scaffold.sh` — auto-doc generator
|
||
|
||
Detects project type (Cargo.toml / package.json / pyproject.toml / pubspec.yaml / go.mod / Package.swift / docker-compose), emits CLAUDE.md / DECISIONS.md / runbook / README.
|
||
|
||
```
|
||
kei-docs-scaffold [--type=all|claude|decisions|runbook|readme]
|
||
[--force] [--dry-run] [DIR]
|
||
```
|
||
|
||
Default: `--type=all`. Idempotent without `--force`.
|
||
|
||
### Hooks
|
||
|
||
All 10 kit-shipped hooks live under `hooks/*.sh`, get copied to `~/.claude/hooks/` on install. Every hook respects `KEI_DISABLED_HOOKS` and `KEI_HOOK_PROFILE` (see Runtime hook controls below). Silent fall-through on missing `jq` — never aborts a tool call system-wide.
|
||
|
||
| Hook | Event | Severity | Bypass |
|
||
|---|---|---|---|
|
||
| `assemble-agents` | `PostToolUse:Edit\|Write` | advisory (rebuilds; never blocks) | — |
|
||
| `assemble-validate` | `PreToolUse:Bash` | **block** — exit 1 on `git commit` in `~/.claude` when manifests fail validation | — |
|
||
| `no-hand-edit-agents` | `PreToolUse:Edit\|Write` | **block** — exit 2 on generated `.md` edit attempts | `AGENT_MIGRATION=1` |
|
||
| `tomd-preread` | `PreToolUse:Read` | redirect — exit 2 with stderr pointing to cached `.md` | — |
|
||
| `agent-fork-logger` | `PreToolUse:Agent` | advisory (logs to `kei-ledger`; silent if absent) | — |
|
||
| `orchestrator-dirty-check` | `PreToolUse:Agent` | warn (stderr only) | `ORCHESTRATOR_META=1` or `ORCHESTRATOR_DIRTY_OK=1` |
|
||
| `site-wysiwyd-check` | `PostToolUse:Edit\|Write` | warn (stderr drift report) | — |
|
||
| `session-end-dump` | `Stop` | advisory (archives trace + calls `kei-memory ingest`) | — |
|
||
| `milestone-commit-hook` | `PostToolUse:Bash` | advisory (appends to audit-backlog on `feat:`/`refactor:`/merge) | — |
|
||
| `error-spike-detector` | `PostToolUse:*` | warn (stderr when ≥3 errors in 20-call window) | — |
|
||
|
||
Details beyond the table:
|
||
|
||
- **`assemble-agents`** — diff source: `_manifests/*.toml` rebuilds one agent; `_blocks/*.md` rebuilds ALL. Calls `_assembler/target/release/assemble --in-place`.
|
||
- **`assemble-validate`** — only fires when `git commit` runs inside `~/.claude`; validates every manifest; stderr-lists failures and exits 1 on any.
|
||
- **`no-hand-edit-agents`** — SSoT marker is `<!-- GENERATED by _assembler -->` on line 1. Files without the marker pass silently (legacy hand-authored agents). `AGENT_MIGRATION=1` overrides during migration only.
|
||
- **`tomd-preread`** — whitelist: `.docx`, `.doc`, `.xlsx`, `.pptx`, `.csv`. Cache key: basename + mtime + short path-hash (prevents collision between two same-basename files). Cache dir: `$KEISEI_TOMD_CACHE` or `/tmp/keisei-tomd-cache`.
|
||
- **`agent-fork-logger`** — extracts `subagent_type` + `prompt` + `isolation`; branch = `agent/<slug>-<ts>` when `isolation=worktree`, else `inline-<slug>-<ts>`. Spec-SHA = first 16 hex chars of SHA-256(prompt).
|
||
- **`orchestrator-dirty-check`** — runs `git status --porcelain` on repo root, stderr-warns with modified + untracked counts.
|
||
- **`site-wysiwyd-check`** — triggers on `.tsx` / `.vue` / `.svelte` / `.astro` / `.css` / `.html` / `.jsx` / `.ts`. Walks up to find `.keisei/dev-server.pid`; bails if no live server or no `.keisei/target.png`.
|
||
- **`session-end-dump`** — copies transcript JSONL to `~/.claude/memory/traces/<session_id>.jsonl`, calls `kei-memory ingest`, then best-effort calls `kei-sleep-sync.sh` (RULE 0.15, silent if sleep-sync not opted in).
|
||
- **`milestone-commit-hook`** — case-sensitive prefix match on `feat:`, `refactor:`, `merge` (avoids false-firing on `feature-docs.md`).
|
||
- **`error-spike-detector`** — rolling window in `~/.claude/memory/error-window.txt`; error-classifier = `is_error=true` OR message matches `/error:|failed|panic|denied/i`.
|
||
|
||
### Skills (grouped)
|
||
|
||
39 skills under `skills/<name>/SKILL.md`. Each is invoked as `/<skill-name>` inside Claude Code. Free-text is used only for intake fields; every other decision is a click via `AskUserQuestion`.
|
||
|
||
<details>
|
||
<summary><b>Meta / project setup (4)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/compose-solution` | Meta-orchestrator — converts a free-text task into the right artefact (agent / skill / hook / rule / block) by composing existing primitives. Enriches `_blocks/` over time. |
|
||
| `/new-project` | 4-phase bootstrap — intake, fork skeleton (branch + ledger row + sub-agent spawn), parallel execution with progress aggregation, per-branch merge ceremony. RULE 0.12 at project scale. |
|
||
| `/new-agent` | Interactive 6-question wizard that builds a project-specialist manifest and its `.md`. |
|
||
| `/onboard` | Scan a project (or scope) and propose agents + hooks + primitives based on detected stack. Three modes: Full auto, Step-by-step, Full manual. |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Design / frontend (18)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/site-create` | End-to-end site pipeline — intake → design → sections → WYSIWYD mock-render loop → audits → preview → deploy. The verify gate HARD-BLOCKS deploy of unlocked sections. |
|
||
| `/site-builder` | Build a site from block recipes. WYSIWYD invariant via `mock-render`. |
|
||
| `/site-teardown` | Deconstruct any live site into a reusable recipe — HTML, CSS, JS, tokens, animations. |
|
||
| `/landing-page` | Orchestrates design + copy + assets + animations + SEO for a landing page. Supports recipes (apple-product, saas, portfolio, ecommerce). |
|
||
| `/design-system` | Build a design system — tokens, base components, Tailwind config, dark mode, docs. |
|
||
| `/ui-component` | Build a UI component — API design, variants, a11y, animations, tests. |
|
||
| `/form-builder` | Multi-step forms — Zod validation, Turnstile anti-spam, serverless backends, upload, progressive enhancement. |
|
||
| `/scroll-animation` | Scroll-driven animation — GSAP ScrollTrigger, CSS scroll-timeline, parallax, pin/scrub. |
|
||
| `/motion-design` | Motion design — page transitions, element animations, View Transitions API, Rive/Lottie, a11y. |
|
||
| `/web-effects` | Visual web effects — WebGL shaders, particles, noise/grain, displacement maps, CSS-only. |
|
||
| `/web-assets` | Image / font / video optimization — AVIF, responsive srcset, font subsetting, Sharp.js. |
|
||
| `/figma-to-code` | Figma design → code — screenshot, context, tokens, responsive implementation. |
|
||
| `/frontend-design` | Anti-AI-slop aesthetic philosophy — typography pairing, color theory, spatial composition, motion guidelines, design archetypes. |
|
||
| `/responsive-audit` | 6-breakpoint audit — layout, touch targets, overflow, images. |
|
||
| `/a11y-audit` | WCAG 2.2 AA compliance — contrast, keyboard nav, screen reader, prefers-reduced-motion. |
|
||
| `/perf-audit` | Perf baseline → profile → top-3 bottlenecks → fix → remeasure. |
|
||
| `/seo-audit` | Technical + content SEO via WebFetch + code inspection. |
|
||
| `/web-deploy` | Cloudflare Pages / Vercel / edge functions / caching / Core Web Vitals / CI/CD / DNS. |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Infra / ops (4)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/vm-provision` | End-to-end VPS — provider → plan → provision → harden → `ssh-check` + `firewall-diff` hard-gate → handoff. Stops if either verification fails. |
|
||
| `/ci-scaffold` | Production CI/CD plan — platform (GitHub vs Forgejo), build matrix, OIDC-vs-token, release automation, security gate. Emits workflow YAML + runs `kei-ci-lint`. |
|
||
| `/observability-setup` | Logs + metrics + traces triad on an existing service — instrumentation → scrape+ship → dashboard → alerts. |
|
||
| `/auth-setup` | Production auth/IAM plan — user flows, IdPs, session strategy, authorization model, threat mitigations. Never writes secret values. |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>API / schema / docs / tests (5)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/api-design` | API design — style (REST / GraphQL / tRPC / gRPC), resource model, OpenAPI 3.1 or GraphQL SDL, versioning, rate-limit + auth handoff, codegen. |
|
||
| `/schema-design` | Relational schema → migrations → `kei-migrate` apply. PG / SQLite / MySQL autodetect. |
|
||
| `/docs-scaffold` | 5-phase — detect project type, audit existing docs, generate CLAUDE.md / DECISIONS.md / runbook / README / diagrams / CHANGELOG. |
|
||
| `/test-matrix` | Beyond-unit test stack — fuzzing, property-based, load, E2E, mutation. Composes right mix per language × critical path × CI target. |
|
||
| `/test-gen` | Generate tests for untested code — happy path, edge cases, error handling. |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Retro / audit / research (5)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/self-audit` | RULE 0.14 session retrospective triage — runs `kei-memory analyze + patterns`, routes findings to `/escalate-recurrence` / `/debug-deep` / audit-backlog. |
|
||
| `/pr-review` | PR review — Constructor Pattern awareness, security, SSoT check. |
|
||
| `/refactor` | Refactor with behavior preservation — checkpoint, extract, test, audit. |
|
||
| `/debug-deep` | 5-phase RCA using multi-agent analysis + error pattern matching. |
|
||
| `/research` | Deep research via parallel agents + web search + cross-referencing. |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Sleep layer + runtime (3)</b></summary>
|
||
|
||
| Skill | One-liner |
|
||
|---|---|
|
||
| `/sleep-setup` | RULE 0.15 one-time wizard — local-only / remote-only / hybrid, trigger time, memory-repo init, SSH deploy key, `/schedule create` + cron snippet. |
|
||
| `/sleep-on-it` | v0.12 incubation — defer a question to the nightly remote agent. Up to 5 tasks per night (15 min each). Priority maps to budget. |
|
||
| `/hooks-control` | v0.15.1 click-only runtime enable/disable — emits shell `export` / `unset` for user to paste. Does NOT execute anything itself. |
|
||
|
||
</details>
|
||
|
||
### `keisei` CLI — exobrain entry point
|
||
|
||
`keisei` is the only Rust primitive that mounts state into OTHER tools' configs. It reads a portable brain directory (see brain layout above) and writes `mcpServers.keisei` entries into each detected AI client's config file.
|
||
|
||
**Five subcommands** (every flag listed is the actual clap arg surface in `_primitives/_rust/keisei/src/main.rs`):
|
||
|
||
```
|
||
keisei attach <brain-path> [--scope user|project]
|
||
keisei mount <brain-path>
|
||
keisei detach
|
||
keisei status
|
||
keisei list-adapters
|
||
```
|
||
|
||
**Flag matrix:**
|
||
|
||
| Subcommand | Required args | Flags | Notes |
|
||
|---|---|---|---|
|
||
| `attach` | `<brain-path>` (dir with `manifest.toml`) | `--scope user\|project` (default `user`) | Attaches to the **first detected** client. Adapters that don't support requested scope error out cleanly. |
|
||
| `mount` | `<brain-path>` | — | Auto-attach to EVERY detected AI client. Always user-scope (host-wide fan-out by design). |
|
||
| `detach` | — | — | Removes `mcpServers.keisei` from every client in the marker; preserves the user's other MCP entries. Deletes marker. |
|
||
| `status` | — | — | Brain name + path + attach timestamp + per-client config path + health (brain root is a dir? `mcp_server` binary exists?). |
|
||
| `list-adapters` | — | — | Tabular view: `name / detected / config_path / scopes`. |
|
||
|
||
**Supported adapters (v0.21):** Claude Code, Cursor, Continue, Zed. Claude Code and Cursor advertise both `user` + `project` scope. Continue and Zed are user-only.
|
||
|
||
**Exit codes:**
|
||
- `0` — success
|
||
- `1` — error (brain validation fail, no adapter detected, NameConflict, scope unsupported, IO)
|
||
|
||
No separate exit code for "config invalid" — all errors funnel through exit 1 with the specific message printed to stderr. (The task brief mentioned exit 2 for config-invalid, but the current main.rs only returns `ExitCode::SUCCESS` or `ExitCode::from(1)`.)
|
||
|
||
**Env vars:**
|
||
|
||
| Var | Purpose |
|
||
|---|---|
|
||
| `KEISEI_HOME` | Test hook — overrides `$HOME` for marker-file resolution and adapter config-path lookup |
|
||
| `KEI_STORE_S3_ENDPOINT` | Custom S3-compatible endpoint (R2 / MinIO / Wasabi) — consumed by `kei-store` when built with `--features s3` |
|
||
| `KEI_STORE_ALLOW_S3_STUB` | Set to `1` to permit the local-manifest S3 stub when the real `s3` feature isn't built |
|
||
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` | Standard AWS credential chain — consumed via `aws-sdk-s3` default resolver |
|
||
| `KEI_AUTH_KEY` | HMAC secret for `kei-auth` (NOT a CLI flag since v0.14.1) |
|
||
|
||
**Marker SSoT:** `~/.keisei/attached.toml` (v0.21+). Schema v3 entries have a `scope` field. Legacy `~/.claude/keisei-attached.toml` auto-migrates on first read (one-shot: legacy deleted, new location written, stderr notice printed).
|
||
|
||
**Security hardening (v0.19):**
|
||
- Brain `mcp_server` path MUST be relative + inside the brain root (rejects `/usr/bin/curl`, `../../etc/shadow`, Windows-style `..\..\`)
|
||
- Brain `name` matches `^[a-z][a-z0-9_-]{0,63}$`
|
||
- Brain root rejected if it's a symlink (blocks USB → `$HOME` pivot)
|
||
- Adapters refuse to clobber existing `mcpServers.<name>` entries — explicit `NameConflict` error, no silent overwrite
|
||
- All config writes go through `fsx::write_atomic_json` (Windows-safe via `tempfile::NamedTempFile::persist`)
|
||
|
||
## 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`.
|
||
|
||
## The nightly cycle at a glance
|
||
|
||
The sleep layer is a **three-phase nightly cycle** on an Anthropic-cloud agent. The three phases run in order on the same scheduled trigger; each is covered in its own section below.
|
||
|
||
```
|
||
YOUR NIGHT
|
||
┌──────────────────────────────────────────────────────┐
|
||
Day →→→ │ Phase A Phase B Phase C │ →→→ Morning
|
||
│ INCUBATION REM NREM │
|
||
│ "sleep on it" consolidation deep-sleep │
|
||
│ v0.12.0 v0.11.0 v0.13.0 │
|
||
│ (queued tasks) (trace patterns) (conflict │
|
||
│ refactor) │
|
||
└──────────────────────────────────────────────────────┘
|
||
↓ ↓ ↓
|
||
sleep-results/ reports/sleep-*.md sleep-deep/*.md
|
||
<uuid>.md (always) (every N days)
|
||
```
|
||
|
||
**Biological analog.** Your Mac is the hippocampus (fast, stateful, volatile — captures raw episodes). The memory-repo is the transport layer. The cloud agent is the neocortex (slow, stateless, generalising). The morning `git pull` is the recall. Phase A mirrors the "sleep on it" effect (Wagner et al. 2004, *Nature*), Phase B mirrors REM dream-state pattern extraction, Phase C mirrors NREM slow-wave system consolidation.
|
||
|
||
**Phase interaction rules (important):**
|
||
|
||
- A `marathon` task in Phase A (8-hour budget, 1 task only) **owns the whole night** — Phases B and C are skipped for that night. Traces are append-only, so the next night's Phase B picks up the skipped backlog.
|
||
- Phase C only fires when today is a multiple of `DEEP_SLEEP_CRON_DAYS` (default 7) counted from your install date. Anchor lives in `sync-repo/reports/install-anchor.txt`.
|
||
- The morning report is for **HUMAN review**. It is NEVER auto-injected into a Claude Code session. Any rule or hook that emerges from it is installed via `/escalate-recurrence` — not by the cloud agent.
|
||
|
||
Governed end-to-end by RULE 0.15 in `~/.claude/rules/sleep-layer.md`.
|
||
|
||
## 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.
|
||
|
||
**4-primitive pipeline, in order:**
|
||
|
||
```
|
||
kei-conflict-scan → kei-refactor-engine → kei-graph-check (via kei-store transport)
|
||
(detect) (propose) (verify) (read/write memory-repo)
|
||
```
|
||
|
||
1. `kei-conflict-scan` reads `_rules/`, `hooks/hooks.json`, `_blocks/`, and `memory/` and emits a typed conflict list (name-collision, matcher-overlap, duplicate-block, orphan-wikilink, CP-violation).
|
||
2. `kei-refactor-engine` groups conflicts by safe-to-auto-resolve vs `requires_human_decision` and writes the plan + auto-resolve markdown.
|
||
3. `kei-graph-check` walks every wikilink / block-ref / handoff-ref in the proposed state; if anything fails to resolve, the fork branch is blocked and the plan is annotated.
|
||
4. `kei-store` is the transport — reads the pre-state from your GitHub / Forgejo / Gitea / FS / S3 backend and writes the two output files back atomically.
|
||
|
||
**Concrete example** (real category, paraphrased):
|
||
|
||
> Conflict detected: hook `no-github-push.sh` (PreToolUse:Bash, matcher `git push`) and rule file `patents.md` (§"Never reference unfiled applications") both govern the same risk surface — a github push containing unfiled-patent language. The hook blocks on URL; the rule blocks on content. Suggested refactor: keep both (they are complementary), but add a cross-ref from `patents.md` to the hook so a future reader sees the two-layer defence. Auto-resolvable (pure documentation edit, no behaviour change). Written to `YYYY-MM-DD-autoresolve.md` for human review.
|
||
|
||
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.
|
||
|
||
## Security model
|
||
|
||
What the kit touches, what it never touches, and the mitigations baked in:
|
||
|
||
- **Memory-repo must be private.** Sleep-sync pushes your session traces (prompts, tool calls, file paths, code snippets) to a git repo you control. `/sleep-setup` Phase 1 warns loudly on PUBLIC visibility. A public memory-repo leaks everything your agents have seen. If the session is marked `[PATENT-IP]` or runs in a banned-project CWD, `session-end-dump.sh` skips the push entirely — local trace is kept, never leaves the machine.
|
||
- **No GitHub push for kit-internal state.** RULE 0.1 forbids `git push` to github.com for any repo containing unfiled-patent IP. Kit ships `genesis-leak-guard.sh` as a pre-commit hook symlink template to keep patent-sensitive terms off any remote.
|
||
- **Secrets by reference only.** `secrets-guard` hook (Rust) blocks hardcoded tokens at `PreToolUse(Edit|Write)`. Every SSH key, API key, deploy token lives in `~/.claude/secrets/.env` (chmod 600, gitignored) or per-project `secrets/*.env`. Hook detects OpenAI/Anthropic/GitHub/Slack/AWS/Telegram token shapes plus PEM private keys (see RULE 0.8).
|
||
- **Supply-chain defences.** All GitHub Actions in `.github/workflows/` are pinned by full commit SHA (defends against CVE-2025-30066-class mutable-tag attacks). `scripts/validate-workflow-shas.sh` verifies every pin; `scripts/install-actionlint.sh` checks SHA-256 of the downloaded tarball before extraction. Dependabot raises weekly PRs for SHA updates.
|
||
- **S3 / R2 / MinIO hardening.** `kei-store::s3_cloud::validate_endpoint` rejects loopback, link-local, and cloud-metadata hosts (`127.0.0.0/8`, `169.254.0.0/16`, `metadata.google.internal`, …) by default to close the SSRF / IMDS-credential-leak surface. Plain HTTP requires opt-in. Non-AWS endpoints must set explicit `access_key_env` + `secret_key_env` — the AWS default credential chain is not consulted.
|
||
- **Brain attach-marker is owner-only.** `~/.keisei/attached.toml` is `chmod 0o600` on unix. Every manifest-sourced string printed by `keisei status` / `attach` / `mount` / `detach` is scrubbed through a control-byte sanitiser — closes the escape-sequence-injection surface from a malicious `brain.name`.
|
||
- **exFAT / FAT32 warning.** SQLite WAL shared-memory mmap is unreliable on those filesystems; `keisei mount` will corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Brain load prints an advisory. See `docs/USB-BRAIN-GUIDE*.md` for APFS / ext4 / NTFS-native walkthroughs.
|
||
|
||
Install-test battle matrix runs every profile against Ubuntu 24.04 + Alpine 3.19 + Debian 12 (`tests/battle/`) — "does it work on a fresh machine?" signal before each release.
|
||
|
||
## Docs
|
||
|
||
- [CHANGELOG.md](./CHANGELOG.md) — full release notes, generated from Conventional Commits by `kei-changelog`
|
||
- [PLUGIN.md](./PLUGIN.md) — Anthropic plugin-format install path (v0.16+) and differences from classic installer
|
||
- [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) — portable brain on removable media; platform splits for macOS / Linux / Windows
|
||
- [tests/battle/README.md](./tests/battle/README.md) — Docker install-test matrix
|
||
|
||
## License
|
||
|
||
MIT. See `LICENSE` in this directory.
|