Add programmer agent design document

Design for a new programmer-orchestrator agent with sub-agents for planning, implementation, and code review. Includes workflow enforcement, project memory via state files, and autonomy controls. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-29 12:48:02 -08:00
parent 89bffd00e6
commit 8adc437cfc
1 changed files with 273 additions and 0 deletions
--- a/docs/plans/2025-12-29-programmer-agent-design.md
+++ b/docs/plans/2025-12-29-programmer-agent-design.md
@@ -0,0 +1,273 @@
+# 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