diff --git a/.github/aw/campaign-creation-instructions.md b/.github/aw/campaign-creation-instructions.md index 4a272b21aa..e3c67e650f 100644 --- a/.github/aw/campaign-creation-instructions.md +++ b/.github/aw/campaign-creation-instructions.md @@ -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 diff --git a/docs/src/content/docs/guides/campaigns/getting-started.md b/docs/src/content/docs/guides/campaigns/getting-started.md index 45a96f4c2d..ba190425e7 100644 --- a/docs/src/content/docs/guides/campaigns/getting-started.md +++ b/docs/src/content/docs/guides/campaigns/getting-started.md @@ -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 @@ -32,10 +30,6 @@ The campaign generator automatically creates: Create `.github/workflows/.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" @@ -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 @@ -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 @@ -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 ` - -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 reverts to ProjectOps pattern -- Recompile: `gh aw compile ` -- Campaign reverts to passive mode - ## Optional: repo-memory for durable state Enable repo-memory for campaigns using this layout: `memory/campaigns//cursor.json` and `memory/campaigns//metrics/.json`. Campaign writes must include a cursor and at least one metrics snapshot. diff --git a/docs/src/content/docs/guides/campaigns/specs.md b/docs/src/content/docs/guides/campaigns/specs.md index 3d2756f715..71e24f90e1 100644 --- a/docs/src/content/docs/guides/campaigns/specs.md +++ b/docs/src/content/docs/guides/campaigns/specs.md @@ -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. @@ -65,8 +61,7 @@ owners: - `tracker-label` (optional): an ingestion hint label that helps discover issues and pull requests created by workers (commonly `campaign:`). 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/.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/.md`). When workflows are configured, the orchestrator will execute them sequentially and can create missing workflows if needed. ## KPIs (recommended shape) diff --git a/docs/src/content/docs/guides/campaigns/technical-overview.md b/docs/src/content/docs/guides/campaigns/technical-overview.md index 929d02ed48..01a8d93ba1 100644 --- a/docs/src/content/docs/guides/campaigns/technical-overview.md +++ b/docs/src/content/docs/guides/campaigns/technical-overview.md @@ -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 @@ -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 diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index 6b6b61cab3..dcbbbd9bc5 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -268,22 +268,8 @@ 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. @@ -291,20 +277,19 @@ See the [ProjectOps Guide](/gh-aw/examples/issue-pr-events/projectops/) for impl 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:** diff --git a/pkg/campaign/orchestrator.go b/pkg/campaign/orchestrator.go index 50c65eab7c..41665b2b14 100644 --- a/pkg/campaign/orchestrator.go +++ b/pkg/campaign/orchestrator.go @@ -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) diff --git a/pkg/campaign/prompts/campaign_creation_instructions.md b/pkg/campaign/prompts/campaign_creation_instructions.md index 4a272b21aa..e3c67e650f 100644 --- a/pkg/campaign/prompts/campaign_creation_instructions.md +++ b/pkg/campaign/prompts/campaign_creation_instructions.md @@ -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 diff --git a/pkg/campaign/schemas/campaign_spec_schema.json b/pkg/campaign/schemas/campaign_spec_schema.json index 25883e30cf..7fa29457a3 100644 --- a/pkg/campaign/schemas/campaign_spec_schema.json +++ b/pkg/campaign/schemas/campaign_spec_schema.json @@ -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)", diff --git a/pkg/campaign/spec.go b/pkg/campaign/spec.go index 2b108914e6..2f3ca0f4f0 100644 --- a/pkg/campaign/spec.go +++ b/pkg/campaign/spec.go @@ -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). diff --git a/pkg/cli/workflows/simple-execution-example.campaign.md b/pkg/cli/workflows/simple-execution-example.campaign.md index 2c83ebe957..21cbe78bb2 100644 --- a/pkg/cli/workflows/simple-execution-example.campaign.md +++ b/pkg/cli/workflows/simple-execution-example.campaign.md @@ -1,7 +1,7 @@ --- id: simple-upgrade-example name: "Simple Framework Upgrade Campaign" -description: "Example showing how campaigns can execute workflows to upgrade services" +description: "Example showing how campaigns execute workflows to upgrade services" version: v1 state: active @@ -23,9 +23,6 @@ workflows: - framework-scanner - framework-upgrader -# Enable active workflow execution -execute-workflows: true - # Governance governance: max-project-updates-per-run: 20 @@ -36,11 +33,11 @@ owners: # Simple Framework Upgrade Campaign -This campaign demonstrates the simplified workflow execution feature. +This campaign demonstrates workflow execution in campaigns. ## How It Works -When `execute-workflows: true` is set, the campaign orchestrator will: +The campaign orchestrator will: 1. **Execute each workflow in sequence** - Run `framework-scanner` then `framework-upgrader` @@ -89,24 +86,22 @@ Execute framework-upgrader (using scanner outputs) ↓ Wait for completion ↓ -Phase 1-4: Normal campaign operations +Phase 1-4: Campaign operations ↓ Discovery → Planning → Updates → Reporting ``` ## Benefits -- **Simple configuration**: Just set `execute-workflows: true` +- **Simple configuration**: Just list workflows to execute - **Self-sufficient**: Creates missing workflows automatically - **Sequential execution**: Workflows run one at a time -- **Backward compatible**: Existing campaigns work unchanged ## Usage -1. Set `execute-workflows: true` in your campaign spec -2. List workflows in the `workflows:` field -3. Define the campaign objective clearly -4. Compile: `gh aw compile` -5. Run the campaign +1. List workflows in the `workflows:` field +2. Define the campaign objective clearly +3. Compile: `gh aw compile` +4. Run the campaign The orchestrator will handle workflow creation and execution automatically!