Knowledge Vault

Multi-Agent Workflow

2 min read

Overview

The AP multi-agent workflow is a parallel AI execution pattern built around a Ghostty 4-pane terminal layout: one shell pane, one Claude Code Opus primary lane (for architecture and planning), and two GitHub Copilot CLI Sonnet background lanes (for independent task execution). Tasks are coordinated through a .management/copilot-tasks.md file that acts as the single source of truth for assignment — containing a task table, claim protocol, quality gates definition, and an off-limits table. The pattern was validated across 12 seeded tasks, with Copilot CLI successfully completing 8 independently; the 2 quality gate failures were caught by the gate mechanism, which is the system working as designed.

Key Concepts

  • Branch-based claims — An agent claims a task by creating a branch named background/task-BG-NNN. The branch name is the claim: git checkout -b fails atomically if the branch already exists, preventing double-claims without requiring a coordination server.
  • Lane separation — Claude Code handles Tier 1 work (architecture, security decisions, cross-cutting concerns) while Copilot CLI handles Tier 3 work (bulk refactoring, independent implementation, low-to-medium complexity tasks). The division maps cleanly to the tiered routing framework.
  • Off-limits table — A mandatory section in .management/copilot-tasks.md listing files and directories background agents must not modify. Prevents context pollution from agents reading too broadly and making bad architectural assumptions.
  • Quality gates — Every completed background task must pass lint, type check (if applicable), existing tests, and build before merging. Gates are enforced at PR review, not commit time.
  • Context pollution risk — The primary failure mode: background agents that read beyond their task scope can make changes based on stale or incomplete architectural understanding. The off-limits table and narrow task scoping mitigate this.
  • Session-level limitation — Branch claims prevent cross-tool conflicts but do not prevent multiple Claude Code sessions from starting the same task. Tasks must be assigned to specific sessions explicitly to avoid this.

Graph View

Backlinks