# Claude Code Configuration

This directory contains project-level configuration for Claude Code agents and Skills.

## Configuration Strategy

We use a **deny-by-default, agent-allow** approach with Skills instead of MCP servers to minimize context overhead:

1. **Project-level** (`.claude/settings.json`): Denies direct access to Jira/GitHub operations from main agent
2. **Agent-level** (`.claude/agents/*.md`): Specialized agents use Skills to perform operations
3. **Skills** (`.claude/skills/*/`): Lightweight bash script wrappers around GitHub CLI and Jira REST API

## File Structure

```
.claude/
├── settings.json           # Project-level permissions (deny Skills from main agent)
├── settings.local.json     # User-specific settings (not checked into git)
└── agents/
    ├── github-workflow.md  # GitHub PR specialist (uses github-operations Skill)
    └── jira-workflow.md    # Jira issue specialist (uses jira-operations Skill)
└── skills/
    ├── github-operations/  # GitHub CLI bash scripts (4 operations)
    │   ├── SKILL.md
    │   └── scripts/
    │       ├── create-pr.sh
    │       ├── list-prs.sh
    │       ├── get-pr.sh
    │       └── get-pr-files.sh
    └── jira-operations/    # Jira REST API bash scripts (9 operations)
        ├── SKILL.md
        └── scripts/
            ├── create-issue.sh
            ├── update-issue.sh
            ├── get-issue.sh
            ├── search-issues.sh
            ├── add-comment.sh
            ├── get-transitions.sh
            ├── transition-issue.sh
            ├── delete-issue.sh
            └── get-issue-types.sh
```

## How It Works

### Main Conversation (Claude Code)
- **Direct GitHub/Jira access**: ❌ Denied by `settings.json`
- **Context overhead**: ~100 tokens (agent descriptions only)
- **Benefit**: Clean main conversation, delegates to specialized agents

### Agents
- **github-workflow**: Uses bash scripts from github-operations Skill (4 operations)
- **jira-workflow**: Uses bash scripts from jira-operations Skill (9 operations)
- **Context**: Only loads Skill documentation when agent is invoked (~1-2k tokens vs 46k for MCPs)

## Agent Operations

### github-workflow Agent (via Bash scripts)
- Create pull requests - `bash .claude/skills/github-operations/scripts/create-pr.sh`
- List pull requests - `bash .claude/skills/github-operations/scripts/list-prs.sh`
- Get PR details - `bash .claude/skills/github-operations/scripts/get-pr.sh`
- Get PR files - `bash .claude/skills/github-operations/scripts/get-pr-files.sh`

### jira-workflow Agent (via Bash scripts)
- Create issues - `bash .claude/skills/jira-operations/scripts/create-issue.sh`
- Update issues - `bash .claude/skills/jira-operations/scripts/update-issue.sh`
- Get issue details - `bash .claude/skills/jira-operations/scripts/get-issue.sh`
- Search issues - `bash .claude/skills/jira-operations/scripts/search-issues.sh`
- Add comments - `bash .claude/skills/jira-operations/scripts/add-comment.sh`
- Get transitions - `bash .claude/skills/jira-operations/scripts/get-transitions.sh`
- Transition issues - `bash .claude/skills/jira-operations/scripts/transition-issue.sh`
- Get issue types - `bash .claude/skills/jira-operations/scripts/get-issue-types.sh`
- Delete issues - `bash .claude/skills/jira-operations/scripts/delete-issue.sh`

## Environment Variables Required

### GitHub Operations (gh CLI)
- `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub personal access token with repo permissions
- The `gh` CLI must be installed and authenticated

### Jira Operations (REST API)
- `ATLASSIAN_SITE_NAME` - Your Atlassian site URL (e.g., https://yoursite.atlassian.net)
- `ATLASSIAN_USER_EMAIL` - Your Atlassian account email
- `ATLASSIAN_API_TOKEN` - Atlassian API token
- Requires `curl` and `jq` to be installed

## Usage

### Invoke GitHub Agent
```
"Create a PR for the merged cell feature"
```
Claude Code will automatically invoke the `github-workflow` agent, which uses bash scripts from the github-operations Skill.

### Invoke Jira Agent
```
"Create a Jira task for refactoring the spatial grid module"
```
Claude Code will automatically invoke the `jira-workflow` agent, which uses bash scripts from the jira-operations Skill.

## Context Optimization

| Approach | Main Context | Agent Context | Total |
|----------|-------------|---------------|-------|
| **MCP Servers** | 46.1k tokens | 0k | 46.1k |
| **Skills** (current) | ~100 tokens | ~1-2k (on demand) | ~100-2.1k |

**Savings**: ~44-46k tokens (95-97% reduction in overhead)

## Troubleshooting

### Agent says "permission denied" or "exit 1"
1. Check environment variables are set correctly
2. For GitHub: Verify `gh` CLI is authenticated (`gh auth status`)
3. For Jira: Test API credentials with curl manually
4. Check `.claude/settings.json` hasn't been modified

### Scripts don't execute
1. Verify bash scripts are executable: `chmod +x .claude/skills/*/scripts/*.sh`
2. Check that `jq` is installed: `which jq`
3. Check that `gh` CLI is installed: `which gh`

### Agent doesn't trigger automatically
1. Ensure agent descriptions in frontmatter are clear
2. Try explicitly mentioning "GitHub" or "Jira" in your request
3. Check agent files exist in `.claude/agents/`

## Architecture Benefits

- **Minimal context overhead** - Skills load on-demand, not globally
- **No external dependencies** - Just bash, curl, jq, and gh CLI
- **Full control** - Scripts are visible and auditable in the repo
- **Fast execution** - Direct CLI/API calls without MCP protocol overhead
- **Easy debugging** - Can test scripts manually from command line