will/claude-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Streamline CLAUDE.md to reflect plugin structure

Browse Source 
- 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>
This commit is contained in:
OpenCode Test
2026-01-01 02:35:44 -08:00
parent 76f41d2634
commit daac279fa4
1 changed files with 80 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
CLAUDE.md
View File

@@ -2,6 +2,10 @@
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
```
@@ -20,113 +24,101 @@ Personal Assistant (Opus) - user interface + ultimate oversight
└── 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 |
|------|---------|--------|
| `~/.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 |
| `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
- 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
- See `state/model-policy.json` for details
### Autonomy Enforcement
- Default: conservative (confirm all write operations)
- Session overrides apply only for current session
- Forbidden actions always blocked regardless of autonomy level
- Session overrides in `state/sysadmin/session-autonomy.json`
- See `state/autonomy-levels.json` for level definitions
## Directory Structure
## 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)
```
~/.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
skills/skill-name/
├── SKILL.md # Main instructions
├── scripts/ # Executable helpers
│ ├── action1.py
│ └── action2.py
└── references/ # Documentation
└── patterns.md
```
## Conventions
Reference scripts from SKILL.md: `Run scripts/action1.py [args]`
- **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
### Agent File Format
## 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
```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]
```
## 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
@@ -134,35 +126,23 @@ User types /command
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
invokes: skill:skill-name
---
```
### Skill Structure
## Hooks
Skills use a subdirectory with `SKILL.md`:
Hooks in `hooks/hooks.json` run on Claude Code events:
```
skills/
└── skill-name/
└── SKILL.md
```
| Event | Use For |
|-------|---------|
| `SessionStart` | Load context, initialize state |
| `PostToolUse[Write\|Edit]` | Format code, run linters |
| `PreCompact` | Save summaries before context compaction |
### Workflow Format
## Notes
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
```
- 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