/gaia-create-story

user-facing

Category:: Sprint Management
Lifecycle phase:: 4 -- Implementation
Arguments:: [story-key]

Arguments

Name	Type	Required	Default	Description
`story-key`	String (`E{n}-S{n}`)	No	Interactive selection	The story to create, in `E{n}-S{n}` format (e.g., `E3-S7`). The key must already exist in `epics-and-stories.md`. When omitted, the command lists all stories without files and prompts for selection.

The story file is written to .gaia/artifacts/implementation-artifacts/epic-{epic_slug}/{story_key}-{slug}/story.md with the 15 required frontmatter fields. The priority_flag field accepts null (default), "next-sprint", or "hotfix" (PR #772). The "hotfix" value is human-set only and causes /gaia-sprint-plan to auto-inject the story into the active sprint.

Layout note. The canonical layout is the nested per-story directory shown above — the basename is always the literal story.md and the parent directory carries the story key + slug. Earlier doc revisions and legacy SKILL.md text showed a flat {key}-{slug}.md shape; that legacy form remains read-only (consumers like /gaia-check-dod and /gaia-check-review-gate walk all three tiers: flat, legacy-nested-with-stories/, and the new per-story). New writes always use the per-story directory; a sibling reviews/ subdir holds review reports.

What it does

/gaia-create-story creates a detailed story file from the epics-and-stories breakdown. It elaborates the story with acceptance criteria in Given/When/Then format, tasks and subtasks, test scenarios, and dependencies. The story is written to its epic directory and registered in the backlog.

When to use it

You have an epic with stories listed in epics-and-stories.md and need to create the detailed story file before development can begin.
Sprint planning flagged a story as "no individual file" -- this command creates it.

Prerequisites

Epics and stories must exist. The story key must appear in .gaia/artifacts/planning-artifacts/epics-and-stories.md. Run /gaia-create-epics first.
No existing story in a non-backlog status. If a story file already exists and is past backlog status, the command halts and directs you to /gaia-fix-story.

Orchestration mode

When /gaia-create-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-create-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 _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-create-story E3-S7

Pass the story key. If omitted, the command displays stories without files and asks you to select one.

What it does step by step

Select story Locates the story in epics-and-stories.md and checks whether a file already exists.
Load context Reads the architecture, UX design, and PRD for elaboration context.
Elaborate story Offers two paths: answer elaboration questions yourself, or auto-delegate to PM and Architect agents (and UX Designer if the story has UI scope). For medium and larger stories, edge-case analysis runs automatically.
Generate story file Writes the story file with complete frontmatter (15 required fields), acceptance criteria, tasks, test scenarios, and dependencies to .gaia/artifacts/implementation-artifacts/epic-{epic_slug}/{story_key}-{slug}/story.md.
Register in backlog Registers the story with status: backlog across all tracking surfaces.
Validate Runs validation against the story file. If critical issues are found, attempts auto-fix (up to 3 attempts). On pass, transitions the story to ready-for-dev.

Story validator CLI shape

The three structural validators that /gaia-create-story invokes during the post-write check (Step 5) accept the story file path in two forms:

Canonical: --file <path>
Deprecated (accepted with NOTICE): a single positional argument

The validators:

scripts/validate-frontmatter.sh — checks the 17-field required-frontmatter contract.
scripts/validate-ac-format.sh — checks the - [ ] **AC{N}:** Given/When/Then checkbox shape.
scripts/validate-canonical-filename.sh — checks the per-story layout.

Operators driving the validators directly should prefer --file <path>. The positional form is preserved for back-compat with older invocations but emits a NOTICE: positional path is deprecated line on stderr. Supplying both forms in the same call is refused.

# Canonical
scripts/validate-frontmatter.sh --file .gaia/artifacts/implementation-artifacts/epic-E1-core/E1-S1-vault-init/story.md

# Deprecated (still works, emits NOTICE)
scripts/validate-frontmatter.sh .gaia/artifacts/implementation-artifacts/epic-E1-core/E1-S1-vault-init/story.md

Acceptance-criteria shape

validate-ac-format.sh is strict — every acceptance criterion in the story body MUST begin with the markdown checkbox prefix - [ ] followed by a bold **AC{N}:** label and a Given/When/Then triple. Bold-bullet variants without the leading checkbox (- **AC1:** Given …), unnumbered bullets, or free-prose acceptance lines all fail the validator with a CRITICAL verdict — even when the content is semantically correct. This shape is enforced because the dev-story and review-qa skills parse the AC list line-by-line off the checkbox prefix; loosening the regex breaks downstream automation.

The required shape, with a worked example block hand-authors can copy directly:

## Acceptance Criteria

- [ ] **AC1:** Given a vault file at ~/.kee/vault.kee, When the user runs kee open vault, Then the CLI prompts for the master password and unlocks the vault on success.
- [ ] **AC2:** Given an incorrect master password, When the user submits it, Then the CLI prints error: invalid password and exits non-zero without revealing whether the path exists.
- [ ] **AC3:** Given a missing vault file, When the user runs the open command, Then the CLI prints error: vault not found at <path> and exits with code 2.

Edge-case ACs follow the same shape; the validator does not distinguish primary from edge-case rows. The story-template ships pre-populated with this idiom — operators amending an existing story should mirror the template's row shape exactly.

Inputs

Input	Source	Description
`story-key`	Command argument	The story to create, in `E{n}-S{n}` format.
Epics and stories	`.gaia/artifacts/planning-artifacts/epics-and-stories.md`	Story summary and epic context.
Architecture	`.gaia/artifacts/planning-artifacts/architecture.md`	Technical context for elaboration.
UX design	`.gaia/artifacts/planning-artifacts/ux-design.md`	UI context (when applicable).

Outputs

Output	Location	Description
Story file	`.gaia/artifacts/implementation-artifacts/epic-{epic_slug}/{story_key}-{slug}/story.md`	Complete story with frontmatter, ACs, tasks, and test scenarios.
Updated tracking	Multiple surfaces	Story registered with `backlog` (or `ready-for-dev` after validation).

Examples

1. Happy path with story key

> /gaia-create-story E3-S7

Loading story E3-S7 from epics-and-stories.md...
  Title: User authentication
  Epic: E3 -- Security

How would you like to elaborate this story?
[u] I'll answer the elaboration questions myself
[a] Auto-delegate to PM (Derek) and Architect (Theo)   -- recommended
> a

Delegating to PM and Architect...

  PM (Derek): 3 edge cases identified, AC prioritization complete.
  Architect (Theo): 2 implementation constraints from the architecture.

Edge case analysis: 6 scenarios generated (boundary, error, security).
Appending edge-case ACs to story...

Writing story file to .gaia/artifacts/implementation-artifacts/epic-E3-security/E3-S7-user-authentication/story.md...
  Frontmatter: 15/15 required fields populated.
  ACs: 5 primary + 3 edge-case (Given/When/Then format).
  Tasks: 8 subtasks.
  Test scenarios: 6 rows.

Registering E3-S7 as backlog...

Validation: PASSED (0 critical, 0 warning).
Transitioning E3-S7 to ready-for-dev.

Story E3-S7 created and ready for development.

2. Interactive selection (no key)

> /gaia-create-story

Loading epics-and-stories.md...

Stories without individual files:
  [1] E5-S12  Add webhook retry logic          (M, P0)
  [2] E5-S14  Improve error messages            (S, P1)
  [3] E8-S3   Config validation UI               (L, P2)

Select a story number: 1

Loading story E5-S12 from epics-and-stories.md...
  Title: Add webhook retry logic
  Epic: E5 -- Integrations

How would you like to elaborate this story?
...

3. Hotfix priority_flag workflow

When a story's frontmatter has priority_flag: "hotfix" (human-set), the story file is created normally. The "hotfix" value is preserved in the frontmatter. When /gaia-sprint-plan runs next, it auto-injects the story into the active sprint via sprint-state.sh inject.

> /gaia-create-story E12-S4

Loading story E12-S4 from epics-and-stories.md...
  Title: Fix payment webhook timeout
  Epic: E12 -- Hotfix queue

[gaia-create-story] Canonical basename preview: E12-S4-fix-payment-webhook-timeout.md

Writing story file...
  Frontmatter: 15/15 required fields populated.
  priority_flag: "hotfix"

Registering E12-S4 as backlog...
Validation: PASSED (0 critical, 0 warning).
Transitioning E12-S4 to ready-for-dev.

Story E12-S4 created. priority_flag: "hotfix" preserved.
Next: /gaia-sprint-plan will auto-inject this story into the active sprint.

4. Regenerating an existing backlog story

When a story file already exists with status: backlog, the command warns before overwriting. If the status is anything past backlog, the command halts.

> /gaia-create-story E5-S12

Loading story E5-S12 from epics-and-stories.md...

WARNING: Story file exists with status backlog. Proceeding will regenerate it.
Continue? y

Writing story file to .gaia/artifacts/implementation-artifacts/epic-E5-integrations/E5-S12-add-webhook-retry-logic/story.md...
...

5. Validation failure -- recovery via /gaia-fix-story

If validation fails after the 3-attempt auto-fix cap, the story remains in validating status. Use /gaia-fix-story to resolve the remaining findings manually.

> /gaia-create-story E6-S9

...
Writing story file...
Registering E6-S9 as backlog...

Validation attempt 1/3: 1 CRITICAL (missing traces_to field).
  Auto-fix: added traces_to: [FR-042].

Validation attempt 2/3: 1 WARNING (AC-3 missing Given/When/Then format).
  Auto-fix: reformatted AC-3.

Validation attempt 3/3: 1 WARNING (dependency E6-S8 not in done status).
  Cannot auto-fix: dependency state is external.

Terminal verdict: FAILED (review-gate.sh updated).
Story E6-S9 remains in validating status.

Run /gaia-fix-story E6-S9 to resolve the remaining findings.

What to run next

/gaia-sprint-plan -- include the new story in a sprint.
/gaia-dev-story -- implement the story immediately if it is in a sprint.
/gaia-atdd -- generate acceptance test skeletons for high-risk stories.

Troubleshooting

"Story is in 'in-progress' status"

A story file already exists and is past backlog. Use /gaia-fix-story to edit it.

"epics-and-stories.md not found"

Run /gaia-create-epics to create the breakdown first.

Validation fails after 3 attempts

The story remains in validating status. Run /gaia-fix-story to manually resolve the remaining findings.

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

Command	Relationship
`/gaia-create-epics`	Creates the epics-and-stories breakdown that this command reads.
`/gaia-fix-story`	Fixes validation findings on an existing story.
`/gaia-dev-story`	Implements the story after it reaches ready-for-dev.
`/gaia-sprint-plan`	Includes the story in a sprint.