# Understanding the Story-Driven Development Workflow in AIOX > Discover AIOX story-driven development. Learn how markdown stories track progress through constitutional gates before code is written, ensuring acceptance criteria are met. - Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core) - Tags: deep-dive - Published: 2026-03-15 --- **AIOX enforces a story-driven development workflow where every task begins as a markdown story file in `docs/stories/` and progresses through constitutional gates that validate acceptance criteria before any code is written.** The AIOX framework (SynkraAI/aiox-core) implements a rigorous story-driven development workflow that mandates all work originate from documented requirements. This approach ensures that every code change traces back to a validated story containing clear acceptance criteria, a defined file list, and a trackable checklist that serves as the single source of truth for progress. ## What Is Story-Driven Development in AIOX? Story-Driven Development (SDD) in AIOX is a governance model defined in **Article III of the Constitution** ([`.aiox-core/constitution.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/constitution.md)). The workflow dictates that no code may be written without a corresponding story file that captures the requirement, acceptance criteria, and impacted files. According to the source code, the `*create-story` command generates a new story file under `docs/stories/`, while the `dev-develop-story` task enforces **constitutional gates** that verify story validity before allowing agent execution. This creates a hard boundary between ideation and implementation. ## Creating a Story: The Foundation of the Workflow ### Initiating with *create-story Every story-driven development workflow begins with the `*create-story` command. Developers or product owners invoke this CLI tool to generate a new story file structure: ```bash @aiox-master *create-story # prompts for title, description, acceptance criteria ``` This creates a directory under `docs/stories/{story-id}/` containing the story definition file, typically [`story.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/story.yaml) or [`story.md`](https://github.com/SynkraAI/aiox-core/blob/main/story.md). ### Defining Requirements and Acceptance Criteria Before development can commence, the story must define three critical elements as specified in [`.aiox-core/constitution.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/constitution.md) (lines 56-64): - **Title**: Clear description of the work - **Acceptance criteria**: Specific conditions that determine completion - **File List**: Explicit enumeration of files that will be modified The file list acts as a contract, limiting the scope of changes and enabling precise progress tracking. ### Validating Against Constitutional Gates The workflow enforces validation through the `*validate-story` command or the `*task validate-story-draft` task. As implemented in [`.aiox-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/tasks/dev-develop-story.md) (lines 94-107), validation checks that: - The story exists in `docs/stories/` - The status is not "Draft" - Required fields (acceptance criteria, file list) are populated Only validated stories pass **Gate 1 – Story-Driven Development** and proceed to implementation. ## Developing Against Stories: Execution Modes ### Interactive and YOLO Development Modes Once validated, development proceeds via the `*develop` task, which supports two execution modes as defined in [`.aiox-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/tasks/dev-develop-story.md) (lines 9-36): ```bash *develop STORY-123 # interactive mode (default) *develop STORY-123 yolo # YOLO mode (fast, autonomous) ``` **Interactive mode** prompts for confirmation at each step, while **YOLO mode** allows agents to proceed autonomously after initial validation. Both modes check Gate 1 before generating any code. ### Isolating Work with Git Worktrees For complex stories, developers can create isolated Git worktrees: ```bash *worktree-create STORY-123 # creates a Git worktree named after the story cd worktrees/STORY-123 ``` This isolation prevents cross-contamination between parallel stories and maintains clean branch management. ### Agent Integration and Story References During development, AIOX agents (`@dev`, `@architect`, etc.) automatically annotate all logs with the active story ID. As documented in [`squads/claude-code-mastery/agents/claude-mastery-chief.md`](https://github.com/SynkraAI/aiox-core/blob/main/squads/claude-code-mastery/agents/claude-mastery-chief.md) (lines 29-31), agents reference the story ID in every operation, creating an immutable audit trail linking code changes to requirements. ## How Stories Track Progress in AIOX ### Checkbox Checklists as Source of Truth The story file contains a **checkbox checklist** that functions as the definitive progress tracker. Each task or sub-task updates a line from `[ ]` to `[x]` as work completes: ```markdown # STORY-123 – User profile page - [ ] Acceptance criteria defined - [ ] Design mockup reviewed - [ ] Backend API implemented - [ ] Front-end component created - [ ] End-to-end tests passing - [ ] Documentation updated ``` ### File List Synchronization When checkboxes are ticked, the **File List** section updates to reflect newly modified files. This synchronization ensures the story document always matches the actual codebase state, preventing scope drift. ### Quality Gate Validation The `dev-develop-story` quality gate validates that at least one checkbox is checked before allowing merge operations, as specified in lines 96-108 of the task definition. This guarantees that progress is explicitly recorded and not merely implied by code existence. ## Closing Stories and Completing the Workflow To close a story and complete the workflow: 1. **Complete all checkboxes**: Ensure every item shows `[x]` 2. **Set status to Done**: Execute `*set-story-status STORY-123 Done` 3. **Run final quality gates**: The [`pre-push.md`](https://github.com/SynkraAI/aiox-core/blob/main/pre-push.md) task verifies the story is marked Done and all required tests pass 4. **Merge**: The story branch merges to `main` via standard Git workflow performed by `@devops` ```bash # Final validation and push npm run lint npm test *pre-push # invokes pre-push quality gate @git push # performed by @devops ``` ## Summary - **Story-Driven Development** is enforced by AIOX Constitution Article III and constitutional gates in `dev-develop-story` - All work originates from markdown files in `docs/stories/` created via `*create-story` - Stories require defined acceptance criteria and file lists before validation passes - Progress tracks via checkbox checklists updated during development - The `*develop` command supports interactive and YOLO execution modes - Git worktrees provide isolation for parallel story development - Quality gates ensure at least one checkbox is complete before merge ## Frequently Asked Questions ### What triggers the constitutional gates in the story-driven development workflow? The constitutional gates trigger automatically when invoking the `*develop` task. Specifically, **Gate 1 – Story-Driven Development** validates that the story exists, is not in Draft status, and contains required fields (acceptance criteria and file list) before any agent generates code. This validation occurs in [`.aiox-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/tasks/dev-develop-story.md). ### How does AIOX enforce that no code is written without a valid story? AIOX enforces this through hard validation in the development task pipeline. The `dev-develop-story` task checks story validity before executing agent commands. If the story fails validation—missing from `docs/stories/`, lacking acceptance criteria, or in Draft status—the workflow halts immediately and refuses to generate code, as mandated by Constitution Article III. ### What is the difference between interactive and YOLO mode in *develop? **Interactive mode** (default) requires explicit confirmation at each development step, allowing human oversight of agent actions. **YOLO mode** (`*develop STORY-123 yolo`) permits autonomous execution after initial validation, optimizing for speed when the developer trusts the story definition. Both modes enforce the same constitutional gates but differ in execution autonomy. ### How do agents track which story they are working on? Agents automatically capture the active story ID from the `*develop` command context and inject it into all log outputs. As implemented in [`squads/claude-code-mastery/agents/claude-mastery-chief.md`](https://github.com/SynkraAI/aiox-core/blob/main/squads/claude-code-mastery/agents/claude-mastery-chief.md), agents reference the story ID in every operation, creating a persistent link between code changes and the originating requirement document.