docs(readme): v0.8.0 — 73 blocks / 34 skills / 21 primitives / 6 hooks / 11 bridges + pipelines section

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 `<dir>.bak-TIMESTAMP/` (or, for shared hook files, to `<file>.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 `<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`, ... |
+| 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/<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
 
 ```
@@ -76,12 +137,14 @@ Then one free-text prompt for slug + description + path + gotchas. The wizard co
   Block edit (_blocks/<block>.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 `<!-- 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.
+- **`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/<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.