/gaia-readiness-check

What it does

/gaia-readiness-check validates that all planning artifacts are complete, consistent, and free of cross-artifact contradictions before implementation begins. It enforces two mandatory gates (traceability matrix and CI setup must exist), checks completeness of every artifact, validates cross-references, and produces a PASS/FAIL/CONDITIONAL PASS readiness report.

When to use it

• After creating all planning artifacts (PRD, architecture, UX design, test plan, epics, traceability matrix, CI setup) and before starting your first sprint.

Prerequisites

• Traceability matrix must exist at .gaia/artifacts/test-artifacts/traceability-matrix.md. Run /gaia-trace to generate it.
• CI setup must exist at .gaia/artifacts/test-artifacts/ci-setup.md. Run /gaia-config-ci to generate it.
• All other planning artifacts (PRD, architecture, epics, test plan) should exist for a comprehensive check.

Orchestration mode

When /gaia-readiness-check 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-readiness-check 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-readiness-check

What it does step by step

1. Load all artifacts Indexes up to nine planning and testing artifacts. Notes any that are missing.
2. Mandatory gates Checks that traceability-matrix.md and ci-setup.md exist. If either is missing, the check halts immediately.
3. Completeness check Verifies each document has all required sections.
4. Consistency check Validates that stories trace to PRD requirements, architecture components map to requirements, and test coverage is adequate.
5. Cross-artifact contradiction check Detects conflicts between artifacts (for example, a requirement in the PRD with no matching story, or an architecture component with no requirement).
6. Architecture assessment Evaluates architecture maturity and risk areas.
7. Operational readiness Evaluates CI/CD pipeline, deployment strategy, and infrastructure readiness.
8. Generate report Writes the readiness report with PASS, FAIL, or CONDITIONAL PASS verdict.

Inputs

This command takes no arguments. All inputs are discovered automatically from the project file layout.

Outputs

Readiness-report frontmatter contract

The readiness-report.md finalize step runs several script-verifiable checks against the file's YAML frontmatter plus its body. A hand-authored report that omits any of these fields fails the checks even when the prose verdict is correct. The required shape:

---
status: PASS                  # one of PASS | FAIL | CONDITIONAL
checks_passed: 47             # aggregate count of checks that passed
critical_blockers: 0          # count of blocking findings; 0 on PASS
contradictions_found: 0       # count of cross-artifact contradictions
priority_schedule_conflicts_count: 0
date: 2026-05-30
---

## Output Verification       # heading required (or equivalent prose section)
...

A further check re-asserts the status: verdict against the body. When /gaia-readiness-check generates the report itself (the canonical path) all the fields land automatically. Hand-authored READY reports must include them explicitly.

Example session

> /gaia-readiness-check

Loading artifacts (9 found, 0 missing)...

Mandatory gates:
  traceability-matrix.md: PASS
  ci-setup.md: PASS

Completeness: 9/9 artifacts have all required sections.
Consistency: 22/22 FRs traced to stories. 18/18 stories have AC.
Contradictions: 0 cross-artifact conflicts found.

Readiness verdict: PASS
  All artifacts complete, consistent, and gate-ready.

Report written to: .gaia/artifacts/planning-artifacts/readiness-report.md

What to run next

• /gaia-sprint-plan -- plan your first sprint.

Troubleshooting

"Gate failed: traceability-matrix.md not found"

Run /gaia-trace to generate the traceability matrix.

"Gate failed: ci-setup.md not found"

Run /gaia-config-ci to configure the CI pipeline.

CONDITIONAL PASS

Some non-critical checks failed but mandatory gates passed. Review the findings and address them before or during implementation.

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.

Related commands