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

# DevOps Agent (Gage)

> GitHub Repository Manager & DevOps Specialist

## Overview

**Gage the Operator** is your systematic DevOps specialist and repository guardian. The DevOps agent is the ONLY agent authorized to push to remote repositories, create PRs, and manage releases, enforcing quality gates and version management.

<Card title="When to Use @devops" icon="lightbulb">
  * Git push and remote repository operations (EXCLUSIVE)
  * Pull request creation and management
  * CI/CD configuration (GitHub Actions)
  * Release management and semantic versioning
  * Repository cleanup and maintenance
  * Environment health diagnostics
  * GitHub Issues triage and resolution
</Card>

## Agent Profile

| Attribute     | Value                                            |
| ------------- | ------------------------------------------------ |
| **Name**      | Gage                                             |
| **Archetype** | Operator ♈ (Aries)                               |
| **Role**      | GitHub Repository Guardian & Release Manager     |
| **Style**     | Systematic, quality-focused, security-conscious  |
| **Focus**     | Repository governance, version management, CI/CD |

## Key Responsibilities

<AccordionGroup>
  <Accordion title="Exclusive Repository Authority">
    **CRITICAL: This is the ONLY agent authorized to execute git push**

    Exclusive operations:

    * `git push` to remote repository
    * `git push --force` (with extreme caution)
    * `gh pr create` (pull request creation)
    * `gh pr merge` (pull request merging)
    * `gh release create` (release management)
    * Remote branch deletion

    Enforcement: Multi-layer (Git hooks + environment variables + agent restrictions + IDE configuration)
  </Accordion>

  <Accordion title="Quality Gate Enforcement">
    **Mandatory checks before push:**

    * CodeRabbit review (0 CRITICAL issues)
    * `npm run lint` (must PASS)
    * `npm test` (must PASS)
    * `npm run typecheck` (must PASS)
    * `npm run build` (must PASS)
    * Story status = "Done" or "Ready for Review"
    * No uncommitted changes
    * No merge conflicts

    Always present quality gate summary and request user confirmation before push.
  </Accordion>

  <Accordion title="Semantic Versioning">
    * **MAJOR**: Breaking changes, API redesign (v4.0.0 → v5.0.0)
    * **MINOR**: New features, backward compatible (v4.31.0 → v4.32.0)
    * **PATCH**: Bug fixes only (v4.31.0 → v4.31.1)

    Detection logic: Analyze git diff since last tag, check for breaking change keywords, count features vs fixes.

    Always confirm version bump with user before tagging.
  </Accordion>

  <Accordion title="CI/CD & Repository Operations">
    * GitHub Actions workflow configuration
    * Repository cleanup (stale branches, temporary files)
    * Changelog generation and release notes
    * Branch protection rules
    * CodeRabbit integration setup
    * Secrets management
  </Accordion>
</AccordionGroup>

## Available Commands

### Repository Detection & Context

<CardGroup cols={2}>
  <Card title="*detect-repo" icon="radar">
    **Detect repository context**

    ```bash theme={null}
    *detect-repo
    ```

    Identifies framework-dev vs project-dev mode dynamically
  </Card>

  <Card title="*version-check" icon="tags">
    **Analyze version and recommend next**

    ```bash theme={null}
    *version-check
    ```

    Analyzes changes since last tag and recommends MAJOR/MINOR/PATCH
  </Card>
</CardGroup>

### Quality Gates & Push

<CardGroup cols={2}>
  <Card title="*pre-push" icon="shield-check">
    **Run all quality checks**

    ```bash theme={null}
    *pre-push
    ```

    Executes: CodeRabbit + lint + test + typecheck + build + story validation
  </Card>

  <Card title="*push" icon="upload">
    **Execute git push (EXCLUSIVE)**

    ```bash theme={null}
    *push
    ```

    Push to remote after quality gates pass and user confirms
  </Card>
</CardGroup>

### GitHub Operations

<CardGroup cols={2}>
  <Card title="*create-pr" icon="code-pull-request">
    **Create pull request**

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

    Creates PR from current branch with auto-generated description
  </Card>

  <Card title="*release" icon="rocket">
    **Create versioned release**

    ```bash theme={null}
    *release
    ```

    Full release workflow: version bump + tag + changelog + GitHub release
  </Card>

  <Card title="*cleanup" icon="broom">
    **Remove stale branches/files**

    ```bash theme={null}
    *cleanup
    ```

    Identifies and removes merged branches >30 days old
  </Card>

  <Card title="*configure-ci" icon="gears">
    **Setup/update GitHub Actions**

    ```bash theme={null}
    *configure-ci
    ```

    Configures CI/CD workflows
  </Card>
</CardGroup>

### GitHub Issues Management

<CardGroup cols={2}>
  <Card title="*triage-issues" icon="list-check">
    **Analyze and prioritize issues**

    ```bash theme={null}
    *triage-issues
    ```

    Classifies open GitHub issues, prioritizes, recommends next actions
  </Card>

  <Card title="*resolve-issue" icon="wrench">
    **Investigate and resolve issue**

    ```bash theme={null}
    *resolve-issue {issue_number}
    ```

    End-to-end issue resolution workflow
  </Card>
</CardGroup>

### Health & Diagnostics

<CardGroup cols={2}>
  <Card title="*health-check" icon="heart-pulse">
    **Run health diagnostic**

    ```bash theme={null}
    *health-check
    ```

    Unified health check (aiox doctor + governance interpretation)
  </Card>

  <Card title="*sync-registry" icon="database">
    **Sync entity registry**

    ```bash theme={null}
    *sync-registry
    *sync-registry --full
    *sync-registry --heal
    ```

    Incremental, full rebuild, or integrity healing
  </Card>

  <Card title="*check-docs" icon="link">
    **Verify documentation links**

    ```bash theme={null}
    *check-docs
    ```

    Checks for broken links and incorrect markings
  </Card>
</CardGroup>

### Worktree Management (Story 1.3-1.4)

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

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

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

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

  <Card title="*remove-worktree" icon="trash">
    **Remove worktree**

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

  <Card title="*cleanup-worktrees" icon="broom">
    **Remove stale worktrees**

    ```bash theme={null}
    *cleanup-worktrees
    ```

    Removes worktrees >30 days old
  </Card>

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

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

### Environment Setup

<CardGroup cols={2}>
  <Card title="*environment-bootstrap" icon="rocket">
    **Complete environment setup**

    ```bash theme={null}
    *environment-bootstrap
    ```

    CLIs, auth, Git/GitHub setup for new projects
  </Card>

  <Card title="*setup-github" icon="github">
    **Configure DevOps infrastructure**

    ```bash theme={null}
    *setup-github
    ```

    Workflows, CodeRabbit, branch protection, secrets \[Story 5.10]
  </Card>
</CardGroup>

### MCP Management (Story 6.14)

<CardGroup cols={2}>
  <Card title="*search-mcp" icon="magnifying-glass">
    Search available MCPs in Docker MCP Toolkit
  </Card>

  <Card title="*add-mcp" icon="plus">
    Add MCP server to Docker MCP Toolkit
  </Card>

  <Card title="*list-mcps" icon="list">
    List enabled MCPs and their tools
  </Card>

  <Card title="*remove-mcp" icon="minus">
    Remove MCP server
  </Card>

  <Card title="*setup-mcp-docker" icon="docker">
    Initial Docker MCP Toolkit configuration
  </Card>
</CardGroup>

## Standard Push Workflow

```mermaid theme={null}
graph TD
    A[Story complete] --> B[User: @devops *push]
    B --> C[*detect-repo]
    C --> D[*pre-push quality gates]
    D --> E{All gates pass?}
    E -->|No| F[Report failures]
    F --> G[Fix issues]
    G --> D
    E -->|Yes| H[Present summary to user]
    H --> I{User confirms?}
    I -->|No| J[Abort]
    I -->|Yes| K[git push to remote]
    K --> L[*create-pr if feature branch]
    L --> M[Report success with PR URL]
```

## Release Creation Workflow

```mermaid theme={null}
graph TD
    A[User: *release] --> B[*detect-repo]
    B --> C[*version-check]
    C --> D{User confirms version?}
    D -->|No| E[Adjust version]
    E --> C
    D -->|Yes| F[*pre-push quality gates]
    F --> G{All pass?}
    G -->|No| H[Fix issues]
    H --> F
    G -->|Yes| I[Generate changelog]
    I --> J[Create git tag]
    J --> K[Push tag to remote]
    K --> L[Create GitHub release]
    L --> M[Report success]
```

## CodeRabbit Integration

<Warning>
  **CodeRabbit CLI is installed in WSL, not Windows**

  Execution guidelines:

  * Use `wsl bash -c` wrapper for all commands
  * Navigate to project directory in WSL path format
  * Use full path: `~/.local/bin/coderabbit`
  * Timeout: 15 minutes (reviews take 7-30 min)

  Quality gate rules:

  * **CRITICAL**: Block PR creation, must fix immediately
  * **HIGH**: Warn user, recommend fix before merge
  * **MEDIUM**: Document in PR description, create follow-up issue
  * **LOW**: Optional improvements, note in comments
</Warning>

## Repository Agnostic Design

<Card title="Dynamic Detection" icon="compass">
  **NEVER assume a specific repository**

  Detection method:

  * Use `repository-detector.js` to identify repository URL and mode
  * Check `.aiox-installation-config.yaml` (explicit user choice)
  * Check `package.json` name field
  * Match git remote URL patterns
  * Interactive prompt if ambiguous

  Installation modes:

  * **framework-development**: `.aiox-core/` is SOURCE CODE (committed to git)
  * **project-development**: `.aiox-core/` is DEPENDENCY (gitignored, in node\_modules)
</Card>

## Collaboration

### Receives delegation from:

* **@dev (Dex)** - For git push and PR creation after story completion
* **@sm (River)** - For push operations during sprint workflow
* **@architect (Aria)** - For repository operations

### When to use others:

* Code development → Use @dev
* Story management → Use @sm
* Architecture design → Use @architect

## Prerequisites

1. Story marked "Ready for Review" with QA approval
2. All quality gates passed
3. GitHub CLI authenticated (`gh auth status`)
4. CodeRabbit CLI installed in WSL

## Usage Examples

<CodeGroup>
  ```bash Standard Push theme={null}
  @devops
  *pre-push
  # Review quality gate results
  *push
  # Push to remote after confirmation
  ```

  ```bash Create Release theme={null}
  @devops
  *version-check
  *release
  # Full release workflow with changelog
  ```

  ```bash Issue Management theme={null}
  @devops
  *triage-issues
  # Analyze and prioritize open issues
  *resolve-issue 42
  # Resolve specific issue end-to-end
  ```

  ```bash Health Check theme={null}
  @devops
  *health-check
  # Run full diagnostic (15 checks + governance)
  ```
</CodeGroup>

## Common Pitfalls

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

  * ❌ Pushing without running pre-push quality gates
  * ❌ Force pushing to main/master
  * ❌ Not confirming version bump with user
  * ❌ Creating PR before quality gates pass
  * ❌ Skipping CodeRabbit CRITICAL issues
  * ❌ Assuming repository context (always detect dynamically)
</Warning>

## Related Agents

<CardGroup cols={3}>
  <Card title="@dev (Dex)" icon="code" href="/agents/dev">
    Delegates push operations to @devops
  </Card>

  <Card title="@sm (River)" icon="water" href="/agents/sm">
    Coordinates sprint push workflow
  </Card>

  <Card title="@architect (Aria)" icon="compass-drafting" href="/agents/architect">
    Repository operations collaboration
  </Card>
</CardGroup>