Understanding the Story-Driven Development Workflow in AIOX

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). 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:

@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 or 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 (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 (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 (lines 9-36):

*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:

*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 (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:

# 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 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

# 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.

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, agents reference the story ID in every operation, creating a persistent link between code changes and the originating requirement document.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}