Use Cases & Examples

📋 All 12 Use Case Categories

From simple triage to multi-repo orchestration — find the right automation for your needs.

---

🏷️ 1. Issue Triage & Labeling

The “hello world” of agentic workflows — practical, immediately useful, and simple to implement. When a new issue is opened, the agent reads it, researches the codebase, applies labels, and posts a helpful comment.

📄 .github/workflows/issue-triage-agent.md

---
timeout-minutes: 5
on:
  issue:
    types: [opened, reopened]

permissions:
  issues: read

tools:
  github:
    toolsets: [issues, labels]

safe-outputs:
  add-labels:
    allowed: [bug, feature, enhancement, documentation, question, help-wanted, good-first-issue]
  add-comment: {}
---

# Issue Triage Agent

List open issues in ${{ github.repository }} that have no labels. For each
unlabeled issue, analyze the title and body, then add one of the allowed
labels: `bug`, `feature`, `enhancement`, `documentation`, `question`,
`help-wanted`, or `good-first-issue`.

Skip issues that:
- Already have any of these labels
- Have been assigned to any user (especially non-bot users)

Do research on the issue in the context of the codebase and, after
adding the label to an issue, mention the issue author in a comment, explain
why the label was added and give a brief summary of how the issue may be
addressed.

---

📚 2. Continuous Documentation Maintenance

Code evolves rapidly; docs do not. Agentic workflows maintain, validate, and improve documentation continuously — catching drift, outdated examples, and terminology inconsistencies.

Workflow	Results	Merge Rate
Daily Documentation Updater	57 merged PRs out of 59 proposed	96%
Glossary Maintainer	10 merged PRs out of 10 proposed	100%
Documentation Unbloat	88 merged PRs out of 103 proposed	85%
Documentation Noob Tester	9 merged PRs (via causal chain)	43%
Multi-device Docs Tester	2 merged PRs out of 2 proposed	100%

📄 .github/workflows/daily-doc-updater.md

---
on:
  schedule: daily

permissions:
  contents: read
  pull-requests: read

tools:
  github:
    toolsets: [default, pull_requests]

safe-outputs:
  create-pull-request:
    title-prefix: "[docs] "
    branch-pattern: "^automated/docs-.*"
---

# Daily Documentation Updater

Review the repository documentation for accuracy and completeness.

## Tasks
- Compare documentation against the current codebase for drift
- Identify outdated code examples, deprecated API references, and broken links
- Update README sections that reference changed functionality
- Ensure all public functions and modules have accurate documentation

## Guidelines
- Keep existing tone and style consistent
- Only propose changes where documentation is factually wrong or missing
- Group related changes into a single pull request
- Write clear PR descriptions explaining what changed and why

---

🔧 3. CI Failure Analysis

The CI Doctor transforms how teams respond to CI failures. Instead of drowning in failure notifications, maintainers receive investigated failures with diagnostic insights, root cause analysis, and proposed fixes.

📄 .github/workflows/ci-failure-doctor.md

---
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    conclusions: [failure]

permissions:
  contents: read
  actions: read
  issues: read

tools:
  github:
    toolsets: [default, actions]

safe-outputs:
  create-issue:
    title-prefix: "[ci-doctor] "
    labels: [ci-failure, needs-investigation]
  create-pull-request:
    title-prefix: "[ci-fix] "
    branch-pattern: "^automated/ci-fix-.*"
---

# CI Failure Doctor

A CI workflow has failed. Investigate the failure and help the team resolve it.

## Investigation Steps
1. Retrieve and analyze the failed workflow run logs
2. Identify the root cause of the failure
3. Search for similar past issues and their resolutions
4. Check if the failure is flaky (intermittent) or deterministic

## Output
- If the fix is straightforward, create a pull request with the fix
- If investigation is needed, create an issue with:
  - Summary of the failure
  - Root cause analysis
  - Suggested remediation steps
  - Links to relevant logs and code

---

🧪 4. Continuous Test Coverage Improvement

Testing agents continuously identify coverage gaps, propose new test cases, and validate existing tests. Small, frequent improvements compound over time.

Workflow	Results	Merge Rate
Daily Testify Expert	19 issues created, 13 led to merged PRs	100% causal
Daily Test Improver	Identifies gaps, implements new tests	Incremental
CLI Consistency Checker	80 merged PRs out of 102 proposed	78%
CI Coach	9 merged PRs out of 9 proposed	100%

📄 .github/workflows/daily-test-improver.md

---
on:
  schedule: daily

permissions:
  contents: read

tools:
  github:
    toolsets: [default]

safe-outputs:
  create-pull-request:
    title-prefix: "[tests] "
    branch-pattern: "^automated/test-.*"
  create-issue:
    title-prefix: "[test-gap] "
    labels: [testing, coverage]
---

# Daily Test Improver

Analyze the test suite for coverage gaps and quality improvements.

## Analysis Tasks
- Identify source files with low or no test coverage
- Find functions and branches that lack edge case testing
- Review existing tests for assertion quality and completeness
- Look for test patterns that could be modernized

## Output
- Create a pull request adding one focused, high-value test
- Include clear descriptions of what the test covers and why it matters
- Ensure new tests follow existing project conventions
- Run the test suite to verify tests pass before proposing

---

📊 5. Repository Reporting & Metrics

Among the simplest workflows to set up. Create regular summaries of repository health, activity, and trends — providing immediate value to maintainers.

📄 .github/workflows/weekly-issue-summary.md

---
on:
  schedule:
    - cron: "0 9 * * MON"

permissions:
  contents: read
  issues: read
  pull-requests: read
  discussions: read

safe-outputs:
  create-issue:
    title-prefix: "[weekly-summary] "
    labels: [report, weekly]
    close-older-issues: true

tools:
  github:
---

# Weekly Issue Summary

Generate a comprehensive weekly summary of issue activity.

## Report Sections
1. **New Issues** — List all issues opened this week with brief descriptions
2. **Closed Issues** — Issues resolved this week and how they were fixed
3. **Stale Issues** — Issues with no activity in the past 14 days
4. **Trending Topics** — Common themes or patterns across recent issues
5. **Recommendations** — Suggested priorities for the coming week

## Format
- Use tables for structured data
- Include trend indicators (↑ ↓ →) where relevant
- Link directly to each referenced issue
- Keep the total report under 500 words

Factory Workflow	Output	Volume
Metrics Collector	Daily metrics tracking agent ecosystem performance	41 discussions
Portfolio Analyst	Cost reduction opportunities & token optimization	7 analysis discussions
Audit Workflows	Meta-agent analyzing logs, costs, errors, success patterns	93 audit reports, 9 issues

---

🛡️ 6. Security & Vulnerability Triage

Security workflows act as automated guardians — scanning for vulnerabilities, exposed credentials, malicious code patterns, and compliance violations.

Factory Workflow	Output	Results
Security Compliance	Vulnerability campaigns with deadline tracking	SLA-driven remediation
Firewall	Network security validation	59 daily reports, 5 smoke tests
Daily Secrets Analysis	Credential exposure scanning	Continuous monitoring
Daily Malicious Code Scan	Suspicious pattern detection	Supply chain defense
Static Analysis Report	Security audits (zizmor, poutine, actionlint)	57 discussions, 12 reports

📄 .github/workflows/pr-security-reviewer.md

---
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: read

tools:
  github:
    toolsets: [default, pull_requests]

safe-outputs:
  add-comment:
    max: 1
---

# PR Security Reviewer

Review the pull request diff for security concerns.

## What to Check
1. **Secrets & Credentials** — hardcoded API keys, tokens, passwords
2. **Injection Vulnerabilities** — SQL injection, XSS, command injection
3. **Dependency Changes** — new deps with known vulnerabilities
4. **Permission Escalation** — changes to auth/access control logic
5. **GitHub Actions Security** — unsafe workflow patterns

## Output Format
Post a single comment with:
- 🔴 **Critical** findings that must be addressed before merge
- 🟡 **Warning** findings that should be reviewed
- 🟢 **Info** observations about security-related changes
- If no issues found, post a brief "Security review passed" comment

---

✨ 7. Code Quality & Continuous Refactoring

Refactoring agents continuously analyze code structure and propose improvements — splitting oversized files, extracting duplicated logic, and identifying dead code.

📄 .github/workflows/code-simplifier.md

---
on:
  schedule: daily

permissions:
  contents: read

tools:
  github:
    toolsets: [default]

safe-outputs:
  create-pull-request:
    title-prefix: "[simplify] "
    branch-pattern: "^automated/simplify-.*"
---

# Continuous Code Simplifier

Identify opportunities to simplify and improve code quality.

## Analysis Tasks
- Find files over 300 lines that could be split into focused modules
- Identify duplicated code blocks for shared utilities extraction
- Look for overly complex functions (high cyclomatic complexity)
- Find dead code (unused imports, unreachable branches, commented-out code)

## Output
- Create one focused pull request per simplification
- Each PR should address a single concern
- Include before/after metrics (lines of code, complexity score)
- Ensure all existing tests continue to pass
- Explain the refactoring rationale clearly in the PR description

📄 .github/workflows/performance-auditor.md

---
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: read

safe-outputs:
  add-comment: {}
---

# Big O Performance Auditor

Review the pull request for algorithmic performance concerns.

## Analysis
- Estimate time and space complexity of changed functions
- Identify potential bottlenecks (nested loops, repeated collection scans)
- Flag operations that scale poorly with input size

## Output Format
Post a structured comment with:
- Complexity estimate for each flagged function
- The specific bottleneck identified
- A refactored implementation suggestion
- Estimated performance impact

---

🚀 8. Release Notes & Changelog Generation

Automate version bumps and human-readable changelog entries. The Changeset workflow in Peli’s Agent Factory achieved a 78% merge rate (22 merged out of 28 proposed PRs).

📄 .github/workflows/release-changelog.md

---
on:
  release:
    types: [published]

permissions:
  contents: read
  pull-requests: read

tools:
  github:
    toolsets: [default, pull_requests]

safe-outputs:
  create-pull-request:
    title-prefix: "[changelog] "
    branch-pattern: "^automated/changelog-.*"
---

# Release Changelog Generator

A new release has been published. Generate a comprehensive changelog.

## Tasks
1. Analyze all commits since the previous release tag
2. Categorize changes into:
   - 🚀 **Features** — new functionality
   - 🐛 **Bug Fixes** — resolved issues
   - 📖 **Documentation** — doc improvements
   - ⚡ **Performance** — speed or efficiency improvements
   - 🔧 **Maintenance** — refactoring, dependency updates, CI changes
   - 💥 **Breaking Changes** — backward-incompatible modifications
3. Generate a human-readable changelog entry
4. Update the CHANGELOG.md file

## Guidelines
- Link each entry to the relevant PR or commit
- Credit contributors by @mention
- Highlight breaking changes prominently at the top
- Follow the Keep a Changelog format (keepachangelog.com)

---

📦 9. Dependency Management

Agentic workflows analyze dependency updates with contextual awareness that simple automated tools lack — assessing risk, checking changelogs, and grouping related updates intelligently.

📄 .github/workflows/dependency-auditor.md

---
on:
  schedule:
    - cron: "0 10 * * MON"

permissions:
  contents: read

tools:
  github:
    toolsets: [default]

safe-outputs:
  create-pull-request:
    title-prefix: "[deps] "
    branch-pattern: "^automated/deps-.*"
  create-issue:
    title-prefix: "[dep-alert] "
    labels: [dependencies, needs-review]
---

# Weekly Dependency Audit

Analyze project dependencies for updates, vulnerabilities, and health.

## Analysis Tasks
1. Check for outdated dependencies and their latest versions
2. Assess risk and breaking change potential for each update
3. Identify deprecated packages that need migration
4. Review dependency health signals (maintenance activity, download trends)

## Output
- For safe, minor updates: create a PR grouping related updates together
- For major version bumps: create an issue with a migration guide
- For security vulnerabilities: create a high-priority issue with remediation
- Include a risk assessment for each proposed change

## Guidelines
- Group related dependency updates into coherent PRs
- Never update multiple major versions simultaneously
- Include test results confirming compatibility
- Link to changelogs and migration guides

---

😤 10. Code Review Assistance

Pull request review agents provide contextual feedback on code changes without replacing human judgment. The Grumpy Reviewer from githubnext/agentics is the standout example.

Factory Workflow	Output	Volume
Schema Consistency Checker	Detects schema/code/doc drift	55 analysis discussions
Breaking Change Checker	Backward-incompatibility alerts	Alert issues
Big O Performance Auditor	Complexity estimates on PRs	PR comments

📄 .github/workflows/grumpy-reviewer.md — from githubnext/agentics

---
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: read
  issues: read

tools:
  github:
    toolsets: [default, pull_requests]

safe-outputs:
  add-comment:
    max: 1
---

# Grumpy Code Reviewer

You are a grumpy but thorough senior developer performing an on-demand
code review. You've seen every anti-pattern, survived every production
incident, and have strong opinions backed by decades of experience.

## When Triggered
Respond when a maintainer comments "/review" on a pull request.

## Review Focus
1. **Correctness** — Will this code actually work? Edge cases? Error handling?
2. **Performance** — Any obvious bottlenecks or scaling issues?
3. **Security** — Input validation? Injection risks? Auth issues?
4. **Maintainability** — Will future-you understand this in 6 months?
5. **Testing** — Are the tests actually testing anything meaningful?

## Tone
- Be direct and opinionated, but never mean
- Use dry humor sparingly
- Always explain WHY something is a problem, not just THAT it is
- Acknowledge good code when you see it (grudgingly)

📄 .github/workflows/breaking-change-checker.md

---
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: read

safe-outputs:
  add-comment:
    max: 1
  create-issue:
    title-prefix: "[breaking-change] "
    labels: [breaking-change, needs-review]
---

# Breaking Change Checker

Analyze the pull request for backward-incompatible changes.

## What Constitutes a Breaking Change
- Removed or renamed public functions, classes, or methods
- Changed function signatures (added required parameters, changed return types)
- Modified data structures or API response shapes
- Changed default values for configuration options
- Removed or renamed CLI commands or flags
- Database schema changes that aren't additive

## Output
- If breaking changes found: post a comment + create a tracking issue
- If no breaking changes, post a brief confirmation comment

---

🧩 Design Patterns

Operational patterns that structure how agentic workflows are organized and triggered.

---

🔒 Safe-Outputs Quick Reference

The core security mechanism — every write operation must be declared in frontmatter.

---

🏭 Peli’s Agent Factory

GitHub Next’s internal collection — the most extensive real-world deployment of agentic workflows.

🎓 Key Lessons Learned

📦 The Agentics Collection (githubnext/agentics)

Community-contributed, MIT-licensed reusable workflows. Install with gh aw add-wizard.

---

🧭 Choosing the Right Approach

Not everything should be an agentic workflow. Here’s how to decide.

---

🚦 Getting Started Progression

A recommended path from first workflow to full automation suite.