Development Workflow

Complete guide to story-driven development and daily workflows in AIOX

Overview

AIOX uses a story-driven development approach where all work starts from a story file in docs/stories/. This ensures traceability, consistent quality, and clear acceptance criteria.

Story-Driven Development

Core Principle

Every feature, bug fix, or enhancement begins with a story. Stories provide:

• Clear requirements - Acceptance criteria define what “done” means
• Task tracking - Checkboxes track progress
• Traceability - Link code changes to requirements
• Context - Maintain understanding across sessions

Story Structure

id: "1.1"
title: "Story Title"
description: "What needs to be done and why"
status: "ready" | "in progress" | "Ready for Review" | "completed"

acceptance_criteria:
  - name: "Feature works correctly"
    tasks:
      - "[ ] Implement core functionality"
      - "[ ] Add error handling"
      - "[ ] Write unit tests"

dev_agent_record:
  agent_model: 'claude-sonnet-4-5'
  implementation_date: '2025-01-23'

The Story Development Cycle

Phase 1: Story Creation

Agent: @sm (Scrum Master)

# Activate Scrum Master
@sm

# Create a new story
*draft

The SM will:

1. Ask about the feature/requirement
2. Create a story file in docs/stories/
3. Define acceptance criteria
4. Break down into tasks

Phase 2: Story Validation

Agent: @po (Product Owner)

# Activate Product Owner
@po

# Validate the story
*validate-story-draft

The PO runs a 10-point validation checklist:

1. Story ID is unique and follows convention
2. Title is clear and descriptive
3. Description explains “what” and “why”
4. Acceptance criteria are testable
5. Tasks are well-defined
6. Dependencies are documented
7. Risks are identified
8. Estimate is reasonable
9. Story is properly sized
10. Story aligns with product goals

Phase 3: Implementation

Agent: @dev (Developer)

# Activate Developer
@dev

# Start implementation
*develop

Dex will:

1. Read the story file
2. Implement code according to acceptance criteria
3. Write tests for each criterion
4. Update checkboxes as tasks complete: [ ] → [x]
5. Update the File List section
6. Change story status to “Ready for Review”

Phase 4: QA Review

Agent: @qa (Quality Assurance)

# Activate QA
@qa

# Review the implementation
*review STORY-ID

Quinn will:

1. Run all quality gates (lint, typecheck, tests)
2. Verify test coverage meets threshold (80%+)
3. Check acceptance criteria are met
4. Review code quality and patterns
5. Validate error handling

Phase 5: Git Operations

Agent: @devops (DevOps)

# Activate DevOps
@devops

# Push changes
*push

Felix will:

1. Stage changes
2. Create commit with story reference
3. Push to remote
4. Create pull request if needed

Note: Only @devops has push authority in AIOX.

Daily Development Workflow

Starting Your Day

# 1. Update your local repository
git checkout master
git pull origin master

# 2. Check story status
@po
*list-stories

# 3. Pick next story
# Look for stories with status: "ready"

# 4. Start implementation
@dev
*develop

During Development

# Check story progress
cat docs/stories/X.X-story.yaml

# Update checkboxes as you complete tasks
# Change: - "[ ] Task"
# To:     - "[x] Task"

# Run quality checks frequently
npm run lint
npm run typecheck
npm test

Before Committing

# 1. Ensure all story tasks are checked
# 2. Update story status to "Ready for Review"
# 3. Run full quality gate
@qa
*review STORY-ID

# 4. If QA passes, commit
git add .
git commit -m "feat: implement feature [Story X.X]"

# 5. Push (triggers pre-push hook)
git push origin feature/my-feature

End of Day

# 1. Update story status if incomplete
# Keep as "in progress" if work continues tomorrow

# 2. Commit work in progress (optional)
git add .
git commit -m "wip: partial implementation [Story X.X]"

# 3. Document blockers or questions in story
# Add notes section with any issues

Working with Tasks

Task Categories

Category	Examples
Development	develop-story, code-review, refactor
Quality	run-tests, validate-code, security-scan
Documentation	generate-docs, update-readme
Workflow	create-story, manage-sprint

Executing Tasks

# List available tasks
aiox tasks list

# Execute a specific task
*task develop-story --story=1.1

# Get task help
*task --help

# Run with verbose output
*task develop-story --story=1.1 --verbose

Task-First Architecture

User Request → Task → Agent Execution → Output
                 │
            Workflow (if multi-step)

Tasks are the primary entry point. Everything in AIOX is a task.

Working with Workflows

Available Workflows

Workflow	Use Case	Agents Involved
story-development-cycle	Standard feature dev	SM → PO → Dev → QA
greenfield-fullstack	New full-stack project	All agents
brownfield-integration	Add to existing project	dev, architect
qa-loop	Quality assurance cycle	QA → Dev

Running Workflows

# Start a workflow
*run-workflow story-development-cycle start

# Check workflow status
*run-workflow story-development-cycle status

# Continue to next step
*run-workflow story-development-cycle continue

# Skip optional step
*run-workflow story-development-cycle skip

# Abort workflow
*run-workflow story-development-cycle abort

Workflow State

Workflows persist state across sessions in .aiox/{instance-id}-state.yaml:

instance_id: "wf-abc123"
workflow_name: "story-development-cycle"
status: "active"
current_step: 2
total_steps: 4
steps:
  - id: create
    status: completed
  - id: validate
    status: in_progress
  - id: implement
    status: pending
  - id: review
    status: pending

Agent Collaboration

Command Authority

Each command has exactly one authoritative agent owner:

Command	Owner	Purpose
*create-prd	@pm	Create product requirements
*create-epic	@pm	Create epic
*draft	@sm	Create story
*validate-story-draft	@po	Validate story
*develop	@dev	Implement feature
*review	@qa	Quality review
*push	@devops	Git push operations

Agent Handoffs

Typical handoff sequence:

1. @pm creates PRD → *create-epic
   Output: docs/prd/epic.md
   Handoff: "Epic ready for @sm to create stories"

2. @sm creates stories → *draft
   Output: docs/stories/X.X-story.yaml
   Handoff: "Story ready for @po validation"

3. @po validates → *validate-story-draft
   Output: Validation report
   Handoff: "Story approved for @dev implementation"

4. @dev implements → *develop
   Output: Code + tests
   Handoff: "Implementation ready for @qa review"

5. @qa reviews → *review
   Output: QA report
   Handoff: "Approved for @devops to push"

6. @devops pushes → *push
   Output: Commit + PR
   Handoff: "Changes pushed to remote"

Code Quality Standards

Pre-commit Checks

Before every commit, these checks run automatically:

# ESLint (code style)
npm run lint

# TypeScript (type checking)
npm run typecheck

# Tests with coverage
npm test

Coverage Requirements

• Minimum: 80% overall coverage
• Statements: 80%
• Branches: 75%
• Functions: 80%
• Lines: 80%

Code Style

Follow the coding standards in .aiox-core/framework/coding-standards.md:

• Use absolute imports
• Follow TypeScript strict mode
• Write descriptive variable names
• Add JSDoc comments for public APIs
• Keep functions small and focused

Story Status Management

Status Flow

ready → in progress → Ready for Review → completed

Status Definitions

Status	Meaning	Who Sets
ready	Validated and ready to start	@po
in progress	Implementation started	@dev
Ready for Review	Implementation complete, needs QA	@dev
completed	QA passed, merged to main	@devops

Updating Status

# In docs/stories/X.X-story.yaml
# Change this:
status: "in progress"

# To this when all tasks complete:
status: "Ready for Review"

Best Practices

Story Creation

1. Keep stories small - 1-3 days of work maximum
2. Clear acceptance criteria - Must be testable
3. Include “why” - Document the business value
4. Link dependencies - Reference related stories

Implementation

1. Work from the story - Read it before coding
2. Update as you go - Check off tasks immediately
3. Test each criterion - One test per acceptance criterion
4. Update file list - Track all changed files

Quality

1. Run checks frequently - Don’t wait for pre-commit
2. Fix issues immediately - Don’t accumulate technical debt
3. Review your own code - Before requesting @qa review
4. Write meaningful tests - Not just for coverage

Collaboration

1. Use the right agent - Follow command authority
2. Clear handoffs - Document what’s ready for next agent
3. Ask questions - Use *help when unsure
4. Document decisions - Keep notes in story file

Troubleshooting

Story Validation Fails

# Check story format
node .aiox-core/utils/aiox-validator.js story docs/stories/X.X-story.yaml

# Common issues:
# - Missing required sections
# - Status doesn't match checkbox completion
# - Invalid YAML syntax

Quality Gate Fails

# Run individual checks
npm run lint
npm run typecheck
npm test

# Auto-fix lint issues
npm run lint -- --fix

# See detailed test output
npm test -- --verbose

Agent Not Responding

1. Verify agent file exists: ls .aiox-core/development/agents/
2. Sync IDE: npm run sync:ide
3. Restart IDE/CLI session
4. Check agent syntax: *help

Next Steps

• Git Workflow Guide - Learn the multi-layer validation system
• Quality Gates Guide - Deep dive into quality assurance
• Custom Workflows - Create your own workflows
• Squad Development - Build domain-specific extensions