aiblueprint-cli 1.4.107 → 1.4.109

package/agents-config/skills/audit-skills/SKILL.md

@@ -5,75 +5,16 @@ argument-hint: "[audit|fix] [project-root]"
 disable-model-invocation: true
 ---
 
-# Audit Skills
-
-Audit skill discovery cost and placement from current files plus observable Codex and Claude session evidence. Treat missing telemetry as uncertainty, not proof that a skill has never been useful.
-
-## Invocation guard
-
-Proceed only when the current user message explicitly invokes `$audit-skills`.
-
-- `$audit-skills audit [project-root]`: produce a read-only audit. This is the default.
-- `$audit-skills fix [project-root]`: audit first, then apply only high-confidence corrections.
-
-Resolve `project-root` from the argument or current repository. Preserve unrelated dirty changes and record Git status for every modified repository.
-
-## Audit
-
-Run the deterministic inventory as a bounded job:
+Proceed only on an explicit `$audit-skills` invocation. Default `audit`; `fix` applies only high-confidence corrections after the ledger exists. Resolve `project-root` from the argument or current repo. Preserve unrelated dirty changes.
 
 ```bash
-bun ~/.agents/skills/audit-skills/scripts/audit-skills.mjs \
-  --project "$PWD" \
-  --format markdown
+bun ~/.agents/skills/audit-skills/scripts/audit-skills.mjs --project "$PWD" --format markdown
 ```
 
-The script inventories global `~/.agents/skills` and `<project>/.agents/skills`, then scans observable Codex and Claude histories for:
-
-- explicit user references such as `$skill-name` or `/skill-name`;
-- Claude `Skill` tool calls;
-- agent reads of a matching `SKILL.md`;
-- working directories associated with observed use;
-- Claude `disable-model-invocation` and Codex `policy.allow_implicit_invocation` controls;
-- name collisions and hardcoded project-root references.
-
-Report these evidence classes separately:
-
-- `OBSERVED_USER`: explicitly named by a user in scanned history;
-- `OBSERVED_MODEL`: loaded or invoked by an agent in scanned history;
-- `UNOBSERVED`: no matching evidence in scanned sources;
-- `EXPLICIT_ONLY`: protected for both Claude and Codex;
-- `INVOCATION_MISMATCH`: protected on only one platform;
-- `LOCALITY_CANDIDATE`: global skill with a project-specific runtime dependency or at least two observed uses confined to one project;
-- `NAME_COLLISION`: same skill name discovered globally and locally.
-
-Include scan coverage and limitations. Cursor ACP stores are opaque blobs and are not counted unless a reliable parser becomes available. Never label `UNOBSERVED` as “never used” without naming the scanned time range and sources.
-
-## Fix
-
-Apply changes only after the audit ledger exists.
-
-Safe automatic corrections:
-
-1. Mirror an existing explicit-only decision across platforms: add `disable-model-invocation: true` when Codex already blocks implicit invocation, or add `policy.allow_implicit_invocation: false` when Claude already blocks it.
-2. Mark a skill explicit-only when its own instructions already require direct user invocation but one or both platform controls are missing.
-3. Repair metadata made stale by a move or rename.
-
-Require explicit user direction or a project-specific runtime dependency before moving a skill between scopes. Multiple uses confined to one project justify review, not automatic relocation; a single observed use is insufficient evidence.
-
-When moving a skill:
-
-1. copy the complete directory, including scripts, references, assets, and `agents/openai.yaml`;
-2. rewrite absolute self-paths and dependencies to their new canonical locations;
-3. validate the destination before removing the source;
-4. use `trash` for source removal;
-5. search all skill roots and plugin/profile metadata for stale references;
-6. confirm the name is discovered exactly once in the intended scope.
-
-For unobserved skills, recommend rather than mutate unless their own text clearly establishes user-only intent. Rarely used incident, security, recovery, and migration skills remain protected from usage-only pruning.
+Report every inventoried skill with scan coverage and one evidence class: `OBSERVED_USER`, `OBSERVED_MODEL`, `UNOBSERVED`, `EXPLICIT_ONLY`, `INVOCATION_MISMATCH`, `LOCALITY_CANDIDATE`, `NAME_COLLISION`. Cursor ACP stores are opaque. Do not label `UNOBSERVED` as never used without naming the scanned range.
 
-## Completion criteria
+Safe automatic fixes: mirror an existing explicit-only decision across Claude/Codex; add missing explicit-only controls when the skill text already requires direct invocation; repair stale move/rename metadata. Move a skill between scopes only with explicit user direction or a project-specific runtime dependency. Copy the full directory, rewrite self-paths, validate, `trash` the source, then confirm the name is discovered once.
 
-Complete an audit only when every inventoried skill has a row, scan coverage is reported, and every recommendation cites static or usage evidence.
+Recommend rather than mutate unobserved skills. Protect incident, security, recovery, and migration skills from usage-only pruning.
 
-Complete a fix only when touched skills validate, moved dependencies resolve, unintended duplicate discovery is absent, and final Git status distinguishes pre-existing changes from this run.
+Done when every skill has a row, every recommendation cites evidence, and — on `fix` — touched skills validate and Git status distinguishes this run.

package/agents-config/skills/environments-manager/SKILL.md

@@ -1,195 +1,27 @@
 ---
 name: environments-manager
 description: Set up per-worktree environments for Claude Code, Cursor, or Codex. Use for worktree-ready repos, IDE environment config, worktree-up/down scripts, or dev.sh wiring.
-disable-model-invocation: false
-allow_implicit_invocation: true
+disable-model-invocation: true
+user-invocable: true
 ---
 
-# Environments Manager
+Ask before writing. Use the host's question UI. Shared logic lives in `scripts/*.sh`; IDE configs only point at those files. Read a matching `examples/` file before writing, then adapt.
 
-Set up per-worktree environments so a fresh worktree is ready to run: env files copied, dependencies installed, optional data services isolated or seeded, generated code refreshed, and common commands exposed through the selected IDE. Supports Claude Code, Cursor, and Codex. The shared scripts are the same on every IDE; only the config file that points at them differs.
+1. Ask what a fresh worktree should do (multi-select): copy ignored env files; install deps; isolate or seed a data backend; run codegen. Capture extra project steps in one follow-up.
+2. Ask the backend. PostgreSQL → [postgresql.md](references/postgresql.md). Convex → [convex.md](references/convex.md). None → skip isolation. Any other backend: research official docs and an in-repo example; do not guess CLI flags; summarize before editing.
+3. Ask which IDEs to wire (Claude Code, Cursor, Codex). Generate `scripts/` once. Then load [claude.md](references/claude.md), [cursor.md](references/cursor.md), and/or [codex.md](references/codex.md) for linking config only.
 
-Keep this skill database-agnostic. The main flow decides what needs to happen; database-specific implementation details live in references and should be loaded only when that backend is relevant.
+Required files: `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, `scripts/dev.sh` (all must end in `.sh`). Put them on the source checkout, not only the current worktree.
 
-## Interactive Flow
+Resolve paths as `WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"` and `SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}"`. Claude: use `WorktreeCreate`, never `SessionStart`; the wrapper adds the worktree then runs `worktree-up.sh` with `ROOT_WORKTREE_PATH` — see [claude.md](references/claude.md). Hook wrappers must survive a missing `/dev/tty`, a wrong default Node version, and CLI prompts.
 
-This skill is interactive. Ask the user the questions below before writing anything. Use whichever interactive question mechanism the host harness provides. Do not assume answers.
+`worktree-up.sh` is idempotent: `set -euo pipefail`, cd to the worktree, then the selected steps in order. Prefer `.worktreeinclude` for Claude env copy. Detect the lockfile for install. Read resource names from env/config or setup metadata; never invent them from branch names. Provide a reset escape hatch via `<PROJECT>_RESET_<RESOURCE>=1`.
 
-### Step 1: What should happen in a fresh worktree?
+`worktree-down.sh` cleans only resources this setup created. Missing tools: print one line and exit 0.
 
-Ask the user what the setup script should do, as a multi-select. The first option is the default-on baseline; the rest are additive opt-ins:
+`dev.sh` picks a free port from `${DEV_PORT_START:-3910}`. Never hardcode a port.
 
-| Option | What it adds to `scripts/worktree-up.sh` |
-| :--- | :--- |
-| Copy ignored env files from the source checkout | Copy `.env`, `.env.local`, `.env.development.local` when the source has them and the worktree does not. For Claude Code, prefer `.worktreeinclude` when possible. |
-| Install dependencies | `pnpm install`, `bun install`, `yarn install`, or `npm install` based on lockfile. |
-| Isolate or seed a data backend | Load the backend reference when it exists. Otherwise use researcher agents to discover the project's backend, docs, and current best setup pattern before writing scripts. |
-| Run codegen | Project-specific codegen such as Prisma, Drizzle, Convex, generated types, or SDK generation. |
-
-If the user has project-specific steps such as seed data, S3/R2 sync, local services, webhook tunnels, fixture generation, or env cloning, ask one follow-up free-form question to capture them.
-
-### Step 2: Which data backend, if any?
-
-Ask which backend needs worktree isolation or seeding. Use the answer to decide which reference to load:
-
-| Backend | Action |
-| :--- | :--- |
-| None | Keep setup to env copy, install, codegen, and dev scripts. |
-| PostgreSQL | Load `references/postgresql.md`. |
-| Convex | Load `references/convex.md`. |
-| Other SQL or non-SQL backend | Use researcher agents to inspect the repo, official docs, and current CLI behavior. Then write a narrow project-specific approach instead of adapting PostgreSQL or Convex by analogy. |
-
-For unknown backends, do not guess commands, reset behavior, file formats, import/export semantics, or production-safety flags. Ask researcher agents to find the official docs and at least one in-repo example or closely matching project pattern. Summarize the discovered approach before editing scripts.
-
-### Step 3: Which IDEs should be wired up?
-
-Ask a multi-select with options: Claude Code, Cursor, Codex. The user can pick any combination. Generate the shared `scripts/` directory once.
-
-### Step 4: Apply each selected IDE
-
-For each selected IDE, read the matching reference file and apply only its linking config. Do not duplicate script logic in IDE config; the IDE config points at `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh`.
-
-- Claude Code -> load `references/claude.md`
-- Cursor -> load `references/cursor.md`
-- Codex -> load `references/codex.md`
-
-## Shared Shape
-
-Every project that uses this skill ends up with:
-
-```text
-scripts/
-├── worktree-up.sh        # idempotent setup
-├── worktree-down.sh      # cleanup before worktree teardown
-├── dev.sh                # start dev server on a free port
-└── (project-specific helpers, all *.sh)
-```
-
-Plus one or more IDE config files. The IDE config is thin; all logic lives in `scripts/`.
-
-Naming convention: every generated script MUST end in `.sh`. No bare `worktree-up`, no `dev`. IDE configs reference scripts by full filename (`scripts/worktree-up.sh`, not `scripts/worktree-up`). This is enforced in every reference file and example.
-
-## Environment Variable Cascade
-
-Each IDE exposes different variables. The shared scripts accept all of them, in this priority:
-
-```bash
-WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
-SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}"
-```
-
-| Platform | Worktree path | Source checkout path | Setup trigger |
-| :--- | :--- | :--- | :--- |
-| Codex | `$CODEX_WORKTREE_PATH` | `$CODEX_SOURCE_TREE_PATH` | `[setup] script` in TOML, runs once per worktree. |
-| Cursor | `pwd` inside worktree | `$ROOT_WORKTREE_PATH` | `setup-worktree-unix` in JSON, runs once per worktree. |
-| Claude | `pwd` inside worktree after wrapper `cd` | `$CLAUDE_PROJECT_DIR` from the hook, re-exported as `ROOT_WORKTREE_PATH` by the wrapper | `WorktreeCreate` hook, runs once per worktree. |
-
-Important about Claude Code: do not use `SessionStart` for setup; it fires every session. Use the `WorktreeCreate` hook, which fires once when `claude --worktree` creates the worktree. The Claude wrapper script (`scripts/claude-worktree-create.sh`) is responsible for calling `git worktree add` itself, then handing off to `scripts/worktree-up.sh` inside the new worktree with `ROOT_WORKTREE_PATH` set. See `references/claude.md`.
-
-If no env var yields a source checkout, fall back to a project-specific absolute path only when you can infer it confidently. Otherwise ask the user during Step 1.
-
-## `scripts/worktree-up.sh`
-
-Setup must be idempotent: reruns are safe. Build the script from the user's Step 1 selections and any backend reference loaded in Step 2. Required behavior in order:
-
-1. `set -euo pipefail`.
-2. Resolve `WORKTREE_PATH` and `SOURCE_PATH`.
-3. `cd "$WORKTREE_PATH"`.
-4. If env copying was selected, copy `.env`, `.env.local`, `.env.development.local` only when the source has them and the worktree does not.
-5. If dependency install was selected, detect the lockfile and run the matching install.
-6. If backend isolation/seeding was selected, apply the backend reference or the researched project-specific approach.
-7. If codegen was selected, run the project's codegen command.
-8. Append any free-form project-specific steps from Step 1.
-
-Base template, before backend-specific additions:
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
-SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-$HOME/Developer/projects/<repo>}}"
-
-cd "$WORKTREE_PATH"
-
-# Copy ignored env files.
-# NOTE for Claude Code users: .worktreeinclude handles this natively. Prefer it
-# over the cp loop when the project uses Claude's --worktree.
-for f in .env .env.local .env.development.local; do
-  if [[ -f "$SOURCE_PATH/$f" && ! -f "$WORKTREE_PATH/$f" ]]; then
-    cp "$SOURCE_PATH/$f" "$WORKTREE_PATH/$f"
-    echo "copied $f"
-  fi
-done
-
-# Install deps.
-if   [[ -f pnpm-lock.yaml ]]; then pnpm install
-elif [[ -f bun.lock || -f bun.lockb ]]; then bun install
-elif [[ -f yarn.lock ]]; then yarn install
-elif [[ -f package-lock.json ]]; then npm install
-fi
-
-# Backend isolation/seeding and codegen go here.
-```
-
-## `scripts/worktree-down.sh`
-
-Cleanup runs before the IDE destroys the worktree. Keep cleanup scoped to resources that the setup script created or selected explicitly.
-
-1. `set -euo pipefail`.
-2. Resolve `WORKTREE_PATH`.
-3. `cd "$WORKTREE_PATH"`.
-4. Run backend-specific cleanup only when the loaded backend reference requires it.
-5. Remove copied local env files only if that is appropriate for the project.
-6. If required tools or env files are missing, print one short message and exit 0.
-
-Never guess resource names from branch names. Read names from the worktree's env/config files or from deterministic setup metadata created by `worktree-up.sh`.
-
-## `scripts/dev.sh`
-
-Pick a free port so multiple worktrees can run in parallel.
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
-cd "$WORKTREE_PATH"
-
-port="${DEV_PORT_START:-3910}"
-while lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
-  port=$((port + 1))
-done
-
-echo "Starting app on http://localhost:$port"
-exec pnpm dev -p "$port"  # adjust for the project package manager
-```
-
-## Standard Actions
-
-Every project should expose these four actions through the IDE's own mechanism:
-
-| Action | Command (typical) |
-| :--- | :--- |
-| Dev | `scripts/dev.sh` |
-| Typecheck | `pnpm ts` / `bun run typecheck` |
-| Unit tests | `pnpm test:ci` / `bun test` |
-| Lint | `pnpm lint:ci` / `bun run lint` |
-
-Add `E2E` as an action only if the suite is cheap enough to run interactively.
-
-## Universal Guardrails
-
-- Never commit secrets. Copying ignored env files into a local worktree is fine; logging them is not.
-- Never put fragile multi-line shell programs inside an IDE config file. Keep all logic in `scripts/`; the IDE config just calls those scripts.
-- Never hardcode a dev port. Pick a free one starting from `${DEV_PORT_START:-3910}`.
-- Setup must be idempotent. Provide a reset escape hatch for stateful resources via env var (`<PROJECT>_RESET_<RESOURCE>=1`).
-- Print resource names and redacted hosts only.
-- The scripts and IDE config must live on the source checkout / main branch, not only the current worktree, or future worktrees will have nothing to copy.
-- Never destroy or import from production data by default. Any setup step that exports from a shared source and replays into a worktree must reject production-looking refs unless the user explicitly approved an override env var.
-- Hook wrappers must survive a missing `/dev/tty`, a wrong default Node version, and CLI prompts. See `references/claude.md` -> "Hook Robustness" for the concrete fixes.
-
-Use this production-source guard in backend references or project-specific helpers:
+Never commit or log secrets. Never embed multi-line programs in IDE config. Never destroy or import production data unless the user set an override env var. Put this guard in any import/replay helper:
 
 ```bash
 assert_non_prod_ref() {
@@ -202,62 +34,6 @@ assert_non_prod_ref() {
 }
 ```
 
-## Verification
+Expose Dev, typecheck, unit tests, and lint through the IDE; add E2E only if cheap.
 
-After generating files:
-
-```bash
-bash -n scripts/worktree-up.sh scripts/worktree-down.sh scripts/dev.sh
-git status --short
-```
-
-If Python 3.11+ is available, validate generated TOML:
-
-```bash
-python3 - <<'PY'
-import tomllib
-with open(".codex/environments/environment.toml", "rb") as f:
-    tomllib.load(f)
-PY
-```
-
-For JSON configs:
-
-```bash
-python3 -c "import json; json.load(open('.cursor/worktrees.json'))"
-python3 -c "import json; json.load(open('.claude/settings.json'))"
-```
-
-## References
-
-Load only the references relevant to the selected backend and IDE:
-
-- `references/postgresql.md` - PostgreSQL isolation, reset, and cleanup.
-- `references/convex.md` - Convex local/cloud deployments, allowlisted seeding, env cloning, and cleanup.
-- `references/claude.md` - Claude Code WorktreeCreate/WorktreeRemove wiring.
-- `references/cursor.md` - Cursor worktree setup wiring.
-- `references/codex.md` - Codex local environment TOML.
-
-## Examples
-
-Working examples live under `examples/`. Read the relevant example before writing files into a real project, but do not copy verbatim. The user's selections, backend reference, and project conventions determine which sections survive.
-
-```text
-examples/
-├── scripts/
-│   ├── worktree-up.sh
-│   ├── worktree-down.sh
-│   ├── dev.sh
-│   ├── convex-selective-seed.sh
-│   ├── claude-worktree-create.sh
-│   └── claude-worktree-remove.sh
-├── claude/
-│   ├── .worktreeinclude
-│   ├── settings.json
-│   └── commands/
-├── cursor/
-│   └── worktrees.json
-└── codex/
-    └── environments/
-        └── environment.toml
-```
+After writing: `bash -n` the three scripts, `git status --short`, and parse generated TOML/JSON when those files exist.

package/agents-config/skills/grill-me/SKILL.md

@@ -4,28 +4,14 @@ description: Grill the user in rapid batches to sharpen a plan, decision, or ide
 disable-model-invocation: true
 ---
 
-# Grill Me
-
 Stress-test the user's thinking until both sides share a precise, actionable understanding.
 
-## Interview loop
-
-1. Inspect the available environment first. Resolve discoverable facts through files, tools, documentation, or other in-scope evidence instead of asking the user.
-2. Open the session by recommending voice input: tell the user that answering with the microphone is fastest, and that short answers keyed `1` through `10` are enough.
-3. Ask exactly 10 numbered questions in one batch. Prioritize the highest-leverage unresolved decisions and order them so earlier questions clarify later ones.
-4. For every question, include a concise **Recommended answer** based on current evidence. Make the tradeoff or consequence clear enough for the user to accept, reject, or amend it quickly.
-5. Invite one grouped reply covering `1` through `10`. Accept terse answers, corrections, skipped items, or a blanket acceptance of the recommendations.
-6. After the reply, summarize what is established, call out contradictions or missing dependencies, and investigate any newly discoverable facts.
-7. Ask the next batch of 10 questions. Continue until the important branches of the decision tree are resolved. If fewer than 10 meaningful decisions remain, ask only those remaining; never add filler questions to reach 10.
-8. Present the final shared understanding as a compact decision brief: goal, scope, constraints, chosen approach, rejected alternatives, risks, and acceptance criteria.
-9. Ask for explicit confirmation that the brief is correct before acting on it.
-
-## Question quality
-
-- Ask decisions only the user can make; investigate facts yourself.
-- Challenge assumptions and compare credible alternatives instead of merely collecting preferences.
-- Keep each question independently answerable and concise enough for a spoken response.
-- Do not repeat settled questions unless new evidence invalidates the earlier answer.
-- Match the user's language.
+1. Resolve discoverable facts from the environment. Ask only decisions the user can make.
+2. Recommend voice input: microphone is fastest; short answers keyed `1` through `10` are enough.
+3. Ask exactly 10 numbered questions in one batch. Lead with the highest-leverage unresolved decisions. Include a concise **Recommended answer** on every question.
+4. Invite one grouped reply. Accept terse answers, skips, or blanket acceptance of the recommendations.
+5. Summarize what is established, investigate new facts, then ask the next batch. If fewer than 10 decisions remain, ask only those.
+6. Present a compact decision brief: goal, scope, constraints, chosen approach, rejected alternatives, risks, and acceptance criteria.
+7. Get explicit confirmation before acting on it.
 
-Do not implement the plan until the user confirms the final decision brief.
+Challenge assumptions. Compare credible alternatives. Match the user's language. Do not implement until the brief is confirmed.

package/agents-config/skills/hooks-manager/SKILL.md

@@ -4,61 +4,15 @@ description: Create, edit, configure, and debug hooks for Claude Code, Codex, an
 disable-model-invocation: true
 ---
 
-# Hooks Manager
+Configure Claude Code, Codex, and Cursor hooks as event-driven commands or prompts. Treat platform syntax as distinct.
 
-Configure Claude Code, Codex, and Cursor hooks as event-driven commands or prompts. Use hooks for validation, logging, formatting, notifications, context injection, and bounded completion checks. Treat platform syntax and capabilities as distinct; do not copy a Claude configuration into Codex or Cursor without adapting it.
+1. Identify the platform and load [router.md](references/router.md).
+2. Load the platform file: [claude-code.md](references/claude-code.md), [codex.md](references/codex.md), or [cursor.md](references/cursor.md).
+3. Pick the scope, file path, lifecycle event, and a command hook (deterministic) or prompt hook (reasoning, if supported).
+4. Validate the native config and run the platform smoke check.
 
-## Quick workflow
+Across agents, keep one portable script plus a small adapter per platform. Report unsupported features.
 
-1. Identify the target platform and load `references/router.md`.
-2. Load the platform reference: `claude-code.md`, `codex.md`, or `cursor.md`.
-3. Identify the scope and file path for that platform.
-4. Select a supported lifecycle event and adapt the shared payload/decision contract.
-5. Choose a command hook for deterministic shell logic, or a prompt hook when natural-language reasoning is required and the platform supports it.
-6. Validate the native config and run the platform-specific smoke check.
+Load as needed: [hook-types.md](references/hook-types.md), [command-vs-prompt.md](references/command-vs-prompt.md), [matchers.md](references/matchers.md), [input-output-schemas.md](references/input-output-schemas.md), [examples.md](references/examples.md), [troubleshooting.md](references/troubleshooting.md).
 
-## Claude-shaped example
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          { "type": "command", "command": "./.claude/hooks/check.sh", "timeout": 30000 }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Command hooks receive JSON on stdin and may return JSON on stdout. Prompt hooks receive `#$ARGUMENTS` and should return a structured decision. Blocking hooks use `{"decision":"block","reason":"..."}`; non-blocking hooks may return a `systemMessage`.
-
-## Safety requirements
-
-- Check `stop_hook_active` in `Stop` and `SubagentStop` hooks to prevent recursive blocking.
-- Set reasonable timeouts, especially for external commands.
-- Use `$CLAUDE_PROJECT_DIR` or another trusted absolute path for scripts.
-- Validate hook JSON with `jq` before relying on it.
-- Keep blocking rules selective so normal work is not accidentally interrupted.
-- Ensure referenced scripts are executable.
-
-## Shared router
-
-When the user asks for a hook that should work across agents, define one portable script with a small adapter per platform. Keep platform-specific event names, input fields, output decisions, exit codes, timeouts, and config paths in the references rather than pretending the formats are identical. Report unsupported features explicitly.
-
-## References
-
-- `references/router.md`: select a platform, map shared lifecycle intent, and avoid unsupported assumptions.
-- `references/claude-code.md`: Claude settings, events, handlers, and `/hooks` verification.
-- `references/codex.md`: Codex config layers, `hooks.json`, trust, and restart/worktree caveats.
-- `references/cursor.md`: Cursor `.cursor/hooks.json`, hook scripts, and native response mapping.
-- `references/research-sources.md`: first-party documentation sources and refresh policy.
-- `references/hook-types.md`: shared event concepts, input/output, and blocking behavior.
-- `references/command-vs-prompt.md`: choose command versus prompt hooks.
-- `references/matchers.md`: regex and MCP matcher patterns.
-- `references/input-output-schemas.md`: event schemas and response fields.
-- `references/examples.md`: notifications, logging, formatting, tests, and safety examples.
-- `references/troubleshooting.md`: debug, JSON, matcher, permission, and timeout checks.
+Check `stop_hook_active` on Stop/SubagentStop. Use trusted absolute paths, timeouts, and `jq` validation. Keep blocking rules selective.