# Build with an agent (/docs/agents)



Read the owner's brief and existing project instructions first. Inspect the package manager, `relay.json`, login, and hosting before selecting a workflow.

```mermaid
flowchart LR
    A["Read the brief"] --> B["Propose a direction"]
    B --> C{"Owner confirms?"}
    C -- "Not yet" --> B
    C -- "Yes" --> D["Connect and discover"]
    D --> E["Build from snippets"]
    E --> F["Verify in the app"]
    F --> G["Report evidence"]
```

> [!IMPORTANT] Keep authorization with the person
> Have the user approve browser login and complete participant email codes or OAuth consent. Integration keys are created by an administrator in Console and saved directly into server secrets. Keep keys and codes out of chat, source, and browser bundles.

## Work through the integration [#work-through-the-integration]

### 1. Confirm the direction before implementation [#1-confirm-the-direction-before-implementation]

For a new project or first Domino integration, use the Domino skill to research the brand and campaign context before building. Inspect the supplied website, assets, existing app, and brief. Extract the visual style and voice, then propose:

* **A brand direction** with a small visual sample.
* **A campaign brief** covering the goal, success measure, participants, actions, motivation, and journey.

Ask only about consequential gaps and offer recommendations. Separate facts from assumptions, and keep unconfirmed rewards, budgets, dates, and eligibility out of participant promises. Present the proposal and wait for the owner's confirmation before implementation.

Save the confirmed direction, sources, confirmation evidence, and open decisions in `CAMPAIGN.md` or the app's established brief document. Later sessions reuse those decisions; material changes reopen only the affected parts. This is an agent instruction, not a CLI enforcement mechanism.

For a project that already has work, such as published quests or staging builds, skip this discovery. Read the project's agent instructions, README, and `CAMPAIGN.md`, review its quests, releases, and builds, summarize what exists, and ask the owner what to change next. Treat the saved brief as confirmed unless the owner says otherwise.

### 2. Establish the connection [#2-establish-the-connection]

Use the project's installed CLI. Run `domino doctor --json`, then `domino doctor --remote --json` when remote access is needed. Outside a project, doctor reports setup health only. Its `agents` field lists the Domino skill loaders installed in the project, not which agent is running. Confirm the effective organization, project, and environment before publication.

| Starting point                               | Rule                                                          |
| -------------------------------------------- | ------------------------------------------------------------- |
| [New hosted app](/docs/reference/hosted)     | Check out the existing project rather than creating it again. |
| [Existing app](/docs/reference/existing-app) | Preserve its repository, framework, login, and hosting.       |

> [!TIP] Upgrade before you work around
> When SDK, docs, and server behavior disagree, read the [changelog](/docs/reference/changelog) and follow the [upgrade guidance](/docs/reference/troubleshooting#check-for-an-sdk-upgrade) before adding a workaround. Check for a newer release that addresses the failure, update the packages together, and retry the original action.

### 3. Discover supported behavior [#3-discover-supported-behavior]

```sh
domino capabilities --json
domino capabilities referrals --json
domino reference participant-api
domino reference troubleshooting
```

The [capability map](/docs/reference/capabilities) is generated from the same catalog bundled with the CLI. A capability's `reference` names a topic for `domino reference`; run `domino reference` without a topic to list every reference the installed CLI ships.

* **It is release guidance, not a live probe.** Command output includes `provenance` with the CLI version and `serverVerified: false`: this is release guidance, not a live server or project capability probe. Scope flags do not change that.
* **Unlisted means unknown.** Treat unlisted behavior and disagreements with the deployed API as unknown, and inspect the applicable contract before changing the architecture.
* **Check some features separately.** Check daily recurrence, social verification, and prize fulfillment separately from points and leaderboards.
* **It names the commands.** A capability's `cli` lists the `domino` commands that reach it, such as `points award` or `trackers ingest`. Operator reads and changes have typed `domino <noun> list|get|…` commands; use them instead of `domino api`. See [resource commands](/docs/reference/automation#resource-commands).
* **Quote project analytics.** To answer how a project is doing, run `domino analytics get --range 7d|30d|90d|all` and quote its numbers instead of computing your own. See [project analytics](/docs/reference/automation#project-analytics). To split or narrow a number, read one metric from the closed catalog with `domino analytics query --metric ID`; `domino analytics metrics` lists them. See [metric catalog](/docs/reference/automation#metric-catalog).
* **Measure the project's goals.** To choose metrics for what a project is for, or to build, check and explain a dashboard, read [measuring a project](/docs/reference/analytics) (`domino reference analytics`).
* **Read the referral reference first.** For invitations, qualification, and inviter bonuses, read it before choosing the authoring and participant APIs.
* **Check on-chain actions.** To reward what a member's linked wallet did on chain, an EVM contract event or a Solana transaction that called a program, read [on-chain actions](/docs/reference/onchain) (`domino reference onchain`).
* **Reward X posts only for approved creators.** X does not allow apps that reward users for posting. When asked to reward people for posting on X, gate each quest that pays for X posts with an `inGroup(group)` prerequisite on a group the operator manages. See [rewarding X posts](/docs/reference/trackers#rewarding-x-posts).

### 4. Find a quest snippet [#4-find-a-quest-snippet]

Before authoring a new quest, follow [the snippet workflow](/docs/reference/authoring#find-a-snippet). Fetch the [live catalog](https://snippets.domino.run/r/registry.json), inspect a matching recipe, then install and adapt its source. New catalog entries are available without updating the agent instructions.

Run the project-local `domino agents install` to register the Domino skill for Codex and Claude in an existing project. Distributed starters already include the loaders and project instruction pointers. The full skill and its references live in `node_modules/@domino-sdk/relay-cli/cli/skills/domino`, so guidance stays matched to the CLI version installed in that checkout. `domino reference authoring` prints the release-specific instructions in the terminal.

Install dependencies before reading the bundled skill. Keep project-specific rules in AGENTS.md. After a CLI upgrade, ask the agent to re-read the bundled skill; routine skill reinstallation is unnecessary. Existing conversations may still contain instructions read before the upgrade.

For older checkouts, run `domino agents install` once after upgrading the CLI. It migrates known copied guidance, preserves project instructions, and adds marked pointers in AGENTS.md and CLAUDE.md. Customized files are reported before any changes; follow the [migration procedure](/docs/reference/existing-app). Commit the loader and instruction changes for the rest of the team.

### 5. Finish with evidence [#5-finish-with-evidence]

Run the app's checks and exercise the requested action through the running app. Verify persisted progress, not only a build or doctor result. If participant sign-in is waiting for the user, report that verification as unfinished.

For a campaign, simulate it in the test environment with test members over several simulated days, then fix what breaks: follow [campaign testing](/docs/reference/campaign-testing), or run `domino reference campaign-testing`.

Return:

* The working preview URL.
* The action verified.
* Any remaining launch dependency.

Label simulated provider results explicitly. Live publication requires human review in Console.

### 6. Report tooling issues [#6-report-tooling-issues]

Report each distinct issue you encounter with Domino tooling, including issues you worked around. Use `domino feedback --reporter agent --title "Short summary" --body-file report.md --json` and follow the [feedback instructions](/docs/reference/troubleshooting#report-a-tooling-issue). Include the returned Linear issue link in your handoff. Humans can use the same command without `--reporter agent`.

Before every completed task's final handoff, also review difficulties that better SDK or CLI support could address, even if no command failed. Report unreported friction such as missing helpers, repetitive manual steps, confusing APIs, or workarounds. Describe the extra work and the concrete tooling improvement that would have helped. Submit only observed difficulties, without repeating earlier reports or sending a general task summary. If there were no such difficulties, skip the completion report.

## Unattended runs [#unattended-runs]

To run an agent with nobody present, such as in CI, a scheduled job, or a sandbox, set `DOMINO_AGENT_MODE=unattended` in its environment. Setting it is your consent for the agent to build from your brief without asking you anything; the agent can't turn it on itself. `domino doctor --json` and `domino whoami --json` report the mode as `agentMode`.

| The Domino skill normally                   | In an unattended run                                                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Interviews you and waits for you to confirm | Treats your brief as confirmed and never waits.                                                                    |
| Asks about consequential gaps               | Picks the most conservative reasonable option and lists it in `CAMPAIGN.md` under "Assumed in an unattended run".  |
| Sends you a sign-in code                    | Uses `RELAY_MANAGEMENT_TOKEN`. Browser login refuses with `UNATTENDED_LOGIN_UNAVAILABLE`.                          |
| Submits tooling feedback to Domino          | Saves it to `./domino-feedback.jsonl`, or `DOMINO_FEEDBACK_FILE`. `--submit` or `DOMINO_FEEDBACK=submit` sends it. |
| Hands over and asks about open decisions    | Ends with a written report and asks no questions.                                                                  |

Live publication still needs your review in Console.

A personal API key can't create projects, so create the project in Console first; an organization [automation key](/docs/agents/automation) with **Create projects** can. Then, in the project's Test environment, create an API key with the **Read** and **Publish** permissions under **Settings → API keys** and give it to the agent as `RELAY_MANAGEMENT_TOKEN`. Start the agent with a prompt like this:

```text
Build a Domino campaign from the brief below on a staging site. Nobody is available to answer questions. Run npx -y @domino-sdk/relay-cli@latest checkout PROJECT_ID, work in the directory it creates, and install dependencies with the command it prints. Then read and follow the Domino skill at node_modules/@domino-sdk/relay-cli/cli/skills/domino/SKILL.md, including its unattended runs section. Stage the result, and end with a report of what you built, the staging link, what you tested, and what you assumed.

Brief: <your campaign brief>
```

## Read only what the task needs [#read-only-what-the-task-needs]

- [Authoring](/docs/reference/authoring) — Definitions, settings, and publication.
- [Participant API](/docs/reference/participant-api) — Sign-in, controllers, and recovery.
- [Referrals](/docs/reference/referrals) — Supported data ownership and limits.
- [Campaign testing](/docs/reference/campaign-testing) — Simulate a campaign with test members, and what to watch for.
- [Analytics](/docs/reference/analytics) — Choose metrics from a project's goals, and build and check dashboards.
- [Troubleshooting](/docs/reference/troubleshooting) — Startup, staging, and access failures.
- [CLI](/docs/reference/cli) — Commands and flags generated from executable help.
- [Connect an AI assistant](/docs/agents/connect) — What an owner's assistant, such as Claude, ChatGPT, Claude Code, VS Code or Cursor, can read and try in test through Domino's MCP server.
- [Run an agent without signing in](/docs/agents/automation) — An organization automation key for CI and headless agents, test environment only.

| Source                                     | Contains                                           |
| ------------------------------------------ | -------------------------------------------------- |
| Every docs page                            | A Markdown copy.                                   |
| [/docs/llms.txt](/docs/llms.txt)           | An index of the site.                              |
| [/docs/llms-full.txt](/docs/llms-full.txt) | The complete public reference.                     |
| The CLI                                    | Release-specific guidance bundled for offline use. |

## Build achievements [#build-achievements]

Ask your agent to define badges with `defineBadge`, include their definitions in `relay.json`, and attach `badge(...)` to quest rewards. The CLI publishes the definitions and quest rewards together. Participant clients read the catalog and member awards; your app composes any tiers or levels. See [badge authoring](/docs/reference/authoring#badges).