diff --git a/README.md b/README.md index ac4ee45..d02ffd1 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,17 @@ # 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. +KeiSeiKit is a comprehensive drop-in toolkit 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, 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, and a build pipeline that keeps every agent derivable from its manifest. +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 -- **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`) +- **Rust** (stable toolchain) — the assembler + 8 primitive crates are a Cargo workspace +- **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 +- **pandoc** (soft) — the `tomd` primitive falls back to pandoc for `.docx` / `.pptx` / `.html` +- **Node + Playwright** (soft) — required for frontend primitives (`design-scrape`, `live-preview`, `mock-render`); install with `npm i -g playwright && playwright install chromium` +- **sqlite3 CLI** (soft) — the `kei-ledger` / `kei-migrate` crates embed SQLite via `rusqlite`; the CLI is only needed if you want to inspect ledger DBs directly ## Install @@ -20,29 +23,31 @@ cd KeiSeiKit `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) +1. Creates `~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}`, `~/.claude/hooks`, `~/.claude/skills` +2. Copies all blocks, primitives (shell + Rust workspace), bridges (overwrites — these 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 +4. Builds the Rust assembler (`cargo build --release` in `_assembler/`) +5. Builds the 8 primitive crates (`cargo build --release` in `_primitives/_rust/`) +6. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place` +7. Copies the five 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. -> **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 `.bak-TIMESTAMP/` (or, for shared hook files, to `.bak-TIMESTAMP`). User-owned `_manifests/*.toml` are never overwritten. +> **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 `.bak-TIMESTAMP/` (or, for shared hook files, to `.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`, ... | +| 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 | 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` | +| 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) | 8 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync` | +| Primitives (shell) | 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 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. +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 @@ -54,7 +59,7 @@ Run the wizard in Claude Code: 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) +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) @@ -63,6 +68,62 @@ You'll be asked (via multiple option-picker batches, not free-text) — each bat 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/`. + +| 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 ``` @@ -76,12 +137,14 @@ Then one free-text prompt for slug + description + path + gotchas. The wizard co Block edit (_blocks/.md) <-- triggers rebuild of ALL agents ``` -Four hooks enforce the pipeline: +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 `` 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. +- **`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 @@ -135,7 +198,7 @@ KeiSeiKit ships 11 verified tool-bridge templates under `_bridges/`. Render them | Aider | `CONVENTIONS.md` + `.aider.conf.yml` | | Replit Agent | `replit.md` | -**Two ways to generate:** +**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. @@ -143,21 +206,11 @@ KeiSeiKit ships 11 verified tool-bridge templates under `_bridges/`. Render them 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. +`/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/` 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. +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/.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. diff --git a/hooks/site-wysiwyd-check.sh b/hooks/site-wysiwyd-check.sh new file mode 100755 index 0000000..f715823 --- /dev/null +++ b/hooks/site-wysiwyd-check.sh @@ -0,0 +1,75 @@ +#!/bin/sh +# site-wysiwyd-check.sh — PostToolUse(Edit|Write) advisory hook. +# +# Detects frontend source edits on a project that has a live dev server +# (.keisei/dev-server.pid exists) and reports visual drift against the +# most recent approved screenshot (.keisei/target.png). +# +# Non-blocking: every exit path is `exit 0`. If any dependency is missing +# (jq, mock-render, visual-diff, live server, target.png) the hook silently +# no-ops. Drift is printed to stderr; Claude Code surfaces it as advisory. +# +# Stdin: JSON with tool_input.file_path. + +command -v jq >/dev/null 2>&1 || exit 0 + +set -eu + +FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null || true) +[ -n "$FILE" ] || exit 0 + +# Extension whitelist — only frontend source files trigger a drift check. +EXT=$(printf '%s' "${FILE##*.}" | tr '[:upper:]' '[:lower:]') +case "$EXT" in + tsx|vue|svelte|astro|css|html|jsx|ts) ;; + *) exit 0 ;; +esac + +# Walk up from the edited file looking for .keisei/dev-server.pid. Stop at / +# or at $HOME to avoid unbounded traversal. +dir=$(dirname "$FILE") +pid_file="" +while [ "$dir" != "/" ] && [ "$dir" != "$HOME" ] && [ -n "$dir" ]; do + if [ -f "$dir/.keisei/dev-server.pid" ]; then + pid_file="$dir/.keisei/dev-server.pid" + break + fi + parent=$(dirname "$dir") + [ "$parent" = "$dir" ] && break + dir="$parent" +done +[ -n "$pid_file" ] || exit 0 + +PROJECT_DIR=$(dirname "$(dirname "$pid_file")") +TARGET_PNG="$PROJECT_DIR/.keisei/target.png" +[ -f "$TARGET_PNG" ] || exit 0 + +# Locate mock-render + visual-diff in the Rust primitive workspace. +RUST_BIN="$HOME/.claude/agents/_primitives/_rust/target/release" +MOCK="$RUST_BIN/mock-render" +DIFF="$RUST_BIN/visual-diff" +[ -x "$MOCK" ] || exit 0 +[ -x "$DIFF" ] || exit 0 + +# Read dev-server URL (default http://localhost:3000 if unrecorded). +URL_FILE="$PROJECT_DIR/.keisei/dev-server.url" +if [ -f "$URL_FILE" ]; then + URL=$(head -n1 "$URL_FILE") +else + URL="http://localhost:3000" +fi +[ -n "$URL" ] || exit 0 + +# Let HMR settle before screenshotting. +sleep 0.5 + +CURRENT_PNG="$PROJECT_DIR/.keisei/current.png" +"$MOCK" screenshot "$URL" --out "$CURRENT_PNG" >/dev/null 2>&1 || exit 0 +[ -f "$CURRENT_PNG" ] || exit 0 + +drift=$("$DIFF" "$TARGET_PNG" "$CURRENT_PNG" 2>/dev/null || true) +if [ -n "$drift" ]; then + echo "[site-wysiwyd] drift vs $TARGET_PNG: $drift" >&2 +fi + +exit 0 diff --git a/install.sh b/install.sh index b7ed068..252fac2 100755 --- a/install.sh +++ b/install.sh @@ -203,6 +203,16 @@ fi if ! command -v pandoc >/dev/null 2>&1; then warn "pandoc not found — tomd primitive will fail on .docx/.pptx. Install: brew install pandoc" fi +# Soft-warn on playwright — frontend primitives (design-scrape, live-preview, +# mock-render) need the Playwright browser driver. Not used by the core fleet. +if ! command -v playwright >/dev/null 2>&1 && ! command -v npx >/dev/null 2>&1; then + warn "playwright/npx not found — frontend primitives (design-scrape, live-preview, mock-render) will fail. Install: npm i -g playwright && playwright install chromium" +fi +# Soft-warn on sqlite3 CLI — kei-ledger / kei-migrate embed rusqlite, so the +# CLI is optional. Only surfaced so users can manually inspect the ledger DB. +if ! command -v sqlite3 >/dev/null 2>&1; then + warn "sqlite3 CLI not found — kei-ledger/kei-migrate work without it (rusqlite embedded). Install if you want manual DB inspection: brew install sqlite" +fi # --- create target dirs ----------------------------------------------------- say "creating directories" @@ -237,12 +247,40 @@ backup_dir "$AGENTS_DIR/_blocks" cp -f "$KIT_DIR/_blocks/"*.md "$AGENTS_DIR/_blocks/" # --- copy primitives (overwrite; primitives are SSoT from kit) ------------- +# Shell primitives live at _primitives/*.sh, Rust primitives under +# _primitives/_rust/ (Cargo workspace). The Rust workspace is copied wholesale +# but the compile artefacts (target/) are excluded — we rebuild locally. if [[ -d "$KIT_DIR/_primitives" ]]; then say "copying primitives -> $AGENTS_DIR/_primitives/" backup_dir "$AGENTS_DIR/_primitives" cp -f "$KIT_DIR/_primitives/"*.sh "$AGENTS_DIR/_primitives/" 2>/dev/null || true cp -f "$KIT_DIR/_primitives/README.md" "$AGENTS_DIR/_primitives/" 2>/dev/null || true chmod +x "$AGENTS_DIR/_primitives/"*.sh 2>/dev/null || true + if [[ -d "$KIT_DIR/_primitives/_rust" ]]; then + say " copying Rust primitive workspace (excluding target/)" + mkdir -p "$AGENTS_DIR/_primitives/_rust" + # Copy workspace manifest + each crate source, skip target/ + cp -f "$KIT_DIR/_primitives/_rust/Cargo.toml" "$AGENTS_DIR/_primitives/_rust/" + if [[ -f "$KIT_DIR/_primitives/_rust/Cargo.lock" ]]; then + cp -f "$KIT_DIR/_primitives/_rust/Cargo.lock" "$AGENTS_DIR/_primitives/_rust/" + fi + for crate_dir in "$KIT_DIR/_primitives/_rust/"*/; do + [ -d "$crate_dir" ] || continue + crate_name="$(basename "$crate_dir")" + [ "$crate_name" = "target" ] && continue + mkdir -p "$AGENTS_DIR/_primitives/_rust/$crate_name" + # Copy Cargo.toml + src/ + tests/ (if present) + cp -f "$crate_dir/Cargo.toml" "$AGENTS_DIR/_primitives/_rust/$crate_name/" 2>/dev/null || true + if [[ -d "$crate_dir/src" ]]; then + mkdir -p "$AGENTS_DIR/_primitives/_rust/$crate_name/src" + cp -rf "$crate_dir/src/"* "$AGENTS_DIR/_primitives/_rust/$crate_name/src/" 2>/dev/null || true + fi + if [[ -d "$crate_dir/tests" ]]; then + mkdir -p "$AGENTS_DIR/_primitives/_rust/$crate_name/tests" + cp -rf "$crate_dir/tests/"* "$AGENTS_DIR/_primitives/_rust/$crate_name/tests/" 2>/dev/null || true + fi + done + fi fi # --- copy bridges (overwrite; templates are SSoT from kit) ----------------- @@ -295,13 +333,19 @@ fi # $HOOKS_DIR is shared with other kits — back up each KeiSeiKit-owned hook # individually rather than the whole directory, so foreign hooks are not # dragged into .bak-TIMESTAMP snapshots on every re-run. +# Discover hooks dynamically from $KIT_DIR/hooks/*.sh so new hooks land +# automatically without editing install.sh. say "copying hooks -> $HOOKS_DIR/" -for h in assemble-agents.sh assemble-validate.sh no-hand-edit-agents.sh tomd-preread.sh; do - [ -f "$KIT_DIR/hooks/$h" ] || continue +hook_count=0 +for hook_src in "$KIT_DIR/hooks/"*.sh; do + [ -f "$hook_src" ] || continue + h="$(basename "$hook_src")" backup_file "$HOOKS_DIR/$h" - cp -f "$KIT_DIR/hooks/$h" "$HOOKS_DIR/$h" + cp -f "$hook_src" "$HOOKS_DIR/$h" chmod +x "$HOOKS_DIR/$h" + hook_count=$((hook_count+1)) done +say " installed $hook_count hook(s)" # --- copy skills ----------------------------------------------------------- if [[ -d "$KIT_DIR/skills" ]]; then @@ -329,6 +373,28 @@ if [[ ! -x "$AGENTS_DIR/_assembler/target/release/assemble" ]]; then exit 2 fi +# --- build Rust primitives workspace (8 crates) ---------------------------- +# Offline-first like the assembler. Failure here is non-fatal: the fleet and +# shell primitives still work without the 8 Rust binaries. +if [[ -d "$AGENTS_DIR/_primitives/_rust" && -f "$AGENTS_DIR/_primitives/_rust/Cargo.toml" ]]; then + say "building Rust primitive workspace (8 crates, cargo build --release)" + if ! ( cd "$AGENTS_DIR/_primitives/_rust" && cargo build --workspace --release --offline ) 2>/tmp/keiseikit-primitives-offline.log; then + say " offline build failed — fetching deps from crates.io" + if ! ( cd "$AGENTS_DIR/_primitives/_rust" && cargo build --workspace --release ); then + warn "Rust primitive workspace build failed; fleet still functional without binaries" + warn " see log: /tmp/keiseikit-primitives-offline.log" + fi + fi + # Report which binaries built successfully. + built=0 + for bin in kei-ledger kei-migrate kei-changelog ssh-check firewall-diff mock-render visual-diff tokens-sync; do + if [[ -x "$AGENTS_DIR/_primitives/_rust/target/release/$bin" ]]; then + built=$((built+1)) + fi + done + say " $built / 8 Rust primitive binaries available" +fi + # --- generate .md agents in-place ------------------------------------------ say "generating agent .md files (--in-place)" AGENT_ROOT="$AGENTS_DIR" "$AGENTS_DIR/_assembler/target/release/assemble" --in-place @@ -397,8 +463,9 @@ else NEXT STEP: merge settings-snippet.json into ~/.claude/settings.json ========================================================================== - KeiSeiKit ships 4 hooks (assemble-agents, assemble-validate, no-hand-edit, tomd-preread). - To activate them, merge entries from: + KeiSeiKit ships 6 hooks (assemble-agents, assemble-validate, no-hand-edit, + tomd-preread, agent-fork-logger, site-wysiwyd-check). To activate them, + merge entries from: $KIT_DIR/settings-snippet.json into your: $SETTINGS_FILE diff --git a/settings-snippet.json b/settings-snippet.json index 84f1317..178924b 100644 --- a/settings-snippet.json +++ b/settings-snippet.json @@ -1,5 +1,5 @@ { - "_comment": "Merge these entries into your ~/.claude/settings.json under the matching keys. If you already have PostToolUse/PreToolUse arrays, append the objects below to them instead of overwriting.", + "_comment": "Merge these entries into your ~/.claude/settings.json under the matching keys. If you already have PostToolUse/PreToolUse arrays, append the objects below to them instead of overwriting. install.sh --activate-hooks automates the merge and de-dupes by hooks[].command.", "hooks": { "PostToolUse": [ { @@ -8,6 +8,11 @@ { "type": "command", "command": "~/.claude/hooks/assemble-agents.sh" + }, + { + "type": "command", + "command": "~/.claude/hooks/site-wysiwyd-check.sh", + "statusMessage": "site-wysiwyd drift check..." } ] } @@ -40,6 +45,16 @@ "statusMessage": "tomd pre-read auto-convert check..." } ] + }, + { + "matcher": "Agent", + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/agent-fork-logger.sh", + "statusMessage": "agent-fork-logger (RULE 0.12)..." + } + ] } ] } diff --git a/skills/compose-solution/phase-3-prior-art.md b/skills/compose-solution/phase-3-prior-art.md index fdd99f7..c83ec8b 100644 --- a/skills/compose-solution/phase-3-prior-art.md +++ b/skills/compose-solution/phase-3-prior-art.md @@ -8,7 +8,14 @@ For EACH component from Phase 2, run three independent searches in parallel ```bash # Replace with the component's 3-5 distinctive keywords as an # ERE alternation like (foo|bar|baz). -grep -rinlE '' _blocks/ _manifests/ _primitives/ skills/ _bridges/ hooks/ 2>/dev/null +# The 7 paths cover: behavioral blocks, agent manifests, shell primitives, +# Rust primitive crates (source + Cargo.toml), all skills, cross-tool +# bridges, and enforced hooks. grep -r recurses, so _primitives/ catches +# both *.sh and _rust//src/*.rs — but _primitives/_rust/ is listed +# explicitly for discoverability when someone reads this file. +grep -rinlE '' \ + _blocks/ _manifests/ _primitives/ _primitives/_rust/ \ + skills/ _bridges/ hooks/ 2>/dev/null ``` ## 3b — Personal bundle reuse (conditional, skip on missing) diff --git a/skills/compose-solution/phase-5-architecture.md b/skills/compose-solution/phase-5-architecture.md index a938627..6c6706f 100644 --- a/skills/compose-solution/phase-5-architecture.md +++ b/skills/compose-solution/phase-5-architecture.md @@ -19,6 +19,25 @@ XLSX / PPTX / CSV), reference the `tomd` primitive over rewrite". The PreToolUse(Read) hook `tomd-preread.sh` already redirects Claude to the converted markdown transparently. +### Pipeline / primitive cross-refs (reuse before rewrite) + +If the user's task maps onto an existing hub-and-spoke pipeline, recommend +it instead of composing from scratch. Each pipeline is itself discoverable +via Phase 3 grep, but surface it explicitly so the user sees the option: + +- VM / server provisioning → `/vm-provision` + `ssh-check` + `firewall-diff` +- Database schema design → `/schema-design` + `kei-migrate` (PG/SQLite/MySQL) +- Metrics + logs observability → `/observability-setup` + `metrics-scrape` + `log-ship` +- Authentication / session / JWT / OAuth → `/auth-setup` +- CI/CD workflow scaffolding → `/ci-scaffold` + `kei-ci-lint` +- REST / GraphQL / gRPC API contract → `/api-design` +- Doc site + changelog automation → `/docs-scaffold` + `kei-changelog` +- Test matrix (unit / integration / e2e / visual) → `/test-matrix` +- Frontend site / UI WYSIWYD loop → `/site-create` + `mock-render` + `visual-diff` + `tokens-sync` +- Multi-agent project bootstrap → `/new-project` + `kei-ledger` (RULE 0.12 fork tracking) + +One-line per reference, click-discoverable, no duplication of pipeline logic. + ## 5b — What is UNNECESSARY? For each block listed, justify why it's in. If a block can be removed