Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 4 additions & 7 deletions .github/aw/campaign-creation-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,24 +183,21 @@ Generated files:
## Best Practices

1. **Start simple** - One clear goal per campaign
2. **Use passive mode first** - Monitor before enabling active execution
3. **Reuse workflows** - Check existing before creating new
4. **Minimal permissions** - Grant only what's needed
5. **Escalate when unsure** - Create issues for human review
2. **Reuse workflows** - Check existing before creating new
3. **Minimal permissions** - Grant only what's needed
4. **Escalate when unsure** - Create issues for human review

### DO:
- ✅ Use unique kebab-case campaign IDs
- ✅ Scan existing workflows before suggesting new
- ✅ Apply least privilege for safe outputs
- ✅ Start with passive mode
- ✅ Follow operation order for project-based campaigns

### DON'T:
- ❌ Create duplicate campaign IDs
- ❌ Skip workflow discovery
- ❌ Grant unnecessary permissions
- ❌ Enable execute-workflows for first campaign

---

**Last Updated:** 2026-01-13
**Last Updated:** 2026-01-15
97 changes: 2 additions & 95 deletions docs/src/content/docs/guides/campaigns/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ This guide is the shortest path from “we want a campaign” to a working dashb
Before creating your first campaign, keep these core principles in mind:

- **Start small**: One clear goal per campaign (e.g., "Upgrade Node.js to v20")
- **Start with ProjectOps pattern**: Use default mode (no `execute-workflows` flag) first to observe behavior and build trust
- **Understand the progression**: ProjectOps pattern (tracking only) → Campaign orchestration (autonomous execution)
- **Reuse workflows**: Search existing workflows before creating new ones
- **Minimal permissions**: Grant only necessary permissions (issues/draft PRs, not merges)
- **Standardized outputs**: Use consistent patterns for issues, PRs, and comments
Expand All @@ -32,10 +30,6 @@ The campaign generator automatically creates:

Create `.github/workflows/<id>.campaign.md` with frontmatter like:

**For your first campaign** (ProjectOps pattern - recommended):

This uses the **ProjectOps pattern** with campaign structure. The orchestrator tracks work created by independent workflows on a project board and reports progress toward objectives. See the [ProjectOps Guide](/gh-aw/examples/issue-pr-events/projectops/) for more on this pattern.

```yaml
id: framework-upgrade
version: "v1"
Expand All @@ -44,40 +38,6 @@ name: "Framework Upgrade"
# Project board URL will be generated automatically
tracker-label: "campaign:framework-upgrade"

objective: "Upgrade all services to Framework vNext with zero downtime."
kpis:
- id: services_upgraded
name: "Services upgraded"
priority: primary
direction: "increase"
baseline: 0
target: 50
time-window-days: 30

workflows:
- framework-upgrade # Use an existing workflow (runs independently)

# Governance (conservative defaults for first campaign)
governance:
max-new-items-per-run: 5
max-project-updates-per-run: 5
max-comments-per-run: 3
```

**Note:** The campaign generator will automatically create a GitHub Project board with the project URL if not provided. You can also specify an existing project URL using `project-url: "https://github.com/orgs/ORG/projects/1"`.

**For experienced users** (campaign orchestration - advanced):

This enables **campaign orchestration** mode. The campaign actively executes workflows, creates missing ones, and drives progress autonomously.

```yaml
id: framework-upgrade
version: "v1"
name: "Framework Upgrade"

project-url: "https://github.com/orgs/ORG/projects/1"
tracker-label: "campaign:framework-upgrade"

objective: "Upgrade all services to Framework vNext with zero downtime."
kpis:
- id: services_upgraded
Expand All @@ -92,21 +52,14 @@ workflows:
- framework-scanner
- framework-upgrader

# Enable campaign orchestration (ADVANCED - only after ProjectOps pattern experience)
execute-workflows: true

# Governance (still start conservative even in orchestration mode)
# Governance (start conservative for first campaign)
governance:
max-new-items-per-run: 10
max-project-updates-per-run: 10
max-comments-per-run: 5
```

**Key differences:**
- **ProjectOps pattern** (default): Discovers and tracks work created by existing workflows (safer, simpler)
- **Campaign orchestration** (`execute-workflows: true`): Executes workflows, creates missing ones (powerful but complex)

**Recommendation:** Start with the ProjectOps pattern to understand campaign tracking. This gives you project board updates and tracking with campaign structure (objectives, KPIs, governance) before moving to autonomous execution.
**Note:** The campaign generator will automatically create a GitHub Project board with the project URL if not provided. You can also specify an existing project URL using `project-url: "https://github.com/orgs/ORG/projects/1"`.

## 2) Compile

Expand Down Expand Up @@ -147,52 +100,6 @@ Items with campaign labels (`campaign:*`) are automatically protected from other

This ensures your campaign items remain under the control of the campaign orchestrator and aren't interfered with by other workflows.

## Migrating from ProjectOps pattern to campaign orchestration

Once you've successfully run campaigns with the ProjectOps pattern for 1-2 weeks and understand how it works, you can enable campaign orchestration:

**Prerequisites before enabling orchestration:**
1. ✅ You've run at least 2-3 campaign runs successfully with the ProjectOps pattern
2. ✅ You understand how the orchestrator coordinates work
3. ✅ You've reviewed the project board and it's tracking items correctly
4. ✅ You have clear governance rules and conservative limits set

**Migration steps:**

1. **Update your campaign spec** to add `execute-workflows: true`:
```yaml
execute-workflows: true # Enable campaign orchestration

governance:
max-new-items-per-run: 10 # Start conservative
max-project-updates-per-run: 10
max-comments-per-run: 5
```

2. **Recompile** the campaign: `gh aw compile <campaign-id>`

3. **Test with a manual run** before scheduling:
- Trigger the workflow manually from GitHub Actions
- Watch the run logs carefully
- Verify it behaves as expected

4. **Monitor closely** for the first few runs:
- Check that workflows execute correctly
- Review any new workflows it creates
- Ensure governance limits are appropriate

5. **Adjust governance** based on observed behavior:
- Increase limits if runs are too conservative
- Decrease limits if runs are too aggressive
- Add opt-out labels if needed

**Rollback if needed:**
- Remove `execute-workflows: true` from spec
- Recompile: `gh aw compile <campaign-id>`
- Campaign reverts to ProjectOps pattern
- Recompile: `gh aw compile <campaign-id>`
- Campaign reverts to passive mode

## Optional: repo-memory for durable state

Enable repo-memory for campaigns using this layout: `memory/campaigns/<campaign-id>/cursor.json` and `memory/campaigns/<campaign-id>/metrics/<date>.json`. Campaign writes must include a cursor and at least one metrics snapshot.
Expand Down
9 changes: 2 additions & 7 deletions docs/src/content/docs/guides/campaigns/specs.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,10 @@ Campaigns are defined as Markdown files under `.github/workflows/` with a `.camp

In GitHub Agentic Workflows, a campaign is not "a special kind of workflow." The `.campaign.md` file is a specification: a reviewable contract that wires together agentic workflows around a shared initiative.

**Two operational modes:**
- **ProjectOps pattern** (default): A [ProjectOps](/gh-aw/examples/issue-pr-events/projectops/) pattern with campaign structure—automated project board management plus objectives, KPIs, and governance
- **Campaign orchestration** (`execute-workflows: true`): True campaign mode—actively executes workflows, creates missing ones, and drives progress autonomously

In a typical setup:

- Worker workflows do the work. They run an agent and use safe-outputs (for example `create_pull_request`, `add_comment`, or `update_issues`) for write operations.
- A generated orchestrator workflow keeps the campaign coherent over time. With the ProjectOps pattern, it discovers and tracks work. In orchestration mode, it also executes workflows and drives progress.
- A generated orchestrator workflow keeps the campaign coherent over time. It discovers and tracks work, executes workflows, and drives progress.
- Repo-memory (optional) makes the campaign repeatable. It lets you store a cursor checkpoint and append-only metrics snapshots so each run can pick up where the last one left off.
- GitHub Project dashboard serves as the canonical source of membership and progress tracking.

Expand Down Expand Up @@ -65,8 +61,7 @@ owners:
- `tracker-label` (optional): an ingestion hint label that helps discover issues and pull requests created by workers (commonly `campaign:<id>`). When provided, the orchestrator's discovery precomputation step can discover work across runs. The project board remains the canonical source of truth.
- `objective`: a single sentence describing what “done” means.
- `kpis`: the measures you use to report progress. Use `priority: primary` to mark exactly one KPI as the primary measure (not `primary: true`).
- `workflows`: the participating workflow IDs. These refer to workflows in the repo (commonly `.github/workflows/<workflow-id>.md`).
- `execute-workflows` (optional): Set to `true` to enable campaign orchestration. When enabled, the orchestrator will run workflows directly, create missing workflows if needed, and use outputs to drive progress. Default: `false` (ProjectOps pattern with campaign tracking). This is the key distinction between the ProjectOps pattern (tracking only) and campaign orchestration (autonomous execution).
- `workflows`: the participating workflow IDs. These refer to workflows in the repo (commonly `.github/workflows/<workflow-id>.md`). When workflows are configured, the orchestrator will execute them sequentially and can create missing workflows if needed.

## KPIs (recommended shape)

Expand Down
48 changes: 2 additions & 46 deletions docs/src/content/docs/guides/campaigns/technical-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,51 +5,7 @@ description: Run structured, goal-driven initiatives with GitHub Agentic Workflo

Agentic campaigns are goal-driven initiatives that coordinate AI agents to achieve specific objectives.

They provide a simple layer for managing work: define objectives with measurable KPIs, track progress on GitHub Projects, and optionally execute workflows to drive work forward.

## Campaign modes

Campaigns operate in two distinct modes:

### ProjectOps pattern (default)
**What it is:** A [ProjectOps](/gh-aw/examples/issue-pr-events/projectops/) pattern with campaign structure

The orchestrator discovers and tracks work created by independent workflows. This is ProjectOps—AI-powered project board management—with added campaign-specific capabilities:

- **ProjectOps foundation**: Discovers issues/PRs and updates project boards
- **Campaign additions**: KPI tracking, governance policies, metrics persistence, objective-based reporting

Worker workflows run on their own schedules and create issues/PRs. The orchestrator tracks them on the project board and reports progress toward campaign objectives without executing the workflows.

**Use the ProjectOps pattern when:**
- Workflows should remain independently scheduled
- You want campaign tracking without workflow orchestration
- Starting your first campaign (safest learning path)
- Adding structure to existing ProjectOps workflows

### Campaign orchestration (`execute-workflows: true`)
**What it is:** True campaign mode with autonomous workflow management

The orchestrator actively runs workflows, creates missing ones, and drives progress toward objectives. This is campaign orchestration where the campaign manages and executes work autonomously.

```yaml
execute-workflows: true
workflows:
- scanner # Will be created if doesn't exist
- upgrader # Will be created if doesn't exist
```

When enabled, the orchestrator will:
1. Check if each workflow exists
2. Create and test any missing workflows based on campaign objective
3. Execute workflows sequentially
4. Collect outputs for coordination

**Use campaign orchestration when:**
- Campaign should autonomously drive work execution
- Need to create workflows on demand
- Coordinating complex multi-workflow initiatives
- Ready for advanced orchestration (after ProjectOps pattern experience)
They provide a simple layer for managing work: define objectives with measurable KPIs, track progress on GitHub Projects, and execute workflows to drive work forward.

## When to use a campaign

Expand All @@ -72,7 +28,7 @@ A campaign consists of:

The orchestrator workflow runs on a schedule (default: daily) and executes phases:

**Phase 0: Workflow Execution** (if `execute-workflows: true`)
**Phase 0: Workflow Execution**
- Check if configured workflows exist
- Create and test any missing workflows
- Execute workflows sequentially
Expand Down
29 changes: 7 additions & 22 deletions docs/src/content/docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,43 +268,28 @@ AI-powered GitHub Projects board management that automates issue triage, routing
**Common patterns:**

1. **Event-driven triage** - Automatically categorize new issues/PRs and route to appropriate project boards
2. **Campaign tracking pattern** - Use `.campaign.md` files (without `execute-workflows: true`) to add structure (objectives, KPIs, governance) to ProjectOps workflows. The orchestrator discovers and tracks work created by independent workflows, reporting progress toward campaign objectives. This provides campaign-style tracking without active workflow execution.

```yaml
# Campaign tracking pattern - ProjectOps with structure
id: framework-upgrade
project-url: "https://github.com/orgs/ORG/projects/1"
tracker-label: "campaign:framework-upgrade"
objective: "Upgrade all services to Framework vNext"
kpis:
- name: "Services upgraded"
target: 50
workflows: [framework-upgrade] # Discovered, not executed
# Note: No execute-workflows flag = ProjectOps pattern
```

**When to use:** Event-driven workflows (issue opened, PR created) that need to categorize and track work on project boards, or when you want campaign-style tracking without active workflow execution.
**When to use:** Event-driven workflows (issue opened, PR created) that need to categorize and track work on project boards.

See the [ProjectOps Guide](/gh-aw/examples/issue-pr-events/projectops/) for implementation details.

### Agentic campaign

A finite, enterprise-scale initiative with explicit ownership, approval gates, and executive visibility. Agentic campaigns orchestrate business outcomes (security remediation, dependency updates, compliance enforcement) across multiple repositories with governance, accountability, and ROI tracking.

**Two operational modes:**

1. **ProjectOps pattern** (default, no `execute-workflows` flag) - Campaign tracking without workflow execution. The orchestrator discovers and tracks work created by independent workflows. This is a ProjectOps pattern with campaign structure (objectives, KPIs, governance).

2. **Campaign orchestration** (`execute-workflows: true`) - True campaign mode that actively executes workflows, creates missing ones, and drives progress autonomously.
Campaigns use `.campaign.md` specification files to define objectives, KPIs, and governance. The orchestrator discovers and tracks work, executes workflows sequentially, and can create missing workflows if needed.

```yaml
# Campaign orchestration mode
# Campaign example
id: framework-upgrade
execute-workflows: true # Enables true campaign orchestration
project-url: "https://github.com/orgs/ORG/projects/1"
workflows:
- framework-scanner # Will be created if missing
- framework-upgrader # Will be created if missing
objective: "Upgrade all services to Framework vNext"
kpis:
- name: "Services upgraded"
target: 50
```

**Key characteristics:**
Expand Down
4 changes: 2 additions & 2 deletions pkg/campaign/orchestrator.go
Original file line number Diff line number Diff line change
Expand Up @@ -310,8 +310,8 @@ func BuildOrchestrator(spec *CampaignSpec, campaignFilePath string) (*workflow.W
promptData.MaxProjectCommentsPerRun = spec.Governance.MaxCommentsPerRun
}

// Add workflow execution instructions if enabled
if spec.ExecuteWorkflows && len(spec.Workflows) > 0 {
// Add workflow execution instructions when workflows are configured
if len(spec.Workflows) > 0 {
workflowExecution := RenderWorkflowExecution(promptData)
appendPromptSection(markdownBuilder, "WORKFLOW EXECUTION (PHASE 0)", workflowExecution)
orchestratorLog.Printf("Campaign '%s' orchestrator includes workflow execution", spec.ID)
Expand Down
11 changes: 4 additions & 7 deletions pkg/campaign/prompts/campaign_creation_instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,24 +183,21 @@ Generated files:
## Best Practices

1. **Start simple** - One clear goal per campaign
2. **Use passive mode first** - Monitor before enabling active execution
3. **Reuse workflows** - Check existing before creating new
4. **Minimal permissions** - Grant only what's needed
5. **Escalate when unsure** - Create issues for human review
2. **Reuse workflows** - Check existing before creating new
3. **Minimal permissions** - Grant only what's needed
4. **Escalate when unsure** - Create issues for human review

### DO:
- ✅ Use unique kebab-case campaign IDs
- ✅ Scan existing workflows before suggesting new
- ✅ Apply least privilege for safe outputs
- ✅ Start with passive mode
- ✅ Follow operation order for project-based campaigns

### DON'T:
- ❌ Create duplicate campaign IDs
- ❌ Skip workflow discovery
- ❌ Grant unnecessary permissions
- ❌ Enable execute-workflows for first campaign

---

**Last Updated:** 2026-01-13
**Last Updated:** 2026-01-15
5 changes: 0 additions & 5 deletions pkg/campaign/schemas/campaign_spec_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -204,11 +204,6 @@
},
"additionalProperties": false
},
"execute-workflows": {
"type": "boolean",
"description": "Enable active workflow execution. When true, the orchestrator will run the workflows listed in the workflows field sequentially and can create new workflows if needed. Default: false (passive discovery only).",
"default": false
},
"governance": {
"type": "object",
"description": "Lightweight pacing and opt-out policies for campaign coordinator workflows (launcher/orchestrator)",
Expand Down
6 changes: 0 additions & 6 deletions pkg/campaign/spec.go
Original file line number Diff line number Diff line change
Expand Up @@ -96,12 +96,6 @@ type CampaignSpec struct {
// campaign (for example: number of approvals and required roles).
ApprovalPolicy *CampaignApprovalPolicy `yaml:"approval-policy,omitempty" json:"approval-policy,omitempty"`

// ExecuteWorkflows enables the campaign to actively run the workflows
// listed in the Workflows field. When true, the orchestrator will
// execute workflows sequentially and can create new workflows if needed.
// Default: false (passive discovery only).
ExecuteWorkflows bool `yaml:"execute-workflows,omitempty" json:"execute_workflows,omitempty"`

// Engine specifies the AI engine to use for the campaign orchestrator.
// Valid values: copilot, claude, codex, custom.
// Default: copilot (when not specified).
Expand Down
Loading
Loading