docs: fix documentation drift — repos: syntax, AGENTS.md architecture

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Front matter syntax	prompts/create-ado-agentic-workflow.md Step 5 and Multi-Repo pattern use deprecated repositories: + checkout: syntax instead of repos:	prompts/create-ado-agentic-workflow.md
Front matter syntax	README front matter fields table lists repositories and checkout — both are #[serde(skip)] in FrontMatter struct (not valid user YAML keys) — instead of the actual repos: field	README.md
Architecture tree	0001_repos_unified.rs missing from the codemods directory listing	AGENTS.md

Details

prompts/create-ado-agentic-workflow.md — deprecated repos syntax (high priority)

Step 5 showed the legacy repositories: / checkout: format:

repositories:
  - repository: my-other-repo
    type: git
    name: my-org/my-other-repo
checkout:
  - my-other-repo

This format is auto-converted by the 0001_repos_unified codemod on ado-aw compile, but since this prompt directly drives agent-generated pipelines, it should demonstrate the canonical repos: syntax. Same issue appeared in the Multi-Repo Agent common pattern.

README.md — wrong field names in front matter table

The FrontMatter struct marks repositories and checkout as #[serde(skip)] — they are populated programmatically by lower_repos() after codemod conversion and cannot be set directly in YAML. The correct user-facing field is repos:, which was not listed in the table.

AGENTS.md — missing codemod file

The architecture tree listed mod.rs and helpers.rs under codemods/ but omitted 0001_repos_unified.rs.

Applied Fixes

• prompts/create-ado-agentic-workflow.md Step 5: Replace repositories: + checkout: example with compact repos: syntax; update bullet-point explanations
• prompts/create-ado-agentic-workflow.md Multi-Repo Agent pattern: Replace with repos: shorthand
• prompts/create-ado-agentic-workflow.md Step 4 workspace note: Replace checkout: reference with repos:
• README.md front matter table: Replace repositories and checkout rows with single repos row
• AGENTS.md architecture tree: Add 0001_repos_unified.rs to codemods listing

---

This pull request was created by the automated documentation freshness check.

---

Warning

Protected Files

This was originally intended as a pull request, but the patch modifies protected files. These files may affect project dependencies, CI/CD pipelines, or agent behaviour. Please review the changes carefully before creating the pull request.

Click here to create the pull request once you have reviewed the changes

Protected files

• AGENTS.md

To route changes like this to a review issue instead of blocking, configure protected-files: fallback-to-issue in your workflow configuration.

Generated by Documentation Freshness Check · ● 2.6M · ◷