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:

## 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:

{
  "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/.json

Per-project context:

{
  "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:

---
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