claude-leverage

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 (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 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 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 inheriting a legacy repo, when user asks "what's missing for AI-first work here?", "is this repo agent-ready?", "audit my repo", "is anything out of sync with the code?", or when the bare-repo-nudge / cheatsheet hook suggests a checkup. Read-only AI-readiness audit — scores ~20 dimensions across Foundation (AGENTS.md / CLAUDE.md / per-dir AGENTS.md), Why (ADRs + session logs), What (GLOSSARY.md + architecture.yml), In-code (AIDEV anchor density + overdue), Hygiene (tests, LOC ratio, structured logging, .gitignore, README, manifest), AND Sync (code↔docs drift: arch-map vs disk, glossary vs code, per-dir AGENTS.md vs dir activity, CHANGELOG vs version, README slash-refs). Each gap → concrete fix action. Differentiated from /init-repo (one-shot bootstrap, writes files) and /stack-check (time-based freshness) — this skill answers completeness AND drift in one pass. See ADR 0006 (initial design) and ADR 0007 (Sync addition) for rationale.

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.

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 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 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`.