Repo AI-layout onboarding

How to bring a repo onto the canonical multi-model AI layout — AGENTS.md + the CLAUDE.md shim + the .ai/ workspace + per-tool configs — defined by the agents standard and the AI workspace standard.

This is governance-driven and done one repo at a time: the MCP tells you a repo has drifted, a script remediates that one repo, and the MCP confirms it. There is no bulk conversion wave.

---

The loop

check_drift(repo)  →  DRIFT  →  Invoke-RepoAiLayout -DryRun  →  Invoke-RepoAiLayout  →  check_drift(repo)  →  PASS  →  commit

1. Detect drift

Call the HCS Governance MCP check_drift tool for the repo (by registry name or local path):

check_drift(repo="azurelocal-ranger")

It returns PASS or DRIFT with a per-finding remediation hint. A repo drifts when AGENTS.md is missing or lacks the MCP-first bootstrap block, CLAUDE.md is not a thin @AGENTS.md shim, any of the eight .ai/ files are missing, .claude/ exists without a settings.json, or an obvious secret pattern is present. If it already returns PASS, there is nothing to do.

2. Preview the change (dry run)

pwsh -File scripts/onboarding/Invoke-RepoAiLayout.ps1 -RepoName azurelocal-ranger -DryRun

-DryRun writes nothing. It prints:

• the resolved local_path, standards_scope, and type from master-registry.db
• what it extracted from the existing CLAUDE.md (repo description, ADO project, area path, Key Vault) and whether each field was extracted or fell back to a default
• a file plan of every CREATE / MODIFY / SKIP

Review the plan. Pay attention to any field marked default — see When extraction falls back below.

3. Apply

pwsh -File scripts/onboarding/Invoke-RepoAiLayout.ps1 -RepoName azurelocal-ranger

The script:

• renders AGENTS.md from templates/AGENTS.md.template with the extracted content and the repo's real standards_scope (a scope note is added for non-hcs scopes)
• rewrites CLAUDE.md as the thin @AGENTS.md shim
• scaffolds any missing .ai/ file from templates/ai-workspace/ (it never overwrites an existing .ai/ file — safe to re-run)
• writes .codex/config.toml and .github/copilot-instructions.md, and .mcp.json only if missing (an existing .mcp.json may already declare repo-specific MCP servers)
• ensures .gitignore ignores .claude/settings.local.json

It makes no API calls and does not commit — committing is your explicit next step.

4. Re-check and commit

check_drift(repo="azurelocal-ranger")

Confirm it now returns PASS, then commit the change yourself:

git add AGENTS.md CLAUDE.md .ai/ .codex/ .github/copilot-instructions.md .mcp.json .gitignore
git commit -m "feat(agents): convert to canonical multi-model AI layout AB#<id>"

Update the conversion-status row for the repo in tracker.md.

---

When extraction falls back

The script pulls the repo identity paragraph, ADO project, area path, and Key Vault out of the existing CLAUDE.md by plain text matching — never an LLM call. That is reliable for the structured fields (they live in known table rows or **bold:** lines), but the identity paragraph varies a lot repo to repo. When the ## What this repo is section is empty, or only a banner image, the script falls back to a generic type-based sentence and marks the description default (type-based) in the plan.

When you see a default field, fix it after applying: open the generated AGENTS.md and write a real one-paragraph repo identity (and correct the key-facts table if the ADO project / Key Vault defaulted). This is expected for repos whose old CLAUDE.md had a thin or image-only description.

---

Notes

• The pilot for this layout is azurelocal-ranger, chosen as the reference-implementation docs repo rather than one of the 7 existing pilot: true repos (those are pilots for the separate IaC/web/docs validation profiles, not for this layout conversion). The script works on any registry repo by name.
• standards_scope comes from master-registry.db and defaults to hcs. Scoped repos (tierpoint-prodtech, azurelocal) get their standards from the MCP only — the public site serves the hcs base scope.
• Re-running the script on an already-converted repo is safe: .ai/ files and an existing .mcp.json are skipped; AGENTS.md, CLAUDE.md, and the tool-pointer files are regenerated deterministically from the templates.

---

Quick reference

File	Template source	Overwrite behaviour
AGENTS.md	templates/AGENTS.md.template	Regenerated
CLAUDE.md	templates/CLAUDE.md.template (or repo-scaffold/ if none existed)	Regenerated as shim
.ai/** (8 files)	templates/ai-workspace/	Created only if missing
.codex/config.toml	templates/codex/config.toml.template	Regenerated
.github/copilot-instructions.md	templates/copilot-instructions.md.template	Regenerated
.mcp.json	templates/mcp.json.template	Created only if missing
.gitignore	—	Appended only if entry absent