the-grimoire-cli 0.3.2

package/.agents/rules/15-skills.md

@@ -0,0 +1,27 @@
+---
+updated: 2026-05-31
+description: Consult skills/catalog.md and use the right skill/plugin/MCP before improvising.
+---
+
+# 15 — Use the right tool (skills / plugins / MCP)
+
+Before improvising any non-trivial task, **consult `skills/catalog.md`** and invoke the primary
+capability for the trigger. If the catalog does not cover it, run **`find-skills`** before
+hand-rolling a solution. For multi-step work, run the matching **workflow chain** end to end — do
+not stop early.
+
+Precedence: this rule defers to `local/`. A project may swap a primary (e.g. pin
+`superpowers:test-driven-development` instead of `tdd`) or disable a tool in `local/AGENTS.local.md`.
+
+## Workflow chains
+
+- **Feature:** `brainstorming → writing-plans → [using-git-worktrees] → tdd → verifier → ecc:code-review → ecc:pr`
+- **Bugfix:** `diagnose → tdd (reproduce) → verifier → ecc:pr`
+- **UI:** `stitch (mockup) → ui-ux-pro-max → react-test → ecc:frontend-a11y → playwright (visual) → verifier`
+- **Architecture:** `improve-codebase-architecture → grill-with-docs → writing-plans → …`
+- **Research-first:** `ecc:deep-research → brainstorming → …`
+
+The required tools for this project are declared in `tooling.json`; run `grimoire bootstrap` to
+install/enable them. The mattpocock engineering skills (`tdd`, `diagnose`, `to-prd`, `to-issues`,
+`triage`, `improve-codebase-architecture`, `zoom-out`) require running `/setup-matt-pocock-skills`
+once per repo first.

package/.agents/rules/20-modes.md

@@ -0,0 +1,41 @@
+---
+updated: 2026-05-31
+description: 'NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires.'
+---
+
+# 20 — Modes: NORMAL vs HOTFIX
+
+A mode is set by a user phrase and **persists for the whole session**. Record it at the top of
+`journal/session/current.md`.
+
+## NORMAL (default)
+
+Full discipline:
+- Plan before code; TDD per the active stack testing-policy.
+- Full `verify` script (`stack/`): typecheck + lint + test + coverage + format:check.
+- Docs and `journal/memory/` updated **same turn** as the change.
+- Commits go through hooks (husky + lint-staged). No `--no-verify`.
+- The verifier must `pass` before "done".
+
+## HOTFIX (on-site fire)
+
+Triggered by phrases like "hotfix", "production down", "on-site fire" (localize the trigger words
+per project in `local/`). Once declared, HOTFIX **persists the whole session** — don't silently
+revert on the next message. Minimize blast radius:
+- **Smallest diff** — one file if possible.
+- **TDD waived** — backfill tests in the cleanup item.
+- **Gate the new path behind an env flag** — single-unset rollback. Document the flag and how to
+  unset it **in the commit body**, so an operator who only has `git log` can roll back.
+- `--no-verify` **allowed** for the emergency commit only.
+- **Never `npm ci`** (or any clean-install that wipes deps) on-site — a cancelled run leaves a
+  half-installed tree and a dead app. If deps are unchanged, build only; otherwise `npm install`
+  (resumable).
+- **Log a `journal/backlog/` item** (`priority: hotfix`) with: a `Hypothesis:` line (keep the disproven ones
+  too), the env flag + rollback, and a cleanup checklist (tests to backfill, flag to remove, ADR if
+  implied). An empty cleanup section means the HOTFIX is undocumented.
+
+**Environmental fire ≠ code fire.** If the on-site cause is hardware / OS / network / AV (RAM,
+keyring, co-tenant load), it is **not** a HOTFIX. Route per `40-handoff.md` — record in `journal/memory/` as
+a `type: field-report`, do not patch code.
+
+Leaving HOTFIX → the cleanup item must be closed under NORMAL discipline.

package/.agents/rules/25-surgical-changes.md

@@ -0,0 +1,29 @@
+---
+updated: 2026-05-31
+description: Touch only what the request needs; do not refactor or "improve" adjacent code.
+---
+
+# 25 — Surgical changes
+
+Touch only what you must. Clean up only your own mess.
+
+## When editing existing code
+
+- **Change only what the request needs.** Every changed line must trace directly to the task. If you
+  cannot explain why a line changed in terms of the request, revert it.
+- **Do not "improve" adjacent code, comments, or formatting.** Not yours to touch this turn.
+- **Do not refactor what is not broken.** Unrelated refactoring is a separate, named task.
+- **Match the existing style** even if you would do it differently. Mirror the surrounding idiom,
+  casing, and comment density.
+- **Notice ≠ delete.** If you spot unrelated dead code, **mention it** — do not remove it unless asked.
+
+## Orphans
+
+- Remove imports / variables / functions that **your** change made unused.
+- Do **not** remove pre-existing dead code unless the task asks for it.
+
+## The test
+
+> Could a reviewer read the diff and see nothing in it that the request did not call for?
+
+If not, trim the diff until they can.

package/.agents/rules/30-verification.md

@@ -0,0 +1,36 @@
+---
+updated: 2026-05-31
+description: 'The independent verifier: the author cannot mark their own work done; verify on fresh context.'
+---
+
+# 30 — Verification (independent verifier)
+
+**Principle: the agent that writes code cannot mark it done.** Bias comes from *shared context*,
+not from the model. Cut the context → cut the bias. One Claude Code subscription is enough via a
+**subagent with fresh context** — the **verifier**.
+
+## Flow (one session)
+
+1. Implementer (main thread) finishes the change.
+2. Main spawns the **verifier** subagent, passing **only**: the requirements, the diff, and the
+   checklist. **Not** the implementer's reasoning or conversation.
+3. The verifier is prompted to **refute** (skeptic; default to FAIL when unsure). It **runs the real
+   commands** (`verify` script — tests/build/lint) and **quotes real output**. No "looks good".
+4. The verifier returns a structured verdict: `pass | fail` + reasons + commands run + quoted output,
+   saved as an artifact.
+5. **Definition of Done** = tests green **AND** verifier `pass` **AND** checklist complete. Missing
+   any one → not done.
+
+## Scaling
+
+- Large work → multiple verifier lenses (correctness / security / requirements-match), run in parallel.
+- Same model family shares blind spots. Mitigate with: refute-style prompt, mandatory quoted
+  evidence, optionally run the verifier on a different model tier. Cross-model verification arrives
+  free when a second tool is added later.
+
+## Tool binding
+
+- Tool-agnostic: this file states the protocol in prose — any agent can follow it.
+- Claude Code: subagent `agents/verifier.md` + command `commands/verify.md`. For big changes, pair
+  with `/code-review` (or `/code-review ultra`).
+- A Stop-hook may warn if "done" is declared without a verifier artifact (per-project opt-in).

package/.agents/rules/35-context-economy.md

@@ -0,0 +1,41 @@
+---
+updated: 2026-05-31
+description: Keep entry and always-on files lean; push detail to references read on demand.
+---
+
+# 35 — Context economy (keep entry files lean)
+
+Entry and always-loaded files are read every session — bloat there taxes every turn (tokens +
+latency). Keep them lean; push detail to reference files reached on demand. This is the whole point
+of the load-order in `AGENTS.md`: start narrow, pull in depth only when the task needs it.
+
+How to write any of these docs (lead, voice, structure, versioning): `standards/writing.md`.
+
+## Budget
+
+- **Entry files** (`CLAUDE.md`, `.agents/AGENTS.md`, `local/AGENTS.local.md`): target **≤250 lines**,
+  **hard ceiling 300**. Line count is a proxy — the real test is *"is every line read most sessions?"*
+- **Each rule / standard file:** one focused topic. If a file grows past its single concern, split it.
+- **Skills / commands:** a skill body loads in full **when invoked** (its name + description load
+  cheaply; the body does not, until used). Keep a skill focused, **~200 lines max** — split a larger
+  one into sub-skills so unrelated capability is not pulled into context on use.
+- **`journal/memory/MEMORY.md`:** one line per memory; the fact itself lives in its own card.
+
+## What an entry file keeps (and little else)
+
+- tone / persona
+- the hardest **always-on** rules (full text lives in `rules/00-always.md`)
+- load order + routing map (where to find everything)
+- pointers to references (`rules/ standards/ stack/ journal/memory/ local/`)
+- precedence / customization note
+
+## What moves out (linked, read on demand)
+
+full rule text · coding standards · stack configs · the capability catalog · ADRs · examples · any
+long procedure. Replace the moved section with a one-line pointer — never inline a catalog or a long
+procedure into an entry file.
+
+## When an entry file crosses the ceiling
+
+Move the least-daily section into its matching reference file (or a new one) and leave a one-line
+pointer behind. Re-check after every edit that adds to an entry file.

package/.agents/rules/40-handoff.md

@@ -0,0 +1,25 @@
+---
+updated: 2026-05-31
+description: 'Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report.'
+---
+
+# 40 — Handoff routing
+
+Every incoming chat request routes to exactly one of:
+
+- **do-now** — single-commit, finishable this session, no ADR needed. No file; just do it and update
+  `journal/session/current.md`.
+- **BACKLOG** — multi-session, needs an ADR, touches schema/architecture, or the user says "add to
+  backlog". Create a `journal/backlog/<id>.md` item (`status: open`, `priority: normal`).
+- **HOTFIX** — production fire in the **code**. Create a `journal/backlog/<id>.md` item (`priority: hotfix`)
+  with a cleanup checklist, then fix under HOTFIX mode (`20-modes.md`).
+- **FIELD-REPORT** — on-site issue whose cause is **environmental** (hardware / OS / network / AV),
+  not the codebase. Record as a `journal/memory/` `type: field-report`; don't patch code. Grep field-reports
+  before assuming a code defect.
+
+Decision rule of thumb:
+
+> Right-now & small → do-now. Big / needs-a-decision / "later" → BACKLOG. Code on fire → HOTFIX.
+> Site/environment on fire → FIELD-REPORT.
+
+When unsure between do-now and BACKLOG, prefer BACKLOG and confirm scope before building.

package/.agents/rules/45-presentation.md

@@ -0,0 +1,35 @@
+---
+updated: 2026-05-31
+description: When and how to render human-facing deliverables as HTML instead of long Markdown.
+---
+
+# 45 — Presentation (HTML for humans)
+
+Long Markdown gets skimmed. For human-facing deliverables an interactive HTML page communicates
+better — tables, side-by-side comparisons, diff annotations, SVG diagrams, toggles. Render with
+`/present` (`commands/present.md`).
+
+## Toggle (default off)
+
+- Project default: set in `local/AGENTS.local.md` ("Presentation mode").
+- Session override: user says **"html on" / "html off"**. When off, reply in Markdown only.
+- Even when on, use HTML for the deliverable types below — not routine replies.
+
+## Use HTML for
+
+spec comparison · code-review dashboard · report / explainer · design prototype · custom editing UI.
+(Catalog: `skills/catalog.md` -> Presentation.)
+
+## Guardrails
+
+- **Agent files stay Markdown.** Load-path files an agent parses — `AGENTS.md`, `SKILL.md`, `rules/`,
+  `standards/`, `tooling.json`, `INDEX.md`, `journal/memory/`, context files — are never rendered as HTML.
+  HTML is only a human-facing *view* of a deliverable; the agent-readable + git-diffable source is
+  always Markdown.
+- **Source stays canonical.** HTML is an ephemeral *view* generated from the Markdown/spec — never
+  the source of truth. Durable decisions still land in `docs/`, `journal/memory/`, specs.
+- **Self-contained + offline.** One file, inline CSS/JS, no remote `<script>`/CDN.
+- **Security.** Escape embedded code/diff/user text; never run untrusted script; no secrets in the page.
+- **Ephemeral.** Artifacts live in `journal/session/artifacts/` (gitignored). Don't commit them.
+- **Close the loop.** Editing UIs export back as JSON/Markdown so changes re-enter the workflow.
+- **Token-aware.** Generating HTML is expensive; reserve it for deliverables that earn it.

package/.agents/rules/50-security.md

@@ -0,0 +1,30 @@
+---
+updated: 2026-05-31
+description: Server-side authorization, no hardcoded secrets/roles, fail closed.
+---
+
+# 50 — Security
+
+- **Permissions via helpers, not literals.** Authorize through a single helper/policy layer.
+  Never `if (role === "admin")` scattered across the code.
+- **Validate + authorize on the server.** Client checks are UX only; the server is the boundary.
+  Validate every input; reject by default.
+- **Fail closed.** On error, missing data, or unknown state → deny, do not allow.
+- **Parameterized queries only.** Never string-concatenate SQL or shell. No dynamic `eval`.
+- **No secrets in code or logs.** Secrets come from env/secret-store. Never commit them; never log
+  them. Scrub before logging.
+- **Least privilege.** Tokens, DB roles, and API scopes get the minimum needed.
+- **Row-level authorization.** Every user row is restricted to its owner (Postgres/Supabase RLS or
+  an app-layer check). **Default-deny** — zero policies means a wide-open database.
+- **Test the abuse paths.** Wrong password, reset for a non-existent email (no user enumeration),
+  expired session, malformed/oversized input — not just the happy path.
+- **Security headers.** Set CSP, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy.
+- **Privacy by default.** Collect the minimum personal data, know where it lives, publish a privacy
+  policy (GDPR/CCPA/PDPA; PHI → HIPAA).
+- **Validate env at startup.** Required env vars are checked at the init boundary with a clear error — never `process.env.X!` at use sites.
+- **Secrets at rest.** Desktop/native apps store secrets in the OS keystore (Electron `safeStorage` / OS keychain), never plaintext on disk.
+- **Dependencies.** Pin versions; review before adding; prefer the std lib when it suffices.
+
+**Before launching a user-facing, data-collecting app:** clear `standards/launch-security-checklist.md`
+(privacy · row-level authz · abuse-path tests · server validation · headers · OWASP) and run a SAST
+scan (`standards/security-scanners.md`). This is part of Definition of Done (`rules/30-verification.md`).

package/.agents/rules/60-commit-style.md

@@ -0,0 +1,14 @@
+---
+updated: 2026-05-31
+description: Conventional Commits and the project's commit/PR conventions.
+---
+
+# 60 — Commit style
+
+- **Conventional Commits.** `type(scope): subject` — `feat` `fix` `docs` `refactor` `test` `chore`
+  `perf` `build` `ci`. Imperative mood, lower-case subject, no trailing period.
+- **One logical change per commit.** Reviewable diffs; no "misc fixes" grab-bags.
+- **Hooks run.** husky + lint-staged on commit. **No `--no-verify`** — the one exception is a
+  HOTFIX emergency commit (`20-modes.md`), which must be cleaned up afterward.
+- **Body explains why** when the change is non-obvious. Reference the `journal/backlog/` id or ADR.
+- **Never bypass signing** unless explicitly asked.

package/.agents/rules/INDEX.md

@@ -0,0 +1,18 @@
+# rules — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `00-always.md` | The non-negotiable rules; violating any is a hard error, not a style nit. |
+| `05-code-quality.md` | Always-on code-quality essentials; the full standard lives in standards/clean-code.md. |
+| `10-working-process.md` | How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD. |
+| `15-skills.md` | Consult skills/catalog.md and use the right skill/plugin/MCP before improvising. |
+| `20-modes.md` | NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires. |
+| `25-surgical-changes.md` | Touch only what the request needs; do not refactor or "improve" adjacent code. |
+| `30-verification.md` | The independent verifier: the author cannot mark their own work done; verify on fresh context. |
+| `35-context-economy.md` | Keep entry and always-on files lean; push detail to references read on demand. |
+| `40-handoff.md` | Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report. |
+| `45-presentation.md` | When and how to render human-facing deliverables as HTML instead of long Markdown. |
+| `50-security.md` | Server-side authorization, no hardcoded secrets/roles, fail closed. |
+| `60-commit-style.md` | Conventional Commits and the project's commit/PR conventions. |

package/.agents/skills/INDEX.md

@@ -0,0 +1,8 @@
+# skills — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `catalog.md` | Capability catalog — What to reach for, by trigger. |
+| `find-skills/` | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that ca… |

package/.agents/skills/README.md

@@ -0,0 +1,6 @@
+# skills — reusable, re-runnable workflows
+
+Portable skill files (Claude Code `skills/` format) that any project inherits. v0.1 ships the
+verification workflow as a command + subagent (`commands/verify.md`, `agents/verifier.md`) rather
+than a standalone skill. Add skills here as patterns prove reusable across projects; they sync as a
+managed path.

package/.agents/skills/catalog.md

@@ -0,0 +1,106 @@
+# Capability catalog
+
+What to reach for, by trigger. **Primary** = default choice. **Alternates** = equivalents when the
+primary is unavailable or you want a second opinion. Anything not here → run `find-skills`.
+
+> The mattpocock engineering skills below require `/setup-matt-pocock-skills` once per repo
+> (configures the issue tracker, triage label vocabulary, and doc layout they consume).
+>
+> Bare-named MCPs in this catalog (`context7`, `exa`, `github`) ship **with the `ecc` plugin** —
+> `grimoire bootstrap` enabling `ecc` wires them; they intentionally have no separate `tooling.json`
+> `mcp` entry. Only standalone servers (`playwright`, `stitch`) live in `tooling.json`.
+
+## Process & engineering
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| starting a new feature | `superpowers:brainstorming` | — | skill |
+| aligning before a change | `grill-me` / `grill-with-docs` | — | skill |
+| writing the implementation plan | `superpowers:writing-plans` | `ecc:plan` | skill |
+| writing code test-first | `tdd` | `superpowers:test-driven-development` | skill |
+| chasing a hard bug / perf regression | `diagnose` | `superpowers:systematic-debugging` | skill |
+| improving architecture (ball of mud) | `improve-codebase-architecture` | — | skill |
+| designing a module's layering | `standards/architecture.md` | `improve-codebase-architecture` | doc |
+| production logging / observability | `standards/observability.md` | — | doc |
+| understanding unfamiliar code | `zoom-out` | — | skill |
+| compacting the session for handoff | `handoff` | — | skill |
+| managing work-state / second brain | `standards/knowledge-management.md` | — | doc |
+| throwaway prototype to flesh out a design | `prototype` | — | skill |
+| turning context into a PRD | `to-prd` | `ecc:plan-prd` | skill |
+| breaking a plan into issues | `to-issues` | — | skill |
+| triaging incoming issues | `triage` | — | skill |
+| writing a new skill | `write-a-skill` | `skill-creator` | skill |
+| isolating parallel work | `superpowers:using-git-worktrees` | `superpowers:dispatching-parallel-agents` | skill |
+
+## Review, security, quality
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| reviewing before merge | `ecc:code-review` | `superpowers:requesting-code-review`, `/code-review` | skill |
+| auditing security-sensitive code | `ecc:security-review` | `ecc:security-scan` | skill |
+| gating a launch (privacy + security) | `standards/launch-security-checklist.md` | `ecc:security-review`, SAST (`standards/security-scanners.md`) | doc |
+| confirming work is done | `verifier` (Grimoire) | `superpowers:verification-before-completion` | subagent |
+| cleaning dead code | `ecc:refactor-clean` | — | skill |
+| running the quality gate | `ecc:quality-gate` | — | skill |
+| writing or reviewing code to standard | `standards/clean-code.md` | `templates/lint/` (enforcement) | doc |
+| writing or editing an agent-facing doc | `standards/writing.md` | — | doc |
+| guarding structural invariants (drift) | `standards/guardrail-tests.md` | — | doc |
+| recording a decision (incl. no-test rationale) | `codex/decisions/` (`0000-template.md`) | — | doc |
+
+## Web / Next.js (pharmaceutical-hub)
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| building a React component | `ecc:react-patterns` | `ecc:react-performance` | skill |
+| reviewing React/TSX | `ecc:react-review` | — | skill |
+| writing React tests | `ecc:react-test` | `tdd` | skill |
+| fixing a React/Next build | `ecc:react-build` | `ecc:build-fix` | skill |
+| Next.js / Turbopack specifics | `ecc:nextjs-turbopack` | — | skill |
+| accessibility pass | `ecc:frontend-a11y` | `web-design-guidelines` | skill |
+| designing an API | `ecc:api-design` | `ecc:backend-patterns` | skill |
+| DB schema / queries | `ecc:postgres-patterns` | `ecc:prisma-patterns` | skill |
+| DB migration | `ecc:database-migrations` | — | skill |
+
+## Healthcare (both repos are medical)
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| handling PHI / privacy | `ecc:healthcare-phi-compliance` | `ecc:hipaa-compliance` | skill |
+| EMR/EHR data patterns | `ecc:healthcare-emr-patterns` | — | skill |
+| clinical decision support | `ecc:healthcare-cdss-patterns` | — | skill |
+| evaluating a health-AI feature | `ecc:healthcare-eval-harness` | — | skill |
+
+## Design / UI
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| designing UI/UX | `ui-ux-pro-max` | `andrej-karpathy` | skill |
+| turning a mockup into UI code | `stitch` (MCP) | — | mcp |
+
+> **Deprecated — do not use:** `frontend-design` (replaced by `ui-ux-pro-max`).
+
+## Research, docs, MCP
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| researching an unknown topic | `ecc:deep-research` | `exa` (MCP) | skill |
+| looking up a library / API | `context7` (MCP) | `ecc:documentation-lookup` | mcp |
+| browser QA / e2e / visual check | `playwright` (MCP) | `ecc:e2e-testing` | mcp |
+| repo / PR operations | `ecc:pr` | `github` (MCP), `/pr` | skill |
+| need a capability you lack | `find-skills` | — | skill |
+
+## Presentation (HTML for humans)
+
+Render with `/present` when presentation mode is on (`rules/45-presentation.md`). HTML is an
+ephemeral view; the Markdown/spec stays canonical.
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| comparing specs / designs side by side | `/present` (HTML) | `superpowers:brainstorming` visual companion | command |
+| presenting a code review to a human | `/present` (HTML dashboard) | `ecc:code-review` | command |
+| writing a report / explainer | `/present` (HTML) | — | command |
+| showing a design prototype | `prototype` | `/present` (HTML) | skill |
+| building a custom editing UI (copy-as-JSON) | `/present` (HTML) | — | command |
+## Communication
+
+`pordee` (Thai-compressed) and `caveman` (terse) are session-level toggles set by the user.

package/.agents/skills/find-skills/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/.agents/stack/INDEX.md

@@ -0,0 +1,9 @@
+# stack — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `desktop.md` | Profile: desktop — Default for Electron / desktop apps (harvested from ever-sync-adapter). |
+| `library.md` | Profile: library — Default for published or internal reusable packages. |
+| `web-app.md` | Profile: web-app — Default for full-stack / front-end web projects. |

package/.agents/stack/README.md

@@ -0,0 +1,66 @@
+# Stack — tech-stack presets
+
+A **profile** pins the framework, lint/format, test setup, and CI scaffold for a project type.
+Pick one at `init`; record the active profile in `local/AGENTS.local.md`.
+
+## Profiles (v0.1 starter set)
+
+- `web-app.md` — full-stack / front-end web.
+- `desktop.md` — Electron / desktop app.
+- `library.md` — published or internal reusable package.
+
+## Testing-policy knob (per profile, project chooses — not hardcoded)
+
+| Policy | Meaning |
+|---|---|
+| `tdd-mandatory` | Red-green-refactor required before merge (ever-sync style). |
+| `test-ready-deferred` | Test harness wired; tests written as features stabilize (pharma style). |
+| `none` | No automated tests (spikes/throwaway only). **Requires a recorded ADR** (`codex/decisions/`) — see `rules/00-always.md` "No silent test gaps". |
+
+## The `verify` script
+
+Every profile defines a `verify` command — the single gate the **verifier** runs
+(`rules/30-verification.md`):
+
+```
+verify = typecheck + lint + test + coverage + format:check
+```
+
+Wire it as a package script (`npm run verify`) so it is one command everywhere. The verifier runs it
+and quotes the real output; "looks good" is never acceptable.
+
+## Knowledge retrieval — graphify (ADR 0006)
+
+Grimoire does **not** ship a homegrown retrieval engine. Searching the codebase (and `codex/`) is
+delegated to **graphify**, a code+docs knowledge graph. The base prescribes the convention; install is
+per-machine.
+
+- **Install** (one-time, per machine): `uv tool install graphifyy` then `graphify install`.
+- **Build / refresh** the graph for a repo: `graphify .` (PowerShell: no leading slash). Code is
+  extracted locally via AST (free, no API); docs/PDFs use the IDE session model (no separate key).
+  `graphify hook install` rebuilds the code graph on every commit (AST only, free).
+- **Query-first**: prefer `graphify query "<question>"` / `graphify path A B` / `graphify explain X`
+  over grepping raw files or reading the whole report — it is the cheaper, structured path.
+- **Commit policy**: `graphify-out/` is committed so the team shares one map; local-only artifacts
+  (`cost.json`, `cache/`, `.graphify_python`) are gitignored (`templates/gitignore-snippet.txt`).
+- **`codex/` is the source of truth** graphify indexes — content vs retrieval stay separate.
+
+Optional personal layer (not a base dependency): **obsidian-wiki** maintains a cross-project Obsidian
+vault via the coding agent (Karpathy LLM-Wiki). Install it in your global agent skills, never in the
+managed contract.
+
+## Laziness enforcement — ponytail (ADR 0007)
+
+The **principle** lives in the contract: `standards/clean-code.md` owns the ladder, the "never
+simplify away" guardrail, and the `ponytail:` shortcut marker — tool-agnostic, every agent gets it.
+**Enforcement automation** is delegated to the **ponytail** plugin (skill-capable hosts: Claude Code,
+Codex, OpenCode, Gemini, pi); install is per-machine, optional.
+
+- **Install** (Claude Code): `/plugin marketplace add DietrichGebert/ponytail` then
+  `/plugin install ponytail@ponytail`. Other hosts: see the ponytail README.
+- **`/ponytail-review`** — review the current diff for over-engineering; hands back a delete-list.
+- **`/ponytail-audit`** — same, whole repo instead of the diff.
+- **`/ponytail-debt`** — harvest the `ponytail:` shortcut markers into a ledger so "later" isn't
+  "never". This is why the marker token in `clean-code.md` is literally `ponytail:`.
+- Without the plugin the principle still holds (the marker is self-documenting); you just lose the
+  automated harvest/review.