58944e15bd
Substrate thesis requires a single source of truth before parallel work streams (UI/Atoms/Graph/Runtime) can proceed independently without drift. This document is that SSoT. Key decisions baked in (open to revision before lock): - Atom = one verb on a primitive, not one crate. Target ~150 atoms across current 25 crates. Crate = physical container, atom = unit of composition. - File layout: src/atoms/<verb>.rs (code) + atoms/<verb>.md (docs with machine-parseable YAML frontmatter) + atoms/schemas/*.json (JSON Schema draft-07 for input/output) + capabilities.toml (auto-generated aggregator, committed to repo). - Atom kinds: command / query / stream / transform. Combined with side_effects[] and idempotent flag, runtime decides retry safety, parallelism, caching. - Naming: <crate>::<verb> globally unique. Rust :: separator keeps it native-feeling. - Versioning: atoms inherit crate SemVer. Breaking change to an atom = new atom (create-v2), old marked deprecated. - Runtime contract: `kei-runtime invoke <atom-id> --input <json>` with schema validation at entry + exit, ledger row per invocation. - Graph contract: kei-sage auto-walks atoms/*.md, resolves [[atom-id]] wikilinks, exposes rank / related / search / graph over atom corpus. - UI contract: kei-forge web wizard generates .md + .json + .rs + test from form input; postcondition cargo check + kei-schema-lint pass. Document declares 4 stream interfaces explicitly — each stream knows what it reads from this schema, what it writes, what it does NOT depend on from other streams. Enables true parallel work. 6 open questions flagged for user review at bottom: 1) JSON Schema draft-07 vs 2020-12 2) Atom ID separator :: vs / 3) side_effects strings vs structured 4) capabilities.toml committed vs gitignored 5) kei-atom-template in this PR or defer to Stream A 6) Error model per-atom vs shared registry STATUS: DRAFT — awaits user approval + SCHEMA-LOCKED.md marker before parallel streams start. Once locked, breaking changes require explicit revocation + all-streams sync. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .claude-plugin | ||
| .github | ||
| _assembler | ||
| _blocks | ||
| _bridges | ||
| _manifests | ||
| _primitives | ||
| _templates | ||
| _ts_packages | ||
| docs | ||
| hooks | ||
| install | ||
| scripts | ||
| skills | ||
| tests/battle | ||
| .dockerignore | ||
| .gitignore | ||
| CHANGELOG.md | ||
| install.sh | ||
| LICENSE | ||
| PLUGIN.md | ||
| README.md | ||
| settings-snippet.json | ||
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 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.
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.mdback 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.
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.
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.
keisei mount /Volumes/MyBrain # attaches to every detected AI client
keisei detach # clean unmount from all clients
Setup path: docs/INSTALL.md § keisei CLI.
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:
# 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.
What's in the box
| 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 |
Every primitive / hook / skill with its actual CLI surface → docs/REFERENCE.md.
Docs
| File | What's in it |
|---|---|
| docs/INSTALL.md | Install paths, profiles, MCP binary, keisei CLI, runtime hook controls |
| docs/REFERENCE.md | Every primitive / hook / skill / pipeline with flags + exit codes |
| docs/ARCHITECTURE.md | Build pipeline, cross-tool bridges, meta-composer, workflow editing |
| docs/SLEEP-LAYER.md | Three-phase nightly cycle + session self-audit |
| docs/SECURITY.md | Threat model + mitigations |
| docs/WHY.md | Full "From the author" philosophical backstory |
| docs/USB-BRAIN-GUIDE.md | Portable brain on removable media — macOS / Linux / Windows splits |
| CHANGELOG.md | Release notes (Conventional Commits → Markdown via kei-changelog) |
| PLUGIN.md | Anthropic plugin-format install path (v0.16+) |
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.
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 — a well-formulated problem is already half the solution. Full backstory in docs/WHY.md.
License
MIT. See LICENSE.