diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 04234cfe65..4511d5921c 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -12,7 +12,6 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [/cloclo](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/cloclo.md) | claude | [![/cloclo](https://github.com/githubnext/gh-aw/actions/workflows/cloclo.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/cloclo.lock.yml) | - | `/cloclo` | | [Agent Performance Analyzer - Meta-Orchestrator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/agent-performance-analyzer.md) | copilot | [![Agent Performance Analyzer - Meta-Orchestrator](https://github.com/githubnext/gh-aw/actions/workflows/agent-performance-analyzer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/agent-performance-analyzer.lock.yml) | - | - | | [Agent Persona Explorer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/agent-persona-explorer.md) | copilot | [![Agent Persona Explorer](https://github.com/githubnext/gh-aw/actions/workflows/agent-persona-explorer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/agent-persona-explorer.lock.yml) | - | - | -| [Agentic Campaign Generator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/agentic-campaign-generator.md) | claude | [![Agentic Campaign Generator](https://github.com/githubnext/gh-aw/actions/workflows/agentic-campaign-generator.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/agentic-campaign-generator.lock.yml) | - | - | | [Agentic Workflow Audit Agent](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/audit-workflows.md) | claude | [![Agentic Workflow Audit Agent](https://github.com/githubnext/gh-aw/actions/workflows/audit-workflows.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/audit-workflows.lock.yml) | - | - | | [AI Moderator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/ai-moderator.md) | copilot | [![AI Moderator](https://github.com/githubnext/gh-aw/actions/workflows/ai-moderator.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/ai-moderator.lock.yml) | - | - | | [Archie](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/archie.md) | copilot | [![Archie](https://github.com/githubnext/gh-aw/actions/workflows/archie.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/archie.lock.yml) | - | `/archie` | diff --git a/docs/src/content/docs/guides/campaigns/creating-campaigns.md b/docs/src/content/docs/guides/campaigns/creating-campaigns.md new file mode 100644 index 0000000000..f0dc3c679d --- /dev/null +++ b/docs/src/content/docs/guides/campaigns/creating-campaigns.md @@ -0,0 +1,115 @@ +--- +title: Creating Campaigns +description: How to create agentic campaigns using custom agent, interactive CLI wizard, or manual commands +banner: + content: 'Do not use. Campaigns are still incomplete and may produce unreliable or unintended results.' +--- + +There are three ways to create a campaign: + +## Recommended: CLI Interactive wizard + +Use the interactive wizard for guided campaign creation: + +```bash +gh aw campaign new --interactive +``` + +The wizard prompts you for: +- Campaign objective and description +- Repository scope (current repo, multiple repos, or org-wide) +- Workflow discovery and selection +- Owners and stakeholders +- Risk level assessment +- Project board creation + +This is the easiest way to create a well-configured campaign with all required fields. + +## Alternative: Custom agent (via Copilot Chat) + +You can also use the custom agent in GitHub Copilot Chat: + +1. **Open Copilot Chat** in your repository +2. **Type `/agent` with your campaign goal**, for example: + ``` + /agent create campaign: Burn down all open code security alerts, + prioritizing file-write alerts first and batching up to 3 related + alerts/PR with a brief fix rationale comment. + ``` +3. **Wait for the agent** to generate: + - GitHub Project board with required fields and views + - Campaign spec file (`.campaign.md`) + - Pull request with the campaign configuration +4. **Review and merge** the PR to activate the campaign + +The custom agent analyzes your goal description, discovers relevant workflows, and generates a complete campaign configuration ready for review. + +See [Getting started](/gh-aw/guides/campaigns/getting-started/) for a detailed walkthrough. + +## CLI-based creation + +### Manual mode + +For advanced users who prefer direct control: + +```bash +# Create campaign spec and GitHub Project +gh aw campaign new my-campaign-id --project --owner @me + +# Or for organizations +gh aw campaign new my-campaign-id --project --owner myorg +``` + +This scaffolds the campaign spec and creates a Project board, but you'll need to manually configure all fields, add worker workflows, and test thoroughly. + +See [CLI commands](/gh-aw/guides/campaigns/cli-commands/) for complete command reference. + +## Example: Security Alert Campaign + +Here's what a campaign spec looks like after creation: + +**Issue description** you provide: + +> Burn down all open code security alerts, prioritizing file-write alerts first +> and batching up to 3 related alerts/PR with a brief fix rationale comment. + +**Generated [campaign spec](/gh-aw/guides/campaigns/specs/)**: + +```yaml +--- +id: security-alert-burndown +name: "Security Alert Burndown" +description: "Drive the code security alerts backlog to zero" + +# GitHub Project for tracking +project-url: "https://github.com/orgs/ORG/projects/1" +tracker-label: "campaign:security-alert-burndown" + +# Strategic goals +objective: "Reduce open code security alerts to zero without breaking CI." +kpis: + - id: open_alerts + name: "Open alerts" + priority: primary + direction: "decrease" + target: 0 + +# Worker workflows to dispatch +workflows: + - security-alert-fix + +# Governance and pacing +governance: + max-project-updates-per-run: 10 + max-comments-per-run: 10 +--- +``` + +The spec compiles into a campaign orchestrator workflow (`.campaign.lock.yml`) that GitHub Actions executes on schedule. The orchestrator [dispatches workers, tracks outputs, updates the Project board, and reports progress](/gh-aw/guides/campaigns/lifecycle/). + +## Next steps + +- [Getting started](/gh-aw/guides/campaigns/getting-started/) – step-by-step tutorial +- [Campaign specs](/gh-aw/guides/campaigns/specs/) – configuration reference +- [Campaign Lifecycle](/gh-aw/guides/campaigns/lifecycle/) – execution model +- [CLI commands](/gh-aw/guides/campaigns/cli-commands/) – command reference diff --git a/docs/src/content/docs/guides/campaigns/getting-started.md b/docs/src/content/docs/guides/campaigns/getting-started.md index 537df11348..a687b3b6cd 100644 --- a/docs/src/content/docs/guides/campaigns/getting-started.md +++ b/docs/src/content/docs/guides/campaigns/getting-started.md @@ -5,20 +5,24 @@ banner: content: 'Do not use. Campaigns are still incomplete and may produce unreliable or unintended results.' --- -Create your first campaign using the automated creation flow. The flow generates a Project board, campaign spec, and orchestrator workflow based on an issue description. +Create your first campaign using the custom agent in GitHub Copilot Chat. The agent generates a Project board, campaign spec, and orchestrator workflow based on your goal description. ## Prerequisites - Repository with GitHub Agentic Workflows installed -- `create-agentic-campaign` label configured in your repository -- Write access to create issues and merge pull requests +- GitHub Copilot access +- Write access to create pull requests and merge them - GitHub Actions enabled ## Create a campaign -1. **Create an issue** describing your campaign goal and scope -2. **Apply the label** `create-agentic-campaign` to the issue -3. **Wait for automation** - A pull request appears within a few minutes +1. **Open Copilot Chat** in your repository +2. **Describe your campaign** using `/agent`: + ``` + /agent create campaign: Burn down all open code security alerts, + prioritizing file-write alerts first + ``` +3. **Wait for the agent** - A pull request appears with your campaign configuration 4. **Review the PR** - Verify the generated Project, spec, and orchestrator 5. **Merge the PR** when ready 6. **Run the orchestrator** from the Actions tab to start the campaign diff --git a/docs/src/content/docs/guides/campaigns/index.mdx b/docs/src/content/docs/guides/campaigns/index.mdx index 8d91f235b3..be7f033035 100644 --- a/docs/src/content/docs/guides/campaigns/index.mdx +++ b/docs/src/content/docs/guides/campaigns/index.mdx @@ -7,86 +7,41 @@ banner: content: 'Do not use. Campaigns are still incomplete and may produce unreliable or unintended results.' --- -import FeatureCard from '../../../../components/FeatureCard.astro'; -import FeatureGrid from '../../../../components/FeatureGrid.astro'; - ## What are Agentic Campaigns? -[**Agentic campaigns**](/gh-aw/reference/glossary/#agentic-campaign) help you coordinate **[agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** toward a shared goal. - -Imagine you have a goal that takes more than one workflow run, across one or more repositories. You can write a worker workflow to do the work, but you still need a way to schedule it, fan it out, track what it created, and report progress. - -Campaigns provide that orchestration layer: you define the goal and guardrails in a campaign spec, which gets compiled into an orchestrator workflow that runs on a schedule. On each run, the orchestrator can dispatch worker workflows, track the issues and pull requests they create, update a GitHub Project board, and publish a status update with metrics. - -Use campaigns when work needs coordination across multiple workflows or repositories, plus tracking, pacing, and governance. If a single workflow is enough (even on a schedule), start with a standalone agentic workflow. - -## Why use campaigns? - - - - Define campaign objectives and key performance indicators (KPIs) with optional narrative context. - - - Coordinate existing dispatchable workflows instead of rewriting automation. - - - Track work and status updates in one GitHub Project board. - - - Cap updates per run, opt out items, and keep changes predictable. - - +**GitHub agentic campaigns** are AI-powered orchestration workflows that coordinate multiple **[agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** toward a shared goal across one or more repositories. -## Natural language to campaign +Just as [agentic workflows](/gh-aw/introduction/overview/) use natural language instructions to give an AI agent tasks and [safe outputs](/gh-aw/reference/safe-outputs/) to enable controlled GitHub operations, campaigns use **[campaign specs](/gh-aw/guides/campaigns/specs/)** to give an **orchestrator agent** high-level strategic instructions. The orchestrator agent interprets your campaign's objective and KPIs, then autonomously manages worker workflows to achieve the goal. -Campaigns use agentic workflows to generate configuration from natural language descriptions. +## When to Use Campaigns -**Example input**: Describe your goal in plain language: +Use campaigns when your goal requires: +- **Multiple workflow runs** across one or more repositories +- **Coordination** of worker workflows doing similar tasks +- **Tracking** of created issues and pull requests +- **Progress reporting** against strategic objectives +- **Governance** with pacing controls and safety limits -```md -Burn down all open code security alerts, prioritizing file-write alerts first -and batching up to 3 related alerts/PR with a brief fix rationale comment. -``` +If a single workflow is enough (even on a schedule), start with a standalone agentic workflow. -The campaign generator converts this into a **[campaign spec](/gh-aw/guides/campaigns/specs/)** in a pull request for review. Essential spec components include: +## How Campaigns Work -```yaml ---- -id: security-alert-burndown -name: "Security Alert Burndown" -description: "Drive the code security alerts backlog to zero" - -# GitHub Project for tracking -project-url: "https://github.com/orgs/ORG/projects/1" -tracker-label: "campaign:security-alert-burndown" - -# Strategic goals -objective: "Reduce open code security alerts to zero without breaking CI." -kpis: - - id: open_alerts - name: "Open alerts" - priority: primary - direction: "decrease" - target: 0 - -# Worker workflows to dispatch -workflows: - - security-alert-fix - -# Governance and pacing -governance: - max-project-updates-per-run: 10 - max-comments-per-run: 10 ---- -``` +Campaigns provide an orchestration layer on top of your existing workflows: -The spec is validated and compiled into the campaign orchestrator workflow (`.campaign.lock.yml`) that GitHub Actions executes. +1. **Define your goal** in a [campaign spec](/gh-aw/guides/campaigns/specs/) with objectives, KPIs, and governance rules +2. **Compile to orchestrator** – the spec becomes a workflow that runs on schedule (daily by default) +3. **Orchestrator coordinates** – dispatches worker workflows, tracks their outputs, updates a GitHub Project board +4. **Progress tracked** – campaign publishes metrics and status updates against your KPIs -Once merged, the orchestrator runs on schedule (daily by default) to [dispatch worker workflows, discover items, update the Project board, and report status](/gh-aw/guides/campaigns/lifecycle/). +**Key concepts:** +- **Campaign spec**: YAML configuration defining goals, governance, and worker coordination +- **Orchestrator agent**: AI agent managing campaign execution, worker dispatch, and progress tracking +- **Worker workflows**: Your existing dispatchable workflows that do the actual work ## Next steps -- [Getting started](/gh-aw/guides/campaigns/getting-started/) – create your first campaign -- [Campaign specs](/gh-aw/guides/campaigns/specs/) – fields you can configure -- [Campaign Lifecycle](/gh-aw/guides/campaigns/lifecycle/) – what the orchestrator does each run -- [CLI commands](/gh-aw/guides/campaigns/cli-commands/) – inspect and validate campaigns +- [Creating campaigns](/gh-aw/guides/campaigns/creating-campaigns/) – issue-based or CLI creation +- [Getting started](/gh-aw/guides/campaigns/getting-started/) – step-by-step tutorial +- [Campaign specs](/gh-aw/guides/campaigns/specs/) – configuration reference +- [Campaign Lifecycle](/gh-aw/guides/campaigns/lifecycle/) – execution model +- [CLI commands](/gh-aw/guides/campaigns/cli-commands/) – command reference