Repository navigation
Description
Add gh aw run guidance to the dispatcher agent template
Problem
The dispatcher agent template at .github/agents/agentic-workflows.agent.md does not mention gh aw run anywhere. As a result, agents loaded with this dispatcher (and the humans they're paired with) reach for gh workflow run <file>.lock.yml when they want to trigger an agentic workflow on demand.
That works, but it bypasses everything gh aw run adds:
- workflow resolution by short name (no need to remember
.lock.yml) - input parsing / validation against the workflow's declared inputs
- correct run-tracking for agentic workflows (the CLI knows which run it just kicked off)
- consistent UX with the rest of the
gh awsurface (compile,logs,audit)
This is especially noticeable when an agent is asked to "trigger workflow X on this branch" mid-conversation — without explicit guidance in the template, the agent defaults to gh workflow run.
Analysis
The Quick Reference section of the template currently lists gh aw init, gh aw compile, gh aw logs, gh aw audit, and gh aw fix — every common verb except run. The omission appears unintentional: gh aw run is a documented, stable subcommand (verified locally on v0.68.3 — gh aw run --help exits 0). Other prompt files in the repo already assume gh aw is the canonical entry point ("the agent will use gh aw or the mcp server" in debug-agentic-workflow.md).
Adding two lines fixes this for every downstream consumer of the template — including any repo that runs gh aw upgrade, since the template gets re-emitted on upgrade.
Implementation Plan
Make two small additions to .github/agents/agentic-workflows.agent.md:
1. Quick Reference section — add gh aw run between compile and logs:
# Generate the lock file for a workflow
gh aw compile [workflow-name]
+# Trigger a workflow run (always prefer this over `gh workflow run`)
+gh aw run [workflow-name] --ref <branch>
+
# Debug workflow runs
gh aw logs [workflow-name]
gh aw audit <run-id>2. Important Notes section — add an explicit "Triggering runs" bullet so the agent knows to prefer gh aw run even when the user phrases the request as "kick off the workflow" or "dispatch X":
- **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself.
+- **Triggering runs**: Always use `gh aw run <workflow-name> --ref <branch>` instead of `gh workflow run <file>.lock.yml`. The `gh aw` CLI handles workflow resolution, input parsing, and run-tracking correctly for agentic workflows.Validation
gh aw run --helpexits 0 on v0.68.3 (verified locally).- No code changes; documentation/template only.
- No existing tests should regress — this is a markdown-only edit to a template file.
Why this matters for the project
The template is the agent's "system prompt" for everything gh-aw-related across every repo that imports it. Each missing verb in Quick Reference is a small but compounding nudge toward the wrong tool. Codifying gh aw run here is a one-time, persistent fix.
Out of scope
- Changes to the
gh aw runcommand itself. - Changes to other prompt files (
create,update,debug, etc.) — happy to follow up with a separate issue if those should also referencegh aw runexplicitly.
Activity
pelikhan commentedon Apr 26, 2026
Related to #27259
pelikhan commentedon Apr 26, 2026
@copilot create a new instructions file to explain the various cli commands. Make sure to be very clear that they can be invoked as a cli on a local development or as a MCP tool in more restricted environment. Cover various debugging scenarios, reference debug.md. Do the usual dispatching from the general instructions file.