agentscamp 0.1.0

package/content/commands/refactor.md

@@ -0,0 +1,82 @@
+---
+description: "Refactor the target for readability and structure without changing behavior."
+argument-hint: "[file or function]"
+---
+
+Refactor `$ARGUMENTS` to improve readability, structure, and maintainability while keeping observable behavior exactly the same. If `$ARGUMENTS` is empty, ask which file or function to target before making any changes.
+
+> [!WARNING]
+> This is a behavior-preserving refactor, not a rewrite. Do not add features, change public APIs, alter return values, or modify side effects. If you discover a genuine bug, stop and report it instead of silently "fixing" it.
+
+## 1. Establish a baseline
+
+Before touching anything, understand the current behavior and how it is verified.
+
+- Read `$ARGUMENTS` and the code that calls it. Note the public interface: function signatures, exported symbols, and any side effects (I/O, network, mutation, logging).
+- Find the relevant tests. Run them to confirm they pass before you start, so you have a known-good baseline.
+
+```bash
+# Adjust to the project's test runner
+npm test            # or: pytest, go test ./..., cargo test
+```
+
+If there are no tests covering the target, say so. Add a minimal characterization test that captures current behavior before refactoring, or ask the user how to proceed.
+
+## 2. Identify what to improve
+
+Look for concrete, well-known issues rather than stylistic preference:
+
+- **Naming** — vague or misleading identifiers (`data`, `tmp`, `doStuff`).
+- **Duplication** — repeated logic that can be extracted into one place.
+- **Long functions** — units doing several jobs that should be split.
+- **Deep nesting** — guard clauses and early returns can flatten control flow.
+- **Dead code** — unused variables, unreachable branches, stale comments.
+- **Leaky structure** — mixed levels of abstraction in one function.
+
+## 3. Apply changes in small steps
+
+Make one focused transformation at a time. Prefer many small, verifiable edits over one large rewrite.
+
+A typical move is replacing nested conditionals with guard clauses:
+
+```js
+// Before
+function getDiscount(user) {
+  if (user) {
+    if (user.isActive) {
+      return user.isPremium ? 0.2 : 0.1;
+    }
+  }
+  return 0;
+}
+
+// After
+function getDiscount(user) {
+  if (!user || !user.isActive) return 0;
+  return user.isPremium ? 0.2 : 0.1;
+}
+```
+
+After each meaningful step, re-run the tests so a regression is caught immediately and isolated to the change that caused it.
+
+## 4. Verify behavior is unchanged
+
+- Run the full test suite again; it must pass with no modifications to the assertions.
+- Run the linter and type checker to confirm nothing was broken.
+
+```bash
+npm run lint
+npm run build   # or the project's typecheck command
+```
+
+> [!NOTE]
+> If a test had to change to keep passing, that means behavior changed. Revert and rethink, or surface the discrepancy to the user.
+
+## 5. Summarize
+
+Report back concisely:
+
+- **What changed** — the specific refactorings applied (e.g. "extracted `validateInput`, flattened nesting in `parse`").
+- **Why** — the readability or structure problem each change addressed.
+- **Verification** — that tests, lint, and types still pass.
+- **Follow-ups** — anything out of scope you noticed (suspected bugs, missing test coverage) listed separately, not acted on.

package/content/commands/review-pr.md

@@ -0,0 +1,101 @@
+---
+description: "Review a pull request for correctness, security, and style, and summarize findings."
+argument-hint: "[PR number]"
+---
+
+Review pull request **#$ARGUMENTS** end to end. Produce a focused, actionable review that a maintainer can act on immediately. Do not approve or merge the PR — your job is to analyze and report.
+
+## Gather context
+
+Pull the PR metadata and the full diff before forming any opinion. Use the GitHub CLI so you read the same state reviewers see.
+
+```bash
+# Title, body, author, branches, labels, and CI status
+gh pr view $ARGUMENTS
+
+# Full diff for the PR
+gh pr diff $ARGUMENTS
+
+# Files changed with additions/deletions
+gh pr view $ARGUMENTS --json files --jq '.files[] | "\(.path) +\(.additions) -\(.deletions)"'
+
+# CI / check results
+gh pr checks $ARGUMENTS
+```
+
+Read the PR description and any linked issues to understand the *intended* behavior. Then check out the branch locally so you can inspect surrounding code, run the test suite, and verify claims.
+
+```bash
+gh pr checkout $ARGUMENTS
+```
+
+> [!NOTE]
+> Review the change against its stated goal. A technically clean diff that does not solve the problem described in the PR is still a problem worth flagging.
+
+## What to evaluate
+
+### Correctness
+
+Trace the changed logic against the intended behavior. Look for off-by-one errors, incorrect conditionals, unhandled `null`/`undefined`, broken edge cases, race conditions, and resource leaks. Confirm new behavior is covered by tests and that existing tests still pass.
+
+```bash
+# Run the project's test suite (adapt to the repo)
+npm test
+```
+
+### Security
+
+Inspect every place untrusted input enters the system. Flag injection risks (SQL, shell, template), missing authentication or authorization checks, unsafe deserialization, path traversal, and secrets committed to the repo.
+
+```bash
+# Scan the diff for accidentally committed secrets
+gh pr diff $ARGUMENTS | grep -nEi '(api[_-]?key|secret|token|password|BEGIN [A-Z ]*PRIVATE KEY)'
+```
+
+> [!WARNING]
+> Never echo a real secret you discover into the review. Report the file and line, recommend rotation, and ask the author to remove it from history.
+
+### Style and maintainability
+
+Check naming, dead code, duplicated logic, oversized functions, and adherence to the project's lint rules and conventions. Prefer the codebase's existing patterns over personal preference.
+
+```bash
+npm run lint
+```
+
+## Classify each finding
+
+Tag every finding by severity so the author knows what blocks merge:
+
+- **Blocker** — must fix before merge (bugs, security holes, broken tests).
+- **Should-fix** — important but not strictly blocking.
+- **Nit** — minor style or polish; optional.
+
+For each finding, cite the exact `file:line`, explain *why* it matters, and propose a concrete fix or a suggested diff.
+
+## Output format
+
+Summarize the review in this structure:
+
+```markdown
+## Review of PR #$ARGUMENTS — <title>
+
+**Verdict:** Approve / Request changes / Comment
+
+### Summary
+<2-3 sentences on what the PR does and overall quality.>
+
+### Blockers
+- `path/to/file.ts:42` — <issue and fix>
+
+### Should-fix
+- `path/to/file.ts:88` — <issue and fix>
+
+### Nits
+- `path/to/file.ts:101` — <issue and fix>
+
+### What looks good
+- <notable strengths worth calling out>
+```
+
+Keep feedback specific and respectful. End with a clear recommendation and the single most important next step for the author.

package/content/commands/run-evals.md

@@ -0,0 +1,34 @@
+---
+description: "Run the project's LLM evaluation suite (DeepEval, promptfoo, or RAGAS) and report scores against thresholds before a merge."
+argument-hint: "<eval suite path / config, or the feature to evaluate>"
+allowed-tools: "Read, Grep, Glob, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the eval target — a path to the eval suite/config, or the feature whose suite should run. Restate what you're evaluating in one sentence first.
+
+This command runs the **LLM evaluation suite** (e.g. [DeepEval](/tools/deepeval), [promptfoo](/tools/promptfoo), or [RAGAS](/tools/ragas)) — it is **not** a unit-test runner. If the project has no eval suite yet, say so and point to scaffolding one rather than inventing ad-hoc checks.
+
+> [!NOTE]
+> Evals are non-deterministic and cost tokens (judge metrics call an LLM). Run the full frozen dataset, not a cherry-picked subset, or the result is meaningless.
+
+## Step 1 — Locate the suite
+
+Find the eval config/tests (e.g. `deepeval`/pytest eval files, `promptfooconfig.yaml`, or a RAGAS script) and the frozen dataset. Confirm the metrics and their thresholds. If none exists, stop and recommend scaffolding one — do not fabricate a suite.
+
+## Step 2 — Run it
+
+Execute the suite over the **full** dataset using the project's runner. Capture the raw output. Do not modify prompts or the dataset to make it pass.
+
+## Step 3 — Report against thresholds and baseline
+
+Produce a table: metric | score | threshold | baseline | pass/fail | delta vs baseline. Call out any metric below threshold or regressed from baseline explicitly.
+
+## Step 4 — Verdict
+
+Give a clear merge verdict: **pass** (all metrics clear threshold, no regression) or **block** (which metric failed, by how much). For a block, point at the likely stage — retrieval, prompt, or model — rather than guessing a fix.
+
+> [!WARNING]
+> Never tune the prompt against the same cases you're reporting on in the same run, and never relax a threshold just to go green. If a threshold is wrong, change it deliberately in its own commit with a rationale.

package/content/commands/scaffold-pgvector-schema.md

@@ -0,0 +1,42 @@
+---
+description: "Scaffold a production-ready pgvector schema and HNSW index for a corpus — matching the project's migration tooling, distance metric, and embedding dimensions."
+argument-hint: "<table/corpus name and embedding dimensions, or a description of the data>"
+allowed-tools: "Read, Grep, Glob, Edit, Write, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the corpus to store: a table/collection name, the embedding dimensions (and ideally the embedding model, so the distance metric is correct), and any metadata fields you'll filter on. If the dimensions or model aren't given, ask — guessing the vector size is the one thing you cannot paper over later.
+
+Goal: produce a **migration-managed** pgvector schema and index that's correct on the first apply — right dimension, right operator class, indexed filter columns — not ad-hoc `CREATE TABLE` run by hand.
+
+> [!NOTE]
+> This scaffolds the schema; it does not embed your data. Embedding and ingestion are a separate step (see [pgvector](/tools/pgvector) and the [vector-search-engineer](/agents/data-ai/vector-search-engineer)).
+
+## Step 1 — Detect the project's conventions
+
+Before writing any SQL, find how this project manages schema: look for a migrations directory and tool (e.g. Prisma, Drizzle, Alembic, Flyway, golang-migrate, Rails, Knex) and match its file naming and format. Confirm Postgres is the database and check whether `vector` is already enabled. Never hand-write DDL out of band when a migration tool owns the schema — generate a migration in the project's format.
+
+## Step 2 — Enable the extension
+
+Add `CREATE EXTENSION IF NOT EXISTS vector;` as the first step of the migration (or confirm it's already enabled, including on the managed provider if there is one — most require enabling it explicitly).
+
+## Step 3 — Define the table and vector column
+
+Create the table (or alter an existing one) with a `vector(N)` column where **N is the embedding model's exact output dimension**. Include the content/reference columns and the metadata columns you'll filter on. State the dimension and model in a comment so the next person knows what produced these vectors.
+
+## Step 4 — Choose the operator class to match the metric
+
+Pick the index operator class to match the embedding model's distance metric — `vector_cosine_ops` for cosine (most common), `vector_l2_ops` for Euclidean, `vector_ip_ops` for inner product. A mismatch here silently degrades recall, so state the assumption explicitly.
+
+## Step 5 — Create the HNSW index (and filter indexes)
+
+Add an HNSW index on the vector column with the chosen operator class, and **B-tree indexes on the metadata columns you filter on** so filtered search doesn't fall back to a scan. Leave HNSW `m` / `ef_construction` at sensible defaults but note that they're tunable — point to the [Embedding Index Tuner](/skills/database/embedding-index-tuner) for fitting them to a recall target.
+
+## Step 6 — Emit a sample query and the apply command
+
+Provide a parameterized nearest-neighbour query with a metadata `WHERE` clause and an `ORDER BY embedding <=> $1 LIMIT 20` (over-retrieve, then rerank), and tell the user the exact command to apply the migration with their project's migration tool. Remind them that building the index on a large existing table should use `CREATE INDEX CONCURRENTLY` to avoid locking writes.
+
+> [!WARNING]
+> Get the **dimension** and **operator class** right before any data is loaded. Changing the vector dimension later means re-creating the column and re-embedding the whole corpus; changing the metric means re-building the index. Both are far cheaper to decide now than to migrate later.

package/content/commands/scaffold-vllm-config.md

@@ -0,0 +1,44 @@
+---
+description: "Scaffold a vLLM serving config for a model on a target GPU — pick precision/quantization and parallelism to fit, set batching and context length, and expose an OpenAI-compatible server."
+argument-hint: "<model + target GPU(s) and VRAM, or a description of the serving workload>"
+allowed-tools: "Read, Grep, Glob, Bash, Edit, Write"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as what to serve: a model (id/size), the target GPU(s) and VRAM, and ideally the workload shape (chat vs. batch, prompt/response lengths, target concurrency). If the GPU/VRAM isn't given, ask — it determines whether the model fits at all and at what precision.
+
+Goal: a **runnable, fits-the-GPU** vLLM serving config with an OpenAI-compatible endpoint — sane defaults a human can then load-test and tune, not a guess that OOMs on first launch.
+
+> [!NOTE]
+> This scaffolds a starting config; it does not load-test or tune to an SLO. For benchmarking and tuning throughput/p95 against a budget, hand off to the [llm-inference-engineer](/agents/data-ai/llm-inference-engineer). For local single-user running, [Ollama](/tools/ollama) is simpler than vLLM.
+
+## Step 1 — Size the model against the GPU
+
+Estimate the model's memory at candidate precisions (FP16/BF16 vs. FP8 vs. AWQ/GPTQ int4) plus KV-cache headroom for your context length and concurrency. Decide whether it fits one GPU or needs **tensor parallelism** (`--tensor-parallel-size N`). State the assumption.
+
+## Step 2 — Choose precision/quantization
+
+Pick the highest precision that fits with headroom; drop to FP8 or 4-bit quantization only as needed to fit, and **flag that quantization can affect quality** so it gets re-checked against an eval set, not assumed safe.
+
+## Step 3 — Set the core serving flags
+
+Produce the `vllm serve` invocation (or equivalent config) with the parameters that matter:
+
+- `--max-model-len` — context length sized to your prompts (don't over-allocate; it costs KV-cache memory).
+- `--gpu-memory-utilization` — how much VRAM vLLM may use (leave headroom).
+- `--max-num-seqs` — concurrency / batch width.
+- `--tensor-parallel-size` — for multi-GPU models.
+- quantization flag if used.
+
+## Step 4 — Expose the OpenAI-compatible endpoint
+
+Confirm the server exposes `/v1/chat/completions` (and `/v1/completions`) so existing OpenAI clients work by changing the base URL. Note the host/port and any served-model-name.
+
+## Step 5 — Emit the config and a smoke test
+
+Output the final command/config plus a one-line `curl` (or OpenAI-client snippet) to verify the endpoint responds, and the env/launch notes (GPU visibility, model download/cache). 
+
+> [!WARNING]
+> The two failure modes to pre-empt: an out-of-memory crash on launch (precision/context/concurrency too high for the VRAM) and a silent quality drop from quantization. Size conservatively with KV-cache headroom, and re-run your eval set after any quantization before trusting the deployment — see [vLLM](/tools/vllm).

package/content/commands/security-scan.md

@@ -0,0 +1,129 @@
+---
+description: "Scan the current diff or given paths for security vulnerabilities."
+argument-hint: "[paths]"
+allowed-tools: "Read, Grep, Glob, Bash"
+---
+
+Audit code for security vulnerabilities and report what you find by severity. This command is **read-only** — investigate and report, but do not edit code, rewrite history, or "fix it while you're in there." Work through the steps below and trace every finding to a concrete line.
+
+## Scope
+
+Decide what to audit before reading a single file:
+
+- If `$ARGUMENTS` is provided, treat it as the set of paths or globs to scan (`src/api`, `app/**/*.ts`, `lib/auth.ts`). Restrict the audit to those files and the code they directly call.
+- If `$ARGUMENTS` is empty, scan the **current diff** — the uncommitted and recently committed changes — so the review matches what is about to ship.
+
+```bash
+# No arguments → derive the scope from the diff
+git diff --name-only HEAD          # unstaged + staged changes vs. HEAD
+git diff --name-only origin/main...HEAD   # everything on this branch
+```
+
+> [!NOTE]
+> Default to the diff, not the whole repository. A focused review of what changed is far more useful than a shallow pass over the entire codebase. Only widen scope when `$ARGUMENTS` tells you to.
+
+## Step 1 — Map untrusted input
+
+Vulnerabilities live where untrusted data crosses a trust boundary. Before pattern-matching, identify every entry point in scope: HTTP handlers, request bodies, query/path params, headers, cookies, file uploads, webhook payloads, message-queue consumers, CLI args, and env-driven config.
+
+```bash
+# Common request/entry-point surfaces (adapt to the stack)
+grep -rnE 'req\.(body|query|params|headers|cookies)|request\.(get|args|json)|process\.argv' <scope>
+```
+
+Trace each tainted value from entry point to where it is used. The checks below all reduce to one question: *does untrusted input reach a dangerous sink without being neutralized?*
+
+## Step 2 — Injection (SQL, command, template)
+
+Look for untrusted input concatenated or interpolated into an interpreter instead of parameterized.
+
+```bash
+# SQL built with string concatenation/interpolation instead of bound params
+grep -rnE "(query|execute|raw)\(.*(\+|\$\{|%s|f\"|f')" <scope>
+
+# Shell execution with interpolated input
+grep -rnE 'exec\(|execSync|spawn\(|os\.system|subprocess\.(run|call|Popen)|child_process' <scope>
+
+# Server-side template rendering from user input (SSTI)
+grep -rnE 'render(_template_string|String)?\(|Template\(|\$\{[^}]*req' <scope>
+```
+
+- **SQL:** flag anything that is not a parameterized query / prepared statement. ORMs are safe only until someone reaches for `.raw()`.
+- **Command:** flag any shell string built from input; the fix is an `exec`-family call with an argument array and no shell, or an allowlist.
+- **Template:** flag user data passed as the *template* rather than as *data* bound into a fixed template.
+
+## Step 3 — Missing authorization (and authentication)
+
+Authentication asks *who are you*; authorization asks *are you allowed to touch this object*. The second is the one people forget. For every state-changing or data-returning handler, confirm there is an explicit ownership/role check.
+
+- Find endpoints that take an object id (`/users/:id`, `/orders/:id`) and verify the handler checks the object belongs to the caller — not just that the caller is logged in. Missing that check is **IDOR / broken object-level authorization**.
+- Watch for checks done in the UI or middleware but **not** re-enforced on the server.
+- Flag admin/privileged routes that rely only on a hidden URL or a client-supplied role.
+
+> [!WARNING]
+> "The user can't reach this page" is not authorization. Anyone can call the endpoint directly. Every protected action needs a server-side check at the point it mutates or returns data.
+
+## Step 4 — Hardcoded secrets
+
+Scan for credentials committed to the repo. Report file and line — **never paste the secret value into your output**, even partially.
+
+```bash
+grep -rnEi '(api[_-]?key|secret|token|passwd|password|client[_-]?secret|aws_[a-z_]*key)\s*[:=]\s*["'\''][^"'\'' ]{8,}' <scope>
+grep -rnE 'BEGIN [A-Z ]*PRIVATE KEY' <scope>
+```
+
+If you find a live credential, treat it as a **Critical** finding: it must be rotated, not just deleted, because it is already in git history.
+
+## Step 5 — SSRF, path traversal, and unsafe deserialization
+
+```bash
+# SSRF: server-side fetch where the URL/host comes from input
+grep -rnE '(fetch|axios|requests\.(get|post)|http\.(get|request)|urlopen)\(' <scope>
+
+# Path traversal: filesystem paths built from input
+grep -rnE '(readFile|open|sendFile|createReadStream|path\.join)\(.*(req|input|params|argv)' <scope>
+
+# Unsafe deserialization
+grep -rnE 'pickle\.loads|yaml\.load\(|unserialize|Marshal\.load|ObjectInputStream' <scope>
+```
+
+- **SSRF:** a user-controlled URL fed to a server-side request lets an attacker hit internal services and cloud metadata (`169.254.169.254`). Require an allowlist of hosts/schemes; blocklists leak.
+- **Path traversal:** input reaching a file path enables `../../etc/passwd`. Require canonicalization plus a check that the resolved path stays inside the intended root.
+- **Deserialization:** `pickle.loads`, `yaml.load` (without `SafeLoader`), and PHP `unserialize` on untrusted bytes are remote code execution. Require safe loaders or a strict schema.
+
+## Step 6 — Missing input validation
+
+Even where there's no obvious sink, unvalidated input causes downstream damage: oversized payloads, type confusion, mass assignment, and bypassed business rules.
+
+- Check that request bodies are validated against a schema (zod, pydantic, JSON Schema) before use — not trusted by shape.
+- Flag **mass assignment**: spreading a request body straight into a DB write (`User.create({ ...req.body })`) lets a caller set `isAdmin`. Require an explicit allowlist of writable fields.
+- Confirm numeric/length/enum bounds, and that file uploads are checked for type and size.
+
+## Step 7 — Report findings
+
+Rank by **severity**, give each finding a concrete fix, and state your **confidence**.
+
+```markdown
+## Security scan — <diff or scope>
+
+**Summary:** <1–2 sentences: N findings, highest severity, overall posture.>
+
+### Confirmed
+- **[Critical] SQL injection** — `src/api/search.ts:48`
+  - Untrusted `req.query.q` is concatenated into the SQL string.
+  - **Fix:** use a parameterized query (`db.query(sql, [q])`).
+  - **Confidence:** high — input flows directly to the sink with no escaping.
+
+### To double-check
+- **[Medium] Possible SSRF** — `src/lib/fetchImage.ts:21`
+  - `url` comes from the request; host allowlisting may exist upstream — verify the caller.
+  - **Fix:** enforce a scheme + host allowlist at this function.
+  - **Confidence:** medium — needs the call site confirmed.
+```
+
+Severity guide: **Critical** (RCE, auth bypass, live secret) · **High** (injection, SSRF, IDOR on sensitive data) · **Medium** (missing validation, traversal behind a guard) · **Low** (defense-in-depth, hardening).
+
+> [!NOTE]
+> Separate **confirmed** issues — where you traced tainted input to a dangerous sink — from things **to double-check** that depend on context you could not verify (an upstream guard, a framework default, a sanitizer elsewhere). Honest confidence is more useful than false certainty in either direction.
+
+End with the single highest-priority issue to address first. Do not modify any files — this command only reports.

package/content/commands/set-perf-budget.md

@@ -0,0 +1,47 @@
+---
+description: "Define and enforce a cost and latency budget for an LLM feature or endpoint — set p95/p99 latency and cost-per-request ceilings, instrument to measure them against real traffic, and wire a check that fails when the budget is breached."
+argument-hint: "<the LLM endpoint/feature to budget, plus any target numbers (e.g. 'chat API, p95 < 2s, < $0.02/req')>"
+allowed-tools: "Read, Grep, Glob, Bash"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the LLM feature or endpoint to put a budget around — and any target numbers the user gave. The job is to turn "it should be fast and cheap" into **explicit, measured ceilings** that a build or monitor can enforce, so cost and latency can't regress silently. A budget nobody checks is a wish; this command produces one that fails loudly.
+
+> [!NOTE]
+> This sets and enforces the budget. To then *find and cut* what's over budget, hand off to the [llm-cost-optimizer](/agents/data-ai/llm-cost-optimizer) agent; for the techniques behind the targets, see [LLM Cost and Latency Engineering](/guides/advanced/llm-cost-latency-engineering).
+
+## Step 1 — Pin the budget numbers
+
+Settle the ceilings before measuring anything:
+
+- **Latency** — p50/p95/p99 targets (budget the **tail**, p95/p99, not the average — users feel the tail). Distinguish total time from time-to-first-token for streamed responses.
+- **Cost** — a cost-per-request ceiling, and/or a daily/monthly spend cap for the feature.
+- **Scope** — which endpoint/feature/model this budget covers, since different routes warrant different budgets.
+
+If the user didn't give numbers, propose defaults from the feature's UX (interactive vs. batch) and current measured baseline, and state them explicitly.
+
+## Step 2 — Establish the baseline
+
+Measure current cost and latency against **representative** traffic — real prompt/response sizes and concurrency, not a single warm request. Pull from existing observability/traces ([Helicone](/tools/helicone), [Portkey](/tools/portkey), or your logs) where available. Report p50/p95/p99 and cost-per-request as they stand, so the budget is grounded in reality and you know the gap.
+
+## Step 3 — Instrument the metrics
+
+Ensure the numbers are actually captured per request: latency (and time-to-first-token), input/output tokens, and computed cost. If instrumentation is missing, add the minimal measurement needed — you can't enforce a budget you don't record.
+
+## Step 4 — Wire the enforcement
+
+Make the budget fail loudly when breached, at the right gate:
+
+- **CI / pre-merge** — a latency/cost regression test over a representative sample that fails the build when p95 or cost-per-request exceeds the ceiling.
+- **Runtime** — alerts or guardrails on p95/p99 and on the daily/monthly spend cap (gateway budgets and rate limits can hard-stop runaway cost).
+
+Pick the gate that matches the risk: regression-prone code → CI; runaway-spend risk → runtime caps.
+
+## Step 5 — Document the budget
+
+Record the ceilings, where they're enforced, the current baseline vs. target, and what to do on a breach (route to the [llm-cost-optimizer](/agents/data-ai/llm-cost-optimizer)). A budget that lives only in someone's head isn't enforced.
+
+> [!WARNING]
+> Budget the tail, not the mean. An average latency under target hides the p99 requests that make users churn — and an average cost hides the expensive outlier prompts that dominate the bill. Set and enforce p95/p99 and per-request ceilings, not just the average.

package/content/commands/setup-claude-ci.md

@@ -0,0 +1,60 @@
+---
+description: "Wire Claude Code into this repo's CI the safe way — install the GitHub App or scaffold the workflow YAML, scope permissions to the minimum, set secrets correctly, and verify with a real trigger."
+argument-hint: "<what CI should do — e.g. 'review PRs', 'fix failing tests', 'respond to @claude mentions'>"
+allowed-tools: "Read, Grep, Glob, Bash, Write, Edit"
+model: sonnet
+---
+
+## Scope
+
+Treat `$ARGUMENTS` as the job Claude should do in CI — review PRs, respond to `@claude` mentions, fix failing tests on a schedule, draft release notes. Restate it in one sentence, including the trigger (mention, PR opened, cron) and the smallest set of abilities the job needs, before touching anything.
+
+Goal: a working `anthropics/claude-code-action@v1` workflow with **minimum permissions**, secrets handled correctly, and a verified first run — not just a YAML file that looks right.
+
+## Step 1 — Detect the starting point
+
+Check for an existing setup: `.github/workflows/*.yml` referencing `claude-code-action`, an installed GitHub App, an `ANTHROPIC_API_KEY` secret (`gh secret list`), and any checked-in `.claude/settings.json` whose permission rules will also apply in CI. Extend what exists rather than duplicating it.
+
+## Step 2 — Choose the integration mode
+
+Map `$ARGUMENTS` to one of the action's two modes:
+
+- **Mention mode** (no `prompt` input) — the action answers `@claude` comments on issues and PRs. Right for on-demand help and "fix this" requests.
+- **Prompt mode** (`prompt` input set) — runs automatically on the workflow's trigger. Right for PR-opened reviews, scheduled audits, release notes.
+
+State the trigger events the workflow will subscribe to and why.
+
+## Step 3 — Prefer the installer, fall back to manual
+
+If the user can run interactive commands, recommend `claude /install-github-app` — it installs the GitHub App, stores the secret, and scaffolds the workflow in one flow. Otherwise scaffold manually:
+
+```yaml
+name: Claude Code
+on:
+  issue_comment:
+    types: [created]
+jobs:
+  claude:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+Adapt `on:` to the chosen trigger; add `prompt:` for prompt mode. For Bedrock/Vertex shops, use `use_bedrock`/`use_vertex` with OIDC instead of a static key.
+
+## Step 4 — Scope it down
+
+Add `claude_args` with the narrowest flags that let the job succeed — e.g. a reviewer gets `--max-turns 12` and read-heavy tools; a test-fixer gets `Edit` plus `Bash(npm test:*)` only. Never pass `--dangerously-skip-permissions` in CI; the runner is not a sandbox you control. Confirm the workflow doesn't run with secrets on arbitrary fork PRs.
+
+> [!WARNING]
+> Treat the bot like any contributor with write access: minimum tools, bounded turns, and the merge button stays human — the action cannot approve PRs by design, so don't engineer around that gate.
+
+## Step 5 — Secrets, correctly
+
+Verify `ANTHROPIC_API_KEY` exists as a repo (or org) secret — `gh secret set ANTHROPIC_API_KEY` if not — and that the key is a dedicated CI key, not someone's personal one, so it can be rotated without breaking laptops. Never echo the key in workflow logs.
+
+## Step 6 — Verify with a real trigger
+
+Don't declare success on a green YAML lint. Fire the actual trigger: open a scratch PR and comment `@claude what does this PR change?` (mention mode) or push a trivial PR (prompt mode). Confirm the action ran, the response landed, and the cost is visible in the run output. Hand back: the workflow file path, the trigger, the permission envelope, and how to tune it later via `claude_args` — pointing at [Running Claude Code in CI](/guides/advanced/claude-code-ci-github-actions) for the deeper reference.