From daac279fa45f61ad17d75f3bfc0b6665ee1edc9b Mon Sep 17 00:00:00 2001 From: OpenCode Test Date: Thu, 1 Jan 2026 02:35:44 -0800 Subject: [PATCH] Streamline CLAUDE.md to reflect plugin structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 180 ++++++++++++++++++++++++------------------------------ 1 file changed, 80 insertions(+), 100 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ba27a6d..fde6bc5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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: → Reusable capability - ├─→ invokes: workflow: → Multi-step process - └─→ modifies: state: → 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