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 aw surface (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 --help exits 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 run command itself.
- Changes to other prompt files (
create, update, debug, etc.) — happy to follow up with a separate issue if those should also reference gh aw run explicitly.
Add
gh aw runguidance to the dispatcher agent templateProblem
The dispatcher agent template at
.github/agents/agentic-workflows.agent.mddoes not mentiongh aw runanywhere. As a result, agents loaded with this dispatcher (and the humans they're paired with) reach forgh workflow run <file>.lock.ymlwhen they want to trigger an agentic workflow on demand.That works, but it bypasses everything
gh aw runadds:.lock.yml)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, andgh aw fix— every common verb exceptrun. The omission appears unintentional:gh aw runis a documented, stable subcommand (verified locally on v0.68.3 —gh aw run --helpexits 0). Other prompt files in the repo already assumegh awis the canonical entry point ("the agent will usegh awor the mcp server" indebug-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 runbetweencompileandlogs:2. Important Notes section — add an explicit "Triggering runs" bullet so the agent knows to prefer
gh aw runeven 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).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 runhere is a one-time, persistent fix.Out of scope
gh aw runcommand itself.create,update,debug, etc.) — happy to follow up with a separate issue if those should also referencegh aw runexplicitly.