Microsoft Aspire team ships docs 45 hours after code using AI agents

A 10-person team solved the documentation lag problem

The Microsoft Aspire team—a group of 10 engineers building developer tools for distributed applications—merged 82 feature documentation pull requests at a median of 44.8 hours after the corresponding product code shipped, according to internal metrics covering releases 13.3 and 13.4. Every documentation draft was reviewed by the engineer who built the feature. The team added no writers and changed no processes. They automated the reverse-engineering work that typically creates weeks of delay between code and documentation.

The constraint was architectural: Aspire's product code lives in microsoft/aspire while documentation lives in microsoft/aspire.dev—separate repositories with different deployment pipelines and review chains. Cross-repository automation typically requires broad repository tokens that security teams rightly restrict. The Aspire team needed a way to generate documentation in one repository based on changes merged in another without compromising their security posture.

How GitHub Agentic Workflows bridges repositories safely

GitHub Agentic Workflows, a project from GitHub Next, separates agent reasoning from write operations. Teams author workflows as markdown files with YAML frontmatter and natural-language prompts. At runtime, an agent processes the prompt with read access to specified repositories but cannot write directly to GitHub. Instead, it emits structured intent—JSON describing pull requests, issues, and comments it wants to create. A separate handler with narrowly scoped permissions materializes that intent through a per-workflow GitHub App.

The Aspire team's pr-docs-check workflow runs when pull requests merge to main or release branches. A bash script first determines the target documentation branch by checking the pull request milestone, linked issues, or base reference—milestones in the product repository map directly to release branches in the documentation repository. The agent then reads the diff, scans linked issues, and decides whether documentation is needed. If yes, it drafts content following the team's style guidelines and emits a pull request creation request.

The safe-outputs handler enforces strict constraints defined in frontmatter: pull requests must target main or release/* branches, carry a [docs] prefix and docs-from-code label, remain in draft state, and land in microsoft/aspire.dev. Protected files including AGENTS.md and dependency manifests are off-limits. The GitHub App token reaches exactly two repositories and nothing else in the organization. If pull request creation fails for any reason, the system falls back to filing an issue so no work is lost.

The numbers from production use

Over a 30-day window spanning May and June 2026, the workflow ran 396 times—once for every merged pull request in microsoft/aspire. It created 82 documentation pull requests. All 82 merged with zero closed without merging and zero still open. The workflow correctly identified that 314 pull requests—internal refactors, test fixes, dependency updates—required no user-facing documentation.

Thirty-eight percent of documentation pull requests merged within 24 hours; 96 percent merged within seven days. The median time from code merge to documentation merge was 44.8 hours. The engineer who approved the feature code became the reviewer for the documentation draft, eliminating the weeks-long cycle of a documentation writer discovering a shipped feature, reverse-engineering what changed, and hunting down context from an engineer who had moved on.

Why it matters

Cross-repository automation has been a security and tooling dead end for most teams. GitHub Agentic Workflows demonstrates that AI agents can operate across repository boundaries without broad tokens or manual handoffs when write operations flow through a constrained, auditable pipeline. The Aspire team's approach shifts documentation from a trailing activity to a concurrent one—features aren't done until the docs merge—without adding staff or retraining processes. Documentation writers now focus on narrative content, sample programs, and conceptual guides rather than mechanical reference updates that fall directly out of code diffs.

These details were first reported by the Microsoft Aspire team on the GitHub blog.