/gaia-quick-dev

What it does

/gaia-quick-dev implements a quick spec end-to-end -- the fastest path from idea to code in GAIA. It loads a spec file produced by /gaia-quick-spec, auto-detects your project's technology stack, delegates implementation to a matching developer agent, runs tests, and validates the result against the spec's acceptance criteria.

When to use it

• You have a quick spec at .gaia/artifacts/implementation-artifacts/quick-spec-{name}.md and want to implement it.
• A prior session was interrupted -- the command detects the checkpoint and offers to resume.

Prerequisites

• A quick spec must exist. Run /gaia-quick-spec first.

Orchestration mode

When /gaia-quick-dev 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-quick-dev 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-quick-dev add-dark-mode-toggle

Pass the spec name (the same name used with /gaia-quick-spec).

What it does step by step

1. Load spec Reads the quick spec file. If not found, directs you to run /gaia-quick-spec first.
2. Resolve checkpoint Checks for an in-progress checkpoint. If found, offers Proceed, Start fresh, or Review options.
3. Delegate to developer Auto-detects the project stack (TypeScript, Python, Java, Go, Flutter, Angular, or mobile) and delegates implementation to the matching developer agent, applying TDD where practical.
4. Verify Runs the project's test suite and validates against the spec's acceptance criteria.
5. Complete Archives the checkpoint and reports the files touched.

Inputs

Outputs

Example session

> /gaia-quick-dev add-dark-mode-toggle

Loading spec: .gaia/artifacts/implementation-artifacts/quick-spec-add-dark-mode-toggle.md
No active checkpoint. Fresh run.

Auto-detected developer: typescript-dev based on package.json.

Implementing...
  Writing src/hooks/useTheme.ts...
  Writing src/components/DarkModeToggle.tsx...
  Updating src/styles/theme.css...
  Writing tests/components/DarkModeToggle.test.tsx...

Running tests: 4 new tests, 4 PASSING.
Acceptance criteria: 3/3 met.

Quick spec add-dark-mode-toggle implemented. Files touched: 4.
All tests passing. Checkpoint archived.

What to run next

• Commit and push your changes using your normal git workflow.
• /gaia-review-code -- optional code review before merging.

Troubleshooting

"Quick spec not found"

Run /gaia-quick-spec {name} first.

Stack auto-detection failed

The command asks you to select from the seven supported stacks (TypeScript, Angular, Flutter, Java, Python, mobile, Go).

Checkpoint has drifted files

Files were modified externally since the last session. Choose Proceed (accept risk), Start fresh, or Review the drift.

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