agentscamp 0.1.0

package/content/skills/adr-writer.md

@@ -0,0 +1,90 @@
+---
+name: "adr-writer"
+description: "Write an Architecture Decision Record capturing a decision the user describes, in Michael Nygard ADR format (Status, Context, Decision, Consequences) with an added Considered Alternatives section. Use when recording a significant architectural or technology choice."
+allowed-tools: "Read, Grep, Glob, Write"
+version: 1.0.0
+---
+
+Turn an architectural decision into a durable, reviewable record. The skill takes the decision the user describes, gathers the real constraints that shaped it from the repository, and writes a Nygard-style Architecture Decision Record — context and problem, the decision and its status, the consequences, and the alternatives that were considered and rejected. The result is a numbered, immutable document that explains *why* a choice was made to whoever reads the code in two years.
+
+## When to use this skill
+
+- You made a consequential, hard-to-reverse choice (datastore, framework, auth model, sync vs. async, monorepo vs. polyrepo) and want the reasoning captured before it's forgotten.
+- You're starting an ADR log in a repo that has none, or adding the next record to an existing `docs/adr/` directory.
+- A pull request changes architecture and a reviewer asked "where is this written down?"
+- You're revisiting an old decision and need to supersede it with a new record instead of silently editing history.
+
+> [!NOTE]
+> An ADR is immutable once merged. You don't edit a decision to change it — you write a new ADR that supersedes it and flip the old one's status to `Superseded by ADR-NNNN`. Editing the substance of a merged record erases the history the log exists to preserve.
+
+## Instructions
+
+1. **Locate the ADR log.** Search for an existing directory — `docs/adr/`, `docs/decisions/`, `doc/adr/`, or `adr/`. Read one or two existing records to match the local heading set, status vocabulary, and front-matter (some logs use `MADR`, some `Nygard`, some carry a `date:`/`deciders:` block). If no log exists, default to `docs/adr/`.
+2. **Assign the number and slug.** Find the highest existing `NNNN-*.md` and increment it, zero-padded to four digits (`0001`, `0002`, ...). Build the filename as `docs/adr/NNNN-kebab-title.md` from a short, decision-focused title (`0007-use-postgres-for-primary-store.md`). Never reuse or renumber an existing file.
+3. **Detect the real constraints — don't invent them.** Mine the repo for evidence that shaped the decision instead of writing generic pros and cons:
+   - Read `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` for the current stack and what's already a dependency.
+   - Grep for the systems in play (`grep -ri "mongoose\|prisma\|pg\|sqlalchemy"`) to see what's actually wired up.
+   - Check `docker-compose.yml`, `*.tf`, CI config, and any `README`/`CLAUDE.md` for deployment targets, scale signals, and stated team conventions.
+   - Note the requirement that forces the decision (transactions, relational queries, a managed offering already in the cloud account, an existing team skillset).
+4. **Write the record.** Use the Nygard section order: `# NNNN. Title`, then `## Status`, `## Context`, `## Decision`, `## Consequences` (split into *positive* and *negative* — be honest about the costs you're accepting), and `## Considered Alternatives` (an added section not in Nygard's original — list each rejected option with the specific reason it lost). Write in past/decided tense, name concrete tradeoffs, and cite the constraints from step 3 rather than restating textbook definitions.
+5. **Set the status deliberately.** Use `Proposed` for an open decision under review, `Accepted` once it's agreed, `Deprecated` for an outdated record, or `Superseded by ADR-NNNN` when replaced. If this record retires an older one, update that file's status line to point here.
+6. **Verify and report.** Confirm the filename number is unique, the title slug matches the heading, and every alternative has a stated reason for rejection. List the file you wrote, and flag any section you filled from assumption rather than repo evidence so the user can correct it before merging.
+
+> [!WARNING]
+> Don't pad the Consequences with only upsides. An ADR that lists no negative consequences is a sales pitch, not a decision record — the reviewer can't weigh a tradeoff you hid. Name the lock-in, the operational cost, or the capability you gave up.
+
+## Examples
+
+For the decision "choose Postgres over MongoDB for the primary datastore," the skill detects no `mongoose`/`prisma` is wired yet, sees a managed Postgres already in the cloud account, and writes `docs/adr/0001-use-postgres-as-primary-datastore.md`:
+
+```markdown
+# 0001. Use PostgreSQL as the primary datastore
+
+## Status
+
+Accepted — 2026-06-03
+
+## Context
+
+The billing and account services need ACID transactions across orders,
+invoices, and ledger entries, and most read paths join three or more
+entities. Our data is strongly relational with a stable schema. The team
+already operates a managed Postgres instance in the existing cloud account
+and knows SQL; no one has run MongoDB in production here.
+
+## Decision
+
+We will use PostgreSQL 16 as the primary datastore for all transactional
+services, accessed through a single connection pool per service. Document-
+shaped, schemaless data (audit blobs, webhook payloads) will live in
+`jsonb` columns rather than a separate document database.
+
+## Consequences
+
+**Positive**
+
+- Multi-row transactions and foreign keys enforce invariants in the
+  database instead of in application code.
+- One datastore to operate, back up, and monitor — reuses the managed
+  instance and the team's existing SQL skills.
+- `jsonb` covers the few semi-structured cases without a second system.
+
+**Negative**
+
+- Horizontal write scaling requires deliberate work (partitioning, read
+  replicas) if write volume outgrows a single primary.
+- Schema changes need migrations and review; less forgiving than a
+  schemaless store during rapid early iteration.
+
+## Considered Alternatives
+
+- **MongoDB** — rejected: our access patterns are relational and need
+  cross-document transactions, which fight against its document model and
+  would push join logic into the application.
+- **Postgres + a separate document DB** — rejected: doubles operational
+  surface for a small amount of semi-structured data that `jsonb` handles.
+- **SQLite** — rejected: no managed multi-writer story for our concurrency
+  and availability needs.
+```
+
+After writing, report the path and note any section (e.g. projected write volume) that came from an assumption rather than a measured constraint, so the user can verify it before merging.

package/content/skills/branch-rebaser.md

@@ -0,0 +1,86 @@
+---
+name: "branch-rebaser"
+description: "Rebase the current branch onto its base and walk every conflict methodically, resolving each by understanding both sides. Use when your feature branch has fallen behind main and you want a clean, linear history without clobbering changes."
+allowed-tools: "Read, Bash, Edit"
+version: 1.0.0
+---
+
+Bring the current branch up to date by rebasing it onto its base, replaying your commits one at a time on top of the latest upstream. The skill confirms the working tree is clean before touching anything, fetches the real base, then steps through conflicts deliberately — reading both versions of each hunk and reconstructing the intended result rather than blindly accepting one side — and finishes by rebuilding and re-running tests so you know the rebase preserved behavior, not just resolved markers.
+
+## When to use this skill
+
+- Your feature branch has fallen behind `main`/`master` and you want a linear history instead of a merge commit.
+- A rebase is mid-flight with conflicts and you want each one resolved by intent, not by reflexively picking `--ours` or `--theirs`.
+- You need the branch updated before opening or refreshing a PR, and CI must still pass afterward.
+
+> [!NOTE]
+> Rebasing rewrites commit SHAs. Only rebase branches you own. If others have based work on this branch or it is already shared, prefer a merge — or coordinate before rewriting history.
+
+## Instructions
+
+1. **Confirm a clean tree.** Run `git status --porcelain` and `git rev-parse --abbrev-ref HEAD`. If there are uncommitted changes, stop and have the user commit or stash them (`git stash push -u`) before proceeding — a rebase over a dirty tree loses work. Note the current branch name.
+2. **Fetch the latest base.** Run `git fetch origin --prune` so you rebase onto what truly exists upstream, not a stale local ref.
+3. **Identify the base — do not guess.** Detect it instead of assuming `main`:
+   - Prefer the configured upstream: `git rev-parse --abbrev-ref @{upstream}` (e.g. `origin/main`).
+   - Fall back to the repo's default branch: `git symbolic-ref refs/remotes/origin/HEAD` → strip to `origin/<branch>`.
+   - Confirm the branch is actually behind: `git rev-list --left-right --count HEAD...origin/<base>`. If the right-hand count is `0`, it's already up to date — report that and stop.
+4. **Start the rebase.** Run `git rebase origin/<base>`. If it completes with no conflicts, skip to step 7.
+5. **Resolve each conflict by understanding both sides.** For every conflicted file (`git diff --name-only --diff-filter=U`):
+   - Read the file and locate the `<<<<<<<` / `=======` / `>>>>>>>` markers. The top block (`HEAD`/`ours`) is the base's version; the bottom block (`theirs`) is *your* commit being replayed.
+   - Inspect both versions in isolation when unclear: `git show :2:<file>` (ours) and `git show :3:<file>` (theirs).
+   - Reconstruct the intended result so **both** changes survive — keep the upstream fix *and* your feature edit. Never delete a side just to clear the markers.
+   - Edit the file to the merged result, remove all conflict markers, then `git add <file>`.
+6. **Continue, and repeat per commit.** Run `git rebase --continue`. Conflicts surface one replayed commit at a time, so return to step 5 for each new batch. If a commit becomes empty after resolution, `git rebase --skip` it. Use `git rebase --abort` to return to the pre-rebase state if anything looks wrong.
+7. **Verify by building and testing.** Resolved markers are not proof of correctness. Run the project's build and test commands (detect them — e.g. `npm run build && npm test`, `pytest`, `go build ./... && go test ./...`). Fix any breakage the rebase introduced.
+8. **Report and flag gaps.** Summarize how many commits replayed, which files conflicted and how each was resolved, and whether build/tests pass. Surface anything that needs a human eye (semantic conflicts the test suite may not catch, skipped commits). Do **not** force-push unless explicitly told to (see warning).
+
+> [!WARNING]
+> Updating a remote branch after a rebase requires a force-push, which rewrites history others may have pulled. Always use `git push --force-with-lease` (never bare `--force`) so you fail safely if the remote moved. If the branch is shared or backs an open PR with other contributors, **confirm with the user first** before pushing.
+
+## Examples
+
+A conflict-resolution loop on a branch two commits behind `origin/main`:
+
+```text
+$ git status --porcelain          # clean tree, ok to proceed
+$ git fetch origin --prune
+$ git rev-list --left-right --count HEAD...origin/main
+3       2                          # 3 local commits, 2 upstream → behind, rebase
+
+$ git rebase origin/main
+Auto-merging src/config.ts
+CONFLICT (content): Merge conflict in src/config.ts
+error: could not apply 1f4a2b9... feat(config): add retry option
+```
+
+`src/config.ts` shows both sides — upstream renamed the timeout field; your commit added a sibling key:
+
+```ts
+<<<<<<< HEAD                       # ours: upstream's rename
+  requestTimeoutMs: 5_000,
+=======                            # theirs: your new feature
+  timeout: 5000,
+  retries: 3,
+>>>>>>> 1f4a2b9 (feat(config): add retry option)
+```
+
+Keep *both* intentions — adopt the upstream rename and carry your new key onto it:
+
+```ts
+  requestTimeoutMs: 5_000,
+  retries: 3,
+```
+
+```text
+$ git add src/config.ts
+$ git rebase --continue
+[detached HEAD 9c1d0e2] feat(config): add retry option
+Successfully rebased and updated refs/heads/feat/retry.
+
+$ npm run build && npm test        # verify behavior, not just markers
+✓ build passed   ✓ 142 tests passed
+
+$ git push --force-with-lease      # only after confirming the branch isn't shared
+```
+
+Reported: 3 commits replayed, 1 conflict in `src/config.ts` (resolved by adopting the upstream `requestTimeoutMs` rename while carrying `retries`), build and tests green.

package/content/skills/bundle-analyzer.md

@@ -0,0 +1,77 @@
+---
+name: "bundle-analyzer"
+description: "Analyze a JS/TS production bundle and surface the biggest size wins — heavy dependencies, duplicate packages, missing code-splitting, oversized polyfills, and dev/server code leaking into the client. Use when a bundle is too large and you need a ranked, actionable reduction plan."
+allowed-tools: "Read, Grep, Glob, Bash"
+version: 1.0.0
+---
+
+Inspect a JavaScript/TypeScript production bundle and find where the bytes actually go. The skill builds a stats report, attributes weight to specific modules and packages, and hunts for the patterns that bloat bundles in practice — a 200KB date library imported for one helper, two copies of the same package at different versions, a route that ships eagerly instead of lazily, a polyfill set targeting browsers you dropped years ago, or server-only code that slipped past the client boundary. It returns a ranked list of concrete reductions with the estimated savings of each, so you fix the 80KB win before the 4KB one.
+
+## When to use this skill
+
+- A production bundle (or a specific route/chunk) has grown past budget and you need to know exactly what to cut.
+- You suspect duplicate packages, a heavyweight dependency, or a barrel import dragging in a whole library.
+- A first-load or main chunk is too big and you want to know what should be code-split or deferred.
+- You want to confirm dev-only tooling, source maps, or server code is not leaking into the client bundle.
+
+> [!NOTE]
+> Always measure the **production** build, not dev. Dev bundles include HMR runtime, unminified source, and no tree-shaking, so their sizes are meaningless for this analysis. Compare **gzip/brotli** transfer sizes, not raw bytes — that is what users actually download.
+
+## Instructions
+
+1. **Locate the build and detect the bundler.** Identify the toolchain before doing anything — do not guess. Check `package.json` scripts and lockfiles for `next`, `vite`, `webpack`, `rollup`, `esbuild`, or `@remix-run`. Note the package manager (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`) since duplicate-detection commands differ per manager.
+2. **Produce a stats report using the project's own analyzer.** Match existing config rather than bolting on a new tool:
+   - **Next.js** — run the production build and read its per-route First Load JS table; if `@next/bundle-analyzer` is wired up, run `ANALYZE=true npm run build`.
+   - **Vite/Rollup** — use `rollup-plugin-visualizer` if present, or build and inspect `dist/assets/*` sizes.
+   - **Webpack** — generate `--json` stats (`webpack --profile --json=stats.json`, which writes the file directly so console warnings don't corrupt the JSON) and analyze, e.g. with `source-map-explorer` over the emitted bundle + map.
+   - If no analyzer is configured, fall back to `npx source-map-explorer 'dist/**/*.js'` against the built output and its source maps.
+3. **Attribute weight to packages, not just files.** Map the largest modules back to their npm packages. For each heavyweight dependency, determine whether it is fully used or pulled in by a barrel/side-effect import, and whether a lighter alternative exists (e.g. `date-fns`/`dayjs` over `moment`, native `Intl` over `numeral`, `lodash-es` with named imports over `lodash`).
+4. **Detect duplicates and version skew.** Run `npm ls <pkg>` / `pnpm why <pkg>` / `yarn why <pkg>` on suspect packages to find the same library bundled at multiple versions, and check for both ESM and CJS copies of the same dep. Flag candidates for `resolutions`/`overrides` or dedupe.
+5. **Find missing code-splitting and oversized polyfills.** Look for large modules in the entry/main chunk that are only needed on one route or behind an interaction (charts, editors, markdown renderers, PDF libs) — these belong behind `import()` / `next/dynamic` / `React.lazy`. Inspect the polyfill/transpile target (`browserslist`, `target` in `tsconfig`/`vite`/`tsup`) for `core-js` or regenerator-runtime bloat aimed at browsers you no longer support.
+6. **Hunt for leaked dev/server code.** Grep the client bundle and imports for things that should never ship: test/mock files, `process.env` debug branches, server-only modules (`fs`, `crypto` server usage, DB clients, secrets), and dev dependencies imported from app code. In Next.js, confirm Server Component / `"use client"` boundaries are not dragging server modules into client chunks.
+7. **Verify each proposed cut.** Do not estimate from intuition alone. Where feasible, apply the change behind the analyzer (or `--dry`) and re-run the build to measure the real delta. At minimum, cite the measured pre-change size from the stats report for every finding.
+8. **Report a ranked plan.** Output findings ordered by estimated gzip savings, each with: the module/package, current size, the specific fix, the expected reduction, and a rough effort/risk rating. Flag anything you could not measure precisely so the user knows what to confirm.
+
+> [!WARNING]
+> Tree-shaking only works on side-effect-free ESM. A default or namespace import from a CJS package (or a package missing `"sideEffects": false`) pulls in the **whole** module regardless of what you use — so "import one helper" can still cost the full library. Verify the import shape, not just the import statement.
+
+## Examples
+
+A ranked findings report for a Next.js app whose largest route shipped 412 KB of First Load JS:
+
+```text
+Bundle analysis — route /dashboard (First Load JS: 412 KB gzip → target 180 KB)
+Ranked by estimated gzip savings:
+
+1. moment + moment-timezone .................. 71 KB  [HIGH]
+   Imported in 3 files for formatting only. Replace with date-fns
+   named imports (tree-shakeable). Est. -64 KB. Effort: M, Risk: low.
+
+2. Duplicate react (18.2.0 + 18.3.1) .......... 44 KB  [HIGH]
+   `npm ls react` shows two copies via an old @charting/core dep.
+   Add an override to pin a single version + dedupe. Est. -44 KB.
+   Effort: S, Risk: low.
+
+3. recharts loaded eagerly in entry chunk ..... 38 KB  [HIGH]
+   Only rendered below the fold on /dashboard. Move behind
+   next/dynamic({ ssr: false }). Est. -38 KB from First Load.
+   Effort: S, Risk: low.
+
+4. lodash default import (whole library) ...... 24 KB  [MED]
+   `import _ from "lodash"`. Switch to `lodash-es` + named imports
+   (debounce, groupBy). Est. -21 KB. Effort: S, Risk: low.
+
+5. core-js polyfills for IE11 ................. 19 KB  [MED]
+   browserslist still includes "ie 11". Drop it (no IE traffic in
+   analytics). Est. -19 KB. Effort: S, Risk: med (confirm targets).
+
+6. server-only `pg` Pool pulled into client ... 12 KB  [HIGH]
+   db/client.ts imported from a "use client" component. Move the
+   query behind a Server Action / route handler. Est. -12 KB +
+   removes a secret-leak vector. Effort: M, Risk: med.
+
+Estimated total reduction: ~198 KB gzip (412 → ~214 KB).
+Top 3 fixes alone recover 146 KB. Re-run the analyzer after each.
+```
+
+Re-run the build after applying the top findings to confirm the measured First Load JS dropped as projected, and re-check `npm ls` to verify the duplicate is gone.

package/content/skills/changelog-from-prs.md

@@ -0,0 +1,81 @@
+---
+name: "changelog-from-prs"
+description: "Draft a release changelog by summarizing merged pull requests since the last tag. Use when preparing a release or writing release notes."
+version: 1.0.0
+---
+
+Turn a range of merged pull requests into a clean, human-readable changelog. This skill collects the PRs merged since the previous release tag, groups them by change type (features, fixes, breaking changes, and more), and drafts release notes that are accurate, scannable, and ready to paste into a GitHub release or `CHANGELOG.md`.
+
+## When to use this skill
+
+- You are cutting a new release and need release notes that reflect what actually shipped.
+- You want a first draft of a `CHANGELOG.md` entry that follows [Keep a Changelog](https://keepachangelog.com/) conventions.
+- You need to summarize a noisy list of merge commits into something a human reader can understand.
+- You are reviewing what changed between two tags before deciding on a version bump.
+
+> [!NOTE]
+> This skill drafts notes from real PR data. It does not push tags or publish releases. Always review the draft before publishing.
+
+## Instructions
+
+1. **Find the last release tag.** Use the most recent semantic-version tag as the lower bound. If no tag exists, fall back to the first commit.
+
+   ```bash
+   git describe --tags --abbrev=0
+   ```
+
+2. **Collect merged PRs in the range.** Prefer the GitHub CLI so you get titles, numbers, authors, and labels. Use the merge date of the last tag as the cutoff.
+
+   ```bash
+   LAST_TAG=$(git describe --tags --abbrev=0)
+   SINCE=$(git log -1 --format=%cI "$LAST_TAG")
+   gh pr list --state merged --base main --limit 200 \
+     --search "merged:>$SINCE" \
+     --json number,title,author,labels,mergedAt
+   ```
+
+3. **Classify each PR.** Map it to a changelog section using labels first, then the title prefix (Conventional Commits style), then a judgment call:
+   - `feat` / `enhancement` -> **Added** or **Changed**
+   - `fix` / `bug` -> **Fixed**
+   - `breaking` / `!` in the title -> **Breaking Changes** (call these out at the top)
+   - `deprecate` -> **Deprecated**
+   - `security` -> **Security**
+   - `docs`, `chore`, `ci`, `test`, dependency bumps -> omit unless user-facing.
+
+4. **Rewrite titles into reader-facing notes.** Drop the type prefix, use the imperative-to-past or noun phrasing the section expects, and explain the user impact rather than the implementation. Keep the PR number for traceability.
+
+5. **Order and group.** Lead with breaking changes, then Added, Changed, Deprecated, Removed, Fixed, Security. Within a section, order by importance, not PR number.
+
+6. **Suggest the version bump.** Breaking changes -> major; new features -> minor; fixes only -> patch. State the recommendation but let the user confirm.
+
+7. **Emit the draft.** Output Markdown ready to paste, with a version header and date. Note any PRs you could not confidently classify so the user can review them.
+
+> [!WARNING]
+> Do not invent changes. If a PR title is ambiguous, list it under an "Uncategorized — needs review" heading instead of guessing its impact.
+
+## Examples
+
+**Input** — three merged PRs since `v1.3.0`:
+
+```
+#142  feat: add --json output flag to export command   (label: enhancement)
+#147  fix: prevent crash when config file is empty      (label: bug)
+#151  feat!: rename `--token` to `--api-key`            (label: breaking)
+```
+
+**Output** — drafted changelog entry:
+
+```markdown
+## v1.4.0 — 2026-06-02
+
+### Breaking Changes
+- Renamed the `--token` flag to `--api-key` for clarity. Update scripts that pass `--token`. (#151)
+
+### Added
+- `export` now supports a `--json` flag for machine-readable output. (#142)
+
+### Fixed
+- Fixed a crash that occurred when the config file was empty. (#147)
+
+> Recommended bump: minor → major (contains a breaking change). Suggested version: v2.0.0.
+```

package/content/skills/chunking-strategy-optimizer.md

@@ -0,0 +1,34 @@
+---
+name: "chunking-strategy-optimizer"
+description: "Find the chunking strategy and size that maximizes retrieval quality for a specific corpus, by sweeping configurations against a fixed eval set instead of guessing. Use when RAG answers miss obvious content, when standing up a new corpus, or when picking chunk size/overlap."
+allowed-tools: "Read, Grep, Glob, Bash"
+version: 1.0.0
+---
+
+Chunking is the highest-leverage, most-overlooked knob in retrieval: if the right passage never lands in a single chunk, no reranker or bigger model recovers it. This skill replaces "512 tokens with 50 overlap, because that's what the tutorial said" with a measured choice — sweep candidate strategies over a fixed eval set and pick the one that actually retrieves the answers.
+
+## When to use this skill
+
+- Standing up retrieval for a new corpus and you need a defensible chunking default.
+- RAG answers miss content you can see exists in the source documents.
+- Deciding chunk size, overlap, or strategy (token vs. sentence vs. recursive vs. semantic).
+- Migrating embedding models and want to re-confirm chunking still holds up.
+
+## Instructions
+
+1. **Build a retrieval eval set first.** Collect 20–50 real questions and, for each, the passage(s) that contain the answer (the "gold" spans). Hand-label if needed — even 20 cases beat eyeballing. This set is the ground truth every configuration is scored against; freeze it.
+2. **Define the candidate configurations.** A small grid, not a search of everything: 2–3 strategies (e.g. recursive, sentence, semantic) × 2–3 sizes (e.g. 256 / 512 / 1024 tokens) × overlap (0 / 10–15%). Hold the embedding model and retriever fixed so chunking is the only variable.
+3. **Run each configuration end to end.** For each config: chunk the corpus (e.g. with [Chonkie](/tools/chonkie)), embed the chunks with the fixed model, index them, and run the eval queries.
+4. **Score retrieval, not generation.** Report **recall@k** (does a gold passage appear in the top-k?) and a rank-aware metric like **nDCG@k** for k ∈ {5, 10, 20}. Generation quality is downstream noise here — measure whether the right chunk is retrieved at all.
+5. **Pick the smallest config that clears the bar.** Prefer the configuration with the fewest/smallest chunks that hits your recall target — smaller chunks mean lower embedding cost, lower storage, and tighter prompts. Report the full table so the trade-off is visible.
+6. **Re-check after any upstream change.** New embedding model, new document types, or a corpus that grew in a new direction all invalidate the result — re-run the sweep.
+
+> [!WARNING]
+> Never tune chunking without a frozen eval set and a baseline number. "The answers look better" is how silent recall regressions ship. If no eval set exists, building one is your first deliverable.
+
+> [!TIP]
+> Semantic chunking often wins on heterogeneous prose but costs embeddings at ingestion time; fixed-size recursive chunking is cheaper and frequently close. Let the numbers, not the brochure, decide.
+
+## Output
+
+A ranked table of configurations with recall@k and nDCG@k, the recommended configuration with its rationale, and the eval set itself (so the decision is reproducible and re-runnable).

package/content/skills/claude-settings-auditor.md

@@ -0,0 +1,38 @@
+---
+name: "claude-settings-auditor"
+description: "Audit every Claude Code settings layer — user, project, local, and managed — and report the effective merged configuration with its risks: over-broad Bash allows, missing deny rules for secrets, bypassPermissions defaults, unvetted MCP servers and hooks, and rules that never match. Use before trusting a new repo's checked-in settings, or to harden your own before handing the agent more autonomy."
+allowed-tools: "Read, Grep, Glob, Bash"
+version: 1.0.0
+---
+
+Claude Code's behavior is the *merge* of up to five settings sources — and the merged result is what nobody ever reads. This skill reads it for you: every layer, precedence applied, with each risky or dead rule called out and a safer replacement proposed. Run it on a freshly cloned repo before working in it, or on your own setup before granting more autonomy.
+
+## When to use this skill
+
+- You cloned a repo with a checked-in `.claude/settings.json` (and maybe `.mcp.json` and hooks) and want to know what you're trusting before the first session.
+- Your permission prompts feel wrong — too many, too few — and you want the effective rule set explained.
+- You're about to loosen the reins (acceptEdits, broader allows, CI automation) and want the floor checked first.
+
+## When NOT to use this skill
+
+- You want to *write* a specific hook — that's [hook-writer](/skills/workflow/hook-writer).
+- You're auditing the application's code for vulnerabilities — that's the [security-auditor](/agents/quality-security/security-auditor) agent; this skill audits the agent harness configuration itself.
+
+## Instructions
+
+1. **Collect every layer.** Read `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, and check for managed policy files (platform-specific admin paths). Include `.mcp.json` and any `.claude/hooks/` scripts referenced. Note which files exist, which are committed to the repo, and which are personal.
+2. **Compute the effective configuration.** Apply precedence (managed > local > project > user) and the permission decision order (deny → ask → allow). Produce the merged permissions table, the active hooks by event, the MCP servers by scope, and the notable toggles (`defaultMode`, `enableAllProjectMcpServers`, `disableAllHooks`, `autoMemoryEnabled`).
+3. **Hunt permission holes.** Flag, with severity: blanket allows (`Bash`, `Bash(*)`, `mcp__*` in allow), allows that swallow more than intended (`Bash(git *)` covers `git push --force`), **missing deny rules for secrets** (`.env*`, key files, cloud credential paths), `WebFetch` unbounded, and `bypassPermissions` as a default mode anywhere outside a container.
+4. **Vet hooks and MCP servers as supply chain.** For each hook script: what does it execute, is the source readable, does any blocking hook fail open? For each MCP server: scope, provenance, whether secrets are inline instead of `${VAR}` expansion, and whether `enableAllProjectMcpServers` auto-approves more than the user realizes. Read the scripts — don't trust filenames.
+5. **Find dead and shadowed rules.** Rules that can never fire (shadowed by an earlier deny, malformed pattern, the `Bash(ls *)`-vs-`lsof` word-boundary trap, tools that don't exist) are noise that breeds false confidence — list them for deletion.
+6. **Report by severity, then propose the patch.** CRITICAL (acts now, dangerous), WARN (risky under the wrong prompt), INFO (hygiene). For each finding: the file and line, why it matters in one sentence, and the exact replacement rule. Offer the corrected settings JSON as a diff the user can apply — but do not modify files unless asked.
+
+> [!NOTE]
+> A checked-in settings file is the *team's* contract — recommend fixes to it as a PR suggestion, not a silent local edit, and keep personal loosening in `settings.local.json` where it belongs.
+
+> [!TIP]
+> The fastest wins are nearly universal: add `deny: ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]`, replace any bare `Bash` allow with the three or four commands actually used, and move `git push` to `ask`.
+
+## Output
+
+An effective-configuration summary (what wins, from which file), a severity-ordered findings list with file:line and one-line impact each, and a ready-to-apply corrected settings diff — plus the explicit list of things that looked unusual but are fine, so the next auditor doesn't re-litigate them.

package/content/skills/conventional-commits.md

@@ -0,0 +1,80 @@
+---
+name: "conventional-commits"
+description: "Generate clear Conventional Commits messages from staged changes. Use when committing code and you want a well-structured, consistent commit message."
+allowed-tools: "Bash"
+version: 1.0.0
+---
+
+This skill inspects your staged changes and produces a commit message that follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. It picks the right type and scope, writes a concise imperative subject, adds a body explaining the *why* when the change is non-trivial, and flags breaking changes correctly — so your history stays readable and your tooling (changelogs, semantic-release) keeps working.
+
+## When to use this skill
+
+- You have changes staged with `git add` and want to commit them.
+- You want a consistent, spec-compliant message instead of free-form text.
+- You are unsure which type (`feat`, `fix`, `chore`, …) fits the change.
+- Your repo uses semantic versioning or automated changelog generation that depends on commit conventions.
+
+> [!NOTE]
+> This skill only reads and commits what is **already staged**. Stage the exact hunks you want first (`git add -p`). It will not stage files for you.
+
+## Instructions
+
+1. Read the staged diff to understand what actually changed:
+   ```bash
+   git diff --cached
+   ```
+   If nothing is returned, stop and tell the user there are no staged changes to commit.
+2. Check the staged file list for scope hints (directory or package names):
+   ```bash
+   git diff --cached --name-only
+   ```
+3. Choose the **type** from the staged changes:
+   - `feat` — a new user-facing capability
+   - `fix` — a bug fix
+   - `docs` — documentation only
+   - `style` — formatting, no logic change
+   - `refactor` — code change that neither fixes a bug nor adds a feature
+   - `perf` — performance improvement
+   - `test` — adding or correcting tests
+   - `build` / `ci` — build system or pipeline changes
+   - `chore` — maintenance, deps, tooling
+4. Derive an optional **scope** in parentheses from the affected area (e.g. `auth`, `api`, `parser`). Omit it if the change is broad.
+5. Write the **subject** line: `type(scope): summary`
+   - Imperative mood ("add", not "added" or "adds").
+   - No trailing period; aim for 50 characters, hard limit 72.
+6. If the change is non-trivial, add a blank line then a **body** explaining the motivation and any context the diff alone does not convey. Wrap at ~72 columns.
+7. If the change breaks compatibility, mark it: append `!` after the type/scope (e.g. `feat(api)!:`) **and** add a `BREAKING CHANGE:` footer describing the migration.
+8. Add footers for issue references when relevant (e.g. `Refs: #123`, `Closes: #456`).
+9. Present the proposed message to the user for confirmation, then commit:
+   ```bash
+   git commit -m "feat(parser): add support for nested arrays" \
+     -m "Handles arbitrarily deep nesting by recursing on bracket pairs." \
+     -m "Closes: #128"
+   ```
+
+## Examples
+
+Suppose `git diff --cached --name-only` shows `src/auth/session.ts` and the diff replaces a 1-hour token TTL with a configurable value, removing the old constant.
+
+```text
+feat(auth)!: make session token TTL configurable
+
+Replace the hardcoded 1-hour TTL with SESSION_TTL_SECONDS so deployments
+can tune session lifetime without a rebuild. Falls back to 3600 when the
+variable is unset.
+
+BREAKING CHANGE: the SESSION_MAX_AGE constant has been removed. Set the
+SESSION_TTL_SECONDS environment variable instead.
+
+Closes: #214
+```
+
+Commit it:
+
+```bash
+git commit \
+  -m "feat(auth)!: make session token TTL configurable" \
+  -m "Replace the hardcoded 1-hour TTL with SESSION_TTL_SECONDS so deployments can tune session lifetime without a rebuild. Falls back to 3600 when the variable is unset." \
+  -m "BREAKING CHANGE: the SESSION_MAX_AGE constant has been removed. Set the SESSION_TTL_SECONDS environment variable instead." \
+  -m "Closes: #214"
+```

package/content/skills/coverage-gap-finder.md

@@ -0,0 +1,72 @@
+---
+name: "coverage-gap-finder"
+description: "Run the project's coverage tool and identify the highest-value untested paths — error branches, edge cases, and critical modules — then propose specific test cases for each gap. Use when you have a coverage report but don't know where new tests will pay off most."
+allowed-tools: "Read, Grep, Glob, Bash"
+version: 1.0.0
+---
+
+Turn a raw coverage report into a ranked, actionable plan. This skill runs the project's existing coverage tool, reads the per-line and per-branch data, and surfaces the gaps that actually matter — uncovered error handlers, unguarded edge cases, and critical modules with thin coverage — rather than nudging an arbitrary percentage upward. For each gap it proposes concrete, named test cases you can hand straight to a scaffolder. The goal is risk reduction per test written, not a green 100% badge.
+
+## When to use this skill
+
+- You have (or can generate) a coverage report but don't know which untested lines are worth testing first.
+- A module is business-critical and you want to confirm its error paths and edge cases are exercised.
+- You're triaging tech debt and need a prioritized list of test gaps instead of a wall of red lines.
+
+> [!NOTE]
+> Line coverage measures *executed* lines, not *correct* behavior. A function can be 100% covered by a test that asserts nothing. Treat coverage as a map of blind spots, not a quality score — prioritize gaps by blast radius, then verify the new tests actually assert something.
+
+## Instructions
+
+1. **Detect the test stack and coverage tool.** Do not guess — inspect the project:
+   - JS/TS: `package.json` for `vitest --coverage` / `jest --coverage` (look for `coverage` scripts or a `c8`/`nyc`/`@vitest/coverage-v8` dep).
+   - Python: `pytest --cov` (`pytest-cov`), `coverage run`, config in `pyproject.toml`/`.coveragerc`.
+   - Go: `go test -coverprofile`. Java: JaCoCo. Match whatever already runs in CI.
+2. **Generate machine-readable coverage.** Run the tool to emit a structured report — `--coverage --coverage.reporter=json` (Vitest), `--cov --cov-report=json` (pytest), or `-coverprofile=cover.out` (Go). Parse the JSON/profile, not the pretty terminal table; you need per-file branch and line data. (For Vitest, `--coverage.reporter=json` writes `coverage/coverage-final.json` with per-file branch and line data; the unrelated `--reporter=json` is a *test-result* reporter — pass/fail/timing — and won't produce coverage.)
+3. **Rank gaps by value, not size.** For every uncovered region, weight it by signals — uncovered `catch`/`except`/error returns, `if`/`switch` branches with no covered alternative, input validation, and modules central to the app (auth, payments, parsing, persistence). Down-rank generated code, trivial getters, and config glue. A 60%-covered payment module outranks a 40%-covered logging helper.
+4. **Locate the exact untested paths.** For each top gap, read the source and name the specific uncovered branch (file, function, line range) and *why* it's untested — e.g. "the `429` retry branch is never hit because no test injects a rate-limit response."
+5. **Propose concrete test cases.** For each gap, write one bullet per missing case stating the input/condition and the expected behavior — not "add tests for error handling," but "call `withRetry` with a stubbed client that throws `RateLimitError` twice then succeeds; assert it retries and returns the value." Hand these to `test-scaffolder` to generate.
+6. **Verify the baseline and report.** Re-run coverage to confirm the numbers you're quoting are current, then output a prioritized gap list (highest value first) with file, current coverage, the risk, and the proposed cases. Flag any module you couldn't analyze (e.g. excluded from the report, untestable without a fixture).
+
+> [!WARNING]
+> Never chase 100%. Forcing coverage on glue code, framework boilerplate, or unreachable defensive branches produces brittle tests that assert nothing and slow the suite. Stop when the remaining gaps are low-risk — and say so explicitly in the report.
+
+## Examples
+
+Running coverage on a Vitest project and triaging the JSON report:
+
+```bash
+npx vitest run --coverage --coverage.reporter=json
+# reads coverage/coverage-final.json
+```
+
+Output — a prioritized gap list, not a flat percentage:
+
+```
+Coverage: 78% lines / 64% branches (412/640 branches)
+
+HIGH VALUE
+1. src/payments/charge.ts — 71% lines, 50% branches
+   Risk: the declined-card and idempotency-key-reuse branches are never exercised.
+   Propose:
+   - charge() with a gateway stub returning `card_declined` → asserts no DB write, throws PaymentError
+   - charge() called twice with the same idempotency key → asserts the second call returns the first result, no double charge
+
+2. src/auth/verifyToken.ts — 83% lines, 60% branches
+   Risk: expired-token and malformed-signature paths uncovered.
+   Propose:
+   - verifyToken() with a token whose `exp` is in the past → asserts throws TokenExpiredError
+   - verifyToken() with a tampered signature → asserts throws InvalidSignatureError
+
+MEDIUM VALUE
+3. src/parse/csv.ts — 88% lines
+   Risk: quoted-field-with-embedded-comma branch untested.
+   Propose:
+   - parseCsv('"a,b",c') → asserts two fields ["a,b", "c"]
+
+SKIP (low value)
+- src/logger.ts (45%) — thin wrapper over console; defensive branches only.
+- src/generated/*.ts — codegen output, exclude from coverage instead.
+```
+
+Hand the HIGH and MEDIUM cases to `test-scaffolder`, then re-run coverage to confirm the branches now flip green.

package/content/skills/dead-code-finder.md

@@ -0,0 +1,65 @@
+---
+name: "dead-code-finder"
+description: "Find genuinely unused code — unreferenced exports, unreachable files, and unused dependencies — and remove it safely with build/test verification. Use when trimming a codebase or untangling years of accreted cruft."
+allowed-tools: "Read, Grep, Glob, Bash"
+version: 1.0.0
+---
+
+Hunt down code that nothing references and delete it without breaking the build. The skill walks the dependency graph from the project's real entry points, flags exports no module imports, files no path reaches, and dependencies no source line uses — then removes them one at a time, re-running the build and tests after each deletion so a false positive surfaces immediately instead of in production.
+
+## When to use this skill
+
+- A codebase has accumulated dead exports, orphaned files, or leftover utilities after refactors and feature removals.
+- `package.json` lists dependencies you suspect nothing imports anymore.
+- You want a measured, verifiable cleanup pass — not a risky bulk delete.
+
+> [!WARNING]
+> "Unreferenced" is not the same as "unused." Code can be reached at runtime in ways static search misses: string-based requires (`require(`./handlers/${name}`)`), reflection/DI containers, framework entrypoints (route files, migrations, CLI commands, test setup), config-driven plugin loading, and anything that is part of a published **public API**. Treat these as live until proven otherwise. Verify every removal with the build **and** tests before moving to the next one.
+
+## Instructions
+
+1. **Locate the entry points.** Identify where execution actually begins — `main`/`exports`/`bin` in `package.json`, `next.config`/route conventions, `if __name__ == "__main__"`, CLI definitions, test runners. Everything reachable from these is live; the dead set is the complement.
+2. **Detect the right tooling — do not guess.** Match the ecosystem and prefer purpose-built tools over hand-rolled grep:
+   - TS/JS: `knip` (exports, files, and deps in one pass), `ts-prune`, `depcheck`, or `eslint`'s `no-unused-vars`.
+   - Python: `vulture`, `deptry`, `ruff check --select F401`.
+   - Go: `staticcheck`/`go vet`, `golangci-lint`. Rust: `cargo +nightly udeps`, dead-code warnings.
+   Read the config these tools already respect; honor existing ignore lists.
+3. **Build the candidate list, then triage.** For each candidate (unreferenced export, unreached file, unused dependency), grep the **whole repo** — including configs, test setup, CI scripts, dynamic-import strings, and docs — before trusting the tool. Drop anything matched by the dynamic-usage patterns in the warning above, and anything re-exported from a package's public entry point.
+4. **Remove one thing at a time.** Delete a single export/file/dependency, then run the project's build and test commands. Never batch deletions across the verification step — a green-then-red transition must point at exactly one change.
+5. **Verify after each removal.** Run the real commands (`npm run build && npm test`, `pytest`, `go build ./... && go test ./...`). A clean build and passing suite is the proof. If anything breaks, revert that single change and mark the candidate as a live-via-dynamic-usage false positive.
+6. **Report and flag gaps.** List what was removed (with the verifying command output), what was kept and why, and any candidates that need human judgment — public-API surface, generated code, or dynamic usage your search could not rule out.
+
+> [!NOTE]
+> Run the cleanup on a branch and keep each removal as its own commit. If a deletion only surfaces a failure in CI or a downstream consumer, a granular history makes the exact revert trivial.
+
+## Examples
+
+Confirming an export is truly unused before deleting it — `formatLegacyDate` in `src/utils/date.ts`:
+
+```bash
+# 1. Tool flags it as an unreferenced export
+$ npx knip --include exports
+src/utils/date.ts:42:14 - 'formatLegacyDate' is unused (exports)
+
+# 2. Verify by hand across the WHOLE repo, including dynamic strings and configs
+$ grep -rIn "formatLegacyDate" --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md' --include='*.yml' .
+src/utils/date.ts:42:export function formatLegacyDate(d: Date): string {
+# Only the definition — no importers, no string references, no re-export in index.ts
+```
+
+One self-reference and nothing else: safe to delete. Remove it, then prove the codebase still compiles and passes:
+
+```bash
+$ npm run build && npm test
+✓ build succeeded
+✓ 214 passed
+```
+
+Contrast with a false positive — an export `knip` also flags, but grep finds reached dynamically:
+
+```bash
+$ grep -rIn "handlers/" --include='*.ts' .
+src/router.ts:18:  const mod = await import(`./handlers/${route.name}`);
+```
+
+The static tool can't follow the template-literal import, so `handlers/checkout.ts` only *looks* orphaned. Keep it, document the dynamic load, and report it as a manual-review case rather than deleting it.