# Maf Release Watcher > Detects new MAF releases, extracts breaking changes, and keeps the toolkit's registry/matrix/guide current. Three-stage pipeline: (1) deterministic data extraction via GitHub Actions + Python helpers + dotnet-inspect, commits raw data with TODOs directly to main, (2) dispatches a sibling workflow that opens a GitHub issue for GitHub Copilot Coding Agent to fill the TODOs, (3) Copilot opens a PR w… - **Type:** Skill - **Install:** `agentstack add skill-joslat-maf-doctor-maf-release-watcher` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [joslat](https://agentstack.voostack.com/s/joslat) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [joslat](https://github.com/joslat) - **Source:** https://github.com/joslat/maf-doctor/tree/main/.github/skills/maf-release-watcher ## Install ```sh agentstack add skill-joslat-maf-doctor-maf-release-watcher ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # maf-release-watcher ## Purpose When Microsoft ships a new MAF version, this pipeline keeps the toolkit's three artefacts current with zero manual baseline-update work: - **`.maf-version`** — the tracked-current pointer - **`docs/compatibility-matrix.md`** — dependency-version table (new row per release) - **`guides/maf-X.Y.Z-migration-guide.md`** — per-version delta with banner pointing back to the chain - **`guides/maf-current-migration-guide.md`** — auto-regenerated cumulative reference - **`.github/skills/maf-obsolete-api-registry/registry.yaml`** — append-only breaking-change registry Two of those (`compatibility-matrix.md` row contents, per-version guide TODO sections, registry-entry TODO fields) require *judgement* the deterministic pipeline can't fully automate — release notes have to be interpreted, before/after C# examples written, etc. That work is delegated to **GitHub Copilot Coding Agent** via a second workflow (`maf-ai-fill-todos.yml`) that opens an issue with a structured prompt and assigns the bot. --- ## When this skill is "invoked" It isn't, in the Copilot-Chat sense. The work runs in GitHub Actions VMs, not in a Copilot conversation. This skill is the **reference doc** explaining what those workflows do, so a maintainer reading the repo can understand the whole loop without piecing it together from two `.yml` files plus three Python scripts. Triggers for the pipeline itself: - **Weekly cron**: `0 9 * * 1` (Monday 09:00 UTC) — defined in `.github/workflows/maf-release-watcher.yml` - **Manual dispatch**: `gh workflow run maf-release-watcher.yml -f maf_version=X.Y.Z` --- ## Architecture — the three stages ``` TRIGGER (cron or gh workflow run) │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ STAGE 1 — Deterministic data extraction │ │ .github/workflows/maf-release-watcher.yml │ │ Runs on a fresh Ubuntu VM provisioned by GitHub Actions │ │ NO LLM, NO AGENT — just shell + Python + dotnet CLI │ ├────────────────────────────────────────────────────────────────────┤ │ │ │ 1.1 Check NuGet for latest MAF stable │ │ 1.2 Run `dotnet-inspect diff` for Microsoft.Agents.AI[.Workflows]│ │ 1.3 Fetch GitHub release notes from microsoft/agent-framework │ │ 1.4 Run `python3 .github/scripts/update_compat_matrix.py` │ │ → inserts a new row at the top of compatibility-matrix.md │ │ 1.5 Run `python3 .github/scripts/gen_guide_section.py` │ │ → writes guides/maf-X.Y.Z-migration-guide.md │ │ → ALSO regenerates guides/maf-current-migration-guide.md │ │ 1.6 Run `maf-doctor registry-extract` (the dotnet tool CLI) │ │ → emits draft registry entries, appended to registry.yaml │ │ 1.7 Update .maf-version │ │ 1.8 Upload diff-core.txt / diff-workflows.txt / release-notes.txt│ │ as workflow artefacts for reviewer audit │ │ 1.9 git commit + git push origin main │ │ (direct-to-main; PR-based gate was removed 2026-05-12 │ │ per maintainer preference for solo workflow) │ │ 1.10 gh workflow run maf-ai-fill-todos.yml -f target_version=X.Y.Z│ │ → dispatches Stage 2, decoupled / async │ │ │ └────────────────────────────────────────────────────────────────────┘ │ async dispatch ▼ ┌────────────────────────────────────────────────────────────────────┐ │ STAGE 2 — AI-fill dispatch │ │ .github/workflows/maf-ai-fill-todos.yml │ │ Runs on ANOTHER fresh Ubuntu VM │ │ Still no LLM — just creates an issue + assigns Copilot │ ├────────────────────────────────────────────────────────────────────┤ │ │ │ 2.1 Ensure `maf-release` and `ai-fill` labels exist (idempotent) │ │ 2.2 Open a GitHub issue: │ │ - Title: "Fill TODOs for MAF X.Y.Z" │ │ - Body: full filling prompt (the prompt the maintainer │ │ wrote — what to fill, style anchor, constraints) │ │ - Labels: maf-release,ai-fill │ │ 2.3 Assign Copilot Coding Agent via GraphQL │ │ - bot ID: BOT_kgDOC9w8XQ (stable across all repos) │ │ - mutation: addAssigneesToAssignable (additive) │ │ (gh CLI's --assignee doesn't work — REST `/users/Copilot` │ │ doesn't return the bot. GraphQL does.) │ │ │ └────────────────────────────────────────────────────────────────────┘ │ issue assignment ▼ ┌────────────────────────────────────────────────────────────────────┐ │ STAGE 3 — GitHub Copilot Coding Agent │ │ Runs on GitHub's own infrastructure (NOT our workflow VM) │ │ THIS is the LLM/agent part │ ├────────────────────────────────────────────────────────────────────┤ │ │ │ 3.1 Reads the issue body (the prompt) │ │ 3.2 Reads the repo (registry.yaml, matrix, guide, release notes) │ │ 3.3 Creates a branch (e.g. copilot/fill-todos-for-maf-1-4-0) │ │ 3.4 Makes file edits — fills the TODOs: │ │ - registry: fix_description, example_before/after, │ │ guide_section (N/A if no parallel in 1.3 guide) │ │ - compat matrix: real version constraints if release │ │ notes mention them, else `unknown` + TODO comment │ │ - per-version guide: Breaking Changes, New Patterns, │ │ Obsolete APIs, Known Misalignments sections │ │ - clean up terminal-escape artefacts in diff summary │ │ 3.5 Opens a draft PR titled │ │ "chore: AI-filled TODOs for MAF X.Y.Z" │ │ labelled `maf-release,ai-fill` │ │ │ └────────────────────────────────────────────────────────────────────┘ ``` --- ## The Python helper scripts — what, where, why The Python scripts in `.github/scripts/` are **CI-runner code** invoked by the Stage-1 workflow via `run: python3 .github/scripts/.py`. They are NOT skills, NOT MCP tools, NOT Copilot-invoked. They run on the Ubuntu runner's pre-installed Python 3 during workflow execution. They exist because the data transformation is **deterministic** (parse JSON, insert a row in a Markdown table, write a Markdown stub from a template) — work that doesn't need an LLM and shouldn't pay LLM-token costs. ### `update_compat_matrix.py` - **Inputs (via env vars)**: `OLD_VERSION`, `NEW_VERSION` - **Reads**: `docs/compatibility-matrix.md` - **Writes**: same file, with a new row inserted at the top of the data section - **Idempotency**: if a row for `NEW_VERSION` already exists, the script no-ops (`exit 0`). - **Position-agnostic**: inserts before the FIRST `**X.Y.Z**` row it finds, so the matrix stays ordered newest-first regardless of which version was previously latest. ### `gen_guide_section.py` - **Inputs (via env vars)**: `OLD_VERSION`, `NEW_VERSION` - **Reads**: `diff-core.txt` (output of `dotnet-inspect diff`), `release-notes.txt` (output of `gh release view`) - **Writes**: - `guides/maf--migration-guide.md` — per-version delta file - `guides/maf-current-migration-guide.md` — auto-regenerated cumulative concatenation of all per-version files (TOC at top, ascending version order) - **Idempotency on the per-version file**: re-runs preserve everything under the `## Human additions` heading; only the `AUTO-GENERATED START / END` block is overwritten. - **Banner**: every auto-generated per-version file now opens with a callout that says it's a **delta only** and points readers at the chain or at the cumulative file. This is what makes the per-version files honest about their scope. --- ## Files modified by a successful run After Stage 1, before Stage 3: | File | Modification | |---|---| | `.maf-version` | New version | | `docs/compatibility-matrix.md` | New row at top of data table (`unknown` cells for some columns) | | `guides/maf-X.Y.Z-migration-guide.md` | New per-version file with banner + AUTO-GENERATED stub + Human-additions marker | | `guides/maf-current-migration-guide.md` | Regenerated cumulative file | | `.github/skills/maf-obsolete-api-registry/registry.yaml` | New entries appended (with TODO placeholders for `fix_description`, `example_before`, `example_after`, `guide_section`) | After Stage 3 (Copilot's PR): | File | Modification | |---|---| | `registry.yaml` | TODO placeholders filled in for that version's entries | | `compatibility-matrix.md` | `unknown` cells filled OR explicit `unknown + TODO comment` if the release notes don't reveal them | | Per-version guide | `Breaking Changes`, `New Patterns`, `Obsolete APIs`, `Known Misalignments` sections filled; terminal-escape artefacts cleaned | --- ## Human review checklist (when Copilot's PR opens) - [ ] **Registry entries**: spot-check 1-2 of Copilot's `example_before`/`example_after` snippets against the real MAF surface. Compile if you can. - [ ] **Compat matrix**: if cells are still `unknown`, you'll need to look up versions from the MAF csproj on NuGet — Copilot left them when release notes were ambiguous. - [ ] **Migration guide "Breaking Changes"**: confirm one bullet per registry entry; no breaking change in the diff is missed. - [ ] **Migration guide "New Patterns"**: confirm each PR # mentioned corresponds to a real MAF PR (cross-reference at `https://github.com/microsoft/agent-framework/pull/`). - [ ] **`guide_section`**: for entries on a new MAF surface, value should be `N/A` (not `TBD`, not `TODO`). If Copilot used `TBD`, fix to `N/A`. - [ ] **`## Human additions` heading**: should be untouched. --- ## Limitations the pipeline can't solve - **Obsolete-by-attribute APIs not in the diff**: `dotnet-inspect` v0.7.8 surfaces `[Obsolete]` at the type/member level. But the COMPILER is still ground-truth for transitive obsoletions, overload-resolution surprises, and project-local `[Obsolete]` decorations. Run `MafRunCs0618Hunt` against a real project pinned to the new version after the watcher commits to catch these. - **Behavioural changes the diff can't see**: a method whose signature is identical but whose runtime semantics changed (e.g. "now returns ValueTask instead of starving silently") is invisible to `dotnet-inspect`. Release-notes interpretation by Copilot in Stage 3 catches some of these but not all. - **Whether the new version is actually *good***: the pipeline tells you what changed, not whether you should upgrade. That call is human. --- ## Related artefacts - **Workflows**: `.github/workflows/maf-release-watcher.yml`, `.github/workflows/maf-ai-fill-todos.yml` - **Python helpers**: `.github/scripts/gen_guide_section.py`, `.github/scripts/update_compat_matrix.py` - **CLI used by Stage 1**: `maf-doctor registry-extract` (from the published NuGet tool) - **MCP tool for multi-version paths**: `MafMigrationPath(currentVer, targetVer)` — returns the ordered chain of per-version guide sections to read - **Resource**: `maf://compatibility` — exposes the matrix to the LLM at chat time ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [joslat](https://github.com/joslat) - **Source:** [joslat/maf-doctor](https://github.com/joslat/maf-doctor) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-joslat-maf-doctor-maf-release-watcher - Seller: https://agentstack.voostack.com/s/joslat - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.