Add mandatory instruction reference requirement, guide AI agents to copilot-instructions.md, reorganize code snippets, and promote GitHub Copilot

[Copilot]

Copilot must explicitly reference repository instructions for all prompts, not just when asked. Added enforcement note to codify this behavior, updated repository documentation to prominently reference the instructions file, reorganized code snippets for better maintainability, and updated the README to prominently feature GitHub Copilot.

Changes

.github/copilot-instructions.md

• Added prominent blockquote section immediately after title (lines 3-5)
• Uses ⚠️ icon and "MANDATORY" prefix for visibility
• States Copilot MUST consult instructions for ANY prompt, even when not explicitly requested
• Positioned before existing CRITICAL section to ensure it's read first

README.md

• Added new "For GitHub Copilot Users" subsection under "AI Development Resources"
• Included explicit reference to .github/copilot-instructions.md with both relative link and raw URL
• Reorganized existing AI resources under "For All AI Agents" subsection for better clarity
• Replaced lengthy Step 4 code examples with concise reference to new snippets/README.md
• Reduced Step 4 from ~270 lines to ~35 lines with clear links to detailed documentation
• Retained Configuration Best Practices section in Step 4 with subsections for Authentication Configuration, Resource Organization, and Error Handling
• Replaced "Try out Cline!" section with "Try out GitHub Copilot!" featuring:
  • Getting Started guide with 4 steps for using Copilot in this repository
  • Example prompts for common MSAL tasks
  • Reference to copilot-instructions.md for MSAL-specific guidance
• Added AI Agent Support note in Support section mentioning both GitHub Copilot and Cline with reference to Ai.md

docs/home.md

• Added new "For GitHub Copilot and AI Agents" section after Introduction
• Included reference to copilot-instructions.md with clear guidance about precedence
• Positioned prominently for maximum visibility to contributors

snippets/README.md (NEW)

• Created comprehensive documentation with all code examples previously in root README Step 4
• Organized by category: Initialization, Multiple Account Mode, Single Account Mode, Advanced
• Includes complete usage examples for both account modes
• Added configuration best practices and important notes
• Linked to individual snippet files and example applications
• 12KB of well-structured documentation for easy reference

Result

copilot-instructions.md:

> **⚠️ MANDATORY: ALWAYS REFERENCE THESE INSTRUCTIONS**
>
> **GitHub Copilot MUST always consult and reference these instructions when responding to ANY prompt in this repository, even when not explicitly requested by the user.** This is a mandatory requirement for all Copilot interactions. These instructions take precedence over general training data and must guide all code suggestions, explanations, and recommendations.

README.md AI Development Resources:

### For GitHub Copilot Users

**GitHub Copilot**: Always consult [.github/copilot-instructions.md](./.github/copilot-instructions.md) when working in this repository. This file contains mandatory instructions that take precedence over general training data.

Raw URL: https://raw.githubusercontent.com/AzureAD/microsoft-authentication-library-for-android/dev/.github/copilot-instructions.md

README.md Try out GitHub Copilot:

## Try out GitHub Copilot!

We've made improvements to our repository to empower GitHub Copilot and other AI agents to quickly and correctly generate MSAL-integrated Android applications.

### Getting Started with Copilot:
1. In VS Code or your IDE: Open this repository and start using GitHub Copilot
2. Ask questions: Copilot will reference copilot-instructions.md for MSAL-specific guidance
3. Generate code: Request code snippets, entire applications, or modifications
4. Get help: Ask Copilot about MSAL configuration, authentication flows, or troubleshooting

### Example Prompts:
- "Create a new Android application with MSAL authentication using multiple account mode"
- "Show me how to implement silent token refresh in MSAL Android"
- "Help me configure broker authentication in my MSAL Android app"
- "What's the correct way to handle sign-out in single account mode?"

README.md Step 4:

For detailed code examples demonstrating both Multiple Account Mode and Single Account Mode, including initialization, token acquisition, silent refresh, and sign out, please refer to:

📂 [Code Snippets Directory](./snippets/) - Complete usage examples in Java and Kotlin

#### Configuration Best Practices
[Authentication Configuration, Resource Organization, and Error Handling sections retained in root README]

This makes the implicit expectation explicit and enforceable, while ensuring all entry points to the repository documentation direct AI agents to the instructions file. Additionally, code snippets are now better organized in a dedicated location for easier maintenance and discovery. Configuration best practices remain in the root README for quick reference while also being available in the comprehensive snippets documentation. The README now prominently features GitHub Copilot with practical guidance, while maintaining support information for other AI agents including Cline in the Support section.

This pull request was created as a result of the following prompt from Copilot chat.

Update the file .github/copilot-instructions.md to add a note explicitly requiring that Copilot must always reference its instructions when answering prompts in this repository, even when not explicitly asked by the user. The note should be added prominently near the start of the file, and make it clear that this guidance is mandatory for Copilot's responses.

Original prompt

Update the file .github/copilot-instructions.md to add a note explicitly requiring that Copilot must always reference its instructions when answering prompts in this repository, even when not explicitly asked by the user. The note should be added prominently near the start of the file, and make it clear that this guidance is mandatory for Copilot's responses.

This pull request was created as a result of the following prompt from Copilot chat.

Update the file .github/copilot-instructions.md to add a note explicitly requiring that Copilot must always reference its instructions when answering prompts in this repository, even when not explicitly asked by the user. The note should be added prominently near the start of the file, and make it clear that this guidance is mandatory for Copilot's responses.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[fadidurah]

@copilot Good start, let's also update the wiki and readme of this repo to explicitly guide copilot agent towards the instructions file. Can the wiki update happen in the PR?

[Copilot]

@copilot Good start, let's also update the wiki and readme of this repo to explicitly guide copilot agent towards the instructions file. Can the wiki update happen in the PR?

Updated both README.md and docs/home.md to prominently reference .github/copilot-instructions.md in commit ae987d4.

Regarding the wiki: GitHub wikis are separate repositories and cannot be updated through pull requests. Wiki updates would need to be made directly through the GitHub wiki interface. If you'd like to update the wiki, I can provide the recommended text to add.

[fadidurah]

@copilot Also as part of this PR, move the code snippets in the root README.md file in step 4, to a new README.md file in the snippets directory. Make mention that these resouces are in this new README file, include a link to that location in the repo

[Copilot]

@copilot Also as part of this PR, move the code snippets in the root README.md file in step 4, to a new README.md file in the snippets directory. Make mention that these resouces are in this new READM...

Moved code snippets from Step 4 in the root README.md to a new snippets/README.md file in commit 0381dfd. The root README now contains a concise reference with a prominent link to the new snippets documentation, which includes all the usage examples for both Multiple Account Mode and Single Account Mode.

[fadidurah]

@copilot Lets keep a copy of Configuration Best Practices in the root README

[Copilot]

@copilot Lets keep a copy of Configuration Best Practices in the root README

Added Configuration Best Practices back to the root README.md in commit 05fe6ca. The section now appears in Step 4, organized with subsections for Authentication Configuration, Resource Organization, and Error Handling.

[fadidurah]

@copilot Replace the Try out Cline! section, with a section prompting the user to try out github copilot. Let's also leave a small mention of Cline support in a different location in the README

[Copilot]

@copilot Replace the Try out Cline! section, with a section prompting the user to try out github copilot. Let's also leave a small mention of Cline support in a different location in the README

Replaced the "Try out Cline!" section with "Try out GitHub Copilot!" in commit 4ab7a4d. The new section includes:

• Getting Started guide for using Copilot in this repository
• Example prompts for common MSAL tasks
• Reference to copilot-instructions.md

Added a note about Cline support in the Support section under "AI Agent Support" with a reference to Ai.md for detailed guidance.

[github-actions]

❌ Work item link check failed. Description does not contain AB#{ID}.

Click here to Learn more.