claude-code/CLAUDE.md

# Claude Code Shared Memory

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

## Plugin Status

This configuration can be installed as a plugin via `.claude-plugin/plugin.json`.

## 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)
```

See `agents/README.md` for details on agent files and execution.

## Directory Structure

```
~/.claude/
├── .claude-plugin/              # Plugin manifest
│   └── plugin.json
├── CLAUDE.md                    # This file - shared memory
├── hooks/                       # Event handlers
│   └── hooks.json
├── agents/                      # Agent definitions
│   └── README.md
├── skills/                      # Skill definitions
│   └── skill-name/
│       ├── SKILL.md
│       ├── scripts/             # Executable helpers
│       └── references/          # Documentation
├── commands/                    # Slash command definitions
├── workflows/                   # Workflow definitions (design docs)
│   └── README.md
├── state/                       # Shared state files (JSON)
│   ├── sysadmin/
│   ├── programmer/
│   └── personal-assistant/
├── automation/                  # Managed scripts
└── mcp/                         # MCP integrations
```

## Shared State Files

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

| File | Purpose | Writer |
|------|---------|--------|
| `state/system-instructions.json` | Central process definitions | master-orchestrator |
| `state/future-considerations.json` | Deferred features/decisions | master-orchestrator |
| `state/model-policy.json` | Model selection rules | master-orchestrator |
| `state/autonomy-levels.json` | Autonomy definitions | master-orchestrator |
| `state/component-registry.json` | Skills, commands, agents routing | master-orchestrator |
| `state/personal-assistant-preferences.json` | PA persistent config | personal-assistant |
| `state/personal-assistant/general-instructions.json` | User memory | personal-assistant |
| `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
- See `state/model-policy.json` for details

### Autonomy Enforcement
- Default: conservative (confirm all write operations)
- Session overrides in `state/sysadmin/session-autonomy.json`
- See `state/autonomy-levels.json` for level definitions

### Git Workflow
This repo uses Gitea (not GitHub). Follow this workflow:

1. **Create feature branch**: `git checkout -b feature/descriptive-name`
2. **Commit work**: Make atomic commits with clear messages
3. **Rebase onto main**: `git rebase origin/main`
4. **Push branch**: `git push -u origin feature/branch-name`
5. **Create PR**: `~/.claude/automation/gitea-pr.sh "PR Title" "Description"`
6. **Merge** (after user approval): `~/.claude/automation/gitea-merge.sh`
   - Rebases onto main and pushes
   - Deletes local and remote branch
   - Closes PR via API

Notes:
- Gitea token stored at `~/.config/gitea-token`

### PR Review Policy

| Repo Type | Review Process |
|-----------|----------------|
| ~/.claude | Linting/validation only (shellcheck, JSON/YAML syntax, Python syntax) |
| Code repos | Full review via code-reviewer agent (Sonnet) before user approval |

### Gitea API Commands

```bash
# List all PRs
curl -s -H "Authorization: token $(cat ~/.config/gitea-token)" \
  "https://gitea-http.taildb3494.ts.net/api/v1/repos/will/claude-code/pulls?state=all"

# Close a PR (after rebase merge)
curl -s -X PATCH \
  -H "Authorization: token $(cat ~/.config/gitea-token)" \
  -H "Content-Type: application/json" \
  -d '{"state":"closed"}' \
  "https://gitea-http.taildb3494.ts.net/api/v1/repos/will/claude-code/pulls/{PR_NUMBER}"
```

## Component Formats

| Component | Format | Location |
|-----------|--------|----------|
| **Agents** | Markdown + YAML frontmatter | `agents/` |
| **Skills** | SKILL.md + scripts/ + references/ | `skills/` |
| **Commands** | Markdown + YAML frontmatter | `commands/` |
| **Workflows** | YAML (design docs, not auto-executed) | `workflows/` |
| **State** | JSON | `state/` |
| **Hooks** | JSON | `hooks/` |

### Skill Structure (Resources Pattern)

```
skills/skill-name/
├── SKILL.md                    # Main instructions
├── scripts/                    # Executable helpers
│   ├── action1.py
│   └── action2.py
└── references/                 # Documentation
    └── patterns.md
```

Reference scripts from SKILL.md: `Run scripts/action1.py [args]`

### Agent File Format

```yaml
---
name: agent-name
description: When to use this agent
model: sonnet|opus|haiku
tools: Tool1, Tool2, Tool3
allowed-tools: Tool1, Tool2   # Optional: restrict tools
---

[Agent instructions in Markdown]
```

### Command Frontmatter

```yaml
---
name: command-name
description: What this command does
aliases: [alias1, alias2]
invokes: skill:skill-name
---
```

## Hooks

Hooks in `hooks/hooks.json` run on Claude Code events:

| Event | Use For |
|-------|---------|
| `SessionStart` | Load context, initialize state |
| `PostToolUse[Write\|Edit]` | Format code, run linters |
| `PreCompact` | Save summaries before context compaction |

## Notes

- Workflows are **design documents**, not auto-executed (see `workflows/README.md`)
- Agents are **personas**, not auto-spawned (see `agents/README.md`)
- Use `component-registry.json` for routing decisions
- No duplication: CLAUDE.md = overview, state JSON = details