| name | spec-driven-stories |
| description | Create user stories with acceptance criteria, technical specifications, and UI specifications through an 8-phase workflow with structural anti-skip enforcement. Prevents token optimization bias through per-phase reference loading, checkpoint persistence, Execute-Verify-Record enforcement, and artifact verification. Use when transforming feature descriptions into structured stories, generating stories from epic features, or creating follow-up stories for deferred work. Supports CRUD, authentication, workflow, and reporting story types with complete technical and UI specifications.
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Task","ask the user","Skill","Bash(devforgeai-validate:*)"] |
| model | opus |
| effort | High |
| version | 2.0.0 |
| last-updated | 2026-05-20 |
| topics | user stories, acceptance criteria, technical specification, UI specification, batch, DEVARCH seed, anti-skip |
Spec-Driven Stories
Produce a complete, implementation-ready user story file with acceptance criteria, technical specification, UI specification (when applicable), and Definition of Done — written to devforgeai/specs/Stories/STORY-NNN.story.md. The story-template schema is a load-bearing contract — every downstream skill (/dev, /qa, /release, /fix-story, /validate-stories, backend-architect Phase 2.5) consumes its output shape.
Single-file design principle (NON-NEGOTIABLE): one story = one file. Sidecars (STORY-NNN-notes.md, STORY-NNN/spec.md, etc.) are forbidden — enforced deterministically by stories-sidecar-write-blocker.sh (PreToolUse[Write|Edit]). All story metadata, ACs, tech spec, UI spec, and DoD live in STORY-NNN.story.md.
Context files are THE LAW: tech-stack.md, source-tree/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md. If ambiguous or conflicting — HALT and use ask the user.
Execution Model
This skill expands inline. After invocation, execute Phase 00 Initialization immediately. Do not wait passively, ask permission, or offer execution options. See .claude/rules/core/anti-skip-behavior.md for the canonical execution contract (Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076).
INLINE-skill contract: the orchestrator executes phase steps directly (Read/Write/Edit/Glob/Grep/ask the user/Bash). Subagents are scoped to content-only or read-only roles — story-requirements-analyst (Phase 02, content-only per RCA-007), api-designer (Phase 03 conditional, content-only), story-self-validator (Phase 07, read-only findings JSON). The primary writes every file.
Anti-Skip Enforcement Contract
Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .codex/hooks/ scripts, and .codex/hooks/phase-steps-registry.json (ADR-076). Behavioral residue: .claude/rules/core/anti-skip-behavior.md.
Story Template
Current Version: v3.1 (assets/templates/story-template.md, loaded in Phase 05).
The template carries the authoritative SECTION_MANIFEST (HTML-comment-embedded YAML). Phase files derive structural constants (required sections, subsections, format_version) from the manifest via devforgeai-validate parse-manifest — never hardcoded.
DEVARCH-seed fields (v3.1, optional — populated when /create-story ingests a Development Architecture seed):
feature_ref — F-NN matching the source Solution/Development Architecturesource_devarch — relative path to the DEVARCH document
backend-architect Phase 2.5 strict-HALTs when source_devarch is required but empty (per ADR-067/068/069).
When to Use This Skill
- User runs
/create-story [feature-description | EPIC-NNN | SEED-NNN | *.development-architecture.html | --from-recommendations=STORY-NNN]
/create-stories-from-rca decomposes RCA recommendations into stories/create-missing-stories batch-creates stories for coverage gaps (via spec-driven-coverage Phase 04)- spec-driven-dev creates tracking stories for deferred DoD items
- Manual:
Skill(command="spec-driven-stories")
Do NOT use for: epic creation (use spec-driven-lifecycle epic mode), sprint planning (use spec-driven-lifecycle sprint mode), modifying existing stories (use Edit on the story file directly).
Modes
| Mode | Trigger | Phase 01 behavior |
|---|
SINGLE_STORY | Free-form feature description | Interactive ask the user for metadata |
EPIC_BATCH | EPIC-NNN argument from /create-story | Driven by context markers set by command + spec-driven-coverage |
FROM_RECOMMENDATIONS | --from-recommendations=STORY-NNN | Drives Step R.1–R.8 in story-discovery-from-recommendations.md |
DEVARCH_SEED | SEED-NNN or *.development-architecture.html argument | Phase 01 Sub-step 1.2.0 ingests + schema-validates the seed |
Batch Mode (EPIC_BATCH)
Triggered when conversation contains **Batch Mode:** true. Required context markers: Story ID, Epic ID, Feature Number, Feature Name, Feature Description, Priority, Points, Type, Sprint, Batch Mode, Batch Index.
Behavior: Phase 01 skips interactive questions and extracts metadata from markers. Phases 02–07 run unchanged. Phase 08 skips the next-action ask the user and returns to the batch loop. If required markers are missing → fall back to interactive mode.
Batch reference caching (RCA-049): stable reference files are pre-loaded ONCE before the loop (references/story-discovery-batch.md Step 0.4.5) to reduce token pressure. This is the ONLY authorized batch token optimization. Per-story subagent invocations and dynamic files (epic/sprint modified by linking) are loaded fresh each iteration. Caching does NOT authorize skipping any Execute-Verify-Record triplet.
Post-batch structural validation (RCA-049): references/story-discovery-batch.md Step 0.7 validates every created story against the SECTION_MANIFEST after the loop — HALT gate if any story is missing required sections / component IDs / format_version.
Parameter Extraction
Extract from conversation context markers set by the invoking command:
| Context Marker | Set By | Description |
|---|
$MODE | /create-story | SINGLE_STORY / EPIC_BATCH / FROM_RECOMMENDATIONS |
$EPIC_ID | /create-story | EPIC-NNN identifier |
$FEATURE_DESCRIPTION | /create-story | Feature description, SEED-NNN, or path |
$STORY_ID | batch mode | STORY-NNN identifier |
$FEATURE_NUMBER | batch mode | Feature number (e.g., 1.1) |
$FEATURE_NAME | batch mode | Feature name |
$PRIORITY | batch mode | High/Medium/Low/Critical |
$POINTS | batch mode | Story points (Fibonacci) |
$TYPE | batch mode | feature/bugfix/refactor/documentation |
$SPRINT | batch mode | Sprint-N identifier |
$BATCH_MODE | batch mode | true/false |
$BATCH_INDEX | batch mode | 0-based index |
$SOURCE_STORY_ID | FROM_RECOMMENDATIONS | Source STORY-NNN |
$REC_IDS_FLAG | FROM_RECOMMENDATIONS | Optional REC-A,REC-B filter |
$INCLUDE_BLOCKING | FROM_RECOMMENDATIONS | true/false |
$SOURCE_RCA | /create-stories-from-rca | RCA-NNN identifier (ADR-074) |
$SOURCE_RECOMMENDATION | /create-stories-from-rca | REC-N identifier (ADR-074) |
$ADDRESSES_WHY | /create-stories-from-rca | 5-Whys traceability line (ADR-074 Required tier) |
$EVIDENCE_FILES | /create-stories-from-rca | Comma-separated evidence paths (ADR-074 Required tier) |
$TEST_SPECIFICATION | /create-stories-from-rca | Markdown test table from RCA recommendation (ADR-074 Rendered tier) |
$CONDITIONAL | /create-stories-from-rca | Conditional trigger object (ADR-074 Rendered tier) |
When invoked from /create-stories-from-rca, the 6 RCA-derived markers above populate frontmatter rca_traceability fields and an <rca_origin> XML element in the story's Provenance section (rendered in Phase 05). See ADR-074 + .codex/skills/spec-driven-rca/references/recommendation-contract.md for the contract.
Phase 00: Initialization [INLINE — Bootstraps State]
This phase runs inline because it creates the state that all other phases depend on.
Step 0.1: Parse Arguments
IF context markers already set by /create-story (Mode, Epic ID, Next Session ID in conversation):
Confirm: "Context from /create-story: MODE=${MODE}, EPIC_ID=${EPIC_ID}, SESSION_ID=${NEXT_SESSION_ID}"
Skip 0.2-0.3 — preflight already handled resume + session ID
GOTO Step 0.4
ELSE:
Extract markers from Parameter Extraction table; defaults: $MODE="SINGLE_STORY", $TYPE="feature", $BATCH_MODE=false
Step 0.2: Resume Detection
FROM_RECOMMENDATIONS early-exit (story-preflight does not accept STORY-NNN args):
IF $MODE == "FROM_RECOMMENDATIONS":
today = YYYY-MM-DD
existing = search for `devforgeai/workflows/checkpoints/SC-${today}-*.checkpoint.json`
resumable = [cp for cp in existing if cp.mode == "FROM_RECOMMENDATIONS"
and cp.source_story_id == $SOURCE_STORY_ID and cp.current_phase != "08"]
IF resumable non-empty:
ask the user: "Resume FROM_RECOMMENDATIONS session for ${SOURCE_STORY_ID}? Or start fresh?"
IF resume → Restore state, GOTO Phase Orchestration Loop at CURRENT_PHASE
GOTO Step 0.3
Other modes:
IF conversation contains resume_session from story-preflight:
inspect (resume_session.checkpoint_file)
ask the user: "Resume session ${session_id}? Or start fresh?"
IF resume → Restore state, GOTO Phase Orchestration Loop at CURRENT_PHASE
ELSE:
Fallback (direct invocation, no command): Bash("devforgeai-validate story-preflight ${EPIC_ID} --project-root=. --format=json")
Parse resume_session from JSON
Step 0.3: Generate Session ID
FROM_RECOMMENDATIONS (filesystem scan):
IF $MODE == "FROM_RECOMMENDATIONS":
existing = search for `devforgeai/workflows/checkpoints/SC-${today}-*.checkpoint.json`
SESSION_ID = "SC-${today}-001" if empty else f"SC-${today}-{max_seq+1:03d}"
GOTO Step 0.4
Other modes:
IF "**Next Session ID:**" marker present: SESSION_ID = marker value
ELSE: Bash("devforgeai-validate story-preflight ${EPIC_ID} --project-root=. --format=json"); parse next_session_id
Step 0.4: CLI Initialization
devforgeai-validate phase-init ${SESSION_ID} --workflow=stories --project-root=. 2>&1
| Exit | Meaning | Action |
|---|
| 0 | New workflow | Set CURRENT_PHASE = "01"; proceed to 0.5 |
| 1 | Existing workflow | Resume: devforgeai-validate phase-status → CURRENT_PHASE |
| 2 | Invalid session ID | HALT — must match SC-YYYY-MM-DD-NNN |
| 127 | CLI not installed | Continue without CLI enforcement (backward compatibility) |
Step 0.5: Display Session Banner
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DevForgeAI Story Creation Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: ${SESSION_ID} Mode: ${MODE}
Epic: ${EPIC_ID|'None'} Batch: ${BATCH_MODE}
Feature: ${FEATURE_DESCRIPTION|'None provided'}
Phases: 8 (Discovery → Requirements → Tech Spec → UI Spec → File Creation → Linking → Validation → Completion)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
Set CURRENT_PHASE = 1. GOTO Phase Orchestration Loop at Phase 01.
Phase Orchestration Loop
For each phase from CURRENT_PHASE to 8:
- ENTRY GATE — IF phase_id == "01": skip (phase-init IS the entry gate). ELSE:
devforgeai-validate phase-check ${SESSION_ID} --workflow=stories --from={prev} --to={phase_id} --project-root=.. Exit ≠ 0 AND ≠ 127 → HALT.
- LOAD PHASE —
inspect (".codex/skills/spec-driven-stories/phases/{phase_files[phase_num]}"). Load fresh.
- LOAD REFERENCES — load the references listed in the phase's Contract section. All of them. Per-phase, not consolidated.
- EXECUTE — follow every EXECUTE-VERIFY-RECORD triplet in the phase file, in order.
- EXIT GATE —
devforgeai-validate phase-complete ${SESSION_ID} --workflow=stories --phase={phase_id} --checkpoint-passed --project-root=.. Exit ≠ 0 AND ≠ 127 → HALT.
- CHECKPOINT — update checkpoint JSON with phase completion; write to disk. file write returns cleanly on success; trust the return value.
Phase-Output Cache (Sprint 3)
Phases write per-phase JSON cache files to tmp/${SESSION_ID}/phase-outputs/phase-NN.json to share processed data without redundant disk reads or re-parsing. Schema: contracts/phase-output-schema.json (oneOf of 7 phase definitions, each carrying schema_version + phase_id discriminator constants).
Cache-miss behavior: readers ALWAYS fall through to fresh compute on missing file, schema_version mismatch, phase_id mismatch, or null payload. Cache miss is NEVER a HALT — the cache is a performance optimization, not a correctness requirement.
POST-EPIC-EDIT RE-READ CAVEAT: Phase 06.1 mutates the epic file via file edit; Phase 07.2.5 (AC fidelity check) MUST re-read the epic from disk and ignore the cache.
Phase Table
| Phase | Name | File | Subagents |
|---|
| 00 | Initialization | (inline above) | — |
| 01 | Story Discovery & Context | phases/phase-01-story-discovery.md | — |
| 02 | Requirements Analysis | phases/phase-02-requirements-analysis.md | story-requirements-analyst (BLOCKING, content-only) |
| 03 | Technical Specification | phases/phase-03-technical-specification.md | api-designer (CONDITIONAL, content-only) |
| 04 | UI Specification | phases/phase-04-ui-specification.md | — |
| 05 | Story File Creation | phases/phase-05-story-file-creation.md | — |
| 06 | Epic/Sprint Linking | phases/phase-06-epic-sprint-linking.md | — |
| 07 | Self-Validation | phases/phase-07-self-validation.md | story-self-validator (BLOCKING, read-only findings) |
| 08 | Completion Report | phases/phase-08-completion-report.md | — |
Subagent contracts (loaded per-phase, not upfront):
contracts/requirements-analyst-contract.yaml (Phase 02)contracts/api-designer-contract.yaml (Phase 03, conditional)contracts/template-consumer-contract.yaml — schema-authority relationship between story-template.md and consuming phase files. Phase files MUST derive structural constants from the manifest, never hardcode shadow copies (prevents RCA-048 drift).
State Persistence
- Checkpoint:
devforgeai/workflows/checkpoints/${SESSION_ID}.checkpoint.json
- References:
references/ (self-contained within this skill)
- Contracts:
contracts/ (self-contained)
- Templates:
assets/templates/ (self-contained)
- Scripts:
scripts/ (self-contained)
- Phase-output cache:
tmp/${SESSION_ID}/phase-outputs/phase-NN.json
Integration Points
Invoked by: /create-story, /create-stories-from-rca, spec-driven-coverage Phase 04 (which is invoked by /create-missing-stories), spec-driven-lifecycle (epic/sprint decomposition), spec-driven-dev (deferred-work tracking).
Provides output to: spec-driven-design (AC → UI requirements), spec-driven-dev Phase 01 intake + backend-architect Phase 2.5 DEVARCH intake, spec-driven-qa (AC → validation targets).
See references/integration-guide.md for complete integration patterns.
Workflow Completion Validation
completed_count = len(checkpoint.progress.phases_completed)
IF completed_count < 8: HALT "WORKFLOW INCOMPLETE — ${completed_count}/8 phases completed"
IF completed_count == 8: Display "All 8 phases completed"; update checkpoint.status = "completed"
Success Criteria
- Story ID matches
STORY-\d+
- User Story (As a / I want / So that — exactly one canonical block)
- ≥ 3 Acceptance Criteria (Given/When/Then)
- Technical specification (v2.0 YAML, components + business_rules + non_functional_requirements)
- UI specification (or explicit N/A)
- Non-functional requirements (measurable)
- Edge cases documented
- Definition of Done (checkboxes)
- Story file at
devforgeai/specs/Stories/${STORY_ID}.story.md (single file — no sidecars)
- Epic/sprint files updated (if applicable)
- Self-validation passed (Phase 07 Checks 1–9 + story-self-validator findings)
- DEVARCH-seed fields populated (when seed was supplied)
Reference Files Inventory
Loaded on-demand during workflow execution. The full inventory is documented in references/integration-guide.md; per-phase reference lists live in each phases/phase-NN-*.md Contract section. Categories:
- Phase guides (8) — one primary reference per phase
- AC patterns (4) —
acceptance-criteria-core.md, acceptance-criteria-domains.md, acceptance-criteria-refactor.md (conditional), acceptance-criteria-patterns.md
- Story discovery (4) —
story-discovery.md, story-discovery-batch.md, story-discovery-interactive.md, story-discovery-from-recommendations.md
- Creation guides (5) — requirements, technical-spec (×2), UI, story-file
- Validation (4) — story-validation-workflow, validation-checklists, context-validation, validator-traps
- Structure & examples (3) — story-structure-guide, story-examples, story-type-classification
- Supporting (5) — epic-sprint-linking, custody-chain-workflow, gap-to-story-conversion, batch-mode-configuration, completion-report
- Schema (3) — checkpoint-schema, contract-schema, template-version-validation
- Workflow (3) — error-handling, parameter-extraction, integration-guide
- Patterns (3) — fix-resolution-patterns, refactor-quality-checks, user-input-integration-guide
Total: 8 phase files + 30 references + 3 contracts + 1 template.
Best Practices
- Provide a clear feature description — minimum 10 words, specific WHO/WHAT.
- Associate with an epic when possible — enables traceability + feature tracking.
- Ensure ACs are testable — verifiable Given/When/Then, no vague metrics.
- Include UI specs for frontend work — mockups prevent implementation ambiguity (or use design.md when present).
- Trust self-validation — Phase 07 auto-corrects common issues; story-self-validator (Phase 07.2.5–7.3.7) catches RCA-050/FM-4/FM-5 patterns.
