> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Story-Driven Development

> Every line of code starts with a story: the AIOX development methodology

<Note>
  **Status**: MUST (Constitutional Principle)

  Defined in `.aiox-core/constitution.md` - All development MUST follow story-driven principles. Violations blocked via gates.
</Note>

## The Principle

**All development begins and ends with a story.**

No code is written without a story. No feature ships without story validation. Stories are the atomic unit of development in AIOX.

<Card title="Core Tenet" icon="scroll">
  Stories provide the context, requirements, acceptance criteria, and completion definition that enable AI agents to implement features autonomously and reliably.
</Card>

## Constitutional Rules

From the AIOX Constitution v1.0.0:

### MUST Rules

<Warning>
  These rules are **mandatory** and enforced via automated gates:
</Warning>

<Steps>
  <Step title="No Code Without Story">
    **MUST**: Nenhum código é escrito sem uma story associada

    Every implementation effort must be tied to a specific story file in `docs/stories/`.
  </Step>

  <Step title="Clear Acceptance Criteria">
    **MUST**: Stories DEVEM ter acceptance criteria claros antes de implementação

    Stories cannot be implemented until they have well-defined, verifiable acceptance criteria.
  </Step>

  <Step title="Progress Tracking">
    **MUST**: Progresso DEVE ser rastreado via checkboxes na story

    Tasks and subtasks are tracked using markdown checkboxes: `[ ]` → `[x]`
  </Step>

  <Step title="File List Maintenance">
    **MUST**: File List DEVE ser mantida atualizada na story

    Every file created, modified, or deleted must be documented in the story's File List section.
  </Step>

  <Step title="Standard Workflow">
    **SHOULD**: Stories seguem o workflow: @po/@sm cria → @dev implementa → @qa valida → @devops push

    The recommended workflow ensures quality gates at each transition.
  </Step>
</Steps>

## Gate Enforcement

<Warning>
  **Gate**: `dev-develop-story.md` - BLOCK if no valid story exists
</Warning>

```mermaid theme={null}
graph LR
    A[Start Development] --> B{Valid Story Exists?}
    B -->|No| C[BLOCK: Create Story First]
    B -->|Yes| D{Acceptance Criteria?}
    D -->|No| C
    D -->|Yes| E{Story Status Approved?}
    E -->|No| C
    E -->|Yes| F[ALLOW: Begin Implementation]
    
    style C fill:#dc3545,color:#fff
    style F fill:#34a853,color:#fff
```

## Story Anatomy

Every AIOX story follows a consistent structure:

<Tabs>
  <Tab title="Header">
    **Story Identification**

    ```yaml theme={null}
    ---
    story_id: story-1.2.3
    epic_id: epic-1.2
    title: User Authentication System
    status: Draft | Approved | In Progress | Ready for Review | Done
    priority: High | Medium | Low
    complexity: Simple | Standard | Complex
    assignee: @dev
    created: 2026-03-05
    updated: 2026-03-05
    ---
    ```

    Provides essential metadata for tracking and workflow automation.
  </Tab>

  <Tab title="Context">
    **Story Description**

    ```markdown theme={null}
    ## Story

    As a user
    I want to securely authenticate
    So that I can access protected features

    ### Background
    Current system lacks authentication. Users need secure login.

    ### References
    - PRD: docs/prd.md (Section 3.2)
    - Architecture: docs/architecture.md (Auth Flow)
    ```

    Provides context WITHOUT duplicating full PRD/architecture docs.
  </Tab>

  <Tab title="Acceptance Criteria">
    **Verifiable Requirements**

    ```markdown theme={null}
    ## Acceptance Criteria

    - [ ] User can register with email/password
    - [ ] User can log in with valid credentials
    - [ ] User receives JWT token on successful login
    - [ ] Token expires after 24 hours
    - [ ] Invalid credentials return 401 error
    - [ ] All endpoints are covered by tests
    ```

    Must be **specific**, **testable**, and **complete**.
  </Tab>

  <Tab title="Tasks">
    **Implementation Checklist**

    ```markdown theme={null}
    ## Tasks

    ### Backend
    - [ ] Create user model with email/password fields
    - [ ] Implement password hashing (bcrypt)
    - [ ] Create /register endpoint
    - [ ] Create /login endpoint
    - [ ] Implement JWT token generation
    - [ ] Add token expiration logic

    ### Tests
    - [ ] Unit tests for user model
    - [ ] Integration tests for auth endpoints
    - [ ] Test token expiration behavior
    ```

    Provides **sequenced steps** for implementation.
  </Tab>

  <Tab title="Dev Agent Record">
    **Agent-Maintained Sections**

    ```markdown theme={null}
    ## Dev Agent Record

    ### Agent Model Used
    - claude-4.5-sonnet (2026-03-05)

    ### Debug Log References
    - No critical issues encountered

    ### Completion Notes
    - Implemented JWT with 24h expiration
    - Used bcrypt for password hashing
    - All tests passing

    ### Change Log
    - 2026-03-05: Initial implementation
    - 2026-03-05: Added integration tests
    ```

    **ONLY** @dev can modify these sections.
  </Tab>

  <Tab title="File List">
    **Changed Files Inventory**

    ```markdown theme={null}
    ## File List

    ### Created
    - src/models/User.ts
    - src/routes/auth.ts
    - src/utils/jwt.ts
    - tests/auth.test.ts

    ### Modified
    - src/app.ts (added auth routes)
    - package.json (added bcrypt, jsonwebtoken)

    ### Deleted
    - None
    ```

    Critical for code review and rollback capability.
  </Tab>
</Tabs>

## The Story Lifecycle

### Phase 1: Creation

<Card title="@sm (Scrum Master) Drafts Story" icon="pen">
  Using `*draft` command and `create-next-story.md` task:

  1. Read epic context
  2. Extract requirements from PRD/architecture
  3. Define clear acceptance criteria
  4. Break down into sequenced tasks
  5. Populate all required sections
  6. Set status: "Draft"
</Card>

**Key Principle:**

> "Creating crystal-clear stories that dumb AI agents can implement without confusion"

Stories must be **self-contained**—all information needed for implementation is IN the story.

### Phase 2: Validation

<Card title="@po (Product Owner) Validates" icon="clipboard-check">
  Using `*validate-story-draft {story-id}` command:

  1. Check story completeness
  2. Verify acceptance criteria clarity
  3. Ensure PRD/architecture alignment
  4. Validate task sequencing
  5. Issue GO/NO-GO decision
</Card>

**Validation Checklist:**

* All required sections present?
* Acceptance criteria testable?
* Tasks properly sequenced?
* References to PRD/arch docs?
* Complexity appropriately assessed?

**Outcomes:**

* **GO**: Status → "Approved", ready for @dev
* **NO-GO**: Status remains "Draft", @sm revises

### Phase 3: Implementation

<Card title="@dev (Developer) Implements" icon="code">
  Using `*develop {story-id}` command and `dev-develop-story.md` task:

  **Order of Execution:**

  1. Read first (or next) task
  2. Implement task and subtasks
  3. Write tests
  4. Execute validations
  5. ONLY if ALL pass → mark checkbox `[x]`
  6. Update File List with changes
  7. Repeat until all tasks complete
</Card>

**Implementation Modes:**

<Tabs>
  <Tab title="Interactive Mode">
    `*develop-interactive {story-id}`

    **Default mode**: Checkpoints at each task

    ```mermaid theme={null}
    graph LR
        A[Read Task] --> B[Implement]
        B --> C[Test]
        C --> D{Pass?}
        D -->|Yes| E[Mark Complete]
        D -->|No| B
        E --> F{More Tasks?}
        F -->|Yes| G[Ask User: Continue?]
        F -->|No| H[Complete]
        G -->|Yes| A
    ```

    **Best for:** Learning, complex stories, high-risk changes
  </Tab>

  <Tab title="YOLO Mode">
    `*develop-yolo {story-id}`

    **Autonomous mode**: No interruptions

    ```mermaid theme={null}
    graph LR
        A[Read All Tasks] --> B[Implement All]
        B --> C[Test All]
        C --> D{Pass?}
        D -->|Yes| E[Mark Complete]
        D -->|No| F[Retry/Fix]
        F --> C
        E --> G[Ready for Review]
    ```

    **Best for:** Simple stories, trusted implementations, speed

    **Generates**: `.ai/decision-log-{story-id}.md` with autonomous decisions
  </Tab>

  <Tab title="Preflight Mode">
    `*develop-preflight {story-id}`

    **Planning mode**: Plan first, execute after approval

    ```mermaid theme={null}
    graph LR
        A[Read All Tasks] --> B[Create Implementation Plan]
        B --> C[Show Plan to User]
        C --> D{Approved?}
        D -->|Yes| E[Execute Plan]
        D -->|No| F[Revise Plan]
        F --> C
        E --> G[Complete]
    ```

    **Best for:** Architectural changes, unfamiliar domains, risk mitigation
  </Tab>
</Tabs>

**Critical Rules for @dev:**

* ✓ ONLY update Dev Agent Record sections
* ✓ Mark tasks `[x]` ONLY when validated
* ✓ Update File List continuously
* ✗ NEVER modify Story, Acceptance Criteria, or other sections
* ✗ NEVER skip tests ("I'll add them later")

**Completion Criteria:**

1. All tasks marked `[x]`
2. All validations pass (lint, typecheck, tests, build)
3. File List complete
4. Story DoD checklist executed
5. Status → "Ready for Review"

### Phase 4: Quality Assurance

<Card title="@qa (QA Engineer) Reviews" icon="shield-check">
  Using `*review {story-id}` command and `qa-review-story.md` task:

  **Review Process:**

  1. Validate acceptance criteria met
  2. Review code quality and standards
  3. Check test coverage
  4. Verify File List accuracy
  5. Execute QA gate checks
  6. Issue verdict
</Card>

**QA Verdicts:**

<Tabs>
  <Tab title="APPROVE">
    ✅ **Story meets all quality standards**

    * All acceptance criteria satisfied
    * Code follows standards
    * Tests comprehensive and passing
    * No critical issues

    **Next Step:** @devops push
  </Tab>

  <Tab title="REJECT">
    ⚠️ **Issues found, requires fixes**

    * Generates `QA_FIX_REQUEST.md`
    * Lists specific issues
    * Provides fix guidance

    **Next Step:** @dev `*fix-qa-issues` (8-phase fix workflow)
  </Tab>

  <Tab title="BLOCKED">
    🛑 **Critical issues prevent approval**

    * Fundamental problems
    * Architecture violations
    * Security concerns

    **Next Step:** Escalate to @architect or @aiox-master
  </Tab>
</Tabs>

**QA Feedback Loop:**

```mermaid theme={null}
graph TD
    A[@qa review] --> B{Verdict?}
    B -->|APPROVE| C[@devops push]
    B -->|REJECT| D[@dev fix-qa-issues]
    B -->|BLOCKED| E[Escalate]
    D --> F[Apply Fixes]
    F --> A
    
    style C fill:#34a853,color:#fff
    style D fill:#f9ab00,color:#fff
    style E fill:#dc3545,color:#fff
```

Maximum 5 iterations before escalation.

### Phase 5: Deployment

<Card title="@devops (DevOps) Deploys" icon="rocket">
  Using `*push` command and `github-devops-pre-push-quality-gate.md` task:

  **Pre-Push Quality Gate:**

  1. `npm run lint` → Must pass
  2. `npm run typecheck` → Must pass
  3. `npm test` → Must pass
  4. `npm run build` → Must succeed
  5. Story status → "Done" or "Ready for Review"
  6. All checks pass → `git push`
  7. Create Pull Request (if configured)
</Card>

**Why Only @devops Can Push?**

* Centralized quality enforcement
* Consistent deployment process
* Audit trail for all pushes
* Constitutional authority separation

## Story Progress Tracking

### Checkbox System

<Card title="Task Tracking" icon="list-check">
  Progress is tracked using markdown checkboxes:

  ```markdown theme={null}
  ## Tasks

  - [ ] Incomplete task
  - [x] Completed task
  - [ ] Another incomplete task
  ```

  Agents mark `[x]` ONLY when task is validated and complete.
</Card>

### File List Maintenance

<Card title="Change Inventory" icon="folder-tree">
  Every file touched during implementation is documented:

  **Purpose:**

  * Code review efficiency
  * Rollback capability
  * Impact analysis
  * Merge conflict prevention

  **Rule:** Update CONTINUOUSLY, not at the end.
</Card>

### Status Transitions

```mermaid theme={null}
stateDiagram-v2
    [*] --> Draft: @sm creates
    Draft --> Approved: @po validates (GO)
    Draft --> Draft: @po validates (NO-GO)
    Approved --> InProgress: @dev starts
    InProgress --> ReadyForReview: @dev completes
    ReadyForReview --> InProgress: @qa REJECT
    ReadyForReview --> Done: @qa APPROVE
    Done --> [*]: @devops pushes
```

## Why Story-Driven?

### For AI Agents

<CardGroup cols={2}>
  <Card title="Context Sufficiency" icon="database">
    Stories contain ALL information needed. Agents don't need to search/guess.
  </Card>

  <Card title="Verifiable Progress" icon="check-double">
    Checkbox tracking provides clear completion state.
  </Card>

  <Card title="Bounded Scope" icon="square-dashed">
    Tasks define exact work—prevents scope creep.
  </Card>

  <Card title="Quality Gates" icon="shield">
    Each phase has clear entry/exit criteria.
  </Card>
</CardGroup>

### For Humans

<CardGroup cols={2}>
  <Card title="Traceability" icon="timeline">
    Every change maps to a story with rationale.
  </Card>

  <Card title="Review Efficiency" icon="magnifying-glass">
    File List + tasks provide review roadmap.
  </Card>

  <Card title="Knowledge Capture" icon="brain">
    Dev Agent Record preserves decisions.
  </Card>

  <Card title="Reproducibility" icon="clone">
    Clear tasks enable recreation if needed.
  </Card>
</CardGroup>

### For Teams

<CardGroup cols={2}>
  <Card title="Shared Understanding" icon="users">
    Stories are single source of truth.
  </Card>

  <Card title="Parallel Work" icon="diagram-project">
    Clear boundaries enable simultaneous stories.
  </Card>

  <Card title="Onboarding" icon="graduation-cap">
    New team members read stories to understand.
  </Card>

  <Card title="Audit Trail" icon="file-lines">
    Complete history of what/why/when.
  </Card>
</CardGroup>

## Common Pitfalls

<Warning>
  **Anti-Pattern**: Starting implementation before story validation

  **Result:**

  * Wasted effort on wrong requirements
  * Scope misalignment
  * Quality gate failures
  * Rework

  **Solution:** Always wait for @po validation (GO decision)
</Warning>

<Warning>
  **Anti-Pattern**: Vague acceptance criteria

  **Example:** "User can authenticate" ❌

  **Better:** "User receives JWT token on successful login" ✅

  **Result of vague:** Ambiguous completion, agent confusion, incomplete implementation

  **Solution:** Make criteria **specific**, **testable**, **complete**
</Warning>

<Warning>
  **Anti-Pattern**: Not updating File List during development

  **Result:**

  * Incomplete story record
  * Difficult code review
  * Merge conflicts
  * Lost context

  **Solution:** Update File List CONTINUOUSLY as you modify files
</Warning>

<Warning>
  **Anti-Pattern**: Modifying story sections outside agent authority

  **Example:** @dev changing Acceptance Criteria ❌

  **Result:**

  * Scope drift
  * Requirement corruption
  * Loss of product vision

  **Solution:** Respect section ownership boundaries
</Warning>

## Integration with Other Principles

Story-Driven Development works in harmony with:

<CardGroup cols={2}>
  <Card title="CLI First" icon="terminal" href="/concepts/cli-first">
    All story workflows execute via CLI commands (`*develop`, `*review`, `*push`)
  </Card>

  <Card title="Agent Authority" icon="user-shield" href="/concepts/agents#authority">
    Story lifecycle enforces agent authority boundaries
  </Card>

  <Card title="Quality First" icon="shield-check" href="/guides/quality-gates">
    Stories enforce quality gates at each transition
  </Card>

  <Card title="No Invention" icon="ban" href="/concepts/architecture#principles">
    Stories derive from PRD/architecture, never invent
  </Card>
</CardGroup>

## Best Practices

<Check>
  **Story Creation**

  * Extract requirements from PRD/architecture
  * Make acceptance criteria specific and testable
  * Sequence tasks logically
  * Include all necessary context WITHOUT duplicating docs
  * Set appropriate complexity level
</Check>

<Check>
  **Story Implementation**

  * Read full story before starting
  * Follow task sequence exactly
  * Mark checkboxes ONLY when validated
  * Update File List continuously
  * Use appropriate mode (interactive/yolo/preflight)
</Check>

<Check>
  **Story Review**

  * Validate ALL acceptance criteria
  * Check File List completeness
  * Verify test coverage
  * Review code quality
  * Provide specific, actionable feedback
</Check>

## Summary

<Card title="Story-Driven Development Essence" icon="star">
  **Stories are the atomic unit of development**

  * Provide complete context for agents
  * Define clear success criteria
  * Track progress transparently
  * Enforce quality gates
  * Enable autonomous implementation
  * Maintain audit trail

  **No story = No code. Period.**
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    See how stories flow through workflows
  </Card>

  <Card title="Agent System" icon="robot" href="/concepts/agents">
    Learn which agents work with stories
  </Card>

  <Card title="Creating Stories" icon="pen" href="/guides/creating-stories">
    Practical guide to story creation
  </Card>

  <Card title="Quality Gates" icon="shield-check" href="/guides/quality-gates">
    Understand story quality enforcement
  </Card>
</CardGroup>