/setup

name: setup
description: 'Use when the user asks to set up the agent environment. Covers credentials, placeholders, tool access checks, a uv venv, a pack install, or a role-model mapping file. Not for unattended runs.'
disable-model-invocation: true

Setup

One concern: configure the agent environment. Four mechanisms reach it: credentials and placeholders, a uv-managed virtual environment, a pack install from an archive, and a role-to-model mapping file. Every mechanism requires explicit human confirmation; run one mechanism per invocation, and when the user names none, list the four and ask which to run.

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to set up or configure the agent environment from a fresh or existing clone: credentials, placeholders, the virtual environment, a third-party pack install from an archive, or a role-to-model mapping file. | | Authority | Human-gated: asks before each credential write, `.venv` creation, placeholder replacement in skill scripts, pack install, and role-model file write; every other write is reversible local, with version control as the rollback. | | Side effect | Creates or updates .env and token.json, creates a uv-managed `.venv`, replaces placeholders in skill scripts, installs a pack into a target directory behind hash verification, and writes one role-to-model mapping file. | | Done | The selected mechanism reaches its done state: a ready/not-ready checklist with one example prompt per configured integration, a present or created `.venv`, an installed pack with a saved applied manifest, or a written and re-read role-model file. |

Not for

• Automated or unattended runs; every mutation requires human approval.

Inputs

• Mechanism: which of the four to run. When absent, list the mechanisms and ask.
• Credentials (optional): desired integration names (e.g. `GITHUB_TOKEN`, `OPENAI_API_KEY`). If absent, the credentials mechanism lists all recognized integrations and asks which to configure.
• Virtual environment (optional): `.venv` path, defaulting to the project root.
• Pack install (required for that mechanism): source archive URL, target directory, expected file manifest mapping paths to expected SHA-256 hashes, and required transformations keyed by strict unique anchors.
• Role-model mapping (required for that mechanism): `role: model` pairs, an absolute rule file path, the caller-supplied available-models set, and optional prior file content for drift detection.

Mechanism selection

| User asks | Mechanism | |---|---| | set up credentials, configure an integration, replace placeholders, token, gather tool credentials into .env, verify repository or tool access | credentials and placeholders | | create or check the virtual environment, uv venv | virtual environment | | install a pack or template repository from an archive | pack install | | write role-to-model choices or a model mapping file | role-model mapping |

Credentials and placeholders

1. **Confirm scope.** If the user named no integration, list every known integration placeholder found in skill scripts and .env templates. Ask the user to select which to configure. **Done when:** the user selects integrations or declines.

2. **Identify targets.** For each selected integration, locate the corresponding placeholder in skill scripts (search for `{{VARIABLE_NAME}}` patterns or comments naming the integration) and identify which credential file it reads (`.env` or `token.json`). Do not write in this step. **Done when:** every selected integration has a placeholder located and its credential file identified.

3. **Detect current state.** Check whether a real value already exists in `.env` or `token.json` for each selected integration. Never overwrite an existing non-empty value: report the key name and that it was skipped, never the value. **Done when:** the current state of every selected integration is recorded.

4. **Make each credential file safe before creating or appending.** Check `.env` and every `token.json` that a selected integration uses. A path is safe when it is not tracked and it is ignored; do not use `git status` for either check, because an ignored path is omitted from that output. In a git work tree: stop when `git ls-files --error-unmatch -- <path>` succeeds (the file is tracked); when `git check-ignore -q -- <path>` fails, obtain confirmation and add the path to `.gitignore`, creating it when missing; create an empty file only when the path is safe. In a fresh directory with no git work tree: create a `.gitignore` excluding `.env` and `token.json`, then create each empty file when missing. **Done when:** every credential file is safe, or the unsafe state is reported and the mechanism stops.

5. **Ask for each missing value, with format validation.** Prompt the user to supply the credential; accept it only via direct user input in the conversation. Validate basic format: a non-empty string plus the named tool's convention (for example, a Slack bot token starts with `xoxb-`; a Postgres URL contains `://`). Discard a failing value and prompt again. **Done when:** every missing value is supplied and validated, or the user declines.

6. **Write credentials.** Append each validated credential as one `KEY=VALUE` line to `.env`, or write it to `token.json` as the integration requires. Write nothing else to the file. **Done when:** every validated value is written, or skipped with the reason.

7. **Verify repository, tool access, and prerequisites.** When a repository is supplied or detected: confirm the remote is reachable (`git ls-remote` or an authenticated HEAD request) and the token grants at least read access; report pass or fail without exposing token values. Run the named tool's prerequisite checks; stop on the first failure and name the tool and the failing check. Confirm `.env` parses (`dotenv` or equivalent) and report its keys. **Done when:** access and every prerequisite pass, or the first failure is reported.