[Kristen Womack (kristenwomack)]

Summary

• Replace the root symlink with a cross-platform Markdown entry point that routes agents to the guidance for their task.
• Put security and privacy guidance first, consolidate shared extension and VS Code rules, and preserve extension-local contracts and exceptions.
• Remove the redundant root Copilot and scoped Go instruction files. Add scoped frontmatter for extension and documentation instructions, and keep the extension contract review pass mandatory before general PR review.

Intentional policy change

Agents must read the full CLI handbook for core CLI and Microsoft-authored extension work, rather than for every repository task. Repository-wide requirements and applicable path-specific guidance remain explicit.

The existing instruction-update automation still references the removed files and may propose recreating them; updating the automation is outside this PR's scope.

Discovery checks

• Core CLI: Confirmed the root entry point links to the CLI handbook and Go guidance.
• Extension review: Confirmed the root and shared extension guidance route reviewers to the mandatory contract-review skill, including for fork PRs.
• VS Code: Confirmed the root entry point leads to the VS Code guide and its authoritative local instructions.
• Documentation: Confirmed the root entry point links to documentation maintenance guidance, and checked representative core, extension, VS Code, and documentation paths against its ** scope.
• Windows: Verified a fresh git checkout-index with core.symlinks=false produces a regular Markdown root file. Git records it as mode 100644.
• Checked 40 local links and headings, the then-present frontmatter declarations, representative glob matches using Node, and the preserved review and core-dependency rules. The Go instruction file was subsequently removed in response to review. git diff --check passed.
• Ran the CI-pinned cspell version against cli/azd/extensions/AGENTS.md after adding file-scoped terminology exceptions.

Copilot desktop observation

In a fresh Copilot desktop session based on this branch, the agent-visible initial context contained unlabeled instruction blocks matching the repository pointer, root guidance, and documentation-maintenance guidance. At that revision, the client also listed Go and extension instruction files for the agent to read, but did not inject their contents in that initial context. The Go instruction file and root Copilot pointer were removed later in response to review. Reading representative core Go, extension, VS Code, and documentation files did not visibly deliver additional instruction blocks.

This observation does not establish source attribution for unlabeled blocks, hidden client state, or behavior in other clients. It also does not prove that linked local or scoped instructions load automatically; the root guide explicitly directs agents to read applicable instructions.

Closes #10801

[azure-pipelines]

Azure Pipelines:
Successfully started running 9 pipeline(s).
18 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The revised guides omit CI safeguard and reviewer-skill routing, conflict on extension-only variable documentation, and apply Go 1.26 guidance to a Go 1.22 module.

4 open issues

• Add a root-guide route for CI and pipeline safeguards · New
• Preserve the code-review skill requirement in the root guide · New
• Distinguish core variables from extension-only variables · New
• Scope Go guidance to each module's supported toolchain · New

What changed in this PR

This PR improves how coding agents discover azd guidance across platforms and work areas, addressing #10801.

Changes:

• Replace the root symlink with a Markdown entry point, requiring full CLI-handbook reading only for core CLI and Microsoft-authored extension work.
• Consolidate shared extension and VS Code rules while retaining local contracts and exceptions.
• Add scoped instruction frontmatter and retain mandatory extension contract review.

Extension user-contract audit: blocked by unavailable review history (8 extension files inspected; 0 new contract comments; existing-thread count unavailable).

File	Description
ext/​vscode/​AGENTS.md	Route agents to authoritative VS Code instructions.
ext/​vscode/​.github/​copilot-instructions.md	Consolidate VS Code conventions and validation checks.
cli/​azd/​extensions/​azure.ai.toolboxes/​AGENTS.md	Link shared guidance; remove duplicated dependency and Go rules.
cli/​azd/​extensions/​azure.ai.skills/​AGENTS.md	Link shared guidance and core-dependency policy.
cli/​azd/​extensions/​azure.ai.routines/​AGENTS.md	Link shared guidance; remove duplicated Go and tenant rules.
cli/​azd/​extensions/​azure.ai.projects/​AGENTS.md	Link shared guidance while retaining project-specific rules.
cli/​azd/​extensions/​azure.ai.inspector/​AGENTS.md	Link shared guidance and core-dependency policy.
cli/​azd/​extensions/​azure.ai.connections/​AGENTS.md	Replace duplicated dependency and Go guidance with shared links.
cli/​azd/​extensions/​azure.ai.agents/​AGENTS.md	Link shared guidance while retaining agent-specific requirements.
cli/​azd/​extensions/​AGENTS.md	Centralize extension security, review, dependency, and validation rules.
cli/​azd/​AGENTS.md	Route mandatory extension review to the shared guide.
.github/​instructions/​go.instructions.md	Correct frontmatter and link authoritative Go conventions.
.github/​instructions/​extensions.instructions.md	Correct frontmatter and route to shared and local guides.
.github/​instructions/​documentation.instructions.md	Apply documentation-maintenance guidance repository-wide.
.github/​copilot-instructions.md	Replace blanket handbook loading with a root-guide pointer.

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Deleting go.instructions.md drops core CLI review rules for input precedence, ignored flags, and location-bound model/quota data without preserving them in the handbook.

2 open issues

• Preserve core CLI review rules in the handbook · New
• Distinguish core variables from extension-only variables

3 resolved since last review

• Scope Go guidance to each module's supported toolchain
• Preserve the code-review skill requirement in the root guide
• Add a root-guide route for CI and pipeline safeguards

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

The consolidation removes core CLI review rules for input precedence, ignored flags, and location-scoped model/quota data without preserving them elsewhere or documenting an intentional policy change.

No open issues 🎉

2 resolved since last review

• Preserve core CLI review rules in the handbook
• Distinguish core variables from extension-only variables

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Human assessment is needed for an unpublished concern that the guidance may imply URL userinfo is cleared, although neither referenced helper does so.

No open issues 🎉

_{Review effort: Max}

[Richard Park (richardpark-msft)]

Seems fine enough, but I realize we don't have much in the way of testing around this.

[azure-sdk-automation]

VSCode Extension Installation Instructions

1. Download the extension at https://azuresdkartifacts.z5.web.core.windows.net/azd/vscode/pr/10818/azure-dev-0.11.0-alpha.1.vsix
2. Extract the extension from the compressed file
3. In vscode
   a. Open "Extensions" (Ctrl+Shift+X)
   b. Click the ...\ menu at top of Extensions sidebar
   c. Click "Install from VSIX"
   d. Select location of downloaded file

[azure-sdk-automation]

azure.ai.agents PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-agents.zip"

• Version: 1.0.0-beta.23.pr.10818.7033882
• Merge commit: 228c017

[azure-sdk-automation]

azure.ai.inspector PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-inspector.zip"

• Version: 1.0.0-beta.9.pr.10818.7033884
• Merge commit: 228c017

[azure-sdk-automation]

azure.ai.routines PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-routines.zip"

• Version: 1.0.0-beta.11.pr.10818.7033887
• Merge commit: 228c017

[azure-sdk-automation]

azure.ai.toolboxes PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-toolboxes.zip"

• Version: 1.0.0-beta.13.pr.10818.7033712
• Merge commit: a11415b

[azure-sdk-automation]

azure.ai.skills PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-skills.zip"

• Version: 1.0.0-beta.10.pr.10818.7033888
• Merge commit: 228c017

[azure-sdk-automation]

azure.ai.connections PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-connections.zip"

• Version: 1.0.0-beta.11.pr.10818.7033883
• Merge commit: 228c017

[azure-sdk-automation]

azure.ai.projects PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10818/azure-ai-projects.zip"

• Version: 1.0.0-beta.16.pr.10818.7033885
• Merge commit: 228c017

[JeffreyCA]

Thank you, looks great! Just a couple of comments

[JeffreyCA]

This should be the general guidance for all extensions not just these specific ones

[JeffreyCA]

This kind of relates to my other comment, we should also encourage the use of stacked PRs for larger changes that build on top of each other, especially if touching both azd core and extension code. Makes reviewing much easier

The one limitation we may want to call out is that they require PRs to be opened from Azure/azure-dev - PRs from fork repos are not supported.