docs(readme): install profiles table + migration note for v0.9.0
This commit is contained in:
Parfii-bot
parent
67d6f5a15a
commit
c5078f8918
1 changed files with 53 additions and 13 deletions
66
README.md
66
README.md
|
|
@ -6,33 +6,73 @@ The kit is MIT-licensed and fully generic — install it on a fresh machine and
|
|||
|
||||
## Prerequisites
|
||||
|
||||
- **Rust** (stable toolchain) — the assembler + 8 primitive crates are a Cargo workspace
|
||||
**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
|
||||
- **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
|
||||
|
||||
**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
|
||||
|
||||
```bash
|
||||
git clone <your-fork-of-this-repo> KeiSeiKit
|
||||
cd KeiSeiKit
|
||||
./install.sh
|
||||
./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, 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` 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
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
|
@ -43,8 +83,8 @@ After install, the only remaining step is merging `settings-snippet.json` into y
|
|||
| 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) | 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` |
|
||||
| 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue