# Claude Code Config

Pre-configured Claude Code setup with specialized agents and workflow automation.

## Requirements

- **Claude Code v2.1.19 or higher** - This configuration uses v2.1.19 features (see below)
- [uv](https://docs.astral.sh/uv/) - Fast Python package manager (used for running hook scripts)

### Claude Code v2.1.19 Features Used

This configuration leverages these features:

- **Agent-scoped hooks** - Hooks defined in agent frontmatter (e.g., `PreToolUse` in git-expert) (v2.1.0)
- **`allowed-tools`** - Tool restrictions in agent frontmatter (e.g., docs-fetcher is read-only) (v2.1.0)
- **`additionalContext` in PreToolUse** - Provides guidance when blocking commands (v2.1.9)
- **Task management system** - Built-in task tracking with `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet` for complex workflows (v2.1.16)
- **Slash command argument syntax** - Bracket syntax `$ARGUMENTS[0]` and shorthand `$0`, `$1` for positional arguments (v2.1.19)

> Note: `context: fork` was evaluated but not used due to compatibility issues with multi-phase workflows.

## Quick Start (Plugins)

The easiest way to use this repository's features is via plugins:

### 1. Add the marketplace

```text
/plugin marketplace add myk-org/claude-code-config
```

### 2. Install plugins

```text
# GitHub operations (PR reviews, releases, review handling)
/plugin install myk-github@myk-org

# Local code review and database queries
/plugin install myk-review@myk-org

# Qodo AI code review integration
/plugin install myk-qodo@myk-org

# Cursor agent CLI integration
/plugin install myk-cursor@myk-org
```

### 3. Install Required CLIs

For `myk-github`, `myk-review`, and parts of `myk-qodo`:

```bash
uv tool install myk-claude-tools
```

Or from this repository:

```bash
uv tool install git+https://github.com/myk-org/claude-code-config
```

For `myk-cursor`, install [Cursor](https://cursor.com), enable its CLI, and
ensure `agent` is available on your PATH. See
[`plugins/myk-cursor/README.md`](./plugins/myk-cursor/README.md) for usage and
`--fix` mode details.

### Available Plugin Commands

| Plugin | Command | Description |
|--------|---------|-------------|
| myk-github | `/myk-github:pr-review` | Review PR and post inline comments |
| myk-github | `/myk-github:release` | Create release with changelog |
| myk-github | `/myk-github:review-handler` | Process all review sources |
| myk-review | `/myk-review:local` | Review uncommitted changes |
| myk-review | `/myk-review:query-db` | Query review database |
| myk-qodo | `/myk-qodo:review` | AI-powered code review |
| myk-qodo | `/myk-qodo:describe` | Generate PR descriptions |
| myk-qodo | `/myk-qodo:improve` | Get improvement suggestions |
| myk-qodo | `/myk-qodo:ask` | Ask questions about code |
| myk-cursor | `/myk-cursor:prompt` | Run prompts via Cursor agent CLI with optional `--fix` mode for direct file changes |

> **For full orchestrator pattern with agents and hooks**, see [Full Installation](#installation) below.

## Installation

Clone to any location and symlink into `~/.claude`:

```bash
# Clone to ~/git/ (or your preferred location)
git clone https://github.com/myk-org/claude-code-config ~/git/claude-code-config

# Create ~/.claude if it doesn't exist
mkdir -p ~/.claude

# Symlink each component
ln -sf ~/git/claude-code-config/agents ~/.claude/agents
ln -sf ~/git/claude-code-config/rules ~/.claude/rules
ln -sf ~/git/claude-code-config/scripts ~/.claude/scripts
ln -sf ~/git/claude-code-config/skills ~/.claude/skills
ln -sf ~/git/claude-code-config/settings.json ~/.claude/settings.json
ln -sf ~/git/claude-code-config/statusline.sh ~/.claude/statusline.sh
```

**Updating:**

```bash
cd ~/git/claude-code-config && git pull
```

Your symlinks will automatically point to the updated files.

## What's Included

- **4 plugins** with 10 commands (myk-github, myk-review, myk-qodo, myk-cursor)
- **CLI tool** (`myk-claude-tools`) for plugin operations
- **16 specialized agents** for different domains (Python, Go, Java, Docker, Kubernetes, Git, etc.)
- **1 skill** for context-aware automation
- **Orchestrator pattern** with automatic agent routing via CLAUDE.md
- **Pre-commit hooks** for rule enforcement
- **Status line** integration
- **SessionStart tool validation** - Checks for required tools (uv, gh, prek, mcpl) and prompts to install missing ones

## Agents

| Agent | Purpose |
| ----- | ------- |
| `python-expert` | Python development, testing, async patterns |
| `go-expert` | Go development, goroutines, modules |
| `java-expert` | Java/Spring Boot development |
| `frontend-expert` | JS/TS/React/Vue/Angular |
| `bash-expert` | Shell scripting and automation |
| `docker-expert` | Dockerfile, container orchestration |
| `kubernetes-expert` | K8s/OpenShift, Helm, GitOps |
| `jenkins-expert` | CI/CD pipelines, Jenkinsfiles |
| `git-expert` | Git operations, branching strategies |
| `github-expert` | GitHub platform operations (PRs, issues, releases) |
| `test-automator` | Test suites, CI pipelines |
| `test-runner` | Test execution and reporting |
| `debugger` | Error analysis, debugging |
| `technical-documentation-writer` | Documentation |
| `api-documenter` | OpenAPI/Swagger specs |
| `docs-fetcher` | Fetches external library/framework documentation, prioritizes llms.txt |

## Marketplace Plugins

This configuration uses plugins from the [Anthropic official marketplace](https://github.com/anthropics/claude-plugins-official).

> **Critical (required for the code-review loop):** `pr-review-toolkit`, `superpowers`, `feature-dev`
> All others are optional enhancements.

### Install all at once

```text
/plugin marketplace add claude-plugins-official
```

Then install each plugin:

```text
# --- Critical (required for code-review loop) ---
/plugin install feature-dev@claude-plugins-official
/plugin install pr-review-toolkit@claude-plugins-official
/plugin install superpowers@claude-plugins-official

# --- Optional enhancements ---
/plugin install claude-code-setup@claude-plugins-official
/plugin install claude-md-management@claude-plugins-official
/plugin install code-review@claude-plugins-official
/plugin install code-simplifier@claude-plugins-official
/plugin install coderabbit@claude-plugins-official
/plugin install commit-commands@claude-plugins-official
/plugin install frontend-design@claude-plugins-official
/plugin install github@claude-plugins-official
/plugin install gopls-lsp@claude-plugins-official
/plugin install jdtls-lsp@claude-plugins-official
/plugin install lua-lsp@claude-plugins-official
/plugin install playground@claude-plugins-official
/plugin install pyright-lsp@claude-plugins-official
/plugin install security-guidance@claude-plugins-official
```

### Plugin purpose

| Plugin | Purpose |
|--------|---------|
| `claude-code-setup` | Claude Code automation recommendations |
| `claude-md-management` | CLAUDE.md file management and improvement |
| `code-review` | Pull request code review |
| `code-simplifier` | Code simplification and refactoring |
| `coderabbit` | CodeRabbit AI code review integration |
| `commit-commands` | Git commit, push, PR, and branch cleanup |
| `feature-dev` | Feature architecture, codebase exploration, code review |
| `frontend-design` | Frontend interface design |
| `github` | GitHub operations and workflows |
| `gopls-lsp` | Go language server (gopls) integration |
| `jdtls-lsp` | Java language server (Eclipse JDT.LS) integration |
| `lua-lsp` | Lua language server integration |
| `playground` | Interactive HTML playground creation |
| `pr-review-toolkit` | PR review with specialized agents (code-reviewer, test-analyzer, silent-failure-hunter) |
| `pyright-lsp` | Python language server (Pyright) integration |
| `security-guidance` | Security best practices |
| `superpowers` | Brainstorming, debugging, TDD, code review workflows |

> **Note:** Missing plugins are detected automatically at session start. Claude Code will prompt you to install any missing plugins.

### Automatic Documentation Fetching

When specialist agents work with external libraries or frameworks, they can automatically fetch the latest
documentation through the `docs-fetcher` agent. This ensures that code follows current best practices and
uses up-to-date APIs.

**Key features:**

- Prioritizes `llms.txt` files (LLM-optimized documentation)
- Falls back to official documentation sites
- Caches results for faster subsequent access
- Provides context-relevant excerpts to specialist agents

**Example workflow:**

```text
python-expert working with FastAPI
         ↓
    docs-fetcher fetches FastAPI docs
         ↓
python-expert uses current best practices
```

## Skills

Skills are similar to slash commands but auto-invoke based on task context rather than requiring explicit invocation.

| Skill           | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| `agent-browser` | Browser automation for web testing, form filling, screenshots, and data extraction |

### agent-browser Installation

See [agent-browser](https://github.com/vercel-labs/agent-browser) for installation instructions.

## MCP Server Access

This configuration uses [mcp-launchpad](https://github.com/kenneth-liao/mcp-launchpad) (`mcpl`) for on-demand MCP server access.

**Benefits over native MCP loading:**

- Tools are NOT loaded into context at session start
- No 30% context consumption from tool definitions
- Agents discover and call tools on-demand via CLI

**Installation:**

```bash
uv tool install https://github.com/kenneth-liao/mcp-launchpad.git
```

See `rules/15-mcp-launchpad.md` for detailed usage instructions and command reference.

## Why Agent-Based Workflow?

This configuration implements an **orchestrator pattern** where Claude acts as a manager delegating to specialist agents. Here's why:

### Context Preservation

- **Main conversation stays lean** - The orchestrator only tracks high-level progress
- **Specialists work in isolation** - Each agent handles its task without bloating the main context
- **Parallel execution** - Multiple agents can work simultaneously on independent tasks

### Expertise Separation

- **Domain knowledge** - Each agent has specialized instructions for its domain (Python best practices, Git workflows, Docker patterns)
- **Tool restrictions** - Agents only use tools relevant to their specialty
- **Consistent patterns** - Same agent = same coding style and conventions

### Quality Assurance

- **Mandatory code review** - Every code change goes through 3 parallel plugin review agents
- **Automated testing** - `test-automator` runs after changes
- **Review loop** - Changes iterate until approved

### Workflow Example

```text
User: "Add a new feature to handle user auth"
         │
         ▼
   ┌─────────────────┐
   │  ORCHESTRATOR   │  (main Claude - manages, doesn't code)
   └────────┬────────┘
            │
   ┌────────┼────────────────┐
   │        │                │
   ▼        ▼                ▼
┌──────┐ ┌──────┐      ┌──────────┐
│python│ │ git  │      │test-auto │
│expert│ │expert│      │  mator   │
└──────┘ └──────┘      └──────────┘
   │        │                │
   └────────┴────────────────┘
            │
            ▼
  ┌──────────┬──────────┬──────────┐
  │superpow. │pr-review │feat-dev  │
  │ reviewer │ reviewer │ reviewer │
  └──────────┴──────────┴──────────┘
            │
            ▼
       Done
```

### Benefits

- **Reduced token usage** - Specialist context is discarded after task completion
- **Better code quality** - Domain experts produce better code
- **Faster execution** - Parallel agents vs sequential operations
- **Maintainability** - Easy to add/modify agents for new domains

## Orchestrator Pattern Details

The `CLAUDE.md` file (local-only, not tracked in git) defines an orchestrator pattern where:

1. The main Claude instance acts as a **manager/orchestrator**
2. It delegates tasks to **specialist agents** based on the domain
3. After code changes, automatic **code review** and **test** loops run

## Customization

- **Edit `CLAUDE.md`** to customize orchestrator rules and agent routing
- **Edit `.claude/settings.json`** to modify hooks and allowed tools
- **Edit agents in `.claude/agents/`** to customize agent behavior

## File Structure

```text
~/.claude/
├── agents/           # Specialist agent definitions
├── plugins/          # Plugin definitions (myk-github, myk-review, myk-qodo, myk-cursor)
├── skills/           # Skills (auto-invoked based on context)
│   └── agent-browser/
│       └── SKILL.md
├── rules/            # Orchestrator rules (auto-loaded)
├── scripts/          # Helper scripts for hooks
│   ├── git-protection.py         # Protects main branch, merged branches
│   ├── my-notifier.sh            # Custom notifications
│   ├── rule-enforcer.py          # Blocks orchestrator from using Edit/Write/Bash
│   ├── rule-injector.py          # Auto-loads rules from rules/
│   └── session-start-check.sh    # Validates required tools at session start
├── tests/            # Unit tests for Python scripts
├── settings.json     # Hooks and tool permissions
├── statusline.sh     # Status line script
├── tox.toml          # Test configuration
├── pyproject.toml    # Python project config (ruff, mypy)
├── .pre-commit-config.yaml  # Pre-commit hooks
└── LICENSE           # MIT License
```

## Development

### Running Tests

Tests are run via tox with uv:

```bash
# Run all tests
uvx --with tox-uv tox

# Run specific Python version
uvx --with tox-uv tox -e py313

# Pass pytest arguments
uvx --with tox-uv tox -- -v --tb=short
```

### Pre-commit

This project uses pre-commit hooks for code quality:

```bash
# Install pre-commit hooks
pre-commit install

# Run on all files
pre-commit run --all-files
```

## Contributing

When adding or modifying plugins, agents, or features, ensure all markdown documentation files
in the repository are updated to reflect the changes. In particular, update
[`AI_REVIEW.md`](./AI_REVIEW.md) when modifying shared project context or guidelines.

## Plugins

See [Quick Start (Plugins)](#quick-start-plugins) above for installation and available commands,
or [plugins/README.md](./plugins/README.md) for detailed documentation.

### Prerequisites for github/review plugins

These plugins use the `myk-claude-tools` CLI:

```bash
uv tool install myk-claude-tools
```

Or install from this repository:

```bash
uv tool install git+https://github.com/myk-org/claude-code-config
```

## License

MIT
