claude-settings/README.md

# Claude Code Configuration

This directory contains global Claude Code configuration that is synced
across machines via git.

## What's Tracked

### Global Instructions
- **CLAUDE.md** - Global working preferences, code style standards, TDD
  workflow, and communication style

### Settings
- **settings.json** - Claude Code application settings

### Custom Agents (`agents/`)
Specialized agents for specific workflows:
- **gentoo-sysadmin.json** - Gentoo Linux system administration (OpenRC,
  Portage, kernel)
- **tdd-test-writer.json** - TDD Ping-Pong workflow (writes failing tests)
- **code-reviewer.json** - Code review against strict style guidelines
- **documentation-writer.json** - Creates comprehensive project documentation
- **python-ai-tutor.json** - AI/ML coursework assistant with teaching focus
- **dotfiles-manager.json** - Dotfiles management with chezmoi

### Slash Commands (`commands/`)
Quick workflow commands:
- **/gentoo-update** - Safe Gentoo system update workflow
- **/tdd-next** - Start next TDD test cycle
- **/style-check** - Comprehensive code style validation
- **/doc-sync** - Update all project documentation
- **/review-pr** - Review pull request before merge
- **/script-install** - Install system script with proper permissions

## What's NOT Tracked

The `.gitignore` excludes machine-specific and sensitive data:
- `.credentials.json` - Authentication tokens (SENSITIVE)
- `CLAUDE-LOCAL.md` - Machine-specific overrides (work/personal)
- `*-local.json` - Machine-specific settings
- `history.jsonl` - Conversation history (machine-specific)
- `todos/` - Session-specific todo lists
- `projects/` - Project state (machine-specific paths)
- `session-env/` - Session environment data
- `file-history/` - File version history
- `plans/` - Plan mode drafts
- `debug/`, `downloads/`, `statsig/` - Temporary/analytics data

## Multi-Machine Setup

**Using this config across multiple machines (personal, work, etc.)?**

See **[MULTI-MACHINE-SETUP.md](MULTI-MACHINE-SETUP.md)** for the complete
guide.

**Quick summary:**
- Shared config (`CLAUDE.md`, agents, commands) syncs via git
- Machine-specific overrides go in `CLAUDE-LOCAL.md` (not tracked)
- No branch conflicts - layered configuration approach
- Same repo works for personal and work computers with different credentials

## Using Custom Agents

Custom agents are invoked using the Task tool:

```python
# In conversation context
Use the Task tool with subagent_type matching the agent name
```

Or via CLI:
```bash
claude --agents '{"review": "~/.claude/agents/code-reviewer.json"}'
```

## Using Slash Commands

In Claude Code conversation:
```
/gentoo-update
/tdd-next
/style-check
/doc-sync
/review-pr <pr-number>
/script-install
```

## Setup on New Machine

1. Clone this repository:
   ```bash
   cd ~/.claude
   git init
   git remote add origin <your-repo-url>
   git pull origin main
   ```

2. Set up credentials (not tracked):
   ```bash
   claude setup-token
   ```

3. Verify configuration:
   ```bash
   cat CLAUDE.md
   ls agents/
   ls commands/
   ```

## Style Guidelines

All code follows strict standards defined in `CLAUDE.md`:
- 80-character line limit
- 2-space indentation
- Language-specific conventions (PEP 8, Airbnb, POSIX sh)
- Minimal comments
- Security-first approach
- TDD Ping-Pong workflow for development

## Maintenance

### Adding New Agents
1. Create `agents/<name>.json` with:
   - `name`: Agent identifier
   - `description`: When to use this agent
   - `prompt`: Detailed agent instructions
2. Commit and push

### Adding New Commands
1. Create `commands/<name>.md` with markdown instructions
2. Commit and push

### Updating Global Instructions
1. Edit `CLAUDE.md`
2. Test with a few conversations
3. Commit and push

## Repository Structure

```
~/.claude/
├── README.md              # This file
├── CLAUDE.md              # Global instructions
├── settings.json          # Application settings
├── .gitignore             # Ignore patterns
├── agents/                # Custom agents (tracked)
│   ├── gentoo-sysadmin.json
│   ├── tdd-test-writer.json
│   ├── code-reviewer.json
│   ├── documentation-writer.json
│   ├── python-ai-tutor.json
│   └── dotfiles-manager.json
├── commands/              # Slash commands (tracked)
│   ├── gentoo-update.md
│   ├── tdd-next.md
│   ├── style-check.md
│   ├── doc-sync.md
│   ├── review-pr.md
│   └── script-install.md
└── [ignored directories]  # Machine-specific data (not tracked)
    ├── .credentials.json
    ├── history.jsonl
    ├── todos/
    ├── projects/
    ├── session-env/
    ├── file-history/
    ├── plans/
    ├── debug/
    ├── downloads/
    └── statsig/
```

## Contributing

When adding or modifying agents/commands:
1. Follow the existing format
2. Test thoroughly
3. Update this README if adding new categories
4. Use semantic commit messages
5. Keep documentation in sync

---

**Last Updated**: 2025-11-26