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

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

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

Create initial state files:

~/.claude/state/programmer/session-autonomy.json

{
  "level": "conservative",
  "overrides": {}
}

~/.claude/state/programmer/preferences.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

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

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