claude-leverage

USE WHEN a load-bearing architectural decision is being made in conversation (database / framework / auth model / integration choice, or explicit rejection of an alternative) — one likely to be re-litigated in 6 months without the rationale. Bootstraps a numbered MADR ADR in `docs/adr/`, asks for context + decision + alternatives, updates the index. Immutable status once accepted. See `docs/adr/README.md` for the convention; full Do/Don't list in this SKILL body.

USE WHEN setting up a repo for AI-first work, after a major directory restructure, or when an agent needs structured answers like "which modules are stable?" / "what's the public surface of X?" that the prose AGENTS.md doesn't give cheaply. Bootstraps or refreshes `architecture.yml` at repo root — machine-readable module metadata (path / role / stability / public_surface / depends_on / paired_with / owners). Hand-curated; the skill drafts, the user confirms. See ADR 0005 for why this file lives at root and why YAML over JSON.

USE WHEN setting up Codex CLI in a project, tightening sandbox for prod/CI, or when user asks about Codex permissions. Interactive helper for per-project `.codex/config.toml`: `dev` / `prod` / `custom` profiles, idempotent via markers, preserves unmanaged config below the block. Codex-only artifact.

USE WHEN setting up a repo for AI-first work (after /init-repo), or when the context-surface hook should start feeding repo conventions to agents before edits. Drafts `conventions.yml` at repo root: per-kind casing (inferred from the code), a vague-name denylist seed, directory roles, and a hand-filled house-rules block. Idempotent — never overwrites a populated file; re-running prints suggested additions for manual merge. Read-only on code; never invents house rules. After writing, run /refresh-context-map so the hook picks it up.

USE WHEN the user explicitly asks to verify that this repo's DECLARED build/test/lint commands actually run ("does the quickstart work?", "validate the commands in AGENTS.md"), typically after /repo-doctor or /repo-doctor --semantic raised suspicion. Executes only commands the repo itself declares (AGENTS.md build/test blocks, README quickstart), with preview + explicit confirmation, denylist tripwire, and timeouts. Advisory — results never enter /repo-doctor's deterministic score (ADR 0012/0013). Opt-in by invocation; never fired by hooks or other skills.

USE WHEN about to open a PR, when teammate asks "what's in this diff?", or when returning to a branch and needing self-orientation. Three modes: `--for pr|review|self`. Reads `git diff HEAD` (or passed range), returns 3–5 bullet plain-English narration. Read-only — defers security/test concerns to other skills.

USE WHEN setting up a repo for AI-first work, when an agent hallucinates domain term meaning, or when user asks to bootstrap / extend the repo's domain glossary. Surfaces candidate terms by identifier frequency, asks the user for 1-sentence definitions, writes `GLOSSARY.md` at repo root. Idempotent — re-running adds new terms without overwriting existing ones. Read-only on code; never invents domain meaning. Full Do/Don't list in this SKILL body. See ADR 0005 for why this file lives at root.

USE WHEN starting work in a project that lacks a claude-leverage AGENTS.md (no `claude-leverage:` marker blocks at git root), or when user asks to set up the stack here. Drops AGENTS.md + `.gitignore` patterns + optional language-specific logging template + optional CLAUDE.md routing snippets. Interactive, idempotent via markers.

USE WHEN auditing logging in a legacy codebase, after adopting the JSON-lines spec, or when user asks to clean up logging. Finds print/console.log/interpolated logger calls and suggests spec- compliant replacements per AGENTS.md. Read-only — never auto-rewrites. Templates per language in `templates/logging/`.

USE WHEN documenting a non-obvious workflow prose explains poorly, or when user describes a multi-step process and asks for a visualization. Generates a mermaid sequenceDiagram or flowchart, optional insertion into target markdown between idempotent markers, `mmdc` validation in a 3-retry loop.

USE WHEN AIDEV anchors / per-dir AGENTS.md / ADRs have changed in this repo and the smart-context-surfacing PreToolUse hook needs an updated manifest. Rebuilds `.claude-leverage-context-map.json` at the repo root by running `scripts/build-context-map.py`. Read-only on source — only writes the manifest.

USE WHEN adding/renaming/removing a top-level dir, before a release, or when user asks to regenerate the README architecture diagram. Refreshes the mermaid block in README between `<!-- repo-map:start -->` markers (surrounding content untouched). Optional dep-graph block via `madge`/`pydeps`.

USE BEFORE committing security-sensitive changes (auth, crypto, routes, user-input handling, secret loading, templates), or when the `security-nudge` Stop hook suggests it. Audits the current diff for OWASP-Top-10-shaped issues + deps typosquatting. Read-only. Delegates to the `security-reviewer` Sonnet subagent shipped here; returns Critical / Important / Nice schema with `file:line`.

USE WHEN ending a substantial working session — user says "thanks/tomorrow/wrap up", or session shipped 3+ commits with no log today, or user asks for a summary. Distills the conversation into `docs/sessions/YYYY-MM-DD-<topic>.md` (context, what was done, key decisions, open questions, next steps). Hard cap ~80 lines. Distillate, NOT transcript. See `docs/sessions/README.md`.

USE WHEN the `stack-freshness` SessionStart hook nudges ("stack last checked 42d ago"), or when user asks to check dep versions. Verifies Claude Code + Codex + plugin + CLI deps vs `stack.toml` (per-OS update commands), flags stale AIDEV-TODO/QUESTION anchors (deadline-aware), and sanity-checks AGENTS.md size + imports. Read-only. Resets the freshness timestamp.