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

```mermaid theme={null}
graph LR
    A[@sm: Draft Story] --> B[@po: Validate]
    B --> C[@dev: Implement]
    C --> D[@qa: Review]
    D -->|Pass| E[@devops: Push & PR]
    D -->|Issues| F[@dev: Fix]
    F --> D
```

<Info>
  **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
</Info>

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

<Steps>
  <Step title="Epic Analysis">
    SM reads the epic document to understand overall scope and goals
  </Step>

  <Step title="Story Decomposition">
    Breaks epic into implementation-sized user stories (typically 1-3 days each)
  </Step>

  <Step title="Story Drafting">
    Creates story markdown with:

    * Clear title and description
    * Acceptance criteria (initially as placeholders)
    * File list section
    * Task checklist
    * Metadata (status: Draft)
  </Step>
</Steps>

<Accordion title="Story Template">
  ```markdown theme={null}
  # 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)
  ```
</Accordion>

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

<Warning>
  **Gate Checkpoint:** Story cannot proceed to development without PO validation.
</Warning>

### Validation Checklist

The PO agent verifies:

<Accordion title="Story Structure">
  * [ ] Title follows format: "Story {id} - {Title}"
  * [ ] Status field present and set to "Draft"
  * [ ] Epic linkage documented
  * [ ] Effort estimate provided
  * [ ] Dependencies listed (or explicitly "None")
</Accordion>

<Accordion title="Acceptance Criteria">
  * [ ] At least 3 testable criteria
  * [ ] Each criterion is measurable
  * [ ] Criteria align with epic goals
  * [ ] No invented requirements (Constitution check)
</Accordion>

<Accordion title="Implementation Plan">
  * [ ] File list includes all expected changes
  * [ ] Task breakdown is actionable
  * [ ] Complexity assessment reasonable
  * [ ] Technical approach documented if STANDARD/COMPLEX
</Accordion>

### Validation Outcomes

<Tabs>
  <Tab title="GO">
    ```yaml theme={null}
    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.
  </Tab>

  <Tab title="NO-GO">
    ```yaml theme={null}
    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.
  </Tab>
</Tabs>

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

<CardGroup cols={3}>
  <Card title="Interactive Mode" icon="hand">
    **Default mode**

    Pauses at key checkpoints:

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

    Best for: Complex stories, learning
  </Card>

  <Card title="YOLO Mode" icon="rocket">
    **Autonomous execution**

    Runs end-to-end without interruption.

    Best for: Simple stories, trusted patterns
  </Card>

  <Card title="Pre-flight Mode" icon="clipboard-check">
    **Plan-then-execute**

    Shows complete plan, waits for approval, then executes.

    Best for: High-risk changes
  </Card>
</CardGroup>

### Development Workflow

<Steps>
  <Step title="Story Analysis">
    Developer agent reads story, acceptance criteria, and linked spec/epic
  </Step>

  <Step title="Implementation Planning">
    Creates execution plan:

    * File changes needed
    * Order of implementation
    * Test strategy

    ```bash theme={null}
    # Interactive mode: shows plan, waits for confirmation
    # YOLO mode: proceeds automatically
    ```
  </Step>

  <Step title="Code Implementation">
    Implements each acceptance criterion:

    * Writes production code
    * Creates/updates tests
    * Updates configuration if needed

    ```typescript theme={null}
    // 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
      }
    }
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="Pre-commit Quality Gate">
    Runs Layer 1 quality checks:

    ```bash theme={null}
    npm run lint        # ESLint
    npm run typecheck   # TypeScript
    npm test            # Unit + integration tests
    npm run build       # Build verification
    ```

    **BLOCKED if any check fails.**
  </Step>

  <Step title="Local Commit">
    Creates commit with conventional commit message:

    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

<Note>
  Developer does NOT push to remote. That authority belongs exclusively to @devops per the [Constitution](/architecture/constitution).
</Note>

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

<AccordionGroup>
  <Accordion title="Functional Verification">
    **Checks:**

    * [ ] All acceptance criteria met
    * [ ] Feature works as specified
    * [ ] Edge cases handled
    * [ ] Error handling robust

    **Method:** Code review + test execution
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Documentation">
    **Checks:**

    * [ ] Story file list updated
    * [ ] README updated if needed
    * [ ] API docs generated
    * [ ] Comments explain "why" not "what"

    **Method:** Documentation review
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### QA Verdicts

<Tabs>
  <Tab title="PASS">
    ```yaml theme={null}
    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.
  </Tab>

  <Tab title="CONCERNS">
    ```yaml theme={null}
    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.
  </Tab>

  <Tab title="FAIL">
    ```yaml theme={null}
    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.
  </Tab>

  <Tab title="WAIVED">
    ```yaml theme={null}
    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.
  </Tab>
</Tabs>

## QA Loop (Iterative)

If QA returns FAIL, enter the QA Loop:

```mermaid theme={null}
graph TD
    A[QA: FAIL verdict] --> B[@dev: Fix Issues]
    B --> C[Run Quality Gates]
    C --> D[@qa: Re-review]
    D -->|Pass| E[Proceed to Push]
    D -->|Fail| F{Iteration < 5?}
    F -->|Yes| B
    F -->|No| G[Escalate to Human]
```

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

<Steps>
  <Step title="Pre-Push Quality Gate (Layer 2)">
    Runs comprehensive checks:

    ```bash theme={null}
    npm run lint
    npm run typecheck
    npm test
    npm run build
    npm run security-scan  # If configured
    ```

    **BLOCKED if any check fails.**
  </Step>

  <Step title="Push to Remote">
    ```bash theme={null}
    git push -u origin feature/story-3.1-oauth-integration
    ```

    Only @devops has authority to push (Constitution).
  </Step>

  <Step title="Create Pull Request">
    Automated PR creation via GitHub CLI:

    ```bash theme={null}
    gh pr create \
      --title "Story 3.1: OAuth Provider Integration" \
      --body "$(cat PR_BODY.md)" \
      --label "story" \
      --assignee @team-leads
    ```
  </Step>

  <Step title="Trigger CI/CD">
    GitHub Actions triggered:

    * Run tests on multiple environments
    * CodeRabbit review (automated)
    * Build verification
    * Security scans
  </Step>
</Steps>

## 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](/workflows/quality-gates) for detailed documentation.

## Story Status Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Draft: SM creates story
    Draft --> Approved: PO validates (GO)
    Draft --> Draft: PO validates (NO-GO)
    Approved --> InProgress: Dev starts implementation
    InProgress --> ReadyForReview: Dev completes + commits
    ReadyForReview --> InProgress: QA FAIL
    ReadyForReview --> Done: QA PASS + PR merged
    Done --> [*]
```

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Commit Hygiene">
    Use conventional commits:

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

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Warning>
  **Issue:** Pre-commit quality gate fails

  **Resolution:**

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

<Warning>
  **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
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quality Gates" icon="shield-check" href="/workflows/quality-gates">
    Understand the three-layer validation system in detail
  </Card>

  <Card title="Agent: Developer" icon="code" href="/essentials/agents/dev">
    Explore Dex's full command set and capabilities
  </Card>

  <Card title="Agent: QA" icon="clipboard-check" href="/essentials/agents/qa">
    Learn about Quinn's review methodology and criteria
  </Card>

  <Card title="Story Templates" icon="file-lines" href="/guides/story-templates">
    Reference templates for different story types
  </Card>
</CardGroup>