Skip to main content

​
Overview

The Development Cycle (Story Development Cycle - SDC) is the primary workflow for all code implementation in AIOX. It enforces story-driven development through a structured, four-phase agent handoff sequence.
Typical Duration: 1-5 days depending on story complexitySuccess Indicators:
  • Story status: “Ready for Review” or “Done”
  • All tests passing
  • PR created and approved

​
Phase 1: Story Creation (SM)

​
Agent: River (@sm)

Command: *draft or *create-next-story Task: create-next-story.md Input: Epic context from docs/epics/{epic-id}.md Output: Story file in docs/stories/{story-id}-{title}.md
1

Epic Analysis

SM reads the epic document to understand overall scope and goals
2

Story Decomposition

Breaks epic into implementation-sized user stories (typically 1-3 days each)
3

Story Drafting

Creates story markdown with:
  • Clear title and description
  • Acceptance criteria (initially as placeholders)
  • File list section
  • Task checklist
  • Metadata (status: Draft)
# Story 3.1 - OAuth Provider Integration

**Status:** Draft
**Epic:** 3.0 - Authentication System
**Effort:** 3 points
**Dependencies:** None

## Description

Implement OAuth 2.0 provider integration for user authentication.

## Acceptance Criteria

- [ ] OAuth provider configured with client ID and secret
- [ ] Authorization code flow implemented
- [ ] Token exchange endpoint functional
- [ ] User session created upon successful auth
- [ ] Error handling for failed auth attempts

## File List

**Created:**
- `src/auth/oauth-provider.ts`
- `src/auth/oauth-config.ts`
- `tests/auth/oauth.test.ts`

**Modified:**
- `src/config/app-config.ts`

## Tasks

- [ ] Create OAuth provider class
- [ ] Implement authorization flow
- [ ] Add token exchange logic
- [ ] Write unit tests
- [ ] Update configuration

## Notes

- Must use existing auth service per CON-001
- Response time target: < 200ms (NFR-001)

​
Phase 2: Story Validation (PO)

​
Agent: Nova (@po)

Command: *validate-story-draft {story-id} Task: validate-next-story.md Input: Draft story from Phase 1 Output: GO/NO-GO decision + updated story status
Gate Checkpoint: Story cannot proceed to development without PO validation.

​
Validation Checklist

The PO agent verifies:
  • Title follows format: “Story - ”
  • Status field present and set to “Draft”
  • Epic linkage documented
  • Effort estimate provided
  • Dependencies listed (or explicitly “None”)
  • At least 3 testable criteria
  • Each criterion is measurable
  • Criteria align with epic goals
  • No invented requirements (Constitution check)
  • File list includes all expected changes
  • Task breakdown is actionable
  • Complexity assessment reasonable
  • Technical approach documented if STANDARD/COMPLEX

​
Validation Outcomes

decision: GO
confidence: 0.90
status_update: Approved
message: "Story is well-defined and ready for development."
next_command: "*develop {story-id}"
Story status updated to Approved. Developer can proceed.

​
Phase 3: Implementation (Dev)

​
Agent: Dex (@dev)

Command: *develop {story-id} (interactive) or *develop-yolo {story-id} (autonomous) Task: dev-develop-story.md Input: Approved story Output: Implemented code + updated story status

Interactive Mode

Default modePauses at key checkpoints:
  • After planning
  • Before major changes
  • After each acceptance criterion
Best for: Complex stories, learning

YOLO Mode

Autonomous executionRuns end-to-end without interruption.Best for: Simple stories, trusted patterns

Pre-flight Mode

Plan-then-executeShows complete plan, waits for approval, then executes.Best for: High-risk changes

​
Development Workflow

1

Story Analysis

Developer agent reads story, acceptance criteria, and linked spec/epic
2

Implementation Planning

Creates execution plan:
  • File changes needed
  • Order of implementation
  • Test strategy
# Interactive mode: shows plan, waits for confirmation
# YOLO mode: proceeds automatically
3

Code Implementation

Implements each acceptance criterion:
  • Writes production code
  • Creates/updates tests
  • Updates configuration if needed
// Example: OAuth provider implementation
export class OAuthProvider {
  async authorize(): Promise<AuthorizationURL> {
    // Implementation per AC-001
  }
  
  async exchangeToken(code: string): Promise<TokenResponse> {
    // Implementation per AC-002
  }
}
4

Story Progress Update

As each task completes, developer updates story:
  • Checks off completed tasks: [ ] → [x]
  • Updates File List with actual changes
  • Documents any deviations or decisions
5

Pre-commit Quality Gate

Runs Layer 1 quality checks:
npm run lint        # ESLint
npm run typecheck   # TypeScript
npm test            # Unit + integration tests
npm run build       # Build verification
BLOCKED if any check fails.
6

Local Commit

Creates commit with conventional commit message:
feat(auth): implement OAuth provider integration

- Add OAuthProvider class with authorization flow
- Implement token exchange endpoint
- Add comprehensive test coverage
- Update app configuration for OAuth

Closes Story-3.1
Developer does NOT push to remote. That authority belongs exclusively to @devops per the Constitution.

​
Phase 4: QA Review (QA)

​
Agent: Quinn (@qa)

Command: *review {story-id} (full review) or *gate {story-id} (quick gate) Task: qa-gate.md or qa-review-story.md Input: Implemented story with code changes Output: Verdict (PASS/CONCERNS/FAIL/WAIVED) + findings

​
QA Evaluation Layers

Checks:
  • All acceptance criteria met
  • Feature works as specified
  • Edge cases handled
  • Error handling robust
Method: Code review + test execution
Checks:
  • Follows coding standards
  • No code smells or anti-patterns
  • Proper error handling
  • Logging and observability added
  • Comments where needed (not obvious code)
Method: Static analysis + manual review
Checks:
  • Unit tests for new functions
  • Integration tests for workflows
  • Coverage >= previous level (no regression)
  • Tests are meaningful (not just mocks)
Method: Coverage report + test quality review
Checks:
  • Story file list updated
  • README updated if needed
  • API docs generated
  • Comments explain “why” not “what”
Method: Documentation review
Checks:
  • Performance targets met (NFR-001: < 200ms)
  • Security best practices followed
  • Accessibility standards if UI change
  • Dependency updates justified
Method: NFR checklist validation

​
QA Verdicts

verdict: PASS
confidence: 0.95
findings: []
message: "Implementation meets all criteria. Ready for merge."
next_agent: devops
next_command: "*push"
Story proceeds to DevOps for push and PR creation.

​
QA Loop (Iterative)

If QA returns FAIL, enter the QA Loop: Max Iterations: 5 (configurable) Commands:
  • *fix-qa-issues - Developer addresses specific findings
  • *apply-qa-fixes - Developer applies automated fixes
  • *review {story-id} - QA re-reviews after fixes

​
Phase 5: Push & PR Creation (DevOps)

​
Agent: Felix (@devops)

Command: *push (pre-push checks + push + PR) Task: github-devops-pre-push-quality-gate.md Input: QA-approved code on local branch Output: Code pushed to remote + PR created
1

Pre-Push Quality Gate (Layer 2)

Runs comprehensive checks:
npm run lint
npm run typecheck
npm test
npm run build
npm run security-scan  # If configured
BLOCKED if any check fails.
2

Push to Remote

git push -u origin feature/story-3.1-oauth-integration
Only @devops has authority to push (Constitution).
3

Create Pull Request

Automated PR creation via GitHub CLI:
gh pr create \
  --title "Story 3.1: OAuth Provider Integration" \
  --body "$(cat PR_BODY.md)" \
  --label "story" \
  --assignee @team-leads
4

Trigger CI/CD

GitHub Actions triggered:
  • Run tests on multiple environments
  • CodeRabbit review (automated)
  • Build verification
  • Security scans

​
Quality Gates Integration

The development cycle enforces three quality gate layers:
LayerPhaseEnforcementAutomated?
Layer 1Pre-commit (Dev)Local checks before commitYes
Layer 2PR Automation (DevOps)CI/CD + CodeRabbitYes
Layer 3Human Review (Post-PR)Architecture + final approvalNo
See Quality Gates for detailed documentation.

​
Story Status Lifecycle

​
Best Practices

Keep stories small and focused:Good:
  • Implement OAuth provider integration (3 points)
  • Add user session management (5 points)
  • Create login UI component (2 points)
Too Large:
  • Build complete authentication system (21 points) ← Should be an epic
Rule of Thumb: If story > 5 points, consider splitting.
Use conventional commits:
feat(scope): add new feature
fix(scope): fix bug
refactor(scope): refactor code
test(scope): add tests
docs(scope): update documentation
Include story reference: Closes Story-{id} or Refs Story-{id}
Write tests before or during implementation:
  1. Read acceptance criterion
  2. Write failing test
  3. Implement code to pass test
  4. Refactor if needed
  5. Move to next criterion

​
Troubleshooting

Issue: Pre-commit quality gate failsResolution:
# Run checks individually to diagnose
npm run lint          # Fix linting errors
npm run typecheck     # Fix type errors
npm test              # Fix failing tests
npm run build         # Fix build errors

# Re-attempt development
*develop {story-id} --resume
Issue: QA returns FAIL multiple timesResolution:
  • Review QA findings carefully
  • Ensure you understand root cause, not just symptoms
  • Consider pairing with human developer if stuck
  • After 5 iterations, escalate to @architect for guidance

​
Next Steps

Quality Gates

Understand the three-layer validation system in detail

Agent: Developer

Explore Dex’s full command set and capabilities

Agent: QA

Learn about Quinn’s review methodology and criteria

Story Templates

Reference templates for different story types

Build docs developers (and LLMs) love

Get started for freeTalk to us