chore: Add Agentic AI development assets for GitHub Copilot

[PlagueHO]

Summary

Add Agentic AI development assets so that GitHub Copilot (agent mode) and other AI coding agents can build, test, and contribute to this repository correctly — following DSC Community conventions and ComputerManagementDsc-specific patterns.

The reference implementation is SqlServerDsc, which has a mature set of GitHub Copilot instruction files. Most files can be copied from there and adapted by removing SQL Server-specific content and substituting ComputerManagementDsc-specific details.

---

Files to create

1. AGENTS.md (repository root)

Top-level guidance for AI agents. Must cover:

• Repository overview — purpose of the module, supported Windows versions, DSC engine versions
• Build & test workflow — how to set up the environment, build, and run tests (see build commands below)
• Resource types present — this repository contains both MOF-based resources (source/DSCResources/) and class-based resources (source/Classes/); agents must know which pattern applies where
• MOF-based resource structure — source/DSCResources/DSC_<ResourceName>/ containing .psm1, .schema.mof, and localization in en-US/
• Class-based resource structure — source/Classes/<DependencyGroupNumber>.<ClassName>.ps1, inheriting from ResourceBase (DscResource.Base)
• Key conventions — localized strings, DscResource.Common helpers, CHANGELOG updates
• DSC Community resources — Guidelines, Blog Posts
• Build commands:

  # One-time setup per pwsh session
  ./build.ps1 -Tasks noop
  
  # Build
  ./build.ps1 -Tasks build
  
  # Run unit tests
  Invoke-Pester -Path 'tests/Unit' -Output Detailed
  
  # Run a specific test file
  Invoke-Pester -Path 'tests/Unit/DSCResources/DSC_<ResourceName>.Tests.ps1' -Output Detailed

• Never run integration tests locally — integration tests require a full Windows environment and run only in CI

---

2. tests/AGENTS.md (tests folder)

Focused guidance for the tests/ directory. Must cover:

• Test framework — Pester 5 syntax is required; Pester 4 syntax must not be used
• Pester 4 vs Pester 5 structural differences — key syntax changes agents must know:
  • Describe/Context/It/BeforeAll/AfterAll/BeforeEach/AfterEach — PascalCase
  • No Assert-MockCalled → use Should -Invoke
  • No Should -Be $true → use Should -BeTrue
  • BeforeDiscovery for test case data instead of script-level variables
  • $PSDefaultParameterValues pattern for Mock:ModuleName, Should:ModuleName, InModuleScope:ModuleName
• Unit test location — tests/Unit/DSCResources/ for MOF resources, tests/Unit/Classes/ for class-based resources
• Integration test location — tests/Integration/ (one config file + one test file per resource)
• Required setup block — exact boilerplate for BeforeDiscovery/BeforeAll/AfterAll including DscResource.Test module bootstrap
• Running unit tests:

  # All unit tests (new pwsh session recommended after class changes)
  Invoke-Pester -Path 'tests/Unit' -Output Detailed
  
  # Single resource
  Invoke-Pester -Path 'tests/Unit/DSCResources/DSC_<ResourceName>.Tests.ps1' -Output Detailed

• Running integration tests — CI only; not to be run locally unless explicitly instructed

---

3. .github/copilot-instructions.md

Workspace-level instructions loaded automatically by GitHub Copilot. Must cover:

• Module identity — ComputerManagementDsc, DSC Community, purpose
• Always update CHANGELOG.md Unreleased section for every change
• Resource development best practices (brief; details in .github/instructions/ files)
• Both resource types — MOF-based (source/DSCResources/) and class-based (source/Classes/)
• Mandatory reading — point agents at the instruction files below
• Key external references:
  • DSC Community Guidelines: https://dsccommunity.org/guidelines/
  • DSC Community Blog: https://dsccommunity.org/blog/
  • DscResource.Common: https://github.com/dsccommunity/DscResource.Common
  • DscResource.Base: https://github.com/dsccommunity/DscResource.Base
  • DscResource.Test: https://github.com/dsccommunity/DscResource.Test

---

4. .github/instructions/*.instructions.md

Copy the following files from SqlServerDsc .github/instructions/ and adapt as described:

New file	Source file	Adaptations required
dsc-community-style-guidelines.instructions.md	dsc-community-style-guidelines.instructions.md	Update file organization paths for DSCResources layout; remove source/Public and source/Private sections (not used here); note both MOF and class resource types
dsc-community-style-guidelines-mof-resources.instructions.md	dsc-community-style-guidelines-mof-resources.instructions.md	Copy as-is — already generic DSC Community content with no SQL Server specifics
dsc-community-style-guidelines-class-resource.instructions.md	dsc-community-style-guidelines-class-resource.instructions.md	Copy as-is — already generic; verify applyTo glob matches source/Classes/**/*.ps1
dsc-community-style-guidelines-pester.instructions.md	dsc-community-style-guidelines-pester.instructions.md	Copy as-is — fully generic Pester 5 guidelines
dsc-community-style-guidelines-unit-tests.instructions.md	dsc-community-style-guidelines-unit-tests.instructions.md	Replace {MyModuleName} placeholder with ComputerManagementDsc; update applyTo path to include tests/Unit/DSCResources/ and tests/Unit/Classes/; remove SMO stub type references
dsc-community-style-guidelines-integration-tests.instructions.md	dsc-community-style-guidelines-integration-tests.instructions.md	Replace {MyModuleName} with ComputerManagementDsc; update resource location path to tests/Integration/ (flat, not Commands//Resources/ subfolders); remove SQL Server CI environment notes
dsc-community-style-guidelines-powershell.instructions.md	dsc-community-style-guidelines-powershell.instructions.md	Copy as-is — fully generic PowerShell style guidelines
dsc-community-style-guidelines-localization.instructions.md	dsc-community-style-guidelines-localization.instructions.md	Update string file paths: MOF resources use source/DSCResources/DSC_<Name>/en-US/DSC_<Name>.strings.psd1; module-level strings in source/en-US/ComputerManagementDsc.strings.psd1; update PREFIX convention examples
dsc-community-style-guidelines-changelog.instructions.md	dsc-community-style-guidelines-changelog.instructions.md	Update repo URL to dsccommunity/ComputerManagementDsc in issue reference format
dsc-community-style-guidelines-markdown.instructions.md	dsc-community-style-guidelines-markdown.instructions.md	Copy as-is — fully generic Markdown style guidelines
ComputerManagementDsc-guidelines.instructions.md	SqlServerDsc-guidelines.instructions.md	Replace with ComputerManagementDsc-specific content (see below)

ComputerManagementDsc-guidelines.instructions.md content

This is the repo-specific file replacing SqlServerDsc-guidelines.instructions.md. It should cover:

• Build & test workflow — same ./build.ps1 commands as in AGENTS.md
• Naming conventions:
  • MOF-based resources: DSC_<ResourceName> prefix on all files and functions
  • Class-based resources: PascalCase class name, file prefix <DependencyGroupNumber>.<ClassName>.ps1
• Resource type selection — new resources should prefer class-based unless there is a specific reason for MOF-based
• No SQL Server or SMO references
• applyTo: "**" (applies globally, like the SqlServerDsc equivalent)

---

Acceptance criteria

• AGENTS.md created at repository root
• tests/AGENTS.md created
• .github/copilot-instructions.md created
• All 11 .github/instructions/*.instructions.md files created
• No SQL Server–specific content remains in any file
• All {MyModuleName} or {owner}/{repo} placeholders replaced with correct values
• All applyTo globs verified against actual file paths in this repo

References

• SqlServerDsc instruction files: https://github.com/dsccommunity/SqlServerDsc/tree/main/.github/instructions
• DSC Community Guidelines: https://dsccommunity.org/guidelines/
• DSC Community Blog: https://dsccommunity.org/blog/
• GitHub Copilot customization docs: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot