Merge branch 'integration/v0.8.0-globals' — README/install/settings/compose-solution refresh for v0.8.0 surface
This commit is contained in:
Parfii-bot
commit
2796df2bf3
6 changed files with 275 additions and 39 deletions
117
README.md
117
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.
|
||||
|
||||
|
|
|
|||
75
hooks/site-wysiwyd-check.sh
Executable file
75
hooks/site-wysiwyd-check.sh
Executable file
|
|
@ -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
|
||||
77
install.sh
77
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
|
||||
|
|
|
|||
|
|
@ -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)..."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -8,7 +8,14 @@ For EACH component from Phase 2, run three independent searches in parallel
|
|||
```bash
|
||||
# Replace <keywords> with the component's 3-5 distinctive keywords as an
|
||||
# ERE alternation like (foo|bar|baz).
|
||||
grep -rinlE '<keywords>' _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/<crate>/src/*.rs — but _primitives/_rust/ is listed
|
||||
# explicitly for discoverability when someone reads this file.
|
||||
grep -rinlE '<keywords>' \
|
||||
_blocks/ _manifests/ _primitives/ _primitives/_rust/ \
|
||||
skills/ _bridges/ hooks/ 2>/dev/null
|
||||
```
|
||||
|
||||
## 3b — Personal bundle reuse (conditional, skip on missing)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue