Update campaign documentation for orchestrator architecture and propose improvements

[Copilot]

Campaign documentation was outdated, missing details on discovery precomputation, cursor-based incremental processing, and governance policies. Also created a comprehensive improvements proposal for future enhancements.

Updated Core Documentation

campaigns.md

• Documented two-phase orchestrator: discovery precomputation (GitHub Script) → agent coordination (manifest-driven updates)
• Explained cursor-based incremental discovery with deterministic ordering
• Defined metrics snapshot schema (required: campaign_id, date, tasks_total, tasks_completed)

specs.md

• Governance policies: max-discovery-items-per-run, max-discovery-pages-per-run, max-project-updates-per-run, max-comments-per-run
• Optional project-github-token field for Projects v2 custom token
• Clarified KPI priority syntax: priority: primary (not primary: true)

getting-started.md

• Updated compilation flow: spec → orchestrator generation (discovery step + agent job) → .campaign.lock.yml

New: Improvements & Future Directions

Created improvements.md with 5 enhancement proposals prioritized by value:

High Priority

1. Summarized reports: Aggregate metrics across runs, post markdown summaries to Epic issues
2. Adaptive orchestration: Read historical metrics to adjust discovery budgets dynamically

Medium Priority

3. Learning system: Capture patterns (discovery efficiency, worker performance, governance tuning) in memory/campaigns/<id>/learnings.json
4. Retrospectives: Auto-generate completion analysis with KPI outcomes and recommendations

Low Priority

5. Cross-campaign analytics: Portfolio dashboard for multi-campaign health tracking

Each proposal includes configuration examples, format templates, and implementation guidance.

Screenshots

Main campaigns guide with orchestrator architecture:

New improvements document:

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/20.19.6/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/20.19.6/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev owner --uid-owner 0 -j ACCEPT 5036-9064/test-1gh mpile pkg/mod/golang.o/repos/actions/github-script/git/ref/tags/v8 infocmp -1 /ref/tags/v8 pkg/mod/golang.org/toolchain@v0.0.1-go1.25.0.lin/home/REDACTED/work/gh-aw/gh-aw/scripts/lint_error--norc 6/x64/bin/node 641488/b402/mathiptables t 641488/b402/impo-t infocmp (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Update campaign documentation according to latest implementation changes (in orchestrator, etc.). Create a report on what could be improved and how campaigns can create summarized reports/make use of learnings.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using Astro Starlight and GitHub Docs voice

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@mnkiefer oops I merge the unbloater PR and it broken this one...

[mnkiefer]

@mnkiefer oops I merge the unbloater PR and it broken this one...

@pelikhan: Just a minor conflict, resolved now. Will merge once pipeline are green. 👍🏼