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, 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

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.