claude-code/plans/shimmering-discovering-bonbon.md

# Linux Sysadmin Agent - Implementation Plan

## Overview

Create a Linux sysadmin agent for Arch Linux workstation management, integrated into a multi-agent system with a master orchestrator overseeing all agents.

## Architecture

```
~/.claude/
├── CLAUDE.md                          # Shared memory: conventions, state file locations
├── agents/
│   ├── master-orchestrator.md         # NEW: oversight layer (Opus)
│   ├── linux-sysadmin.md              # NEW: workstation agent (Sonnet)
│   ├── k8s-orchestrator.md            # UPDATE: add shared state awareness
│   ├── k8s-diagnostician.md           # UPDATE: add shared state awareness
│   ├── argocd-operator.md             # UPDATE: add shared state awareness
│   ├── prometheus-analyst.md          # UPDATE: add shared state awareness
│   └── git-operator.md                # UPDATE: add shared state awareness
├── state/
│   ├── system-instructions.json       # NEW: central process definitions
│   ├── future-considerations.json     # NEW: deferred features/decisions
│   ├── model-policy.json              # NEW: cost-efficient model selection rules
│   ├── autonomy-levels.json           # NEW: shared autonomy definitions
│   └── sysadmin/
│       └── session-autonomy.json      # NEW: per-session overrides
├── skills/
│   └── sysadmin-health/
│       └── SKILL.md                   # NEW: health check skill
├── commands/
│   └── sysadmin/
│       ├── health.md                  # NEW: /health slash command
│       └── update.md                  # NEW: /update slash command
├── workflows/
│   └── sysadmin/
│       ├── health-check.yaml          # NEW: scheduled workflow
│       └── system-update.yaml         # NEW: manual workflow
├── automation/
│   └── sysadmin/
│       └── scripts/                   # NEW: managed scripts directory
└── settings.json                      # UPDATE: remove non-standard agent fields
```

## Agent Hierarchy

```
Master Orchestrator (Opus) - monitor, coordinate, enforce
├── linux-sysadmin (Sonnet) - workstation management
├── k8s-orchestrator (Opus) - cluster management
│   ├── k8s-diagnostician (Sonnet)
│   ├── argocd-operator (Sonnet)
│   ├── prometheus-analyst (Sonnet)
│   └── git-operator (Sonnet)
├── network-agent (future)
└── personal-assistant (future)
```

## Linux Sysadmin Agent Specification

### Target Environment
- **OS**: Arch Linux (rolling release)
- **Package managers**: pacman, yay (AUR), homebrew
- **Init system**: systemd

### Responsibilities
- **System maintenance**: Package updates, cache cleanup, log rotation, orphan removal
- **Troubleshooting**: Analyze journalctl logs, diagnose failed services, identify bottlenecks
- **Configuration**: Manage systemd services, edit configs (with approval), dotfile awareness
- **Security**: Monitor failed logins, check firewall, identify vulnerable packages
- **Health reporting**: Disk, memory, CPU, swap, service status, pending updates

### Tools

**Safe (auto-execute):**
- `journalctl`, `systemctl status`, `pacman -Q*`, `yay -Q*`, `brew list`
- `df`, `free`, `top`, `ps`, `ip`, `ss`, `uname`, `lsblk`, `findmnt`
- `uptime`, `last`, `who`

**Confirm (require approval):**
- `pacman -S/R/Syu`, `yay -S/R`, `brew install/upgrade`
- `systemctl start/stop/restart/enable/disable`
- Config file edits, `ansible-playbook`

**Forbidden:**
- `rm -rf /`, `dd` on system disks, `chmod -R 777`
- Kernel parameter changes without explicit request
- Anything touching `/boot` without confirmation

### Autonomy Model

Default: **Conservative** (read-only, confirm all changes)

```json
{
  "levels": {
    "conservative": "Confirm all write operations",
    "moderate": "Auto-execute routine maintenance, confirm installs/removals",
    "trusted": "Auto-execute most operations, confirm only destructive"
  },
  "session_override": "~/.claude/state/sysadmin/session-autonomy.json"
}
```

## Master Orchestrator Specification

### Responsibilities
1. **Monitor**: Watch agent activity, detect anomalies, track pending approvals
2. **Coordinate**: Route cross-agent requests, prevent conflicts
3. **Enforce**: Validate autonomy rules, block forbidden actions, escalate to user
4. **Memory**: Maintain shared state files (all agents read, master writes)

### Cross-Agent Communication Flow
```
Agent A → Master Orchestrator → Agent B
                ↓
        (route, validate, log)
```

## Model Selection Policy

```json
{
  "opus": ["complex reasoning", "cross-agent coordination", "policy enforcement"],
  "sonnet": ["standard operations", "well-defined tasks", "routine automation"],
  "haiku": ["simple queries", "status checks", "log parsing", "data extraction"]
}
```

**Cost rules:**
1. Start with lowest capable model
2. Escalate only when task complexity requires
3. Agents may request model upgrade from orchestrator
4. Log model usage for cost analysis

## Multi-Subagent Delegation

Agents can delegate to multiple subagents:

- **Parallel**: Independent tasks run simultaneously
- **Sequential**: Dependent tasks run in order
- **Model override**: Request specific model per delegation

## Shared State Files

| File | Purpose | Writer |
|------|---------|--------|
| `system-instructions.json` | Central process definitions | master-orchestrator |
| `future-considerations.json` | Deferred features/decisions | master-orchestrator |
| `model-policy.json` | Model selection rules | master-orchestrator |
| `autonomy-levels.json` | Autonomy definitions | master-orchestrator |
| `session-autonomy.json` | Per-session overrides | user/CLI |

All agents MUST be aware of these files and follow the processes defined within.

## Implementation Steps

### Phase 1: Foundation
1. Create `state/system-instructions.json`
2. Create `state/future-considerations.json`
3. Create `state/model-policy.json`
4. Create `state/autonomy-levels.json`
5. Update `CLAUDE.md` with shared state locations

### Phase 2: Master Orchestrator
6. Create `agents/master-orchestrator.md` with YAML frontmatter

### Phase 3: Linux Sysadmin Agent
7. Create `agents/linux-sysadmin.md` with YAML frontmatter
8. Create `state/sysadmin/` directory structure

### Phase 4: Update Existing Agents
9. Update `agents/k8s-orchestrator.md` - add shared state awareness
10. Update `agents/k8s-diagnostician.md` - add shared state awareness
11. Update `agents/argocd-operator.md` - add shared state awareness
12. Update `agents/prometheus-analyst.md` - add shared state awareness
13. Update `agents/git-operator.md` - add shared state awareness

### Phase 5: Clean Settings
14. Update `settings.json` - remove non-standard `agents` field with `promptFile`

### Phase 6: Skills & Commands
15. Create `skills/sysadmin-health/SKILL.md`
16. Create `commands/sysadmin/health.md`
17. Create `commands/sysadmin/update.md`

### Phase 7: Workflows
18. Create `workflows/sysadmin/health-check.yaml`
19. Create `workflows/sysadmin/system-update.yaml`
20. Create `automation/sysadmin/scripts/` directory

## Future Considerations

Track in `state/future-considerations.json`:

| ID | Category | Description | Priority |
|----|----------|-------------|----------|
| fc-001 | infrastructure | Prometheus node_exporter + Alertmanager for workstation | medium |
| fc-002 | agent | Network admin agent | medium |
| fc-003 | agent | Personal assistant agent | medium |
| fc-004 | integration | External LLM integration (non-Claude models) | low |
| fc-005 | optimization | Model usage logging and cost tracking | medium |
| fc-006 | design | Revisit slash commands design | low |
| fc-007 | optimization | Optimize document structure/format | low |

## Critical Files to Modify

- `~/.claude/agents/k8s-orchestrator.md`
- `~/.claude/agents/k8s-diagnostician.md`
- `~/.claude/agents/argocd-operator.md`
- `~/.claude/agents/prometheus-analyst.md`
- `~/.claude/agents/git-operator.md`
- `~/.claude/settings.json`
- `~/.claude/CLAUDE.md`

## Agent File Format (Claude Code Required)

All agents must use Markdown with YAML frontmatter:

```markdown
---
name: agent-name
description: When to use this agent
model: sonnet|opus|haiku
tools: Tool1, Tool2, Tool3
---

[Agent instructions in Markdown]
```