@dennisrongo/skills 0.3.0 → 0.4.0

package/README.md

@@ -103,6 +103,7 @@ node bin/claude-skills.js list
 | [`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`. |
+| [`ship-it`](./skills/ship-it/SKILL.md) | Pre-launch **operational-readiness** gate for a feature, release, or branch — the complement to [`code-review`](./skills/code-review/SKILL.md). Walks a fixed 10-category checklist (logging, error handling, telemetry, feature flags, migrations, rollback strategy, secrets, local-first storage, auth, update strategy) against the named scope and produces a structured report with PASS / GAP / N/A per item — every PASS backed by a `file:line` citation, every GAP labelled `no evidence found at <path>`, every N/A justified in one line. The final verdict groups findings as **Blocking** (secrets in code, missing authz on a new endpoint, destructive migration without rollback, no way to disable the change in prod) / **Should-fix** / **N/A with reason** / **Passing**, then asks per-blocker whether to draft a fix. **Never edits code unprompted** and **forces scope before auditing** — a PR, a flag, a release tag, or a module — so the output stays actionable. Distinct from `code-review` (diff quality) and `pr-review` (branch / per-task review): `ship-it` is the operational gate that catches what diff-level reviews don't surface. Triggers on "is this ready to ship?", "ship-it check", "production checklist", "pre-launch checklist", "release readiness", or `/ship-it`. |
 | [`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". |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dennisrongo/skills",
-  "version": "0.3.0",
+  "version": "0.4.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/ship-it/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: ship-it
+description: Pre-launch operational-readiness checklist for a feature, release, or branch. Walks a fixed 10-category gate (logging, error handling, telemetry, feature flags, migrations, rollback, secrets, local-first storage, auth, update strategy), produces a structured report with PASS / GAP / N/A per item, every PASS backed by `file:line` evidence and every GAP cited as `no evidence found at <path>`. Final verdict groups findings as **Blocking** / **Should-fix** / **N/A with reason** / **Passing**. Use this skill whenever the user says "is this ready to ship?", "ship-it check", "/ship-it", "production checklist", "pre-launch checklist", "production readiness", "release readiness", "launch checklist", or asks whether a release is operationally safe — even if they don't explicitly say "ship-it skill". Use [`code-review`](../code-review/SKILL.md) for diff-level code quality (DRY, dead code, tests). Use `ship-it` for cross-cutting operational readiness. Never edits code unprompted — recommendation first, ask, then fix.
+---
+
+# Ship It
+
+The operational gate I run before calling something done. Code review tells me the diff is clean; `ship-it` tells me the thing won't page me at 3am.
+
+## When to use this skill
+
+- "is this ready to ship?" / "ship-it check" / "/ship-it"
+- "production checklist" / "pre-launch checklist" / "production readiness" / "release readiness" / "launch checklist"
+- "can we deploy this?" / "anything missing before we ship?"
+- The user names a branch, PR, release tag, or module and asks whether it's safe to release.
+
+Do **not** auto-trigger when the user is asking about diff-level code quality, DRY, dead code, or test coverage — that's [`code-review`](../code-review/SKILL.md)'s job. If the trigger is ambiguous (e.g. bare "ready to ship?" with a working tree full of uncommitted edits), ask once whether they want the diff review or the operational checklist.
+
+## Hard rules
+
+- **Recommend, don't refactor.** This is an audit. Never edit code unprompted. After the report, ask per-blocker whether the user wants a fix drafted.
+- **Evidence is mandatory.** Every PASS must cite `file:line`. "I checked, it looks fine" is not a PASS — that's a GAP labelled `couldn't verify`.
+- **N/A needs a reason.** Mark a category N/A only with a one-line justification (e.g. *"server-only service, no local storage layer"*). Don't fabricate gaps for categories that don't apply.
+- **Stay in your lane.** Don't re-do `code-review`'s work. If the user asks about DRY / dead code / test coverage, defer.
+
+## Workflow
+
+### Phase 1 — Name the unit being shipped
+
+Don't proceed until scope is named. Ask the user with `AskUserQuestion` if it isn't obvious:
+
+- A specific PR / branch? → `git diff` against the base; scope the audit to changed files + their direct call graph.
+- A feature flag? → grep the flag key; scope to gated code paths.
+- A release tag / version bump? → `git diff <prev-tag>..HEAD`.
+- A module / directory? → scope to that path.
+
+Echo the scope back in one line before starting Phase 2 (*"Auditing branch `feat/billing-v2` against base `main` — 14 files changed."*).
+
+### Phase 2 — Walk the 10 categories
+
+For each category: state the criterion in one line, search the codebase for evidence, mark PASS / GAP / N/A. Use `Grep` and `Read` aggressively; spawn an `Explore` sub-agent for any category where the search would take more than 3 queries.
+
+#### 1. Logging
+
+**What good looks like:** Structured logs (JSON or key=value), correlation / request IDs propagated, levels used correctly (`error` ≠ `info`), no secrets / tokens / PII in log output, errors logged with stack + context, not just the message.
+
+**How to check:** Grep for the logger import and inspect call sites in changed files. Confirm a request-ID middleware exists upstream and that the new code paths inherit it. Grep for known secret-shaped variables being passed to log calls.
+
+#### 2. Error handling
+
+**What good looks like:** Each failure mode named (network, validation, auth, downstream 5xx), no `catch {}` / `except: pass` / `_ = ...` silent swallows, user-facing errors mapped to safe messages, retry / backoff on external-boundary calls (HTTP, DB, queues).
+
+**How to check:** Grep for empty catches, bare `except`, error-swallowing patterns. Trace each new external call to see how failures propagate. Confirm idempotency where retries exist.
+
+#### 3. Telemetry
+
+**What good looks like:** New code paths emit metrics (counts, latencies, error rates), traces propagate (OpenTelemetry / equivalent context passed through), dashboards / alerts updated to include the new signal.
+
+**How to check:** Grep for the metrics client in changed files. Confirm at least one counter and one latency histogram per significant code path. Ask the user whether the dashboards / alerts were updated — that's usually out-of-tree.
+
+#### 4. Feature flags
+
+**What good looks like:** New behavior gated behind a flag with a clear owner, documented default state for prod (almost always `off`), and a written ramp / cleanup plan (when does the flag get removed?).
+
+**How to check:** Grep for the flag client; confirm new branches are gated. Read the flag definition file / dashboard config for owner + default. Ask the user for the cleanup plan if it isn't in the PR description.
+
+#### 5. Migrations
+
+**What good looks like:** Forward-compatible — the deployed code tolerates BOTH old and new schema for at least one release. Backfill plan named if columns are added. Runtime estimated against prod-size data (not just dev).
+
+**How to check:** Read the migration files. Look for `ALTER TABLE` against large tables — flag any that take exclusive locks. Confirm the matching code reads `column ?? fallback` rather than assuming the new shape exists. Ask about backfill strategy.
+
+#### 6. Rollback strategy
+
+**What good looks like:** The change can be reverted by redeploying the previous artifact. Flag-on / flag-off is the rollback path where possible. Migrations are split from code deploys so revert never requires a DB rollback. There's a one-liner in the runbook.
+
+**How to check:** Look for the runbook entry. Confirm migrations were merged in a separate commit / PR from the feature code (the "expand / migrate / contract" pattern). If a migration is destructive (DROP, NOT NULL added) call it out as blocking unless a rollback plan exists.
+
+#### 7. Secrets
+
+**What good looks like:** No secrets in code, config files, or logs. Rotation path documented. New env vars added to the secret store (Vault / AWS SM / Doppler / etc.), not just `.env.example`.
+
+**How to check:** Grep changed files for high-entropy strings, common key shapes (`AKIA…`, `sk_live_`, `xoxb-`), and `.env*` diffs. Confirm any new env var also exists in the secret-store config (Terraform / Helm values / etc.).
+
+#### 8. Local-first storage *(skip with N/A for pure server services)*
+
+**What good looks like:** Offline behavior defined (queue + replay, or fail-fast), conflict resolution rule named for sync (last-writer-wins, CRDT, merge UI), schema version in the local DB, migration handles users upgrading from an older client.
+
+**How to check:** Find the local store (IndexedDB / SQLite / Realm / AsyncStorage). Read its schema-version handling and migration code. If the PR changes the local schema, confirm the upgrade path exists.
+
+#### 9. Auth
+
+**What good looks like:** New endpoints / screens have **authorization** checks (not just authentication), tenant / org scoping enforced server-side (never trust client-sent IDs), no IDOR — `GET /orders/:id` verifies the order belongs to the caller — session / token handling unchanged or explicitly reviewed.
+
+**How to check:** For each new route, read the handler top-to-bottom. Confirm: caller identity comes from the session, the resource is loaded scoped to that identity, no `where: { id: req.params.id }` without a tenant predicate. Missing authz on a new route is **blocking**.
+
+#### 10. Update strategy
+
+**What good looks like:** How users get the new version is named and tested.
+- **Web:** deploy + cache-bust (hashed assets, SW update flow if applicable).
+- **Desktop (Tauri / Electron):** auto-update channel signed and pointed at the right manifest.
+- **Mobile:** store review window accounted for, forced-update path for breaking API changes.
+- **CLI / SDK:** version pinning respected, breaking changes major-bumped.
+
+**How to check:** Identify the artifact type and ask the user how the rollout happens. For desktop, read the updater config. For mobile + breaking changes, confirm there's a min-version-supported check on the backend.
+
+### Phase 3 — Produce the report
+
+Group findings into four buckets. Order matters — blocking first.
+
+```markdown
+# Ship-It Report — <scope>
+
+## Blocking
+- **<category>:** <one-line problem> — `<file:line>` or `no evidence found at <path>`
+
+## Should-fix (non-blocking)
+- **<category>:** <one-line problem> — `<file:line>`
+
+## N/A
+- **<category>:** <one-line reason>
+
+## Passing
+- **<category>:** <one-line evidence> — `<file:line>`
+```
+
+**Blocking = any one of:**
+- Secrets in code / logs / committed config.
+- Missing authz on a new endpoint or screen.
+- Destructive migration with no rollback plan.
+- No way to disable the new behavior in prod (no flag, no quick revert).
+- Update strategy genuinely absent for the artifact type.
+
+Everything else is should-fix.
+
+### Phase 4 — Offer to fix
+
+After the report, ask: *"Want me to draft fixes for the blocking items, or stop at the report?"* Wait for explicit go-ahead before editing.
+
+## Examples
+
+### Example 1: PR-scoped audit
+
+**User:** "is this ready to ship?" *(currently on branch `feat/billing-v2` with an open PR)*
+
+**Claude:**
+1. Echoes scope: *"Auditing `feat/billing-v2` against `main` — 14 files changed."*
+2. Walks the 10 categories, citing `file:line` per finding.
+3. Reports: 2 blocking (missing authz on `POST /api/v2/invoices`, no rollback for the `currency_code NOT NULL` migration), 4 should-fix, 1 N/A (local-first storage — server-only), 3 passing.
+4. Asks whether to draft fixes for the blockers.
+
+### Example 2: Module-scoped audit
+
+**User:** "ship-it check on the billing module"
+
+**Claude:**
+1. Scopes to `src/billing/**` (confirms the path exists first).
+2. Skips the "diff vs base" framing — runs the 10 categories against the module's current state.
+3. Marks update-strategy as N/A *("module is consumed by the web app's update flow — covered there, not here")* with a pointer to where it IS covered.
+
+### Example 3: Anti-pattern — wrong skill
+
+**User:** "review my diff"
+
+**Claude:** "That's [`code-review`](../code-review/SKILL.md)'s territory — diff-level quality, DRY, tests. `ship-it` is for the operational gate (logging, flags, migrations, rollback, auth, etc.). Want me to run `code-review` instead, or did you mean the operational checklist?"
+
+## Anti-patterns
+
+- ❌ Marking a category PASS without a `file:line` citation. "Looks fine" is a GAP labelled `couldn't verify`.
+- ❌ Inventing GAPs in N/A categories. A server-only service genuinely has no local-first storage layer — say so and move on.
+- ❌ Reviewing diff quality (DRY, dead code, missing tests) under the ship-it banner. Defer to `code-review`.
+- ❌ Editing code mid-audit. The report comes first, then the user picks what to fix.
+- ❌ Blocking on every missing dashboard or runbook entry. Telemetry without a dashboard is should-fix. Telemetry with secrets in the log line is blocking. Calibrate.
+- ❌ Letting Phase 1 slide. Auditing "the whole repo" produces unactionable output. Force a scope.
+
+## Notes
+
+- Categories 1–7 + 9 apply to almost any service. Category 8 (local-first storage) is N/A for pure server work. Category 10 (update strategy) is where most teams underinvest — push on it.
+- The 10-category list is deliberately fixed. Don't extend it ad-hoc — if you find yourself wanting to add "performance" or "i18n" as a category, that's a separate skill or a should-fix entry under the closest existing category.
+- Pairs well with [`code-review`](../code-review/SKILL.md) (run code-review first for diff quality, then ship-it for operational readiness) and [`handoff`](../handoff/SKILL.md) (capture the report as the next-session pointer if shipping is deferred).