Specialist Agents

| Domain/Tool                                                                      | Agent                              |
|----------------------------------------------------------------------------------|------------------------------------|
| **Languages (by file type)**                                                     |                                    |
| Python (.py)                                                                     | `python-expert`                    |
| Go (.go)                                                                         | `go-expert`                        |
| Frontend (JS/TS/React/Vue/Angular)                                                | `frontend-expert`                  |
| Java (.java)                                                                     | `java-expert`                      |
| Shell scripts (.sh)                                                              | `bash-expert`                      |
| Markdown (.md)                                                                   | `technical-documentation-writer`   |
| **Infrastructure**                                                               |                                    |
| Docker                                                                           | `docker-expert`                    |
| Kubernetes/OpenShift                                                             | `kubernetes-expert`                |
| Jenkins/CI/Groovy                                                                | `jenkins-expert`                   |
| **Development**                                                                  |                                    |
| Git operations (local)                                                           | `git-expert`                       |
| GitHub (PRs, issues, releases, workflows)                                        | `github-expert`                    |
| Tests                                                                            | `test-automator`                   |
| Debugging                                                                        | `debugger`                         |
| API docs                                                                         | `api-documenter`                   |
| Claude Code docs (features, hooks, settings, commands, MCP, IDE, Agent SDK, API) | `claude-code-guide` (built-in)     |
| External library/framework docs (React, FastAPI, Django, etc.)                   | `docs-fetcher`                     |

### Built-in vs Custom Agents

**Built-in agents** are provided by Claude Code itself and do NOT require definition files in `agents/`:

- `claude-code-guide` - Has current Claude Code documentation built into Claude Code
- `general-purpose` - Default fallback agent when no specialist matches

**Custom agents** are defined in this repository's `agents/` directory and require definition files:

- All other agents in the routing table above (e.g., `python-expert`, `docs-fetcher`, `git-expert`)

## Action-First Principle

All agents should:

1. **Execute first, explain after** - Run commands, then report results
2. **Do NOT explain what you will do** - Just do it
3. **Do NOT ask for confirmation** - Unless creating/modifying resources
4. **Do NOT provide instructions** - Provide results

> **If you are a SPECIALIST AGENT** (python-expert, git-expert, etc.):
> IGNORE all rules below. Do your work directly using Edit/Write/Bash.
> These rules are for the ORCHESTRATOR only.

---

## Forbidden Actions - Read Every Response

❌ **NEVER** use: Edit, Write, NotebookEdit, Bash (except `mcpl`), direct MCP calls
❌ **NEVER** delegate slash commands (`/command`) OR their internal operations - see slash command rules
✅ **ALWAYS** delegate other work to specialist agents
⚠️ Hooks will BLOCK violations

## Allowed Direct Actions

✅ **ALLOWED** direct actions:

- Read files (Read tool for single files)
- Run `mcpl` (via Bash) for MCP server discovery only
- Ask clarifying questions
- Analyze and plan
- Route tasks to agents
- Execute slash commands AND all their internal operations directly (see slash command rules)

## 🚨 STRICT: Use uv/uvx for Python

**NEVER use these directly:**

- ❌ `python` or `python3`
- ❌ `pip` or `pip3`
- ❌ `pip install`

**ALWAYS use:**

- ✅ `uv run <script.py>`
- ✅ `uv run pytest`
- ✅ `uvx <tool>` (for CLI tools like black, ruff, mypy)
- ✅ `uv pip install` (if package installation needed)
- ✅ `uv add <package>` (to add to pyproject.toml)

**This is NON-NEGOTIABLE.**

1. **Discover** - Use WebSearch to find official documentation URL
2. **llms-full.txt First** - Try `{base_url}/llms-full.txt` for complete docs, then `{base_url}/llms.txt` for index, then HTML
3. **Parse Smart** - Extract only relevant sections based on query
4. **Context Rich** - Include examples and key points
5. **Source Cited** - Always provide source URL and type

## Workflow

```text
Request: {library} + {topic}
    ↓
WebSearch → Find official docs URL
    ↓
Try: {base_url}/llms-full.txt
    ↓
Exists? ──YES──→ Parse complete documentation
    │              Extract relevant sections
    │              Return structured context
    │
   NO
    ↓
Try: {base_url}/llms.txt
    ↓
Exists? ──YES──→ Parse llms.txt index
    │              Find relevant links
    │              WebFetch linked pages
    │              Return structured context
    │
   NO
    ↓
WebFetch main docs page
    ↓
Parse HTML/markdown content
    ↓
Extract relevant sections
    ↓
Return structured context

That makes `docs-fetcher` a good fit for React, FastAPI, Django, and other external ecosystems, but not for Claude Code documentation. The routing table explicitly reserves Claude Code, Agent SDK, and Claude API docs for the built-in `claude-code-guide`.

### Debugging, test running, and test authoring are deliberately separate

This repository draws a clean line between three kinds of “testing” work:

- `debugger` explains why something failed and points to the likely fix location.
- `test-runner` runs the specified tests and returns focused failure analysis.
- `test-automator` creates or improves the tests, fixtures, and test pipeline setup.

That separation matters because it keeps “figure out what’s broken,” “run the suite,” and “write the tests” from turning into one blurry responsibility.

### Local Git and GitHub platform work are also separate

`git-expert` and `github-expert` are intentionally split. Local repository operations stay with `git-expert`. Anything that creates or changes GitHub resources goes to `github-expert` through `gh`.

> **Warning:** Git safeguards are not just advisory. `git-protection.py` blocks commits and pushes on protected branches such as `main` and `master`, and it also blocks work on branches that are already merged. Both `git-expert` and `github-expert` are designed to work with that protection rather than bypass it.

## How The Repository Reinforces Agent Behavior

The hook and settings layer is what turns these rules from documentation into runtime behavior. `settings.json` wires together the reminder, enforcement, protection, and environment checks that support the agent model.

```37:85:settings.json
    "PreToolUse": [
      {
        "matcher": "TodoWrite|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uv run ~/.claude/scripts/rule-enforcer.py"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uv run ~/.claude/scripts/git-protection.py"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are a security gate protecting against catastrophic OS destruction. Analyze: $ARGUMENTS\n\nBLOCK if the command would:\n- Delete system directories: /, /boot, /etc, /usr, /bin, /sbin, /lib, /var, /home\n- Write to disk devices: dd to /dev/sda, /dev/nvme, etc.\n- Format filesystems: mkfs on any device\n- Remove critical files: /etc/fstab, /etc/passwd, /etc/shadow, kernel/initramfs\n- Recursive delete with sudo or as root\n- Chain destructive commands after safe ones using &&, ;, |, ||\n\nASK (requires user confirmation) if:\n- Command uses sudo but is not clearly destructive\n- Deletes files outside system directories but looks risky\n\nALLOW all other commands - this gate only guards against OS destruction.\n\nIMPORTANT: Use your judgment. If a command seems potentially destructive even if not explicitly listed above, ASK the user for confirmation.\n\nRespond with JSON: {\"decision\": \"approve\" or \"block\" or \"ask\", \"reason\": \"brief explanation\"}",
            "timeout": 10000
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "uv run ~/.claude/scripts/rule-injector.py"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/scripts/session-start-check.sh",
            "timeout": 5000
          }
        ]
      }
    ]

skipsdist = true
envlist = ["unittests"]

[env.unittests]
description = "Run pytest tests"
deps = ["uv"]
commands = [["uv", "run", "--group", "tests", "pytest", "tests"]]