feat: add test-coverage prompt with artifact-reading guidance

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

@@ -18,6 +18,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 - **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
 
 Workflows may optionally include:
 
@@ -118,6 +119,16 @@ When you interact with this agent, it will:
 - "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/main/.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"
+
 ## Instructions
 
 When a user interacts with you:

.github/aw/test-coverage.md

@@ -0,0 +1,53 @@
+---
+description: Guidance for creating agentic workflows that analyze test coverage — prefer reading pre-computed CI artifacts over re-running tests.
+---
+
+# Test Coverage Workflow Guidance
+
+Consult this file when creating or updating a workflow that analyzes test coverage.
+
+## Core Principle: Read Artifacts First
+
+**Always prefer fetching pre-computed coverage artifacts from CI over re-running the test suite.** Re-running tests is slow and duplicates work CI has already done.
+
+## Coverage Data Strategy
+
+Include this decision block in every coverage workflow prompt:
+
+```
+1. Find the latest successful CI run for this commit:
+   `gh run list --commit "$HEAD_SHA" --status success --limit 5 --json databaseId,workflowName`
+2. Download the coverage artifact (try names: coverage-report, coverage, test-results):
+   `gh run download <run-id> --name coverage-report --dir /tmp/coverage`
+3. If found, parse and analyze it — do NOT re-run tests.
+4. If not found, run tests with coverage and note in the report that data was computed fresh.
+```
+
+## Frontmatter Template
+
+```yaml
+engine: copilot
+on:
+  pull_request:
+    types: [opened, synchronize]
+permissions:
+  pull-requests: write  # post coverage comment
+  actions: read         # download artifacts
+network: defaults
+tools:
+  github:
+    toolsets: [default, actions]  # actions toolset enables artifact download
+safe-outputs:
+  add-comment:
+    hide-older-comments: true
+```
+
+## Fallback: Run Tests
+
+Use **only when** no prior CI artifact exists or CI doesn't upload coverage. Supported commands:
+
+| Language | Command |
+|---|---|
+| Node.js | `npx jest --coverage --coverageReporters=json-summary` |
+| Python | `python -m pytest --cov=src --cov-report=json` |
+| Go | `go test ./... -coverprofile=/tmp/coverage.out` |