KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code

KeiSeiKit is a comprehensive drop-in toolkit for Claude Code. It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent .md files from TOML manifests deterministically, six pre-wired hooks, 34 portable skills (including an interactive /new-agent wizard and 10 hub-and-spoke pipelines), 8 Rust primitive crates, 13 shell primitives, and 11 cross-tool bridge templates. 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, 10 pipeline skills that combine primitives end-to-end (/compose-solution, /site-create, /schema-design, /observability-setup, /auth-setup, /api-design, /ci-scaffold, /test-matrix, /docs-scaffold, /new-project, /vm-provision), and a build pipeline that keeps every agent derivable from its manifest.

Prerequisites

Hard (needed for every install, regardless of profile):

• Rust (stable toolchain) — the assembler Cargo workspace is always built
• jq — used by the 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

Soft (only needed if the chosen profile pulls the primitive in — see the profile table below):

• pandoc — tomd uses it for .docx / .pptx / .html (needed for core / full profile)
• Node + Playwright — for the 3 browser-driven frontend primitives design-scrape, live-preview, mock-render (frontend / full profile); install with npm i -g playwright && playwright install chromium
• sqlite3 CLI — optional for manual DB inspection of kei-ledger / kei-migrate (their binaries embed SQLite via rusqlite; ops / dev profile)
• hcloud / vultr-cli — wrapped by provision-hetzner / provision-vultr (ops profile)
• yq v4 (mikefarah/yq Go impl) — required by kei-ci-lint (dev profile)

install.sh checks only the deps relevant to the selected profile and soft-warns once per missing tool.

Install

git clone <your-fork-of-this-repo> KeiSeiKit
cd KeiSeiKit
./install.sh                      # profile=minimal (default, no primitives)

install.sh is idempotent. It:

1. Creates ~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}, ~/.claude/hooks, ~/.claude/skills
2. Copies all blocks + bridges (overwrites — these are SSoT from the kit)
3. Copies primitives ONLY for the selected profile (default: minimal = none). Tracks installed set in ~/.claude/agents/_primitives/.installed.
4. Copies generic manifests (skips if you already have a manifest with that name)
5. Builds the Rust assembler (cargo build --release in _assembler/)
6. If any Rust primitive is in the selected profile: writes a scoped workspace Cargo.toml listing ONLY the installed crates, then cargo build --release
7. Generates agent .md files in-place with AGENT_ROOT=~/.claude/agents assemble --in-place
8. Copies the six hooks and 34 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.

Interactive install

Run ./install.sh with no profile flag on a TTY and you get a menu:

• whiptail or dialog detected → curses-style TUI (radiolist for profile, checklist for custom)
• neither available → plain-text numbered picker (1-7 + a custom option)

After the profile is chosen, an Install Plan screen summarizes what will be copied, which soft-deps are present (jq, pandoc, playwright, cargo, hcloud, vultr-cli, yq, sqlite3, curl), and the rough time + disk footprint — then asks Proceed? [Y/n]. Pass --yes to skip the confirm screen (the menu still runs). Pass --no-execute to parse menu + confirm and exit without copying anything (useful for dry-run). The menu is skipped automatically when any selection flag is passed (--profile, --add, --remove, --list) or when stdin/stdout is not a TTY (CI runs default to minimal exactly as before).

Install profiles

By default ./install.sh is minimal — agents + hooks + skills + bridges, no primitives. Fastest (~5s) and zero Rust compile for primitives. You opt into primitives via --profile=<name> or one-at-a-time via --add=<name>.

Profile	Primitives added	Install time	Disk (approx)
minimal (default)	none	~5s	~2 MB
core	tomd	~5s	~2 MB
frontend	8 site tools: mock-render, visual-diff, tokens-sync, design-scrape, live-preview, figma-tokens, frontend-inspect, screenshot-decode	~60s	~80 MB
ops	8 infra tools: kei-ledger, ssh-check, firewall-diff, provision-hetzner, provision-vultr, harden-base, metrics-scrape, log-ship	~90s	~50 MB
dev	4 dev tools: kei-migrate, kei-changelog, kei-ci-lint, kei-docs-scaffold	~60s	~40 MB
full	everything (21 primitives)	~5 min	~200 MB

Examples:

./install.sh                        # minimal (no primitives)
./install.sh --profile=frontend     # minimal + 8 site tools
./install.sh --profile=full         # everything (old default behaviour)
./install.sh --add=kei-ledger       # add a single primitive on top of current install
./install.sh --add=kei-ledger,ssh-check
./install.sh --add=ops              # a profile name works too — unions its members in
./install.sh --list                 # show each primitive: name | kind | installed? | description
./install.sh --remove=kei-migrate   # remove one (rebuilds scoped rust workspace if needed)

Profile resolution lives in _primitives/MANIFEST.toml — one [primitive.<name>] entry per primitive plus a [profile] block. Edit the manifest to define new profiles without touching install.sh.

Migrating from a full install: if you're re-running install.sh after an earlier version that installed all 21 primitives unconditionally, the new default (minimal) will REMOVE them. To preserve the old behaviour explicitly, pass --profile=full.

Re-install disclaimer: install.sh is idempotent for clean state but overwrites kit-owned _blocks/, _primitives/, _bridges/, _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	73	baseline, evidence-grading, rule-math-first, stack-rust-axum, stack-react-vite, stack-vue-nuxt, stack-sveltekit, stack-astro, 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	6	assemble-agents, assemble-validate, no-hand-edit-agents, tomd-preread, agent-fork-logger, site-wysiwyd-check
Portable skills	34	compose-solution, new-agent, new-project, site-create, schema-design, observability-setup, auth-setup, api-design, ci-scaffold, test-matrix, docs-scaffold, vm-provision, ...
Primitives (Rust crates, opt-in)	8	kei-ledger, kei-migrate, kei-changelog, ssh-check, firewall-diff, mock-render, visual-diff, tokens-sync
Primitives (shell, opt-in)	13	tomd, design-scrape, live-preview, figma-tokens, frontend-inspect, screenshot-decode, metrics-scrape, log-ship, provision-hetzner, provision-vultr, harden-base, kei-ci-lint, kei-docs-scaffold
Cross-tool bridges	11	Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit

Of the 73 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 blocks (stack-*, deploy-*, api-*, scraper-*, domain-*) are a library consumed by the /new-agent wizard and the hub-and-spoke pipeline skills: when you compose a project specialist or spin up a site, the wizard / pipeline picks the appropriate blocks and emits artefacts that reference them.

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 / React-Vite / Vue-Nuxt / SvelteKit / Astro / 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.

Pipelines

Hub-and-spoke skills that combine primitives into end-to-end flows. Each one is an option-picker-first, free-text-last wizard; every phase has a verify-criterion.

Skill	One-line purpose
/compose-solution	Meta-composer: decompose any task, grep prior art, propose math-first architecture, assemble the right artefact (agent / skill / hook / block)
/new-project	Bootstrap a project specialist agent + repo skeleton + bridges + ledger row
/new-agent	Interactive 6-question wizard that builds a project-specialist manifest and its .md
/site-create	Frontend stack pick → design tokens → scaffold → WYSIWYD loop (mock-render, visual-diff, tokens-sync)
/schema-design	DB schema design → migrations → kei-migrate apply (PG/SQLite/MySQL autodetect)
/observability-setup	Pick metrics + logs stack → scrape + ship config (metrics-scrape, log-ship)
/auth-setup	Pick auth model (session / JWT / OAuth2) → emit routes + middleware + token rotation
/api-design	Contract-first: pick REST vs GraphQL vs gRPC, emit types + handlers + tests
/ci-scaffold	GitHub Actions / Forgejo Actions workflow skeleton + kei-ci-lint pre-commit
/test-matrix	Test stack matrix: unit / integration / e2e / visual; pick stack, emit skeleton
/docs-scaffold	Doc site skeleton (mdbook / docusaurus / astro-starlight) + kei-changelog generator
/vm-provision	VM provider pick → provision-* primitive → harden-base + ssh-check + firewall-diff verification

All pipelines share a single discovery layer: /compose-solution Phase 3's prior-art grep covers _blocks/, _manifests/, _primitives/ (shell + Rust), skills/, _bridges/, hooks/ — so any pipeline can reuse primitives without re-inventing them.

Primitives (Rust)

_primitives/_rust/ is a Cargo workspace with 8 single-binary crates. install.sh builds --release and drops binaries at ~/.claude/agents/_primitives/_rust/target/release/<name>.

Crate	Purpose
kei-ledger	Agent-fork lifecycle SQLite (fork / done / fail); SSoT for RULE 0.12
kei-migrate	Universal DB migration runner — Postgres / SQLite / MySQL autodetect from DATABASE_URL
kei-changelog	Git-cliff-style CHANGELOG.md generator from Conventional Commits
ssh-check	sshd_config linter — flags weak ciphers, PermitRootLogin yes, password auth, etc.
firewall-diff	ufw intended-vs-running diff — catches drift between declared policy and live kernel rules
mock-render	Playwright wrapper — takes screenshots with SHA-locked PNGs (WYSIWYD: What You See Is What You Deploy)
visual-diff	Pixel diff with tolerance — used in /site-create screenshot-regression loop
tokens-sync	Design tokens JSON → Tailwind config extend + CSS variables under :root

Primitives (shell)

_primitives/*.sh is the shell-primitive layer. Installed at ~/.claude/agents/_primitives/ by install.sh with chmod +x.

Primitive	Purpose
tomd	Universal non-native-format → markdown (PDF, DOCX, XLSX, PPTX, CSV, images with OCR, code)
design-scrape	Scrape a live URL's DOM + computed styles + asset manifest into a structured JSON blob
live-preview	start / stop / status dev server wrapper — writes .keisei/dev-server.pid for hook discovery
figma-tokens	Figma API → design tokens JSON (consumed by tokens-sync)
frontend-inspect	Pointer a running dev server, dump DOM tree + accessibility tree + CSS cascade for a given selector
screenshot-decode	OCR + layout extraction from a screenshot (used when design source is a PNG, not code)
metrics-scrape	Pull Prometheus / OpenMetrics endpoints, normalize, diff against baseline
log-ship	Tail structured logs, forward to Loki / CloudWatch / journald with rate limits
provision-hetzner	Hetzner Cloud API provisioner — server create + cloud-init + ready-wait
provision-vultr	Vultr API provisioner — same shape as Hetzner
harden-base	Post-provision baseline hardening — fail2ban, ufw, unattended-upgrades, no-root-ssh
kei-ci-lint	Pre-commit / pre-push CI lint — runs the minimum-viable checks locally before push
kei-docs-scaffold	One-shot doc site skeleton emitter (mdbook / docusaurus / astro-starlight)

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

Six 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.
• agent-fork-logger (PreToolUse, Agent) — RULE 0.12 advisory: logs every Agent subagent invocation to the kei-ledger SQLite DB so the orchestrator can validate the fork bundle. Never blocks; silent no-op if kei-ledger is absent.
• site-wysiwyd-check (PostToolUse, Edit/Write) — on frontend-source edits (.tsx, .vue, .svelte, .astro, .css, .html, .jsx, .ts) in a project with a live dev server (.keisei/dev-server.pid), takes a Playwright screenshot via mock-render and diffs against .keisei/target.png via visual-diff. Advisory-only — drift is reported to stderr, never blocks.

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

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

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 / primitives / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, block, or pipeline invocation. 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/, _blocks/, _primitives/ 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.