Development Cycle

Core SM → Dev → QA → DevOps workflow for implementing features and fixes

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 complexity

Success 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 Template

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

Story Structure

• Title follows format: “Story - ”
• Status field present and set to “Draft”
• Epic linkage documented
• Effort estimate provided
• Dependencies listed (or explicitly “None”)

Acceptance Criteria

• At least 3 testable criteria
• Each criterion is measurable
• Criteria align with epic goals
• No invented requirements (Constitution check)

Implementation Plan

• File list includes all expected changes
• Task breakdown is actionable
• Complexity assessment reasonable
• Technical approach documented if STANDARD/COMPLEX

Validation Outcomes

GO

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.

NO-GO

decision: NO-GO
confidence: 0.85
issues:
  - "Acceptance criteria too vague (criterion 3)"
  - "Missing dependency on Story 2.8"
  - "File list incomplete (missing test files)"
status_update: Draft
next_command: "*draft --revise {story-id}"

Story status remains Draft. SM must address issues.

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 mode

Pauses at key checkpoints:

• After planning
• Before major changes
• After each acceptance criterion

Best for: Complex stories, learning

YOLO Mode

Autonomous execution

Runs end-to-end without interruption.

Best for: Simple stories, trusted patterns

Pre-flight Mode

Plan-then-execute

Shows 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

Functional Verification

Checks:

• All acceptance criteria met
• Feature works as specified
• Edge cases handled
• Error handling robust

Method: Code review + test execution

Code Quality

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

Test Coverage

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

Documentation

Checks:

• Story file list updated
• README updated if needed
• API docs generated
• Comments explain “why” not “what”

Method: Documentation review

NFR Compliance

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

PASS

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.

CONCERNS

verdict: CONCERNS
confidence: 0.80
findings:
  - type: minor
    description: "OAuth error messages could be more user-friendly"
    file: "src/auth/oauth-provider.ts:45"
    severity: LOW
message: "Minor issues noted but not blocking. Suggest addressing in follow-up."
waivable: true
next_command: "*push" # or "*apply-qa-fixes"

Developer can choose to fix immediately or create follow-up story.

FAIL

verdict: FAIL
confidence: 0.90
findings:
  - type: critical
    description: "Token exchange missing expiration validation"
    file: "src/auth/oauth-provider.ts:67"
    severity: HIGH
  - type: major
    description: "No tests for authorization failure scenarios"
    file: "tests/auth/oauth.test.ts"
    severity: MEDIUM
message: "Critical issues must be resolved before merge."
next_command: "*fix-qa-issues"

Story returns to Developer. Cannot proceed to merge.

WAIVED

verdict: WAIVED
confidence: 0.85
waived_by: "human-reviewer"
reason: "Performance NFR waived for v1 - follow-up story created"
findings:
  - type: waived
    description: "Response time 250ms (target was 200ms)"
    follow_up_story: "3.5"
message: "Approved with documented waivers."
next_command: "*push"

Human reviewer has authority to waive non-critical issues.

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:

Layer	Phase	Enforcement	Automated?
Layer 1	Pre-commit (Dev)	Local checks before commit	Yes
Layer 2	PR Automation (DevOps)	CI/CD + CodeRabbit	Yes
Layer 3	Human Review (Post-PR)	Architecture + final approval	No

See Quality Gates for detailed documentation.

Story Status Lifecycle

Best Practices

Story Sizing

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.

Commit Hygiene

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}

Test-Driven Development

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 fails

Resolution:

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

Resolution:

• 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