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
83 changes: 83 additions & 0 deletions .github/agents/campaign-designer.agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
```chatagent
---
description: Assist humans in designing and scaffolding gh-aw campaign specs (.campaign.md) and optional starter workflows.
---

# Campaign Designer for gh-aw Campaigns
Comment thread
mnkiefer marked this conversation as resolved.
Resolved

You are an AI agent that guides humans through designing and scaffolding new **campaign definitions** for this repository using the gh-aw campaigns format.

Your job is to help the user:
- Clarify the campaign's purpose, scope, and success metrics.
- Identify owners, sponsors, risk level, lifecycle state, and tags.
- Propose one or more workflows that will implement the campaign.
- Create or update the corresponding `.campaign.md` spec and (optionally) a starter workflow.
- Record a concise design summary (for humans to persist in repo-memory or documentation).

## Step 1: Understand the New Campaign

Start by asking focused questions to understand:
- The campaign goal and the problem it solves.
- Expected duration and lifecycle (planned / active / paused / completed).
- Primary owners and executive sponsors.
- Risk level (low / medium / high) and governance needs.
- Which existing workflows (if any) it should reuse.

Summarize back your understanding and get explicit confirmation before proceeding.

## Step 2: Propose Campaign Spec Fields

Based on the conversation, propose concrete values for the core campaign fields:
- `id` — stable identifier in kebab-case using only lowercase letters, digits, and hyphens (for example: `security-q1-2025`).
- `name` — human-friendly title.
- `description` — short explanation of what the campaign does.
- `workflows` — one or more workflow IDs (basenames under `.github/workflows/` without `.md`).
- `memory-paths` — under `memory/campaigns/<campaign-id>-*/**` when the campaign uses repo-memory.
- `owners` — primary human owners.
- `executive-sponsors` — accountable stakeholders.
- `risk-level` — free-form risk indicator (for example: low / medium / high).
- `state` — lifecycle stage (planned, active, paused, completed, archived).
- `tags` — free-form categorization.
- `tracker-label` — use `campaign:<id>` to stay consistent with `gh aw campaign new` and other specs.
- `allowed-safe-outputs` — which safe-outputs operations the campaign may use.
- `approval-policy` — required approvals and roles.

Show the proposed YAML frontmatter snippet to the user and refine it until they approve. If the user already ran `gh aw campaign new <id>`, read and refine that scaffold instead of starting from scratch.

## Step 3: Create or Update the .campaign.md File

Once the spec fields are approved, guide the user to create or update the spec file:

1. The target file path should be:
- `.github/workflows/<id>.campaign.md`
2. The file should contain:
- The approved YAML frontmatter.
- A short Markdown body explaining the campaign's goals, usage, and how agents should behave.

Encourage the user to keep the spec aligned with existing examples such as `incident-response.campaign.md` and `security-compliance.campaign.md` in this repo.

## Step 4: (Optional) Propose a Starter Workflow

If the user wants a starter workflow for the campaign:

1. Propose a workflow ID (for example: `<id>-run` or `<id>`).
2. Sketch the frontmatter for `.github/workflows/<workflow-id>.md`, including:
- `engine: copilot` (or another engine they choose).
- Appropriate `on:` triggers (typically `workflow_dispatch` for manual runs at first).
- Minimal `permissions:` and `safe-outputs:` consistent with the campaign spec.
3. Describe the high-level steps the workflow should perform within the campaign.

Keep the starter workflow intentionally simple and clearly mark TODO sections for humans to refine.

## Step 5: Record the Design and Next Steps

Help the user capture a brief design summary they can persist alongside the spec or in repo-memory, including:
- Final campaign spec fields.
- Chosen workflow IDs.
- Paths to created or updated files.
- Open questions or follow-up tasks.

When you are done, summarize what you designed and clearly list next steps for the human owner (for example: "run `gh aw campaign validate`, wire this into your incident runbook", etc.).

Always keep humans in the loop for final approval of campaign specs and workflows, especially for high-risk or compliance-sensitive campaigns.
```
2 changes: 1 addition & 1 deletion .github/workflows/stale-repo-identifier.lock.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 16 additions & 0 deletions docs/src/content/docs/guides/campaigns.md
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,22 @@ This gives you a centralized, Git-backed catalog of campaigns in the
repository, aligned with the executable workflows in `.github/workflows/` and
the data they write into repo-memory.

### Interactive Campaign Designer

For a more guided, conversational experience, this repo also includes a
reusable **custom agent**:

- `.github/agents/campaign-designer.agent.md` ("Campaign Designer for gh-aw Campaigns")

You can:

- Use `gh aw campaign new <id>` to scaffold a minimal spec, then
open the **Campaign Designer** agent in GitHub Copilot Chat or your
preferred agent UI to refine fields like `owners`, `memory-paths`, and
`approval-policy`, or
- Start directly with the agent and let it propose a complete
`.campaign.md` spec (and optional starter workflow) based on your answers.

### Example: Incident Response Campaign

**Full workflow**: `.github/workflows/campaign-incident-response.md`
Expand Down
34 changes: 30 additions & 4 deletions pkg/campaign/command.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@ package campaign

import (
"encoding/json"
"errors"
"fmt"
"os"
"strings"

"github.com/githubnext/gh-aw/pkg/console"
"github.com/githubnext/gh-aw/pkg/constants"
Expand Down Expand Up @@ -94,8 +96,28 @@ fields to match your initiative.
Examples:
` + constants.CLIExtensionPrefix + ` campaign new security-q1-2025
` + constants.CLIExtensionPrefix + ` campaign new modernization-winter2025 --force`,
Args: cobra.ExactArgs(1),
Args: cobra.MaximumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) == 0 {
// Build an error message with suggestions but without the leading
// error prefix icon; the main CLI handler will add that.
var b strings.Builder
b.WriteString("missing campaign id argument")
b.WriteString("\n\nSuggestions:\n")
suggestions := []string{
"Provide an ID: '" + constants.CLIExtensionPrefix + " campaign new security-q1-2025'",
"Use '" + constants.CLIExtensionPrefix + " campaign' to see existing campaigns",
"Run '" + constants.CLIExtensionPrefix + " help campaign new' for full usage",
}
for _, s := range suggestions {
b.WriteString(" • ")
b.WriteString(s)
b.WriteString("\n")
}

return errors.New(b.String())
}

id := args[0]
force, _ := cmd.Flags().GetBool("force")

Expand All @@ -109,7 +131,9 @@ Examples:
return err
}

fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created campaign spec at "+path))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(
"Created campaign spec at "+path+". Open this file and fill in owners, workflows, memory-paths, and other details.",
))
return nil
},
}
Expand Down Expand Up @@ -183,8 +207,10 @@ func runStatus(pattern string, jsonOutput bool) error {
return nil
}

// Render table to stdout for human-friendly output
output := console.RenderStruct(specs)
// Build a compact summary view for human-friendly table output.
// Full campaign definitions remain available via the --json flag.
summaries := buildCampaignSummaries(specs)
output := console.RenderStruct(summaries)
fmt.Print(output)
return nil
}
Expand Down
20 changes: 10 additions & 10 deletions pkg/campaign/spec.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,34 +11,34 @@ package campaign
// workflows and repo-memory conventions.
type CampaignSpec struct {
ID string `yaml:"id" json:"id" console:"header:ID"`
Name string `yaml:"name" json:"name" console:"header:Name"`
Description string `yaml:"description,omitempty" json:"description,omitempty" console:"header:Description,omitempty"`
Name string `yaml:"name" json:"name" console:"header:Name,maxlen:30"`
Description string `yaml:"description,omitempty" json:"description,omitempty" console:"header:Description,omitempty,maxlen:60"`

// Version is an optional spec version string (for example: v1).
// When omitted, it defaults to v1 during validation.
Version string `yaml:"version,omitempty" json:"version,omitempty" console:"header:Version,omitempty"`

// Workflows associates this campaign with one or more workflow IDs
// (basename of the Markdown file without .md).
Workflows []string `yaml:"workflows,omitempty" json:"workflows,omitempty" console:"header:Workflows,omitempty"`
Workflows []string `yaml:"workflows,omitempty" json:"workflows,omitempty" console:"header:Workflows,omitempty,maxlen:40"`

// MemoryPaths documents where this campaign writes its repo-memory
// (for example: memory/campaigns/incident-*/**).
MemoryPaths []string `yaml:"memory-paths,omitempty" json:"memory_paths,omitempty" console:"header:Memory Paths,omitempty"`
MemoryPaths []string `yaml:"memory-paths,omitempty" json:"memory_paths,omitempty" console:"header:Memory Paths,omitempty,maxlen:40"`

// MetricsGlob is an optional glob (relative to the repository root)
// used to locate JSON metrics snapshots stored in the
// memory/campaigns branch. When set, `gh aw campaign status` will
// attempt to read the latest matching metrics file and surface a few
// key fields.
MetricsGlob string `yaml:"metrics-glob,omitempty" json:"metrics_glob,omitempty" console:"header:Metrics Glob,omitempty"`
MetricsGlob string `yaml:"metrics-glob,omitempty" json:"metrics_glob,omitempty" console:"header:Metrics Glob,omitempty,maxlen:30"`

// Owners lists the primary human owners for this campaign.
Owners []string `yaml:"owners,omitempty" json:"owners,omitempty" console:"header:Owners,omitempty"`
Owners []string `yaml:"owners,omitempty" json:"owners,omitempty" console:"header:Owners,omitempty,maxlen:30"`

// ExecutiveSponsors lists executive stakeholders or sponsors who are
// accountable for the outcome of this campaign.
ExecutiveSponsors []string `yaml:"executive-sponsors,omitempty" json:"executive_sponsors,omitempty" console:"header:Executive Sponsors,omitempty"`
ExecutiveSponsors []string `yaml:"executive-sponsors,omitempty" json:"executive_sponsors,omitempty" console:"header:Executive Sponsors,omitempty,maxlen:30"`

// RiskLevel is an optional free-form field (e.g. low/medium/high).
RiskLevel string `yaml:"risk-level,omitempty" json:"risk_level,omitempty" console:"header:Risk Level,omitempty"`
Expand All @@ -53,21 +53,21 @@ type CampaignSpec struct {

// Tags provide free-form categorization for reporting (for example:
// security, modernization, rollout).
Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" console:"header:Tags,omitempty"`
Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" console:"header:Tags,omitempty,maxlen:30"`

// AllowedSafeOutputs documents which safe-outputs operations this
// campaign is expected to use (for example: create-issue,
// create-pull-request). This is currently informational but can be
// enforced by validation in the future.
AllowedSafeOutputs []string `yaml:"allowed-safe-outputs,omitempty" json:"allowed_safe_outputs,omitempty" console:"header:Allowed Safe Outputs,omitempty"`
AllowedSafeOutputs []string `yaml:"allowed-safe-outputs,omitempty" json:"allowed_safe_outputs,omitempty" console:"header:Allowed Safe Outputs,omitempty,maxlen:30"`

// ApprovalPolicy describes high-level approval expectations for this
// campaign (for example: number of approvals and required roles).
ApprovalPolicy *CampaignApprovalPolicy `yaml:"approval-policy,omitempty" json:"approval-policy,omitempty"`

// ConfigPath is populated at load time with the relative path of
// the YAML file on disk, to help users locate definitions.
ConfigPath string `yaml:"-" json:"config_path" console:"header:Config Path"`
ConfigPath string `yaml:"-" json:"config_path" console:"header:Config Path,maxlen:60"`
}

// CampaignApprovalPolicy captures basic approval expectations for a
Expand Down
37 changes: 37 additions & 0 deletions pkg/campaign/summary.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
package campaign

import "strings"

// campaignSummary provides a compact, human-friendly view of campaign specs
// for the default `gh aw campaign` table output. Full details remain
// available via `--json`.
type campaignSummary struct {
ID string `json:"id" console:"header:ID"`
Name string `json:"name" console:"header:Name,maxlen:30"`
State string `json:"state" console:"header:State"`
RiskLevel string `json:"risk_level,omitempty" console:"header:Risk,omitempty"`
TrackerLabel string `json:"tracker_label,omitempty" console:"header:Tracker Label,omitempty,maxlen:24"`
Workflows string `json:"workflows,omitempty" console:"header:Workflows,omitempty,maxlen:40"`
Owners string `json:"owners,omitempty" console:"header:Owners,omitempty,maxlen:30"`
ConfigPath string `json:"config_path" console:"header:Config Path,maxlen:60"`
}

// buildCampaignSummaries converts full campaign specs into compact summaries
// suitable for human-friendly table output.
func buildCampaignSummaries(specs []CampaignSpec) []campaignSummary {
summaries := make([]campaignSummary, 0, len(specs))
for _, spec := range specs {
summaries = append(summaries, campaignSummary{
ID: spec.ID,
Name: spec.Name,
State: spec.State,
RiskLevel: spec.RiskLevel,
TrackerLabel: spec.TrackerLabel,
Workflows: strings.Join(spec.Workflows, ", "),
Owners: strings.Join(spec.Owners, ", "),
ConfigPath: spec.ConfigPath,
})
}

return summaries
}
3 changes: 3 additions & 0 deletions pkg/cli/commands.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ var sharedAgenticWorkflowAgentTemplate string
//go:embed templates/debug-agentic-workflow.agent.md
var debugAgenticWorkflowAgentTemplate string

//go:embed templates/campaign-designer.agent.md
var campaignDesignerAgentTemplate string

// SetVersionInfo sets the version information for the CLI
func SetVersionInfo(v string) {
version = v
Expand Down
5 changes: 5 additions & 0 deletions pkg/cli/copilot-agents.go
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,11 @@ func ensureDebugAgenticWorkflowAgent(verbose bool, skipInstructions bool) error
return ensureAgentFromTemplate("debug-agentic-workflow.agent.md", debugAgenticWorkflowAgentTemplate, verbose, skipInstructions)
}

// ensureCampaignDesignerAgent ensures that .github/agents/campaign-designer.agent.md contains the campaign designer agent
func ensureCampaignDesignerAgent(verbose bool, skipInstructions bool) error {
return ensureAgentFromTemplate("campaign-designer.agent.md", campaignDesignerAgentTemplate, verbose, skipInstructions)
}

// deleteSetupAgenticWorkflowsAgent deletes the setup-agentic-workflows.agent.md file if it exists
func deleteSetupAgenticWorkflowsAgent(verbose bool) error {
gitRoot, err := findGitRoot()
Expand Down
14 changes: 13 additions & 1 deletion pkg/cli/init.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (
var initLog = logger.New("cli:init")

// InitRepository initializes the repository for agentic workflows
func InitRepository(verbose bool, mcp bool, codespaceRepos []string, codespaceEnabled bool) error {
func InitRepository(verbose bool, mcp bool, campaign bool, codespaceRepos []string, codespaceEnabled bool) error {
initLog.Print("Starting repository initialization for agentic workflows")

// Ensure we're in a git repository
Expand Down Expand Up @@ -89,6 +89,18 @@ func InitRepository(verbose bool, mcp bool, codespaceRepos []string, codespaceEn
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created debug agentic workflow agent"))
}

// Write campaign designer agent if requested
if campaign {
initLog.Print("Writing campaign designer agent")
if err := ensureCampaignDesignerAgent(verbose, false); err != nil {
initLog.Printf("Failed to write campaign designer agent: %v", err)
return fmt.Errorf("failed to write campaign designer agent: %w", err)
}
if verbose {
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created campaign designer agent"))
}
}

// Configure MCP if requested
if mcp {
initLog.Print("Configuring GitHub Copilot Agent MCP integration")
Expand Down
9 changes: 7 additions & 2 deletions pkg/cli/init_command.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ With --codespaces flag:
- Pre-installs @github/copilot
- Use without value (--codespaces) for current repo only, or with comma-separated repos (--codespaces repo1,repo2)

With --campaign flag:
- Creates .github/agents/campaign-designer.agent.md with the Campaign Designer agent for gh-aw campaigns

After running this command, you can:
- Use GitHub Copilot Chat: type /agent and select create-agentic-workflow to create workflows interactively
- Use GitHub Copilot Chat: type /agent and select debug-agentic-workflow to debug existing workflows
Expand All @@ -52,6 +55,7 @@ Examples:
RunE: func(cmd *cobra.Command, args []string) error {
verbose, _ := cmd.Flags().GetBool("verbose")
mcp, _ := cmd.Flags().GetBool("mcp")
campaign, _ := cmd.Flags().GetBool("campaign")
codespaceReposStr, _ := cmd.Flags().GetString("codespaces")
codespaceEnabled := cmd.Flags().Changed("codespaces")

Expand All @@ -68,8 +72,8 @@ Examples:
}
}

initCommandLog.Printf("Executing init command: verbose=%v, mcp=%v, codespaces=%v, codespaceEnabled=%v", verbose, mcp, codespaceRepos, codespaceEnabled)
if err := InitRepository(verbose, mcp, codespaceRepos, codespaceEnabled); err != nil {
initCommandLog.Printf("Executing init command: verbose=%v, mcp=%v, campaign=%v, codespaces=%v, codespaceEnabled=%v", verbose, mcp, campaign, codespaceRepos, codespaceEnabled)
if err := InitRepository(verbose, mcp, campaign, codespaceRepos, codespaceEnabled); err != nil {
initCommandLog.Printf("Init command failed: %v", err)
return err
}
Expand All @@ -79,6 +83,7 @@ Examples:
}

cmd.Flags().Bool("mcp", false, "Configure GitHub Copilot Agent MCP server integration")
cmd.Flags().Bool("campaign", false, "Install the Campaign Designer agent for gh-aw campaigns in this repository")
cmd.Flags().String("codespaces", "", "Create devcontainer.json for GitHub Codespaces with agentic workflows support. Specify comma-separated repository names in the same organization (e.g., repo1,repo2), or use without value for current repo only")
// NoOptDefVal allows using --codespaces without a value (returns empty string when no value provided)
cmd.Flags().Lookup("codespaces").NoOptDefVal = " "
Expand Down
Loading
Loading