Update trigger workflows with comments

[strawgate]

Let's do inline comments for hinting at how and where to configure things per workflow

[github-actions]

tl;dr Add inline YAML comments to the trigger templates in gh-agent-workflows/*/example.yml (and re-sync to .github/workflows/trigger-*.yml) to show where users customize triggers, permissions, and /ai filters.

Recommendation
Update each trigger template with short, inline comments near on:, permissions:, jobs.run.if, uses:, and secrets: to explain what consumers should edit per workflow, then run make compile so the dogfood trigger-*.yml files inherit the comments.

Findings

• Trigger templates currently have no inline guidance (e.g., gh-agent-workflows/pr-review/example.yml:1-18, gh-agent-workflows/issue-triage/example.yml:1-16, gh-agent-workflows/mention-in-issue/example.yml:1-19, gh-agent-workflows/mention-in-pr/example.yml:1-21, gh-agent-workflows/docs-drift/example.yml:1-16).
• Dogfood triggers are copied from the templates (gh-agent-workflows/DEVELOPING.md:34-36, 95-122), so edits should be made in gh-agent-workflows/*/example.yml and then synced.
• The current trigger-pr-review.yml in .github/workflows/ mirrors the example without comments (.github/workflows/trigger-pr-review.yml:1-18).

Verification

I ran a quick search to confirm the trigger templates are minimal and only include secrets/uses blocks (no inline guidance today):

$ rg -n "additional-instructions|setup-commands|COPILOT_GITHUB_TOKEN" gh-agent-workflows --glob "**/example.yml"
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/docs-new-contributor-review/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/agent-efficiency/example.yml:17:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/pr-review/example.yml:18:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/small-problem-fixer/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/breaking-change-detect/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/docs-drift/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/downstream-health/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/code-simplifier/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/stale-issues/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/bug-hunter/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/project-summary/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/release-update/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/test-improvement/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/mention-in-issue/example.yml:19:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/issue-triage/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/semantic-function-clustering/example.yml:16:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/mention-in-pr/example.yml:21:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}
/home/runner/work/ai-github-actions/ai-github-actions/gh-agent-workflows/pr-checks-fix/example.yml:21:      COPILOT_GITHUB_TOKEN: $\{\{ secrets.COPILOT_GITHUB_TOKEN }}

No tests run since this is a comment-only change to workflow templates.

Detailed Action Plan

1. Add inline comments to gh-agent-workflows/*/example.yml near on: to explain what consumers should customize (e.g., trigger types/labels, schedule cron, workflow_dispatch), starting with representative templates such as pr-review/example.yml:2-5, docs-drift/example.yml:2-6, and mention-in-issue/example.yml:2-5.
2. Add brief comments near permissions: to indicate least-privilege vs. when contents: write is needed (e.g., issue-triage/example.yml:6-10, mention-in-issue/example.yml:6-10, mention-in-pr/example.yml:8-12).
3. Add short comments on jobs.run.if filters to call out /ai gating or label exclusions (pr-review/example.yml:13-15, mention-in-issue/example.yml:14-16, mention-in-pr/example.yml:16-18).
4. Add comments near uses: and secrets: to clarify pinning (@v0) and required secret (COPILOT_GITHUB_TOKEN) (pr-review/example.yml:16-18, docs-drift/example.yml:14-16).
5. Run make compile to sync the updated templates into .github/workflows/trigger-*.yml per gh-agent-workflows/DEVELOPING.md:95-122, then verify the dogfood triggers now include the comments (e.g., .github/workflows/trigger-pr-review.yml:1-18).

Related Items

Type	Link	Relevance
Issue	#65	Prior work touching trigger templates and shims.
Issue	#17	Workflow consistency review (may overlap with comment guidance).
PR	#93	Workflow trigger/dispatch changes (context on trigger edits).
File	gh-agent-workflows/DEVELOPING.md:34-36, 95-122	Confirms templates copy to trigger-*.yml.
File	gh-agent-workflows/*/example.yml	Target files for adding inline comments.

---

What is this? | From workflow: Issue Triage Agent

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not. for issue #139

[strawgate]

/ai sounds good, inputs too make a pr

[github-actions]

Opened a PR titled "Add inline comments to trigger templates" that adds inline YAML guidance across gh-agent-workflows/*/example.yml for triggers, permissions, gates, pins, and secrets.

Testing: make lint.

Note: .github/workflows/trigger-*.yml still needs a make compile sync after merge to propagate the comments (workflow guardrails kept this PR to templates only).

---

What is this? | From workflow: Issue Assistant

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not. for issue #139

[github-actions]

This issue was labeled stale on 2026-08-10 and has had no further activity for 30 days. Closing automatically. If this issue is still relevant, please reopen it.

---

What is this? | From workflow: Trigger Stale Issues Remediator

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.