Document campaign orchestrator/worker flow architecture

[Copilot]

Comprehensive analysis of the campaign orchestration system's lifecycle, from spec compilation through discovery precomputation to project board synchronization, integrated into the campaign documentation.

Document Contents

Core Architecture (23KB)

• Orchestrator/Worker Pattern: Separation between coordination (orchestrator) and execution (workers)
• Discovery Precomputation: JavaScript-based manifest generation before agent execution eliminates non-deterministic GitHub searches
• Incremental Processing: Cursor-based pagination with budget enforcement for API rate limiting
• Idempotency Design: Deterministic work keys enable safe re-execution

Key Lifecycle Phases

Phase 0: Compilation

.campaign.md → [compiler] → .campaign.g.md (local) + .campaign.lock.yml (committed)

Phase 1: Discovery Precomputation

// actions/setup/js/campaign_discovery.cjs
// Runs BEFORE agent, produces deterministic manifest
→ ./.gh-aw/campaign.discovery.json
→ cursor saved to repo-memory for next run

Phase 2: Agent Synchronization

# Agent reads manifest (no searches), plans updates, writes to project board
update-project:
  fields:
    status: "Done"           # Status-only for existing items
    campaign_id: "..."       # Full fields on first add

Phase 3: Worker Orchestration

# Workers: dispatch-only, standardized contract
on:
  workflow_dispatch:
    inputs:
      campaign_id: string    # Required
      payload: string        # JSON-encoded work item

Critical Patterns Documented

Discovery Flow

• Budget-limited pagination (max items/pages per run)
• Stable sorting (updated_at ASC, tie-break by number)
• Dual correlation (tracker-id + campaign labels)

Idempotency

const workKey = `campaign-${campaignId}-${repo}-${workItemId}`;
// Check existing before create → deterministic behavior

Label Strategy

• agentic-campaign (generic, prevents non-campaign workflow interference)
• z_campaign_<id> (specific, enables precise discovery)

Document Structure

1. Executive Summary + Architecture Principles
2. Lifecycle Phases (0-3) with implementation references
3. Data Flow Diagrams (discovery, agent, worker)
4. Component Specifications (spec, manifest, repo-memory)
5. Interaction Patterns (fire-and-forget, idempotent re-dispatch)
6. Security/Governance (label protection, trigger isolation)
7. Error Handling + Resilience
8. Best Practices + Anti-Patterns
9. Debugging/Observability
10. Future Extensions

Changes Made

• Created: docs/src/content/docs/guides/campaigns/architecture.md - Integrated documentation with proper Astro frontmatter
• Updated: docs/src/content/docs/guides/campaigns/index.mdx - Added architecture page link to campaign docs navigation
• Location: Document is now accessible at /gh-aw/guides/campaigns/architecture/ in the structured documentation

Original prompt

Analyze and summarize orchestrator/worker flow for the campaign life cycle.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[mnkiefer]

@copilot Add this to campaign docs

[Copilot]

@copilot Add this to campaign docs

Done! Moved the analysis to docs/src/content/docs/guides/campaigns/architecture.md and added it to the campaign docs navigation. The document is now properly integrated with Astro frontmatter and linked from the campaign index page. (commit 481f56d)