Admin

Admin - Local Machine Companion (Alpha)

Script path resolution: When Claude Code loads this file, it provides the full path. All scripts/ references below are relative to this file's directory. Derive SKILL_DIR from this file's path and prepend it when running scripts (e.g., if loaded from /path/to/skills/admin/SKILL.md, run /path/to/skills/admin/scripts/test-admin-profile.sh).

Profile Gate — Mandatory First Step

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

Bash (WSL/Linux/macOS):

scripts/test-admin-profile.sh

PowerShell (Windows):

pwsh -NoProfile -File "scripts/Test-AdminProfile.ps1"

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

If exists: false — stop and run the TUI setup interview before proceeding. Full details: references/profile-gate.md (discovery, TUI interview, create commands, troubleshooting).

Fallback: When Scripts Fail

If both bash and PowerShell test scripts fail (e.g., shell not available, permission denied, script missing from plugin cache), use native Claude tools to check directly:

1. Check satellite .env — Read ~/.admin/.env to get ADMIN_ROOT and ADMIN_DEVICE
2. Check profile JSON — Read $ADMIN_ROOT/profiles/$ADMIN_DEVICE.json
3. If both exist, proceed normally using the values read from these files
4. If neither exists, run the TUI setup interview (see references/profile-gate.md)

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 (v4.0 — 3-Project Split)

Secrets are organized across 3 Infisical projects by trust boundary, with folder hierarchies:

4-layer model: age key → vault (bootstrap) → Infisical Cloud (3 projects) → generated runtime files

URI-based access (new in v4.0):

resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN"
secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN

Legacy CLI (still works via fallback):

secrets HCLOUD_TOKEN          # Falls back through: generated/.env → Infisical → vault → .env

Runtime rendering: render-runtime.sh resolves all secretRefs/fileRefs from the profile and writes $ADMIN_ROOT/generated/.env for scripts that don't need live Infisical access.

Guides: references/secrets-architecture.md (full model), references/infisical.md (setup), references/vault-guide.md (fallback)

Architecture

Ecosystem Map

admin (core)
  ├── 9 satellite skills: devops, oci, hetzner, contabo, digital-ocean, vultr, linode, coolify, kasm
  ├── 7 agents: profile-validator, docs-agent, verify-agent, tool-installer, ops-bot, server-provisioner, deployment-coordinator
  ├── Profile system: ~/.admin/.env (satellite) → $ADMIN_ROOT/profiles/*.json (+ GitHub sync)
  └── Secrets: 3 Infisical projects (operator/runtime/customer) → vault (fallback) → .env (legacy)

Data Flow

Satellite .env (bootstrap)  →  profile.json (device config)  →  Agent decisions
        ↓                              ↓                              ↓
  ADMIN_ROOT, DEVICE,          tools, servers, prefs,          Session logs
  PLATFORM, SECRETS_BACKEND    secretRefs, fileRefs            (~/.admin/logs/)
        ↓                              ↓
  generated/.env (pre-rendered) → Infisical (3 projects) → vault.age → .env

• Satellite .env (~/.admin/.env): Per-device bootstrap. Points to ADMIN_ROOT, configures secrets backend.
• Root .env ($ADMIN_ROOT/.env): Bootstrap only (ADMIN_ROOT, ADMIN_DEVICE, ADMIN_PLATFORM, ADMIN_SECRETS_BACKEND).
• Profile JSON ($ADMIN_ROOT/profiles/{DEVICE}.json): Full device config with secretRefs (URI pointers) and fileRefs.
• Projects config ($ADMIN_ROOT/config/infisical-projects.json): Project slug → ID mapping.
• Generated ($ADMIN_ROOT/generated/.env, compat.env): Pre-resolved secrets for scripts that don't need live Infisical access.

Agent Roster

All agents run the profile gate as their first step. See references/agent-teams.md for collaboration patterns.

Satellite Dependency Graph

admin (core) ─── required by all satellites
  │
  ├── devops ─── required by provider + app skills
  │     │
  │     ├── oci, hetzner, contabo, digital-ocean, vultr, linode
  │     │        (provision servers)
  │     │              │
  │     └── coolify, kasm
  │           (deploy apps TO provisioned servers)
  │
  └── Profile system provides: server inventory, SSH keys, credentials (via vault)

• admin: Core profile, logging, tool installation. Required by everything.
• devops: Server inventory, SSH, deployment coordination. Required by all infrastructure.
• Provider skills (oci, hetzner, etc.): Provision VMs. Independent of each other.
• App skills (coolify, kasm): Deploy TO servers. Require a provisioned server from a provider skill.

Task Qualification (MANDATORY)

• If the task involves remote servers/VPS/cloud, stop and hand off to devops.
• If the task is local machine administration, continue.
• If ambiguous, ask a clarifying question before proceeding.

Task Routing

Profile-Aware Adaptation (Always Check Preferences)

• Python: preferences.python.manager (uv/pip/conda/poetry)
• Node: preferences.node.manager (npm/pnpm/yarn/bun)
• Packages: preferences.packages.manager (scoop/winget/choco/brew/apt)

Never suggest install commands without checking preferences first.

Package Installation Workflow (All Platforms)

1. Detect environment (Windows/WSL/Linux/macOS)
2. Load profile via profile gate
3. Check if tool already installed (profile.tools)
4. Use preferred package manager
5. Log the operation

Logging (MANDATORY)

Log every operation with the shared helpers.

Bash — params: MESSAGE LEVEL (INFO|WARN|ERROR|OK):

source scripts/log-admin-event.sh
log_admin_event "Installed ripgrep" "OK"

PowerShell — params: -Message -Level (INFO|WARN|ERROR|OK):

pwsh -NoProfile -File "scripts/Log-AdminEvent.ps1" -Message "Installed ripgrep" -Level OK

Note: There are no -Tool, -Action, -Status, or -Details parameters. Use -Message with a descriptive string.

Scripts / References

• Core scripts: scripts/ (profile, logging, issues, AGENTS.md)
• MCP scripts: scripts/mcp-*
• Skills registry scripts: scripts/skills-*
• References: references/*.md

Quick Pointers

• Cross-platform guidance: references/cross-platform.md
• Shell detection: references/shell-detection.md
• Device profiles: references/device-profiles.md
• PowerShell tips: references/powershell-commands.md
• Infisical secrets: references/infisical.md
• Remote profile sync: references/remote-profile.md
• devadmin onboarding/migration: references/devadmin-onboarding.md (run /adopt-devadmin)