168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code
|
|
|
|
KeiSeiKit is a drop-in agent fleet 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, four pre-wired hooks, and seven portable skills including an interactive `/new-agent` wizard. 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 12-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, and a build pipeline that keeps every agent derivable from its manifest.
|
|
|
|
## Prerequisites
|
|
|
|
- **Rust** (stable toolchain) — the assembler is a small Cargo binary
|
|
- **jq** — used by the four 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
|
|
|
|
## Install
|
|
|
|
```bash
|
|
git clone <your-fork-of-this-repo> KeiSeiKit
|
|
cd KeiSeiKit
|
|
./install.sh
|
|
```
|
|
|
|
`install.sh` is idempotent. It:
|
|
|
|
1. Creates `~/.claude/agents/{_blocks,_manifests,_templates,_assembler,_generated}`, `~/.claude/hooks`, `~/.claude/skills`
|
|
2. Copies all blocks (overwrites — blocks are SSoT from the kit)
|
|
3. Copies generic manifests (skips if you already have a manifest with that name)
|
|
4. Builds the Rust assembler (`cargo build --release`)
|
|
5. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
|
|
6. Copies the four hooks and seven 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.
|
|
|
|
> **Re-install disclaimer (v0.1.1):** `install.sh` is idempotent for clean state but **overwrites kit-owned `_blocks/`, `_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.
|
|
|
|
## What you get
|
|
|
|
| Category | Count | Examples |
|
|
|---|---:|---|
|
|
| Behavioral blocks | 33 | `baseline`, `evidence-grading`, `rule-math-first`, `stack-rust-axum`, `deploy-modal`, `api-fal-ai`, ... |
|
|
| Generic agents (manifests) | 12 | `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, `kei-cost-guardian`, `kei-modal-runner`, ... |
|
|
| Hooks | 4 | `assemble-agents` (PostToolUse), `assemble-validate` (PreToolUse Bash), `no-hand-edit-agents` (PreToolUse Edit/Write), `tomd-preread` (PreToolUse Read) |
|
|
| Skills | 7 | `new-agent`, `research`, `test-gen`, `pr-review`, `refactor`, `debug-deep`, `compose-solution` |
|
|
|
|
Of the 33 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 12 shipped manifests. The remaining **25 blocks** (`stack-*`, `deploy-*`, `api-*`, `scraper-*`, `domain-*`) are a library consumed by the `/new-agent` wizard: when you compose a project specialist, the wizard picks the appropriate stack / deploy / API / scraper / domain blocks and emits a manifest that references them. The kit's generic 12 agents do not import them by default.
|
|
|
|
> **Frontend-stack coverage gap.** The shipped `stack-*` blocks currently cover Next.js and Flutter. Pure frontend frameworks (React-Vite, Vue-Nuxt, SvelteKit, Astro, Angular, plain-web) are planned as a follow-up; contributions are welcome via PR. Blocks stay in a single `_blocks/` directory — no opt-in split planned.
|
|
|
|
## 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 / 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.
|
|
|
|
## 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
|
|
```
|
|
|
|
Four hooks enforce the pipeline:
|
|
|
|
- **`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. Cache under `$KEISEI_TOMD_CACHE` (default `/tmp/keisei-tomd-cache`). Degrades silently if `jq` or the primitive is absent.
|
|
|
|
## 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 11 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` |
|
|
|
|
**Two ways to generate:**
|
|
|
|
1. **At install time** — `./install.sh --with-bridges` renders all 11 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 11, 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.
|
|
|
|
## Primitives
|
|
|
|
`_primitives/` holds first-class building blocks that agents and pipelines depend on — executable utilities, not behavioral markdown. Currently one primitive ships with the kit:
|
|
|
|
- `tomd` — universal non-native-format → markdown converter (PDF, DOCX, XLSX, PPTX, CSV, code, images with OCR). Ported from the KeiAgent project (user's personal CLI predecessor) with KeiSeiKit-style error tags and a configurable cache directory (`KEISEI_TOMD_CACHE`, default `/tmp/keisei-tomd-cache`).
|
|
|
|
The matching hook `hooks/tomd-preread.sh` is a `PreToolUse(Read)` entry that auto-redirects Claude to a cached markdown conversion when a Read targets an opaque binary format — no agent has to know about `tomd` explicitly, but any agent that *does* need to shell out can invoke `~/.claude/agents/_primitives/tomd.sh report.pdf > report.md` directly.
|
|
|
|
`/compose-solution` auto-discovers primitives: Phase 3's prior-art grep includes `_primitives/` so new composed artefacts can reference the existing converter instead of rolling their own.
|
|
|
|
## 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 / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, or block. 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/` and `_blocks/` for prior art → Phase 5 proposes `hook = PreToolUse:Bash + pattern + exit 2` → Phase 7 hands off to `/escalate-recurrence` with severity and event pre-filled.
|
|
|
|
Phase 6 is the feedback loop: when a component has no prior art, the skill drafts a new `_blocks/<slug>.md` and — on your click — persists it. Next time `/compose-solution` (or `/new-agent`) runs, that block is discoverable. Every session leaves the kit a little smarter; the report prints `_blocks/` count before → after so the growth is visible.
|
|
|
|
See `skills/compose-solution/SKILL.md` and its phase files (`phase-1-intake.md` through `phase-7-assemble.md`) for the full 7-phase pipeline.
|
|
|
|
## License
|
|
|
|
MIT. See `LICENSE` in this directory.
|