diff --git a/.github/workflows/daily-team-evolution-insights.lock.yml b/.github/workflows/daily-team-evolution-insights.lock.yml index 6583c3d937..088d691639 100644 --- a/.github/workflows/daily-team-evolution-insights.lock.yml +++ b/.github/workflows/daily-team-evolution-insights.lock.yml @@ -156,7 +156,7 @@ jobs: const determineAutomaticLockdown = require('/opt/gh-aw/actions/determine_automatic_lockdown.cjs'); await determineAutomaticLockdown(github, context, core); - name: Download container images - run: bash /opt/gh-aw/actions/download_docker_images.sh ghcr.io/github/github-mcp-server:v0.28.1 node:lts-alpine + run: bash /opt/gh-aw/actions/download_docker_images.sh node:lts-alpine - name: Write Safe Outputs Config run: | mkdir -p /opt/gh-aw/safeoutputs diff --git a/.github/workflows/daily-team-evolution-insights.md b/.github/workflows/daily-team-evolution-insights.md index 234ab9a22b..3ec5ed405c 100644 --- a/.github/workflows/daily-team-evolution-insights.md +++ b/.github/workflows/daily-team-evolution-insights.md @@ -18,7 +18,7 @@ network: - "*" tools: github: - mode: local + mode: remote toolsets: [repos, issues, pull_requests, discussions] safe-outputs: create-discussion: diff --git a/pkg/cli/templates/execute-campaign-workflow.md b/pkg/cli/templates/execute-campaign-workflow.md index 18bd14d679..5fedd4c85e 100644 --- a/pkg/cli/templates/execute-campaign-workflow.md +++ b/pkg/cli/templates/execute-campaign-workflow.md @@ -1,8 +1,8 @@ # Workflow Execution -This campaign is configured to **actively execute workflows**. Your role is to dispatch the configured workflows (via `workflow_dispatch`) so they can create/advance work items that the orchestrator will discover and track. +This campaign is configured to **actively execute workflows**. Your role is to run the workflows listed in sequence, collect their outputs, and use those outputs to drive the campaign forward. -**IMPORTANT:** In the current implementation, dispatching a workflow does **not** provide a workflow run ID and the orchestrator should **not** wait/poll for completion. Treat dispatch as "kick off work" and rely on the next orchestrator run's discovery to observe outcomes. +**IMPORTANT: Active execution is an advanced feature. Exercise caution and follow all guidelines carefully.** --- @@ -17,18 +17,31 @@ The following workflows should be executed in order: --- -## Requirements +## Workflow Creation Guardrails -Before dispatching any workflow: +### Before Creating Any Workflow, Ask: -1. The workflow must already exist in `.github/workflows/` as either: +1. **Does this workflow already exist?** - Check `.github/workflows/` thoroughly +2. **Can an existing workflow be used?** - Even if not perfect, existing is safer +3. **Is the requirement clear?** - Can you articulate exactly what it should do? +4. **Is it testable?** - Can you verify it works before using it in the campaign? +5. **Is it reusable?** - Could other campaigns benefit from this workflow? - - a compiled agentic workflow (`.lock.yml`), or - - a standard GitHub Actions workflow (`.yml`). +### Only Create New Workflows When: -1. The workflow must support `workflow_dispatch`. +✅ **All these conditions are met:** +- No existing workflow does the required task +- The campaign objective explicitly requires this capability +- You have a clear, specific design for the workflow +- The workflow has a focused, single-purpose scope +- You can test it independently before campaign use -If a workflow is missing or not dispatchable, report it in the campaign status update and continue with the remaining workflows. +❌ **Never create workflows when:** +- You're unsure about requirements +- An existing workflow "mostly" works +- The workflow would be complex or multi-purpose +- You haven't verified it doesn't already exist +- You can't clearly explain what it does in one sentence --- @@ -36,40 +49,116 @@ If a workflow is missing or not dispatchable, report it in the campaign status u For each workflow: -1. **Check availability** - - - The workflow must be present as `.github/workflows/.lock.yml` or `.github/workflows/.yml`. - - If only `.github/workflows/.md` exists, it must be compiled first (outside this run). - -1. **Dispatch the workflow** - - - Use the per-workflow safe-output tool generated for this campaign. - - The tool name is the workflow ID with dashes normalized to underscores. - - Example: workflow `dependency-updater` → tool `dependency_updater` - - Provide inputs only if needed; the tool schema will expose any `workflow_dispatch.inputs`. - -1. **Do not wait for completion** - - - Dispatching is fire-and-forget. The orchestrator should continue to discovery + project updates. - - Outcomes are observed on later runs via the discovery manifest (`./.gh-aw/campaign.discovery.json`). +1. **Check if workflow exists** - Look for `.github/workflows/.md` or `.github/workflows/.lock.yml` + +2. **Create workflow if needed** - Only if ALL guardrails above are satisfied: + + **Design requirements:** + - **Single purpose**: One clear task (e.g., "scan for outdated dependencies", not "scan and update") + - **Explicit trigger**: Must include `workflow_dispatch` for manual/programmatic execution + - **Minimal tools**: Only include tools actually needed (principle of least privilege) + - **Safe outputs only**: Use appropriate safe-output limits (max: 5 for first version) + - **Clear prompt**: Describe exactly what the workflow should do and return + + **Create the workflow file at `.github/workflows/.md`:** + ```yaml + --- + name: + description: + + on: + workflow_dispatch: # Required for execution + + tools: + github: + toolsets: [default] # Adjust based on needs + # Only add other tools if absolutely necessary + + safe-outputs: + create-issue: + max: 3 # Start conservative + add-comment: + max: 2 + --- + + # + + You are a focused workflow that . + + ## Task + + + + ## Output + + + ``` + + - Compile it with `gh aw compile .md` + - **CRITICAL: Test before use** (see testing requirements below) + +3. **Test newly created workflows** (MANDATORY): + + **Why test?** - Untested workflows may fail during campaign execution, blocking progress. Test first to catch issues early. + + **Testing steps:** + - Trigger test run: `mcp__github__run_workflow(workflow_id: "", ref: "main")` + - Wait for completion: Poll until status is "completed" + - **Verify success**: Check that workflow succeeded and produced expected outputs + - **Review outputs**: Ensure results match expectations (check artifacts, issues created, etc.) + - **If test fails**: Revise the workflow, recompile, and test again + - **Only proceed** after successful test run + + **Test failure actions:** + - DO NOT use the workflow in the campaign if testing fails + - Analyze the failure logs to understand what went wrong + - Make necessary corrections to the workflow + - Recompile and retest + - If you can't fix it after 2 attempts, report in status update and skip this workflow + +4. **Execute the workflow** (skip if just tested successfully): + - Trigger: `mcp__github__run_workflow(workflow_id: "", ref: "main")` + - Wait for completion: Poll `mcp__github__get_workflow_run(run_id)` until status is "completed" + - Collect outputs: Check `mcp__github__download_workflow_run_artifact()` for any artifacts + - **Handle failures gracefully**: If execution fails, note it in status update but continue campaign + +5. **Use outputs for next steps** - Use information from workflow runs to: + - Inform subsequent workflow executions (e.g., scanner results → upgrader inputs) + - Update project board items with relevant information + - Make decisions about campaign progress and next actions --- ## Guidelines **Execution order:** - -- Dispatch workflows **sequentially** (one dispatch at a time). -- Do **not** wait/poll for completion. -- Keep dispatch volume low (the campaign safe-output max is capped). +- Execute workflows **sequentially** (one at a time) +- Wait for each workflow to complete before starting the next +- **Why sequential?** - Ensures dependencies between workflows are respected and reduces API load + +**Workflow creation:** +- **Always test newly created workflows** before using them in the campaign +- **Why test first?** - Prevents campaign disruption from broken workflows +- Start with minimal, focused workflows (easier to test and debug) +- **Why minimal?** - Reduces complexity and points of failure +- Keep designs simple and aligned with campaign objective +- **Why simple?** - Easier to understand, test, and maintain **Failure handling:** - -- If dispatch fails for a workflow, record it in the status update and continue. -- If a workflow is missing/not compiled/not dispatchable, record it in the status update and continue. +- If a workflow test fails, revise and retest before proceeding +- **Why retry?** - Initial failures often due to minor issues easily fixed +- If a workflow fails during campaign execution, note the failure and continue +- **Why continue?** - One workflow failure shouldn't block entire campaign progress +- Report all failures in the status update with context +- **Why report?** - Transparency helps humans intervene if needed + +**Workflow reusability:** +- Workflows you create should be reusable for future campaign runs +- **Why reusable?** - Reduces need to create workflows repeatedly, builds library of capabilities +- Avoid campaign-specific logic in workflows (keep them generic) +- **Why generic?** - Enables reuse across different campaigns **Permissions and safety:** - - Keep workflow permissions minimal (only what's needed) - **Why minimal?** - Reduces risk and follows principle of least privilege - Prefer draft PRs over direct merges for code changes @@ -81,8 +170,7 @@ For each workflow: ## After Workflow Execution -Once all workflows have been dispatched (or skipped with rationale), proceed with the normal orchestrator steps: - +Once all workflows have been executed (or created and executed), proceed with the normal orchestrator steps: - Step 1: Discovery (read state from manifest and project board) - Step 2: Planning (determine what needs updating) - Step 3: Project Updates (write state to project board)