Workflow Coordination for Agents

Agents collaborate better when they have a centralized, persistent store for coordination. The underlying pattern is structured metadata that enables automated routing and state tracking—GitHub is one accessible implementation, but the same principles apply to Linear, Jira, Notion, or even a local file-based system.

The Underlying Pattern

What makes workflow coordination work isn't the specific tool—it's the structure:

1. Canonical source for workflow decisions: One place where task state lives
2. Structured metadata categories: Labels, tags, or fields that enable routing
3. Machine-parseable relationships: Explicit dependencies between work items
4. Persistent artifacts: Context that survives session boundaries

GitHub implements these through issues, labels, and PRs. Linear uses issues and projects. A local system might use a JSON file or SQLite database. The patterns transfer.

GitHub as One Implementation

The following sections use GitHub as a concrete example. Adapt the patterns to your coordination system:

The Core Principle

Use version control platform as the primary communication medium between agents.

Why this works:

• Persistence: Context survives session boundaries
• Structure: Issues, PRs, labels provide natural organization
• Traceability: Git history shows evolution of decisions
• Human-readable: Developers can follow along and intervene
• Machine-parseable: Agents can query via gh CLI

Structured Metadata Categories

The key pattern: define mandatory categories that enable automated routing. Work items need enough structure that agents can parse and act on them without human intervention.

Example: Four-Category Taxonomy

One effective taxonomy uses four categories—adapt the specifics to your domain:

The categories matter more than the specific values. Your system might use:

• Type instead of Component (feature, bug, chore, refactor)
• Urgency instead of Priority (now, soon, later, someday)
• Size with story points instead of Effort

Why This Enables Automation

With structured categories, agents can:

• Route automatically: "Component:database" → spawn database expert
• Prioritize without judgment: Sort by priority, then effort, then age
• Track state machines: Status labels enforce allowed transitions
• Validate completeness: Reject work items missing required categories

Validation pattern (GitHub example):

gh label list --limit 100 | grep -E "component:|priority:|effort:|status:"

This prevents drift and ensures consistency across agent sessions. The equivalent in other systems: query your API or database for the allowed values before creating work items.

Work Item Relationships

The pattern: explicit, machine-parseable relationships between work items enable dependency-aware scheduling. Without these, agents treat every task as independent.

Relationship Types

Six relationship types cover most scenarios:

Machine-Parseable Format

Whatever your system, relationships need consistent format. Example using markdown:

## Relationships
 
- **Depends On**: #25 (API key generation) - Required for auth middleware
- **Blocks**: #74, #116 (symbol extraction, search) - Provides AST foundation
- **Related To**: #42 (user settings) - Shares config patterns

The specifics matter less than consistency. Agents can parse:

• Linear's built-in relations
• Jira's "is blocked by" / "blocks" links
• A JSON field in a local database
• Markdown sections with predictable format

Agents use these to build dependency graphs for prioritization—identifying unblocked high-leverage items (those that unblock others).

The Issue-to-PR Workflow

┌─────────────┐
│ Issue Created │
│ (with labels) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Plan Written │
│ docs/specs/  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Branch Created │
│ from issue #   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Implementation │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PR Submitted │
│ refs issue   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Review/Merge │
└─────────────┘

Branch naming from issue

# Fetch issue metadata
gh issue view <issue-number> --json number,title,labels
 
# Map labels to branch type:
# bug label → bug/
# enhancement/feature → feature/
# chore/maintenance → chore/
 
# Format: <type>/<issue-number>-<slug>
# Example: feature/123-add-user-authentication

PR references issue

## Summary
Brief description of changes
 
## Changes
- Bullet points of what changed
 
## Test Plan
- How to verify
 
Closes #123

The Closes #123 creates the link back to the originating issue.

Spec Files as Persistent Context

Plans live in docs/specs/ with issue numbers in filenames:

docs/specs/feature-123-user-auth.md
docs/specs/bug-456-token-refresh.md

This creates traceability:

• Issue #123 → docs/specs/feature-123-*.md → feature/123-* branch → PR

Future agents can reconstruct context by following these breadcrumbs.

Spec Files Beat Accumulated Context

[2025-12-09]: Rather than passing large contexts between agents in messages, write findings to disk as spec files. Each agent reads the same spec independently, avoiding context bloat and enabling parallel access to shared state.

This pattern has several advantages:

1. No context accumulation: Messages stay focused, avoiding the "wall of text" problem in multi-agent handoffs
2. Parallel access: Multiple agents can read the same spec simultaneously without coordination
3. Version control: Specs are tracked in Git, providing history and rollback
4. Session survival: Context persists across agent restarts and crashes
5. Human readability: Developers can inspect and override agent decisions

Anti-pattern (context passing):

Orchestrator → Build Agent: "Based on the analysis from Scout Agent (3000 words),
and the design from Planning Agent (2000 words), implement feature X..."

Better (spec-based):

Orchestrator → Build Agent: "Read .claude/.cache/specs/feature-123-spec.md
and implement according to the design section"

The spec file becomes the single source of truth. Agents coordinate by reading and writing to it, not by accumulating context in conversation threads.

Validation Evidence in PRs

PRs include structured validation sections:

## Validation Evidence
 
### Level: 2 (Integration)
 
**Commands Run**:
- ✅ `bun run lint`
- ✅ `bun test --filter integration` - 42 tests passed
- ✅ `bun run build`
 
**Real-Service Evidence**:
- Supabase: SELECT returned expected rows
- Auth flow: Token refresh successful

Three validation levels:

1. Docs-only: Linting, formatting
2. Integration: Real service tests
3. Full E2E: Complete user flows

Output Format Discipline

Agents must not leak reasoning into artifacts. Forbidden patterns:

• "Let me..." / "I'll..."
• "Based on the..." / "Looking at..."
• "Great!" / "Successfully!"
• "First, I'll check..."

Bad (meta-commentary):

Let me create a branch for this issue. Based on the labels,
I'll use the feature/ prefix. Great, the branch was created successfully!

Good (artifact only):

Branch: feature/123-add-user-auth
From: develop (abc1234)
Issue: #123 - Add user authentication

Production artifacts (commits, PRs, issues) should contain decisions, not reasoning.

Specialized Agents for GitHub Operations

Delegate GitHub operations to focused agents:

This reduces context contamination in the main agent and ensures consistency.

Metrics to Track

Velocity

• Commit frequency: >5/day indicates healthy pace
• PR turnaround: <2 days suggests efficient review
• Feature completion: Issues closed vs. opened

Quality

• CI failure rate: <5% suggests robust gates
• Post-release bugs: <1% indicates effective testing

Agent Collaboration

• Context handoff success via GitHub
• Pattern consistency across sessions
• Knowledge accumulation in issues/PRs

Alternative: Database-Backed Communication

[2025-12-08]: For faster-moving workflows, expose CRUD operations on a shared communications store via MCP tools or function calling. This provides:

• Lower latency than GitHub API
• More flexible schema
• Better suited for real-time coordination

GitHub remains better for:

• Human oversight and intervention
• Long-lived context (issues that span weeks)
• Integration with existing dev workflows

The patterns (labels, relationships, validation evidence) apply to both.

Questions to Explore

• How do agents handle GitHub API rate limiting during parallel operations?
• What's the escalation path when a PR is stuck in review?
• How do you detect and prevent issue relationship cycles?
• When should agents comment on issues vs. create new ones?

Connections

• Multi-Agent Orchestration: GitHub as coordination layer for multi-agent systems
• Context Management: Issues/PRs as persistent context stores
• Production Concerns: GitHub workflows as part of deployment pipeline

Source Examples

These patterns were extracted from real project configurations:

KotaDB

• issue.md: Issue creation with four-category labeling
• issue-relationships.md: Machine-parseable relationship format
• pull_request.md: PR validation evidence sections
• commit.md: Conventional commits with meta-commentary detection
• prioritize.md: Dependency-aware prioritization