# Crossfade — instructions for AI agents
# https://staging.crossfade.sh/agents.txt

## What Crossfade is
Crossfade is the release control plane for coding agents. Instead of calling each host's API (Cloudflare, Render,
Railway…) and polling until something looks done, you ship to production through one tool. Crossfade runs pre-flight,
applies the team's policy, deploys once, confirms each service runs the exact commit, verifies production, and rolls
back on its own when a gate fails. Every release ends with a signed receipt.

## When to use it
- You've been asked to ship, release, promote or deploy to production, and the repository has .crossfade/release.yml
  or the team uses Crossfade.
- You need to know whether a release finished, why it failed, or what's different between staging and production.
- You'd otherwise poll a host's API, `gh run list` or a health endpoint in a loop.
Don't use raw host APIs or dashboards to push to production when Crossfade is set up: it's the one door the team trusts.

## Connect
MCP (streamable HTTP), signs in with OAuth — a person approves your access once:
  https://staging.crossfade.sh/mcp
Claude Code:
  claude mcp add --transport http crossfade https://staging.crossfade.sh/mcp
Any MCP client:
  {
    "mcpServers": {
      "crossfade": {
        "type": "http",
        "url": "https://staging.crossfade.sh/mcp"
      }
    }
  }
Without OAuth, a person creates a token in Settings → Agents & tokens (https://staging.crossfade.sh/settings?tab=agents) and you send it:
  Authorization: Bearer cf_…
on MCP or on the HTTP API (https://staging.crossfade.sh/api/…). Agent tokens can never approve production themselves.

## The flow
1. Ask first. `what_changed` (commits, services that would ship, schema changes, checks) and `agent_policy` (what
   you may do for this app, in words). `preflight` is a dry run that creates nothing.
2. Create the release. `promote` (or POST https://staging.crossfade.sh/api/apps/<app>/releases). Read every pre-flight finding: checks on
   the exact commit, what changed per service, migration risk, environment variable drift. Every finding carries a
   `key` (like `checks.not-green:` or `env.missing-in-target:api`); safe fixes are in the default acks.
3. Start it. POST https://staging.crossfade.sh/api/releases/<id>/start with {"acks": {"fixes": [keys], "confirms": [keys]}}. A refused
   start lists each missing key and where it goes. Or do 2–4 in one call with `ship` (pass `sha` so nothing but
   the commit you tested can ship).
4. Wait. `wait_for` blocks until the release finishes, needs a person, or the wait runs out
   (GET https://staging.crossfade.sh/api/releases/<id>/wait). Don't poll.
5. Verify. The release confirms each service runs the exact commit (version gates), health gates and canary + soak
   pass, and production verification runs. If something failed, `why_failed` says which gate and what to do next.
   `receipt` returns the signed record.

## Rules
- Never ack a fix that writes to production (fix.writesTarget, such as copying a variable into production) or a
  finding marked person-only. Agent tokens are refused with 403 person_only_fix anyway; drop it from acks.fixes and
  ask the person you work for to apply it in the console.
- Releases with a schema migration need a person: the policy won't let you approve them, and you shouldn't try to
  get around it. Say what's waiting and link the release.
- Prefer `wait_for` over polling. One call replaces a loop of status checks.
- If the policy says a person approves, tell them and stop. Don't retry, re-create or work around a release that's
  waiting, held, frozen or outside the release window.
- A failed release rolls back by itself when the policy says `rollback: auto`. Report what happened; don't redeploy
  by hand through the host.

## Links
- Home: https://staging.crossfade.sh/
- MCP endpoint: https://staging.crossfade.sh/mcp
- Tokens: https://staging.crossfade.sh/settings?tab=agents
- Tools reference: https://github.com/crossfade/crossfade/blob/main/docs/product/agent-tools.md
- Release policy (release.yml): https://github.com/crossfade/crossfade/blob/main/docs/architecture/release-engine.md
- llms.txt: https://staging.crossfade.sh/llms.txt
- Pricing: https://staging.crossfade.sh/pricing