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)

{
  "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

{
  "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:

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

[Agent instructions in Markdown]