Add programmer agent implementation handoff

Actionable handoff document with specific tasks for implementing
the programmer agent system.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

@@ -0,0 +1,159 @@
+# 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
+```