agentscamp 0.1.0

package/content/commands/extract-function.md

@@ -0,0 +1,107 @@
+---
+description: "Extract a code region into a well-named function and update the call site."
+argument-hint: "<file:lines or description>"
+allowed-tools: "Read, Grep, Glob, Edit"
+---
+
+Extract a region of code into a single, well-named function and replace the original code with a call to it. The result must behave exactly as before — this is a mechanical refactor, not a redesign.
+
+## Scope
+
+Interpret `$ARGUMENTS` as the region to extract:
+
+- **`path/to/file.ts:40-72`** — extract those line numbers in that file.
+- **A description** like *"the validation block in `createUser`"* — locate the matching region with `Grep`/`Glob` before touching anything.
+
+If `$ARGUMENTS` is empty, ask which region to extract. Do not guess — extracting the wrong span produces a function nobody asked for.
+
+> [!WARNING]
+> This is behavior-preserving. Do not add features, change return values, fix bugs you notice along the way, or alter side effects. If you spot a real bug, stop and report it instead of folding a fix into the extraction.
+
+## Step 1 — Locate and read the region
+
+Read the file and pin down the exact span. Read enough surrounding context to see what comes before and after the region, not just the lines themselves.
+
+```bash
+# When $ARGUMENTS names a file
+rg -n "createUser" path/to/file.ts
+
+# Confirm the enclosing function and its boundaries
+rg -n "^\s*(function|const|def|fn|public|private)" path/to/file.ts
+```
+
+Confirm the region is a coherent unit — one job, with a clear top and bottom. If the lines straddle two unrelated concerns, extract the smaller coherent piece and say so.
+
+## Step 2 — Determine inputs and outputs
+
+This is the part that breaks naive extractions. Work out exactly what the region consumes and what it produces.
+
+- **Inputs (parameters):** every variable the region *reads* but does not itself define inside the region. These become parameters.
+- **Outputs (return value):** variables defined inside the region that are *read after* it. One value → return it. Several → return a tuple/object, or keep the extraction smaller.
+- **Mutations:** values the region mutates in place (array pushes, object field writes, mutated arguments). The caller must still observe these — pass the object through and mutate it, or return the new value and reassign at the call site.
+
+> [!WARNING]
+> Watch for **captured closure state** and **early returns**. A `return`/`break`/`continue`/`throw` inside the region changes control flow for the *enclosing* function — a plain extracted function cannot reproduce a `break` in the caller's loop, and an early `return` becomes a return from the new function, not the original. If the region contains either, model it explicitly (return a sentinel and branch at the call site, or leave the control-flow line outside the extraction) or report that the region is not cleanly extractable.
+
+## Step 3 — Write the function
+
+Create the function with a name that states what it does, not how. Place it sensibly: a module-level helper near related functions, or a private method on the same class if it uses instance state.
+
+```ts
+// Before — inline region inside createUser
+const trimmed = input.email.trim().toLowerCase();
+if (!trimmed.includes("@") || trimmed.length > 254) {
+  throw new ValidationError("invalid email");
+}
+const email = trimmed;
+
+// After — extracted, single responsibility, descriptive name
+function normalizeEmail(raw: string): string {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed.includes("@") || trimmed.length > 254) {
+    throw new ValidationError("invalid email");
+  }
+  return trimmed;
+}
+```
+
+Match the file's existing conventions — async/sync, error handling, naming style, and how other helpers in the file are declared and exported.
+
+## Step 4 — Replace the original with a call
+
+Swap the region for a call that wires up the same inputs and outputs. Keep the surrounding variable names identical so the rest of the function is untouched.
+
+```ts
+// Inside createUser
+const email = normalizeEmail(input.email);
+```
+
+Preserve order of operations. If the region had side effects (logging, I/O, mutation) sequenced relative to its neighbors, the call must sit at the exact same point.
+
+## Step 5 — Verify behavior is unchanged
+
+Find and read every caller of the enclosing code path, then confirm the contract still holds.
+
+```bash
+# Find callers of the function you edited
+rg -n "createUser\(" --type ts
+
+# Run the tests covering this code
+npm test            # or: pytest, go test ./..., cargo test
+```
+
+- The same arguments must flow in and the same value/mutations must flow out.
+- Run the linter and type checker — a type error here usually means an input or output was mis-classified in Step 2.
+
+> [!NOTE]
+> If a test had to change to keep passing, behavior changed. Revert and re-examine the inputs/outputs — a correct extraction never requires touching assertions.
+
+## Report
+
+Summarize concisely:
+
+- **Extracted** — the new function name, its signature, and where it now lives.
+- **Call site** — the file and line where the region was replaced.
+- **Inputs/outputs** — parameters in, value(s) out, and any mutations preserved.
+- **Verification** — that callers, tests, lint, and types still pass.
+- **Caveats** — any early-return or closure-capture handling, or anything you left out of scope.

package/content/commands/find-bug.md

@@ -0,0 +1,93 @@
+---
+description: "Investigate a reported symptom, form hypotheses, and locate the root cause."
+argument-hint: "[symptom]"
+---
+
+You are debugging a reported issue. The symptom to investigate is: **$ARGUMENTS**
+
+Your goal is to find the *root cause* — not the first plausible explanation, and not a patch over the symptom. Work methodically through the phases below. Do not skip ahead to a fix until you can explain exactly why the bug happens.
+
+## 1. Reproduce and characterize the symptom
+
+Before touching the code, pin down what "$ARGUMENTS" actually means in concrete terms.
+
+- Identify the **exact** observable failure: error message, stack trace, wrong output, crash, hang, or incorrect state.
+- Determine **when** it happens: every time, intermittently, only with certain inputs, only in certain environments.
+- Establish a reliable reproduction. If you cannot reproduce it, that is your first task — search logs, tests, and recent reports for clues.
+
+> [!NOTE]
+> A bug you cannot reproduce is a bug you cannot confidently fix. Invest here first; everything downstream depends on a stable repro.
+
+Capture the failing signal directly when possible:
+
+```bash
+# Re-run the failing command/test and capture full output
+<your test or repro command> 2>&1 | tee /tmp/find-bug.log
+```
+
+## 2. Gather evidence
+
+Collect facts before forming theories. Read the actual error, don't paraphrase it.
+
+- Read the **full** stack trace top to bottom; the deepest frame in *your* code is usually the most relevant.
+- Grep for the error message, the failing symbol, and surrounding identifiers to locate candidate files.
+- Check recent changes — a regression often points straight at the culprit.
+
+```bash
+# Find what changed recently around the suspect area
+git log --oneline -20 -- <suspect_path>
+git blame -L <start>,<end> <file>
+```
+
+## 3. Form hypotheses
+
+List the **plausible** root causes as explicit, testable statements. Rank them by likelihood given the evidence.
+
+Common categories to consider:
+
+- **State / lifecycle** — stale cache, race condition, uninitialized or mutated shared state.
+- **Boundary conditions** — null/empty/zero, off-by-one, overflow, timezone, encoding.
+- **Contract mismatch** — API shape changed, wrong type, wrong units, optional treated as required.
+- **Environment** — config, env vars, dependency version, build vs. runtime difference.
+
+Write each hypothesis with the prediction it implies, e.g. *"If the cache is stale, then clearing it before the call will make the symptom disappear."*
+
+## 4. Test each hypothesis
+
+Confirm or eliminate hypotheses one at a time. Change **one** variable per experiment so the result is unambiguous.
+
+- Add targeted logging or assertions at the boundary you suspect.
+- Use a debugger or a minimal script to inspect actual values at the point of failure.
+- Bisect when the cause is unclear and you have a known-good past state:
+
+```bash
+git bisect start
+git bisect bad                 # current revision is broken
+git bisect good <known_good>   # last revision known to work
+# git replays commits; mark each: git bisect good | git bisect bad
+git bisect reset               # when finished
+```
+
+> [!WARNING]
+> Resist confirmation bias. Actively try to *disprove* your favorite hypothesis. If an experiment "kind of" supports it, treat that as a no until you have a clean, repeatable result.
+
+## 5. Identify the root cause
+
+You have found the root cause only when you can state, precisely:
+
+- **Where** it is — the specific file, function, and line(s).
+- **Why** it produces the symptom — the exact chain of cause and effect.
+- **When** it triggers — the conditions required, which must match the reproduction from Step 1.
+
+If your explanation does not fully account for the observed behavior (including any intermittency), you are not done — return to Step 3.
+
+## 6. Report findings
+
+Summarize concisely so the fix is obvious and safe:
+
+- **Root cause:** one or two sentences naming the exact defect.
+- **Evidence:** the experiments and observations that prove it.
+- **Affected scope:** other call sites or inputs that hit the same defect.
+- **Suggested fix:** the minimal change that addresses the cause, plus a test that would have caught it.
+
+Do not apply the fix unless asked — your job here is to locate and explain the root cause. Hand off a clear, verifiable diagnosis.

package/content/commands/fix-failing-test.md

@@ -0,0 +1,106 @@
+---
+description: "Diagnose and fix a failing test by finding the real root cause."
+argument-hint: "[test name or path]"
+allowed-tools: "Read, Grep, Glob, Edit, Bash"
+---
+
+Make a failing test green by fixing the **actual root cause**, not by papering over it. Follow the steps below in order. The hard part is the judgment call in Step 3 — whether the test or the code is wrong — so do not skip it.
+
+## Scope
+
+`$ARGUMENTS` names the failing test to fix. It may be a test file path (`src/lib/parse.test.ts`), a single test name or pattern (`parses nested config`), or a `file::test` selector your runner understands. Use it to scope the run so you iterate on one failure at a time.
+
+If `$ARGUMENTS` is empty, run the full suite first, find the failing test(s), and pick the first failure to work on. If several tests fail, fix them one at a time and re-run between fixes — a single root cause often explains a cluster of failures, and fixing it may turn the rest green for free.
+
+## Step 1 — Reproduce and read the real failure
+
+Detect the test runner (`jest`, `vitest`, `pytest`, `go test`, `cargo test`, …) from the manifest, then run only the target so the output stays readable.
+
+```bash
+# vitest / jest — by name pattern or file
+npx vitest run -t "parses nested config"
+npx jest path/to/file.test.ts -t "parses nested config"
+
+# pytest — node id or keyword
+pytest "tests/test_parse.py::test_nested_config" -x -vv
+
+# go — single test by regexp
+go test ./pkg/parse -run TestNestedConfig -v
+```
+
+Read the *entire* failure block, not just the red summary line:
+
+- The assertion that failed, with **expected vs. actual** values.
+- The stack trace — find the first frame inside the project's own source, not framework internals.
+- The exact input the test fed in, so you can replay the path by hand.
+
+> [!NOTE]
+> Confirm the test fails for the reason you think it does. A `ReferenceError`, an import that throws at load, a timeout, or a snapshot mismatch are different problems than a logic assertion — don't start fixing math when the real issue is the suite can't even import the module.
+
+## Step 2 — Locate the code under test
+
+Trace from the failing assertion back to the production code that produced the wrong value.
+
+```bash
+# Find the symbol the test imports / calls
+rg -n "parseConfig" src
+
+# Open the test and the implementation side by side
+```
+
+Read both the test and the implementation. Reconstruct what value the code returns for the test's input and *why*, walking the same branch the failing case takes. Check whether the behavior recently changed.
+
+```bash
+# What touched this code lately, and was the test updated alongside it?
+git log --oneline -10 -- src/lib/parse.ts
+git log -p -1 -- src/lib/parse.ts
+```
+
+## Step 3 — Decide: is the TEST wrong or the CODE wrong?
+
+This is the decision that determines everything else. **State your verdict explicitly before you edit anything**, and back it with the evidence from Steps 1–2. One side is wrong:
+
+- **The code is wrong** when the test encodes the genuinely intended behavior (a clear spec, a documented contract, the obvious correct answer) and the implementation produces something else. Fix the implementation.
+- **The test is wrong** when the implementation is correct and the test asserts the wrong thing — a stale expectation after an intentional behavior change, a bad fixture, a flawed mock, a brittle snapshot, or an order/timing assumption that was never guaranteed. Fix the test.
+
+When it is genuinely ambiguous (no spec says which behavior is right), do not guess silently. State both interpretations and the user-facing consequence of each, and ask which is intended before changing code.
+
+> [!WARNING]
+> Never make a test pass by weakening or deleting the assertion — loosening an exact match to `toBeTruthy()`, widening a tolerance, adding `.skip`/`xit`, or editing the expected value to match buggy output. That hides a real bug behind a green check. If the assertion is correct, fix the code; only relax an assertion when the assertion itself is provably wrong.
+
+## Step 4 — Fix the correct side
+
+Apply the smallest change that addresses the root cause you identified.
+
+- **Fixing the code:** correct the actual defect — the off-by-one, the wrong operator, the unhandled `null`, the bad early return. Don't special-case the one input the test uses; fix the general behavior so related inputs are right too.
+- **Fixing the test:** update the expectation, fixture, or mock to match the genuinely correct behavior, and leave a one-line comment on *why* if it isn't obvious. If the test was brittle (timing, ordering, snapshot churn), make it deterministic rather than just nudging the expected value.
+
+Touch only what the diagnosis requires. Leave unrelated cleanup for another change.
+
+## Step 5 — Re-run and confirm green
+
+Run the scoped target first to confirm the specific failure is gone.
+
+```bash
+npx vitest run -t "parses nested config"
+```
+
+Then run the surrounding file and the full suite to make sure the fix didn't break a sibling test.
+
+```bash
+npx vitest run path/to/file.test.ts   # the whole file
+npx vitest run                        # the full suite
+```
+
+> [!NOTE]
+> If the target now passes but a previously-green test fails, your change had a side effect that the broader suite encodes as intended behavior. That regression is a new signal — return to Step 3 and reconcile the two expectations rather than suppressing either one.
+
+## Report
+
+Summarize for the user, concisely:
+
+- **Verdict:** which side was wrong (test or code) and the one-line root cause.
+- **Fix:** the file and what you changed, and why it addresses the cause rather than the symptom.
+- **Result:** the target test and full suite are green (paste the final pass count), or the open question you need answered if the intended behavior was ambiguous.
+
+Do not commit or push — leave the change staged for the user to review unless they explicitly ask you to commit.

package/content/commands/new-component.md

@@ -0,0 +1,119 @@
+---
+description: "Scaffold a new UI component matching the project conventions."
+argument-hint: "<ComponentName> [props]"
+allowed-tools: "Read, Grep, Glob, Write, Edit"
+---
+
+Scaffold a new UI component named in `$ARGUMENTS`, generated to match this repository's existing conventions exactly. Discover the conventions first by reading real neighbor components — never impose a structure the repo does not already use.
+
+## Scope
+
+Read `$ARGUMENTS` as `<ComponentName> [props]`:
+
+- The first token is the component name in the project's casing (e.g. `UserCard`, `user-card`). Normalize it to whatever convention the codebase uses, not your own preference.
+- Any remaining tokens are a rough prop list — `title:string variant?:primary|secondary count:number onSelect:fn`. Treat `?` as optional and `fn` as a callback. If props are vague, infer a minimal sensible interface and note your assumptions.
+
+If `$ARGUMENTS` is empty, ask for the component name and its purpose before generating anything. Do not invent a component the user did not request.
+
+## Step 1 — Detect the project's conventions
+
+Before writing a single line, find a representative existing component and study how it is built. This is the most important step — everything downstream mirrors what you find here.
+
+```bash
+# Find existing components to mirror (adapt globs to the repo)
+fd -e tsx -e jsx -e vue -e svelte . src/components src/app 2>/dev/null | head -30
+
+# Inspect the manifest for framework, test runner, and styling deps
+cat package.json
+```
+
+From a real neighbor file, extract and write down:
+
+- **Framework & file type** — React `.tsx`, Vue SFC `.vue`, Svelte `.svelte`, Solid, Angular.
+- **File layout** — one file per component vs. a folder (`Button/index.tsx`, `Button.tsx`, `Button.test.tsx`, `Button.stories.tsx`).
+- **Styling** — Tailwind classes, CSS Modules, `styled-components`, vanilla-extract, plain CSS. Note any `cn()`/`clsx` helper and variant utility (`cva`, `tv`).
+- **Prop typing** — `interface Props` vs. `type Props`, `React.FC` vs. plain function, `forwardRef`, default exports vs. named.
+- **Test / story patterns** — the test framework (`vitest`, `jest`, `@testing-library`), and whether stories use CSF, MDX, or none.
+- **Imports & aliases** — path aliases (`@/components`), import ordering, and how shared primitives are imported.
+
+> [!NOTE]
+> Pick the closest neighbor to what you are building (a card if scaffolding a card) and mirror it line for line — directory, naming, export style, and formatting. A component that looks hand-written by the team beats a "correct" one that fights the codebase.
+
+## Step 2 — Generate the component
+
+Create the component file at the location and with the naming the codebase uses. The block below is illustrative — match the framework and style you found in Step 1, not this snippet.
+
+```tsx
+import { cn } from "@/lib/utils";
+
+interface UserCardProps {
+  title: string;
+  variant?: "primary" | "secondary";
+  count: number;
+  onSelect?: () => void;
+}
+
+export function UserCard({
+  title,
+  variant = "primary",
+  count,
+  onSelect,
+}: UserCardProps) {
+  return (
+    <div
+      className={cn("rounded-lg border p-4", variant === "primary" && "bg-card")}
+      onClick={onSelect}
+    >
+      <h3>{title}</h3>
+      <span>{count}</span>
+    </div>
+  );
+}
+```
+
+- Reuse existing primitives and helpers (the local `cn()`, shared `Button`, design tokens) instead of reintroducing your own.
+- Keep the public prop surface minimal and typed; derive optionality from the `?` markers in `$ARGUMENTS`.
+- Match the neighbor's export style (named vs. default) so existing import patterns keep working.
+
+> [!WARNING]
+> Only create the files needed for this component. Do not edit unrelated files, restructure folders, add dependencies, or change shared config. If a missing helper or barrel export is required, flag it rather than silently introducing a new pattern.
+
+## Step 3 — Add types, test, and story
+
+Generate the supporting files that the neighbor component has — no more, no fewer. If the project keeps types inline, keep them inline; if it ships a `.test.tsx` and a `.stories.tsx` alongside each component, produce both in the same folder.
+
+```tsx
+// UserCard.test.tsx — mirror the project's test framework and queries
+import { render, screen } from "@testing-library/react";
+import { UserCard } from "./UserCard";
+
+test("renders the title", () => {
+  render(<UserCard title="Ada" count={3} />);
+  expect(screen.getByText("Ada")).toBeInTheDocument();
+});
+```
+
+- Put each file exactly where the codebase puts it, and use its import aliases.
+- Cover the rendered output and one prop-driven branch in the test; do not over-test scaffolding.
+- If the repo has no tests or no stories, skip that artifact — do not introduce a tool the project does not use.
+
+> [!NOTE]
+> If you add the component to a barrel file (`index.ts`) or registry, only do so when neighbors are exported the same way. Follow the existing export ordering.
+
+## Step 4 — Verify and report
+
+Confirm the generated files fit the project before handing back.
+
+```bash
+# Adapt to the repo's commands
+npm run lint
+npx tsc --noEmit   # or the project's typecheck/build command
+# npm run build    # heavier fallback if you need a full bundle
+```
+
+Report concisely:
+
+- **Files created** — each path, and the neighbor file each one was modeled on.
+- **Props** — the resolved interface and any optionality or types you inferred.
+- **Conventions followed** — framework, styling approach, export style, and test/story pattern matched.
+- **Follow-ups** — anything intentionally skipped (no story because the repo has none) or a missing helper the user should wire up.

package/content/commands/plan-feature.md

@@ -0,0 +1,71 @@
+---
+description: "Explore the codebase and produce an implementation plan for a feature."
+argument-hint: "<feature description>"
+allowed-tools: "Read, Grep, Glob"
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the feature request — what the user wants to build (`add CSV export to the reports page`, `support OAuth login`, `rate-limit the public API`). Restate it in one sentence to confirm you understood it before planning.
+
+If `$ARGUMENTS` is empty, ask one focused question: *"What feature should I plan?"* Do not guess a feature out of thin air.
+
+> [!WARNING]
+> Read-only mode. Do not modify the repository, run migrations, install packages, or scaffold code. Your only output is the written plan. If the user wants you to start building, that is a separate follow-up.
+
+> [!NOTE]
+> Where the request is ambiguous (auth provider, storage backend, UI placement, scope boundaries), state your assumptions explicitly and plan against them rather than stalling. Flag each assumption so the user can correct it.
+
+## Step 1 — Understand the request
+
+Break the feature into concrete capabilities and acceptance criteria before touching the code.
+
+- What is the user-facing behavior when this is done? What is the smallest version that ships value?
+- What is explicitly **out of scope**? Name it so the plan stays bounded.
+- What existing behavior must not break?
+
+## Step 2 — Explore the code to ground the plan
+
+A plan written without reading the code is a guess. Map the feature onto the real structure before proposing anything. You only have `Read`, `Grep`, and `Glob` here — explore with those, not the shell:
+
+- **Orient first:** `Read` `README.md`, `package.json`, and `CLAUDE.md` for project type, scripts, conventions, and the test/lint/typecheck commands. Use `Glob` (e.g. `src/**/*.ts`, `**/routes/**`) to see how the tree is laid out.
+- **Find the area the feature touches:** `Grep` for terms drawn from `$ARGUMENTS` (e.g. `export|report|download`) to locate the relevant files. Map the entry points, data flow, and layers the feature crosses (routes, services, models, UI).
+- **Find a pattern to mirror:** `Grep` for the shape of similar existing features (e.g. `router\.|app\.(get|post)|export function`), then `Read` the **closest existing feature** end to end. The cleanest plan usually copies an established pattern rather than inventing one.
+
+## Step 3 — Write the plan
+
+Output the plan in this structure. Be specific — cite real file paths and symbols you found in Step 2, not placeholders.
+
+```markdown
+## Plan — <one-line feature summary>
+
+### Assumptions
+- <each ambiguity you resolved, and how>
+
+### Affected files & modules
+- `path/to/file.ts` — <what changes and why>
+- `path/to/other.ts` — <new function / modified signature>
+
+### Proposed approach
+<2-4 paragraphs describing the design: data flow, where new code lives,
+how it hooks into existing patterns, and the public interface.>
+
+### Trade-offs & alternatives
+- **Chosen:** <approach> — <why it wins here>
+- **Alternative:** <other option> — <why rejected / when it would be better>
+
+### Risks & unknowns
+- <thing that could break, perf concern, migration risk, or open question>
+
+### Implementation steps
+1. <smallest first, each independently reviewable>
+2. ...
+
+### Test plan
+- <unit / integration tests to add, key cases & edge cases>
+- <how to verify manually; commands to run>
+```
+
+## Report
+
+Deliver the plan as your message — it is the whole deliverable. Keep it tight enough to read in one pass, specific enough to start coding from immediately, and end with the single recommended first step. Remember: no files were changed; this is a plan to act on, not the action.

package/content/commands/profile-postgres-queries.md

@@ -0,0 +1,41 @@
+---
+description: "Profile a Postgres workload to find the queries actually costing you — rank by total time with pg_stat_statements, EXPLAIN the worst offenders, and recommend the highest-leverage fix."
+argument-hint: "<database/connection details, a slow endpoint, or a description of the workload>"
+allowed-tools: "Read, Grep, Glob, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the workload to profile — a database/connection, a slow endpoint or report, or a description of where the database feels slow. The job here is **triage**: find *which* queries cost the most before optimizing any one of them, so effort goes where it pays.
+
+> [!NOTE]
+> This command profiles a workload to rank its worst queries. To then fix a single slow query from its plan, hand off to the [sql-optimizer](/skills/data/sql-optimizer) skill; to choose the right index for it, the [postgres-index-strategist](/skills/database/postgres-index-strategist).
+
+## Step 1 — Establish the data source
+
+Prefer **`pg_stat_statements`** (the aggregated view of normalized query stats) — confirm the extension is enabled. If it isn't available, fall back to the slow-query log or a representative trace, and say so. Profiling against an empty dev database tells you nothing; use representative data and traffic.
+
+## Step 2 — Rank by total cost, not just slowness
+
+Pull the top queries by **`total_exec_time`** (total time spent across all calls) — the real cost driver — alongside `calls`, `mean_exec_time`, and `rows`. A fast query run a million times can outweigh a slow one run twice. Report the top offenders by total time and by call count.
+
+## Step 3 — EXPLAIN the worst offenders
+
+For each top query, run `EXPLAIN (ANALYZE, BUFFERS)` on a representative instance and read for the dominant cost: sequential scans on large filtered tables, estimate-vs-actual row blowups (stale statistics), nested loops over huge intermediates, or sorts spilling to disk.
+
+## Step 4 — Classify the fix
+
+For each, name the highest-leverage fix and route it:
+
+- **Missing/wrong index** → an index recommendation (type matters — B-Tree vs. GIN vs. BRIN; see [postgres-index-strategist](/skills/database/postgres-index-strategist) and [Indexing Postgres at Scale](/guides/database/postgres-indexing-at-scale)).
+- **Stale statistics** → `ANALYZE` the table before anything else.
+- **A single slow query needing a rewrite** → [sql-optimizer](/skills/data/sql-optimizer).
+- **App-side N+1** (same query, huge `calls`) → fix in the application (eager-load / batch), not the database.
+
+## Step 5 — Report a prioritized plan
+
+Produce a ranked table — query | total time | calls | mean | the diagnosis | the proposed fix — ordered by total cost so the team fixes the biggest win first. Quantify where you can ("this one query is 40% of total DB time").
+
+> [!WARNING]
+> Optimize by **total** time, not by the single slowest query. The query that dominates your database's load is often a moderately-fast one executed constantly — chasing the one query with the worst single-run time can spend effort where it barely moves the needle.

package/content/commands/red-team-llm.md

@@ -0,0 +1,45 @@
+---
+description: "Red-team an LLM app or agent for prompt injection, jailbreaks, and data leakage — probe the real attack surface (input, RAG, tools, system prompt) with adversarial inputs and report what got through and how to fix it."
+argument-hint: "<the app/endpoint/agent to test, or a description of its inputs, tools, and data>"
+allowed-tools: "Read, Grep, Glob, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the LLM app/agent to red-team — an endpoint, an agent, or a description of its inputs, tools, retrieved sources, and data. Restate the target and its attack surface in one sentence before probing.
+
+> [!WARNING]
+> Red-team only systems you are **authorized** to test. This command runs adversarial attacks; confirm you have permission for the target and use a non-production or isolated environment where possible. The aim is to find holes before an attacker does — on your own system.
+
+Goal: probe the **real** attack surface with adversarial inputs, record what succeeds and its blast radius, and return prioritized fixes — an active attack campaign, complementary to the design review the [prompt-injection-auditor](/agents/quality-security/prompt-injection-auditor) performs.
+
+## Step 1 — Map the attack surface
+
+Enumerate every channel that reaches the model: direct user input, **retrieved/RAG content**, **tool outputs**, browsed pages or ingested files, and the system prompt. The indirect channels (content the system reads while working) are the ones most worth attacking.
+
+## Step 2 — Choose attack categories
+
+Cover the categories that matter for this target:
+
+- **Direct prompt injection** — instruction-override in user input.
+- **Indirect injection** — payloads planted in a document, tool result, or page the system ingests.
+- **Jailbreak** — bypassing safety/policy constraints.
+- **System-prompt leakage** — extracting the hidden instructions (LLM07).
+- **Data exfiltration** — making the model reveal data or secrets it shouldn't.
+- **Tool misuse** — inducing a harmful or out-of-scope tool call (for agents).
+
+## Step 3 — Run the probes
+
+Execute adversarial inputs for each category — automated with a red-teaming tool like [promptfoo](/tools/promptfoo) (injection/jailbreak suites) and/or targeted manual probes, including the **indirect** path (seed a poisoned document/tool result and see if the agent obeys it). Vary phrasings; a single failed attempt proves nothing.
+
+## Step 4 — Record what got through and its blast radius
+
+For each successful attack, capture the input, what the model did, and — critically — the **impact**: data leaked, action taken, constraint bypassed. Rank by blast radius (what it could actually cause), not by novelty.
+
+## Step 5 — Recommend fixes and re-test
+
+Map each finding to a mitigation — least privilege, human approval, trust boundaries, input/output guardrails, secrets out of context (see [Defending Against Prompt Injection](/guides/ai-safety/defending-prompt-injection)) — then re-run the successful attacks to confirm the fix contains them. An attack that now achieves nothing is the success criterion, not one you believe you blocked.
+
+> [!NOTE]
+> Report negatives honestly: state which attack categories you ran, which you didn't, and that passing today's probes is not proof of safety — red-teaming is continuous, because new bypasses appear. Gate releases on it, don't treat it as a one-time sign-off.