KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code

KeiSeiKit is a drop-in agent fleet for Claude Code. It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent .md files from TOML manifests deterministically, three pre-wired hooks, and six 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 14-agent fleet (implementers, critics, researchers, cost-guardians, and more), 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 three 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

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 three hooks and six 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	34	baseline, evidence-grading, rule-math-first, stack-rust-axum, deploy-modal, api-fal-ai, ...
Generic agents (manifests)	14	code-implementer, critic, validator, security-auditor, architect, researcher, ml-implementer, cost-guardian, modal-runner, ...
Hooks	3	assemble-agents (PostToolUse), assemble-validate (PreToolUse Bash), no-hand-edit-agents (PreToolUse Edit/Write)
Skills	6	new-agent, research, test-gen, pr-review, refactor, debug-deep

Of the 34 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 14 shipped manifests. The remaining 26 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 14 agents do not import them by default.

Creating a new agent

Run the wizard in Claude Code:

/new-agent

You'll be asked (via option-pickers, not free-text):

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. Contains unfiled patent IP? (Yes — banned public / No)
6. Has credentials? (Yes / No)
7. 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

Three 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.

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

Agent	Role
code-implementer	Write production code, Constructor Pattern enforced, Test-First discipline
infra-implementer	Deploy scripts, CI/CD, secrets management, cost-aware paid infra
ml-implementer	Training scripts, inference code, Modal jobs, exact param counts
critic	Read-only anti-pattern / bug / security / perf / debt finder
validator	Fact-checker; verifies API existence, version compat, citations, doc claims
security-auditor	Risk-classified security audit with variant analysis + supply chain check
architect	Read-only structural analysis; dep graph, patterns, coupling
researcher	Generic web + codebase research, evidence-graded findings
ml-researcher	ML literature, benchmarks, reproducibility, tooling-reuse search
cost-guardian	Pre-launch GO/NO-GO for paid compute (Modal, AWS, fal.ai, Apify, etc.)
modal-runner	Modal compute orchestrator with KILL GUARD (never stops running jobs)
fal-ai-runner	fal.ai image/video/3D generation expert
patent-researcher	Prior-art, FTO, novelty — never leaks unfiled IP to public search
patent-compliance	Pre-filing cross-reference gate and defensive-language helper

License

MIT. See LICENSE in this directory.