/gaia-deploy

user-facing
Category:
Deployment
Lifecycle phase:
5 -- Deployment
Arguments:
--env <env> --version <ver> [--skip-smoke] [--story-key <key>]

What it does

/gaia-deploy orchestrates a five-phase deployment pipeline: pre-deploy gate, deploy, health-check, post-deploy smoke tests, and final verdict. It uses your configured deploy adapter to execute the actual deployment and runs smoke suites against the deployed environment. The pipeline is sequential and transparent -- each phase reports its status, and a failure at any phase halts subsequent phases.

When to use it

  • You have a version ready to deploy and all reviews have passed.
  • You want to deploy to a specific environment (staging, production) with automated verification.

Prerequisites

  • All reviews must pass. The pre-deploy gate checks the composite review verdict. If any review has not passed, the deployment is blocked.
  • A deploy adapter must be configured in your project configuration under deployment.adapter.
  • Environment credentials must be available as environment variables (never inline values).

Orchestration mode

When /gaia-deploy starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:


────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-deploy skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-deploy --env staging --version 1.3.0

What it does step by step

  1. Pre-deploy gate Checks the composite review verdict. Deployment is blocked unless all reviews show APPROVE.
  2. Deploy Invokes the configured deploy adapter to deploy the specified version to the target environment. No automatic retry on failure.
  3. Health-check Polls the health endpoint of the deployed service until it returns a successful response, or times out.
  4. Post-deploy smoke Runs configured smoke test suites (e2e, performance, security, accessibility) against the deployed environment.
  5. Final verdict Aggregates all phase results into PASSED or FAILED. Writes a deployment report to the evidence directory.

Inputs

InputSourceDescription
--envCommand argument (required)Target environment (e.g., staging, production).
--versionCommand argument (required)Version tag or artifact identifier to deploy.
--skip-smokeCommand argument (optional)Skip the post-deploy smoke phase.
--story-keyCommand argument (optional)Story key for Review Gate context.

Outputs

OutputLocationDescription
Deployment reportevidence/deployment-report.jsonStructured report with environment, version, timestamp, and per-phase verdicts.
Evidence filesevidence/deploy/ and evidence/smoke/Stdout, stderr, and health-check results from each phase.

Example session

> /gaia-deploy --env staging --version 1.3.0

Phase 1: Pre-deploy gate... APPROVE
Phase 2: Deploy via script-deploy adapter... OK
Phase 3: Health-check... OK (3 attempts, 4.2s)
Phase 4: Post-deploy smoke...
  e2e: APPROVE
  perf: APPROVE
Phase 5: Final verdict... PASSED

Deployment report written to evidence/deployment-report.json

What to run next

Troubleshooting

Pre-deploy gate BLOCKED

One or more reviews have not passed. Run the failing reviews or check /gaia-check-review-gate.

Deploy adapter BLOCKED

The configured deploy adapter is not available. Install the required tool or check your deployment.adapter setting.

Health-check timeout

The deployed service did not respond within the timeout. Check that the service is running and network routing is correct.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

  • echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
  • .gaia/config/project-config.yaml contains: 
    orchestration:
  mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.