@dennisrongo/skills 0.3.0 → 0.5.0

package/README.md

@@ -103,6 +103,8 @@ 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`. |
+| [`task-executor`](./skills/task-executor/SKILL.md) | Disciplined execution loop for a single, already-defined task — Understand → Inspect → Plan → Execute incrementally → Validate after every change → Track assumptions → Update progress. Forces a strict per-turn output format with six fixed sections (**Goal** / **Current understanding** / **Files to inspect** / **Plan** / **Progress** / **Risks** / **Assumptions**) so the work stays legible and resumable instead of devolving into ad-hoc edits across turns. When the inspection working set spans multiple layers (controller + service + persistence + tests), Phase 2 convenes an **inspection council**: parallel `Explore` sub-agents — one per layer slice — each map their area and return `file:line`-cited findings on existing patterns, wiring points, and sibling test classes; the main session aggregates the results into `Current understanding` so the working context window stays free for the strict per-turn output the executional phase keeps emitting. Small inspection sets (≤ ~5 files, one layer) skip the council and read inline. Enters Plan Mode after inspection and gates on `ExitPlanMode` approval before writing any code; every plan step is then one logical change followed by an immediate validation (test, build, type-check, curl, page load) before the next checkbox ticks. Assumptions are tracked explicitly until confirmed by code or the user — and promoted into `Current understanding` or killed, never silently carried. Composes downward from [`plan-and-build`](./skills/plan-and-build/SKILL.md) (which interviews the user to design the feature) and routes back to it when the user invokes this skill on a fuzzy spec. Triggers on `/task-executor`, "Work on task: …", or any concrete, already-defined task handed to Claude for execution. |
 | [`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.5.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).

package/skills/task-executor/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: task-executor
+description: Disciplined execution loop for a single defined task — Understand → Inspect → Plan → Execute incrementally → Validate after every change → Track assumptions → Update progress. Forces a strict per-turn output format (Goal / Current understanding / Files to inspect / Plan / Progress / Risks / Assumptions) so the work stays legible and resumable instead of devolving into ad-hoc edits. When the inspection set spans multiple layers (controller + service + persistence + tests), Phase 2 convenes an **inspection council**: parallel `Explore` sub-agents — one per layer — each map their slice and return `file:line`-cited findings on existing patterns, wiring points, and sibling test classes; the main session aggregates the results into `Current understanding` so the working context window stays free for execution. Small inspection sets skip the council. Enters Plan Mode after inspection and gates on `ExitPlanMode` approval before writing any code. Each incremental change is followed by a validation step (run the test, build, type-check, or curl the endpoint) before moving to the next checkbox. Use this skill whenever the user says "/task-executor", "Work on task: <description>", "task-executor", or hands you a single concrete task to execute with discipline — even if they don't name the skill. Do **not** auto-trigger on greenfield feature design with a fuzzy spec — use [`plan-and-build`](../plan-and-build/SKILL.md) instead, which interviews the user to design the feature before this skill's executional discipline applies.
+---
+
+# Task Executor
+
+A discipline for working on a single, already-defined task. The task is given; the goal is to execute it without skipping context, without batching changes, and without losing the thread mid-way. Every turn emits the same six sections so the user (and any future session) can pick up the state at a glance.
+
+## When to use this skill
+
+- The user runs `/task-executor` or types "task-executor".
+- The user says "Work on task: …" with a concrete task description (a ticket, a bullet, a paragraph spec).
+- The user hands you a defined deliverable and asks you to execute it — not to design it from scratch.
+
+Do **not** use this skill for:
+
+- Fuzzy or greenfield feature work where the spec still needs grilling. Use [`plan-and-build`](../plan-and-build/SKILL.md) for that — it includes the interview phase this skill skips.
+- Bug diagnosis. Use [`diagnose`](../diagnose/SKILL.md).
+- One-line fixes, renames, doc edits — the per-turn output format is more ceremony than value at that size.
+
+If the user invokes this skill on a spec that turns out fuzzy mid-flight, stop and recommend `plan-and-build` rather than pretending the spec is clear.
+
+## The per-turn output format (non-negotiable)
+
+Every assistant turn during this skill — from the first response to the final report — opens with these six sections, in this order, with exactly these headers. Sections that have nothing yet say `_(none yet)_` rather than being omitted, so the structure stays scannable.
+
+```markdown
+## Goal
+<one short paragraph — the task in the user's terms, restated>
+
+## Current understanding
+<what is now known about the task, the code, the constraints — updated each turn>
+
+## Files to inspect
+- path/to/file1.ext — why
+- path/to/file2.ext — why
+
+## Plan
+1. Step
+2. Step
+3. Step
+
+## Progress
+- [x] Completed step (with one-line evidence: test passing, command output, file written)
+- [ ] Pending step
+- [ ] Pending step
+
+## Risks
+- Risk or open question
+- Risk or open question
+
+## Assumptions
+- Assumption being relied on that has NOT been confirmed by code or the user
+- Assumption being relied on that has NOT been confirmed by code or the user
+```
+
+Rules:
+
+- **Restate the goal verbatim each turn.** It anchors against drift. If the user redirects, update the goal and note the redirect in `Current understanding`.
+- **Files to inspect is a live list.** Add as you discover relevance; mark a file as inspected by moving it into `Current understanding` with what you learned. Don't carry a file in both places.
+- **Progress checkboxes are append-only across turns.** Never silently delete a step — if a step is dropped, leave it ticked or struck and explain in `Current understanding`.
+- **Assumptions get promoted or killed.** When you confirm an assumption (by reading the code, running the loop, or asking the user), move it into `Current understanding` as a fact and remove it from `Assumptions`. When you falsify one, say what changed.
+
+If the conversation runs long and the sections grow, **compact** rather than truncate: collapse old completed steps into a one-line summary at the top of `Progress` and keep the active checkboxes verbatim.
+
+## Phases
+
+### Phase 1 — Understand
+
+Restate the task back to the user in your own words inside the `Goal` section of the first turn. Surface anything ambiguous as a `Risks` item or, if it blocks design, ask **one** clarifying question with `AskUserQuestion`. Do not interview broadly — this skill assumes the spec is given. If you find yourself with more than two clarifying questions, stop and recommend `plan-and-build`.
+
+Specifically capture in `Current understanding`:
+
+- What done looks like (the user's acceptance criteria, or your inferred version if they didn't state one).
+- Constraints that are stated, not inferred (auth model, framework, persistence, naming).
+- Anything the user said NOT to do.
+
+Anything you're filling in by inference goes into `Assumptions`, not `Current understanding` — until it's confirmed.
+
+### Phase 2 — Inspect
+
+Before drafting a plan, read the relevant code. Populate `Files to inspect` as a working set, then actually read them — don't list-and-skip. Use `Glob` / `Grep` / `Read` in parallel where the lookups are independent. Stop reading when you understand:
+
+- The existing pattern for whatever layer this task touches (controller, page, service, hook, migration).
+- The wiring points the new code needs to hook into (DI registration, route table, exports, schema).
+- Any sibling test class or test file the new tests should be appended to.
+
+Move each inspected file from `Files to inspect` into `Current understanding` with a one-line takeaway. Skip generic file summaries — note only the takeaway that affects the plan.
+
+#### Decision gate: inline reads vs. inspection council
+
+Be honest about scope before deciding. Manufacturing a sub-agent council for a three-file task is ceremony.
+
+- **Inline reads (default)** when the inspection set is ≤ ~5 files or stays inside one layer / module. Read them directly with `Read` (in parallel) and roll the takeaways into `Current understanding`.
+- **Inspection council** when the set spans ≥ 2 distinct layers (e.g. controller + service + persistence + tests) and the total reading is wide enough that doing it inline would burn the main context — especially since every turn of this skill re-emits the six-section output block. The council protects the working window so you can still execute cleanly over many turns.
+
+#### Inspection council (parallel `Explore` sub-agents)
+
+When convened:
+
+1. **Slice by layer / area.** Name 2–4 distinct slices of the codebase the plan will touch (e.g. *Controller + routing*, *Service / domain*, *Persistence + migrations*, *Tests + fixtures*). Each slice gets one sub-agent. Slices must be non-overlapping — if two slices would re-read the same files, merge them.
+2. **Spawn in parallel.** Send a **single message** with N `Agent` calls using `subagent_type=Explore`, one per slice. Each agent gets a self-contained brief:
+   - The verbatim task (the `Goal` paragraph).
+   - The one slice it owns and what to map within it.
+   - What to report: existing pattern for that layer, wiring points the new code must hook into, sibling test class / test file to append to, any forbidden-pattern signals (e.g. "no `ExecuteSqlRaw`", "no direct `fetch` in server components"), and `file:line` citations for every claim.
+   - Hard constraint: "Do not propose a plan. Do not invent. If you cannot find an existing pattern in your slice, say so explicitly — do not fabricate."
+   - Length cap: ≤ 300 words.
+3. **Aggregate, don't duplicate.** When all sub-agents return, merge their findings into `Current understanding` as one consolidated picture — not four parallel sections. Each finding keeps its `file:line` citation. Anything no sub-agent could find a pattern for goes into `Assumptions` (you'll be inventing it; that needs to be visible).
+4. **Re-emit the six-section output** with the consolidated `Current understanding` before moving to Phase 3.
+
+The point isn't "more agents = better." It's that wide inspection eats the main context window and the per-turn output format eats it again every turn — the council pushes the reading off-window so the executional phase still has room to breathe.
+
+**Library API check.** If the plan depends on a specific third-party library / framework symbol (e.g. EF Core, Prisma, NextAuth, Stripe SDK), and the version is pinned in this repo, query `context7` for the current docs before drafting the plan. Training-data API knowledge can be a major version behind.
+
+### Phase 3 — Plan (gate on approval)
+
+Draft the `Plan` section as a numbered list of concrete, verifiable steps. Each step is one logical change with a clear validation method.
+
+Then enter Plan Mode (`EnterPlanMode`) and present the plan along with the rest of the per-turn output. Call `ExitPlanMode` and **wait**. Do not write a single file until the user approves the plan.
+
+If the user pushes back, revise and re-present. Do not partial-implement against an unapproved plan.
+
+### Phase 4 — Execute incrementally
+
+Walk the plan one step at a time. For each step:
+
+1. **Make the smallest change that completes the step.** No drive-by refactors, no "while I'm here" fixes, no batched edits across multiple steps.
+2. **Validate immediately.** Run the test, build, type-check, lint, curl the endpoint, or load the page — whichever signal is appropriate for that step. If there's no automated signal at all, say so explicitly in `Progress`; don't pretend there is one.
+3. **Tick the checkbox** with a one-line evidence note (`tests pass`, `dotnet build green`, `200 OK with expected body`).
+4. **Re-emit the full per-turn output** before moving to the next step.
+
+When a validation fails:
+
+- Do not move on.
+- Add the failure mode to `Risks`.
+- Diagnose in place (one focused investigation, not a tangent). If it turns into a real debugging session, suggest dropping into `diagnose` and pausing this skill.
+
+When you find new files you need to read mid-execution, add them to `Files to inspect` rather than reading silently. The list is the audit trail.
+
+### Phase 5 — Final validation and report
+
+When every checkbox is ticked:
+
+- Re-run the full validation suite for the task (tests + build + any acceptance criteria from `Current understanding`).
+- Emit one last full per-turn output where `Progress` is entirely `[x]`, `Assumptions` is empty (or each remaining assumption is justified as out-of-scope), and `Risks` lists anything the user should know about that wasn't part of the task.
+- End with one short paragraph: what changed, what to run, what's deliberately not done.
+
+## Anti-patterns
+
+- ❌ Omitting sections "because nothing changed". The structure exists precisely so a future session can resume — write `_(none yet)_` instead.
+- ❌ Skipping inspection because the answer "looks obvious". The cost of being wrong is much higher than the cost of one extra `Read`.
+- ❌ Batching multiple plan steps into a single change and ticking them together. The validation-per-step is the discipline; collapsing it loses the value.
+- ❌ Treating an unconfirmed inference as `Current understanding`. Anything you're betting on without evidence is an `Assumption` until proven.
+- ❌ Drifting from the strict header set ("here's a quick update" prose-only turns). One ad-hoc turn becomes ten.
+- ❌ Running this skill on a fuzzy spec. Stop and route to [`plan-and-build`](../plan-and-build/SKILL.md) — its Phase 1 grill is what's missing.
+- ❌ Exiting Plan Mode while the plan still has open questions or assumptions that materially change the design.
+- ❌ Continuing past a failed validation. A red test is a Phase-4 stop, not a TODO for later.
+- ❌ Inventing new abstractions when an existing pattern in the repo would have answered the same need. The inspection phase exists to prevent this.
+- ❌ Convening the inspection council for a 3-file task. Ceremony for its own sake. Inline reads are the default — escalate only when the inspection set genuinely spans multiple layers.
+- ❌ Spawning the inspection sub-agents serially instead of in parallel — one message, N `Agent` calls. Serial defeats the context-protection rationale.
+- ❌ Letting a sub-agent slice overlap with another's. If two slices would re-read the same files, merge them first.
+- ✅ Same six headers every turn, one step at a time, one validation per step, assumptions tracked explicitly until confirmed or killed.
+
+## Examples
+
+### Example 1: A concrete task with a defined scope
+
+**User:** "/task-executor — Work on task: Add a Stripe subscriptions webhook endpoint that records subscription state changes in our existing `Subscriptions` table."
+
+**Claude:**
+
+1. **Phase 1 — Understand.** First turn opens with all six headers. `Goal` restates the task. `Current understanding` notes "endpoint must verify Stripe signature; state changes recorded in existing `Subscriptions` table". `Assumptions` lists "endpoint lives under `/api/webhooks/stripe`" (not yet confirmed) and "no new table needed".
+2. **Phase 2 — Inspect.** Populates `Files to inspect` with `BillingService.cs`, `Subscriptions.cs` (the entity), `appsettings.json` (for the webhook secret), one existing webhook endpoint as a pattern reference. Reads them in parallel, then moves each into `Current understanding` with a one-line takeaway. Confirms the assumption about the route (or revises it).
+3. **Phase 3 — Plan.** Enters Plan Mode. Plan lists: (1) add `StripeWebhookController` with signature verification, (2) extend `BillingService.HandleSubscriptionEvent`, (3) wire DI, (4) append three NUnit tests to `BillingServiceTests`, (5) run `dotnet test`, (6) run `dotnet build`. Calls `ExitPlanMode` and waits.
+4. **Phase 4 — Execute.** Step (1): writes the controller, runs `dotnet build`, ticks `[x] controller scaffolded — build green`. Re-emits all six sections. Step (2): writes the service method, writes the first test, runs `dotnet test` — red for the right reason, then green after implementation, ticks. Continues one at a time.
+5. **Phase 5 — Report.** Final turn shows every step `[x]`, lists files written, gives the exact command for the user to test the endpoint locally with Stripe CLI.
+
+### Example 2: User invokes the skill on a fuzzy spec
+
+**User:** "/task-executor — Build the subscription management area."
+
+**Claude:** First turn opens with the six headers anyway. `Goal` restates what the user said. `Current understanding` flags that "subscription management area" is undefined (pages? roles? actions? entry point?). `Risks` lists three or four concrete ambiguities. Then a single short paragraph at the end: "This spec is too fuzzy for `task-executor`. Recommend dropping into [`plan-and-build`](../plan-and-build/SKILL.md) — its Phase 1 grill is what's needed before this skill's discipline applies. Want me to switch?"
+
+### Example 3: A validation fails mid-execution
+
+**User:** Mid-task. Claude has ticked steps 1–3 and just ran the tests for step 4.
+
+**Claude:** Re-emits all six sections. `Progress` shows step 4 unchecked with a one-line note `tests failed — NullReferenceException at BillingService.cs:84`. `Risks` adds the failure. `Current understanding` notes the call site. Diagnoses in place — one targeted read, one minimal fix, re-runs. If the fix is one-line and obvious, ticks the step and continues. If the failure spreads or the cause is non-obvious, suggests pausing this skill and dropping into [`diagnose`](../diagnose/SKILL.md).
+
+## Notes
+
+- This skill composes downward from [`plan-and-build`](../plan-and-build/SKILL.md): once `plan-and-build` lands an approved plan, you can hand the steps to `task-executor` for the disciplined incremental execution. The skills overlap in Plan Mode usage but differ in upstream phases — `plan-and-build` interviews and detects stack; `task-executor` assumes the spec is given and forces output discipline every turn.
+- The six-header format is deliberately rigid. It's the part of the skill that loses value the moment you let it slip — one ad-hoc turn breaks the contract.
+- If the task is small enough that the six-section output dwarfs the actual work, the task is too small for this skill. Just do it.