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 with rebase (after user approval):

   git checkout main && git rebase feature/branch-name && git push
   

Notes:

• Use rebase, not merge commits
• Stash uncommitted state files before switching branches
• Delete feature branches after merge
• Gitea token stored at ~/.config/gitea-token

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

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

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