f2358397c9
- README rewritten with bioinspired framing: KeiSeiKit as living neural structure of Kei (DNA / REM / Deep Sleep / creator lineage). All counts verified against source: 36 crates, 12 agents, 43 skills, 12 hooks, 82 blocks. - docs/PHILOSOPHY.md new 11.4 KB deep-dive on the substrate thesis, the 4-layer architecture, and roadmap (federation / signing / marketplace / visualization as Wave 14+). - .gitignore hardened: .env, secrets/, *.pem, *.key, id_rsa*, id_ed25519*, .claude/secrets/ — public-repo safe. .env.example and .env.template re-included. - docs/SECURITY.md: secret hygiene section with revoke-and-rotate protocol + canonical ~/.claude/secrets/.env reference (RULE 0.8). Verified clean: defensive grep for sk-ant-, ghp_, private keys, token/key assignments = zero hits across tree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
116 lines
9 KiB
Markdown
116 lines
9 KiB
Markdown
# KeiSeiKit
|
||
|
||
> A living neural structure you install next to your AI assistant.
|
||
> A mini-universe where any user, from any domain, can discover a new primitive or grow a new class of agent.
|
||
|
||
KeiSeiKit is not a toolkit. It is a substrate for cognitive growth — an opinionated neural structure of Kei that a developer installs, shapes, and extends. It sleeps when you sleep, remembers what you decided yesterday, heals mistakes it notices in itself, and runs from a directory you can put on a USB stick and carry between machines.
|
||
|
||
## Install in one line
|
||
|
||
```bash
|
||
/plugin marketplace add KeiSei84/KeiSeiKit
|
||
/plugin install keisei@keisei-marketplace
|
||
```
|
||
|
||
Twelve agents appear in Claude Code, forty-three skills become callable as `/self-audit`, `/sleep-on-it`, `/compose-solution`, `/new-project`, `/spawn-agent` — and the nightly consolidation cycle is wired. Other install paths: [docs/INSTALL.md](./docs/INSTALL.md).
|
||
|
||
## The five biological principles
|
||
|
||
KeiSeiKit is organised around five properties a living neural system has, and most software doesn't. Each principle maps to concrete code shipped in this repo.
|
||
|
||
- **DNA and taxonomy.** Every agent invocation gets a 80-character deterministic identifier composed from role, capability bitmap, scope hash, task-body hash, and per-spawn nonce. Every primitive and agent is tagged along seven orthogonal facets — kingdom, mechanism, domain, layer, stage, stability, language — so the graph is queryable along any axis. See `_primitives/_rust/kei-agent-runtime/src/dna.rs` and [docs/TAXONOMY.md](./docs/TAXONOMY.md).
|
||
|
||
- **Creator lineage.** Every row in the agent ledger carries `creator_id` and `fork_parent_id`. Who spawned what, from which parent, under which DNA — traceable. No orphan artefacts, no "where did this come from". See `_primitives/_rust/kei-ledger/src/schema.rs` migration v4.
|
||
|
||
- **Sleep. Three phases, every night.** Phase A is incubation: during the day you drop tasks into `/sleep-on-it`; at 03:00 a remote Claude agent works on them. Phase B is REM: the same agent reads the day's JSONL traces, extracts cross-session patterns, and writes a report. Phase C is NREM (every seven days by default): a conflict-scan plus refactor-engine propose a clean-up branch. Nothing auto-injects into the next session — you `git pull`, read, decide. See [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md).
|
||
|
||
- **Self-healing.** Three passive hooks (`session-end-dump`, `milestone-commit-hook`, `error-spike-detector`) feed a session retrospective. When the same mistake reappears twice, `/escalate-recurrence` offers to codify it as rule plus wiki entry plus hook — at the severity you pick. Silent-first: the first ten sessions log without prompting, so the baseline is real.
|
||
|
||
- **Growth by composition.** `/new-project` scaffolds a project across four phases with branch + ledger + artefact bundle per fork. `/spawn-agent` emits a new agent manifest. `/compose-solution` decomposes a free-text problem, greps existing atoms for prior art, and proposes the smallest artefact — agent, skill, hook, rule, block, or pipeline — that closes the gap. Every session leaves the substrate slightly larger than it found it.
|
||
|
||
The deeper theory — why these five and not others, and the analogy with hippocampal / cortical dynamics — is in [docs/PHILOSOPHY.md](./docs/PHILOSOPHY.md).
|
||
|
||
## Four layers
|
||
|
||
```
|
||
4. Portability USB stick / iCloud / S3 — keisei mount, any machine
|
||
3. Sleep Phase A (incubation) → Phase B (REM) → Phase C (NREM)
|
||
2. Cognition DNA + ledger + taxonomy + memory + self-audit
|
||
1. Substrate atoms, agents, skills, hooks, blocks, bridges
|
||
```
|
||
|
||
Layer 1 is the body — the reusable parts. Layer 2 is identity and memory. Layer 3 is overnight learning. Layer 4 is the ability to pick up and move.
|
||
|
||
## What ships (verified counts)
|
||
|
||
- **36 Rust primitives** — pure Rust workspace crates, release-stripped, each ≤2 MB, no Python runtime. Covers the ledger, memory, router, migrate, agent runtime, forge, spawn/replay, sleep infrastructure, and the `keisei` CLI.
|
||
- **12 agents** (`kei-*` namespaced) — code-implementer, infra-implementer, ml-implementer, critic, validator, security-auditor, architect, researcher, ml-researcher, cost-guardian, modal-runner, fal-ai-runner. All carry a `substrate_role` facet.
|
||
- **43 skills** — one-command pipelines including `/new-project`, `/spawn-agent`, `/self-audit`, `/sleep-on-it`, `/sleep-setup`, `/compose-solution`, `/schema-design`, `/api-design`, `/auth-setup`, `/observability-setup`, `/ci-scaffold`, `/pr-review`, `/debug-deep`.
|
||
- **12 hooks** — pre-commit safety net, always on: assembler, validator, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, session-end-dump, milestone-commit-hook, error-spike-detector, and two capability gates.
|
||
- **82 behavioural blocks** — tested patterns composable into your own agents via `blocks = [...]` in a manifest.
|
||
- **11 capabilities / 5 roles** — the capability-graph that agents resolve at spawn time.
|
||
- **11 cross-tool bridges** — one source of truth emits `.cursorrules`, Cursor MDC, `AGENTS.md`, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit. Switch AI tools without rewriting your setup.
|
||
- **500+ tests** across the Rust workspace, green on `cargo test --workspace` on every supported OS.
|
||
|
||
Every number is regenerated from source by `scripts/regen-counts.sh` — no manual drift.
|
||
|
||
## Domain-agnostic by construction
|
||
|
||
KeiSeiKit has no hardcoded domain. The same substrate ships unchanged for biology, finance, law, medicine, music, research, game dev, ops. What's domain-aware lives in the *blocks* — reusable markdown cubes you compose into an agent manifest — and the assembler rebuilds the affected agents when a block changes. If you work in a domain the kit doesn't yet cover, the path to first-class support is a manifest plus a handful of blocks, not a fork.
|
||
|
||
## How to start
|
||
|
||
**Install:** the two-line plugin command above. Other paths — full profile, dev profile, MCP-only, manual, Nix, Docker — are in [docs/INSTALL.md](./docs/INSTALL.md).
|
||
|
||
**Discover a new primitive:**
|
||
```
|
||
/compose-solution "I want a hook that blocks rm -rf ~/ in any Bash call"
|
||
```
|
||
The skill greps existing atoms, proposes the smallest intervention, drafts a block if nothing matches, and hands off to `/escalate-recurrence` to persist it.
|
||
|
||
**Grow a new agent:**
|
||
```
|
||
/spawn-agent
|
||
```
|
||
Four phases: role, task, scope, emit. The wizard writes the manifest, composes its DNA, forks a ledger row, and the assembler generates the agent markdown Claude Code will pick up.
|
||
|
||
**Start a new project:**
|
||
```
|
||
/new-project
|
||
```
|
||
Four phases: intake, fork skeleton, parallel execution (orchestrator owns git per RULE 0.13), merge ceremony with per-branch AskUserQuestion.
|
||
|
||
## Portability
|
||
|
||
Every primitive is a pure Rust binary ≤2 MB. Every hook is POSIX shell. Every skill is markdown. Every manifest is TOML. The `keisei` CLI mounts a brain-directory into Claude Code + Cursor + Continue + Zed simultaneously; the directory can live on a USB stick, iCloud, S3, or any filesystem. Move it to another machine and the same agents, the same memory, the same artefact bundles are there. [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md).
|
||
|
||
## Under the hood
|
||
|
||
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 a block changes, 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 cannot ship. Python is reserved for the places where Python is genuinely better.
|
||
|
||
Build pipeline, cross-tool bridge mechanics, meta-composer internals, sleep-layer details → [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
|
||
|
||
## Docs
|
||
|
||
| | |
|
||
|---|---|
|
||
| [PHILOSOPHY.md](./docs/PHILOSOPHY.md) | The biological principles, in depth |
|
||
| [INSTALL.md](./docs/INSTALL.md) | All install paths, profiles, `keisei` CLI, hook controls |
|
||
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, bridges, meta-composer |
|
||
| [REFERENCE.md](./docs/REFERENCE.md) | Every primitive, hook, skill with flags and exit codes |
|
||
| [SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Phase A / B / C nightly cycle + self-audit |
|
||
| [TAXONOMY.md](./docs/TAXONOMY.md) | The seven-facet vocabulary |
|
||
| [SUBSTRATE-SCHEMA.md](./docs/SUBSTRATE-SCHEMA.md) | Atom contract |
|
||
| [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 |
|
||
|
||
## Authorship
|
||
|
||
Built by Denis Parfionovich (<parfionovich@keilab.io>) at KeiLab, while running 4–8 parallel Claude Code terminals every day. What you are looking at is the scaffolding that makes that possible — shared now so you don't have to build your own. Forks and pull requests welcome.
|
||
|
||
## License
|
||
|
||
MIT. See [LICENSE](./LICENSE).
|