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)
    ├── programmer-orchestrator (Opus) - code development
    │   ├── code-planner (Sonnet)
    │   ├── code-implementer (Sonnet)
    │   └── code-reviewer (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 |
| `~/.claude/state/kb.json` | Shared knowledge base | 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
│   ├── programmer/             # Programmer 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:

```markdown
---
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

```yaml
---
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:

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