Agent Workflow System

A structured development workflow for multi-agent software development.

---

Quick Links

Document	Purpose
Implementation Plan	Phased rollout plan
PROPOSAL.md	Full design document

Roles

Role	Description
PM	Triages issues, writes requirements
Tech Lead	Creates specs, coordinates coders
Coder	Implements tasks, opens PRs
Reviewer	Reviews PRs for quality

Workflows

Workflow	When to Use
Feature Development	New feature, idea → production
Bug Fix	Fixing reported bugs
Code Review	PR review process

Prompts

Prompt	For Role
PM Triage	PM during heartbeat
Task Breakdown	TL speccing an issue
Coder Brief	TL spawning coder
Code Review	TL spawning reviewer

Context

Document	Purpose
Seeding Strategy	How to pass context efficiently
CONTEXT Template	Per-project context file

Templates

Template	Purpose
PM State	PM session state
TL State	TL session state
Coder State	Coder session state
Reviewer Brief	Reviewer spawn brief

---

The Flow

User Request
    ↓
[inbox] Issue Created
    ↓ PM triage
[backlog] Requirements added, priority set
    ↓ TL picks up
[ready] Tech spec, branch created
    ↓ Coder spawned
[in-progress] Implementation
    ↓ PR opened
[review] 2 reviewers assigned
    ↓ 2 approvals
[approved] Ready to merge
    ↓ TL merges
[done] Issue closed

---

Getting Started

Phase 1: Setup Labels (Do This First)

# Run in your project repo
cd ~/projects/{repo}

# State labels
gh label create "state:inbox" --color FBCA04
gh label create "state:backlog" --color 0052CC
gh label create "state:ready" --color 0E8A16
gh label create "state:in-progress" --color 5319E7
gh label create "state:review" --color D93F0B
gh label create "state:approved" --color 1D76DB
gh label create "state:blocked" --color B60205
gh label create "state:done" --color EDEDED

# Role labels
gh label create "role:pm" --color FEF2C0
gh label create "role:tl" --color C2E0C6
gh label create "role:coder" --color BFDADC

# Priority labels
gh label create "priority:p0" --color B60205
gh label create "priority:p1" --color D93F0B
gh label create "priority:p2" --color FBCA04
gh label create "priority:p3" --color 0E8A16

Phase 2: Create CONTEXT.md

Copy templates/CONTEXT-template.md to obsidian-vault/projects/{project}/CONTEXT.md and fill it out.

Phase 3: Start Using the Flow

1. Create an issue with state:inbox
2. During heartbeat, PM triages
3. TL specs and spawns coders
4. Coders implement and open PRs
5. Reviewers review
6. TL merges

---

Model Allocation

Role	Model	Why
PM	Opus	Coordination, judgment
Tech Lead	Opus	Architecture, review
Coder	Sonnet	Implementation
Reviewer	Opus	Quality judgment

---

Key Principles

1. Context in files, not memory — Agents are amnesiac
2. Point to files, don't dump — Save tokens
3. One agent per branch — Avoid conflicts
4. 2 reviews required — Quality gate
5. State files at checkpoints — Enable continuation

---

File Structure

obsidian-vault/projects/{project}/
├── CONTEXT.md              # Project context (agents read this)
├── README.md               # Human overview
├── decisions/              # ADRs
└── specs/                  # Technical specifications

memory/subagents/
├── active/                 # Live session state
│   ├── pm-{project}-state.md
│   ├── tl-{project}-state.md
│   └── coder-{project}-{task}-state.md
├── archive/                # Completed sessions
└── templates/              # Copy-paste starters

---

Status

• Proposal written
• Roles defined
• Workflows documented
• Prompts created
• Context strategy defined
• Labels created (Phase 1)
• MATE CONTEXT.md created (Phase 2)
• First issue through flow (Phase 3)