@dennisrongo/skills 0.1.3 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # claude-skills
 
-The [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) skills I ([Dennis Rongo](https://github.com/dennisrongo)) use every day — not shelfware, not theory. Each one earns its place by surviving real work: shipping .NET APIs and Next.js frontends, reviewing PRs, debugging production, and keeping commits clean.
+The [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) skills I ([Dennis Rongo](https://github.com/dennisrongo)) use every day — not shelfware, not theory. Each one earns its place by surviving real work: shipping features, reviewing PRs, debugging production, designing architecture, and keeping commits clean.
 
 They're small, composable, and meant to be tuned. Install the ones you want, edit them in-place, send a PR if yours sharpens mine.
 
@@ -92,15 +92,17 @@ node bin/claude-skills.js list
 
 | Skill | What it does |
 |---|---|
+| [`code-review`](./skills/code-review/SKILL.md) | Production-readiness review of **uncommitted** working-tree changes (staged + unstaged). Hunts DRY violations, dead code, leaky abstractions, premature abstraction, magic values, missing error handling, debug residue, missing migrations / flags / logs, and other common best-practice gaps — prioritized correctness → DRY/design → tests → security → performance → production-readiness → readability. On non-trivial diffs, convenes a **lens council**: parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests / production-readiness), followed by an **adversarial critique round** that challenges each lens's blocking flags against context from the others — false positives demoted, contradictions surfaced for the user, multi-lens findings promoted. Small diffs skip the council. Auto-detects and runs the project's tests and build (`npm`, `pytest`, `dotnet`, `go`, `cargo`, `Makefile`, monorepo orchestrators) and gates the verdict on them being green. **Never edits code unprompted** — produces a categorized report (`blocking` / `suggestion` / `nit` / `praise`) with `file:line` citations, then asks per-finding before fixing. Distinct from [`pr-review`](./skills/pr-review/SKILL.md), which scopes to committed branch work. Triggers on "code review", "review the diff", "is this production ready", "DRY check", or `/code-review`. |
+| [`codebase-explainer`](./skills/codebase-explainer/SKILL.md) | Produce a durable onboarding artifact for a repo — writes `ONBOARDING.md` (or `docs/ONBOARDING.md` if `docs/` exists) with a tight **read this first** minimum, system overview, dependency map (top-level prod deps + how each is actually used in *this* codebase, with key call site), startup flow (entry point → bootstrap → config), auth flow (or an explicit "no auth detected" when there isn't one), and the 5–15 important files — every claim backed by a `file:line` citation. Walks the repo with **parallel Explore sub-agents** to stay context-safe on big projects, refreshes an existing `ONBOARDING.md` in place instead of rewriting from scratch, and is opinionated about what *not* to include (no dev/test/types deps, no 40-file "important files" lists, no fabricated auth flows, no dates that rot). Built for revisiting a project after months away — and for new teammates landing in an unfamiliar repo. Composes with [`improve-codebase-architecture`](./skills/improve-codebase-architecture/SKILL.md) when shallow-module clusters surface and [`handoff`](./skills/handoff/SKILL.md) for session-level state. Triggers on "explain this codebase", "onboard me", "give me a tour", "where do I start", "I haven't looked at this in months", or `/codebase-explainer`. |
 | [`conventional-commits`](./skills/conventional-commits/SKILL.md) | Write git commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) spec (`feat`, `fix`, `chore`, `docs`, …), auto-prefixed with the ticket number from the current branch (e.g. `feature/12345-...` → `#12345`) and a project tag (`API` / `CLIENT` / `CONSOLE` / `DB`) when detectable from the diff. Both prefixes are omitted when they don't apply. Triggers on commit-message requests. |
-| [`diagnose`](./skills/diagnose/SKILL.md) | Disciplined diagnosis loop for hard bugs and performance regressions — reproduce → minimise → hypothesise → instrument → fix → regression-test. Forces a fast, deterministic feedback loop before any guessing, generates 3–5 ranked falsifiable hypotheses, uses tagged `[DEBUG-...]` instrumentation that's trivially cleaned up, and ends with a post-mortem on what would have prevented the bug. Triggers on "diagnose this" / "debug this" / bug reports / flaky tests / perf regressions. |
+| [`diagnose`](./skills/diagnose/SKILL.md) | Disciplined diagnosis loop for hard bugs and performance regressions — reproduce → minimise → hypothesise → instrument → fix → regression-test. Forces a fast, deterministic feedback loop before any guessing. On non-trivial cases, Phase 3 convenes a **hypothesis council**: parallel `Explore` sub-agents — one per candidate hypothesis — each defending its case with falsifiable predictions and `file:line` evidence from the actual codebase, followed by a cross-examination round that drops defenders who couldn't find supporting evidence and ranks the survivors. Trivial bugs skip the council and use 1–2 inline hypotheses. Uses tagged `[DEBUG-...]` instrumentation that's trivially cleaned up, and ends with a post-mortem on what would have prevented the bug. Triggers on "diagnose this" / "debug this" / bug reports / flaky tests / perf regressions. |
 | [`dotnet-onion-api`](./skills/dotnet-onion-api/SKILL.md) | Scaffold a new .NET solution (Web API + Worker microservices) using ONION architecture and EF Core, codifying battle-tested layered patterns and explicitly removing common legacy pitfalls (sproc-centric repos with reflection, EF6 on netstandard2.1, polling console workers, mutable base-service state, missing `CancellationToken`). Three modes — full solution scaffold, add-a-feature slice, add-a-worker microservice. Resolves TFM and NuGet versions at scaffold time (not hard-coded). |
 | [`grill-with-docs`](./skills/grill-with-docs/SKILL.md) | Interview-driven design review. Stress-tests a plan, RFC, or feature idea against the project's existing domain model and documented decisions — one question at a time with `AskUserQuestion`, sharpening fuzzy terminology and surfacing contradictions with the codebase. Updates `CONTEXT.md` (glossary) inline as terms resolve and writes ADRs to `docs/adr/` only when the decision is hard to reverse, non-obvious, and had real trade-offs. Writes no production code — composes with [`plan-and-build`](./skills/plan-and-build/SKILL.md) for the implementation handoff. Triggers on "grill me", "stress-test this plan", "challenge this design", "/grill-with-docs", or a pasted RFC. |
 | [`handoff`](./skills/handoff/SKILL.md) | Capture a session hand-off before context runs out — writes a dated `.claude/handoffs/*.md` (objective, progress, decisions, files, open issues, ready-to-paste next-session prompt) plus a lightweight memory pointer so a fresh Claude session can resume cleanly. |
 | [`improve-codebase-architecture`](./skills/improve-codebase-architecture/SKILL.md) | Surface architectural friction and propose **deepening opportunities** — refactors that collapse clusters of shallow modules into one deep module with a real seam. Walks the codebase with an Explore sub-agent, applies the **deletion test** to suspected pass-throughs, presents numbered candidates (files / problem / solution / benefits) using `CONTEXT.md` for the domain and a strict architecture glossary (module / interface / seam / depth / leverage / locality) for the structure, then drops into a grilling loop with optional parallel sub-agent interface design ("Design It Twice"). Updates `CONTEXT.md` inline as new concepts get named and offers an ADR only when a rejection is load-bearing. Composes with [`grill-with-docs`](./skills/grill-with-docs/SKILL.md) for glossary + ADR discipline and [`plan-and-build`](./skills/plan-and-build/SKILL.md) for the implementation handoff. Writes no production code. Triggers on "improve architecture", "architecture review", "find refactoring / deepening opportunities", "find shallow modules", "make this more testable", or `/improve-codebase-architecture`. |
-| [`nextjs-app-router`](./skills/nextjs-app-router/SKILL.md) | Scaffold a new Next.js (App Router) frontend with TypeScript, Redux Toolkit + RTK Query, Tailwind + shadcn/ui (Radix), and React Hook Form + Zod. Codifies route-group auth boundaries, a single injected RTK Query API, schema-driven forms with introspected defaults, server-side `middleware.ts`, and Vitest + Playwright + CI defaults — while forbidding common pitfalls (`'use client'` on root pages, `router.push` in `useEffect`, `serializableCheck: false`, `@ts-ignore`, mixed `moment`/`date-fns`, `styled-components` alongside Tailwind, case-sensitive folder dupes, `dangerouslySetInnerHTML` without sanitization, tokens outside `httpOnly` cookies). Three modes — full project scaffold, add-a-feature slice, add-an-API-slice. Resolves package versions at scaffold time (not hard-coded). |
-| [`plan-and-build`](./skills/plan-and-build/SKILL.md) | Plan-first feature builder. Grills the user about the feature (à la `grill-with-docs`) until the design is unambiguous, detects the project's stack and conventions, presents a plan, and gates on `ExitPlanMode` approval before writing any code. Builds TDD-first with NUnit when a .NET API changes — appending to the matching test class if one already exists rather than forking a parallel one — reuses existing patterns, keeps comments minimal, and generates EF Core / migration files **without ever** running `dotnet ef database update` or any DDL/SQL against the user's database. Triggers on "build/add/implement a feature", "/plan-and-build", or a pasted feature spec. |
-| [`pr-review`](./skills/pr-review/SKILL.md) | Conduct a structured PR / diff review prioritized correctness → design → tests → security → performance → readability, with categorized feedback (`blocking` / `suggestion` / `question` / `nit` / `praise`). |
+| [`nextjs-app-router`](./skills/nextjs-app-router/SKILL.md) | Scaffold a new Next.js (App Router) **fullstack** app — TypeScript, **NextAuth (Auth.js v5)**, **Prisma + PostgreSQL**, Route Handlers as the backend, Redux Toolkit + RTK Query, Tailwind + shadcn/ui (Radix), React Hook Form + Zod. **API-driven by deliberate choice**: pages are `'use client'`, all data flows UI → RTK Query → `/api/**` Route Handlers → Prisma. No `fetch()` in server components, no Server Actions, no async `page.tsx`. Confirms the database (Postgres + Prisma) and NextAuth providers with the user before writing files. Forbids the usual pitfalls (custom JWT cookies alongside NextAuth, multiple `createApi`/`PrismaClient` instances, `serializableCheck: false`, `@ts-ignore`, mixed `moment`/`date-fns`, `styled-components` alongside Tailwind, case-sensitive folder dupes, `dangerouslySetInnerHTML` without sanitization, Route Handlers that skip `requireSession()` or trust client-sent user IDs, `prisma db push` in CI). Three modes — full project scaffold, add-a-feature slice (page + form + Route Handler + Zod schema + RTK Query endpoints + Prisma model), add-an-API-slice. Resolves package versions at scaffold time (not hard-coded). |
+| [`plan-and-build`](./skills/plan-and-build/SKILL.md) | Plan-first feature builder. Grills the user about the feature (à la `grill-with-docs`) until the design is unambiguous, detects the project's stack and conventions, presents a plan, and gates on `ExitPlanMode` approval before writing any code. When Phase 3 hits a genuine design fork (service-layer vs. CQRS, new table vs. nullable columns, sync vs. background job, etc.) and Phase 2 didn't settle it, runs **Design It Twice**: two parallel sub-agents each draft the BEST plan for one side of the named axis, then an inline debate names three wins for each and recommends one — the user sees a single recommended plan with a one-line "considered alternative" note so they can redirect with one sentence. Skipped when an existing pattern in the repo already dictates the approach. Builds TDD-first with NUnit when a .NET API changes — appending to the matching test class if one already exists rather than forking a parallel one — reuses existing patterns, keeps comments minimal, and generates EF Core / migration files **without ever** running `dotnet ef database update` or any DDL/SQL against the user's database. Triggers on "build/add/implement a feature", "/plan-and-build", or a pasted feature spec. |
+| [`pr-review`](./skills/pr-review/SKILL.md) | Structured review of a local branch, **grouped per `#NNN` task** referenced in commit messages, prioritized correctness → design → tests → security → performance → readability, with categorized feedback (`blocking` / `suggestion` / `question` / `nit` / `praise`). On non-trivial tasks, convenes a **per-task lens council**: parallel `Explore` sub-agents through distinct lenses (correctness / design / security / tests) on that task's diff only, followed by an **adversarial critique round** that demotes false-positive blockers when another lens defuses them, surfaces contradictions as `question` items for the user, and promotes findings raised by multiple lenses independently. Small tasks skip the council. The council never crosses task boundaries — each `#NNN` gets its own verdict. Triggers on "review my PR", "review the diff", "review my branch", or `/pr-review`. |
 | [`tauri-2-app`](./skills/tauri-2-app/SKILL.md) | Scaffold a new Tauri 2 desktop app (Rust backend + TypeScript/React frontend) using a thin-frontend / rich-Rust-backend architecture with modular `commands/`, `state/`, `storage/`, `platform/` traits, `error/` macros, single-instance + updater plugins wired correctly, capability JSON per window, encrypted secrets at rest, `spawn_blocking` for sync work, and typed frontend command hooks — while forbidding common pitfalls (committed `.backup`/`.orig`/`.temp` files, plaintext API keys in `settings.json`, tokens in `localStorage`, `cfg!(target_os)` in command bodies instead of trait-based platform code, hand-rolled date math instead of `chrono`, raw `std::fs` bypassing capability checks, blocking I/O inside async commands, missing `windows_subsystem = "windows"` in `main.rs`, `devtools: true` in release, hardcoded bundle identifiers / updater pubkeys / CDN URLs). Three modes — full project scaffold, add-a-command end-to-end, add-a-Rust-module slice. Resolves Cargo + npm versions at scaffold time (not hard-coded). |
 | [`write-a-skill`](./skills/write-a-skill/SKILL.md) | Author a new Claude Code skill — interview-driven scaffolding that produces a properly-structured `SKILL.md` (trigger-rich YAML description, "When to use", workflow, examples, anti-patterns), drops it in the right location (library `skills/`, project `./.claude/skills/`, or global `~/.claude/skills/`), updates the README skills table when extending this library, and runs a review checklist focused on the failure mode that matters most — under-triggering descriptions. Triggers on "create/write/add a skill", "/write-a-skill", or a pasted SKILL.md URL with "one like this". |
 
@@ -136,11 +138,26 @@ This CLI just copies skill folders to one of those locations. Nothing magic.
 
 ## Adding your own skills
 
+This library ships with a [`write-a-skill`](./skills/write-a-skill/SKILL.md) skill that scaffolds new ones for you — that's the intended path. Don't hand-edit `SKILL.md` from scratch; the skill knows the structure, writes a trigger-rich description (the part Claude actually reads), and updates the README table for you.
+
+Install it once, globally, from npm — no clone needed to use it:
+
+```bash
+npx @dennisrongo/skills install write-a-skill
+```
+
+From there:
+
+- **For a project skill or a global skill on your machine** — `cd` to the project (or anywhere), open Claude Code, and say `/write-a-skill`. It interviews you, picks the right location (`./.claude/skills/` for a project skill, `~/.claude/skills/` for a global one), and drops the new `SKILL.md`. Done.
+- **To contribute a skill back to this library** — you do need a working tree to commit. Clone the repo, `cd` in, open Claude Code, and say `/write-a-skill`. It detects the library repo, writes to `skills/<name>/SKILL.md`, and adds the row to the table above. Commit and push to `main`; on any machine `npx --yes github:dennisrongo/claude-skills install <your-skill-name>` picks it up.
+
+### The directory shape
+
 The library lives in [`skills/`](./skills). Each skill is a directory containing a `SKILL.md` with YAML frontmatter.
 
 ```
 skills/
-├── _template/              # not installed (leading underscore skips it)
+├── _template/              # starting point — the leading underscore skips it from install
 │   └── SKILL.md
 ├── conventional-commits/
 │   └── SKILL.md
@@ -150,7 +167,9 @@ skills/
     └── scripts/            # optional executable helpers
 ```
 
-### Minimal `SKILL.md`
+### If you'd rather do it by hand
+
+Copy `skills/_template/` to `skills/<your-skill-name>/`, edit the `SKILL.md`, and add a row to the skills table above. Minimum viable file:
 
 ```markdown
 ---
@@ -163,15 +182,7 @@ description: One sentence describing what it does AND when to trigger it. Be spe
 Instructions for Claude...
 ```
 
-The `description` is the most important field — it's what Claude reads to decide whether to consult the skill. Be explicit about trigger conditions; under-triggering is the more common failure mode.
-
-To add a new skill:
-
-1. Clone the repo: `git clone https://github.com/dennisrongo/claude-skills.git`
-2. Copy `skills/_template/` to `skills/<your-skill-name>/`
-3. Edit `SKILL.md`
-4. Commit and push to `main`
-5. On any machine: `npx github:dennisrongo/claude-skills install <your-skill-name>` — picks up the new skill immediately, no publishing step needed
+The `description` is the single highest-leverage field — it's the only thing Claude reads when deciding whether to consult the skill. Be explicit about trigger conditions; under-triggering is the more common failure mode. (This is the part [`write-a-skill`](./skills/write-a-skill/SKILL.md) is opinionated about — using it will save you from the rookie mistake of writing "Helps with X.")
 
 > Tip: `npx` caches the package per version spec. If you push an update to `main` and the next `npx github:dennisrongo/claude-skills ...` call doesn't seem to pick it up, run `npx --yes ...` to force a refresh, or clear the cache with `npx clear-npx-cache`.
 
@@ -218,33 +229,71 @@ npx --yes github:dennisrongo/claude-skills install --all --force
 
 ## Releasing
 
-Releases are published to npm automatically by [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) when a GitHub Release is published. The package ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm verifies it was built by this repo's Actions workflow.
-
-One-time setup:
-
-1. Create an automation-scoped `NPM_TOKEN` at https://www.npmjs.com/settings/<user>/tokens (use a "Granular Access Token" or "Automation" token).
-2. Add it to the repo as a secret: **Settings → Secrets and variables → Actions → New repository secret**, name `NPM_TOKEN`.
-3. If you ever rename the package, confirm the new name is free: `npm view <name>`. The current scoped name `@dennisrongo/skills` lives under your npm user/org — `npm publish --access public` will create it on first publish.
-
-Cutting a release:
+Releases are published to npm automatically by [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) **when a GitHub Release is published**. The package ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm verifies it was built by this repo's Actions workflow.
+
+### Cutting a release — step by step
+
+Run these from a clean working tree on `main`, in this order.
+
+1. **Commit and push your work first.** The release is cut from the tip of `main`; nothing uncommitted gets shipped.
+   ```bash
+   git status            # must be clean
+   git push origin main
+   ```
+2. **Pick the bump.** Follow semver (pre-1.0: still treat new features as `minor`):
+   - `patch` — bug fix in an existing skill, doc tweak, CLI fix.
+   - `minor` — new skill, materially new behavior in an existing skill, new CLI flag.
+   - `major` — removal or rename of a skill / CLI command, breaking change to install layout.
+3. **Bump the version + create the tag.**
+   ```bash
+   npm version <patch|minor|major>
+   # creates a "vX.Y.Z" commit and a matching git tag
+   ```
+4. **Push the bump commit and the tag together.**
+   ```bash
+   git push --follow-tags
+   ```
+5. **Create the GitHub Release** — this is the step that **triggers the npm publish workflow**.
+   ```bash
+   gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+   ```
+6. **Watch the workflow run.**
+   ```bash
+   gh run watch           # interactive, exits when done
+   # or
+   gh run list --workflow=publish.yml --limit 1
+   ```
+7. **Verify the publish.** Once the run is green:
+   ```bash
+   npm view @dennisrongo/skills version    # should match the new tag
+   npx @dennisrongo/skills@latest list     # smoke test
+   ```
+
+If the workflow fails, fix forward — don't reuse a published version number. npm rejects republishing the same version, so the next attempt needs a fresh bump.
+
+### What the workflow does
+
+`.github/workflows/publish.yml` runs on `release: published` and:
+
+1. Checks out the tag.
+2. Asserts `package.json` version matches the release tag (fails fast on mismatch).
+3. Runs `npm test`.
+4. Runs `npm publish --provenance --access public`.
+
+Both invocation forms work after publish:
 
 ```bash
-# Bump version (creates a commit + tag)
-npm version patch   # or minor / major
-
-# Push the commit and tag
-git push --follow-tags
-
-# Create a GitHub Release pointing at the new tag — the workflow takes over from there.
-gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+npx @dennisrongo/skills install                 # via npm (recommended)
+npx github:dennisrongo/claude-skills install    # latest commit on main
 ```
 
-The workflow checks `package.json` version matches the release tag, runs tests, then publishes with `--provenance`. After publishing both invocation forms work:
+### One-time setup (already done for this repo)
 
-```bash
-npx @dennisrongo/skills install                 # via npm
-npx github:dennisrongo/claude-skills install    # still works, latest main
-```
+Keep this for reference if the package ever moves or gets forked:
+
+1. Create an automation-scoped `NPM_TOKEN` at https://www.npmjs.com/settings/<user>/tokens (use a "Granular Access Token" or "Automation" token).
+2. Add it to the repo as a secret: **Settings → Secrets and variables → Actions → New repository secret**, name `NPM_TOKEN`.
+3. If you ever rename the package, confirm the new name is free: `npm view <name>`. The current scoped name `@dennisrongo/skills` lives under your npm user/org — `npm publish --access public` will create it on first publish.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dennisrongo/skills",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "A curated, fine-tunable library of Claude Code skills. Install globally or per-project via npx.",
   "bin": {
     "skills": "bin/claude-skills.js"

package/skills/code-review/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: code-review
+description: Production-readiness code review of **uncommitted** working-tree changes (staged + unstaged). Hunts DRY violations, dead code, leaky abstractions, missing error handling, and other common best-practice gaps; auto-detects and runs the project's tests and build; reports findings categorized `blocking` / `suggestion` / `nit` and **never edits code without permission** — recommendation first, ask, then fix. On non-trivial diffs, spawns a **lens council**: parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests / production-readiness), then an adversarial critique round that challenges each lens's blocking flags against context from the others — false positives get demoted, contradictions get surfaced for the user to adjudicate. Small diffs skip the council. Use this skill whenever the user says "code review", "review my code", "review the diff", "check my uncommitted changes", "is this production ready", "ready to ship", "DRY check", "clean up duplication", or "/code-review" — even if they don't explicitly say "code review skill". Distinct from `pr-review` (which scopes to committed branch work grouped by `#NNN`): this skill scopes to the working tree and gates on tests + build green.
+---
+
+# Code Review
+
+Review the uncommitted changes in the working tree against DRY and common software-engineering best practices, verify the project still builds and its tests still pass, and surface findings as recommendations the user can act on — **without editing code unprompted**.
+
+## When to use this skill
+
+- "code review" / "review my code" / "review the diff"
+- "check my uncommitted changes" / "is this production ready" / "ready to ship"
+- "DRY check" / "clean up duplication"
+- `/code-review`
+
+Do **not** auto-trigger when the user is asking for a PR / committed-branch review — defer to [`pr-review`](../pr-review/SKILL.md) for that. The dividing line is **committed vs. uncommitted**.
+
+## Hard rule: recommend, don't refactor
+
+If you find issues, **do not start editing**. Produce the findings report first. After delivering it, ask the user, per issue or per batch: *"Want me to fix #N?"* — and wait for an explicit yes before touching code. If the user pre-authorizes the whole batch ("fix them all"), proceed; otherwise default to ask-per-fix.
+
+This rule overrides any general "be helpful, fix it" instinct. A drive-by refactor mid-review collapses the user's mental model of what changed.
+
+## Workflow
+
+1. **Snapshot the diff.** Run in parallel:
+   - `git status --short` — see what's modified, staged, untracked.
+   - `git diff` — unstaged changes.
+   - `git diff --staged` — staged changes.
+   - `git diff <base>...HEAD` is **out of scope** here — that's `pr-review`'s job.
+2. **Understand intent.** Read the diff top-to-bottom once. If the *why* isn't obvious from context, ask the user one focused question before reviewing — "is this correct" is unanswerable without intent.
+3. **Detect test + build commands.** Inspect repo manifests in parallel and infer commands:
+   - `package.json` → `npm test`, `npm run build` (or `pnpm` / `yarn` if the lockfile says so)
+   - `pyproject.toml` / `pytest.ini` → `pytest`, plus `python -m build` or project-specific
+   - `*.csproj` / `*.sln` → `dotnet build`, `dotnet test`
+   - `go.mod` → `go build ./...`, `go test ./...`
+   - `Cargo.toml` → `cargo build`, `cargo test`
+   - `Makefile` → check for `test` / `build` targets first
+   - Monorepo (`turbo.json`, `nx.json`, `pnpm-workspace.yaml`) → use the orchestrator
+4. **Run tests, then build.** Tests first (faster signal). If tests pass, run the build. Capture output. If a command doesn't exist or fails to start, note it and continue — don't fabricate a green result.
+5. **Review.** Decide single-pass vs. lens council (see [Lens council](#lens-council-for-non-trivial-diffs)):
+   - **Single-pass (inline)** when the diff is small and tightly scoped — roughly: < 100 lines changed, < 5 files, no security-sensitive paths (auth, crypto, input validation, file/SQL/shell sinks). Walk the priority list yourself; faster on trivial changes.
+   - **Lens council** otherwise. Spawn parallel `Explore` sub-agents — one per lens — then run an adversarial critique round before reporting.
+   Earlier categories outrank later ones — a correctness bug makes a readability nit irrelevant.
+6. **Map findings to the diff.** Every finding cites `file:line` so the user can jump to it.
+7. **Categorize each finding** as `blocking` / `suggestion` / `nit` / `praise` (see [Categories](#categories)).
+8. **Produce the report** in the [Output format](#output-format).
+9. **Offer to fix.** After the report, list the fix-able findings by number and ask which to apply. Wait for confirmation. Then fix only the approved ones, one commit-worthy change at a time, and re-run tests after. When applying fixes, follow the [Code rules when applying fixes](#code-rules-when-applying-fixes) below.
+
+## Code rules when applying fixes
+
+These rules govern the fix-application phase only — they don't change the report itself.
+
+- **Minimal comments.** Default to no comments. Only add one when the *why* is non-obvious (a workaround, a non-trivial invariant, a domain rule that isn't visible from the names). Never write block headers, never restate *what* the next line does, never leave `// TODO` without an issue link. One short line max — no multi-line comment blocks, no multi-paragraph docstrings. If the fix needs a comment to be understandable, the fix probably needs better names instead.
+- **No drive-by edits.** Touch only what the approved finding requires. If you spot something else worth fixing, surface it as a *new* finding in a follow-up report — don't bundle it in.
+- **Match the project's formatting.** Don't reformat unrelated code in the diff.
+- **No `// removed`, `// was: X` trails.** If you deleted something, delete it. Git history is the audit log.
+
+## Categories
+
+- **`blocking`** — must fix before ship: bug, broken contract, security hole, build/test failure, missing migration, hard-coded secret.
+- **`suggestion`** — would improve the code; user can take or leave. DRY consolidations, dead-code removal, missing error handling on non-critical paths.
+- **`nit`** — style/preference; never blocks.
+- **`praise`** — something done well. Include at least one when there's something genuine to praise.
+
+Lead each finding with the *why*. "This swallows the exception so a failure here is silently lost" beats "add error handling".
+
+## What to look for
+
+Priority order — review top-to-bottom, stop wasting tokens on lower categories once a higher one is on fire.
+
+### 1. Correctness
+- Off-by-one in loops and slicing
+- Null / undefined / empty-collection handling at boundaries
+- Concurrent access without synchronization; race conditions in async code
+- Error paths that swallow exceptions or log-and-continue when they shouldn't
+- Default values that silently change behavior
+- Floating-point comparisons with `==`
+- Timezone / DST / locale assumptions
+
+### 2. DRY and design
+This is the user-emphasized lens — apply it explicitly.
+- **Duplication that should be unified** — same logic in 2+ places, copy-pasted blocks, parallel switch/if-else ladders, the same regex written twice.
+- **Premature abstraction** (the inverse trap) — a "shared helper" with one caller, configurable in ways nobody uses. **YAGNI** wins; three similar lines beats a wrong abstraction.
+- **Single Responsibility** — functions doing two unrelated things, classes mixing concerns.
+- **Leaky abstractions** — implementation details bleeding through an interface (e.g. ORM types in a domain API).
+- **Tight coupling** that will be painful to undo; circular dependencies.
+- **State that should live elsewhere** — module-level mutable state, globals smuggled in via singletons.
+- **Public API changes** that aren't backwards-compatible without a migration note.
+- **Magic numbers / magic strings** — name them.
+- **Composition over inheritance** where inheritance is being used as code-reuse, not for "is-a".
+
+### 3. Tests
+- Tests that pass even when the code is broken (assertion-free, over-mocked, snapshot-only).
+- Missing edge cases: empty inputs, max sizes, unicode, negative numbers, timezones, concurrent calls.
+- Flaky-by-design tests (`sleep`, ordering assumptions, network).
+- New behavior in the diff with **no new test** — call it out.
+- Test names that describe *what runs* instead of *what's verified*.
+
+### 4. Security
+- User input flowing into shell, SQL, HTML, file paths, or `eval` without escaping/parameterization.
+- Secrets in code, logs, error messages, or commit-able files.
+- Authn / authz checks missing on new endpoints or new entry points.
+- Crypto: hand-rolled, weak algos (`md5`, `sha1` for security use), hardcoded keys/IVs.
+- `console.log` / `print` / `Debug.WriteLine` of PII or tokens.
+- Unsafe deserialization of untrusted input.
+
+### 5. Performance
+- N+1 queries inside loops.
+- Unbounded memory growth — caches without eviction, accumulating arrays, recursive growth.
+- Synchronous I/O / blocking calls in hot paths or async contexts.
+- Repeated work that could be hoisted out of a loop.
+- O(n²) where O(n) is easy.
+
+### 6. Production-readiness (working-tree-specific lens)
+- **Debug residue** — `console.log`, `print`, `TODO: remove`, `// debug`, commented-out blocks, scratch files.
+- **Logging** — new code path with no log line at all, *or* spammy logs in a hot path.
+- **Observability** — new failure mode with no metric / no trace.
+- **Config** — new env var without a default and without docs / `.env.example`.
+- **Migrations** — schema change with no migration, or a migration without a rollback story.
+- **Error messages** — user-facing errors leaking stack traces, internal paths, or DB error strings.
+- **Feature flags** — new behavior shipped unflagged when the project uses flags.
+- **Backward compatibility** — breaking a wire format, DB column, or public API without a deprecation path.
+
+### 7. Readability
+- Naming: variables that say *what* (`data`, `result`) instead of *what for*.
+- Function length / nesting depth — extract when it stops fitting in your head.
+- Comments: only when *why* is non-obvious; not narration of *what*.
+- Dead code, unused imports, unused exports.
+
+### 8. Style
+Only mention if the project has no formatter / linter. Otherwise trust the tools.
+
+## Lens council (for non-trivial diffs)
+
+A single pass through the priority list anchors on whatever you saw first. For non-trivial diffs, run the lenses **in parallel** and then have them critique each other before publishing findings.
+
+### When to convene the council
+
+- Diff is ≥ ~100 lines changed, **or** touches ≥ 5 files, **or** edits security-sensitive paths (auth, crypto, input validation, SQL/shell/HTML sinks, file paths from user input).
+- Or you've already spotted contradictions on first read ("this looks broken / no it's fine because…") — the council resolves them deterministically.
+
+Otherwise stay single-pass. The council is overhead on a 20-line change.
+
+### Lenses
+
+Spawn one sub-agent per lens. Default set (skip lenses that don't apply — e.g. no schema changes → no migration sub-lens within prod-readiness):
+
+| Lens | Looks for | Aligns with |
+|---|---|---|
+| **Correctness** | Off-by-one, null/undefined, race conditions, swallowed errors, default-value behaviour shifts, tz/locale assumptions | §1 |
+| **Design / DRY** | Duplication that should unify, premature abstraction, single-responsibility violations, leaky abstractions, tight coupling, magic values, public-API breakage | §2 |
+| **Security** | Untrusted input into sinks (shell/SQL/HTML/path/`eval`), secrets in code or logs, missing authn/authz, weak crypto, unsafe deserialization | §4 |
+| **Tests** | Assertion-free / over-mocked / snapshot-only tests, missing edge cases, flaky-by-design tests, new behaviour with **no** test, test names that don't describe verification | §3 |
+| **Production-readiness** | Debug residue, missing/spammy logging, no observability on new failure modes, undocumented env vars, schema change without migration, error messages leaking internals, missing feature flag, wire/DB breakage without deprecation | §6 |
+
+Performance (§5), readability (§7), and style (§8) usually roll into Design — only spawn a dedicated lens for them if the diff is genuinely perf-sensitive or the project has no linter.
+
+### How to run it
+
+1. **Spawn in parallel.** Send a **single message** with N `Agent` calls (`subagent_type=Explore`). Each lens gets:
+   - The full diff (or the slice relevant to its files when the diff is huge).
+   - **One** lens with its checklist verbatim from [What to look for](#what-to-look-for).
+   - Instructions: "Find issues **only in your lens.** Categorize each as `blocking` / `suggestion` / `nit`. Cite `file:line` for every finding. Lead each finding with the *why*. If your lens has no findings, say 'no findings' explicitly. Report in ≤500 words."
+2. **Collect findings.** Each agent returns its list. Don't publish yet.
+3. **Critique round.** Read all lenses side by side, then do an adversarial pass before the report:
+   - **Challenge every `blocking`** — "is this actually exploitable / actually a bug / would this actually break in production?" Demote to `suggestion` or drop if the answer is no when you read the surrounding code.
+   - **Surface contradictions.** Correctness flags a missing null check, but Security found the caller validates upstream → call it out as a *question* for the user, not a flag, and link both citations.
+   - **Merge near-duplicates** across lenses (e.g. Design and Tests both noticed the new branch has no coverage — merge into one finding).
+   - **Promote** anything multiple lenses independently flagged. That's a real signal.
+4. **Publish.** Synthesize into the [Output format](#output-format). Add a footer: `Lenses run: <list>. <N> findings raised by sub-agents, <M> dropped on critique.`
+
+The user sees one clean report, not five agent transcripts. The transcripts stay internal — they were the deliberation.
+
+## Output format
+
+```
+# Code review — uncommitted changes
+
+**Files changed:** <N> (<S staged>, <U unstaged>, <X untracked>)
+
+**Build:** ✅ passed / ❌ failed / ⚠️ not detected
+**Tests:** ✅ passed (<N>/<N>) / ❌ failed (<F> failing) / ⚠️ not detected
+<paste relevant failing output, trimmed>
+
+---
+
+## Verdict
+**Ship / Fix blockers first / Build broken**
+
+<one-paragraph summary of the change and overall state>
+
+---
+
+## Blockers
+
+### B1. <short title> — `path/to/file.ext:42`
+**Why:** <root cause / consequence>
+**Fix:** <concrete recommendation>
+
+### B2. ...
+
+## Suggestions
+
+### S1. <short title> — `path/to/file.ext:88`
+**Why:** ...
+**Fix:** ...
+
+## Nits
+- `path:line` — <one-liner>
+
+## Praise
+- <thing done well>
+
+---
+
+## Fixes I can apply
+
+If you want, I can apply any of: B1, B2, S1, S3. Which? (or "all", or "none")
+```
+
+End with the offer. Wait for the user's choice. Apply only the approved set, then re-run tests.
+
+## Examples
+
+### Example 1: Working-tree review with a build failure
+
+**User:** "do a code review on what I have so far"
+
+**Claude:**
+- Runs `git status` + `git diff` + `git diff --staged` in parallel.
+- Detects `package.json` → runs `npm test` and `npm run build`.
+- Build fails on a missing import → calls it out as `B1` with the file:line, doesn't try to fix it yet.
+- Finds two copy-pasted validation blocks → `S1` (DRY consolidation) with a sketch of the extracted helper.
+- Reports, then asks: "Want me to fix B1 and S1?"
+
+### Example 2: Pre-existing tests, new feature with no coverage
+
+**User:** "is this ready to ship?"
+
+**Claude:** Reviews diff. Tests pass but the new branch in `processOrder()` has no test. Flags as `B2` (blocking — "new behavior with no test, regression risk on next refactor"). Does **not** write the test silently; offers to write it after the report.
+
+### Example 3: User pre-authorizes fixes
+
+**User:** "review the diff and fix anything you find"
+
+**Claude:** Produces the full report first anyway, then applies fixes one at a time, re-running tests between batches. Pre-authorization doesn't skip the report — it only skips the per-fix confirmation.
+
+## Anti-patterns
+
+- ❌ Editing files during the review pass. Report first, **always**.
+- ❌ Fixing without asking, even for "obvious" issues. Obviousness is not consent.
+- ❌ Skipping the test/build run because "the diff looks fine".
+- ❌ Reporting a green build without actually running it.
+- ❌ Reviewing committed history — that's [`pr-review`](../pr-review/SKILL.md)'s job. Stop at the working tree.
+- ❌ DRY-ing prematurely — calling out three similar lines as duplication when the right call is to leave them. Note the pattern; flag only when the abstraction is clearly warranted.
+- ❌ Padding the report with style nits when there are correctness blockers.
+- ❌ Hand-wavy findings without `file:line`.
+- ❌ Convening the lens council on a 15-line diff. Single-pass it.
+- ❌ Spawning the lens agents serially instead of in parallel — one message, N agents.
+- ❌ Skipping the critique round and publishing the raw union of lens findings. False-positive blockers erode trust fast.
+- ❌ Dumping the per-agent transcripts into the user's report. The council is internal deliberation — the user sees the synthesized report.
+- ✅ Tests + build run, findings cited to lines, categorized, **report → ask → fix**.
+
+## Notes
+
+- If the working tree is clean, say so and stop — there's nothing to review. Don't pivot to `pr-review` without being asked.
+- If tests take a long time, run them in the background and continue the static review while they run; reconcile the report once results land.
+- This skill composes with [`conventional-commits`](../conventional-commits/SKILL.md): after fixes are approved and applied, hand the commit-message authoring to that skill rather than improvising one here.

package/skills/codebase-explainer/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: codebase-explainer
+description: Produce a durable onboarding artifact for a codebase — writes `ONBOARDING.md` (or `docs/ONBOARDING.md` if `docs/` exists) covering a "read this first" minimum, system overview, dependency map (top-level deps + how each is actually used), startup flow (entry points → bootstrap → config), auth flow (or explicit "none detected"), and 5–15 important files — every claim backed by a `file:line` citation. Walks the repo via parallel Explore sub-agents so big projects don't blow context, calls out what makes THIS codebase non-obvious (not generic framework descriptions), refreshes an existing onboarding doc instead of rewriting from scratch, and renders a condensed summary inline. Built for revisiting a project after months away and for new teammates landing in an unfamiliar repo. Use this skill whenever the user says "explain this codebase", "explain the codebase", "onboard me", "give me a tour", "tour this repo", "what does this repo do", "where do I start", "I haven't looked at this in months", "codebase overview", "read this first", or invokes `/codebase-explainer` — even if they don't name the skill.
+---
+
+# Codebase Explainer
+
+Produce a durable onboarding artifact — the document past-you wishes you'd written before stepping away from this repo for six months. Not a chat answer that disappears: a committed `ONBOARDING.md` with a tight "read this first" list, system overview, dependency map, startup flow, auth flow, and the important files. Every claim cited with `file:line`.
+
+## When to use this skill
+
+- "explain this codebase" / "explain the codebase" / "what does this repo do"
+- "onboard me" / "give me a tour" / "tour this repo" / "where do I start"
+- "I haven't looked at this in months" / "I forgot how this works"
+- "codebase overview" / "read this first" / "create an onboarding doc"
+- `/codebase-explainer` / `/onboard`
+
+Do **not** auto-trigger for:
+
+- Architecture refactor suggestions → [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md)
+- Feature design or implementation → [`plan-and-build`](../plan-and-build/SKILL.md)
+- Bug triage → [`diagnose`](../diagnose/SKILL.md)
+- A specific diff review → [`pr-review`](../pr-review/SKILL.md) or [`code-review`](../code-review/SKILL.md)
+- Session hand-off (different artifact, session-scoped) → [`handoff`](../handoff/SKILL.md)
+
+## Workflow
+
+### 1. Detect the lay of the land (no sub-agents yet)
+
+Read root-level signals directly to scope the exploration:
+
+- **Manifests** — `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `*.sln`, `Gemfile`, `composer.json`, `pom.xml`, `build.gradle*`.
+- **Entry-point hints** — `next.config.*`, `vite.config.*`, `tsconfig.json`, `Procfile`, `Dockerfile`, `docker-compose*.yml`, `main.*`, `Program.cs`, `manage.py`.
+- **Existing docs** — `README.md`, `CONTEXT.md`, `docs/`, any `ONBOARDING.md` already present.
+- **Workspace shape** — monorepo (`pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`) vs. single project.
+
+If an `ONBOARDING.md` already exists, this is **refresh mode**: read it first, then look for drift (new top-level deps, moved entry points, new/removed routes, auth changes) and update in place — don't rewrite from scratch.
+
+### 2. Run Explore sub-agents in parallel
+
+Spawn `subagent_type=Explore` calls in a **single message** so they run concurrently. Brief each agent self-containedly — it has no conversation context. Default fan-out:
+
+- **System overview** — what this project actually does, key domains, top-level modules, public-facing surfaces (HTTP routes / CLI commands / exported APIs).
+- **Dependency map** — top-level prod deps only (skip dev/test/types). For each: what it does *in this codebase* (not generic), and the load-bearing call site (`file:line`). If a dep is genuinely non-obvious (niche library, internal fork, name that doesn't reveal its purpose), the agent MAY check `context7` (or any docs-MCP server available in the environment) for a one-line "what is this library" — `context7__resolve-library-id` → `context7__query-docs`. Skip the lookup for well-known libraries (React, Express, Prisma, etc.) — the *generic* description is what we're trying to avoid; what matters is how it's used *here*.
+- **Startup flow** — entry point → bootstrap → config loading → server start. A numbered sequence with `file:line` per step.
+- **Auth flow** — login/session/token handling, middleware/guards, user model, where authorization decisions are made. If none, the agent must say "no auth detected" explicitly so Step 3 doesn't fabricate one.
+- **Important files** — the 5–15 files a new contributor *must* know about, each with a one-line "why it matters."
+
+Each agent reports back in ≤300 words with `file:line` citations. Don't ask Explore to read entire files — ask for the specific answer plus citations.
+
+### 3. Synthesize ONBOARDING.md
+
+Write the artifact to `docs/ONBOARDING.md` if a `docs/` directory exists, otherwise `ONBOARDING.md` at repo root. Sections, in this order:
+
+1. **Read this first** — 3–7 bullets max. The minimum a fresh contributor needs to not be dangerous.
+2. **System overview** — 1–3 paragraphs. What it does, who it serves, the dominant architectural shape.
+3. **Startup flow** — numbered, with `file:line` per step.
+4. **Auth flow** — same shape, or a one-liner "No authentication layer — this is X" if the agent confirmed none.
+5. **Dependency map** — table: `Dependency | What it does here | Key call site`.
+6. **Important files** — bulleted list with `file:line` and a one-line "why it matters."
+7. **Project glossary** *(optional)* — only if `CONTEXT.md` exists or domain terms surfaced repeatedly during exploration.
+8. **Footer** — one line: *"Generated by `/codebase-explainer`. Re-run to refresh."*
+
+No timestamps in the file body (dates rot). The git history is the timestamp.
+
+### 4. Render a condensed summary inline
+
+After writing the file, render in chat: the "Read this first" bullets verbatim, plus a one-sentence pointer to the file path. Do **not** re-paste the full document — the file is the artifact.
+
+### 5. Offer the share step (optional)
+
+If making this teammate-accessible would help, mention `ShareOnboardingGuide` — it uploads `ONBOARDING.md` and returns a link. Offer once; never auto-invoke.
+
+## Examples
+
+### Example 1: First pass on a six-month-old project
+
+**User:** "I haven't touched this repo since November — onboard me"
+
+**Claude:**
+1. Reads `package.json`, `next.config.ts`, `prisma/schema.prisma`, existing `README.md`. Notes: Next.js App Router + NextAuth + Prisma + Postgres.
+2. Spawns five Explore agents in parallel (overview, deps, startup, auth, important files) in one message.
+3. Synthesizes → writes `ONBOARDING.md` with startup flow rooted at `app/layout.tsx:12` → `lib/auth.ts:34` and auth flow citing the NextAuth `authOptions` and the `requireSession()` helper.
+4. Prints the "Read this first" bullets and the file path. Offers `ShareOnboardingGuide`.
+
+### Example 2: Refresh against an existing onboarding doc
+
+**User:** "/codebase-explainer — refresh the onboarding doc, I added Stripe and a new admin route last sprint"
+
+**Claude:**
+1. Reads existing `docs/ONBOARDING.md`. Spawns Explore agents scoped to "what's changed": new top-level deps, new routes under `app/**/route.ts`, auth changes.
+2. Updates the dependency map (Stripe row added with `lib/payments/stripe.ts:18` citation), appends the admin route to startup flow, leaves untouched sections alone.
+3. Reports a diff-style summary in chat: "+1 dep, +1 route, auth unchanged."
+
+## Anti-patterns
+
+- ❌ Generic framework descriptions ("This is a Next.js app."). Call out what makes THIS codebase non-obvious — the custom session helper, the funky background job runner, the legacy module that traps newcomers.
+- ❌ Listing every dependency including dev/test/types. Prod + top-level only.
+- ❌ "Important files" with 40 entries. 5–15 is the budget. If you can't pick, you don't understand the codebase yet — Explore more.
+- ❌ Inventing an auth flow when there isn't one. If the agent reports no auth, the section says "No authentication layer." That's load-bearing information for a future reader.
+- ❌ Reading whole source files into the main context. Sub-agents return summaries with `file:line` citations — trust them.
+- ❌ Claims without `file:line` citations. A claim the next reader can't verify rots fast.
+- ❌ Hard-coded dates ("as of November 2025") in the file body. Git history is the timestamp.
+- ❌ Rewriting an existing `ONBOARDING.md` from scratch when the user asked to refresh.
+- ✅ Tight "read this first," cited everywhere, explicit about absences, refreshable.
+
+## Notes
+
+- **Composes with** [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md): an onboarding pass often surfaces shallow-module clusters worth a deepening review. Hand the user a pointer; don't propose refactors here.
+- **Composes with** [`handoff`](../handoff/SKILL.md): `ONBOARDING.md` is project-level orientation (durable across many sessions); a handoff is session-level state. Different artifacts, both useful.
+- **Composes with** [`grill-with-docs`](../grill-with-docs/SKILL.md): if exploration surfaces fuzzy domain terminology, a follow-up grilling pass to populate `CONTEXT.md` makes future onboarding sharper.
+- `ShareOnboardingGuide` (when available in the environment) uploads `ONBOARDING.md` and returns a teammate-shareable link. Optional; user-initiated.