feat: deploy AIM (AI Agent Instruction Modules)

[tablackburn]

Phase 0 of #120 — deploy AIM (AI Agent Instruction Modules) as the first PR of the v1.0.0 cycle.

What's included

• AGENTS.md (root) — agent-facing entry point with instruction matrix; Last sync: 2026-05-15
• aim.config.json — module configuration; external sources enabled (awesome-copilot fallback)
• instructions/ — 12 instruction modules:
  • Core: agent-workflow, shorthand, git-workflow, testing, update
  • Language/tools: powershell, markdown, readme, github-cli
  • Repository management: releases, contributing
  • Repo-specific: repository-specific.instructions.md (migrated from CLAUDE.md)
• CLAUDE.md — one-line @AGENTS.md import so Claude Code auto-loads AIM context (see "CLAUDE.md handling" below)

CLAUDE.md migration

CLAUDE.md content was migrated to instructions/repository-specific.instructions.md, keeping only repo-specific content (project layout, $PSBPreference internals, task dependency variables, naming conventions, build workflows, BuildHelpers env vars). Generic content covered by standard AIM modules (PowerShell style, git workflow, generic testing patterns) was dropped to avoid duplication.

Stale references corrected during migration:

• Version: 0.7.3 → 0.8.0
• Public function count: 9 → 12 (signing functions added in 0.8.0)

CLAUDE.md handling

The original CLAUDE.md was deleted, then re-added as a one-line file containing only @AGENTS.md. Reason: Claude Code auto-loads CLAUDE.md from the project root but does not auto-load AGENTS.md (memory docs). Using the official @-import syntax means fresh Claude Code sessions in this repo automatically pick up AIM context (AGENTS.md → instruction matrix → applicable modules) without needing a manual pointer in every prompt.

This matches the AIM source repo, which ships both AGENTS.md and CLAUDE.md.

Scope

Docs/config-only — no module code changes. Verified locally:

• git diff --stat origin/main: 16 files changed, 0 under PowerShellBuild/, requirements.psd1, CHANGELOG.md, or .github/
• ./build.ps1 -Task Test -Bootstrap passes (314 passed, 0 failed, 2 skipped — the skips are git-tagging tests that expectedly skip on feature branches)
• Module version, dependencies, and CI workflows untouched

Note on module count vs #120 checklist

#120's Phase 0 checklist lists 8 modules. This PR deploys 12 — the additional readme, contributing, update, and repository-specific modules were included per the Phase 0 deployment scope I worked from. Happy to drop any of them if the tracking issue's narrower list was intentional.

Phase 0 checklist (#120)

• Add AGENTS.md, aim.config.json, instructions/
• Migrate CLAUDE.md content → instructions/repository-specific.instructions.md
• Modules included: agent-workflow, shorthand, git-workflow, testing, powershell, markdown, releases, github-cli (plus readme, contributing, update, repository-specific — see note above)
• Fix stale version reference (CLAUDE.md said 0.7.3; actual is 0.8.0)

Commits

1. feat: deploy AIM (AI Agent Instruction Modules) — main deployment + CLAUDE.md content migration + CLAUDE.md deletion
2. docs: add CLAUDE.md as @AGENTS.md import for Claude Code auto-loading — restore CLAUDE.md as a 1-line pointer

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR deploys AIM as the agent-instruction foundation for the v1.0.0 cycle, replacing the old monolithic Claude guide with a modular instruction set and repository-specific guidance.

Changes:

• Adds AGENTS.md, aim.config.json, and AIM instruction modules.
• Migrates repo-specific Claude guidance into instructions/repository-specific.instructions.md.
• Keeps CLAUDE.md as a one-line import of AGENTS.md.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
AGENTS.md	Adds the agent-facing entry point and instruction matrix.
aim.config.json	Configures included AIM modules and external source fallback.
CLAUDE.md	Replaces the old guide with an @AGENTS.md import.
instructions/agent-workflow.instructions.md	Adds agent workflow and pre-flight guidance.
instructions/contributing.instructions.md	Adds upstream AIM contribution guidance.
instructions/git-workflow.instructions.md	Adds Git, branch, commit, and PR conventions.
instructions/github-cli.instructions.md	Adds GitHub CLI operational guidance.
instructions/markdown.instructions.md	Adds Markdown formatting standards.
instructions/powershell.instructions.md	Adds PowerShell coding standards.
instructions/readme.instructions.md	Adds README maintenance guidance.
instructions/releases.instructions.md	Adds release management guidance.
instructions/repository-specific.instructions.md	Adds PowerShellBuild-specific project, API, build, and test guidance.
instructions/shorthand.instructions.md	Adds abbreviation and shorthand naming guidance.
instructions/testing.instructions.md	Adds general testing practices.
instructions/update.instructions.md	Adds AIM update and sync procedures.

Comments suppressed due to low confidence (3)

instructions/repository-specific.instructions.md:110

• This dependency-variable table stops at $PSBPublishDependency, but PowerShellBuild/psakeFile.ps1 also defines $PSBSignModuleDependency, $PSBBuildCatalogDependency, $PSBSignCatalogDependency, and $PSBSignDependency. Include those rows so agents can correctly customize the signing task chain.

| `$PSBPublishDependency`               | `@('Test')`                      |

instructions/repository-specific.instructions.md:198

• The module-level task list omits the signing tasks currently defined in PowerShellBuild/psakeFile.ps1 (SignModule, BuildCatalog, SignCatalog, and Sign). Add them here so the repository instructions reflect the actual consumer-facing task surface.

| `Publish`               | Publish to repository                        |

instructions/repository-specific.instructions.md:286

• This Invoke-Build example has the same alias/path issue as the earlier snippet: PowerShellBuild.IB.Tasks is an exported alias to dot-source after Import-Module, not a child path to combine with the module directory. Update the example to match the working pattern shown in README.md and tests/TestModule/.build.ps1.

. ([IO.Path]::Combine((Split-Path (Get-Module PowerShellBuild -ListAvailable).Path), 'PowerShellBuild.IB.Tasks'))

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tablackburn]

This is a bug in the upstream AIM template — github-cli.instructions.md is synced from tablackburn/ai-agent-instruction-modules. Filed upstream as tablackburn/ai-agent-instruction-modules#23 to fix at the source; this repo will pick up the corrected version on the next AIM sync. Not patched locally to keep the file as a clean upstream mirror.

[tablackburn]

This is also a bug in the upstream AIM template — the instruction contradicts upstream's own CONTRIBUTING.md:94, which correctly says new files go in instruction-templates/. Filed upstream as tablackburn/ai-agent-instruction-modules#23. Not patched locally to keep the file as a clean upstream mirror.

[tablackburn]

Addressed Copilot's review in fbf2bbe.

Inline comments: replies attached to each thread. Summary:

• Lines 73, 141, 279, 286 → fixed in this commit.
• Lines 59, 169 → filed upstream as fix: contributing.instructions.md folder reference and github-cli.instructions.md release notes flag tablackburn/ai-agent-instruction-modules#23 (both are bugs in synced AIM templates; will refresh on next sync).

Suppressed "low confidence" findings (all valid, addressed in the same commit):

• Line 110 → added four signing dependency variable rows.
• Line 198 → added four signing tasks plus expanded the precondition note for Sign.Enabled and Windows-only cmdlet availability.
• Line 286 → same fix as line 141.