daac279fa4
- Remove redundant documentation (now in README files) - Add plugin status section - Reference agents/README.md and workflows/README.md - Document skill resources pattern (scripts/ + references/) - Add hooks documentation - Clarify that workflows are design docs, not auto-executed - Add component-registry.json to state files table - Reduce overall length while maintaining key information 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
149 lines
4.9 KiB
Markdown
149 lines
4.9 KiB
Markdown
# 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
|
|
|
|
## 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
|