Add gh-aw agent factory automation suite

.gitattributes

@@ -72,3 +72,7 @@
 *.pfx binary
 *.pem binary
 
+###############################################################################
+# GitHub Agentic Workflows generated lock files
+###############################################################################
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/agents/agentic-workflows.agent.md

@@ -0,0 +1,196 @@
+---
+description: GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing
+disable-model-invocation: true
+---
+
+# GitHub Agentic Workflows Agent
+
+This agent helps you work with **GitHub Agentic Workflows (gh-aw)**, a CLI extension for creating AI-powered workflows in natural language using markdown files.
+
+## What This Agent Does
+
+This is a **dispatcher agent** that routes your request to the appropriate specialized prompt based on your task:
+
+- **Creating new workflows**: Routes to `create` prompt
+- **Updating existing workflows**: Routes to `update` prompt
+- **Debugging workflows**: Routes to `debug` prompt  
+- **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt
+- **Creating report-generating workflows**: Routes to `report` prompt — consult this whenever the workflow posts status updates, audits, analyses, or any structured output as issues, discussions, or comments
+- **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt
+- **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes
+- **Analyzing test coverage**: Routes to `test-coverage` prompt — consult this whenever the workflow reads, analyzes, or reports on test coverage data from PRs or CI runs
+- **CLI commands and triggering workflows**: Routes to `cli-commands` guide — consult this whenever the user asks how to run, compile, debug, or manage workflows from the command line, or when they need the MCP tool equivalent of a `gh aw` command
+
+Workflows may optionally include:
+
+- **Project tracking / monitoring** (GitHub Projects updates, status reporting)
+- **Orchestration / coordination** (one workflow assigning agents or dispatching and coordinating other workflows)
+
+## Files This Applies To
+
+- Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md`
+- Workflow lock files: `.github/workflows/*.lock.yml`
+- Shared components: `.github/workflows/shared/*.md`
+- Configuration: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/github-agentic-workflows.md
+
+## Problems This Solves
+
+- **Workflow Creation**: Design secure, validated agentic workflows with proper triggers, tools, and permissions
+- **Workflow Debugging**: Analyze logs, identify missing tools, investigate failures, and fix configuration issues
+- **Version Upgrades**: Migrate workflows to new gh-aw versions, apply codemods, fix breaking changes
+- **Component Design**: Create reusable shared workflow components that wrap MCP servers
+
+## How to Use
+
+When you interact with this agent, it will:
+
+1. **Understand your intent** - Determine what kind of task you're trying to accomplish
+2. **Route to the right prompt** - Load the specialized prompt file for your task
+3. **Execute the task** - Follow the detailed instructions in the loaded prompt
+
+## Available Prompts
+
+### Create New Workflow
+**Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/create-agentic-workflow.md
+
+**Use cases**:
+- "Create a workflow that triages issues"
+- "I need a workflow to label pull requests"
+- "Design a weekly research automation"
+
+### Update Existing Workflow  
+**Load when**: User wants to modify, improve, or refactor an existing workflow
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/update-agentic-workflow.md
+
+**Use cases**:
+- "Add web-fetch tool to the issue-classifier workflow"
+- "Update the PR reviewer to use discussions instead of issues"
+- "Improve the prompt for the weekly-research workflow"
+
+### Debug Workflow  
+**Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/debug-agentic-workflow.md
+
+**Use cases**:
+- "Why is this workflow failing?"
+- "Analyze the logs for workflow X"
+- "Investigate missing tool calls in run #12345"
+
+### Upgrade Agentic Workflows
+**Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/upgrade-agentic-workflows.md
+
+**Use cases**:
+- "Upgrade all workflows to the latest version"
+- "Fix deprecated fields in workflows"
+- "Apply breaking changes from the new release"
+
+### Create a Report-Generating Workflow
+**Load when**: The workflow being created or updated produces reports — recurring status updates, audit summaries, analyses, or any structured output posted as a GitHub issue, discussion, or comment
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/report.md
+
+**Use cases**:
+- "Create a weekly CI health report"
+- "Post a daily security audit to Discussions"
+- "Add a status update comment to open PRs"
+
+### Create Shared Agentic Workflow
+**Load when**: User wants to create a reusable workflow component or wrap an MCP server
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/create-shared-agentic-workflow.md
+
+**Use cases**:
+- "Create a shared component for Notion integration"
+- "Wrap the Slack MCP server as a reusable component"
+- "Design a shared workflow for database queries"
+
+### Fix Dependabot PRs
+**Load when**: User needs to close or fix open Dependabot PRs that update dependencies in generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`)
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/dependabot.md
+
+**Use cases**:
+- "Fix the open Dependabot PRs for npm dependencies"
+- "Bundle and close the Dependabot PRs for workflow dependencies"
+- "Update @playwright/test to fix the Dependabot PR"
+
+### Analyze Test Coverage
+**Load when**: The workflow reads, analyzes, or reports test coverage — whether triggered by a PR, a schedule, or a slash command. Always consult this prompt before designing the coverage data strategy.
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/test-coverage.md
+
+**Use cases**:
+- "Create a workflow that comments coverage on PRs"
+- "Analyze coverage trends over time"
+- "Add a coverage gate that blocks PRs below a threshold"
+
+### CLI Commands Reference
+**Load when**: The user asks how to run, compile, debug, or manage workflows from the command line; needs the MCP tool equivalent of a `gh aw` command; or is in a restricted environment (e.g., Copilot Cloud) without direct CLI access.
+
+**Reference file**: https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/cli-commands.md
+
+**Use cases**:
+- "How do I trigger workflow X on the main branch?"
+- "What's the MCP equivalent of `gh aw logs`?"
+- "I'm in Copilot Cloud — how do I compile a workflow?"
+- "Show me all available gh aw commands"
+
+## Instructions
+
+When a user interacts with you:
+
+1. **Identify the task type** from the user's request
+2. **Load the appropriate prompt** from the GitHub repository URLs listed above
+3. **Follow the loaded prompt's instructions** exactly
+4. **If uncertain**, ask clarifying questions to determine the right prompt
+
+## Quick Reference
+
+```bash
+# Initialize repository for agentic workflows
+gh aw init
+
+# Generate the lock file for a workflow
+gh aw compile [workflow-name]
+
+# Trigger a workflow on demand (preferred over gh workflow run)
+gh aw run <workflow-name>             # interactive input collection
+gh aw run <workflow-name> --ref main  # run on a specific branch
+
+# Debug workflow runs
+gh aw logs [workflow-name]
+gh aw audit <run-id>
+
+# Upgrade workflows
+gh aw fix --write
+gh aw compile --validate
+```
+
+## Key Features of gh-aw
+
+- **Natural Language Workflows**: Write workflows in markdown with YAML frontmatter
+- **AI Engine Support**: Copilot, Claude, Codex, or custom engines
+- **MCP Server Integration**: Connect to Model Context Protocol servers for tools
+- **Safe Outputs**: Structured communication between AI and GitHub API
+- **Strict Mode**: Security-first validation and sandboxing
+- **Shared Components**: Reusable workflow building blocks
+- **Repo Memory**: Persistent git-backed storage for agents
+- **Sandboxed Execution**: All workflows run in the Agent Workflow Firewall (AWF) sandbox, enabling full `bash` and `edit` tools by default
+
+## Important Notes
+
+- Always reference the instructions file at https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/github-agentic-workflows.md for complete documentation
+- Use the MCP tool `agentic-workflows` when running in GitHub Copilot Cloud
+- Workflows must be compiled to `.lock.yml` files before running in GitHub Actions
+- **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF
+- Follow security best practices: minimal permissions, explicit network access, no template injection
+- **Network configuration**: Use ecosystem identifiers (`node`, `python`, `go`, etc.) or explicit FQDNs in `network.allowed`. Bare shorthands like `npm` or `pypi` are **not** valid. See https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/network.md for the full list of valid ecosystem identifiers and domain patterns.
+- **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>` to trigger a workflow on demand — not `gh workflow run <file>.lock.yml`. `gh aw run` handles workflow resolution by short name, input parsing and validation, and correct run-tracking for agentic workflows. Use `--ref <branch>` to run on a specific branch.
+- **CLI commands reference**: For a complete guide on all `gh aw` commands and their MCP tool equivalents (for restricted environments), see https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/cli-commands.md

.github/aw/actions-lock.json

@@ -0,0 +1,19 @@
+{
+  "entries": {
+    "actions/github-script@v9.0.0": {
+      "repo": "actions/github-script",
+      "version": "v9.0.0",
+      "sha": "3a2844b7e9c422d3c10d287c895573f7108da1b3"
+    },
+    "github/gh-aw-actions/setup-cli@v0.72.0": {
+      "repo": "github/gh-aw-actions/setup-cli",
+      "version": "v0.72.0",
+      "sha": "ff0525b685481744f490a0d362753d8001e4b39d"
+    },
+    "github/gh-aw-actions/setup@v0.72.0": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.72.0",
+      "sha": "ff0525b685481744f490a0d362753d8001e4b39d"
+    }
+  }
+}

.github/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "github-agentic-workflows": {
+      "command": "gh",
+      "args": [
+        "aw",
+        "mcp-server"
+      ]
+    }
+  }
+}

.github/workflows/agentic.md

@@ -0,0 +1,131 @@
+# Agentic Workflows
+
+This repository uses [GitHub Agentic Workflows (`gh aw`)](https://github.github.com/gh-aw/)
+to run a small suite of AI-powered automations alongside the standard CI workflows.
+Each workflow is authored as a Markdown file with YAML frontmatter and compiled to a
+sibling `*.lock.yml` GitHub Actions file by `gh aw compile`. Both files are committed.
+
+The set is intentionally narrow and modeled on patterns from [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).
+
+## Workflow catalog
+
+| Workflow | Source | Trigger | Effect |
+|---|---|---|---|
+| [`issue-triage`](./issue-triage.md) | `githubnext/agentics/workflows/issue-triage` *(retuned)* | `issues: [opened, reopened]` | Labels, comments on, types, or closes the triggering issue (spam only). Rubric tightened to the repo's actual label set — see the workflow source. |
+| [`backlog-triage`](./backlog-triage.md) | Custom (this repo) | `schedule: weekly on monday` + `workflow_dispatch` | Picks up to 10 oldest open issues with no area / type label and no prior triage comment, then applies the `issue-triage` rubric to each. Idempotent via a `<!-- backlog-triage -->` marker comment. |
+| [`ci-doctor`](./ci-doctor.md) | `githubnext/agentics/workflows/ci-doctor` | `workflow_run` on `["Aspire Samples CI"]` completed on `main` | Files a `[ci-doctor]` issue (labels `automation`, `ci`) with root-cause analysis when CI fails. **Only investigates main-branch runs — PR-CI failures are out of scope.** |
+| [`doc-updater`](./doc-updater.md) | `githubnext/agentics/workflows/doc-updater` *(retuned)* | `schedule: weekly on monday` + `workflow_dispatch` | Opens a `[docs]` pull request that updates **only** `samples/*/README.md` files whose corresponding sample folder had material code changes in the last week. Strictly does not touch the root `README.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `LICENSE`, or anything outside `samples/`. |
+| [`malicious-code-scan`](./malicious-code-scan.md) | `githubnext/agentics/workflows/malicious-code-scan` | `schedule: daily` + `workflow_dispatch` | Reviews the last 3 days of code changes for supply-chain / exfiltration patterns and files Code Scanning alerts to the Security tab (not the issue tracker). |
+
+A sixth workflow, `agentics-maintenance.yml`, is generated automatically by
+`gh aw compile` because `doc-updater` uses the `expires` field; it sweeps expired
+draft items on a schedule and should be left alone.
+
+## Known caveats
+
+- **`set-issue-type` may silently no-op.** This safe output sets a repo-level
+  *issue type* (Bug/Feature/Task), not a label. It only works if the parent
+  organization has issue types configured and exposed to this repo. If the org
+  hasn't enabled them, the call fails silently and the agent falls back to a type
+  *label* (`bug` / `enhancement` / `documentation`) per the rubric — this is
+  intentional and not a bug.
+- **`ci-doctor` only investigates `main` failures.** PR-CI failures are
+  deliberately out of scope: the doctor's job is to alert maintainers when the
+  protected branch breaks, not to comment on every red PR. If you want a per-PR
+  fix-it agent, add `pr-fix` (`gh aw add githubnext/agentics/workflows/pr-fix`) in
+  a follow-up PR.
+- **`malicious-code-scan` requires Code Scanning to be enabled.** The workflow
+  publishes alerts via the `create-code-scanning-alert` safe output, which uses
+  the GitHub Code Scanning API. Microsoft repos generally have Advanced Security
+  (and therefore Code Scanning) enabled. If alerts don't appear in the Security
+  tab after a run, confirm Code Scanning is on for the repo before assuming a
+  workflow bug.
+
+## Authentication model
+
+Two credential systems are involved. Both must be configured by a repository
+administrator before any workflow can run successfully.
+
+### 1. AI engine — Copilot (`COPILOT_GITHUB_TOKEN`)
+
+All four workflows use the `copilot` engine. Copilot requires a fine-grained
+Personal Access Token with the `Copilot Requests: Read` permission, stored as a
+repository secret named `COPILOT_GITHUB_TOKEN`. Per the `gh aw` auth model this
+secret **cannot** be a GitHub App token; it must be a PAT owned by a user with an
+active Copilot license. See
+[gh-aw auth reference](https://github.github.com/gh-aw/reference/auth/#copilot_github_token)
+for the setup link with the correct permission pre-selected.
+
+### 2. GitHub tools + safe-outputs — `ASPIRE_BOT` GitHub App
+
+All write-back operations (labels, comments, issues, PRs, code-scanning alerts) go
+through a dedicated GitHub App, `ASPIRE_BOT`, using
+[`actions/create-github-app-token`](https://github.com/actions/create-github-app-token)
+to mint a short-lived, scope-minimized token per job. Two repository secrets:
+
+| Secret | What it is |
+|---|---|
+| `ASPIRE_BOT_APP_ID` | The App ID (or Client ID) of the `ASPIRE_BOT` GitHub App. |
+| `ASPIRE_BOT_PRIVATE_KEY` | The PEM-encoded private key for the App. |
+
+The `ASPIRE_BOT` App must be **installed on this repository** with at minimum:
+
+- `Contents`: Read & write (for `doc-updater`'s PR branch pushes)
+- `Issues`: Read & write (for `issue-triage` and `ci-doctor`)
+- `Pull requests`: Read & write (for `doc-updater`)
+- `Metadata`: Read
+- `Code scanning alerts`: Read & write (for `malicious-code-scan`)
+- `Actions`: Read (for `ci-doctor` reading workflow run logs)
+
+## Running locally
+
+The `gh aw` CLI is required for development:
+
+```bash
+gh extension install github/gh-aw
+```
+
+Useful commands when editing a workflow:
+
+```bash
+gh aw validate                 # schema-check all workflows
+gh aw compile                  # regenerate *.lock.yml files (commit both)
+gh aw status                   # show registered workflows and last-run info
+gh aw run <workflow-name>      # trigger a workflow on GitHub Actions
+gh aw audit <run-id-or-url>    # download logs and generate a report
+```
+
+`*.lock.yml` files are marked `linguist-generated=true merge=ours` in
+`.gitattributes`. Do not edit them by hand — re-run `gh aw compile` after changing
+the source `.md`.
+
+## Customizing a workflow
+
+1. Edit the relevant `.github/workflows/<name>.md`. The frontmatter (between the
+   `---` markers) controls triggers, permissions, tools, safe-outputs, and the
+   engine. The body below is the natural-language prompt.
+2. Run `gh aw compile --approve` from the repo root.
+3. Commit **both** the `.md` and the regenerated `.lock.yml`.
+
+For `ci-doctor`, the list of workflows it watches lives in
+`ci-doctor.md` under `on.workflow_run.workflows`. Add more workflow `name:` values
+there if you want the doctor to investigate failures of other workflows on `main`.
+
+## Disabling the suite
+
+To temporarily silence the agents without removing them:
+
+```bash
+gh aw disable issue-triage backlog-triage ci-doctor doc-updater malicious-code-scan
+```
+
+Re-enable with `gh aw enable <name>`.
+
+## Why these workflows?
+
+These map to the most-trafficked patterns from the agent factory tour: triage
+(both new issues and the stale backlog), fault investigation, documentation
+hygiene, and security compliance. Other useful agents (`daily-repo-status`,
+`pr-fix`, ChatOps-style assistants, etc.) can be added later via
+`gh aw add githubnext/agentics/<workflow-name>` and are intentionally deferred
+until this baseline is proven.