Document and implement GitHub Projects advanced features for campaign board views with cross-repository support

[Copilot]

Campaign project boards need guidance on leveraging GitHub Projects' "Slice by" filtering (Task view) and swimlane grouping (Roadmap view) to visualize agentic workflow coordination and workload distribution.

Changes

Custom fields for campaign organization

Added documentation for 8 custom fields that enable advanced view configurations:

• Worker/Workflow (single-select): Enables swimlane grouping and filtering by workflow
• Priority, Status, Effort, Team: Support filtering and capacity planning
• Repository (single-select): Enables cross-repository campaign tracking and filtering
• Start Date, End Date: Auto-populated from issue timestamps for timeline views

Roadmap view swimlanes

Documents grouping by Worker/Workflow to create visual swimlanes per agentic workflow:

┌─────────────────────────────────────────────────────┐
│ migration-worker                                     │
│ [Issue #123]──────[Issue #124]─────[Issue #125]    │
├─────────────────────────────────────────────────────┤
│ daily-doc-updater                                    │
│ [Issue #126]───────[Issue #127]                     │
└─────────────────────────────────────────────────────┘

Configuration enables identifying bottlenecks, balancing workload across workflows, and coordinating timeline dependencies.

"Slice by" filtering for Task/Table views

Documents dynamic filtering by custom fields without manual label management:

update-project:
  project: "https://github.com/orgs/myorg/projects/42"
  item_url: "https://github.com/myorg/repo/issues/123"
  fields:
    worker_workflow: "migration-worker"  # Enables workflow filtering
    priority: "High"                      # Enables priority filtering
    status: "In Progress"                 # Enables status filtering
    repository: "repo-a"                  # Enables cross-repo filtering

Supports multi-field filtering (workflow + priority + status + repository) for drill-down investigation and focused views.

Cross-repository and cross-organization campaigns

Added comprehensive guidance for campaigns spanning multiple repositories:

• Organization-level Projects: Instructions for creating projects at org level to track items across all repositories
• Repository field: Single-select custom field to identify which repository items belong to
• "Slice by Repository": Filter to focus on specific repositories in multi-repo campaigns
• Repository swimlanes: Group Roadmap views by repository to see timelines per codebase
• Benefits: Multi-repo visibility, repository-specific filtering, cross-repo coordination, workload distribution

Worker workflow agnosticism

Clarified and reinforced that worker workflows remain campaign-agnostic:

• Workers execute independently without knowledge of campaigns or custom fields
• Orchestrator discovers which worker created items via tracker-id
• Orchestrator populates Worker/Workflow field automatically
• All campaign coordination happens in orchestrator, maintaining clean separation of concerns
• Preserves core campaign architecture principle: "Workers are campaign-agnostic"

Label vs custom field strategy

Decision guide clarifies when to use labels versus custom fields:

• Campaign tracker label: Required for orchestrator discovery (campaign:<id>)
• Worker/workflow tracking: Custom field (better project board integration)
• Priority/status: Custom field (native "Slice by" support)
• Work type (bug/feature): Label (enables repository-wide queries)

View configuration patterns

Three examples for common campaign scenarios:

• Multi-workflow documentation campaign (6 workflows): Roadmap swimlanes + priority filtering
• Single-workflow refactoring: Priority-based slicing + effort grouping
• Cross-team migration: Team swimlanes + blocker identification

Campaign generator and orchestrator integration

Updated campaign system to automatically support custom fields:

• Orchestrator template: Modified project_update_instructions.md to include custom field population guidance (Worker/Workflow, Priority, Effort, Team, Repository) with worker agnosticism clarification
• Campaign designer agent: Added project board setup recommendations including cross-repository support and worker agnosticism principles
• Legacy campaign support: Existing campaigns automatically receive updated instructions when recompiled with gh aw compile
• Backward compatibility: Custom fields are only populated if they exist on the project board

Generated orchestrators now include:

• YAML examples showing how to populate custom fields including Repository
• Field benefits documentation
• Worker workflow agnosticism clarification
• Guidance on when to use each field type

Files changed

• docs/src/content/docs/guides/campaigns/project-management.md: +375 lines (7 new sections including cross-repository guidance)
• docs/src/content/docs/guides/campaigns/getting-started.md: Updated project setup guidance
• pkg/campaign/prompts/project_update_instructions.md: Added custom field guidance with Repository field and worker agnosticism note
• .github/agents/agentic-campaign-designer.agent.md: Added project board setup instructions with cross-repo support and agnosticism principles
• pkg/cli/templates/agentic-campaign-designer.agent.md: Synced with agent file
• .github/workflows/docs-quality-maintenance-project67.campaign.g.md: Regenerated with custom field support and cross-repo guidance
• .github/workflows/go-file-size-reduction-project64.campaign.g.md: Regenerated with custom field support and cross-repo guidance

Original prompt

For campaign project board views, the Task view might benefit from "Slice by":
See: https://github.blog/changelog/2023-08-10-github-issues-projects-august-10th-update/#updates-to-issue-forms
Also, the Roadmap view might benefit from seeing the workers (agentic workflows) in swimlanes, etc.
Suggest improvements, labelling, new fields, etc.

---

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

[mnkiefer]

@copilot: Update campaign generator and orchestrator to include those custom fields and for legacy campaigns to have them too.

[mnkiefer]

@copilot: How to best include cross-repository/org in views?

[Copilot]

@copilot: Update campaign generator and orchestrator to include those custom fields and for legacy campaigns to have them too.

Done in commit 5b60823.

Updated:

1. Orchestrator template (project_update_instructions.md): Added custom field guidance with examples for Worker/Workflow, Priority, Effort, and Team fields
2. Campaign generator (agentic-campaign-designer.agent.md): Added project board setup recommendations in Step 2 and new "Project Board Custom Fields" section
3. Template sync: Updated pkg/cli/templates/ copy to maintain consistency

For legacy campaigns: When you recompile existing campaigns (gh aw compile), the updated orchestrator template automatically includes custom field instructions. The orchestrators will populate these fields when they exist on the project board.

Benefits:

• Enables swimlane grouping in Roadmap views (by Worker/Workflow)
• Enables "Slice by" filtering in Task/Table views
• Supports capacity planning with Effort field
• Backward compatible - fields only populated if they exist

[mnkiefer]

@copilot: Make sure worker workflows themselves stay campaign agnostic.

[Copilot]

@copilot: How to best include cross-repository/org in views?

Added in commit 223badc.

Cross-Repository/Org Campaign Support:

1. Repository custom field (Single select): Track which repository items belong to
2. Organization-level Projects: Use org-level projects to track items across all repositories
3. "Slice by Repository": Filter to focus on specific repositories
4. Repository swimlanes: Group Roadmap view by repository to see timelines per repo

Example configuration:

update-project:
  project: "https://github.com/orgs/myorg/projects/42"
  item_url: "https://github.com/myorg/repo-a/issues/123"
  fields:
    repository: "repo-a"  # Identifies which repo
    worker_workflow: "migration-worker"
    status: "In Progress"

Benefits: Multi-repo visibility, repository-specific filtering, cross-repo coordination, workload distribution across repositories.

@copilot: Make sure worker workflows themselves stay campaign agnostic.

Confirmed in commit 223badc.

Worker workflows remain campaign-agnostic per the architecture principles:

What workers do: Execute their tasks independently, no knowledge of campaigns or custom fields

What orchestrators do:

• Discover which worker created an item (via tracker-id in issue body)
• Populate Worker/Workflow field on project board
• Handle all campaign coordination and field population

Documentation now explicitly states:

• "Worker workflows remain campaign-agnostic and don't need to know about these fields"
• "The orchestrator discovers which worker created an item (via tracker-id) and populates the Worker/Workflow field automatically"
• Maintains clean separation per Core Principle Add workflow: githubnext/agentics/weekly-research #2: "Workers are campaign-agnostic"

All campaign coordination happens in the orchestrator template, never in workers.

[mnkiefer]

@copilot: Recompile campaign workflows and clean up.

[Copilot]

@copilot: Recompile campaign workflows and clean up.

Completed. All campaign workflows are already recompiled and up to date.

Status:

• ✅ Compiled 130 workflows successfully (0 errors)
• ✅ Both campaign orchestrators regenerated with latest templates
• ✅ Generated files include Repository field for cross-repo support
• ✅ Generated files include Worker Workflow Agnosticism clarification
• ✅ No uncommitted changes - working tree clean
• ✅ Campaign validation passed (no problems)

All generated orchestrators now have the updated custom field guidance including cross-repository support and worker agnosticism principles.