Admin - Context-Aware DevOps Companion

Purpose: Read your device profile, adapt instructions to your setup, route to specialist skills.

Core Value

When a GitHub repo says pip install package, this skill knows you prefer uv and suggests uv pip install package instead.

⚠️ STEP 0: Detect Environment (MANDATORY FIRST)

Before ANY operation, run this detection to find the profile:

# Detect environment and set ADMIN_ROOT
if grep -qi microsoft /proc/version 2>/dev/null; then
    # WSL - profile is on Windows side
    WIN_USER=$(cmd.exe /c "echo %USERNAME%" 2>/dev/null | tr -d '\r')
    ADMIN_ROOT="/mnt/c/Users/$WIN_USER/.admin"
    ENV_TYPE="wsl"
elif [[ "$OS" == "Windows_NT" || -n "$MSYSTEM" ]]; then
    # Git Bash on Windows
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="windows-gitbash"
elif [[ "$(uname -s)" == "Darwin" ]]; then
    # macOS
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="macos"
else
    # Native Linux
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="linux"
fi

HOSTNAME=$(hostname)
PROFILE_PATH="$ADMIN_ROOT/profiles/$HOSTNAME.json"

echo "Environment: $ENV_TYPE"
echo "Admin Root:  $ADMIN_ROOT"
echo "Profile:     $PROFILE_PATH"
echo "Exists:      $(test -f "$PROFILE_PATH" && echo 'YES' || echo 'NO')"

Critical Path Rules

Common Mistake

❌ WRONG: Assume ~/.admin always works

# This FAILS in WSL because ~ is /home/wsladmin, not Windows
ls ~/.admin/profiles/  # Empty or doesn't exist

✅ RIGHT: Detect environment first, then find profile

# In WSL, profile is on Windows side
ls /mnt/c/Users/Owner/.admin/profiles/  # Found!

Quick Start: After Detection

Bash (WSL/Linux/macOS)

# After running detection above
source /path/to/admin/scripts/load-profile.sh
load_admin_profile "$PROFILE_PATH"
show_admin_summary

PowerShell (Windows)

. scripts/Load-Profile.ps1
Load-AdminProfile -Export
Show-AdminSummary

The Key Innovation: Preferences

"preferences": {
  "python": { "manager": "uv", "reason": "Fast, modern, replaces pip+venv" },
  "node": { "manager": "npm", "reason": "Default, bun for speed" },
  "packages": { "manager": "scoop", "reason": "Portable installs" }
}

Always check preferences before suggesting commands.

Adaptation Examples

Profile Sections Quick Reference

Routing Rules

Tool Installation Workflow

1. Detect environment (Step 0 above)
2. Load profile: load_admin_profile "$PROFILE_PATH"
3. Check if installed: jq '.tools.{name}.present' "$PROFILE_PATH"
4. If not installed:
   • Check preferred manager: jq '.preferences.packages.manager' "$PROFILE_PATH"
   • Construct install command for that manager
5. After install: Update profile

Server Operations Workflow

1. List servers: jq '.servers[]' "$PROFILE_PATH"
2. Get SSH details:
   bashCopy

   SERVER=$(jq '.servers[] | select(.id == "cool-two")' "$PROFILE_PATH")
   

3. Handle path conversion (WSL needs to convert Windows paths):
   bashCopy

   KEY_PATH=$(echo "$SERVER" | jq -r '.keyPath')
   # Convert C:/Users/... to /mnt/c/Users/...
   if [[ "$KEY_PATH" == *":"* ]]; then
       DRIVE=$(echo "$KEY_PATH" | cut -c1 | tr '[:upper:]' '[:lower:]')
       REST=$(echo "$KEY_PATH" | cut -c3- | sed 's|\\|/|g')
       KEY_PATH="/mnt/$DRIVE$REST"
   fi
   

First-Run Setup

If profile doesn't exist:

Windows (PowerShell):

.\scripts\Initialize-AdminProfile.ps1

WSL/Linux - Profile should be created from Windows side first, then accessed from WSL via /mnt/c/...

Capability Checks

# Load profile first, then check
HAS_DOCKER=$(jq -r '.capabilities.hasDocker' "$PROFILE_PATH")
HAS_WSL=$(jq -r '.capabilities.hasWsl' "$PROFILE_PATH")

if [[ "$HAS_DOCKER" == "true" ]]; then
    docker info
fi

References

• references/device-profiles.md - Profile management details
• references/routing-guide.md - Detailed routing logic
• references/first-run-setup.md - Initial setup flow
• references/cross-platform.md - Windows ↔ WSL coordination

Scripts

Related Skills