Advisory hook (RULE 0.12). Reads Agent tool_input JSON from stdin, hashes
the prompt (SHA-256 first 16), derives agent id and branch per isolation
mode, emits kei-ledger fork row.
NEVER blocks: every exit path is exit 0. Missing jq / kei-ledger / git
= silent no-op. Advisory because isolation=false trivial agents are
expected to slip through (RULE 0.12 Exceptions 1-2).
Constructor Pattern: 51 LOC, POSIX sh, chmod +x.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hub-and-spoke skill that converts "I need auth for app X" into a
reviewable plan across 5 phases: intake (flows/stack/storage/MFA),
identity-provider pick + env scaffold, session strategy + cookies,
authorization model + permission matrix, and threats + mitigations.
- 8 AskUserQuestion calls total (≥6 hub-and-spoke contract; 4 in Phase 1
+ 1 each in Phases 2–5).
- Reads all four _blocks/auth-*.md; never writes production code or
secret values.
- RULE 0.8 (Secrets SSoT): emits env VARIABLE NAMES only; storage path
is secrets/auth.env per domain-has-secrets.md.
- Constructor Pattern: 6 files, largest 115 LOC (<200 limit).
- Fail-closed default + NO DOWNGRADE on unsafe combinations
(passkey-only without recovery → return recovery-path options, not
"not supported").
Evidence grade [E2] — pipeline mirrors OWASP ASVS v4.0.3 chapters 2–4.
Single binary, three backends (Postgres/SQLite/MySQL) autodetected
from DATABASE_URL scheme. Sequential .sql migrations tracked in
_kei_migrations with SHA-256 checksums.
Commands:
kei-migrate up — apply pending
kei-migrate down [n] — revert last N (requires .down.sql)
kei-migrate status — list applied vs pending
kei-migrate create <name> — scaffold up+down pair with UTC ts
Constructor Pattern: 10 source files, all <90 LOC, functions <30 LOC.
Deps: sqlx 0.8 (any+postgres+sqlite+mysql, rustls), clap 4, chrono,
sha2, anyhow, tokio.
Tests: 9/9 passing (cargo test, SQLite backend).
Clippy clean: cargo clippy --all-targets -- -D warnings.
Safety features:
- checksum drift detection on applied migrations
- IRREVERSIBLE marker blocks down-revert
- duplicate version detection at scan time
- each migration in its own transaction
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds four behavioural blocks for testing paradigms beyond unit tests
(test-gen already covers unit-test generation):
- test-fuzz.md — cargo-fuzz/hypothesis/fast-check corpus + triage + CI
- test-property.md — proptest/hypothesis/fast-check invariants + shrinking
- test-load.md — k6/vegeta/oha/hyperfine baseline→profile→fix loop + SLO
- test-e2e.md — Playwright page-objects + trace viewer + flake policy
Each block 32-53 LOC (within 60-LOC block cap). Single-concern,
composable via _manifests/*.toml like any other _blocks/*.md.
Tooling cited at [E4] based on official docs; version pinning deferred
to consumers.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- L1: install.sh post-install banners '~14 generated agents' → '12 generated agents'
(both the activated-path and the manual-merge-path copies).
- L2: skills/compose-solution/SKILL.md handoff reference '14 kit agents' → '12 kit agents'.
- L3: README /new-agent section rephrases 'via option-pickers' to call out that
the 6 questions are grouped into multiple option-picker batches (two
AskUserQuestion calls) rather than six separate prompts.
- M1 (RULE 0.4): replace fabricated URLs 'https://example.invalid/PROJECT-D'
and 'https://…/PROJECT-D' with plain text ('user's personal CLI predecessor').
- M2: tomd-preread cache key = basename + mtime + 8-char shasum of full path,
so two files with the same basename+mtime at different paths no longer
collide. Portable shasum shim; falls back to 'nohash' if shasum absent.
- M3: install.sh --with-bridges gated on ROLLED_BACK=0 so bridges are NOT
emitted into $PWD after an ERR-trap rollback.
- M4: rollback() guards rm -rf "$orig" behind an existence check.
- M5: skills/research/SKILL.md front-matter note — role tags like
'web-researcher' / 'meta-critic' are ad-hoc prompt labels for the generic
kei-researcher subagent, NOT separate manifests. Prevents fruitless
grep in _manifests/.
- M6: README adds a 'Frontend-stack coverage gap' callout listing the
planned-but-not-shipped frameworks (React-Vite, Vue-Nuxt, SvelteKit,
Astro, Angular, plain-web).
- M7: no-hand-edit-agents.sh documents at case block that the GENERATED
marker is the SOLE source of truth — legacy unmarked .md files pass
silently by design; re-run the assembler to adopt them.
- phase-2-decompose.md: delete 'or researcher if that agent is present in the user's
global fleet' clause that silently bypassed the kei-namespace. Replace with an
explicit prefer-kei note warning that bare 'researcher' matches only the user's
personal fleet and may have divergent handoffs.
- install.sh activate_hooks(): call backup_file "$target" on the merge path
(after the 'create new' early-return) so ERR-trap rollback can restore the
pre-merge settings.json. Previously an ERR in the jq-merge or mv left no
backup pair to restore.
Smoke-test surfaced that check_deps hard-failed on missing pandoc even
for CSV / JSON / code-fence / image conversions that never call pandoc.
Pandoc is now checked lazily by need_pandoc(), invoked only from
convert_pandoc and convert_doc (the two paths that actually need it).
Matches install.sh soft-warn behavior: pandoc is opt-in for docx/pptx/
html, not a universal requirement.
Verified: tomd.sh /tmp/test.csv now returns markdown table with only
python3 + jq installed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- README.md: new 'Primitives' section between Cross-tool bridges and
Meta-composer. Explains _primitives/ vs _blocks/, lists tomd, names
the PreToolUse(Read) hook, notes /compose-solution auto-discovery
- phase-3-prior-art.md: extend grep target list to include _primitives/
- phase-5-architecture.md: one-paragraph note on referencing tomd
primitive instead of rolling custom binary-format parsing (reuse
over rewrite)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- install.sh:
- mkdir $AGENTS_DIR/_primitives
- copy *.sh + README.md from kit _primitives/ with backup_dir guard
- chmod +x for the primitive scripts
- extend hooks-copy loop to include tomd-preread.sh (skips if absent,
preserving back-compat with kits that predate the primitive)
- soft-warn (not hard-fail) if pandoc is missing — tomd primitive is
opt-in and works without pandoc for CSV/code/JSON/images
- settings-snippet.json: add PreToolUse(Read) entry for tomd-preread.sh
with statusMessage. New matcher block (no existing Read matcher).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- New _primitives/ directory, analogous to _blocks/_manifests/_bridges
- tomd.sh: standalone PDF/DOCX/XLSX/PPTX/CSV/code/image → markdown
converter (180 LOC, ported from PROJECT-D bin/keiagent-tomd)
- [tomd] error tag for KeiSeiKit style, KEISEI_TOMD_CACHE env var
- README.md: purpose + invocation + compose-solution discovery
Primitives are first-class building blocks that agents and pipelines
depend on. Installed at $HOME/.claude/agents/_primitives/ by install.sh
in a follow-up commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After merging feat/compose-solution, 3 phase files still referenced
patent-scale research / patent block suffix / sensitive IP question. Strip
those generic-kit-incompatible examples:
- phase-2-decompose.md: "patent-scale" → "deep-domain"
- phase-6-block-augment.md: "<slug>-patent" disambiguator → "<slug>-embedded"
- phase-7-assemble.md: drop sensitive IP from fields passed to new-agent wizard
Final grep for "patent" in main tree: zero hits.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Strip all patent-related tooling from the generic kit so it can ship
publicly under MIT without leaking sensitive IP. restricted-scope agents,
blocks, and skill conditionals live in the private PROJECT-E.
Deleted (5 files):
- _manifests/kei-patent-compliance.toml
- _manifests/kei-patent-researcher.toml
- _blocks/domain-sensitive IP-aware.md
- _assembler/tests/fixtures/_manifests/kei-patent-compliance.toml
- _assembler/tests/snapshots/kei-patent-compliance.snap
Cross-reference cleanup:
- 6 manifests: remove kei-patent-* handoffs and "sensitive IP" forbidden lines
- _blocks/deploy-local-only.md: drop sensitive IP rationale, keep ML weights /
offensive / kernel / client-confidential banned-public triggers
- skills/research/SKILL.md: drop patent-angle-scanner + "Patent angles" section
- skills/new-agent/SKILL.md: drop Q5 (patent), renumber Q6→Q5 Q7→Q6
- README.md: drop 2 restricted agents rows, renumber wizard questions 5-7→5-6,
update counts 34→33 blocks / 14→12 agents
- _assembler/tests/golden.rs: remove golden_patent_compliance test
- _assembler/tests/roundtrip.rs: swap kei-patent-compliance fixture to
kei-cost-guardian for double-assembly determinism test
- _assembler/tests/fixtures/_manifests/kei-researcher.toml + snapshot:
remove kei-patent-researcher handoff
Tests: 21 → 20 integration tests, all passing. Grep for "patent" in
main tree returns zero hits outside .claude/worktrees.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a Meta-composer section between Cross-tool bridges and License. The
section explains the one-paragraph intake, links to the 7-phase pipeline,
shows a hook-creation example that routes to /escalate-recurrence, and
emphasizes the Phase 6 block-augmentation feedback loop — the kit gets
smarter with every invocation, with before/after _blocks/ count reported
per session.
Adds a pure-click meta-composer that converts a free-text task description
into the right durable KeiSeiKit artefact — agent, skill, hook, rule, or
block — by composing existing primitives:
- Phase 1 intake (one free-text DESC + target-type click)
- Phase 2 wave-based decomposition (delegates to /research for heavy tasks)
- Phase 3 prior-art grep sweep across _blocks/, _manifests/, skills/,
_bridges/, hooks/ + optional PROJECT-E + external docs
- Phase 4 gap analysis (AskUserQuestion multi-select)
- Phase 5 math-first architecture proposal (derive-first, "what is
unnecessary" pass, Constructor-Pattern check)
- Phase 6 block augmentation — drafts + persists new _blocks/<slug>.md
on user click; kit gets smarter each session
- Phase 7 recipe assembly — branches by type, hands off to /new-agent
(agent) or /escalate-recurrence (hook / rule)
Split into SKILL.md (121-LOC index) + seven phase-*.md files (each <160
LOC) to stay under the 500-LOC/file Constructor-Pattern limit. Minimum 6
AskUserQuestion calls per session enforced by the pipeline; every
referenced block / skill / manifest / bridge path verified to exist on
disk before commit (RULE 0.4 — no fabricated references).
Writes only to _blocks/<slug>.md and skills/<slug>/SKILL.md;
handoffs to /new-agent and /escalate-recurrence own their own files.
- Insert Phase 8 between Phase 6 (Report) and Phase 7 (setup)
- Single AskUserQuestion with 3 options: all 11 / AGENTS.md only / skip
- On accept: invoke ~/.claude/agents/_bridges/emit.sh with the
project path from Phase 2 (optionally --only AGENTS.md)
- On skip: print the exact command the user can run later
- All paths idempotent (emit.sh skips existing files)
- Copy _bridges/ into ~/.claude/agents/_bridges/ so new-agent
skill Phase 8 can invoke the renderer from the user fleet dir
- Add --with-bridges flag: after agents/hooks/skills install,
invoke _bridges/emit.sh "$PWD" to render 11 bridge files
- Guard: if $PWD is the KeiSeiKit source repo itself (detected
via ./install.sh + ./_bridges), warn and skip — avoid
polluting the kit's own working tree
- --help prints usage block; flag parser loop supports future
--activate-hooks coexistence without refactor
- Single-concern renderer (<100 LOC per Constructor Pattern)
- Idempotent — existing files are skipped, not overwritten
- Args: <target> [name] [description]; name defaults to basename,
description defaults to first non-blank line of CLAUDE.md or
README.md, fallback "No description"
- --only <output-path> restricts emission to one file (used by
/new-agent Phase 8 "AGENTS.md only" path)
- Placeholders substituted: PROJECT_NAME, PROJECT_DESCRIPTION,
YEAR, MONTH, DATE
Caught in Phase-2 double-audit pass AFTER commits 1-5 were already
pushed: top-level _blocks/*.md contains prose handoff references to
"cost-guardian" that get composed into generated agent .md files.
These were missed by the skills/manifests sweep because blocks weren't
in the original task spec list (only fixture _blocks/ were mentioned,
and those are separate).
Impact if left unfixed: any project-specialist created via /new-agent
with Q3=Yes (paid APIs) or Q7!=None (scrapers) would compose these
blocks and emit a generated .md referencing the stale `cost-guardian`
handoff target — a dangling reference after the kei-* rename.
Files touched (10 references, all to `cost-guardian`):
- _blocks/api-apify.md (1)
- _blocks/api-elevenlabs.md (2)
- _blocks/api-fal-ai.md (2)
- _blocks/domain-paid-apis.md (2)
- _blocks/scraper-paid-tier.md (3)
Verify: cargo test -> 17/17 still green (fixture _blocks/ isolated
from top-level _blocks/, so no snapshot drift).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wizard's Phase 3 previously computed a deterministic `<slug>-specialist`
name and wrote it directly. Now:
- Phase 3 composition step states the PROPOSED default: `kei-<slug>-specialist`
(matches the KeiSeiKit kit-prefix convention introduced in commit 3039ada).
- NEW Phase 3.5: one AskUserQuestion call with three options:
1. `kei-<slug>-specialist` (default, kit convention)
2. `<slug>-specialist` (user namespace, no kei- prefix)
3. Specify custom name (free-text with strict validation:
regex ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, length 3-40, no --, no
leading/trailing dash; no auto -specialist suffix)
- Resolved value stored as FINAL_NAME and threaded through Phase 4
(manifest Write path), Phase 5 (--validate + --in-place assemble args),
and Phase 6 (report block + git-commit example).
- Phase 2 prompt updated to reflect the confirmation step.
- Invalid custom-name input re-asks instead of falling through (constructive-
only rule).
Touches only skills/new-agent/SKILL.md. The installed ~/.claude/skills/new-agent/
copy will be refreshed on the next `./install.sh` run.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Agents-overview table: 14 rows renamed to kei-<name>.
- "What you get" table examples: kei-<name> with trailing "...".
- Intro paragraph: note on kei-* namespace motivation (no collision
with user's own same-named agents).
No code/behavior change — this is pure docs alignment with the manifest
rename in commit 3039ada.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Rename 4 fixture manifests under _assembler/tests/fixtures/_manifests/
({code-implementer,cost-guardian,patent-compliance,researcher}.toml
-> kei-<name>.toml) via git mv. Copy updated top-level manifests into
fixtures so they stay byte-identical (fixtures mirror real manifests).
- Rename 4 snapshot files under _assembler/tests/snapshots/ to match
the new insta snapshot keys.
- Update snapshot bodies to reflect the kei- prefix in:
* frontmatter name field (name: kei-<n>)
* GENERATED comment (_manifests/kei-<n>.toml)
* handoff target lines
* === HEADER === REPORT header (uppercased name in output_format)
- Update test code (golden.rs, roundtrip.rs, validator_negative.rs,
determinism.rs) to use the new manifest filenames + snapshot keys.
Rust function names (e.g. golden_researcher) untouched — they are
internal identifiers, not manifest refs, and the word-boundary rule
(no "_" preceding match) correctly skipped them.
Verify:
cd _assembler && cargo test
-> 17 tests passed (0 + 3 + 4 + 2 + 2 + 6 across 6 test files)
-> Re-run produces no *.snap.new files (snapshots stable)
Regeneration path: because cargo-insta CLI is not installed on the
build host, the .snap.new files produced by the first (failing) test
run were accepted by renaming .snap.new -> .snap. Second cargo test
run passed cleanly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mechanical rename of all 14 kit-agent references in skills/*/SKILL.md.
Pattern: word-boundary match that excludes "-" on both sides, applied
longest-first so "ml-researcher" rewrites before "researcher" (avoids
the "kei-ml-kei-researcher" double-prefix trap).
skills/new-agent/SKILL.md (14 refs):
- Phase 3.3 handoff list (code-implementer/critic/validator mandatory,
cost-guardian/ml-implementer/ml-researcher/infra-implementer/
security-auditor conditional)
- Phase 3.5 role-template example (Hand off ... to code-implementer ...)
- Phase 4 manifest-template example (target = "code-implementer" etc.)
- Phase 6 report-block example ("Handoffs: code-implementer, critic, ...")
- Description-string ref on Phase 1b (cost-guardian mandatory)
skills/research/SKILL.md (5 refs):
- `critic` renamed to `kei-critic` inside backticks and bold
- Teammate-role mentions that happen to share the name
- NOTE: hyphenated compound labels like `web-researcher`, `code-explorer`,
`{component}-critic`, `meta-critic` are left untouched — they are
ad-hoc teammate-role labels, not kit-agent handoffs. The boundary rule
(no "-" immediately before the name) preserves them correctly.
Other 4 skills (debug-deep, pr-review, refactor, test-gen) have zero
kit-agent references — untouched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
