feat: add campaign-style playbook and update refs

.github/aw/campaign.md

@@ -0,0 +1,141 @@
+# Campaign Workflows
+
+Shared reference for **campaign workflows**: coordinated, time-bounded pushes with measurable outcomes, including **KPI workflows** (measure and improve a metric over time).
+
+## Design principles
+
+Treat campaigns as a **workflow design pattern**, not a separate feature.
+
+### Minimum viable campaign spec
+
+1. **Goal**: What is the measurable success criteria (metric, source, target, deadline)?
+2. **Cadence**: How often should it run? Should it allow `workflow_dispatch` for manual control?
+3. **Stop condition**: What does "goal met" look like, and what should the workflow do when it’s met (report + stop early)?
+4. **Outputs**: What should be written (comment, issue, PR) vs only reported (stdout/stderr)?
+5. **Scope**: Single repo or cross-repo? If cross-repo, who owns coordination and auth?
+6. **Constraints**: Budget/time/quality constraints per run (max PRs, max issues, runtime limit, etc.)
+
+### Composable building blocks (start simple)
+
+- **Agentic (default)**: Use when work requires judgment, synthesis, or ambiguous decisions.
+- **Deterministic core (opt-out)**: Use when tasks are precise, repeatable, and easy to validate.
+- **Hybrid**: Keep deterministic prep in `steps:` and use an agentic prompt for decisions/edge cases.
+- **Metrics + memory**: Use `cache-memory` (and optionally `repo-memory`) to persist goal tracking and state across runs.
+
+### Pacing levers (how to avoid overwhelming humans and systems)
+
+Use the **minimum levers** for safe throughput:
+
+- **Cadence**: Prefer fuzzy `schedule:` (and weekdays for daily) to spread runs.
+- **No overlap**: Use workflow-level `concurrency:` so only one campaign run is active at a time.
+- **Global throughput**: If you have multiple campaigns, consider using the **same `concurrency.group`** across them.
+- **Hard deadline**: Use `on.stop-after` when the campaign should stop after a date/time or relative window.
+- **Output caps**: Enforce “how much writing” with `safe-outputs.*.max` (e.g., max 1 PR per run; max 1–3 comments per run).
+- **Rate limiting**: For large scopes, use round-robin + cache-memory (one component per run).
+- **Goal-aware early exit**: Add a deterministic pre-check and stop immediately when the goal is already met.
+
+**Minimal pacing example (pick what you need):**
+
+```yaml
+---
+on:
+  schedule: weekly
+  stop-after: "+30d"
+
+concurrency:
+  group: "campaign-weekly-ci-kpi"
+  cancel-in-progress: false
+
+permissions:
+  content: read
+  issues: read
+tools:
+  cache-memory: true
+
+safe-outputs:
+  create-pull-request:
+    max: 1
+  add-comment:
+    max: 1
+  noop:
+---
+```
+
+### Goal-aware early exit (deterministic pre-check + agentic report)
+
+Use a deterministic pre-check step when possible. If the goal is already met, exit early and still report outcomes.
+
+```markdown
+---
+on:
+  workflow_dispatch:
+permissions: read-all
+tools:
+  cache-memory: true
+steps:
+  - name: Precompute goal status
+    run: |
+      # Replace with real metric computation.
+      # Keep this step deterministic so it’s easy to validate.
+      echo '{"goal_met": true, "metric": "coverage", "value": 82, "target": 80}' > /tmp/gh-aw/agent/goal_status.json
+safe-outputs:
+  add-comment:
+    max: 1
+  noop:
+---
+
+# Goal-aware run
+
+Read `/tmp/gh-aw/agent/goal_status.json`.
+
+If `goal_met` is true:
+
+- Post a short summary (3–5 bullets) and stop.
+
+Otherwise:
+
+- Proceed with the plan, then end with a summary and learnings.
+```
+
+### KPI workflows (measure + improve)
+
+KPI workflows are campaigns where the first-class output is a **metric** and an **interpretation**.
+
+**Strong default:** Make KPI computation deterministic and easy to validate.
+
+- Compute a KPI in `steps:` and write a small JSON payload (e.g., `/tmp/gh-aw/agent/kpi.json`).
+- The agent reads that JSON, decides what to do (report-only vs follow-up), and always ends with a short summary.
+
+**Inputs (when you need knobs):**
+
+- Use `workflow_dispatch` inputs for user-controlled parameters (e.g., target threshold, window size) and have a deterministic `steps:` block normalize those inputs into a JSON config the agent reads.
+- Use `safe-inputs:` when the agent needs a constrained, auditable tool to fetch privileged data (it’s not a human input mechanism).
+
+**Minimum viable KPI spec (keep it explicit):**
+
+- `kpi.name` + `kpi.definition` (formula)
+- `kpi.source` (command, GitHub API read, file parse)
+- `kpi.target` (threshold + timeframe)
+- `kpi.scope` (branch, directory, package set)
+- `kpi.publish_to` (comment/issue/discussion) + “update existing?”
+
+**Standard deterministic payload (suggested):**
+
+```json
+{
+  "kpi": "ci_success_rate",
+  "value": 0.92,
+  "target": 0.95,
+  "window": "last_30_runs",
+  "goal_met": false,
+  "notes": "2 failures were flaky tests"
+}
+```
+
+### Cross-repo coordination (advanced; keep it explicit)
+
+- `safe-outputs.dispatch-workflow` is same-repo only.
+- For org-wide or multi-org campaigns, use a coordinator that sends `repository_dispatch` to each target repo.
+  - This requires a PAT or GitHub App token with access to every repo it dispatches.
+  - Prefer a fine-grained PAT scoped to the specific repos with `Actions: Read & Write`.
+  - Treat this as a privileged operation: keep permissions minimal and lock down inputs.

.github/aw/create-agentic-workflow.md

@@ -173,6 +173,7 @@ Before creating workflows, consult these documentation resources:
 
 - **Main documentation site**: https://github.github.com/gh-aw/
 - **Comprehensive reference**: `.github/aw/github-agentic-workflows.md` (local file with complete frontmatter schema)
+- **Campaign playbook**: `.github/aw/campaign.md` (patterns for campaign/KPI workflows; campaigns are not a separate workflow type)
 - **Setup guides**: https://github.github.com/gh-aw/setup/quick-start/
 - **Example workflows**: `.github/workflows/*.md` (actual working examples in this repository)
 
@@ -194,6 +195,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per
 
    - What should trigger the workflow (`on:` — e.g., issues, pull requests, schedule, slash command)?
    - What should the agent do (comment, triage, create PR, fetch API data, etc.)?
+  - If the user says “campaign”, “KPI”, “pacing”, “cadence”, or “stop-after”, consult `.github/aw/campaign.md` (it’s still an agentic workflow; this is just a pattern).
    - ⚠️ If you think the task requires **network access beyond localhost**, explicitly ask about configuring the top-level `network:` allowlist (ecosystems like `node`, `python`, `playwright`, or specific domains).
    - 💡 If you detect the task requires **browser automation**, suggest the **`playwright`** tool.
    - 🔐 If building an **issue triage** workflow that should respond to issues filed by non-team members (users without write permission), suggest setting **`roles: all`** to allow any authenticated user to trigger the workflow. The default is `roles: [admin, maintainer, write]` which only allows team members.

.github/aw/create-shared-agentic-workflow.md

@@ -16,6 +16,7 @@ You are a conversational chat agent that interacts with the user to design secur
 **Build on agentic workflows**
 
 - You extend the basic agentic workflow creation prompt with shared component best practices
+- If the user says “campaign”, “KPI”, “pacing”, “cadence”, or “stop-after”, consult @.github/aw/campaign.md (campaign/KPI workflows are still just agentic workflows; this is a design pattern playbook).
 - Shared components are stored in `.github/workflows/shared/` directory
 - Components use frontmatter-only format (no markdown body) for pure configuration
 - Components are imported using the `imports:` field in workflows

.github/aw/debug-agentic-workflow.md

@@ -52,6 +52,7 @@ Report back with specific findings and actionable fixes.
 - Always consult the **instructions file** for schema and features:
   - Local copy: @.github/aw/github-agentic-workflows.md
   - Canonical upstream: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
+- If the user says “campaign”, “KPI”, “pacing”, “cadence”, or “stop-after”, consult @.github/aw/campaign.md (campaign/KPI workflows are still just agentic workflows; this is a design pattern playbook).
 
 **Key Commands Available**
 

.github/aw/update-agentic-workflow.md

@@ -57,6 +57,7 @@ You format your questions and responses similarly to the GitHub Copilot CLI chat
 - Always consult the **instructions file** for schema and features:
   - Local copy: @.github/aw/github-agentic-workflows.md
   - Canonical upstream: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
+- If the user says “campaign”, “KPI”, “pacing”, “cadence”, or “stop-after”, consult @.github/aw/campaign.md (campaign/KPI workflows are still just agentic workflows; this is a design pattern playbook).
 - Key commands:
   - `gh aw compile` → compile all workflows
   - `gh aw compile <name>` → compile one workflow

.github/aw/upgrade-agentic-workflows.md

@@ -16,6 +16,7 @@ Read the ENTIRE content of this file carefully before proceeding. Follow the ins
 - Always consult the **instructions file** for schema and features:
   - Local copy: @.github/aw/github-agentic-workflows.md
   - Canonical upstream: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
+- If the user says “campaign”, “KPI”, “pacing”, “cadence”, or “stop-after”, consult @.github/aw/campaign.md (campaign/KPI workflows are still just agentic workflows; this is a design pattern playbook).
 
 **Key Commands Available**