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

# 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

```yaml theme={null}
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)

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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`:

```yaml theme={null}
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:

```bash theme={null}
# 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

```yaml theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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