claude-code/CLAUDE.md

Claude Code Shared Memory

This file contains shared conventions, state file locations, and instructions that apply to all agents.

Agent System Architecture

Personal Assistant (Opus) - user interface + ultimate oversight
└── 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)

Shared State Files

All agents MUST read and follow the processes defined in these files:

File	Purpose	Writer
~/.claude/state/system-instructions.json	Central process definitions	master-orchestrator
~/.claude/state/future-considerations.json	Deferred features/decisions	master-orchestrator
~/.claude/state/model-policy.json	Model selection rules	master-orchestrator
~/.claude/state/autonomy-levels.json	Autonomy definitions	master-orchestrator
~/.claude/state/sysadmin/session-autonomy.json	Per-session overrides	user/CLI
~/.claude/state/personal-assistant-preferences.json	PA persistent config	master-orchestrator
~/.claude/state/personal-assistant/session-context.json	Session context override	user/CLI
~/.claude/state/personal-assistant/general-instructions.json	User memory	personal-assistant

Key Processes

Model Selection

• Start with lowest capable model (haiku → sonnet → opus)
• Escalate only when task complexity requires
• Log model usage for cost analysis

Cross-Agent Communication

• All cross-agent requests route through master orchestrator
• Master validates, routes, and logs all requests
• Personal assistant has ultimate escalation authority
• No direct agent-to-agent communication

Autonomy Enforcement

• Default: conservative (confirm all write operations)
• Session overrides apply only for current session
• Forbidden actions always blocked regardless of autonomy level

Directory Structure

~/.claude/
├── CLAUDE.md                    # This file - shared memory
├── agents/                      # Agent definitions (Markdown + YAML frontmatter)
├── state/                       # Shared state files (JSON)
│   ├── sysadmin/               # Linux sysadmin agent state
│   └── personal-assistant/     # Personal assistant agent state
├── skills/                      # Skill definitions
├── commands/                    # Slash command definitions
├── workflows/                   # Workflow definitions
└── automation/                  # Managed scripts and automation

Conventions

• Agent files: Markdown with YAML frontmatter
• Data files: JSON format
• Logs: JSON lines format where applicable
• No duplication: Information lives in one place. CLAUDE.md = overview, state JSON = details

Maintenance

See system-instructions.json for detailed maintenance procedures.

Key rules:

• master-orchestrator maintains agents/, state/, skills/, commands/, workflows/
• linux-sysadmin maintains state/sysadmin/, automation/
• personal-assistant maintains state/personal-assistant/general-instructions.json
• When adding/removing agents: update agent file, supervisor's hierarchy, this diagram, and model-policy.json

Agent File Format

All agents must use this format:

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

[Agent instructions in Markdown]

Component Types and Formats

Format Conventions

Component	Format	Location	Purpose
State	JSON	state/	Machine-readable configuration
Agents	Markdown + YAML frontmatter	agents/	Agent personas and instructions
Commands	Markdown + YAML frontmatter	commands/	User-invocable shortcuts
Skills	SKILL.md in subdirectory	skills/	Reusable capabilities
Workflows	YAML	workflows/	Multi-step automation

Component Relationships

User types /command
       │
       ▼
   Command (thin wrapper)
       │
       ├─→ invokes: skill:<name>     → Reusable capability
       ├─→ invokes: workflow:<path>  → Multi-step process
       └─→ modifies: state:<path>    → Configuration change

Command Frontmatter

---
name: command-name
description: What this command does
aliases: [alias1, alias2]
invokes: skill:skill-name           # OR
invokes: workflow:category/name     # OR
modifies: state:category/file
---

Skill Structure

Skills use a subdirectory with SKILL.md:

skills/
└── skill-name/
    └── SKILL.md

Workflow Format

Workflows use pure YAML for step-based automation:

name: workflow-name
description: What this workflow does
trigger:
  - schedule: "0 */6 * * *"
  - manual: true
steps:
  - name: step-name
    agent: agent-name
    task: |
      Task description