diff --git a/.github/aw/campaign.md b/.github/aw/campaign.md new file mode 100644 index 0000000000..ba9e97199e --- /dev/null +++ b/.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. diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 92dfafdaa0..0e7257ecab 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.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. diff --git a/.github/aw/create-shared-agentic-workflow.md b/.github/aw/create-shared-agentic-workflow.md index 99722fbd8b..d669dd5259 100644 --- a/.github/aw/create-shared-agentic-workflow.md +++ b/.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 diff --git a/.github/aw/debug-agentic-workflow.md b/.github/aw/debug-agentic-workflow.md index d268b06517..26a36a95b7 100644 --- a/.github/aw/debug-agentic-workflow.md +++ b/.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** diff --git a/.github/aw/update-agentic-workflow.md b/.github/aw/update-agentic-workflow.md index f4269a022b..5158880220 100644 --- a/.github/aw/update-agentic-workflow.md +++ b/.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 ` → compile one workflow diff --git a/.github/aw/upgrade-agentic-workflows.md b/.github/aw/upgrade-agentic-workflows.md index b8df062ada..8b1762b04f 100644 --- a/.github/aw/upgrade-agentic-workflows.md +++ b/.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**