Summary request: campaigns evolution

[mnkiefer]

Summary request: campaigns evolution in this repository

We would like to analyze the history of campaigns in this repository and produce a structured summary of how the campaigns area has developed over time.

What to cover

1. Origin

   • When campaigns first appeared in the repo
   • The earliest files, models, endpoints, UI, or workflows related to campaigns
   • The initial purpose and scope

2. Major evolution

   • Key milestones in how campaigns changed over time
   • Important refactors, redesigns, or architecture changes
   • Changes to data models, APIs, business logic, background jobs, or UI flows
   • Any shifts in terminology, ownership, or feature boundaries

3. Important PRs / commits / issues

   • Identify the most important pull requests, commits, and issues related to campaigns
   • Explain what changed in each and why it mattered
   • Group related changes into phases where possible

4. Current state

   • How campaigns are implemented today
   • Main entry points in the codebase
   • Key files, modules, services, and tests
   • Any known limitations, TODOs, or unfinished areas

5. Narrative timeline

   • Provide a chronological timeline of campaign-related developments
   • Include approximate dates and links to supporting PRs/commits/issues where available

Output format

Please provide:

• An executive summary
• A chronological timeline
• A phase-by-phase breakdown of campaign evolution
• A current architecture/code map
• A list of notable PRs, commits, and issues
• A short section on open questions / risks / follow-up areas

Research guidance

Please search for campaign-related code and history broadly, including:

• filenames, symbols, routes, docs, tests, migrations, and configs
• terms such as campaign, campaigns, and any renamed equivalents if discovered
• relevant GitHub issues, pull requests, and commit history

If the term "campaign" is overloaded in this repository, distinguish between the different meanings and summarize each separately.

[mnkiefer]

/scout history=full

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report — Campaigns Evolution in github/gh-aw

Triggered by @github-actions[bot]

Executive Summary

"Campaigns" in gh-aw began as a small update-project safe-output capability in Nov 2025, grew into a first-class subsystem with its own pkg/campaign package, .campaign.md spec format, gh aw campaign CLI, orchestrator generator, designer, and AI-powered generator across Dec 2025, then was deliberately de-framed in Feb 2026: campaigns were reinterpreted as a pattern on top of normal agentic workflows rather than a separate workflow type. The dedicated package, CLI, designer agent, and .campaign.md spec were removed; only the reusable primitives (tracker-id, update-project safe-output, call-workflow, repo/cache-memory) and a reference playbook remain. The term "campaign" today lives on (a) as a documented design pattern, (b) in a few production workflows (e.g. dependabot-campaign.md), and (c) in the unrelated ab-testing-advisor "experiment campaign" automation that produces dozens of A/B experiment issues.

Term overload (resolved up front)

• Agentic campaign — the main meaning: a time-bounded, goal-driven, multi-workflow initiative tracked via projects/issues. This is the subject of the timeline below.
• Experiment campaign — used by the ab-testing-advisor workflow to label individual A/B test experiments (e.g. "[ab-advisor] Experiment campaign for daily-fact: A/B test prompt_style"). Same word, different feature; not part of the agentic-campaigns lineage.

Click to expand detailed findings

Chronological timeline

Date	PR	What changed
2025-11-09	#3524	Origin. mnkiefer adds update-project safe-output and ships an "AI Triage Campaign" example workflow. Concept of "Campaigns" introduced in docs.
2025-11-12	#3737	Renames frontmatter field fingerprint → campaign.
2025-11-18	#4289	Renames campaign → tracker-id (the name that survives to today).
2025-11-20	#4415	Adds assign-to-agent campaign capability.
2025-12-11	#6082	First-class campaigns. Adds .campaign.md specs, gh aw campaign CLI (status, validate, new), governance fields (owners, risk_level, approval_policy).
2025-12-11	#6136	Refactors campaign code into pkg/campaign with JSON-schema validation + tests.
2025-12-11	#6162	Interactive campaign designer.
2025-12-12	#6226	Orchestrator generator. BuildOrchestrator compiles .campaign.md into scheduled orchestrator workflows. Initial campaigns shipped: file-diet, incident-response, org-modernization, security-compliance.
2025-12-14	#6407	Migrates schema validation from gojsonschema to santhosh-tekuri/jsonschema.
2025-12-16	#6636	AI-powered campaign generator — issue-form → spec via agentic workflow.
2025-12-18	#6816	Decouples orchestrators from workers using tracker-id (tracker-based monitoring instead of label coupling).
2025-12-19	#6984	Renames "Campaigns" → "Agentic campaigns", promotes to top-level nav. CLI/file ext kept (gh aw campaign, .campaign.md).
2025-12-21	#7135 → #7139	Adds campaign launcher; immediately consolidates it into the orchestrator.
2025-12-22	#7237 / #7279	Adds Objective + KPIs to the campaign spec and orchestrator templates.
2025-12-29	#8079	GitHub MCP toolsets for Campaign Manager observability.
2025-12-31	#8228	Security fix: incorrect file permissions in campaign spec creation (Alert #390).
2026-01-15	#10059	(Closed, not merged) First attempt: "Remove campaigns feature." Build broke; abandoned.
2026-01-19	#10747	Ships the Security Alert Burndown campaign — orchestrator + worker + KPIs. The flagship example of the by-now-mature framework.
2026-02-03	#13515, #13571, #13572, #13573, #13596	The "de-framing". Removes the campaign-designer agent, drops campaign-id from workflows, strips campaign-specific dispatcher routing, deletes campaign terminology from docs, updates tests.
2026-02-03	#13518	Dispatcher only includes campaign routing when gh aw init --campaign is passed.
2026-02-17	#16436	Reframe as a pattern. Adds .github/aw/campaign.md playbook: "campaign and KPI workflows are patterns within agentic workflows, not separate workflow types."
2026-03-08	#20109	Inlines campaign-discovery logic directly into the workflow step; removes standalone campaign_discovery.cjs.
2026-03-15 / 03-20	#21066, #21998	Permissions + epic-dedup fixes for the still-running Security Alert Burndown campaign.
2026-05-13	#32019	[caveman] instruction-verbosity optimization touches the campaign playbook (.github/aw/campaign.md) among others.

Phase-by-phase breakdown

Phase 1 — Capability seed (Nov 2025)

Campaigns enter the codebase not as a feature, but as a safe-output (update-project) that lets an agentic workflow write to a GitHub Projects v2 board. The first real example is the AI Triage Campaign — a single workflow that picks ~10 AI-ready issues and pushes them onto a project board for Copilot. The frontmatter field used to correlate runs is renamed twice: fingerprint → campaign → tracker-id within ten days. That naming churn is the strongest signal that the team was still feeling out the concept.

Phase 2 — First-class subsystem (Dec 2025)

The concept gets a full architecture in three weeks:

• Spec format: .campaign.md with YAML frontmatter (id, owners, workflows, risk_level, state, tracker_label, memory_paths, metrics_glob, approval_policy).
• Code home: pkg/campaign/ with schema validation.
• CLI: gh aw campaign (list, status, validate, new).
• Orchestrator generator: BuildOrchestrator compiles a spec into a scheduled coordinator workflow.
• Designer / generator: interactive designer + an AI-powered generator triggered by an issue form.
• Worker decoupling: workers are discovered via tracker-id, not labels.
• KPIs and Objectives added to the spec.

Four seed campaigns ship: file-diet, incident-response, org-modernization, security-compliance.

Phase 3 — De-framing (Jan–Feb 2026)

After ~6 weeks of production use, the team concludes campaigns don't need to be a separate type — the building blocks already exist. Over a single Feb-3 day, five PRs strip the campaign-designer agent, the campaign-id field, the dispatcher routing, and the docs terminology. The CLI command and .campaign.md extension are removed from the core flow; the pkg/campaign package is retired. The Security Alert Burndown campaign (shipped just two weeks earlier) keeps running on the surviving primitives.

Phase 4 — Pattern-as-a-document (Feb 2026 → today)

PR #16436 recasts campaigns as a playbook: .github/aw/campaign.md. Today campaigns are written as ordinary .md workflows that combine three reusable primitives: tracker-id:, safe-outputs.update-project (board), and safe-outputs.call-workflow (worker fan-out). Examples now in the repo: dependabot-campaign.md, issue-monster.md, security-compliance.md. The Security Alert Burndown campaign was the live test of this stripped-down model and remains the canonical example.

Current architecture / code map (May 2026)

• Pattern playbook: .github/aw/campaign.md — design principles, pacing levers, KPI workflow template, cross-repo coordination.
• Reference workflow: .github/workflows/dependabot-campaign.md (+ .lock.yml).
• Surviving primitives:
  • tracker-id: frontmatter field — at least 20 workflows use it (parser: pkg/workflow/frontmatter_types.go; tests: pkg/workflow/tracker_id_test.go, tracker_id_integration_test.go).
  • safe-outputs.update-project — Projects v2 writes (handler config in pkg/workflow/update_project_handler_config_test.go).
  • safe-outputs.call-workflow — worker fan-out.
  • cache-memory + repo-memory — state across runs.
• Triggering tests: pkg/workflow/campaign_trigger_test.go (issue-form [opened, labeled] trigger pattern from the old campaign generator, kept for the issue #6721 regression).
• Example/spec: pkg/cli/workflows/example-campaign.md — illustrates tracker-id (still named for the old feature).
• Docs / blog: docs/src/content/docs/blog/2026-01-13-meet-the-workflows-campaigns.md (now titled "Project Coordination" / "Campaigns & Projects"); operational and design-patterns blog posts reference the playbook.
• Known dead-doc: pkg/cli/compile_file_operations.go:27 still references the removed compileAllCampaignOrchestrators() helper in its header comment.
• Independent feature reusing the word: ab-testing-advisor workflow opens "Experiment campaign for ..." issues; these are A/B-test runs, not agentic campaigns.

Open questions / risks / follow-ups

• Stale doc reference: pkg/cli/compile_file_operations.go:27 still names compileAllCampaignOrchestrators() — the function no longer exists. Worth removing in a janitor pass.
• Naming overload: "campaign" still means two unrelated things in repo metadata — the agentic-campaign pattern and ab-testing-advisor "experiment campaign" issues. Worth a glossary note if the docs ever revisit this area.
• Documentation lag: the Meet the Workflows: Campaigns blog post (Jan 13, 2026) was written when the first-class subsystem existed; some of its links/screenshots predate the Feb 2026 de-framing.
• No surviving pkg/campaign but plenty of frontmatter/tooling still implicitly assumes the pattern (tracker-id, update-project, call-workflow). Any future refactor should treat the playbook as the source of truth, since the code is now "just workflows."

Suggested next steps

1. Trim the dead comment in pkg/cli/compile_file_operations.go:27.
2. Add a short glossary entry distinguishing agentic campaign from experiment campaign.
3. Treat .github/aw/campaign.md as the canonical spec; cross-link it from the campaigns blog post.
4. Audit which currently-running workflows still self-identify as campaigns (search: tracker-id: + safe-outputs.update-project) and consider listing them in the playbook as worked examples.

References:

• Campaign playbook (.github/aw/campaign.md)
• Workflow Run §26243062493

🔭 Intelligence gathered by Scout · ● 13.4M · ◷