# Contributing to claude-delegator

Contributions welcome. This document covers how to contribute effectively.

---

## Quick Start

```bash
# Clone the repo
git clone https://github.com/jarrodwatts/claude-delegator
cd claude-delegator

# Install plugin in Claude Code
/claude-delegator:setup

# Test your changes by invoking the oracle
```

---

## What to Contribute

| Area | Examples |
|------|----------|
| **New Providers** | Ollama, Mistral, local model integrations |
| **Role Prompts** | New roles for `prompts/`, improved existing prompts |
| **Rules** | Better delegation triggers, model selection logic |
| **Bug Fixes** | Command issues, error messages |
| **Documentation** | README improvements, examples, troubleshooting |

---

## Project Structure

```
claude-delegator/
├── .claude-plugin/         # Plugin manifest
│   └── plugin.json
├── commands/               # Slash commands (/setup, /uninstall)
├── rules/                  # Orchestration logic (installed to ~/.claude/rules/)
├── prompts/                # Role prompts (oracle, momus)
├── config/                 # Provider registry
├── CLAUDE.md               # Development guidance for Claude Code
└── README.md               # User-facing docs
```

---

## Pull Request Process

### Before Submitting

1. **Test your changes** - Run `/claude-delegator:setup` and verify
2. **Update docs** - If you change behavior, update relevant docs
3. **Keep commits atomic** - One logical change per commit

### PR Guidelines

| Do | Don't |
|----|-------|
| Focus on one change | Bundle unrelated changes |
| Write clear commit messages | Leave vague descriptions |
| Test with actual MCP calls | Assume it works |
| Update CLAUDE.md if needed | Ignore developer docs |

### Commit Message Format

```
type: short description

Longer explanation if needed.
```

Types: `feat`, `fix`, `docs`, `refactor`, `chore`

Examples:
- `feat: add Ollama provider support`
- `fix: handle Codex timeout correctly`
- `docs: add troubleshooting for auth issues`

---

## Adding a New Provider

1. **Check native MCP support** - If the CLI has `mcp-server` like Codex, no wrapper needed

2. **Create MCP wrapper** (if needed):
   ```
   servers/your-provider-mcp/
   ├── src/
   │   └── index.ts
   ├── package.json
   └── tsconfig.json
   ```

3. **Add to providers.json**:
   ```json
   {
     "your-provider": {
       "cli": "your-cli",
       "mcp": { ... },
       "roles": ["oracle"],
       "strengths": ["what it's good at"]
     }
   }
   ```

4. **Add role prompts** (optional):
   ```
   prompts/your-role.md
   ```

5. **Update setup command** - Add checks for the new CLI

6. **Document in README** - Add to provider tables

---

## Code Style

### Markdown (Rules/Prompts)

- Use tables for structured data
- Keep prompts concise and actionable
- Test with actual Claude Code usage

### TypeScript (if adding MCP servers)

- No `any` without explicit justification
- No `@ts-ignore` or `@ts-expect-error`
- Use explicit return types on exported functions

---

## Testing

### Manual Testing

After changes, verify with actual MCP calls:

1. Install the plugin in Claude Code
2. Run `/claude-delegator:setup`
3. Verify MCP tools are available (`mcp__codex__codex`)
4. Test MCP tool calls via oracle delegation
5. Verify responses are properly synthesized
6. Test error cases (timeout, missing CLI)

---

## Questions?

Open an issue for:
- Feature requests
- Bug reports
- Documentation gaps
- Architecture discussions