setup-shepherd · git:20261117.92345a0 · 2026-11-17 · sha256 2cc13ca65dd9aaa3

setup-shepherd git:20261117.92345a0A

Immutable. This exact content never changes and is served at /api/v1/blob/2cc13ca65dd9aaa3.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_t3gsgyu2ikmk676o/2cc13ca65dd9aaa3b133ff636635a85acfca63055b6a3488f54540fc7a842a3e.json

Then /plugin install setup-shepherd@markdownregistry-t3gsgyu2ikmk676o in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: setup-shepherd
description: Configure shepherd and prepare its Cursor automation. Use when installing shepherd or changing its repository, environment, model, budget, publication or schedule settings.
disable-model-invocation: true
---

# Set up shepherd

shepherd is a dormant automation pack in the AKLR repository. This file and `optimize-and-deliver-kernels` are not slash skills.

The human enters setup by pointing an agent at this file, in the checkout that will run rounds.

shepherd needs one configuration file, one state directory and one live Cursor automation.

Do not create or update an automation until the user explicitly asks. Setup starts no paid campaign. Never put a secret in plugin files, prompts or committed configuration.

## 1. Check the checkout

Do this before asking for configuration.

The round checkout is the AKLR checkout on the round host, on the base branch. It already holds this pack. Never copy pack files into it.

Verify that it contains this file, `optimize-and-deliver-kernels` with its `references/` and `scripts/`, and the templates. If you were sent here from another copy of the pack and it is newer (`git log -1 -- harness/automations/shepherd`), stop and ask the user to update the checkout.

The automation runs each round itself and needs no plugin. Do not edit `.cursor/settings.json`.

Rounds read the shared skills by path from the checkout, never from an installed plugin or a discovered slash skill, whose cached revision can lag the pack. Verify that the checkout holds `harness/skills/<name>/SKILL.md` for:

- `forge-loop-campaign`
- `remote-gpu`
- `aklr-read-validation`
- `aklr-open-pr`
- `report-progress`
- `aklr-kb`

If any is missing, stop and explain the failure. Do not add `harness/automations/shepherd/skills/` to a plugin manifest.

Tell the user that the pack must be committed on the base branch before the automation is enabled. Do not commit it unless the user asks.

## 2. Adapt the configuration

Copy `../../templates/configuration.example.yaml` to `.shepherd/configuration.yaml` in the repository root. Git ignores it. If it exists, keep its values. Do not edit the example.

Write paths with environment variables such as `$USER`. No host names, usernames or personal absolute paths, even locally. Secrets stay in the credential store.

The configuration is not committed. The live prompt names its path and never paraphrases its values, so the automation must run in the checkout that holds it (step 4).

## 3. Fill the required choices

Ask for or confirm, in one pass:

- Repository and base branch. Infer them from the checkout.
- Mode: `run`, `observe` or `drain`.
- State directory, cluster, image digest and runtime revision. Offer found values: the image is `AKLR_CI_IMAGE` in `.github/workflows/ci.yaml`, resolved to its digest. The runtime is the Hyperloom `AKLR` branch commit (KernelForge) plus the flydsl version `harness/scripts/forge_task/README.md` pins.
- `execution.round_hours`: the round's lease, no longer than the automation's measured run limit (step 4).
- Strategies (`manual` paths, `kernel-less`), `batch_size`, `allowed_ops`, `backends`, `max_parallel_campaigns`, `max_open_prs`, `execution.pool_hours`, `cooldown_hours`.
- Campaign model, reasoning effort, loop hours, node hours, model USD, `max_auto_resumes`, and `model_usd_per_hour`: the highest hourly spend of the model with KernelForge, from provider billing.
- Cumulative budget, its recorded authorization, and the provider's hard limit: the spend cap on the API key or gateway the campaign calls (`claude auth status`, `ANTHROPIC_BASE_URL`). If none exists, the owner must set one.
- Publication: draft PRs, PR comments, `ci:gpu` label, branch prefix, and the issue that is told when a round needs the owner (`attention_issue`; its subscribers are notified by GitHub).
- Model slug and schedule of the Cursor automation, 15 minutes by default. That model runs every round, so pick a strong one.

Use only model slugs the user's Cursor model picker shows. Do not guess a slug or carry over a private default.

Resolve the campaign model to an identifier KernelForge's provider supports. Check the reasoning effort against the pinned KernelForge source (`--agent-reasoning-effort`). Do not guess a model, invent a flag or drop the effort.

Node hours cover setup, finalize, stress and validation as well as the loop. The model budget covers every inner agent call. The outer automation and GPU CI need their own authorization. Never estimate hard caps from logs.

Do not guess any paid-run choice. A missing one blocks the actions that need it, not read-only inspection. With `mode: run`, list each value still `null` as `prepared (blocked: ...)`, never as ready.

## 4. Check the host

Run these checks where every scheduled round will run, not only in this session.

The automation needs:

- A self-hosted Cursor worker, not a cloud agent. A cloud agent has no persistent state directory, no `/proc` of earlier rounds and no cluster access.
- A My Machines or repo-backed pool worker in the checkout that holds `.shepherd/configuration.yaml`. An any-repo pool worker with `--clone-git-repos` clones a fresh checkout without it.
- A measured run limit. Cursor does not document one, so measure it on this worker with a harmless long command, and set `execution.round_hours` at or below it: a round the runner cuts off is then taken over as soon as its lease expires.
- No GitHub or other integration. The round uses the host's own credentials.

The round needs:

- The host's own GitHub credentials (`gh auth status`): read access to main, PRs, CI and reviews; with publication on, branch push and draft PR creation. The `ci:gpu` label is a separate authority.
- `remote-gpu` reading the configured cluster, and `forge_task` and KernelForge help commands resolving in the pinned runtime. No node is needed for this.

The host needs:

- One host and one identity for the worker, ledger and GitHub credentials.
- A state directory on local Linux disk with working `flock` and atomic rename. Not temporary storage, a fresh checkout, a copy, or an unverified network filesystem.
- PyYAML for the system `python3` (the state helper reads the configuration).

Probe worker isolation on an allocated node. Start a container with the worker's mounts (`remote-gpu exec --image <image> --mount <probe>/worker --mount <probe>/secrets:ro`). Record its `docker inspect` mounts, that `gh auth status` fails, that no token-like variable is set, and that the validate directory and the cluster `$HOME` are not visible. The cluster `$HOME` holds no GitHub credentials. Image and tool versions are pinned.

Do not use undocumented integration endpoints.

## 5. Initialize state

Read [state.md](../optimize-and-deliver-kernels/references/state.md). Initialize a new state directory once with the helper; it creates missing private parents.

Setup cannot `save`; only a running round can. The configuration keeps the repository, authorization and caps. An existing directory, or one missing after use, needs investigation, not a new `init`.

Record the passing checks of step 4 and the budget authorization in `readiness.md` in the state directory. If a check has not run, leave paid mode off.

## 6. Prepare the live automation

The user chooses where and how the automation is created or updated; the pack does not depend on it. Finish configuration, host and state validation, then hand over these fields:

- Name `shepherd`, and a description.
- Prompt: [`automation-prompt.example.md`](../../templates/automation-prompt.example.md), as is or adapted. It must point at the committed `optimize-and-deliver-kernels` skill by its repository-relative path and at `.shepherd/configuration.yaml`. It keeps the template's two `begin` commands, so a skipped trigger reads nothing more, and otherwise never copies the skill's contents, paraphrases configuration values or uses a plugin cache path.
- Trigger: only the configured schedule (every 15 minutes is cron `*/15 * * * *`). No repository-event triggers.
- The self-hosted worker checked in step 4, the configured repository and base branch.
- No integrations.
- The automation model the user chose in step 3.

For an existing automation, update these fields in place. Do not create a replacement or duplicate. When moving from another scheduler, disable the old trigger first, and keep the state directory and budgets.

Never call an automation backend service directly, and never build a link that carries draft fields.

Record the automation's name, model and schedule in `readiness.md`. If the automation cannot be configured from here, hand over the prompt intent, configuration path, readiness results and remaining settings, and say it is not saved.

Enable the automation only with `mode: observe`. Keep it there until step 7 passes. The helper refuses an observe round's saves (the first `begin` migrates an older ledger), so the trigger tests can run on the live automation.

## 7. Test before paid operation

Confirm that the pack is committed on the automation's branch and that the live prompt points at the committed `optimize-and-deliver-kernels` skill. If not, stop and tell the user the automation cannot be enabled yet.

Verify with `mode: observe`:

1. One round in this session (`begin --now`, the round, `end`) reads GitHub and existing runs, lists candidates, writes a report and changes nothing.
2. `python -m pytest harness/tests/shepherd` passes with `TMPDIR` on a directory only you and root own, such as `/tmp`. The helper refuses a temp root under another user's directory.
3. Through the automation's own trigger: two concurrent triggers start one round; a second round begins once the first ended; after stopping a running round in Cursor, the first trigger after its lease expires takes over with `recovered_from` set.

Then switch to `mode: run` on probation, within the owner's authorization:

- `budget.total_*`: one campaign's and one pool's bounds, twice that if the owner allows a retry.
- `max_parallel_campaigns: 1`, `max_open_prs: 1`, `allow_draft_pr: true`.
- Reports say `enabled (probation)`.

Accept it after one real campaign reaches confirmed cleanup and a draft PR, and a later automation-started round observes that PR. CPU tests or a prompt preview do not count. If the probation budget runs out first, report `blocked`. After acceptance the owner records a new authorization and raises the budget.

Report each state separately: prepared, saved, enabled (observe), runtime-verified, enabled (probation).