Start with the root AGENTS.md for workspace setup, repository boundaries, and actionable build/test verification. The guidance below remains the source for domain architecture and coding conventions.
These instructions guide GitHub Copilot to provide suggestions and responses aligned with our Android project's conventions, architecture, and coding style, specifically addressing our multi-repository setup and language transition.
The android-complete repository contains multiple sub-repositories as separate modules:
- MSAL - Microsoft Authentication Library for client applications
- ADAL - Azure Active Directory Authentication Library (legacy)
- Broker - Brokered authentication service
- Common - Shared utilities, helpers, and IPC logic
- OneAuth - Library owned by another team (consumed by 1P apps like Teams, Outlook)
- 1ES-Pipelines - Production CI/CD pipeline YAML (releases, hotfixes, validation, publishing)
Important: When asked a question, always search across ALL repositories to provide comprehensive answers. Code may be duplicated or shared across these sub-repos.
Request Flow:
Client App (Teams/Outlook/etc.)
↓
MSAL or OneAuth (entry point)
↓
Common (IPC layer - sends request to Broker)
↓
Broker (processes authentication request)
↓
eSTS (Microsoft token service)
↓
Broker (receives token response)
↓
Common (IPC layer - returns response)
↓
MSAL or OneAuth
↓
Client App
Key Flow Details:
- MSAL/OneAuth → Common → Broker → eSTS → Broker → Common → MSAL/OneAuth
- Entry Points: Requests like
AcquireTokenorAcquireTokenSilenttypically start from MSAL or OneAuth - OneAuth Specifics: OneAuth is consumed by 1P Microsoft apps (Teams, Outlook, etc.). We don't own this code. OneAuth flows start by calling methods from the
BrokerMsalControllerclass - Common Module: Contains all IPC (Inter-Process Communication) logic. MSAL/OneAuth use Common layer to send requests to Broker over IPC
- Broker Module: Handles the actual authentication logic, communicates with eSTS, and returns tokens
The android-dri-search MCP server provides tools for querying past incidents, TSGs, and DRI knowledge:
| Tool | Purpose |
|---|---|
mcp_android-dri-s_get_incident |
Fetch a specific IcM incident by ID |
mcp_android-dri-s_batch_search |
Run multiple ICM and/or TSG searches in parallel |
mcp_android-dri-s_search_tsgs |
Search troubleshooting guides (single query) |
The server is configured in .vscode/mcp.json as android-dri-search. Authentication is automatic via Entra ID OAuth — you must be a member of the Android Auth Client SDK security group. See android_dri_mcp_server/deployment-and-connection-guide.md for details.
For incident investigations: Use the
incident-investigatorskill (located at.github/skills/incident-investigator/SKILL.md) which provides a comprehensive workflow for IcM/customer-reported issues.
- Primary Language for New Code: All new code and new files must be written in Kotlin.
- Existing Language: Recognize that existing files predominantly use Java. When interacting with or modifying existing Java files, maintain the Java style.
- Asynchronous Operations: Use Kotlin Coroutines for all asynchronous and background operations. Leverage structured concurrency.
- MSAL (Microsoft Authentication Library): The Microsoft Authentication (MSAL) repo contains code for MSAL library which enables developers to acquire security tokens from the Microsoft identity platform to authenticate users and access secured web APIs. This is a client-side library consumed by app developers.
- Broker: This repo is involved in brokered authentication. It uses inter-app communication. Copilot should be aware of IPC mechanisms, custom intents, and secure communication patterns relevant to a broker. Broker receives requests from MSAL/OneAuth via Common layer.
- Common: This repo holds shared utilities, helper functions, and all IPC logic. MSAL/OneAuth use this layer to communicate with Broker. Suggestions in this context should aim for reusability and generality.
- ADAL (Azure Active Directory Authentication Library): Similar to MSAL, this is an authentication library, potentially an older version or specific to certain flows. When working in ADAL context, align with its patterns.
- OneAuth: Third-party library owned by another team (not us). Consumed by 1P Microsoft apps like Teams, Outlook, etc. OneAuth flows start by calling
BrokerMsalControllerclass methods. - 1ES-Pipelines (AuthClientAndroidPipelines): This directory contains all 1ES-compliant production pipeline YAML for the Android Auth platform. It includes monthly release orchestrators, hotfix pipelines, daily validation, internal/external publishing, and reusable YAML templates. Files are organized into
production/,non-production/,scripts/, andtemplates/directories. This is NOT the same asazure-pipelines/which contains legacy/deprecated pipeline code. When modifying pipelines, always work in1ES-Pipelines/. All pipeline code is YAML. See therelease-helperskill for detailed pipeline documentation.
Important: When generating code that interacts across these repositories (e.g., calling a function from common in MSAL), ensure the generated code respects the language and API boundaries of each repository.
- Kotlin Style Guide: Follow the official Kotlin Coding Conventions and Google's Kotlin Style Guide.
- Variables: Prefer
valovervarwherever immutability is possible. - Functions: Use expression bodies for single-expression functions.
- Classes:
- Use
data classfor simple data holders.
- Use
- Visibility: Limit visibility of classes, functions, and variables to the minimum required (e.g.,
private,internal).
- Activities: Minimal logic in Activities; primarily used as entry points.
- Services/Broadcast Receivers: Use as sparingly as possible. Prefer Kotlin Coroutines and Flow for background processing and inter-component communication where modern alternatives exist.
- Unit Tests: Write comprehensive unit tests for Kotlin logic using JUnit 4/5 and Mockito/MockK.
- Instrumented Tests: Use Espresso for UI tests in Android components.
- Test Coverage: Aim for high test coverage, especially for new code.
- KDoc: Provide KDoc comments for all public Kotlin classes, functions, and properties.
- JavaDoc: When modifying existing Java code, ensure JavaDoc comments are maintained and updated.
- Conciseness: Comments should explain why something is done, not just what it does.
- TODOs: Use
TODOcomments for incomplete tasks that need to be addressed. - Copywriting: Ensure all comments are clear, concise, and free of spelling/grammar errors. Every new file generated or added should have copyright information on top of the file.
- Custom Logger: Always use the
Loggerclass for all logging purposes. Avoid usingandroid.util.Logor other direct logging frameworks. - Sensitive Data: Never log sensitive information (e.g., personal identifiable information, tokens, passwords).
- When writing new Kotlin code that needs to interact with existing Java code, use Kotlin's interoperability features effectively and safely.
- When suggesting refactors of Java code to Kotlin, prioritize small, safe conversions rather than large-scale rewrites unless explicitly instructed.
- If a prompt is too vague or lacks context, ask for clarification. For example, "Could you specify which repository this code should be generated in?" or "What specific functionality are you looking to implement?"
- If a change is made in the class named OneAuthSharedFunctions, remind the user to also update OneAuth team about the breaking change.
- Take build.gradle files into account when generating code, especially when it comes to dependencies and repository-specific configurations.
For complex investigation tasks, use these skills (read the skill file for detailed instructions):
| Skill | Location | Triggers |
|---|---|---|
| codebase-researcher | .github/skills/codebase-researcher/SKILL.md |
"where is X implemented", "how does Y work", "trace the flow of", data flow investigation |
| incident-investigator | .github/skills/incident-investigator/SKILL.md |
IcM incidents, customer-reported issues, authentication failures |
| vuln-triage-reporter | .github/skills/vuln-triage-reporter/SKILL.md |
[MSRC]/[ITD] vulnerability triage, classify/right-size severity, FireWatch findings, on-call security report |
| aria-alert-investigator | .github/skills/aria-alert-investigator/SKILL.md |
"Aria detected an incident", "investigate Aria alert", "health metric incident", telemetry threshold breach |
| kusto-analyst | .github/skills/kusto-analyst/SKILL.md |
"query Kusto", "analyze telemetry", "check android_spans", eSTS correlation, latency investigation |
| feature-planner | .github/skills/feature-planner/SKILL.md |
"plan this feature", "break this down into PBIs", "decompose this into tasks", feature decomposition |
| pbi-creator | .github/skills/pbi-creator/SKILL.md |
"create the PBIs", "create work items", "push PBIs to ADO", approved plan → ADO work items |
| design-author | .github/skills/design-author/SKILL.md |
"design this feature", "create a design spec", "write a design doc", "create an implementation plan" |
| design-reviewer | .github/skills/design-reviewer/SKILL.md |
"address review comments", "handle my review", "review comments on" |
| code-author | .github/skills/code-author/SKILL.md |
Ordinary implementation, bug fixes, PBIs, tests and PR authoring; coding standards, not an automatic dynamic-workflow launch |
| code-simplifier | .github/skills/code-simplifier/SKILL.md |
"simplify", "any opportunity to simplify", "lots of code changes", "make this simpler and smaller", shrink bloated diffs/PRs and enforce 100% flight isolation |
| code-feature | .github/skills/code-feature/SKILL.md |
Experimental opt-in only: /code-feature or an explicit request to use the coding/dynamic/coding-and-PR workflow; not normal coding prompts, questions or quoted examples |
| pbi-dispatcher | .github/skills/pbi-dispatcher/SKILL.md |
"dispatch PBIs to agent", "assign to Copilot", "send work items to coding agent" |
| test-planner | .github/skills/test-planner/SKILL.md |
"create test plan", "write test cases", "add tests to ADO", "export test plan", "E2E tests for" |
| threat-modeler | .github/skills/threat-modeler/SKILL.md |
"create a threat model", "threat model for", "threat model diagram", "STRIDE analysis for", "security diagram for" |
| s360-reporter | .github/skills/s360-reporter/SKILL.md |
"S360 report", "generate S360 report", "weekly S360", "S360 status", "what are our S360 items" |
| copilot-review-analyst | .github/skills/copilot-review-analyst/SKILL.md |
"analyze Copilot reviews", "Copilot review effectiveness", "review analysis report", "how helpful are Copilot reviews" |
| oncall-weekly-telemetry-report | .github/skills/oncall-weekly-telemetry-report/SKILL.md |
"produce the OCE report", "weekly on-call report", "WoW telemetry report", "weekly broker health report", "generate this week's on-call summary" |
This project uses Azure DevOps (IdentityDivision/Engineering). The Azure DevOps MCP Server is configured in .vscode/mcp.json for work item management. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request.
This project supports an AI-driven development workflow:
- Design: Use the
design-authorskill to create a detailed design spec in theAuthLibrariesApiReviewADO repo and open a PR for team review - Plan: After design approval, use the
feature-plannerskill to decompose the approved design into repo-targeted PBIs. Developer reviews and approves the plan. - Backlog: After plan approval, use the
pbi-creatorskill to discover ADO defaults (area path, iteration) and create work items in ADO with dependency links. - Dispatch: Use the
pbi-dispatcherskill orscripts/agent-pipeline/orchestrate.pyto assign PBIs to GitHub Copilot coding agent - Implement: Copilot coding agent creates PRs in the target repos (
msal,common,broker,adal) - Review: Use
@copilotin PR comments for automated feedback iteration
The design-docs/ folder contains the AuthLibrariesApiReview ADO repo (cloned via git droidSetup). It holds ~150+ design specs for the Android Auth platform. Designs may be outdated — always verify against the current codebase. Use them as historical context and style reference.
| Module | GitHub Repo |
|---|---|
| common / common4j | AzureAD/microsoft-authentication-library-common-for-android |
| msal | AzureAD/microsoft-authentication-library-for-android |
| broker / broker4j | security/ad-accounts-for-android (GHE) |
| adal | AzureAD/azure-activedirectory-library-for-android |
| 1ES-Pipelines | IdentityDivision/Engineering/_git/AuthClientAndroidPipelines (ADO) |
The 1ES-Pipelines/ folder contains the AuthClientAndroidPipelines ADO repo (cloned via git droidSetup). It houses all production CI/CD pipeline YAML for releases, hotfixes, validation, and publishing. Key directories: production/ (release pipelines), non-production/ (validation), templates/ (reusable YAML), scripts/ (Python/PowerShell helpers). This is separate from azure-pipelines/ which contains legacy pipeline code. The release-helper skill provides detailed documentation of all pipeline files.