/gaia-dev-story

What it does

/gaia-dev-story is GAIA's most comprehensive development command. It implements a single user story end-to-end using a strict Test-Driven Development (TDD) cycle: it loads the story specification, plans the implementation, writes failing tests, implements code to make them pass, refactors, verifies the Definition of Done checklist, commits, pushes to a feature branch, creates a pull request, waits for CI to pass, and merges. When finished, the story's Review Gate is initialized for the review phase.

When to use it

• You have a story in ready-for-dev status and want GAIA to implement it using TDD.
• A story previously failed review and you want to rework it -- GAIA detects the in-progress status and enters rework mode, focusing on the review issues.
• A session was interrupted mid-implementation -- GAIA detects the checkpoint and enters resume mode, continuing from where it stopped.

For smaller changes that do not warrant a full story lifecycle, use /gaia-quick-spec followed by /gaia-quick-dev instead.

Prerequisites

• A story file must exist. The file lives inside its epic directory at .gaia/artifacts/implementation-artifacts/epic-{epic_key}-{slug}/stories/{story_key}-{slug}.md (epic-grouped layout). If it does not exist, the command will stop and tell you to run /gaia-create-story first.
• Story status must be ready-for-dev or in-progress. Stories in any other status (backlog, review, done) cannot be implemented.
• All dependency stories must be done. If the story's depends_on list includes stories that are not yet in done status, the command will stop and list the blocking dependencies.
• High-risk stories need ATDD scenarios. If the story's risk level is high, an ATDD scenarios file must exist under .gaia/artifacts/test-artifacts/. If missing, you will be directed to run /gaia-atdd first.
• Architecture and planning artifacts should exist. The command reads architecture.md and ux-design.md for implementation context. They are not strictly required, but their absence reduces plan quality.
• Design approval required. The design must be approved before implementation can begin. Run /gaia-design-review to complete the review, or pass --force-design --reason "<text>" to override with an audited reason. When the override succeeds, a notice is emitted with the current design state, the override reason, and a warning that ux-design.md may be outdated. Override entries carry the sprint scope (sprint_id) in the audit trail. Projects without a UI (compliance.ui_present: false or absent) skip this gate automatically.

Orchestration mode

When /gaia-dev-story 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-dev-story 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 .gaia/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-dev-story E3-S7

The argument is the story key in E{n}-S{n} format (for example, E3-S7 means Epic 3, Story 7).

What it does step by step

1. Load story Locates your story file, reads its frontmatter (status, risk level, dependencies, acceptance criteria), and determines the execution mode: fresh (new implementation), rework (fixing review failures), or resume (continuing from a checkpoint).
2. Update status For fresh stories, transitions the status from ready-for-dev to in-progress. Rework and resume stories are already in-progress.
3. ATDD gate (high-risk only) For stories with risk: high, verifies that acceptance test scenarios exist. If missing, the command stops and directs you to /gaia-atdd.
4. Create the story worktree and feature branch Creates a git feature branch named after the story key. When worktree mode is on (GAIA_WORKTREE_MODE=1 in the environment), the branch is checked out in its own linked worktree at .gaia-worktrees/{story_key}, a sibling of your repository's top-level directory, and every later step (edits, tests, commits, push, pull request) runs inside that worktree while your primary checkout is left untouched. Re-running the command for a story whose worktree still exists re-enters that worktree instead of creating a second one. With the mode off, the branch is created in place; if it already exists (from a prior attempt), the command offers to resume on it.
5. Round guard (rework mode only) In rework mode, before the developer is dispatched, the orchestrator verifies the latest review round is complete by calling assert-round-complete. It also writes and binds the correction brief (or supersedes an existing one). If the round is incomplete or the brief was silently widened, the command halts. Legacy stories with no orchestrated round skip this check.
6. Plan implementation Reads the architecture, UX design, and story acceptance criteria. Generates a detailed implementation plan covering: context, steps, files to modify, testing strategy, and risks.
   
   You are then asked to approve, revise, or validate the plan:
   • approve -- proceed to coding.
   • revise -- provide feedback; GAIA regenerates the plan.
   • validate -- GAIA runs the validator against the plan and shows findings.

   If you have YOLO mode enabled, the plan is automatically validated and auto-fixed (up to 3 iterations) without prompting.

7. TDD Red phase -- write failing tests For each acceptance criterion, GAIA writes test(s) that define the expected behavior. It runs the test suite to confirm all new tests fail (because the implementation does not exist yet). No implementation code is written in this phase.
8. TDD Green phase -- implement to pass GAIA writes the minimum code needed to make all failing tests pass. It runs the test suite after each change to confirm tests are turning green. Each completed acceptance criterion is checked off in the story file.
9. Advisory checks After all tests pass, GAIA scans the staged changes for patterns that commonly carry hidden risk: API route changes (may need contract tests), schema/migration changes (may need migration verification), and large blast radius (many files changed -- may warrant a feature flag). These are advisory only and never block progress.
10. TDD Refactor phase Improves code quality while keeping all tests green: extracts shared utilities, decomposes large functions, improves naming, removes duplication. The test suite is re-run to confirm nothing broke.
11. Post-refactor validation Runs a single validation pass over all code written during the TDD cycle to catch cross-cutting issues. Automatically fixes critical and warning-level findings (up to 3 iterations).
12. Capture findings Any out-of-scope issues discovered during implementation are recorded in the story file's Findings table for later triage.
13. Definition of Done Runs the DoD checklist: build passes, tests pass, no lint warnings, no staged secrets, all subtasks checked, acceptance criteria met. If any check fails, GAIA attempts to fix it automatically (up to 3 attempts).
14. Commit and push Stages all changes, creates a commit with a conventional commit message, and pushes the feature branch to the remote. The commit subject uses a product scope (the main skill or script area the change touches), not the story key. The story key appears in a Story: line in the commit body. The push is blocked if you are on a protected branch (main or staging).
15. Create pull request Creates a PR targeting the first environment in your CI promotion chain. The PR title is the commit subject as written (the story key is not prepended). The PR body includes the acceptance criteria, Definition of Done, a diff summary, and the story cross-reference.
16. Wait for CI Polls CI status using required checks via gh pr checks --required (falls back to all checks with a note when required checks are unavailable or the flag is unsupported). Uses jq-based JSON parsing with a two-poll stability rule and a grace window for late-registering checks. On timeout or failure, the story run halts -- CI must pass before merge. Timeout is configurable via ci_cd.ci_wait_timeout_minutes in project config (default 30 minutes, overridden by --timeout CLI flag). Reports failures with the specific check name and bucket.
17. Merge PR Merges the PR using the repository's configured merge strategy. Handles conflicts and branch protection rules.
18. Post-completion verification Verifies that the merge commit containing the story key actually exists on the target branch. If the merge failed silently, re-runs the push/PR/CI/merge sequence.
19. Initialize Review Gate Seeds the story's Review Gate table with six review rows (code, QA, security, test, performance, accessibility) all set to UNVERIFIED, and transitions the story to review status.
20. Auto-reviews (YOLO mode only) In YOLO mode, automatically runs all six reviews to populate the Review Gate. In normal mode, this step is skipped -- you run reviews manually or via /gaia-review-all.

Inputs

Outputs

Example session

Below is a condensed example of what a typical session looks like.

> /gaia-dev-story E3-S7

Loading story E3-S7...
  Story file: .gaia/artifacts/implementation-artifacts/epic-E3-security/stories/E3-S7-user-authentication.md
  Status: ready-for-dev
  Risk: medium
  Mode: FRESH
  Dependencies: E3-S5 (done), E3-S6 (done) -- all clear.

Transitioning E3-S7 to in-progress...

Creating feature branch feat/E3-S7-user-authentication...
  Branch created.

Planning implementation...

  ## Implementation Plan

  ### Context
  E3-S7 adds email/password authentication to the Express API using
  bcrypt for password hashing and JWT for session tokens.

  ### Steps
  1. Create auth middleware (src/middleware/auth.ts)
  2. Add user model with password hash field (src/models/user.ts)
  3. Implement login endpoint (src/routes/auth.ts)
  4. Implement registration endpoint (src/routes/auth.ts)
  5. Add token refresh endpoint (src/routes/auth.ts)

  ### Testing Strategy
  - Unit tests for password hashing and token generation
  - Integration tests for each endpoint
  - Edge cases: expired tokens, invalid credentials, duplicate emails

  ### Risks
  - Timing attack on password comparison (mitigated by bcrypt)

Do you want to: [approve] [revise] [validate]
> approve

--- TDD Red Phase ---
Writing failing tests for AC1 (user can register with email/password)...
Writing failing tests for AC2 (user can log in with valid credentials)...
Writing failing tests for AC3 (expired tokens are rejected)...
Running test suite: 8 new tests, 8 FAILING (expected).

--- TDD Green Phase ---
Implementing src/middleware/auth.ts...
Implementing src/models/user.ts...
Implementing src/routes/auth.ts...
Running test suite: 8 new tests, 8 PASSING.

--- Advisory Checks ---
  API route changes detected in src/routes/auth.ts
    Consider adding contract tests for the new endpoints.
  (advisory only -- continuing)

--- TDD Refactor Phase ---
Extracting token utilities to src/utils/jwt.ts...
Running test suite: 8 tests, 8 PASSING.

--- Definition of Done ---
  Build: PASSED
  Tests: PASSED (47 total, 8 new)
  Lint: PASSED
  Secrets scan: PASSED
  Subtasks: 5/5 checked
  All checks passed.

Committing: feat(auth): add email/password authentication
  Story: E3-S7
Pushing to origin/feat/E3-S7-user-authentication...
Creating PR #42 "feat(auth): add email/password authentication" targeting staging...
Waiting for CI... all checks passed.
Merging PR #42...

Story E3-S7 transitioned to review.
Review Gate initialized with 6 UNVERIFIED rows.

Done. Run /gaia-review-all E3-S7 to populate the Review Gate,
or run individual reviews.

What to run next

• /gaia-review-all -- run all six reviews to populate the Review Gate.
• Or run individual reviews: /gaia-review-code, /gaia-review-security, /gaia-review-qa, /gaia-review-test, /gaia-review-perf, /gaia-review-a11y.
• /gaia-check-review-gate -- once all reviews pass, transitions the story to done.
• /gaia-triage-findings -- if the story captured findings during implementation, triage them into backlog stories.

Troubleshooting

"Story file not found"

The command expects a story file at .gaia/artifacts/implementation-artifacts/epic-{epic_key}-{slug}/stories/{story_key}-{slug}.md. Run /gaia-create-story {key} to create it from the epics-and-stories breakdown.

"Story status must be ready-for-dev or in-progress"

Stories in backlog status need to be planned into a sprint first (/gaia-sprint-plan). Stories in review or done status have already been implemented.

"Dependency not done"

One or more stories listed in the depends_on frontmatter field are not yet in done status. Implement the blocking stories first, or use /gaia-correct-course to remove or change the dependency if it is no longer needed.

"ATDD scenarios required for high-risk story"

Stories with risk: high must have acceptance test scenarios before implementation begins. Run /gaia-atdd {key} to generate them.

The command stopped at the planning gate

In normal mode, the command pauses after generating the implementation plan and asks you to approve, revise, or validate. Type approve to proceed. If you enable YOLO mode, this gate is passed automatically.

CI steps were skipped

If your project does not have a CI promotion chain configured, the commit/push/PR/CI/merge steps are skipped. The story still completes locally. Configure a promotion chain with /gaia-ci-edit if you want automated CI integration.

A story worktree was left behind

In worktree mode the command keeps a worktree rather than destroy work: it stays when the story timed out, when it still holds uncommitted changes, or when its branch is checked out elsewhere. The completion report prints the worktree path and the exact recovery command; inspect it with git -C .gaia-worktrees/{story_key} status and remove it only once nothing in it is needed. Worktrees orphaned by a run that was killed are cleared automatically the next time a story starts.

Session interrupted mid-implementation

The command writes checkpoints after every file edit. Run /gaia-resume to pick up where you left off. GAIA will detect the checkpoint and enter resume mode.

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