/gaia-quick-spec

What it does

/gaia-quick-spec creates a lightweight implementation specification for small changes -- the quick-flow entry point. It skips the full lifecycle (PRD, architecture, epics) and produces a single markdown file with five fixed sections: summary, files to change, implementation steps, acceptance criteria, and risks.

When to use it

• The change is small (under a day, fewer than 5 files) and does not warrant a full story lifecycle.
• You need a quick spec that a developer can hand to /gaia-quick-dev.

For larger changes, use /gaia-create-prd to start the full lifecycle instead.

Prerequisites

None. This command works on any project at any stage.

Orchestration mode

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

The argument is a short name used in the output filename. If omitted, the command asks for one.

What it does step by step

1. Scope Asks two questions: "What small change or feature do you want to spec?" and "Which files are likely affected?"
2. Quick analysis Identifies affected files, dependencies, and estimates scope (files changed, complexity).
3. Escape hatch check If scope exceeds 5 files or 1 day, offers to escalate to the full lifecycle via /gaia-create-prd.
4. Generate quick spec Assembles the five-section implementation plan.
5. Write output Writes the spec to .gaia/artifacts/implementation-artifacts/quick-spec-{spec_name}.md.

Inputs

Outputs

Example session

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

What small change or feature do you want to spec?
> Add a dark mode toggle to the settings page.

Which files are likely affected?
> src/components/Settings.tsx, src/styles/theme.css, src/hooks/useTheme.ts

Quick analysis:
  3 files affected, estimated < half a day. Within quick-spec threshold.

Quick spec written to .gaia/artifacts/implementation-artifacts/quick-spec-add-dark-mode-toggle.md.
Run /gaia-quick-dev add-dark-mode-toggle to implement it.

What to run next

• /gaia-quick-dev -- implement the spec.

Troubleshooting

"This looks bigger than a quick spec"

The escape hatch fired because the change touches more than 5 files or exceeds 1 day. You can continue anyway (the risk is noted in the spec) or escalate to the full lifecycle.

Output file already exists

The command asks whether to overwrite, rename, or abort.

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