@cursor/july 0.1.92 → 0.1.94

package/docs/example-agents/approval-buddy.md

@@ -1,271 +0,0 @@
----
-title: "Keep PR approval policy deterministic with Approval Buddy"
-description: "Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals."
----
-
-# Keep PR approval policy deterministic with Approval Buddy
-
-Approval Buddy approves eligible pull requests from a fixed roster and
-declines every other request. GitHub still blocks self-approval when the stamp
-identity authored the PR. Code decides eligibility. The model prepares
-evidence, runs two specialist reviews, and passes their findings to the
-approval tool without changing the policy decision.
-
-Use this example when an agent can make a judgment inside a workflow, but
-authorization and the final side effect must stay in deterministic code.
-
-[Browse the Approval Buddy source.](../../examples/approval-buddy/)
-
-## Keep approval policy in code
-
-Approval Buddy draws three hard boundaries:
-
-- `prepare_review` and `approve_pr` re-read the live PR and apply the same
-  eligibility rules.
-- Two subagents inspect prepared evidence, but their findings never grant or
-  block approval.
-- Only `approve_pr` posts the GitHub review.
-
-A spoofed webhook, Slack message, or model claim can't add someone to the
-buddy roster. The mutating tool checks the source of truth immediately before it
-acts.
-
-## Follow the intended stamp flow
-
-The root instructions ask the model to run this sequence for a qualifying PR:
-
-1. A non-draft `pull_request` event arrives with action `opened`, `reopened`,
-   or `ready_for_review`.
-2. The GitHub channel checks its repository allowlist and starts a session.
-3. `turn.started` posts a pending commit status.
-4. The model calls `prepare_review`.
-5. Host code fetches the live PR. It checks the author, open state, merged
-   state, and draft state.
-6. A qualifying PR gets `pr/MANIFEST.md`, `pr/meta.json`, and
-   `pr/diff.patch` in the session workspace. Diffs above 2,000,000
-   characters are truncated and marked in metadata.
-7. The model calls both review subagents through the built-in `task` tool.
-8. It concatenates their contracted replies and calls `approve_pr`.
-9. `approve_pr` re-runs eligibility, posts an `APPROVE` review, and returns
-   the outcome.
-10. The channel posts a final commit status. A self-approval block also gets
-    a short timeline comment because no approval review can appear.
-
-Ineligible PRs skip evidence and subagents. The model still calls
-`approve_pr` so the deterministic tool returns the formal decline reason.
-
-Steps 4 through 9 are prompt-driven. The channel doesn't enforce tool order
-or prove both subagents ran, and `approve_pr` accepts missing findings. A
-failed turn clears the pending status with a green non-blocking result without
-approving the PR.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root agent and policy prompt | [`agent/agent.ts`](../../examples/approval-buddy/agent/agent.ts), [`agent/instructions.md`](../../examples/approval-buddy/agent/instructions.md) | Configure the local agent and describe orchestration order. |
-| GitHub channel | [`agent/channels/github.ts`](../../examples/approval-buddy/agent/channels/github.ts) | Filter wakes, lease GitHub access, and publish status events. |
-| Slack channel | [`agent/channels/slack.ts`](../../examples/approval-buddy/agent/channels/slack.ts) | Accept approval-bot stamp and qualification requests. |
-| Server tools | [`agent/tools/`](../../examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
-| Deterministic policy | [`agent/lib/approve.ts`](../../examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](../../examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
-| Review subagents | [`agent/subagents/`](../../examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
-| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage` (Bugbot `agent_serve_*`). |
-| Live A/B experiment | [`agent/ab.ts`](../../examples/approval-buddy/agent/ab.ts) | Compare baseline responses with a concise, presentation-only treatment (`concise-results`). |
-| Evals and unit tests | [`evals/`](../../examples/approval-buddy/evals/), [`agent/lib/`](../../examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
-
-There are no authored skills, MCP connections, schedules, reminders, hooks,
-sandbox seeds, or tool approvals.
-
-## Prepare credentials
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential.
-- GitHub access to read PRs, post reviews, create commit statuses, and
-  post the self-approval visibility comment.
-
-Optional GIF selection uses:
-
-- `GIPHY_API_KEY` or `APPROVAL_BUDDY_GIPHY_API_KEY`,
-- `APPROVAL_BUDDY_STAMP_GIF`, or
-- severity-specific `APPROVAL_BUDDY_STAMP_GIF_<LEVEL>` variables.
-
-If you enable Giphy in a hosted copy, declare its secret and
-`api.giphy.com` egress.
-
-## Validate without approving a PR
-
-```bash
-agent-sdk validate --dir examples/approval-buddy
-agent-sdk info --dir examples/approval-buddy --json
-```
-
-List the deterministic roster:
-
-```bash
-agent-sdk call list_buddies \
-  --dir examples/approval-buddy \
-  --input '{}'
-```
-
-Set a known merged PR, then run the read-only precheck:
-
-```bash
-MERGED_PR_URL=https://github.com/your-org/your-repo/pull/123
-agent-sdk call prepare_review \
-  --dir examples/approval-buddy \
-  --input "{\"prUrl\":\"$MERGED_PR_URL\"}"
-```
-
-The result should decline because the PR is no longer open. `prepare_review`
-never posts an approval.
-
-> [!CAUTION]
-> Don't use `agent-sdk call approve_pr` as a smoke test. The tool has no
-> `needsApproval` gate and posts a real GitHub review when the PR qualifies.
-
-## See why preparation is separate
-
-`prepare_review` is read-only. It checks policy before fetching a large diff,
-so declined requests don't spend review-agent work.
-
-Direct calls return the evidence file map because their scratch workspace is
-deleted after the call. In-session calls write the tree to
-`ctx.workspaceDir`, where both subagents can read it.
-
-`approve_pr` repeats the live check instead of trusting preparation. A PR can
-close, merge, become a draft, or change author-related context between the two
-steps. Revalidation keeps the final write bound to current state.
-
-This is a reusable two-tool pattern:
-
-- a read-only tool prepares and explains the decision,
-- a mutating tool repeats policy at the side-effect boundary.
-
-## Fan out two review contracts
-
-The two discovered subagents have different contracts:
-
-- The security reviewer reports bugs, breaking changes, and security findings
-  with `High`, `Medium`, or `Low` tags.
-- The code-quality reviewer reports maintainability and structure concerns
-  with `Blocker`, `Major`, or `Minor` tags.
-
-The parent calls both through the harness `task` tool. They inherit the root
-agent's execution surface and read the same `pr/` workspace. The prompt asks
-the parent not to rewrite either reply. The review body trims the combined
-text and caps it at 16,000 characters.
-
-Findings are informational. A high-severity finding doesn't veto the stamp.
-That policy is explicit in the root instructions and approval code.
-
-## Trace GitHub channel behavior
-
-The channel uses `githubChannel` with:
-
-- a configured repository allowlist on the account-linked GitHub transport,
-- a second optional `APPROVAL_BUDDY_REPOS` wake filter,
-- `deliverReplies: false`,
-- progress reactions disabled, and
-- event handlers for turn start, `approve_pr` results, and failed turns.
-
-The source requests `contents-write`, even though the documented workflow
-posts reviews, statuses, and comments. When adapting the example, start with
-`pr-write` and opt up only if a tool must push code.
-
-Every terminal status is green by design. Declines and crashed turns are
-informational, not merge-blocking. This is a product decision in the example,
-not an Agent SDK default.
-
-A successful turn that never calls `approve_pr` leaves the pending status in
-place. The channel clears it on `approve_pr` results and `turn.failed`, but
-has no `turn.completed` fallback.
-
-`github replay` reaches the same channel and can post a real approval, status,
-or comment. Use replay only against a repository and PR created for this
-test.
-
-## Use Slack for explicit requests
-
-Start the dev server:
-
-```bash
-agent-sdk dev examples/approval-buddy
-```
-
-Then ask through the signed-in account-linked Slack connection:
-
-> Would this PR qualify for a stamp?
-
-The instructions route qualification questions to `prepare_review` only. A
-stamp request runs the complete flow and may approve the PR.
-
-This channel uses the account-linked transport instead of a dedicated Socket
-Mode app.
-
-## See how durable storage fits
-
-`defineStorage` replaces the default local session store with a shared,
-durable key-value adapter. Approval Buddy chooses:
-
-- a 15-second write debounce,
-- startup restoration for up to 200 sessions, and
-- a 14-day restore window.
-
-That policy fits long-lived Slack threads and a small webhook fleet. The
-security reviewer uses the same adapter with lazy restore, which fits its
-shorter sessions.
-
-## Run the regression suite
-
-List the four eval cases:
-
-```bash
-agent-sdk eval --dir examples/approval-buddy --list
-```
-
-The suite covers:
-
-- buddy-list routing,
-- declining a merged PR,
-- using only `prepare_review` for a qualification question, and
-- the combined findings headings and severity format over seeded evidence.
-
-Run the safe qualification case:
-
-```bash
-agent-sdk eval \
-  --dir examples/approval-buddy \
-  qualify/merged-pr-question \
-  --json
-```
-
-The qualification case reads a live merged PR. The seeded format case shown
-by `--list` uses a planted auth-bypass diff
-and checks for a `task` call, both headings, and severity tags. It doesn't
-prove both named subagents ran or whether their output reached `approve_pr`.
-Unit tests under `agent/lib/` cover policy, self-approval handling, evidence
-limits, status mapping, GIF selection, and severity parsing.
-
-## Reuse the policy boundary
-
-Keep these properties when you replace the buddy policy:
-
-1. Put authorization in typed code.
-2. Fetch the source of truth inside both prepare and mutate steps.
-3. Give the model evidence only after the request qualifies.
-4. Treat specialist findings as data, not authority.
-5. Keep the core domain mutation in one named tool. Treat channel status and
-   visibility writes as separate, audited effects.
-6. Add a human approval gate if your policy still needs operator consent.
-7. Test read-only routing separately from mutation.
-
-## Where to go next
-
-- [GitHub](../guides/github.md)
-- [Tools](../reference/tools.md)
-- [Subagents](../reference/subagents.md)
-- [Storage](../storage.md)
-- [Slack](../guides/slack.md)
-- [Evals](../evals.md)

package/docs/example-agents/benny.md

@@ -1,187 +0,0 @@
----
-title: "Route Slack work through repository playbooks"
-description: "Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace."
----
-
-# Route Slack work through repository playbooks
-
-This agent is a Slack teammate for a product team. Mentions and direct
-messages reach it through an account-linked transport. New top-level posts in
-an allowlisted issue channel reach it through a dedicated Slack app, even
-without a mention. The agent then selects a repository playbook for triage,
-reproduction, fixes, reviews, on-call work, or design critique.
-
-Use this example when Slack is the intake surface and your durable procedures
-already live as repository skills.
-
-[Browse the current playbook-router source.](../../examples/benny/)
-
-## Combine two Slack transports with repo skills
-
-The playbook router uniquely combines three decisions:
-
-- Two Slack transports serve different engagement modes.
-- `local.cwd` keeps session workspaces inside the monorepo.
-- Instructions route work to inherited repository playbooks
-  instead of authored `agent/skills/`.
-
-The result is a thin agent project over a mature procedure library.
-
-## Follow an issue report
-
-1. A teammate creates a top-level post in the allowlisted issue channel.
-2. The dedicated Socket Mode channel accepts the allowlisted channel.
-3. A 15-second debounce lets edits settle. Deleting the post during that
-   window cancels the dispatch.
-4. The Agent SDK creates a thread-scoped session and sends the report to the
-   playbook router.
-5. The instructions select the matching triage playbook.
-6. The harness finds the repository root, opens the inherited playbook, and
-   follows its procedure.
-7. The agent posts only in the source thread and reports the evidence it
-   gathered.
-
-Mentions and direct messages follow the same agent instructions. They don't
-need the watched-channel path.
-
-## Map the playbook router files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](../../examples/benny/agent/agent.ts) | Names the agent, selects its model, and keeps the harness under `.agent-serve/harness`. |
-| [`agent/instructions.md`](../../examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
-| [`agent/channels/slack.ts`](../../examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
-| [`agent/channels/slack-app.ts`](../../examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
-| [`agent/storage.ts`](../../examples/benny/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](../../examples/benny/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/smoke.eval.ts`](../../examples/benny/evals/smoke.eval.ts) | Checks the agent identity and expected triage route. |
-
-The playbook router authors no tools, MCP connections, subagents, schedules, hooks, A/B
-experiments, or sandbox seeds.
-
-## See why `local.cwd` matters
-
-The Agent SDK normally keeps an ephemeral `run` or `eval` workspace outside a
-large monorepo. This prevents ancestor instruction and repository-rule files
-from leaking into an unrelated agent.
-
-The playbook router needs the opposite. Its procedures live at the repository
-root, so
-`agent.ts` sets:
-
-```ts
-local: {
-  cwd: ".agent-serve/harness",
-}
-```
-
-Each harness workspace lands under
-`examples/benny/.agent-serve/harness/<sessionId>`. Walking up the directory
-tree reaches the host repository and its inherited playbook directory.
-
-Those playbooks are inherited context. `agent-sdk info` reports zero authored
-skills for the agent. Copying this project into another repository removes
-its main procedures unless you copy or replace the skill library too.
-
-## Connect both Slack paths
-
-The account-linked path needs an agent-runtime login and a connected Slack
-account:
-
-```bash
-agent-sdk login
-agent-sdk whoami
-```
-
-It routes explicit mentions without a dedicated Slack token on the host.
-
-For the watched-channel path, configure a dedicated Socket Mode app with:
-
-- subscribe to `message.channels` and `message.groups`,
-- have an App-Level Token with `connections:write`, and
-- be a member of the watched channel.
-
-Run `agent-sdk slack create --dir examples/benny --channel-posts` for a
-dedicated Socket Mode app, then `agent-sdk slack doctor`.
-
-Missing dedicated-app tokens leave that channel idle. They don't stop the
-account-linked channel.
-
-## Validate and start the server
-
-```bash
-agent-sdk validate --dir examples/benny
-agent-sdk info --dir examples/benny --json
-agent-sdk dev examples/benny
-```
-
-The info output should show two Slack channels and no authored skill. That
-combination confirms the example is using inherited playbooks.
-
-## Exercise each engagement mode
-
-Test the explicit account-linked path by asking:
-
-> Which playbook would you use to triage a product UI bug?
-
-Test the dedicated app:
-
-1. Create a top-level post in the allowlisted issue channel.
-2. Don't mention the bot.
-3. Wait for the debounce window.
-4. Confirm the agent replies in the post's thread.
-
-Thread replies don't trigger the proactive watch. Mentions still use Slack's
-normal mention path. Bot-authored posts are ignored to prevent loops.
-
-The channel uses the default handler after filtering. It doesn't apply a
-second code-level classifier, so every accepted top-level post spends a model
-turn and reaches the prompt.
-
-## Inspect thread continuity
-
-The Agent SDK keys Slack sessions by channel and thread timestamp. A follow-up in
-the same thread resumes the conversation and workspace. A new top-level issue
-gets a new session.
-
-This lets a playbook gather evidence over several turns without mixing two
-reports. The playground shows both the account-linked and dedicated-app
-sessions while the dev server runs.
-
-## Run the smoke eval
-
-```bash
-agent-sdk eval --dir examples/benny --list
-agent-sdk eval --dir examples/benny smoke --json
-```
-
-The case asks for the agent identity and the playbook used for issue triage.
-It checks the configured identity and route label.
-
-This is a lexical smoke test. It doesn't prove Slack delivery, skill
-selection, skill loading, procedure execution, or thread-only behavior. Add
-fixture-backed evals around the playbooks when you reuse this design.
-
-## Build a playbook-routed teammate
-
-Use this structure when your organization already has tested skills:
-
-1. Put the playbooks under a stable repository path.
-2. Set `local.cwd` so harness workspaces can inherit that path.
-3. Write a short routing table in `instructions.md`.
-4. Use account-linked Slack for explicit requests.
-5. Add a dedicated app only for allowlisted proactive intake.
-6. Keep the channel allowlist narrow and debounce edited posts.
-7. Add an eval for every important request-to-playbook route.
-
-If the procedures should ship with the agent, put them under
-`agent/skills/` instead. Authored skills appear in the manifest and travel
-with the project.
-
-## Where to go next
-
-- [Slack](../guides/slack.md)
-- [Agent config](../reference/agent-config.md)
-- [Skills](../reference/skills.md)
-- [Sessions and streaming](../reference/sessions.md)
-- [Evals](../evals.md)

package/docs/example-agents/bugbot.md

@@ -1,234 +0,0 @@
----
-title: "Review prepared pull-request evidence"
-description: "Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval."
----
-
-# Review prepared pull-request evidence
-
-This GitHub-read-only reviewer uses host code to fetch the PR
-with `gh` and `git`, builds a trimmed `pr/` evidence tree, then hands that tree
-to the model. The model reads the diff, loads a review skill, and returns at
-most three high-confidence findings.
-
-Use this example when the host should control evidence collection and the
-model shouldn't browse or mutate the source repository.
-
-[Browse the current reviewer source.](../../examples/bugbot/)
-
-## Separate evidence preparation from review
-
-The reviewer separates preparation from judgment:
-
-- Host code owns GitHub and Git access.
-- A server tool turns untrusted PR input into bounded workspace files.
-- A custom channel seeds those files before the model starts.
-- An on-demand skill defines the review procedure and output contract.
-- The model returns chat text. No path posts a GitHub review.
-
-This architecture gives the model a purpose-built evidence package instead of
-a checkout.
-
-## Follow a review
-
-The custom HTTP path runs this sequence:
-
-1. `POST /v1/channels/review/` receives a PR reference.
-2. The handler calls `prepare_pr` without a model turn.
-3. Host code reads PR metadata and the unified diff.
-4. It reuses a matching checkout, force-fetching the PR ref there when the
-   commit is missing. Without a matching checkout, it uses a temporary bare
-   cache.
-5. It creates `pr/MANIFEST.md`, `pr/meta.json`, `pr/diff.patch`, and selected
-   small files and rules.
-6. `send({ workspaceFiles })` creates the model session with that evidence.
-7. The model reads the manifest and diff, then loads `pr-review`.
-8. The channel returns session and playground URLs while the review streams.
-
-If a normal chat starts without evidence, the model can call `prepare_pr`
-mid-turn. That form writes the same files into the active session workspace.
-
-## Map the evidence-review files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](../../examples/bugbot/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](../../examples/bugbot/agent/instructions.md) | Requires diff-first review and confines model work to `pr/`. |
-| [`agent/tools/prepare_pr.ts`](../../examples/bugbot/agent/tools/prepare_pr.ts) | Exposes host preparation as a typed server tool. |
-| [`agent/lib/prepare-pr.ts`](../../examples/bugbot/agent/lib/prepare-pr.ts) | Parses PR references, runs `gh` and `git`, and builds the evidence map. |
-| [`agent/channels/review.ts`](../../examples/bugbot/agent/channels/review.ts) | Provides the loopback-only prepare-and-send HTTP route. |
-| [`agent/channels/slack.ts`](../../examples/bugbot/agent/channels/slack.ts) | Extracts PR references and prepares evidence for mentions and direct messages. |
-| [`agent/skills/pr-review.md`](../../examples/bugbot/agent/skills/pr-review.md) | Sets finding limits, severities, and the machine-readable review format. |
-| [`agent/lib/log.ts`](../../examples/bugbot/agent/lib/log.ts) | Writes timing logs for the host tools to stderr. |
-| [`agent/storage.ts`](../../examples/bugbot/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](../../examples/bugbot/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/review/smoke.eval.ts`](../../examples/bugbot/evals/review/smoke.eval.ts) | Seeds fake evidence and checks the review path without GitHub. |
-
-There is no authored GitHub channel, MCP connection, subagent, schedule,
-hook, A/B experiment, approval, or custom storage.
-
-## Prepare the host
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns and account-linked Slack.
-- `gh` and `git` on `PATH`.
-- `gh` access to the target PR.
-- Network access to GitHub and a writable temporary directory.
-
-The preparer can prefer a configured local checkout. Its `origin` must match
-the target repository. Otherwise the reviewer uses its bare cache. It never
-checks out the PR into the serve host's working tree.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/bugbot
-agent-sdk info --dir examples/bugbot --json
-```
-
-The manifest should show one server tool, one skill, and two authored
-channels.
-
-## Inspect evidence without a model turn
-
-Call the preparation tool directly:
-
-```bash
-agent-sdk call prepare_pr \
-  --dir examples/bugbot \
-  --input '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-Direct tool calls use a scratch workspace removed after the call.
-`prepare_pr` detects this path and returns the complete file map in its
-result. In a model session, it writes the files and returns a smaller summary.
-
-The evidence builder applies explicit limits:
-
-| Evidence | Limit |
-| --- | --- |
-| Post-change file | 12,000 characters |
-| One rule file | 8,000 characters |
-| Combined rules | 12,000 characters |
-| PR body in metadata | 2,000 characters |
-
-Large files remain visible in `diff.patch`. The manifest records which full
-files or rules were omitted.
-
-The per-file limits aren't an aggregate context cap. Every changed file below
-12,000 characters can be included. The diff command has a 12 MiB output
-buffer; a larger diff fails preparation instead of being truncated.
-
-## Run the HTTP review path
-
-Start the server:
-
-```bash
-agent-sdk dev examples/bugbot
-```
-
-From another terminal:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-The route returns `status: "started"`, a continuation token, and session and
-playground URLs. Open the session URL to watch the model read the evidence and
-produce findings.
-
-The channel declares `localDevStrict()`. Direct loopback callers can use it.
-Proxy-forwarding headers and non-loopback hosts are rejected.
-
-Send a follow-up by passing the returned key:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"owner/repo#123","key":"<continuation-token>"}'
-```
-
-The follow-up resumes the session without fetching a new evidence tree.
-
-## Run the Slack path
-
-The account-linked Slack channel handles review-bot mentions and direct
-messages:
-
-> Review https://github.com/owner/repo/pull/123
-
-Slack handlers don't receive the channel `callTool` helper. This example calls
-the shared `preparePrReview` host function, then returns `workspaceFiles` in
-the Slack message preparation result. The model sees the same evidence and
-prompt as the HTTP path.
-
-If a message contains no PR reference, the handler asks for one. Thread
-follow-ups keep the same session.
-
-## See how the skill constrains review
-
-`pr-review.md` tells the model to:
-
-- read the manifest and unified diff first,
-- open at most one supporting file or rules file when a hunk is ambiguous,
-- avoid shell, network, `gh`, and `git`,
-- report no more than three findings,
-- keep each description under 120 words, and
-- emit the machine-readable review contract.
-
-The root instructions set the evidence boundary. The skill holds the reusable
-review procedure. Keeping those roles separate lets another agent reuse the
-same skill with different intake channels.
-
-## Run the fixture-backed eval
-
-```bash
-agent-sdk eval --dir examples/bugbot --list
-agent-sdk eval --dir examples/bugbot review/smoke --json
-```
-
-The eval constructs a `PreparedPrReview`, seeds its file map through
-`workspaceFiles`, and checks for at least one read call with no shell call. It
-doesn't assert which evidence file was read or whether the skill loaded. It
-accepts either a formatted review or a clean result.
-
-This case tests review behavior without GitHub credentials or network data.
-Add fixtures with reachable bugs when you need stricter location and severity
-checks.
-
-## Keep the side-effect boundary clear
-
-The reviewer makes no remote GitHub writes. It doesn't author a GitHub channel and
-doesn't call a review API. Host preparation does write session evidence and
-force-update `refs/pull/<N>/head` in either its bare cache or a matching local
-checkout when the commit is missing. Every result ends with a note saying no
-GitHub review was posted.
-
-If you add publishing later, keep it in a separate tool. This preserves a
-read-only preparation and review path safe to run in evals.
-
-## Reuse the evidence handoff
-
-Use host-prepared workspaces when:
-
-- external APIs should stay off the model's tool surface,
-- context needs hard size limits,
-- the model should inspect a snapshot instead of a live checkout, or
-- several channels need the same preparation.
-
-Return `workspaceFiles` from direct host preparation, write into
-`ctx.workspaceDir` for mid-turn recovery, and encode the reading order in both
-the manifest and a skill.
-
-## Where to go next
-
-- [Webhooks and custom channels](../guides/webhooks.md)
-- [Tools](../reference/tools.md)
-- [Skills](../reference/skills.md)
-- [Slack](../guides/slack.md)
-- [Evals](../evals.md)