From 5e58f5ad605864525653ed0da86cce4577d461c0 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sun, 19 Apr 2026 12:08:50 +0000
Subject: [PATCH] docs: document infrastructure workflows and VS Code tooling

README was missing agentics-maintenance.yml, copilot-setup-steps.yml,
and the .vscode/ directory from the repository layout section.
Added an "Infrastructure workflows" table explaining how these files
are created and what they do, so contributors aren't confused by
files absent from the documented workflow table.

CONTRIBUTING.md now explains what .vscode/mcp.json and settings.json
provide for VS Code + GitHub Copilot Agent users.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CONTRIBUTING.md |  6 ++++++
 README.md       | 17 +++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e348af4..88201af 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,6 +19,12 @@ claude --plugin-dir .
 
 `--plugin-dir .` tells Claude Code to load the plugin manifest from `.claude-plugin/plugin.json` and discover skills in `skills/*/SKILL.md`. The plugin runs entirely locally — no build step, no compilation.
 
+### VS Code + GitHub Copilot setup
+
+If you use VS Code with GitHub Copilot Agent, `.vscode/mcp.json` pre-configures the `gh-aw` MCP server so Copilot can call `gh aw` tools directly (compile, validate, audit, etc.). No manual setup required — open the repo in VS Code and the MCP server activates automatically.
+
+`.vscode/settings.json` marks `*.md` files in `.github/workflows/` as the `github-agentic-workflow` language so Copilot provides correct completions for workflow frontmatter.
+
 ## How the plugin works
 
 ```
diff --git a/README.md b/README.md
index 944f714..b0f38d8 100644
--- a/README.md
+++ b/README.md
@@ -117,12 +117,29 @@ skills/
     q.{md,lock.yml}
     markdown-linter.{md,lock.yml}
     pr-nitpick-reviewer.{md,lock.yml}
+    agentics-maintenance.yml       # auto-generated by gh-aw; manages expiring issues/PRs
+    copilot-setup-steps.yml        # installs gh-aw CLI for GitHub Copilot Agent sessions
     shared/
       reporting.md                 # shared reporting component (run-link formatting)
+
+.vscode/
+  mcp.json                         # MCP server config (gh-aw tools for Copilot in VS Code)
+  settings.json                    # GitHub Copilot markdown association settings
 ```
 
 `.lock.yml` files are marked as `linguist-generated` and `merge=ours` in `.gitattributes` to prevent spurious merge conflicts.
 
+### Infrastructure workflows
+
+Two workflow files are not user-installed — they are managed entirely by `gh aw`:
+
+| File | How it's created | Purpose |
+|---|---|---|
+| `agentics-maintenance.yml` | Auto-generated on `gh aw compile` when any workflow uses `expires:` | Cleans up time-limited issues and PRs on a schedule |
+| `copilot-setup-steps.yml` | Manually committed once | Pre-installs the `gh-aw` CLI extension so GitHub Copilot Agent sessions have it available |
+
+Do not edit `agentics-maintenance.yml` by hand — it is regenerated automatically.
+
 ## Local development
 
 ```bash