---
id: 45c21973-7fae-4cf7-b247-b40a757d54b0
type: decision
title: "Issue Worker Agent: Phased Workflow Architecture"
tags: [claude-configs, issue-worker, agent-design, gitea, automation, workflow, cognitive-memory]
importance: 0.7
confidence: 0.8
created: "2026-03-02T20:19:30.456720+00:00"
updated: "2026-03-02T20:20:08.207657+00:00"
relations:
  - target: b27fb831-811e-4103-b5f1-3c36d5b1ad20
    type: RELATED_TO
    direction: outgoing
    strength: 0.9
    edge_id: a1813354-3f35-46b8-9689-9d259413bf6e
  - target: 73646e80-a640-4316-b7c6-54a4330f1b28
    type: RELATED_TO
    direction: outgoing
    strength: 0.87
    edge_id: c078c5fc-c046-411b-8807-d52f1a4c399f
  - target: 1052e91d-58ed-4308-87e8-e01d1143a146
    type: RELATED_TO
    direction: outgoing
    strength: 0.77
    edge_id: 21f44795-4134-4ebf-b242-0d233ab82a17
  - target: 4321bee8-105e-4fc8-b645-964d1234c966
    type: BUILDS_ON
    direction: outgoing
    strength: 0.95
    edge_id: 0924ac34-ddaa-4eba-ad0f-743077be7354
  - target: c4b2f42d-b443-447f-8a05-bba099e06036
    type: RELATED_TO
    direction: outgoing
    strength: 0.9
    edge_id: 6b20858b-0402-4dfb-ae93-6cf4a0afb86d
  - target: d326094f-63eb-4b42-8aa6-f2d53d6f2628
    type: REQUIRES
    direction: outgoing
    strength: 0.85
    edge_id: 89529f58-d709-46e1-bbdd-c0636ee41b21
  - target: 6ce2055a-b51b-45e4-8ff0-d34b385f7552
    type: RELATED_TO
    direction: outgoing
    strength: 0.7
    edge_id: 6f390811-ecf9-4a2a-a28c-849d585fe9a6
---

# Issue Worker Agent: Phased Workflow Architecture

## Context
Rewrote the issue-worker agent at `~/.claude/agents/issue-worker.md` from a flat 10-step workflow into 4 distinct phases. Config synced to Gitea at commit `a62f16d`.

## Architecture

### Phase 1: Understand
- Read issue from Gitea
- Explicitly read `CLAUDE.md` before any code work
- Assess feasibility
- Add `status/in-progress` label to issue

### Phase 2: Implement
- Explore relevant code
- Create branch using `-B` flag for retry safety
- Implement fix
- Run tests with auto-discovery: `CLAUDE.md` → `Makefile` → `pyproject.toml` → `package.json` → `Cargo.toml`

### Phase 3: Review & Ship
- Self-review via `git diff` before committing (avoids needing a second cleanup commit)
- Commit and push
- Create PR via `gitea-mcp`
- Swap labels: remove `status/in-progress`, add `status/pr-open`
- Comment on original issue with PR link

### Phase 4: Remember
- Store cognitive memory of fix with proper tags
- Create graph edges to related memories using `memory_relate`

## Key Decisions

### Branch Naming
- Changed from `ai/<repo>#<issue_number>` to `ai/<repo>-<issue_number>`
- Reason: `#` causes shell interpretation issues and URL encoding problems

### MCP Tools Added
- `edit_issue` — for swapping labels during phase transitions
- `memory_search` — for finding related existing memories in Phase 4
- `memory_relate` — for creating graph edges in Phase 4

### Self-Review Placement
- `git diff` review placed before commit, not after
- Avoids needing a follow-up fixup commit for issues caught post-commit