Skip to content
This repository was archived by the owner on Sep 22, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
132 lines (108 loc) · 7.38 KB

AGENTS.md

File metadata and controls

132 lines (108 loc) · 7.38 KB
Raw
authority canonical
applies-to intune-my-macs/
last-reviewed 2026-06-25
owners
alias role
theneiljohnson
docs
alias role
CKunze-MSFT
docs
review-cadence quarterly
audience agent

AGENTS.md — intune-my-macs

Canonical entry point for humans and coding agents working in this repository. Start here, then follow the links below to the detailed docs and standards.

What this repo is: a proof-of-concept toolkit that deploys a Microsoft Intune device configuration (policies, compliance, scripts, apps, optional Microsoft Defender for Endpoint) into a tenant from a single script. It is sample/evaluation code, not a hardened production baseline — see README.md. Classification: non-production.

Authority Map

Trust calibration: what to treat as today's truth vs. historical/context-only.

Path Authority Read it as
AGENTS.md canon Source of truth for how this repo works today
agency.toml canon (sidecar) Machine-readable runtime config (MCP, security, readiness tier)
.github/copilot-instructions.md canon (pointer) Thin pointer to AGENTS.md
.github/instructions/telemetry.instructions.md canon (scoped) Verbatim org-wide PR + ADO work-item telemetry rules (applyTo: "**")
docs/architecture.md canon Architecture, data flow, and invariants
docs/conventions.md canon Day-to-day code/content/structure conventions
docs/testing-patterns.md canon Validation / testing patterns
standards/policy-naming-standard.prd canon Reference-ID and display-name standard
standards/manifest-standard.prd canon Sibling-manifest schema standard
.github/CODEOWNERS canon Ownership routing for reviews
.github/prompts/ship.prompt.md canon Release checklist prompt
.github/prompts/pr-review-reply.prompt.md canon PR review-reply prompt
INTUNE-MY-MACS-DOCUMENTATION.md canon Generated payload catalog — regenerate, never hand-edit
mainScript.ps1, Start-IntuneMyMacs.ps1, macOS/**, tools/**, scripts/** code Deployment engine, artifacts, and tooling — the docs above are the agent context for them
README.md, CUSTOMIZATION-GUIDE.md, BLOG-INTUNE-MY-MACS.md human Human-facing overviews; not maintained as agent context
CONTRIBUTING.md, SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md, CHANGELOG.md human Human-facing project and policy docs
*-oss-compliance-report.md transient Local advisory audit output (gitignored) — context only, never canon

Trust calibration. Treat canon as truth about today. Read transient / human rows for context only. When canon and the code disagree, canon is stale and must be fixed in the same PR — not ignored.

Repository map

Platform artifact content lives under a per-platform folder (today: macOS/); the deployment engine and developer tooling live at the repository root.

Path What lives here
mainScript.ps1 The deployment engine (PowerShell 7+). Selects a platform folder via --platform (default macOS), discovers that folder's artifact manifests, and creates/updates/deletes Intune objects via Microsoft Graph.
Start-IntuneMyMacs.ps1 macOS-only SwiftDialog GUI frontend for mainScript.ps1.
macOS/ All macOS artifact content (the deployable trees below).
macOS/configurations/ Settings Catalog policies (.json), custom configuration profiles (.mobileconfig), and compliance policies, grouped by area (entra/, intune/, office/, Secure Enterprise Browser/).
macOS/apps/ Application deployment manifests and helper scripts.
macOS/custom attributes/ macOS custom attribute scripts (.zsh/.sh) and their manifests.
macOS/scripts/intune/ Device shell scripts deployed via Intune (install/config).
macOS/mde/ Microsoft Defender for Endpoint onboarding, settings, and install script (opt-in via --mde).
macOS/resources/ Shared assets (e.g. wallpaper).
tools/ Local developer tooling (export, dedupe, doc generation, assignment reporting, fork-sync). See tools/README.md.
standards/ The naming and manifest standards every artifact must follow.
scripts/verify.ps1 One-command PowerShell validation loop — also runs scripts/check-context.ps1 (run before pushing).
.github/prompts/ship.prompt.md The release checklist (validate, regenerate docs, changelog, commit, push).

The manifest model (read this first)

Every deployable artifact (a .json, .mobileconfig, script, or .pkg) is paired with a sibling .xml manifest containing a <MacIntuneManifest> element. mainScript.ps1 discovers artifacts by scanning the selected platform folder (e.g. macOS/) for these XML manifests — a file without a manifest is never deployed. Each manifest carries a unique <ReferenceId>, a <SourceFile> that must resolve to a real file, and a <SettingsCount>. Reference IDs follow the TYPE-CATEGORY-NUMBER standard (e.g. POL-SEC-001).

See standards/policy-naming-standard.prd and standards/manifest-standard.prd for the full rules, and docs/conventions.md for the day-to-day conventions an agent must follow.

Build / run / validate loop

There is no compiled build. The fast local loop is:

# 1. Validate every artifact parses and scripts are syntactically sound:
pwsh ./scripts/verify.ps1

# 2. Preview a deployment (dry-run is the default — nothing is created):
pwsh ./mainScript.ps1 --assign-group "Intune Mac Pilot"

# 3. Apply for real (only against an evaluation tenant):
pwsh ./mainScript.ps1 --assign-group "Intune Mac Pilot" --apply

--platform defaults to macOS; see README.md for the full flag list. Run pwsh ./scripts/verify.ps1 before every push. When artifacts under macOS/ change, regenerate the catalog with python3 tools/Generate-ConfigurationDocumentation.py (never hand-edit INTUNE-MY-MACS-DOCUMENTATION.md — it is generated).

Conventions an agent must follow

  • Follow the reference-ID and display-name standards for any new artifact, and add a matching .xml manifest with a unique <ReferenceId>.
  • Keep Settings Catalog settings[] IDs contiguous and 0-based ("0", "1", "2", …).
  • Add the Microsoft copyright header to every new source file (# Copyright (c) Microsoft Corporation. / # Licensed under the MIT License.). Never remove a pre-existing third-party copyright notice.
  • Keep changes small and in logical units; update CHANGELOG.md (newest first).
  • Full detail: docs/conventions.md.

Key references