# Set up this agent for orun

You are a coding agent. Follow these instructions to connect yourself to
**Orunbase** — the hosted control plane — so that you can read and act on
the user's workspace through a typed tool plane instead of guessing at it
from the filesystem, and work its repositories the way they expect: with
`git`, `gh` and those tools. Nothing here needs a binary or a credential in
your session; the optional `orun` CLI is an appendix at the end.

**Read this whole file before you start.** If the tool you fetched it with
gave you a summary rather than the text, download it and read the file:

```sh
curl -fsSL https://orunbase.com/agent-setup/prompt.md -o /tmp/orun-setup.md
```

Work through the steps in order. Run the commands yourself where you are
allowed to; where a step needs the human, say exactly what you need, show
them the exact command, and wait. If a step is refused by your harness, do
the rest and say precisely which step is left and how the user finishes it
(the **Blocked?** table at the end).

---

## 0. Establish where you are

- Detect which client you are running inside — Claude Code, Codex, Cursor,
  VS Code, or another MCP client. Steps 1 and 2 use it. If you cannot tell,
  ask rather than writing config for the wrong one.
- If the repository has an `intent.yaml` at its root, it is an orun
  platform: `execution.state.workspace` names the workspace this repository
  reports to (note it; do not pick a different one), and its `work:`
  section names where the epics and task contracts live.
- If your session already carries Orunbase tools (`whoami`, `skills_list`,
  `catalog_search`, …) through an attached connector, step 1 is done.

## 1. Register the tool plane

The Orunbase MCP server is how you read the workspace and declare work:
the service catalog, runs and logs, audit, usage, config, and the work
plane (epics, milestones, tasks, skills). Register it **remotely** — no
binary, no credential in your session; a human authorises it once in the
browser:

1. The user opens the console at **Settings → MCP server** and copies the
   remote URL it prints.
2. Add it to your client:

**Claude Code**

```sh
claude mcp add --transport http orunbase <the URL from the console>
```

If your harness refuses that as a change to your own configuration, write
the project-scope file `.mcp.json` at the repository root instead (Claude
Code reads it) and show the user the diff:

```json
{ "mcpServers": { "orunbase": { "type": "http", "url": "<the URL from the console>" } } }
```

**Cursor** (`~/.cursor/mcp.json`) and **VS Code** (`.vscode/mcp.json`)
take the same shape under `mcpServers` / `servers`; **Codex**
(`~/.codex/config.toml`) takes `[mcp_servers.orunbase]` with `url`. Merge
into an existing file rather than overwriting it; most clients need a
restart to pick up a new server, and the first call opens the browser for
the user to authorise.

Then `whoami`. If it names an account that is **not a member of the
workspace** from step 0, stop and tell the user: a `404` from every
workspace-scoped tool later means exactly this, and only they can fix it
(grant the membership, or authorise the connector as the right account).

## 2. Install the Orunbase skills

The platform hosts the playbooks it expects you to follow — how to declare
an epic and a task, name a branch, write the PR's manifest, which MCP tool
answers which question — as **skills**: `SKILL.md` files, mirrored
anonymously at <https://orunbase.com/skills/index.json>. Copy them into the
directory your client discovers skills in:

| Client | user directory | inside one repository |
|---|---|---|
| Claude Code | `~/.claude/skills` | `.claude/skills` |
| Codex | `~/.codex/skills` | `.codex/skills` |
| Cursor | `~/.cursor/skills` | `.cursor/skills` |
| VS Code | `~/.copilot/skills` | `.github/skills` |

```sh
DEST=~/.claude/skills            # or the repository's directory when your harness refuses writes outside it (a sandboxed or cloud session)
curl -fsSL https://orunbase.com/skills/index.json -o /tmp/skills.json
for name in $(node -e 'for (const s of require("/tmp/skills.json").skills) console.log(s.name)'); do
  mkdir -p "$DEST/$name"
  curl -fsSL "https://orunbase.com/skills/$name/SKILL.md" -o "$DEST/$name/SKILL.md"
  for f in $(node -e 'for (const f of require("/tmp/skills.json").skills.find(s=>s.name===process.argv[1]).files) console.log(f)' "$name"); do
    mkdir -p "$DEST/$name/$(dirname "$f")"; curl -fsSL "https://orunbase.com/skills/$name/$f" -o "$DEST/$name/$f"
  done
done
```

Each file names the revision it is (`orun-rev`). The `orunbase` skill is
the entry point: its first step compares that revision with the live one
(`skill_get orunbase`) and follows the live body when they differ, so
re-running this step is the whole upgrade. With the `orun` binary,
`orun skills pull --client claude-code` (or `codex`, `cursor`, `vscode`;
`--project` for the repository's directory) reads the registry itself,
including anything the workspace published over the defaults — see the
appendix.

## 3. Learn the workspace before you touch it

Orient yourself with the tools rather than by reading files at random:

1. `whoami`, then the workspace from `intent.yaml` (step 0) — confirm it
   with the user only if the repository names none.
2. Pull the **service catalog** for it (`catalog_search`): the entities are
   derived from what actually shipped, so this is the map of record.
3. Read the **recent runs** (`runs_list`) and anything flagged as needing
   attention. If something is failing, say so before proposing new work.
4. Read `intent.yaml` and the `component.yaml` beside each unit you will
   touch. In an orun platform the intent files are the source of truth; the
   pipeline runs `orun plan` and `orun run` on merge, never a raw `pnpm`,
   `wrangler` or `terraform` deploy from a session.

## 4. Rules of engagement

The `orunbase` skill you installed in step 2 is the full statement; hold to
these for the rest of the session:

- **Work is declared in the repository.** An epic is
  `<epics>/<slug>/epic.yaml` with its docs; a task is a key under one of
  its milestones with `<tasks>/<KEY>.TaskContract.yaml`. The merge creates
  them in Orunbase; nothing is minted by hand.
- **One task, one branch, one PR.** Branch `orun/<KEY>-<slug>`, commit with
  `git commit --trailer "Orun-Task: <KEY>"`, end the PR body with the
  `orun:manifest` block (the `pr-provenance` skill has the three lines),
  open it with `gh pr create`, merge only when every check is green. The
  `orun/compliance` check refuses anything else on a repository linked in
  `required` mode.
- **Never invent state.** If a tool can answer the question, call it. A
  number you cannot trace back to a run, an entity, a task or an audit
  record does not go in your answer.
- **Ask before anything irreversible** — deleting resources, rotating
  credentials, force-pushing, converging production.
- **Credentials stay where they are.** You need none; the PR is your
  identity and CI holds its own. Do not print secret values, copy them
  between files, or commit them.

## 5. Report back

Finish with a short summary for the user:

- which client you registered the tool plane with and the file you changed
  (or that the session already had it), and the account `whoami` named;
- where you installed the skills and the `orun-rev` of `orunbase`;
- what the catalog and recent runs say about the workspace right now;
- anything you could not do, and the exact command the user runs to finish
  it.

## With `orun` (optional)

The open-source CLI is what CI runs. On a developer machine it adds
shortcuts — the lineage preflight before you push, the PR opened with its
manifest written for you, the landing that waits for the checks, a local
`orun plan` — and it can serve the same tool plane locally. The `orun-cli`
skill you installed covers all of it; the short version:

```sh
curl -fsSL https://orun.dev/install.sh | sh    # into ~/.local/bin; v2.66.0 or later
orun auth login --device                        # prints a pairing code and a URL — show both to the user and wait
orun auth status                                # its Orgs must include the workspace from step 0
orun skills pull --client claude-code           # the registry, with the workspace's own revisions
claude mcp add orun -- orun mcp serve           # the local stdio server, reusing this login
```

If your harness refuses to run the login or to show its output, ask the
user to run it in the same shell (Claude Code: `! orun auth login --device`).
On a headless runner the user mints an API key under **Settings → API
keys** and exports it as `ORUN_TOKEN`; GitHub Actions needs neither. Never
read, echo or copy the credential file, and never ask the user to paste a
credential into the chat.

## Blocked?

| Step | If your harness refuses it | The user finishes it with |
|---|---|---|
| 1 tool plane | `claude mcp add` refused → write `.mcp.json` in the repository | `claude mcp add --transport http orunbase <URL>` |
| 1 membership | nothing to work around — membership is a decision | grant the account access in the console, or authorise the connector as the right account |
| 2 skills | writes outside the repository refused → use the repository's skills directory | the `curl` loop above, or `orun skills pull --client <client>` |
| 3 orientation | a `404` is a membership problem (step 1), not a retry | — |
| appendix | the CLI is optional; say what it would have added | `orun auth login --device` (Claude Code: prefix with `!`) |

---

_These instructions live at <https://orunbase.com/agent-setup/prompt.md> and are
safe to re-fetch at any time — they carry no credentials and no workspace
state._