docs(readme): outcome-oriented rewrite — hero + features + hide complexity under the hood
Refocuses README from defensive ("here's what LLMs do wrong, here's how we fence it")
to welcoming ("here's what you get, install is one line, complexity lives under the
hood"). Same factual content, same feature count, reorganized for new visitors.
Key changes:
- Hero opens with user outcome, not LLM failure modes
- Install moved to 2nd block (was buried mid-README)
- Features rewritten as scenarios ("Your AI sleeps at night") not specs
- "Batteries included" frames counts as confidence signal, not overwhelm
- "Under the hood (only if you care)" explicitly optional section for devs
- "About" confident — 4-8 parallel terminals flex, not self-deprecation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
annaglova
parent
b8b9c12913
commit
c859df8d37
1 changed files with 56 additions and 88 deletions
144
README.md
144
README.md
|
|
@ -1,111 +1,79 @@
|
|||
# KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code
|
||||
# KeiSeiKit
|
||||
|
||||
**A structural layer over Claude Code, Cursor, Continue, and Zed that catches the failure modes LLMs introduce at commit time — not after they ship.**
|
||||
**Your AI agents, structured. One manifest, eleven AI assistants. A brain that follows you across machines.**
|
||||
|
||||
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.
|
||||
Drop-in kit for Claude Code, Cursor, Continue, and Zed. Install once — get a 12-agent fleet that remembers yesterday's decisions, sleeps at night to consolidate what it learned, and lives on a USB stick you can carry between computers.
|
||||
|
||||
## 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 a three-phase overnight consolidation via a cloud cron. Constructor Pattern throughout — one file per concern, every abstraction replaceable.
|
||||
|
||||
**Rust-first by design.** 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 survival, not style. The full philosophical backstory lives in [docs/WHY.md](./docs/WHY.md).
|
||||
|
||||
## Three killer features
|
||||
|
||||
### 1. The nightly cycle
|
||||
|
||||
Day session → overnight consolidation → morning report. **Three phases on an Anthropic-cloud agent** mirror biological sleep:
|
||||
|
||||
- **Phase A — Incubation** ("sleep on it"): you defer a hard question via `/sleep-on-it`; the remote agent processes it during the night (15 min / 60 min / 4 h / full-night marathon).
|
||||
- **Phase B — REM**: the agent reads your day's trace JSONL, extracts cross-session patterns, commits `reports/sleep-YYYY-MM-DD.md` back to your private memory-repo.
|
||||
- **Phase C — NREM**: every 7 days (by default), scans `_rules/` + `hooks/` + `_blocks/` + `memory/` for conflicts (duplicate matchers, orphan wikilinks, CP violations) and emits a structured refactor plan.
|
||||
|
||||
Morning `git pull` — you read, you decide. Nothing is auto-injected into a future session. Full mechanics: [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md).
|
||||
|
||||
### 2. Constructor-Pattern agent kit
|
||||
|
||||
Agents are built deterministically from TOML manifests + reusable Markdown blocks. Edit a block, the `assemble-agents` hook rebuilds every affected agent. Ship the same `kei-critic` persona to every machine by installing the kit. 12 ready agents (`kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, ...) — all namespaced under `kei-*` so they won't collide with your own. Full wiring: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
|
||||
|
||||
### 3. Exobrain — one brain, every client
|
||||
|
||||
Portable **brain directory** (memory + artifacts + manifests + per-platform MCP server binaries) that mounts into Claude Code, Cursor, Continue, and Zed via a single command. USB stick, iCloud, S3 / R2 / MinIO — same state follows you.
|
||||
## Install in one line
|
||||
|
||||
```bash
|
||||
keisei mount /Volumes/MyBrain # attaches to every detected AI client
|
||||
keisei detach # clean unmount from all clients
|
||||
```
|
||||
|
||||
Setup path: [docs/INSTALL.md § keisei CLI](./docs/INSTALL.md#the-keisei-cli--multi-client-exobrain-mount-v019).
|
||||
|
||||
## What it solves (vs vanilla Claude Code)
|
||||
|
||||
| Problem you hit | 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.
|
||||
|
||||
## Quick install
|
||||
|
||||
Two paths, pick what fits your Claude Code version:
|
||||
|
||||
```bash
|
||||
# Plugin (recommended on Claude Code 2.1+, zero cargo build)
|
||||
/plugin marketplace add KeiSei84/KeiSeiKit
|
||||
/plugin install keisei@keisei-marketplace
|
||||
|
||||
# OR classic (required for Rust primitives)
|
||||
git clone <your-fork-of-this-repo> KeiSeiKit
|
||||
cd KeiSeiKit
|
||||
./install.sh # minimal profile, ~5s, no primitives
|
||||
./install.sh --profile=full # everything, ~5 min, ~200 MB
|
||||
```
|
||||
|
||||
Plugin vs classic install, profiles (`minimal` / `core` / `frontend` / `ops` / `dev` / `full`), MCP-server pre-built binaries, and runtime hook controls → [docs/INSTALL.md](./docs/INSTALL.md).
|
||||
That's it. 12 agents appear in Claude Code, 39 skills become callable as `/self-audit`, `/compose-solution`, `/schema-design`, and nightly consolidation is wired. [Other install paths →](./docs/INSTALL.md)
|
||||
|
||||
## What's in the box
|
||||
## What you actually get
|
||||
|
||||
| Category | Count |
|
||||
|---|---:|
|
||||
| Behavioral blocks | 79 |
|
||||
| Generic agents (manifests) | 12 |
|
||||
| Hooks (PreToolUse / PostToolUse) | 10 |
|
||||
| Portable skills | 39 |
|
||||
| Rust primitives (opt-in, profile-gated) | 25 |
|
||||
| Shell primitives (opt-in) | 13 |
|
||||
| Cross-tool bridges | 11 |
|
||||
### 🌙 Your AI sleeps at night
|
||||
|
||||
Every primitive / hook / skill with its actual CLI surface → [docs/REFERENCE.md](./docs/REFERENCE.md).
|
||||
You worked all day. At bedtime you type `/sleep-on-it what's the right database for X` and close the laptop. While you sleep, a remote agent reads your day's traces, extracts patterns, and by morning your memory-repo has a report waiting. `git pull` → read → decide. Nothing auto-injected. [How sleep works →](./docs/SLEEP-LAYER.md)
|
||||
|
||||
### 💾 One brain, any client
|
||||
|
||||
```bash
|
||||
keisei mount /Volumes/MyBrain
|
||||
```
|
||||
|
||||
Your agents, memory, artifacts, and per-platform MCP binaries all live on a directory — USB stick, iCloud, S3, anything. One command mounts it into Claude Code + Cursor + Continue + Zed simultaneously. Move the drive to another computer — same state is there. [Full setup →](./docs/INSTALL.md#the-keisei-cli)
|
||||
|
||||
### 🧩 Write agent rules once, ship everywhere
|
||||
|
||||
A manifest + reusable blocks compiles into a `.md` file Claude Code reads. Edit one block — every agent using it rebuilds automatically. Same `kei-critic` behaves identically on every machine that installs the kit. [Architecture →](./docs/ARCHITECTURE.md)
|
||||
|
||||
### 🛡️ Catches mistakes before they commit
|
||||
|
||||
Fabricated citations. Secrets in a push. Three failed retries on the same bug. All caught at the hook layer, before anything hits your repo. You don't configure it — it ships wired. [What's watched →](./docs/SECURITY.md)
|
||||
|
||||
### 🌉 One source, eleven AI tools
|
||||
|
||||
Your rules get emitted to `.cursorrules`, `AGENTS.md`, `.github/copilot-instructions.md`, Cursor MDC, Windsurf, Gemini.md, Aider, Continue, Junie, Replit, and plain AGENTS.md — in one command. Switch between tools without rewriting your setup.
|
||||
|
||||
## Batteries included
|
||||
|
||||
- **12 agents** — `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, and more (all namespaced `kei-*` so they coexist peacefully with anything you already have)
|
||||
- **39 skills** — one-command pipelines: `/new-project`, `/schema-design`, `/api-design`, `/ci-scaffold`, `/auth-setup`, `/observability-setup`, `/self-audit`, `/sleep-on-it`, ...
|
||||
- **10 hooks** — pre-commit safety net, always on
|
||||
- **79 behavioral blocks** — tested patterns you compose into your own agents
|
||||
- **25 Rust primitives** — for the jobs where Python silently corrupts your data
|
||||
|
||||
Every symbol, flag, and exit code: [docs/REFERENCE.md](./docs/REFERENCE.md)
|
||||
|
||||
## Under the hood (only if you care)
|
||||
|
||||
Constructor Pattern: one file, one concern. TOML manifests are the source of truth. A Rust assembler compiles them to the Markdown Claude Code expects. When you edit a block, a PostToolUse hook rebuilds every affected agent. Rust is the backbone because the type system catches the class of mistakes LLMs most often introduce — `None` vs `[]`, missing `.await`, unhandled `Result` — at compile time, so they can't ship. Python is reserved for places where Python is genuinely better.
|
||||
|
||||
Full build pipeline, cross-tool bridge mechanics, meta-composer, sleep-layer internals → [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
|
||||
|
||||
## Docs
|
||||
|
||||
| File | What's in it |
|
||||
| | |
|
||||
|---|---|
|
||||
| [docs/INSTALL.md](./docs/INSTALL.md) | Install paths, profiles, MCP binary, `keisei` CLI, runtime hook controls |
|
||||
| [docs/REFERENCE.md](./docs/REFERENCE.md) | Every primitive / hook / skill / pipeline with flags + exit codes |
|
||||
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, cross-tool bridges, meta-composer, workflow editing |
|
||||
| [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Three-phase nightly cycle + session self-audit |
|
||||
| [docs/SECURITY.md](./docs/SECURITY.md) | Threat model + mitigations |
|
||||
| [docs/WHY.md](./docs/WHY.md) | Full "From the author" philosophical backstory |
|
||||
| [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) | Portable brain on removable media — macOS / Linux / Windows splits |
|
||||
| [CHANGELOG.md](./CHANGELOG.md) | Release notes (Conventional Commits → Markdown via `kei-changelog`) |
|
||||
| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format install path (v0.16+) |
|
||||
| [INSTALL.md](./docs/INSTALL.md) | All install paths, profiles, `keisei` CLI, hook controls |
|
||||
| [REFERENCE.md](./docs/REFERENCE.md) | Every primitive, hook, skill with flags and exit codes |
|
||||
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, bridges, meta-composer |
|
||||
| [SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Nightly cycle + self-audit |
|
||||
| [SECURITY.md](./docs/SECURITY.md) | Threat model + mitigations |
|
||||
| [USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) | Portable brain — macOS / Linux / Windows |
|
||||
| [WHY.md](./docs/WHY.md) | The full story of why this exists |
|
||||
| [CHANGELOG.md](./CHANGELOG.md) | What changed, version by version |
|
||||
| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format details |
|
||||
|
||||
## 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.
|
||||
Built by Denis Parfionovich (<parfionovich@keilab.io>) while running 4–8 parallel Claude Code terminals every day. What you're looking at is the scaffolding that makes that possible — shared now so you don't have to build your own.
|
||||
|
||||
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.** Forks and PRs welcome from everyone, not only from those who write code. Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution. Full backstory in [docs/WHY.md](./docs/WHY.md).
|
||||
Forks and PRs welcome. Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue