aiblueprint-cli 1.4.108 → 1.4.110

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.

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

@@ -1,204 +1,23 @@
 ---
 name: rules-manager
-description: Create, edit, and maintain AGENTS.md and .agents/rules/ — tech stack, commands, universal rules, rule index, and rule files. Use to add, modify, restructure, or optimize project rules, conventions, and constraints.
+description: Create, edit, and maintain AGENTS.md and .agents/rules/. Use when adding, modifying, restructuring, or optimizing project rules, conventions, or constraints.
 argument-hint: "[init | add <rule-name> | edit | optimize | task description]"
+disable-model-invocation: true
+user-invocable: true
 ---
 
-<core_principle>
-Rules consume tokens on every agent run. Keep them minimal, specific, and discoverable.
+Manage the two-tier rule system: the always-loaded index plus modular files. Every modular file must be linked from the index or agents will not find it.
 
-**Two-tier system:**
+Open [agents-vs-claude.md](references/agents-vs-claude.md) before choosing `AGENTS.md` + `.agents/rules/` versus `CLAUDE.md` + `.claude/rules/`, path-scoped `paths:` frontmatter, or dual-format setup. Run the same workflows against the chosen pair. Open [examples.md](references/examples.md) before writing a new rule file or index skeleton.
 
-- **AGENTS.md** — Always loaded. Acts as the **index** + universal rules.
-- **.agents/rules/\*.md** — Modular rule files for focused topics (changelog, testing, deployment, etc.).
+Never overwrite existing files without asking. Never write a rule file without confirming its content. Default new rules to a modular file (20–60 lines); put 1–2 line constraints in Universal Rules. When the user names index content (stack, commands, universal rules), edit that file in place. Write specific prohibitions. Do not add generic best practices, linter-enforced rules, or facts the agent can read from the code.
 
-**CRITICAL invariant:** Every file in `.agents/rules/` must be referenced in AGENTS.md so agents know it exists. AGENTS.md without a reference = orphaned rule = invisible to agents.
-</core_principle>
+`init`: read package manifests; if the index or rules directory exists, ask before writing; create a <40-line index with an empty Rules section and the rules directory.
 
-<file_layout>
+`add <name>`: slugify the name; `init` if no index; ask what it enforces and when it applies; write the modular file; add one index bullet whose path matches the file.
 
-```
-project-root/
-├── AGENTS.md                  # Index + universal rules (always loaded)
-└── .agents/
-    └── rules/
-        ├── changelog.md       # Rule for changelog management
-        ├── testing.md         # Rule for tests
-        └── deployment.md      # Rule for deployment
-```
+`edit`: change only the named index section; keep every modular-file link intact.
 
-**AGENTS.md must contain a `## Rules` section listing each `.agents/rules/*.md` file with a one-line description.**
-</file_layout>
+`optimize`: inventory index vs files (flag orphans and broken links); strip linter-enforced, generic, verbose, and code-derivable rules; compress to bullets; show the diff and wait. Targets: index <80 lines, each rule <60.
 
-<agents_md_template>
-Minimal AGENTS.md with rules index:
-
-```markdown
-# Project Name
-
-Short description (1-2 lines).
-
-## Tech Stack
-
-- [Non-obvious tech only]
-
-## Commands
-
-- `[dev]` - Dev server
-- `[test]` - Run tests
-
-## Rules
-
-The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
-
-- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
-- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage
-- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Deploy checklist
-
-## Universal Rules
-
-- [2-3 critical rules that apply everywhere]
-```
-
-The `## Rules` section is the index. Each bullet = one file in `.agents/rules/`. The `## Universal Rules` section holds short, project-wide constraints that don't deserve their own file.
-</agents_md_template>
-
-<rule_file_template>
-Each `.agents/rules/<name>.md` should be focused, short, and actionable.
-
-```markdown
-# [Rule Title]
-
-Short purpose statement (1 line).
-
-## When this applies
-
-- [Specific triggers - what task/context loads this rule]
-
-## Rules
-
-- [Specific, actionable rule]
-- [Another rule with example if format matters]
-
-## Example
-
-[3-5 line concrete example, only if needed]
-```
-
-**Size target:** 20-60 lines per rule file. If longer, split into multiple files.
-</rule_file_template>
-
-<writing_rules>
-**Be specific, never vague:**
-
-```
-NO: "Update changelog properly"
-YES: "Append entry to CHANGELOG.md under ## Unreleased before every PR. Format: - [type] description (#PR)"
-```
-
-**Prohibitions beat positive guidance:**
-
-```
-NO: "Try to write tests"
-YES: "NEVER merge without a passing test for the changed behavior"
-```
-
-**Emphasis hierarchy:** CRITICAL > NEVER > ALWAYS > IMPORTANT
-
-- Lead each section with the most critical rule
-- Use **bold + keyword** for non-negotiables: `**CRITICAL**: Never commit secrets`
-
-**Do NOT include:**
-
-- Generic best practices ("write clean code", "DRY", "SOLID")
-- Linter-enforced rules (ESLint, Prettier, Biome already do this)
-- Things the agent discovers from the code (file structure, framework defaults)
-- Marketing or vision statements
-- Verbose paragraphs - one line is almost always enough
-  </writing_rules>
-
-<workflows>
-
-## `/rules-manager init` - Bootstrap AGENTS.md + .agents/rules/
-
-When the argument contains `init`:
-
-1. **Detect project context** - Read `package.json` or equivalent for name, stack, scripts.
-2. **Check existing files** - If `AGENTS.md` or `.agents/rules/` already exists, read them and ASK before overwriting.
-3. **Create skeleton** - Write AGENTS.md with empty `## Rules` index, ready to populate.
-4. **Create `.agents/rules/` directory** - Empty for now. New rules added via `add` workflow.
-
-Target AGENTS.md size at init: under 40 lines.
-
-## `/rules-manager add <name>` - Add a new rule
-
-When the argument starts with `add`:
-
-1. **Confirm name** - Slugify (e.g., "changelog management" -> `changelog`). Ask user if unclear.
-2. **Read existing AGENTS.md** - Confirm it exists. If not, run `init` first.
-3. **Ask the user for rule content** - What does the rule enforce? When does it apply? Any examples?
-4. **Write `.agents/rules/<name>.md`** - Use the rule file template. Keep it 20-60 lines.
-5. **Update AGENTS.md `## Rules` section** - Add a one-line bullet pointing to the new file:
-   ```
-   - **<Title>** - [.agents/rules/<name>.md](.agents/rules/<name>.md) - <one-line purpose>
-   ```
-6. **Verify the link** - Make sure the path in AGENTS.md exactly matches the created file.
-
-**CRITICAL:** Step 5 is non-negotiable. A rule file without an index entry is invisible.
-
-## `/rules-manager edit` - Modify AGENTS.md directly
-
-When the user wants to change AGENTS.md itself rather than add a rule file — update the tech stack, commands, universal rules, project description, or restructure sections:
-
-1. **Read AGENTS.md** - Load current content.
-2. **Make the targeted edit in place** - Change only the relevant section; leave unrelated sections untouched.
-3. **Preserve the index** - If touching `## Rules`, keep every `.agents/rules/*.md` link intact.
-4. **Stay minimal** - Apply `<writing_rules>`: specific, prohibitions over guidance, no bloat.
-
-This is the default when the user references AGENTS.md content (not a rule file) — e.g. "add a command to AGENTS.md", "update the tech stack", "tighten the universal rules".
-
-## `/rules-manager optimize` - Audit and clean up
-
-When the argument contains `optimize`:
-
-1. **Inventory** - List AGENTS.md and every file in `.agents/rules/`.
-2. **Check the index** - For each file in `.agents/rules/`, verify there's a matching bullet in AGENTS.md `## Rules`. Flag missing entries.
-3. **Check for orphans** - For each AGENTS.md bullet, verify the file exists. Flag broken links.
-4. **Apply bloat removal** - For each rule file, remove:
-   - Linter-enforced rules
-   - Generic best practices
-   - Verbose explanations (compress to one line)
-   - Things derivable from code
-5. **Compress** - Paragraphs to bullets, multi-line rules to single lines.
-6. **Show diff and ask before applying.**
-
-Target sizes:
-
-- AGENTS.md: under 80 lines
-- Each rule file: under 60 lines
-
-## Default - Add a rule based on description
-
-When the argument is a free-form task (e.g., "add a rule about how we tag releases"):
-
-1. Treat as `add` with auto-derived name.
-2. Ask the user 1-2 clarifying questions if the rule scope is unclear.
-3. Follow the `add` workflow.
-   </workflows>
-
-<rules_for_this_skill>
-
-- This skill manages ALL of AGENTS.md (tech stack, commands, universal rules, index, description) and `.agents/rules/` — not just creating new rule files. Editing existing AGENTS.md content is fully in scope.
-- ALWAYS update AGENTS.md `## Rules` index when creating a file in `.agents/rules/`
-- NEVER create a rule file without confirming with the user what it should contain
-- NEVER overwrite existing AGENTS.md or rule files without asking
-- Default to short rule files (20-60 lines). Split if larger.
-- When user asks "create a rule", default to creating a file in `.agents/rules/` (not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
-- When the user references AGENTS.md content directly (a command, the stack, a universal rule), edit AGENTS.md in place via the `edit` workflow — don't spin up a new rule file.
-  </rules_for_this_skill>
-
-<reference_guides>
-
-- **Examples**: [references/examples.md](references/examples.md) - Sample rule files (changelog, testing, deployment)
-- **AGENTS.md vs CLAUDE.md**: [references/agents-vs-claude.md](references/agents-vs-claude.md) - When to use which format
-  </reference_guides>
+A free-form request is `add` with a derived name. Ask 1–2 scope questions if the rule is unclear.