Story-Driven Development

Status: MUST (Constitutional Principle)Defined in .aiox-core/constitution.md - All development MUST follow story-driven principles. Violations blocked via gates.

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.

Core Tenet

Stories provide the context, requirements, acceptance criteria, and completion definition that enable AI agents to implement features autonomously and reliably.

Constitutional Rules

From the AIOX Constitution v1.0.0:

MUST Rules

These rules are mandatory and enforced via automated gates:

No Code Without Story

MUST: Nenhum código é escrito sem uma story associadaEvery implementation effort must be tied to a specific story file in docs/stories/.

Clear Acceptance Criteria

MUST: Stories DEVEM ter acceptance criteria claros antes de implementaçãoStories cannot be implemented until they have well-defined, verifiable acceptance criteria.

Progress Tracking

MUST: Progresso DEVE ser rastreado via checkboxes na storyTasks and subtasks are tracked using markdown checkboxes: [ ] → [x]

File List Maintenance

MUST: File List DEVE ser mantida atualizada na storyEvery file created, modified, or deleted must be documented in the story’s File List section.

Standard Workflow

SHOULD: Stories seguem o workflow: @po/@sm cria → @dev implementa → @qa valida → @devops pushThe recommended workflow ensures quality gates at each transition.

Gate Enforcement

Gate: dev-develop-story.md - BLOCK if no valid story exists

Story Anatomy

Every AIOX story follows a consistent structure:

Story Identification

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

Story Description

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

Verifiable Requirements

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

Implementation Checklist

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

Agent-Maintained Sections

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

Changed Files Inventory

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

The Story Lifecycle

Phase 1: Creation

@sm (Scrum Master) Drafts Story

Using *draft command and create-next-story.md task:

Read epic context
Extract requirements from PRD/architecture
Define clear acceptance criteria
Break down into sequenced tasks
Populate all required sections
Set status: “Draft”

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

@po (Product Owner) Validates

Using *validate-story-draft {story-id} command:

Check story completeness
Verify acceptance criteria clarity
Ensure PRD/architecture alignment
Validate task sequencing
Issue GO/NO-GO decision

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

@dev (Developer) Implements

Using *develop {story-id} command and dev-develop-story.md task:Order of Execution:

Read first (or next) task
Implement task and subtasks
Write tests
Execute validations
ONLY if ALL pass → mark checkbox [x]
Update File List with changes
Repeat until all tasks complete

Implementation Modes:

Interactive Mode
YOLO Mode
Preflight Mode

*develop-interactive {story-id}Default mode: Checkpoints at each taskBest for: Learning, complex stories, high-risk changes

*develop-yolo {story-id}Autonomous mode: No interruptionsBest for: Simple stories, trusted implementations, speedGenerates: .ai/decision-log-{story-id}.md with autonomous decisions

*develop-preflight {story-id}Planning mode: Plan first, execute after approvalBest for: Architectural changes, unfamiliar domains, risk mitigation

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:

All tasks marked [x]
All validations pass (lint, typecheck, tests, build)
File List complete
Story DoD checklist executed
Status → “Ready for Review”

Phase 4: Quality Assurance

@qa (QA Engineer) Reviews

Using *review {story-id} command and qa-review-story.md task:Review Process:

Validate acceptance criteria met
Review code quality and standards
Check test coverage
Verify File List accuracy
Execute QA gate checks
Issue verdict

QA Verdicts:

APPROVE
REJECT
BLOCKED

✅ Story meets all quality standards

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

Next Step: @devops push

⚠️ 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)

QA Feedback Loop: Maximum 5 iterations before escalation.

Phase 5: Deployment

@devops (DevOps) Deploys

Using *push command and github-devops-pre-push-quality-gate.md task:Pre-Push Quality Gate:

npm run lint → Must pass
npm run typecheck → Must pass
npm test → Must pass
npm run build → Must succeed
Story status → “Done” or “Ready for Review”
All checks pass → git push
Create Pull Request (if configured)

Why Only @devops Can Push?

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

Story Progress Tracking

Checkbox System

Task Tracking

Progress is tracked using markdown checkboxes:

## Tasks

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

Agents mark [x] ONLY when task is validated and complete.

File List Maintenance

Change Inventory

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.

Status Transitions

Why Story-Driven?

For AI Agents

Context Sufficiency

Stories contain ALL information needed. Agents don’t need to search/guess.

Verifiable Progress

Checkbox tracking provides clear completion state.

Bounded Scope

Tasks define exact work—prevents scope creep.

Quality Gates

Each phase has clear entry/exit criteria.

For Humans

Traceability

Every change maps to a story with rationale.

Review Efficiency

File List + tasks provide review roadmap.

Knowledge Capture

Dev Agent Record preserves decisions.

Reproducibility

Clear tasks enable recreation if needed.

For Teams

Shared Understanding

Stories are single source of truth.

Parallel Work

Clear boundaries enable simultaneous stories.

Onboarding

New team members read stories to understand.

Audit Trail

Complete history of what/why/when.

Common Pitfalls

Anti-Pattern: Starting implementation before story validationResult:

Wasted effort on wrong requirements
Scope misalignment
Quality gate failures
Rework

Solution: Always wait for @po validation (GO decision)

Anti-Pattern: Vague acceptance criteriaExample: “User can authenticate” ❌Better: “User receives JWT token on successful login” ✅Result of vague: Ambiguous completion, agent confusion, incomplete implementationSolution: Make criteria specific, testable, complete

Anti-Pattern: Not updating File List during developmentResult:

Incomplete story record
Difficult code review
Merge conflicts
Lost context

Solution: Update File List CONTINUOUSLY as you modify files

Anti-Pattern: Modifying story sections outside agent authorityExample: @dev changing Acceptance Criteria ❌Result:

Scope drift
Requirement corruption
Loss of product vision

Solution: Respect section ownership boundaries

Integration with Other Principles

Story-Driven Development works in harmony with:

CLI First

All story workflows execute via CLI commands (*develop, *review, *push)

Agent Authority

Story lifecycle enforces agent authority boundaries

Quality First

Stories enforce quality gates at each transition

No Invention

Stories derive from PRD/architecture, never invent

Best Practices

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

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)

Story Review

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

Summary