claude-code-extensions

<!-- OPENSPEC:START -->
# OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding

Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

<!-- OPENSPEC:END -->

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Purpose

This repository is a **working project for creating and managing Claude Code extensions**: agents, hooks, commands, skills, and output styles. When users request new extensions, you should create them here using the patterns and templates defined below.

### Extension Creation

**IMPORTANT**: When creating extensions, use the appropriate tool:

**For Agents**: Use `meta-agent` at `.claude/agents/meta-agent.md`
- Fetches the latest Claude Code documentation
- Generates complete, production-ready agent files
- Writes directly to `.claude/agents/`

**For Skills**: Use the `/create-skill` command
- Syntax: `/create-skill <name> "<description>" [doc-urls...]`
- Uses the skill skeleton template at `templates/skill-skeleton/`
- Generates SKILL.md and README.md with proper structure
- Evaluates and creates optional directories (templates/, scripts/, references/)
- Writes directly to `.claude/skills/`

## Project Structure

``` md
.claude/
├── settings.json          # Hook configuration (all lifecycle events registered)
├── agents/                # Organized by category: core, orchestrators, universal, specialized
├── hooks/                 # Python scripts for lifecycle events
│   └── utils/            # Shared utilities (llm/, tts/)
├── commands/             # Reusable slash commands
└── skills/               # Model-invoked capabilities (flat structure)

templates/
└── skill-skeleton/       # Starter template for new skills

docs/claude-code/         # Official Claude Code documentation
├── sub-agents.md
├── hooks.md
├── hooks-reference.md
├── commands-reference.md
├── agent-skills.md
└── output-styles.md

logs/                     # Runtime logs (generated by hooks)
```

## Plugin Architecture

This repository supports **dual-mode installation**: as modular Claude Code plugins OR as standalone extensions.

### Multi-Plugin Structure

The repository provides **5 focused plugins** (Phase 1), not a monolithic bundle:

```
.claude-plugin/
├── marketplace.json                    # Marketplace configuration
└── plugins/
    ├── cce-core/
    │   └── plugin.json                # Core plugin manifest
    ├── cce-kubernetes/
    │   └── plugin.json                # Kubernetes plugin manifest
    ├── cce-cloudflare/
    │   └── plugin.json                # Cloudflare plugin manifest
    ├── cce-esphome/
    │   └── plugin.json                # ESPHome plugin manifest
    └── cce-web-react/
        └── plugin.json                # React plugin manifest
```

**Key Principle**: Users install only what they need for their tech stack.

### Dual-Mode Architecture

```
┌─────────────────────────────────────────┐
│  claude-code-extensions Repository      │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Plugin Mode  │  │ Standalone Mode │ │
│  ├──────────────┤  ├─────────────────┤ │
│  │ Uses:        │  │ Uses:           │ │
│  │ • .claude-   │  │ • .claude/      │ │
│  │   plugin/    │  │   directly      │ │
│  │ • Namespaced │  │ • Unprefixed    │ │
│  │   commands   │  │   commands      │ │
│  │   /cce:*     │  │   /git-commit   │ │
│  │   /cce-k8s:* │  │   /prime        │ │
│  │ • Plugin     │  │ • Manual        │ │
│  │   installer  │  │   installer     │ │
│  └──────────────┘  └─────────────────┘ │
│                                         │
│  Both modes use the SAME source files  │
│  in .claude/agents/, .claude/hooks/,   │
│  .claude/commands/, .claude/skills/    │
└─────────────────────────────────────────┘
```

### Hook Path Resolution

To support both modes, all hooks use **fallback path syntax**:

```json
{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "uv run \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"/.claude/hooks/pre_tool_use.py"
      }]
    }]
  }
}
```

**How it works**:
- **Plugin mode**: `${CLAUDE_PLUGIN_ROOT}` is set → evaluates to plugin cache path
- **Standalone mode**: `${CLAUDE_PLUGIN_ROOT}` is unset → falls back to `$CLAUDE_PROJECT_DIR`

### Command Namespacing

| Installation Mode | Namespace | Example Commands |
|-------------------|-----------|------------------|
| **Plugin: cce-core** | `/cce:*` | `/cce:git-commit`, `/cce:prime` |
| **Plugin: cce-kubernetes** | `/cce-kubernetes:*` | `/cce-kubernetes:health` |
| **Standalone** | Unprefixed | `/git-commit`, `/prime`, `/k8s-health` |

**No code changes required** - Claude Code handles namespacing automatically based on plugin configuration.

### Testing in Plugin Mode

```bash
# 1. Validate plugin structure
/plugin validate .

# 2. Install from local path for testing
/plugin marketplace add /path/to/claude-code-extensions
/plugin install cce-core@cce-marketplace

# 3. Test commands with namespace
/cce:git-commit
/cce:prime

# 4. Verify agents appear
/agents  # Should show cce-core agents

# 5. Update plugin after changes
/plugin update cce-core
```

### Plugin Manifest Structure

Each plugin manifest (`.claude-plugin/plugins/*/plugin.json`) defines:

```json
{
  "name": "cce-core",
  "version": "1.0.0",
  "description": "Essential Claude Code extensions",
  "author": { "name": "Claude Code Extensions Contributors" },
  "homepage": "https://github.com/nodnarbnitram/claude-code-extensions",
  "repository": "https://github.com/nodnarbnitram/claude-code-extensions",
  "license": "MIT",
  "keywords": ["core", "essential", "hooks"],
  "agents": [
    "./.claude/agents/core/",
    "./.claude/agents/orchestrators/",
    "./.claude/agents/universal/",
    "./.claude/agents/meta-agent.md"
  ],
  "skills": [
    "./.claude/skills/commit-helper/",
    "./.claude/skills/code-reviewer/"
  ],
  "commands": [
    "./.claude/commands/git-commit.md",
    "./.claude/commands/prime.md"
  ],
  "hooks": "./.claude/settings.json"
}
```

**Custom paths** specify exact agent/skill/command locations - multiple plugins can reference subdirectories under `.claude/`.

## Creating Agents

Agents are Markdown files with YAML frontmatter stored in `.claude/agents/` (project) or `~/.claude/agents/` (user).

### Agent File Format

```markdown
---
name: agent-name
description: When this agent should be invoked (be specific and action-oriented)
tools: Read, Grep, Glob, Bash  # Optional - omit to inherit all tools
---

# Agent System Prompt

Your agent's instructions go here. Be specific about:
- The agent's role and expertise
- When it should be used (include "MUST BE USED" or "use PROACTIVELY" for auto-delegation)
- Step-by-step workflow
- Expected output format
- Delegation patterns to other agents
```

### Organization Structure

Organize agents in subdirectories by category (optional but recommended):

- **`core/`**: Quality/analysis agents
- **`orchestrators/`**: Coordination agents
- **`universal/`**: Framework-agnostic agents
- **`specialized/<tech>/`**: Framework-specific agents

### Key Principles

1. **Single responsibility**: Each agent focuses on one domain
2. **Explicit triggers**: Use "MUST BE USED" in descriptions for proactive delegation
3. **Tool restrictions**: Limit tools to what's needed (improves security and focus)
4. **Delegation patterns**: Orchestrators delegate; specialists implement
5. **Output formats**: Define structured output when reports/analysis are needed

## Creating Hooks

Hooks are shell commands executed at lifecycle events. Python hooks use `uv run --script` for dependency management.

### Hook Lifecycle Events

- **SessionStart**: When Claude Code starts/resumes
- **UserPromptSubmit**: Before Claude processes user input
- **PreToolUse**: Before any tool executes (can block)
- **PostToolUse**: After tool completes
- **PreCompact**: Before context compaction
- **SubagentStop**: When subagent completes
- **Stop**: When main agent finishes responding
- **Notification**: When Claude Code sends notifications

### Python Hook Template

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "python-dotenv",
# ]
# ///

import json
import sys
from pathlib import Path

def main():
    try:
        # Read JSON input from stdin
        input_data = json.load(sys.stdin)

        # Extract relevant fields
        # For PreToolUse/PostToolUse: tool_name, tool_input
        # For UserPromptSubmit: session_id, prompt
        # For SessionStart: session_id, source

        # Your hook logic here

        # Exit codes:
        # 0 = success, continue
        # 2 = block operation, show error to Claude
        sys.exit(0)

    except Exception:
        # Always fail gracefully
        sys.exit(0)

if __name__ == '__main__':
    main()
```

### Register Hooks

Use `/hooks` command or edit `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre_tool_use.py"
          }
        ]
      }
    ]
  }
}
```

### Hook Patterns from This Repository

1. **Logging pattern**: All hooks append JSON to `logs/<hook_name>.json`
2. **Safety checks**: `pre_tool_use.py` includes patterns for blocking dangerous commands
3. **Context loading**: `session_start.py` can inject git status, project context files, GitHub issues
4. **Graceful failure**: Always `sys.exit(0)` on errors to prevent blocking Claude Code

## Creating Commands

Commands are Markdown files that define reusable prompts, stored in `.claude/commands/` (project) or `~/.claude/commands/` (user).

### Command File Format

```markdown
---
description: Brief description shown in /help
argument-hint: [arg1] [arg2]  # Optional
allowed-tools: Bash(git add:*), Bash(git status:*)  # Optional
model: claude-3-5-haiku-20241022  # Optional
---

# Command Instructions

Your prompt goes here. Use:
- $ARGUMENTS for all arguments
- $1, $2, $3 for individual arguments
- @file/path for file references
- !`bash command` for executed commands (requires allowed-tools)
```

### Example Command

```markdown
---
description: Review PR and create commit
argument-hint: [pr-number]
allowed-tools: Bash(git:*)
---

Review PR #$1 and create a git commit:

1. Check current git status: !`git status`
2. Review changes: !`git diff HEAD`
3. Create commit following repo conventions
```

## Creating Output Styles

Output styles modify Claude Code's system prompt to change its behavior and personality. Stored in `.claude/output-styles/` (project) or `~/.claude/output-styles/` (user).

### Output Style Format

```markdown
---
name: Style Name
description: Brief description of what this style does
---

# Custom System Prompt

You are an interactive CLI tool that helps users with [specific purpose].

## Behaviors

[Define specific behaviors, tone, output format]
```

### Key Differences

- **Output Styles**: Modify main agent's system prompt (affect all interactions)
- **Agents**: Separate context for specific tasks
- **Commands**: Reusable prompts (stored user messages)

## Creating Skills

Skills are model-invoked capabilities that Claude autonomously discovers and uses. Unlike slash commands (user-invoked), skills activate based on task context and description matching.

### Skill Directory Structure

Skills are stored in `.claude/skills/skill-name/` (project) or `~/.claude/skills/skill-name/` (user). Each skill is a directory containing at minimum a `SKILL.md` file.

```
.claude/skills/
└── skill-name/
    ├── SKILL.md        # Required - main instructions
    ├── README.md       # Optional - auto-trigger keywords
    ├── scripts/        # Optional - automation scripts
    ├── references/     # Optional - supporting docs
    └── assets/         # Optional - templates, configs
```

### SKILL.md Format

```yaml
---
name: skill-name
description: What it does AND when to use it (include trigger keywords)
allowed-tools: Read, Grep, Glob  # Optional - restricts tool access
---

# Skill Title

## Instructions

Step-by-step guidance for Claude.

## Best Practices

Key patterns and guidelines.

## Example

Concrete usage examples.
```

### Skill Skeleton Template

Use `templates/skill-skeleton/` as a starter for new skills:

```bash
# Manual creation
cp -r templates/skill-skeleton .claude/skills/my-skill
# Then edit SKILL.md with your content

# Or use the skill-creator agent
> Use the skill-creator to create a skill for [purpose]
```

### Description Best Practices

The `description` field is critical for discovery. Include:
- What the skill does
- When Claude should use it
- Specific keywords users would mention

**Good:**
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
```

**Bad:**
```yaml
description: Helps with documents
```

### Optional README.md

For complex skills, add a README.md with auto-trigger keywords:

```markdown
## Auto-Trigger Keywords

### Primary Keywords
- pdf extraction
- form filling
- merge pdf

### Secondary Keywords
- document processing
- acrobat

### Error Pattern Keywords
- "Unable to read PDF"
- "Form field not found"
```

### Tool Restrictions

Use `allowed-tools` for security-sensitive skills:

```yaml
# Read-only skill
allowed-tools: Read, Grep, Glob

# No tool restrictions (inherits all)
# Simply omit the allowed-tools field
```

### Key Principles

1. **Flat structure**: No category subdirectories (skills are discovered by description)
2. **Specific descriptions**: Include what AND when with trigger keywords
3. **Progressive disclosure**: Claude loads additional files only when needed
4. **Model-invoked**: Skills activate automatically based on context
5. **Tool restrictions**: Use `allowed-tools` for read-only or limited-scope skills

For detailed guidance, see `docs/claude-code/agent-skills.md`.

## Development Workflow

### Testing Hooks Locally

```bash
# Create test input
echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' > test.json

# Test hook
uv run ./.claude/hooks/pre_tool_use.py < test.json
echo $?  # Check exit code
```

### Enabling/Disabling Safety Checks

The `pre_tool_use.py` hook has:
- `.env` file blocking: **ENABLED** (lines 93-96)
- Dangerous `rm` command blocking: **ENABLED** (lines 103-105)

Comment/uncomment these blocks to adjust safety policies.

### Plugin Validation and Testing

When working with plugins, validate structure and test in both modes:

```bash
# Validate all plugin manifests
/plugin validate .

# Test plugin mode installation (local)
/plugin marketplace add /path/to/claude-code-extensions
/plugin install cce-core@cce-marketplace
/plugin install cce-kubernetes@cce-marketplace

# Test commands with namespaces
/cce:git-commit
/cce-kubernetes:health

# Verify agents loaded
/agents  # Should show plugin agents

# Test standalone mode (existing workflow)
./install_extensions.py install --dry-run ~/test-project
./install_extensions.py install ~/test-project
cd ~/test-project && claude
> /git-commit  # Should work unprefixed
```

**Critical**: Always test both modes to ensure backward compatibility.

### Best Practices

1. **Version control agents/commands**: Check `.claude/agents/` and `.claude/commands/` into git
2. **Document decisions**: Add comments in hook scripts explaining safety patterns
3. **Test incrementally**: Test each hook/agent/command individually
4. **Use matchers wisely**: Narrow hook matchers to avoid unnecessary executions
5. **Fail gracefully**: Hooks should never crash Claude Code
6. **Leverage existing patterns**: Study the hooks in this repo before creating new ones

## Key Architecture Patterns

### Safety Pattern (PreToolUse hooks)

Hooks can validate and block operations:

- Check for dangerous commands (`is_dangerous_rm_command` pattern in `pre_tool_use.py`)
- Prevent access to sensitive files (`.env` blocking enabled)
- Log all operations for audit
- Exit code 2 blocks operation and shows error to Claude

### Context Preservation Pattern (Agents)

Each agent operates in isolated context:

- Prevents context pollution in main conversation
- Enables longer overall sessions
- Allows specialized instructions per domain

## Important
- Update the `README.md` whenever adding new agents, hooks, commands, skills, or output-styles
- See `CONTRIBUTING.md` for detailed contribution guidelines and development workflow

## References

All documentation in `docs/claude-code/` is official Claude Code reference material. Refer to these when creating extensions.