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

# Dev Agent (Dex)

> Full Stack Developer Agent - Implementation and Testing

## Overview

**Dex the Builder** is your expert senior software engineer specializing in story implementation, testing, debugging, and code quality. The Dev agent transforms requirements into working code following test-driven development practices.

<Card title="When to Use @dev" icon="lightbulb">
  * Implementing user stories from @sm
  * Fixing bugs and refactoring code
  * Running tests and validations
  * Applying QA feedback
  * Registering technical debt
</Card>

## Agent Profile

| Attribute     | Value                                        |
| ------------- | -------------------------------------------- |
| **Name**      | Dex                                          |
| **Archetype** | Builder ♒ (Aquarius)                         |
| **Role**      | Expert Senior Software Engineer              |
| **Style**     | Pragmatic, detail-oriented, solution-focused |
| **Focus**     | Story execution, testing, code quality       |

## Key Responsibilities

<AccordionGroup>
  <Accordion title="Story Implementation">
    * Read story requirements from `docs/stories/`
    * Implement tasks and subtasks sequentially
    * Write comprehensive tests for each feature
    * Execute validations before marking complete
    * Update story **Dev Agent Record** sections only
  </Accordion>

  <Accordion title="Code Quality">
    * Run CodeRabbit pre-commit review before story completion
    * Execute linting, type checking, and test suites
    * Follow project coding standards from `technical-preferences.md`
    * Apply QA fixes from `*apply-qa-fixes` workflow
    * Register technical debt with `*backlog-debt`
  </Accordion>

  <Accordion title="Testing & Validation">
    * Write unit tests for all new functions
    * Create integration tests for API endpoints
    * Run full regression suite before marking story complete
    * Execute smoke tests after deployment
  </Accordion>

  <Accordion title="Authorized Story Updates">
    **ONLY update these story sections:**

    * Tasks/Subtasks checkboxes (\[ ] → \[x])
    * Dev Agent Record section
    * Debug Log References
    * Completion Notes
    * File List (add/modify/delete source files)
    * Change Log
    * Status (Draft → In Progress → Ready for Review)

    **DO NOT modify:** Story description, Acceptance Criteria, Dev Notes, Testing sections
  </Accordion>
</AccordionGroup>

## Available Commands

### Story Development

<CardGroup cols={2}>
  <Card title="*develop" icon="hammer">
    **Implement story tasks**

    ```bash theme={null}
    *develop story-1.2.3
    *develop-yolo           # Autonomous mode
    *develop-interactive    # Interactive mode
    *develop-preflight      # Planning mode
    ```

    Executes the full development workflow: read tasks → implement → test → validate → mark complete
  </Card>

  <Card title="*run-tests" icon="flask">
    **Execute linting and all tests**

    ```bash theme={null}
    *run-tests
    ```

    Runs: `npm run lint`, `npm run typecheck`, `npm test`
  </Card>

  <Card title="*apply-qa-fixes" icon="wrench">
    **Apply QA feedback and fixes**

    ```bash theme={null}
    *apply-qa-fixes
    ```

    Reads `QA_FIX_REQUEST.md` and applies required fixes
  </Card>

  <Card title="*create-service" icon="plus">
    **Create new service from template**

    ```bash theme={null}
    *create-service
    ```

    Scaffolds service from Handlebars templates (api-integration, utility, agent-tool)
  </Card>
</CardGroup>

### Autonomous Build (Epic 8)

<CardGroup cols={2}>
  <Card title="*build" icon="rocket">
    **Complete autonomous build**

    ```bash theme={null}
    *build story-1.2.3
    ```

    Full pipeline: worktree → plan → execute → verify → merge
  </Card>

  <Card title="*build-autonomous" icon="robot">
    **Start autonomous build loop**

    ```bash theme={null}
    *build-autonomous story-1.2.3
    ```

    Coder Agent Loop with automatic retries
  </Card>

  <Card title="*build-resume" icon="play">
    **Resume build from checkpoint**

    ```bash theme={null}
    *build-resume story-1.2.3
    ```

    Continue from last saved checkpoint
  </Card>

  <Card title="*build-status" icon="chart-line">
    **Show build status**

    ```bash theme={null}
    *build-status story-1.2.3
    *build-status --all
    ```

    View current build progress and metrics
  </Card>
</CardGroup>

### Subtask Execution (ADE - Coder Agent)

<CardGroup cols={2}>
  <Card title="*execute-subtask" icon="list-check">
    **Execute single subtask**

    ```bash theme={null}
    *execute-subtask
    ```

    13-step Coder Agent workflow for one subtask
  </Card>

  <Card title="*verify-subtask" icon="check-double">
    **Verify subtask completion**

    ```bash theme={null}
    *verify-subtask
    ```

    Runs configured verification (command, API, browser, e2e)
  </Card>
</CardGroup>

### Recovery System (Epic 5)

<CardGroup cols={2}>
  <Card title="*track-attempt" icon="clipboard">
    **Track implementation attempt**

    ```bash theme={null}
    *track-attempt
    ```

    Registers attempt in `recovery/attempts.json`
  </Card>

  <Card title="*rollback" icon="rotate-left">
    **Rollback to last good state**

    ```bash theme={null}
    *rollback
    *rollback --hard    # Skip confirmation
    ```

    Restore previous working version
  </Card>
</CardGroup>

### Worktree Isolation (Epic 8 - Story 8.2)

<CardGroup cols={2}>
  <Card title="*worktree-create" icon="code-branch">
    **Create isolated worktree**

    ```bash theme={null}
    *worktree-create story-1.2.3
    ```
  </Card>

  <Card title="*worktree-list" icon="list">
    **List active worktrees**

    ```bash theme={null}
    *worktree-list
    ```
  </Card>

  <Card title="*worktree-cleanup" icon="trash">
    **Remove completed worktrees**

    ```bash theme={null}
    *worktree-cleanup
    ```
  </Card>

  <Card title="*worktree-merge" icon="code-merge">
    **Merge worktree branch**

    ```bash theme={null}
    *worktree-merge story-1.2.3
    ```
  </Card>
</CardGroup>

### Gotchas Memory (Epic 9 - Story 9.4)

<CardGroup cols={2}>
  <Card title="*gotcha" icon="exclamation-triangle">
    **Add gotcha manually**

    ```bash theme={null}
    *gotcha "Title - Description"
    ```
  </Card>

  <Card title="*gotchas" icon="book">
    **List and search gotchas**

    ```bash theme={null}
    *gotchas
    *gotchas --category build
    *gotchas --severity critical
    ```
  </Card>

  <Card title="*gotcha-context" icon="sitemap">
    **Get relevant gotchas**

    ```bash theme={null}
    *gotcha-context
    ```

    Context-aware gotcha retrieval
  </Card>
</CardGroup>

### Workflow Intelligence (WIS-4)

<Card title="*waves" icon="wave-square">
  **Analyze workflow for parallel execution**

  ```bash theme={null}
  *waves
  *waves --visual    # ASCII art visualization
  ```

  Identifies tasks that can run in parallel
</Card>

### Quality & Utilities

<CardGroup cols={3}>
  <Card title="*backlog-debt" icon="list-ul">
    Register technical debt item (prompts for details)
  </Card>

  <Card title="*explain" icon="graduation-cap">
    Explain what was just done in teaching detail
  </Card>

  <Card title="*load-full" icon="file">
    Load complete file bypassing cache/summary
  </Card>

  <Card title="*clear-cache" icon="broom">
    Clear dev context cache to force fresh load
  </Card>
</CardGroup>

## Development Workflow

### Standard Story Implementation

```mermaid theme={null}
graph TD
    A[Story assigned by @sm] --> B[*develop story-X.Y.Z]
    B --> C[Read story requirements]
    C --> D[Implement task + subtasks]
    D --> E[Write tests]
    E --> F[Run validations]
    F --> G{All pass?}
    G -->|No| D
    G -->|Yes| H[Update checkboxes]
    H --> I[Update File List]
    I --> J[CodeRabbit review]
    J --> K{CRITICAL issues?}
    K -->|Yes| D
    K -->|No| L[Mark Ready for Review]
    L --> M[Notify @github-devops]
```

### YOLO Mode (Autonomous)

```bash theme={null}
@dev
*develop-yolo story-1.2.3
```

**Autonomous workflow:**

1. Reads story and creates decision tracking context
2. Implements all tasks without confirmation
3. Records autonomous decisions with rationale
4. Generates decision log in `.ai/decision-log-{story-id}.md`
5. Marks story complete automatically

## Git Restrictions

<Warning>
  **@dev CANNOT push to remote repository**

  Only local git operations are allowed:

  * ✅ `git add`, `git commit`, `git status`, `git diff`
  * ✅ `git branch`, `git checkout`, `git merge` (local)
  * ❌ `git push` (ONLY @github-devops)
  * ❌ `gh pr create` (ONLY @github-devops)
</Warning>

**Workflow:**

1. @dev marks story "Ready for Review"
2. @dev notifies user: "Story complete. Activate @github-devops to push changes"
3. User activates `@github-devops *push`

## CodeRabbit Integration

### Self-Healing Loop

```yaml theme={null}
Before marking story "Ready for Review":
  max_iterations: 2
  severity_filter: [CRITICAL]
  
  WHILE iteration < 2:
    1. Run CodeRabbit review (uncommitted changes)
    2. IF no CRITICAL issues:
       - Document HIGH issues in Dev Notes
       - BREAK (ready for review)
    3. IF CRITICAL issues:
       - Auto-fix each CRITICAL issue
       - iteration++
  
  IF CRITICAL issues remain:
    - HALT and report to user
    - DO NOT mark complete
```

## Collaboration

### Receives work from:

* **@sm (River)** - Assigns stories for implementation
* **@qa (Quinn)** - Provides feedback via `*apply-qa-fixes`

### Delegates to:

* **@github-devops (Gage)** - Push, PR creation, remote operations

## Usage Examples

<CodeGroup>
  ```bash Standard Story theme={null}
  @dev
  *develop story-1.2.3
  # Interactive mode, asks before major steps
  ```

  ```bash Autonomous Build theme={null}
  @dev
  *build-autonomous story-1.2.3
  # Full autonomous loop with retries
  ```

  ```bash Apply QA Fixes theme={null}
  @dev
  *apply-qa-fixes
  # Reads QA_FIX_REQUEST.md and applies fixes
  ```

  ```bash Create Service theme={null}
  @dev
  *create-service
  # Scaffolds new service from template
  ```
</CodeGroup>

## Common Pitfalls

<Warning>
  **Avoid these common mistakes:**

  * ❌ Starting before story is approved
  * ❌ Skipping tests ("I'll add them later")
  * ❌ Not updating File List in story
  * ❌ Attempting `git push` directly (use @github-devops)
  * ❌ Modifying non-authorized story sections
  * ❌ Forgetting CodeRabbit pre-commit review
</Warning>

## Related Agents

<CardGroup cols={3}>
  <Card title="@sm (River)" icon="wave" href="/agents/sm">
    Creates stories for @dev to implement
  </Card>

  <Card title="@qa (Quinn)" icon="check" href="/agents/qa">
    Reviews @dev's work and provides feedback
  </Card>

  <Card title="@devops (Gage)" icon="bolt" href="/agents/devops">
    Pushes @dev's commits to remote
  </Card>
</CardGroup>