devops

---
name: devops
description: |
  REMOTE infrastructure administration (alpha v0.0.2). Server inventory, cloud provisioning
  (OCI, Hetzner, Linode, DigitalOcean, Contabo), and application deployment
  (Coolify, KASM). Profile-aware - reads servers from device profile.

  Use when: provisioning VPS, deploying to cloud, installing Coolify/KASM,
  managing remote servers.

  NOT for: local installs, Windows/WSL/macOS admin, MCP servers → use admin.
---

# Admin DevOps - Remote Infrastructure (Alpha)

**Script path resolution**: When Claude Code loads this file, it provides the full
path. Derive `SKILL_DIR` from this file's directory. Admin scripts (profile gate,
logging, secrets) live in the sibling admin skill at `${SKILL_DIR}/../admin/scripts/`.

---

## CRITICAL: Secrets and .env

- NEVER store live `.env` files or credentials inside any skill folder.
- `.env.template` files belong only in `assets/` within a skill.
- Store live secrets in `~/.admin/.env` and reference from there.

## Secrets Management

Three backends available, configured via `ADMIN_SECRETS_BACKEND` in `~/.admin/.env`:

| Backend | Storage | Best For |
|---------|---------|----------|
| `infisical` | Infisical Cloud | Multi-device, audit trail |
| `vault` (default) | `$ADMIN_ROOT/vault.age` | Single device, offline |
| `env` | `$ADMIN_ROOT/.env` | Legacy |

**Fallback chain**: infisical → vault → env. If the primary backend is unavailable, scripts automatically try the next.

**CLI**: Use the admin skill's `secrets` script to retrieve provider API keys:

```bash
# Retrieve a single provider token
HCLOUD_TOKEN=$(${SKILL_DIR}/../admin/scripts/secrets HCLOUD_TOKEN)

# Or if secrets is on PATH
export HCLOUD_TOKEN=$(secrets HCLOUD_TOKEN)
```

### Provider Secrets Map

| Secret Key | Infisical URI | Provider | Used By |
|---|---|---|---|
| `HCLOUD_TOKEN` | `infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN` | Hetzner | hcloud CLI auth |
| `DIGITALOCEAN_ACCESS_TOKEN` | `infisical://admin-operator/prod/providers/digitalocean/ACCESS_TOKEN` | DigitalOcean | doctl auth |
| `CNTB_OAUTH2_CLIENT_SECRET` | `infisical://admin-operator/prod/providers/contabo/CLIENT_SECRET` | Contabo | cntb config |
| `CNTB_OAUTH2_PASS` | `infisical://admin-operator/prod/providers/contabo/OAUTH_PASS` | Contabo | cntb config |
| `LINODE_API_TOKEN` | `infisical://admin-operator/prod/providers/linode/API_TOKEN` | Linode | linode-cli |
| `VULTR_API_KEY` | `infisical://admin-operator/prod/providers/vultr/API_KEY` | Vultr | vultr-cli |
| `CF_API_TOKEN` | `infisical://admin-operator/prod/network/cloudflare/API_TOKEN` | Cloudflare | Tunnel setup |

**Retrieval** (v4.0+):
```bash
# URI-based (recommended)
HCLOUD_TOKEN=$(resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN")

# Multi-project secrets CLI
HCLOUD_TOKEN=$(secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN)

# Legacy (still works via fallback chain)
HCLOUD_TOKEN=$(secrets HCLOUD_TOKEN)
```

**Guides**: `references/secrets-architecture.md` (full 4-layer model), `references/infisical.md` (Infisical setup), `references/vault-guide.md` (age vault fallback)

---

## Profile Gate (MANDATORY First Step)

Check for a profile before any operation. No profile means no server inventory, no preferences, no logging path.

```bash
${SKILL_DIR}/../admin/scripts/test-admin-profile.sh
```

Returns JSON: `{"exists":true|false,"path":"...","device":"...","platform":"..."}`

If `exists: false` — stop and hand off to **admin** skill for `/setup-profile`. Do not proceed without a profile.

Full details: `references/profile-gate.md`

---

## Task Qualification (MANDATORY)

- If the task is **local OS/MCP/skills**, stop and hand off to **admin**.
- If the task is **remote infrastructure**, continue.
- If ambiguous, ask a clarifying question before proceeding.

## Task Routing

| Task | Reference |
|------|-----------|
| Server inventory | Server Operations (use profile.servers) |
| OCI provisioning | **→ Use oci skill** |
| Hetzner provisioning | **→ Use hetzner skill** |
| Linode provisioning | **→ Use linode skill** |
| DigitalOcean provisioning | **→ Use digital-ocean skill** |
| Contabo provisioning | **→ Use contabo skill** |
| Coolify deployment | **→ Use coolify skill** |
| KASM deployment | **→ Use kasm skill** |
| Secrets / Infisical setup | **→ Use admin skill** |
| **Local machine tasks** | **→ Use admin skill** |

## Server Operations

Use `profile.servers[]` for inventory; do not maintain a separate list. Profile is the source of truth.

## Provisioning Workflow (5 Steps)

1. Choose provider
2. Load secrets via `secrets` CLI (provider API key)
3. Run provider workflow (use the dedicated provider skill)
4. Update `profile.servers[]` and `profile.deployments{}`
5. Log the operation via `log_admin_event`

## Logging (MANDATORY)

Log every operation. Logging scripts live in the admin sibling skill.

```bash
source "${SKILL_DIR}/../admin/scripts/log-admin-event.sh"
log_admin_event "Provisioned Hetzner server hzn-01-203-42" "OK"
log_admin_event "OCI provisioning failed: OUT_OF_HOST_CAPACITY" "ERROR"
```

Levels: `OK` (success), `INFO`, `WARN`, `ERROR`

---

## Architecture

### Relationship to Admin

devops is a satellite of admin. It depends on admin for:
- **Profile gate** (`test-admin-profile.sh`) — mandatory first step
- **Logging** (`log-admin-event.sh`) — mandatory operation logging
- **Secrets** (`secrets` CLI) — provider API key retrieval with fallback chain
- **Profile data** (`profile.servers[]`, `profile.deployments{}`) — server inventory

### Sibling Skill Resolution

```
plugins/admin-devops/
  skills/
    admin/      ← core (scripts, secrets, logging live here)
    devops/     ← this skill (references admin scripts via ../admin/)
    oci/        ← provider skill
    hetzner/    ← provider skill
    ...
```

### Agent Roster

| Agent | Model | Role |
|---|---|---|
| server-provisioner | sonnet | Cloud VM provisioning via provider CLIs |
| deployment-coordinator | sonnet | End-to-end app deployment (Coolify/KASM) |

Both agents run the profile gate as their first step.

---

## Scripts / References

- Provider skills: sibling skills under this plugin (oci, hetzner, coolify, etc.)
- Inventory format spec: `references/INVENTORY_FORMAT.md`
- Deployment workflows: `references/DEPLOYMENT_WORKFLOWS.md`
- Troubleshooting: `references/TROUBLESHOOTING.md`

• SKILL.md 6 KB
• assets/agent-devops.env.template 4 KB
• assets/devops-registry.json 2 KB
• assets/env-spec.txt 1 KB
• assets/env-template 9 KB
• assets/provider-infrastructure-template 9 KB
• references/DEPLOYMENT_WORKFLOWS.md 3 KB
• references/EXAMPLE_INVENTORY.md 2 KB
• references/INVENTORY_FORMAT.md 4 KB
• references/PROVIDER_DISCOVERY.md 2 KB
• references/TROUBLESHOOTING.md 2 KB
• references/profile-gate.md 2 KB