---
requiresProjectContext: true
---

# Playbook: Setup

You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
TEAM ROOT: {{team_root}}

Repository ID is injected as `{{ado_project}}` and `{{repo_name}}` template variables.
Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}

## Your Task

Setup task **{{item_id}}: {{item_name}}**
- Priority: {{item_priority}}
- Description: {{item_description}}

{{additional_context}}

{{references}}

{{acceptance_criteria}}

## What "setup" means

`setup` work items boot or configure local infrastructure inside a project
worktree. Canonical examples: bootstrap a dev stack (`bun install`, `npm
install`, write `.env.local`, seed local databases), launch a long-running
dev server via `meta.managed_spawn`, prime a sandbox/emulator. They mutate
state but **produce no pull request**.

If your assignment requires committing files to the tracked repo (real code
or doc changes), it's the wrong type — escalate so the dispatcher reclassifies
it as `implement` / `fix` / `docs` instead of forcing a PR-less merge.

## Working directory

You are running inside a real project worktree. Confirm the path before doing
anything filesystem-sensitive:

```bash
# PowerShell
echo $env:MINIONS_AGENT_CWD
pwd

# bash/zsh
echo "$MINIONS_AGENT_CWD"
pwd
```

`MINIONS_AGENT_CWD` is the engine-resolved worktree root and is the
authoritative path for cwd-sensitive commands. If it disagrees with `pwd`,
prefer `MINIONS_AGENT_CWD` and `cd` there before continuing.

## Project Scope

Primary repo: **{{repo_name}}** ({{ado_org}}/{{ado_project}}) at `{{project_path}}`

## No PR expected

This is the defining contract of `setup`:

- **Do NOT run `git push`.** No remote branch is needed.
- **Do NOT run `gh pr create`** (or any host-specific PR creation command).
- **Do NOT create a new branch** beyond the engine's pre-created worktree branch.
- The engine's PR-attachment contract is short-circuited for `type: "setup"`,
  so completing `done` with no PR is the correct outcome.

If you accidentally produce code changes that need review, stop, leave them
uncommitted, and report what happened in the completion report so the human
can re-dispatch as `implement` or `fix`.

## Managed spawn / keep-process hints

If the dispatcher set `meta.managed_spawn` or `meta.keep_processes` on this
work item, the engine auto-injects the corresponding contract block above
this playbook. Follow the contract block verbatim — it tells you exactly
which sidecar file to write (`agents/<id>/managed-spawn.json` or
`agents/<id>/keep-pids.json`), the schema, and the engine-side reap behavior.
Both injectors are orthogonal to work-item type, so they work the same here
as in `implement`.

## Health Check

Before starting work, run `git status` to confirm the worktree is clean.
If it's dirty or on an unexpected branch, report and stop.

## Working Style

Use subagents only for genuinely parallel, independent tasks. For sequential
work, single-file edits, searches, and file reads, work directly.

## Validation

Prove the setup actually worked before declaring success — the agent's
completion is the only signal the engine and user get that the infrastructure
is up:

- Use the project's documented commands (`CLAUDE.md`, README, `package.json`
  scripts) — don't invent ones.
- For long-running services, hit the documented health endpoint / health
  command before exiting (e.g. `curl http://localhost:<port>/health`).
- Capture the exact commands you ran in the completion report. Do not write
  "setup completed" without naming what ran.

Long installs and dev-stack boots may be quiet for several minutes. Let the
normal CLI command run naturally; do not add artificial heartbeat output.

## When to Stop

Your task is complete when the requested infrastructure is up, validated by
the project's own health command, and the completion report names the
commands you ran and the URLs / PIDs of anything left running. There is no
PR to wait for.

Do NOT remove the worktree — the engine handles cleanup automatically.
