@cursor/july 0.1.94 → 0.1.96

package/skills/ab/SKILL.md

@@ -1,35 +1,24 @@
 ---
 name: agentsdk-ab
 description: >-
-  Author defineAB live A/B metrics plug-ins under agent/ab. Splits traffic into
-  sticky variants and calls onSample with performance metrics as the agent runs
-  — not a test runner. Use when instrumenting production/dev traffic for variant
-  comparison; use defineEval for regression gates.
+  Author defineAB live A/B metrics under agent/ab. Sticky variants
+  and onSample on live runs. Not a test runner. Use when comparing
+  variants on traffic; use defineEval for regression gates.
 ---
 
 # Agent SDK A/B metrics (`defineAB`)
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
-
-`defineAB` is a **live metrics plug-in**. At session creation the engine runs
-`split` and appends durable `ab.assigned` events; the collector folds the
-session event stream and calls `onSample`. There is **no** `agent-sdk ab`
-CLI and **no** assertion API.
-
-Human-facing reference: [`docs/ab.md`](../../docs/ab.md).
+Live metrics plug-in. No `agent-sdk ab` CLI. No assertion API.
+Reference: `docs/ab.md`.
 
 | | `defineEval` | `defineAB` |
 | --- | --- | --- |
-| Job | Regression gates on frozen fixtures | Collect metrics on live runs |
+| Job | Gates on frozen fixtures | Metrics on live runs |
 | Location | `evals/**/*.eval.ts` | `agent/ab.ts` or `agent/ab/<name>.ts` |
-| How it runs | `agent-sdk eval` | Automatically under `serve` / `run` |
-| Driver | `t.send` + gates | `split` → `ab.assigned` + `onSample` |
-
-## Authoring
+| How it runs | `agent-sdk eval` | Under `serve` / `run` |
 
 ```ts
-import { defineAB, splitBySessionHash, splitIf } from "@cursor/july/ab";
+import { defineAB, splitBySessionHash } from "@cursor/july/ab";
 
 export default defineAB({
   name: "concise-instructions",
@@ -37,13 +26,11 @@ export default defineAB({
     control: { label: "Baseline" },
     treatment: {
       label: "Shorter",
-      // Optional: appended to agent instructions for this arm.
       instructions: "Keep replies to one short paragraph.",
     },
   },
   split: splitBySessionHash({ holdout: 0.1 }),
   derive: {
-    // Keep sync + cheap — runs on every event, including message deltas.
     weatherCalls: (event) =>
       event.type === "action.result" && event.data.toolName === "get_weather"
         ? 1
@@ -55,8 +42,6 @@ export default defineAB({
 });
 ```
 
-In tools, read the arm from session context:
-
 ```ts
 async execute(input, ctx) {
   if (ctx.session.abs?.["concise-instructions"] === "treatment") {
@@ -65,78 +50,9 @@ async execute(input, ctx) {
 }
 ```
 
+Enrollment is at session creation. Eval sessions skip it. Do not
+use `splitIf` to filter evals. Split helpers and `onSample`
+fields: `docs/ab.md`.
 
-Discovery: `agent/ab.ts` and `agent/ab/*.ts`. Name defaults to file stem or `config.name`.
-
-Optional project defaults in `agent/ab.config.ts` (retention + persistence):
-
-```ts
-import {
-  defineABConfig,
-  persistABSamplesToDir,
-  persistABSnapshotsToDir,
-} from "@cursor/july/ab";
-
-export default defineABConfig({
-  // maxPlaygroundSessions: 200, // optional; default 200; A/Bs tab / GET /v1/abs only
-  persistSamples: persistABSamplesToDir(".agent-serve/ab-samples"),
-  persistSnapshots: persistABSnapshotsToDir(".agent-serve/ab-snapshots"),
-});
-```
-
-Session `events.ndjson` remains the assignment/metrics source of truth.
-`persistSamples` / `persistSnapshots` are author-controlled exports (like
-eval `persistRuns`).
-
-### Stream model
-
-Typical new-session prefix:
-
-1. `session.started`
-2. one `ab.assigned` per experiment (`variant` key or `null` skip)
-3. `message.received` / `turn.started` / …
-
-Enrollment is **at session creation** (before the first turn) so each arm can
-vary instructions and tool behavior from a known assignment. Failed/`null`
-splits persist as `ab.assigned` with `variant: null` (sticky skip). The
-collector is a pure fold over the log. `SessionRecord.abs` is a convenience
-mirror, not a metrics store. After park/restart it replays `events.ndjson` to
-rebuild counters without re-firing `onSample`.
-
-**Evals are separate:** the eval harness creates sessions with
-`purpose: "eval"` (playground Evals / `agent-sdk eval`). Those skip
-enrollment entirely — no `ab.assigned`, no `onSample`, omitted from
-`GET /v1/abs`. Ordinary chat / `agent-sdk run` / Slack stay `"live"`.
-Do not use `splitIf` to filter evals; the framework already does.
-
-After enrollment, arms are on `session.abs` (experiment → variant | `null`)
-for tools/hooks, and optional per-variant `instructions` are appended to the
-agent prompt for that session (a treatment arm can, say, switch `get_weather`
-to °C for its sessions).
-
-### Split helpers
-
-| Helper | Behavior |
-| --- | --- |
-| `splitBySessionHash({ weights?, holdout?, salt? })` | Sticky hash → arm |
-| `splitByRandom({ weights?, holdout? })` | Random once, then sticky |
-| `splitAlways("control")` | Pin all new sessions |
-| `splitNone()` | Skip everyone (pause in place) |
-| `splitIf(pred, inner)` | Skip unless `pred` |
-| `(ctx) => …` | Custom — variant key or `null` |
-
-### Built-in metrics
-
-`turns`, `turnFailures`, `toolCalls`, `toolErrors`, token fields, `wallTimeMs`,
-plus `custom.*` from `derive`. `onSample` fires on `turn.completed` / `turn.failed`.
-
-Playground **A/Bs** tab and `GET /v1/abs` fold the same durable streams into
-per-session assignments and aggregate arm totals (no separate metrics store).
-
-### `derive` cost
-
-`derive` extractors run on **every** session event (same cost model as hooks).
-Keep them synchronous and cheap — no network, no disk, no heavy parsing.
-
-Before wiring: pick experiment name + arm labels, a split helper (and who
-to leave out), and a real `onSample` sink — do not invent credentials.
+Pick a name, arm labels, a split, and a real `onSample` sink. Do
+not invent credentials.

package/skills/create-agent/SKILL.md

@@ -1,142 +1,99 @@
 ---
 name: agentsdk-create-agent
 description: >-
-  Scaffold a new Agent SDK agent through a guided AskQuestion interview —
-  purpose, name, runtime, model, channels, MCP connections, capabilities —
-  then verify it serves and hand off to hillclimbing. Read this skill when
-  creating a new agent.
-paths:
-  - packages/agent-serve/**/*
+  Scaffold a new Agent SDK agent: short AskQuestion interview, then
+  verify a turn and hand off to hillclimb. Use when creating a new
+  agent. Ask only what the invoking message left open.
 ---
 
 # Create an Agent SDK agent
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
+2. **Scaffold.** `agent-sdk init`, then shape the files.
+3. **Verify.** `validate` / `info` / `call`, then a model turn.
+4. **Channels.** Slack, GitHub, webhook, or schedule as chosen.
+5. **Hillclimb.** `skills/hillclimb/SKILL.md`.
 
-Stand up one new agent project via a short interview, scaffold it, get
-channels working
-with the user, prove a turn runs end-to-end, and set up the improvement loop.
-Sibling skills: `framework-map` for orientation, `setup-slack` for Slack
-wiring, `mcp-auth` for host MCP OAuth, `github` for webhook-driven
-agents, `evals` for the eval API, `ab` for live A/B metrics, `otel` for
-OpenTelemetry export, `hillclimb` for iteration once the agent runs.
-
-Read `framework-map/SKILL.md` first if you haven't; treat the package
-`AGENTS.md` and `README.md` as ground truth for
-framework behavior. Run the CLI with Node, never Bun (Bun corrupts harness
-tool-result streams): use the installed `agent-sdk` bin, or from a source
-checkout `pnpm exec tsx src/bin/agent-serve.ts <command> …` — written as
-`agent-sdk …` below.
+Read `skills/framework-map/SKILL.md` if you have not. CLI is
+`agent-sdk`. Public docs:
+`node_modules/@cursor/july/dist/docs/llms.txt` or `/docs/llms.txt`
+on a running host.
 
 ## Interview
 
-Walk the user through the decisions with the `AskQuestion` tool: batched
-questions, concrete options, the recommended option listed first and labeled
-`(recommended)` so one click accepts it. Rules:
-
-- **Mine the invoking message first.** Never ask a question it already
-  answers. Target: at most two rounds before files appear.
-- **Stage the rounds.** Round 1 fixes identity; round 2 fixes the surface and
-  is tailored by round 1 (no MCP question for a chat toy, no cloud-repos
-  question for local runtime).
-- Use multi-select (`allow_multiple: true`) for channels, MCP connections, and
-  capabilities; single-select elsewhere. Add an "Other" option wherever a
-  custom answer is plausible (name, model, MCP server) — its freeform text is
-  the answer.
-- **Ask about decisions, not implementation.** Instructions wording, tool
-  names, file layout, env prefix, and eval shape are your job — derive them
-  from the purpose and show the result instead of asking.
-- If `AskQuestion` is unavailable or the user says "just go", state the
-  defaults you are assuming in one short list and proceed.
-
-### Round 1 — identity
+`AskQuestion`: batched, recommended option first and labeled
+`(recommended)`.
+
+- Mine the invoking message. Target: two rounds, then files.
+- Round 1 is identity. Round 2 is the surface, tailored by round 1.
+- Multi-select for channels, MCP, capabilities. Other where a
+  custom answer is plausible.
+- Ask decisions, not how to build it. File layout, tool names,
+  env prefix, and eval shape are yours.
+- If `AskQuestion` is missing or the user skips, state defaults
+  in one list and proceed.
+
+### Round 1: identity
 
 | Question | Options |
 | --- | --- |
-| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other (describe) |
-| **Name** | 2–3 slug suggestions derived from the purpose + Other. Slug = directory name: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs`; lowercase-hyphenated |
-| **Location** | `./<slug>` (default) · another directory (user names it) |
+| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |
+| **Name** | 2–3 slugs from the purpose + Other. Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
+| **Location** | `./<slug>` (default) · another directory |
 
-### Round 2 — surface
+### Round 2: surface
 
 | Question | Options | Guidance |
 | --- | --- | --- |
-| **Runtime** | `local` (default) · `cloud` | Local runs on this machine. Cloud runs on a Cursor cloud agent and needs `cloud.repos`. Server tools and skills work on both. Tool approvals and sandbox seeds are local only. Recommend local unless the purpose needs a cloud checkout. |
-| **Model** | `grok-4.5` with `effort=high`, `fast=true` (default) · Other model id | Effort and fast are params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` — the SDK rejects suffix-style ids. |
-| **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack is a dedicated Socket Mode app (`agent-sdk slack create` — own bot user + one app/token pair per agent). When Slack is picked, follow `setup-slack/SKILL.md`. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
-| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Privileged servers the model must not see go in `agent/host-connections/` instead. |
-| **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Always recommend at least one smoke eval. |
+| **Runtime** | `local` (default) · `cloud` | Cloud needs `cloud.repos`. Approvals and sandbox seeds are local only. Recommend local unless the job needs a cloud checkout. |
+| **Model** | `grok-4.5` + `effort=high`, `fast=true` · Other id | Params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` |
+| **Channels** (multi) | playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule | Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook. |
+| **MCP** (multi) | none · remote URL · local stdio · Cursor account connectors · Other | One file under `agent/mcp-connections/`. Account file is `account.ts`, never `cursor.ts`. Named local tools need `advertiseTools: true`. Privileged servers go in `agent/host-connections/`. |
+| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend) | Always recommend one smoke eval. |
 
-Close the round with a one-screen plan — chosen options plus the file tree you
-intend to create — and a final gate: "Scaffold it" / "Adjust something". Only
-write files after approval.
+Close with the plan and file tree, then "Scaffold it" / "Adjust
+something". Write files only after approval.
 
-## Fill in the blanks
+## Fill the blanks
 
-Everything the interview did not fix is yours to decide. Derive it from the
-purpose, and reach for the proven shape instead of
-inventing:
-
-| Purpose looks like | Proven shape |
+| Purpose | Shape |
 | --- | --- |
-| Slack chat assistant | `slackChannel()` with suggested prompts; run `agent-sdk slack create` for the bot and tokens |
-| PR review with host-prepared evidence | channel `callTool` prep into a trimmed workspace `pr/` tree |
-| GitHub-webhook automation | `githubChannel()` hooks, per-PR debounce, replay fixtures |
-| Domain assistant over live APIs / MCP | server + agent tools, a stdio MCP connection, a skill, a schedule |
-| Wrap an existing pipeline/tool | GitHub `{ task }` hook driving a deterministic loop under `agent/lib/` |
-
-Defaults that make first cuts good:
-
-- **Minimal surface.** Instructions + 1–2 real tools + the chosen channels +
-  one smoke eval. Unpicked capabilities are follow-ups, not scope.
-- **`local.cwd`.** Keep the harness outside a monorepo checkout
-  (`~/.cache/agent-serve/<slug>`). Discovery does this for nested git
-  projects. Point cwd at a checkout only when the agent must inherit that
+| Slack chat | `slackChannel({ envPrefix })` + suggested prompts. `agent-sdk slack create` mints the bot. Prefix: `skills/setup-slack/SKILL.md` |
+| PR review with host prep | Channel `callTool` into a trimmed workspace `pr/` tree |
+| GitHub automation | `githubChannel()` hooks, replay fixtures |
+| Domain assistant | Server tools + one MCP connection + a skill |
+| Wrap an existing pipeline | GitHub `{ task }` over a thin `agent/lib/` loop |
+
+Defaults:
+
+- Instructions + 1–2 tools + chosen channels + one smoke eval.
+- `local.cwd` stays outside a monorepo checkout (default: a cache
+  directory under `~/.cache`) unless the agent must inherit that
   tree.
-- **Instructions** (`agent/instructions.md`, required): a few lines — identity,
-  when to use which tool, output shape. Not an essay.
-- **Tool per file**, filename = tool name the model sees. Prefer
-  `execution: "server"` with a zod `inputSchema`; use `execution: "agent"`
-  (script) only when the tool must run where the agent runs (or runtime is
-  cloud). Gate side-effecting tools with `needsApproval: true`. For long
-  tool descriptions, reminder prompts, channel `context`, and errors, use
-  `prompt\`…\`` / `prompt.lines\`…\`` from `@cursor/july` (dedents indented
-  multi-line strings).
-- **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
-  `MY_AGENT_SLACK_*`); `agent-sdk slack create` derives it for you.
-- **Host prep beats model wandering — for evidence, not judgment.** When the
-  purpose has a deterministic setup step (fetch a PR, seed files), do it in
-  the channel handler via `callTool` / `workspaceFiles` rather than
-  instructing the model to do it. Stop there: host code that formats,
-  summarizes, classifies, or composes replies is the model's job specified
-  badly, and it never comes off the books.
-
-### The deterministic-path budget
-
-TypeScript on the deterministic path is a permanent liability — every line
-brings types, tests, restarts, and drift against the framework; prose is
-cheap to change. Default every behavior to instructions/skills and promote
-it to code only when it earns a row on the left:
-
-| Code owns (earns its keep) | Model owns (keep out of code) |
+- `agent/instructions.md`: identity, when to use which tool,
+  output shape.
+- One tool per file. Prefer `execution: "server"` + zod
+  `inputSchema`. Gate side effects with `needsApproval: true`.
+- Long prompts: `prompt\`…\`` / `prompt.lines\`…\`` from
+  `@cursor/july`.
+- Host prep is for evidence (`callTool`, `workspaceFiles`), not
+  judgment, formatting, or replies.
+
+### Deterministic-path budget
+
+Default to instructions and skills. Promote to TypeScript only
+when it earns the left column:
+
+| Code owns | Model owns |
 | --- | --- |
-| Side-effect gates and actuation (approve, deploy, post) | Composing human-facing output — replies, reports, comments, tables — to a shape stated in instructions |
-| Idempotency / dedupe of external writes | Summarizing, classifying, wording, judgment calls |
-| Auth, secrets, signature verification | Deciding what to do next from ground truth |
-| Evidence seeding (`workspaceFiles`, channel `callTool` prep) | Interpreting soft failures and choosing retries |
-| Hard caps at API boundaries (chunk limits, truncation) | Formatting niceties (links, emphasis, ordering) under those caps |
-
-Two smells to check before scaffolding and again before hand-off:
-
-- **Prose in TS.** An `instructions.ts` / `prompt.ts` string builder is a
-  skill file wearing a trench coat — write `.md` and interpolate only what
-  is truly dynamic.
-- **Inverted ratio.** A first cut whose `agent/lib/` + `tools/` dwarf its
-  instructions + skills (~3:1 or worse) is either wrapping an existing
-  deterministic pipeline (fine — keep the wrapper thin and say so) or
-  building a service with a vestigial model turn. Move procedure back into
-  prompts, or question whether this should be an agent at all.
+| Side-effect gates (approve, deploy, post) | Human-facing output to a stated shape |
+| Dedupe of external writes | Summarizing, classifying, wording |
+| Auth and signature checks | What to do next from ground truth |
+| Evidence seeding | Soft-failure retries |
+| Hard API caps | Formatting under those caps |
+
+Smells: prose builders in `.ts` (write `.md`); `agent/lib/` +
+`tools/` dwarfing instructions + skills on a first cut.
 
 ## Scaffold
 
@@ -144,124 +101,67 @@ Two smells to check before scaffolding and again before hand-off:
 agent-sdk init ./<slug>
 ```
 
-`init` writes `package.json` (with `typescript` dev deps and a
-`check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
-`agent/instructions.md`, a demo `agent/tools/echo.ts`, and
-`agent/hooks/memory.ts`. Existing files are left alone (`exist`). It then
-runs `npm install`, and when the host is unsigned runs `login` and waits
-before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
-plan:
-
-1. `tsconfig.json` — init writes a strict, `noEmit` config covering `agent/`
-   and `evals/`; extend it only when the project needs more.
-2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`. Nested git checkouts get `local.cwd` under `~/.cache/agent-serve/<slug>` at discovery even if omitted. Add the `cloud: { repos: [...] }` block for cloud runtime.
-3. `agent/instructions.md` — real instructions; delete or replace `echo.ts`
-   with the real tools.
-4. Add the chosen `channels/`, `mcp-connections/`, `skills/`, `subagents/<id>/`
-   (needs `description`), `schedules/`, `hooks/`, `sandbox/workspace/`. For
-   Slack, do not hand-write the channel — `agent-sdk slack create --dir ./<slug> --name "<Name>"`
-   opens the dashboard wizard (env prefix from the directory name);
-   for a Slack app they own at api.slack.com, `agent-sdk slack init --manual --dir ./<slug> --name "<Name>"`;
-   customize `agent/channels/slack.ts` afterwards (e.g. `suggestedPrompts`).
-5. `evals/evals.config.ts` — `defineEvalConfig({ maxConcurrency: 20 })`
-   (playground runs are memory-only unless you add `persistRuns`)
-   (`maxConcurrency` is required; hard-capped at 200 due to model provider
-   request limits) plus eval cases under `evals/**/*.eval.ts` — prefer one
-   suite file with `cases: [{ id, test }, …]` for related datapoints, or a
-   single `test` for one smoke. Assert `t.succeeded()` + `t.calledTool(...)`
-   (case id = file path, or `<fileId>/<case.id>`). Full assertion API and
-   fixture strategy: `evals/SKILL.md` (sibling skill).
-
-Stick to deps the Agent SDK already
-ships (`zod`, `@modelcontextprotocol/sdk`, `tsx`); a new npm dep needs its own
-install story and is a smell for a first cut.
+`init` writes the project, runs `npm install`, and may wait on
+`login`. Then shape it:
 
-## Verify
+1. `defineAgent` with the chosen model/runtime. Add
+   `cloud: { repos: [...] }` for cloud.
+2. Real `instructions.md`. Replace `echo.ts`.
+3. Chosen `channels/`, `mcp-connections/`, `skills/`,
+   `subagents/<id>/` (needs `description`), `schedules/`, `hooks/`.
+   Slack: `agent-sdk slack create --dir ./<slug> --name "<Name>"`,
+   not a hand-written channel. Manual Slack app:
+   `agent-sdk slack init --manual`.
+4. `evals/evals.config.ts` with `maxConcurrency: 20` (required;
+   cap 200) plus `evals/**/*.eval.ts`. Assert `t.succeeded()` +
+   `t.calledTool(...)`. API: `skills/evals/SKILL.md`.
 
-No API key needed for the structural half — run these first and fix every
-error diagnostic:
+Stay on deps the Agent SDK already ships (`zod`,
+`@modelcontextprotocol/sdk`, `tsx`).
+
+## Verify
 
 ```bash
-agent-sdk validate --dir ./<slug>            # zero errors (warnings explain runtime mismatches)
-agent-sdk info --dir ./<slug> --json         # surface matches the plan
-agent-sdk call <tool> --dir ./<slug> --input '{…}'   # server tools, deterministic, no model
+agent-sdk validate --dir ./<slug>
+agent-sdk info --dir ./<slug> --json
+agent-sdk call <tool> --dir ./<slug> --input '{…}'
 agent-sdk eval --dir ./<slug> --list
-npx tsc --noEmit -p ./<slug>                   # or the project's own type-check task
+npx tsc --noEmit -p ./<slug>
 ```
 
-The typecheck matters: everything above runs through tsx, which strips types
-without checking them. The classic miss is a tool `execute` return that does
-not satisfy `ToolExecuteResult` — returns must be JSON-shaped
-(`ToolResultValue`), so use plain object literals or `type` aliases, not
-`interface` types (their lack of an index signature fails assignability).
+tsx does not typecheck. Tool `execute` must return JSON-shaped
+values: object literals or `type` aliases, not `interface` types.
 
-`serve` also boots without a key (good for checking channel mounts and the
-playground shell), but model turns need `CURSOR_API_KEY` — ask the user for
-one if the environment lacks it (minted in the Cursor dashboard). If no key
-is forthcoming, finish every key-free check, confirm `run` fails with only
-the clean API-key error, and hand these to the user as their next steps:
+Model turns need `CURSOR_API_KEY`. Without one, finish the
+key-free checks, confirm `run` fails with only the API-key error,
+and hand these over:
 
 ```bash
-agent-sdk run --dir ./<slug> --message "<fixture prompt>"   # JSON trajectory
-agent-sdk serve --dir ./<slug> --dev
-# playground: http://127.0.0.1:3000/<slug>/playground
+agent-sdk run --dir ./<slug> --message "<fixture prompt>"
+agent-sdk serve --dir ./<slug> --mode single --dev
+# http://127.0.0.1:3000/playground
 agent-sdk eval --dir ./<slug>
 ```
 
-Serve only the new agent's directory during bring-up — pointing `serve` at a
-parent folder also mounts every sibling agent it contains.
-Runtime state lands in `<project>/.agent-serve/` (gitignored). Nested
-checkouts default `local.cwd` to `~/.cache/agent-serve/<slug>` at
-discovery. `--state-root` is for session files, not harness cwd.
-
-## Channel setup with the user
-
-Each surface beyond the playground has a human gate — drive the user through
-it, verify with doctor commands, and smoke-test before declaring victory.
-
-- **Slack** — follow `packages/agent-serve/skills/setup-slack/SKILL.md` end
-  to end: `slack create` → doctor → `@mention` smoke. Manual path only
-  when they own the Slack app at api.slack.com.
-- **GitHub** — follow `packages/agent-serve/skills/github/SKILL.md`
-  (fixtures / replay / forward / `--cursor-events`).
-- **Custom webhook** — `POST /<slug>/v1/channels/<id>/<route>`. Default
-  `localDevStrict()` is loopback-only; add `bearerAuth(...)` before any
-  tunnel or shared host.
-- **Schedules** — never auto-fire under `--dev`; dispatch via
-  `POST /<slug>/v1/dev/schedules/<id>`.
-
-## Hand off to hillclimbing
-
-Scaffolding proves the agent runs; it says nothing about quality. Once the
-smoke turn passes, propose the improvement loop — one last `AskQuestion` if
-choices are open:
-
-1. **Fixtures** — 1–3 fixed inputs worth optimizing against (a real PR URL, a
-   canonical Slack question, a saved webhook payload).
-2. **Success criteria** — what "better" means first (correct tool choice,
-   fewer tool calls, faster wall time, output quality).
-3. **Freeze line** — what must not change (API contract, output shape).
-
-Those are exactly the preconditions in `skills/hillclimb/SKILL.md`; suggest
-the user (or you) follow that skill with the fixtures you agreed on. Seed
-the loop by pointing
-at the smoke run's session (`.agent-serve/<slug>/sessions/<id>/events.ndjson`
-or the trace under `.agent-serve/traces/`) as the baseline measurement — or,
-when no API key was available, name the user's first real turn as the
-baseline instead. For GitHub agents, snapshot replay fixtures now
-(`agent-sdk github replay ... --dry-run --out fixtures/github`) so the
-loop starts deterministic.
-
-## Working agreements
-
-- Interview → plan gate → scaffold → verify → channel setup → hillclimb
-  handoff. Do not skip verification because the files "look right".
-- Fill blanks yourself. Re-ask only when an answer contradicts the framework,
-  such as approval-gated tools on the cloud runtime.
-- Do not deploy, post to real Slack/GitHub surfaces beyond the smoke tests the
-  user asked for, or commit without being asked.
-- Keep the first cut reviewable: if the plan grows past ~10 files, cut scope
-  and say what you deferred. Re-check the deterministic-path budget at
-  hand-off — behavior that crept into `lib/` during bring-up (formatting,
-  reply shaping, classification) goes back into instructions before you call
-  it done.
+Serve only this agent's directory. Session files land in the
+project state directory (`--state-root`). That is not harness cwd.
+
+## Channel setup
+
+- **Slack.** `skills/setup-slack/SKILL.md`
+- **GitHub.** `skills/github/SKILL.md`
+- **Custom webhook.** `POST /v1/channels/<id>/<route>`.
+  Loopback-only until you add `bearerAuth(...)`.
+- **Schedules.** Never auto-fire under `--dev`.
+  `POST /v1/dev/schedules/<id>`.
+
+## Hillclimb handoff
+
+Once a smoke turn passes, agree fixtures, success criteria, and a
+freeze line, then follow `skills/hillclimb/SKILL.md`. Seed from
+the smoke session under the project state directory. GitHub:
+snapshot `agent-sdk github replay ... --dry-run --out fixtures/github`.
+
+Do not deploy or post to real Slack/GitHub beyond the smoke the
+user asked for. If the plan grows past ~10 files, cut scope.
+Re-check the budget at hand-off.