/gaia spec

/gaia spec produces an immutable SPEC artifact through a guided Socratic conversation. The artifact lands at .gaia/local/specs/SPEC-NNN.md and serves as the contract for /gaia plan to decompose into work. The skill produces an artifact and stops. It does not implement anything.

This is for when you want to implement a large feature or change request with multiple parts, or you want to present an idea or concept and refine it before implementation.

The flow runs on top of spec-kit, with GAIA-specific shape and discipline layered through a registered preset and extension.

When to use it

Run /gaia spec for any feature where the boundaries are not yet clear. It is the right entry point when the description has more questions than answers, or when multiple readings of the same prompt produce different intents.

For changes whose intent is already obvious (a bug fix, a refactor against a known interface, a copy edit), skip directly to /gaia plan.

How to invoke

Interactive (most common)

In interactive mode, the agent asks the user a series of questions to clarify the intent.

/gaia spec your feature description

Auto mode

In auto mode, the agent answers its own questions without user input. If you find that you are consistently picking the recommended option in interactive mode, or if the description is already well-formed or you just want to see what the agent produces, auto mode is a good choice.

/gaia spec auto your feature description

A description is required in auto mode. Without one, the skill aborts immediately.

Two-gate ceremony

The SPEC has two gates and they are non-negotiable.

Gate 1: shape confirmation. Before any clarifying question fires, the skill presents the proposed intent paragraph and the proposed UATs in plain English. The user reads, confirms, or revises. On confirmation, the gate-1 shape is snapshotted to .gaia/local/cache/gate1-<spec_id>.json and treated as immutable for the remainder of the session. The self-review at gate 2 detects drift against this snapshot.

Gate 2: artifact confirmation. After the Socratic loop and self-review apply, the full rendered SPEC is presented to the user one last time. Revisions loop until the user confirms. Only then does the canonical save fire.

Once saved, the SPEC artifact is immutable. Mutations require an explicit reopen ceremony with ## Reopen rationale and ## UAT diff sections, which the lint helper enforces.

Operational primitives

A handful of mechanics are used by multiple steps:

• Working-draft cache. Every fold in the Socratic loop, every gate confirmation, every research result, every self-review apply persists the in-flight draft to .gaia/local/cache/draft-<spec_id>.md. A single Write per turn. No incremental Edit calls. Step 8’s canonical save deletes the cache as its final action. Resumed sessions pick up the cache if it is newer than the canonical artifact.
• Per-topic revisit counter. Tracks how many times the user has chosen “push deeper” on a given topic. On the third revisit, the prompt swaps to settle, defer, or push deeper anyway. Prevents one topic from consuming the whole session.
• Five-question cap. Spec-kit’s /clarify primitive caps the loop at five total questions per session. The wrapper inherits this cap and never invokes /clarify twice to extend it.
• Discuss-this escape. Any closed-set question can drop into a plain Q&A discussion. On settlement, the outcome folds into clarifications.answered[] and the structured loop resumes on the next topic.
• Save partial and resume later. Every closed-set question offers this escape. It writes the draft cache and exits. Re-invoking /gaia spec resumes from the right step.

The flow

1. Description capture. Open-ended prompt if not provided as arguments.
2. GitHub issue mirror prompt. Single AskUserQuestion: skip (recommended) or mirror to a GitHub issue on save.
3. Resume-vs-start-new. If an in-progress SPEC exists, the skill surfaces it (last touched, intent first line, UAT count) and asks: resume, start new, or discard the draft cache.
4. Initial draft. /speckit-specify runs the GAIA preset’s body, allocates a SPEC id, lands the artifact at .gaia/local/specs/SPEC-NNN.md. The before_specify hook (constitution check) fires automatically.
5. Gate 1. Plain prompt: confirm intent and UATs, or revise.
6. Socratic clarify loop. /speckit-clarify runs, capped at five questions. Closed-set questions go through AskUserQuestion with the recommended option first; open-ended questions are plain prompts. Per-topic exhaustion checkpoints fire when the natural well runs dry. Research subagents dispatch for any question requiring prior-art lookup.
7. Self-review. The after_clarify hook fires /speckit-gaia-self-review against the gate-1 snapshot. Findings come back classified low, medium, or high. Low and medium auto-apply; high surfaces to the user before applying. Pending clarifications block save until answered or deferred with rationale.
8. Gate 2. Plain prompt: confirm the full rendered artifact, or revise.
9. Canonical save. Writes .gaia/local/specs/SPEC-NNN.md and deletes the working-draft cache. The after_specify hook fires /speckit-gaia-lint for immutability checks. Cycles 1 and 2 surface failures; cycle 3 prompts to step back to gate 2, defer remaining findings, or push another fix.
10. Optional GitHub issue mirror. If opted in at step 2, gh-mirror.sh creates the issue and stamps the URL into frontmatter. Skips silently when gh is not authenticated, Issues are disabled, or the viewer lacks write permission.
11. Chain to /gaia plan. AskUserQuestion: trigger /gaia plan now or defer. On yes, the skill enters a multi-plan dispatch loop. Each plan runs in its own general-purpose Agent so the wrapper context stays bounded across plan count.

Auto mode

/gaia spec auto <description> produces a SPEC end-to-end without prompts:

• Both gates auto-confirm via internal self-check.
• Closed-set Socratic questions auto-pick the recommended option.
• Open-ended questions get the agent’s best-judgment answer.
• Per-topic exhaustion auto-advances; the third-revisit prompt auto-settles.
• Pending clarifications auto-defer with a static auto-mode rationale.
• The GitHub issue mirror is forced on.
• The chain to /gaia plan is automatic and produces exactly one plan covering the full SPEC.

Use auto mode when the description is well-formed and the cost of stopping for clarifications outweighs the cost of a reviewer auditing the deferred items afterward.

Constraints during a spec session

• Write-surface allowlist. Every write lands in .gaia/local/specs/, .specify/, or .gaia/local/cache/. No source files, no repo configs.
• No machine-local memory for project decisions. Project-relevant decisions belong only in the SPEC artifact, the wiki, or .claude/rules/. Personal preferences (tone, formatting) remain allowed in machine-local memory.

How spec-kit fires GAIA hooks

Spec-kit’s hooks are not shell scripts. When core invokes /speckit-specify (or any other core skill), it reads .specify/extensions.yml for the relevant event and emits an EXECUTE_COMMAND: <id> markdown directive into the agent’s reasoning context. The agent then invokes the rendered slash command as a normal Claude skill.

Five GAIA hooks fire across the SPEC lifecycle. Never invoke them by hand.

Event	Slash command	What it does
before_specify	/speckit-gaia-constitution-check	Verifies .specify/memory/constitution.md is populated and the spec-kit version matches the pin. Blocks if either fails.
after_clarify	/speckit-gaia-self-review	Audits the in-progress draft for placeholders, scope drift against gate 1, internal inconsistency, ambiguous UATs, and pending clarifications.
after_specify	/speckit-gaia-lint	Immutability lint on the saved SPEC: required frontmatter keys, frozen uat_id per UAT, no placeholder text.
before_implement	/speckit-gaia-uat-write	Renders frozen UATs into Playwright e2e specs at .playwright/e2e/<spec-dir>/, leaving a red-state harness before implementation begins.
after_implement	/speckit-gaia-wiki-promote	Promotes merged-PR content into the project wiki under wiki/<subdomain>/. Defers if the implementing PR has not merged yet.

The chain-trigger to /gaia plan lives inline at step 11 of the flow, not as a hook. Disposition of the SPEC artifact (archive, delete, keep) happens through /gaia spec close <SPEC-NNN> after the implementing PR merges.

Related

After save, /gaia plan is the natural next step. The chain-trigger at step 11 dispatches it automatically when accepted.