// Use when selecting, customizing, or composing built-in workflow templates — covers all 7 templates (triage, PR review, docs, release, stale, first-timer, incident) with customization points and composition patterns.
Use when generating workflow files, writing blueprints, or validating format — covers gh-aw markdown format, GitHub Actions YAML, blueprint YAML frontmatter, and template structure.
Use when designing event routing, preventing cascades, composing workflows, or choosing between label-based vs dispatch-based triggers for GitHub agent workflows.
Use when configuring permissions, handling fork PRs, sanitizing untrusted input, or setting up safe-outputs for agent workflows on GitHub.
| name | templates |
| description | Use when selecting, customizing, or composing built-in workflow templates — covers all 7 templates (triage, PR review, docs, release, stale, first-timer, incident) with customization points and composition patterns. |
| version | 0.1.0 |
Reference guide for awful's 7 built-in workflow templates.
| Template | Event | Agent Role | Key Outputs |
|---|---|---|---|
| triage | issues.opened | Classify, label, assign | labels, assignment, acknowledgment comment |
| pr-review | pull_request.opened/synchronize | Review code quality | review comment, approve/request-changes |
| docs | issues.labeled:needs-docs | Generate documentation | docs PR |
| release | push:tags/v* | Generate changelog, create release | GitHub release, announcement comment |
| stale | schedule:daily | Find inactive issues/PRs | warning comment, close |
| first-timer | pull_request.opened (FIRST_TIME_CONTRIBUTOR) | Welcome, guide | welcome comment, first-timer label |
| incident | issues.labeled:incident | Create tracker, notify | tracking comment, @mentions, runbook link |
Event: issues.opened
Purpose: Every new issue gets classified immediately so the team knows what it is and how urgent it is.
Customization points:
component-auth, platform-ios)component-auth → @security-team)Required labels: bug, feature, question, duplicate, priority-high, priority-medium, priority-low
Agent-applied labels: awful:triaged
Event: pull_request.opened, pull_request.synchronize
Purpose: Automated first-pass code review — catches obvious issues before human reviewers spend time.
Fork PR guard: Required — this template has contents: read but the review comment requires pull-requests: write.
Customization points:
Agent-applied labels: awful:reviewed
Human gate: Agent posts a review but does NOT approve — human still merges.
Event: issues.labeled with label needs-docs
Purpose: When a feature is merged without documentation, an issue gets labeled needs-docs. The agent reads the related code and generates a documentation PR.
Customization points:
Required labels: needs-docs
Permissions: contents: write, pull-requests: write — this template creates a PR.
Event: push to tags matching v*
Purpose: When a version tag is pushed, generate a changelog from commits since the previous tag and create a GitHub release.
Customization points:
v1.0.0-rc.1 → pre-release)Permissions: contents: write — creates the GitHub release object.
Note: Does not push code. Creates only the GitHub Release metadata.
Event: schedule (daily cron, 0 9 * * *)
Purpose: Keep the issue tracker clean by closing issues that have had no activity for 37 days (30 days warning + 7 days grace).
Customization points:
priority-high, pinned)Required labels: awful:stale (applied by the agent as warning)
Exempt labels: priority-high, pinned
Idempotent: Safe to run multiple times — already-warned issues won't get duplicate comments.
Event: pull_request.opened with author_association == 'FIRST_TIME_CONTRIBUTOR'
Purpose: Welcome first-time contributors warmly, set expectations, and flag for extra-careful review.
Customization points:
good-first-review for team awarenessRequired labels: first-timer
Note: Does not request changes or add friction. Pure welcome + guidance.
Event: issues.labeled with label incident
Purpose: When someone labels an issue as an incident, the agent immediately structures the response: severity assessment, tracker comment, team notification.
Customization points:
Required labels: incident, sev1, sev2, sev3
Agent-applied labels: awful:incident-tracked
Minimal automation for an open source project:
triage + stale + first-timer
For a project with active development and documentation:
triage + pr-review + docs + release
Maximum automation for a production service:
triage + pr-review + docs + release + stale + first-timer + incident
All 7 templates. Incident response is the addition that makes this appropriate for production.
For requirements that don't fit built-in templates:
/awful:design — architect agent interviews you and builds a custom blueprint/awful:gen — generator produces workflow filesTemplates are referenced in the generator's system prompt. When an agent role in the blueprint matches a template name, the generator uses that template as a base and applies blueprint customizations on top.