# Handoff: Programmer Agent Implementation

## Summary

Implement a programmer-orchestrator agent system for general code development, following the approved design.

## Design Document

`~/.claude/docs/plans/2025-12-29-programmer-agent-design.md`

Read this first - it contains the full specification.

## Implementation Tasks

### 1. Create State Directory Structure

```bash
mkdir -p ~/.claude/state/programmer/projects
```

Create initial state files:

**~/.claude/state/programmer/session-autonomy.json**
```json
{
  "level": "conservative",
  "overrides": {}
}
```

**~/.claude/state/programmer/preferences.json**
```json
{
  "style": {},
  "patterns": {},
  "languages": {}
}
```

### 2. Create Agent Files

Create these in `~/.claude/agents/`:

| File | Model | Reference |
|------|-------|-----------|
| `programmer-orchestrator.md` | opus | Design doc "programmer-orchestrator" section |
| `code-planner.md` | sonnet | Design doc "code-planner" section |
| `code-implementer.md` | sonnet | Design doc "code-implementer" section |
| `code-reviewer.md` | sonnet | Design doc "code-reviewer" section |

Follow the format in `~/.claude/agents/linux-sysadmin.md`:
- YAML frontmatter with name, description, model, tools
- Markdown body with hierarchy position, responsibilities, tool classification

Key points for each:

**programmer-orchestrator**:
- Enforces workflow phases (plan → implement → review)
- Gates transitions on user approval
- Reads/passes project context to sub-agents
- Include the workflow diagram from design doc

**code-planner**:
- Read-only tools (no Write/Edit)
- References superpowers:writing-plans skill
- Output format for plan documents

**code-implementer**:
- Full write access
- Must follow plan received as input
- Cannot commit (returns to orchestrator)

**code-reviewer**:
- Read-only plus git diff
- References superpowers:code-reviewer
- Include the review output format from design doc

### 3. Create Command

**~/.claude/commands/programmer.md**
```yaml
---
name: programmer
description: Invoke the programmer agent for code development tasks
aliases: [code, dev]
invokes: agent:programmer-orchestrator
---

Routes programming tasks to the programmer-orchestrator agent.
```

### 4. Create Skill

**~/.claude/skills/programmer-add-project/SKILL.md**

Skill that:
- Prompts for project path, description, stack, conventions
- Creates `~/.claude/state/programmer/projects/<name>.json`
- Validates path exists

### 5. Update Existing Files

**~/.claude/CLAUDE.md** - Update hierarchy diagram:
```
Personal Assistant (Opus) - user interface + ultimate oversight
└── Master Orchestrator (Opus) - monitor, coordinate, enforce
    ├── linux-sysadmin (Sonnet) - workstation management
    ├── k8s-orchestrator (Opus) - cluster management
    │   ├── k8s-diagnostician (Sonnet)
    │   ├── argocd-operator (Sonnet)
    │   ├── prometheus-analyst (Sonnet)
    │   └── git-operator (Sonnet)
    ├── programmer-orchestrator (Opus) - code development
    │   ├── code-planner (Sonnet)
    │   ├── code-implementer (Sonnet)
    │   └── code-reviewer (Sonnet)
    └── network-agent (future)
```

**~/.claude/state/model-policy.json** - Add entries:
```json
{
  "programmer-orchestrator": "opus",
  "code-planner": "sonnet",
  "code-implementer": "sonnet",
  "code-reviewer": "sonnet"
}
```

**~/.claude/agents/master-orchestrator.md** - Add to supervised agents list:
- programmer-orchestrator

## Reference Files

Examine these for format/style consistency:
- `~/.claude/agents/linux-sysadmin.md` - Agent format example
- `~/.claude/agents/k8s-orchestrator.md` - Orchestrator pattern example
- `~/.claude/agents/master-orchestrator.md` - Hierarchy reference

## Verification

After implementation:
1. All agent files have valid YAML frontmatter
2. State files are valid JSON
3. Hierarchy in CLAUDE.md matches actual agents
4. model-policy.json has all new agents
5. master-orchestrator.md lists programmer-orchestrator

## Commit

Single commit with message:
```
Implement programmer agent system

- Add programmer-orchestrator and sub-agents (planner, implementer, reviewer)
- Add state files for preferences and project context
- Add /programmer command and project registration skill
- Update hierarchy and model policy
```