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-17 (AIM 0.8.14)
• 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.

AIM 0.8.14 sync

Bumped from 0.8.13 → 0.8.14 (released 2026-05-16). Pulls three instruction-file fixes from tablackburn/ai-agent-instruction-modules#24:

• contributing.instructions.md — "Make Changes" pointed contributors at instructions/ instead of instruction-templates/. Surfaced during Copilot review of this PR and filed upstream as tablackburn/ai-agent-instruction-modules#23.
• github-cli.instructions.md — "Creating Releases" example used gh release create --notes, contradicting releases.instructions.md which mandates --notes-file to avoid escaping issues. Replaced with a temp-file pattern and added a precedence note. Also surfaced during this PR's review; same upstream issue.
• shorthand.instructions.md — backfilled the missing Dir → Directory row (pre-existing sync drift in the upstream template; fixed in the same upstream PR).

AGENTS.md Template Version 0.8.13 → 0.8.14 and Last sync 2026-05-15 → 2026-05-17.

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
3. docs: address Copilot review feedback on repository-specific instructions — Sign/Catalog rows, IB alias examples, -FromModule psake pattern, signing task dependency + task rows
4. docs: sync AIM 0.8.14 fixes (contributing folder, gh release notes, Dir row) — pull the three instruction-file fixes from AIM 0.8.14 and bump template version + sync date

🤖 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]

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.