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

# Programmer Agent Design

A specialized agent system for general code development, integrated into the existing agent hierarchy.

## Hierarchy

```
Master Orchestrator (Opus)
├── linux-sysadmin (Sonnet) - workstation management
├── k8s-orchestrator (Opus) - cluster management
│   └── [sub-agents]
└── programmer-orchestrator (Opus) - code development    ← NEW
    ├── code-planner (Sonnet) - design & planning
    ├── code-implementer (Sonnet) - write code
    └── code-reviewer (Sonnet) - review & quality
```

## Agents

### programmer-orchestrator (Opus)

**Purpose**: Routes tasks to appropriate sub-agent, enforces workflow phases, maintains project context and preferences.

**Tools**: `Read, Write, Edit, Bash, Glob, Grep, Task`

**Responsibilities**:
- Route incoming programming requests to appropriate phase
- Enforce workflow: plan → implement → review
- Block phase transitions until approvals received
- Maintain and pass project context to sub-agents
- Handle final commit after review approval

**Escalates to master-orchestrator for**:
- Cross-agent coordination (e.g., needs sysadmin to install dependencies)
- Uncertain autonomy decisions
- Security-sensitive operations

### code-planner (Sonnet)

**Purpose**: Explores codebase, designs solutions, writes implementation plans.

**Tools**: `Read, Glob, Grep, Task, WebSearch, WebFetch`

**Responsibilities**:
- Explore codebase to understand context
- Design solution with architectural decisions
- Write plan to `docs/plans/YYYY-MM-DD-<topic>.md`
- Use `superpowers:writing-plans` skill when available
- Escalate to orchestrator if requirements are ambiguous

**Output**: Plan document in markdown for user approval.

### code-implementer (Sonnet)

**Purpose**: Executes approved plans, writes code, runs tests.

**Tools**: `Read, Write, Edit, Bash, Glob, Grep`

**Responsibilities**:
- Receive plan as input and follow it
- Write code according to plan specifications
- Run tests after implementation if defined in project config
- Report back: files changed, tests passed/failed, blockers

**Constraints**: Cannot commit - returns changes to orchestrator.

### code-reviewer (Sonnet)

**Purpose**: Reviews changes before commit, ensures quality.

**Tools**: `Read, Glob, Grep, Bash` (read-only bash for git diff)

**Responsibilities**:
- Review against: original plan, project conventions, general quality
- Use `superpowers:code-reviewer` agent if available
- Output structured review with findings and required changes

**Output format**:
```markdown
## Review Summary
- Status: APPROVE | CHANGES_REQUESTED
- Files reviewed: N

## Findings
- [severity] file:line - description

## Required Changes (if any)
- [ ] Fix X in file Y
```

## Workflow

```
Request → Plan → [Approval] → Implement → Review → [Approval] → Commit
```

### Phase 1: Planning
- code-planner explores codebase and designs solution
- Writes plan document
- Returns to orchestrator for user approval

### Gate 1: Plan Approval
- User must approve plan before implementation
- Orchestrator blocks code-implementer until approval

### Phase 2: Implementation
- code-implementer receives approved plan
- Writes code following the plan
- Runs tests if available
- Returns changes to orchestrator

### Phase 3: Review
- code-reviewer reviews all changes against plan
- Either approves or requests changes

### Gate 2: Review Approval
- If changes requested, routes back to implementer
- Loop until reviewer approves

### Phase 4: Commit
- Orchestrator handles commit with standard conventions
- Follows existing git commit format

### Bypass Option
For trivial changes (typos, one-liners), orchestrator can skip directly to implement+review without full planning phase.

## State Files

```
~/.claude/state/programmer/
├── session-autonomy.json      # Per-session autonomy overrides
├── preferences.json           # Coding style preferences
└── projects/
    └── <project-name>.json    # Per-project context
```

### preferences.json

Global coding preferences:

```json
{
  "style": {
    "indent": "spaces",
    "indentSize": 2,
    "quotes": "single",
    "trailingComma": true
  },
  "patterns": {
    "errorHandling": "explicit",
    "testing": "colocated"
  },
  "languages": {
    "python": { "formatter": "black", "linter": "ruff" },
    "typescript": { "formatter": "prettier", "linter": "eslint" }
  }
}
```

### projects/<name>.json

Per-project context:

```json
{
  "path": "/home/will/projects/my-app",
  "description": "REST API for inventory management",
  "stack": ["python", "fastapi", "postgresql"],
  "conventions": "See CONTRIBUTING.md",
  "recentWork": [
    { "date": "2025-12-28", "summary": "Added auth endpoints" }
  ],
  "activeTodos": []
}
```

## Autonomy Controls

### Safe (Auto-Execute)

```
# Reading & exploration
Read, Glob, Grep (all files)
Bash: git status, git log, git diff, git branch
Bash: ls, tree, find, wc
Bash: cat, head, tail (for non-sensitive files)
Bash: npm/yarn/pip/cargo list, outdated, info
Bash: test runners in dry-run/list mode

# Analysis
WebSearch, WebFetch (documentation lookups)
Task (spawning exploration agents)
```

### Confirm (Require Approval)

```
# Writing & editing
Write, Edit (any file modifications)
Bash: git add, git commit, git push
Bash: npm/yarn/pip/cargo install, uninstall
Bash: mkdir, touch, cp, mv
Bash: test execution (npm test, pytest, etc.)
Bash: build commands (npm build, cargo build)
Bash: running project scripts
```

### Forbidden (Never Execute)

```
Bash: rm -rf with broad paths
Bash: git push --force, git reset --hard
Bash: chmod 777, chown on system files
Bash: curl | bash, eval of remote code
Bash: writing to ~/.ssh, ~/.gnupg, /etc
Modifying: .env files, credentials, secrets
```

Session autonomy can relax "Confirm" to auto-execute but never touches "Forbidden".

## Command & Skill

### /programmer command

Quick invocation command at `~/.claude/commands/programmer.md`:

```yaml
---
name: programmer
description: Invoke the programmer agent for code development tasks
aliases: [code, dev]
invokes: agent:programmer-orchestrator
---
```

### programmer-add-project skill

Project registration skill at `~/.claude/skills/programmer-add-project/SKILL.md`:

Allows registering a new project with:
- Project path
- Description
- Tech stack
- Conventions reference

Creates entry in `~/.claude/state/programmer/projects/<name>.json`.

## Files to Create

```
~/.claude/agents/
├── programmer-orchestrator.md
├── code-planner.md
├── code-implementer.md
└── code-reviewer.md

~/.claude/state/programmer/
├── session-autonomy.json
├── preferences.json
└── projects/

~/.claude/commands/
└── programmer.md

~/.claude/skills/programmer-add-project/
└── SKILL.md
```

## Files to Update

1. **CLAUDE.md** - Update hierarchy diagram to include programmer-orchestrator branch
2. **model-policy.json** - Add entries for new agents (orchestrator=opus, sub-agents=sonnet)
3. **master-orchestrator.md** - Add programmer-orchestrator to supervised agents list