feat(guidance): add task-scoped AI guidance

.codex/skills/change-delivery-workflow/SKILL.md

@@ -34,7 +34,7 @@ If the repo does not provide a clear versioning contract, default to a `CHANGELO
 
 Use this sequence before editing:
 
-1. Read the repository guidance and inspect the working tree.
+1. Read the repository guidance, inspect the working tree, fetch and prune `origin`, require a usable upstream, and confirm the branch contains `origin/main`. Stop without editing, pulling, rebasing, or merging if any freshness check fails.
 2. If the current branch is `main` or `master`, create and switch to a working branch before making changes.
 3. Review the relevant implementation, tests, docs, and existing validators before choosing the smallest safe change.
 4. Decide whether the repo already defines a release workflow that should be respected for this change.

.codex/skills/downstream-guidance-sync/SKILL.md

@@ -52,7 +52,7 @@ If the downstream repo is missing `scripts/Initialize-DownstreamRepo.ps1` or `.c
 
 When the user requests sync changes, use this sequence:
 
-1. Confirm the downstream repo has a clean working tree.
+1. Confirm both the template and downstream repositories have clean working trees, usable upstreams, and branches containing `origin/main`; fetch and prune each `origin`. Stop without applying, pulling, rebasing, or merging if any check fails.
 2. Create or switch to a non-main branch in the downstream repo, for example:
 
    ```powershell
@@ -121,4 +121,4 @@ It must not update downstream source, tests, Pester configuration, PSScriptAnaly
 
 ## Agent Role
 
-Treat the script as the source of truth for deterministic behavior. The agent role is to orchestrate: run the script, interpret output, inspect diffs, identify whether cleanup assets were delivered, run validation, prepare commits, and draft PR text.
+Treat the script as the source of truth for deterministic behavior. The agent role is to orchestrate: run the script, interpret output, inspect diffs, identify whether cleanup assets were delivered, run validation, prepare commits, and draft PR text.

.codex/skills/downstream-repo-cleanup/SKILL.md

@@ -54,7 +54,7 @@ powershell.exe -NoProfile -File .\scripts\Initialize-DownstreamRepo.ps1 -OutputF
 
 When the user requests cleanup changes, use this sequence:
 
-1. Confirm the repository is still in the immediate post-create window.
+1. Confirm the repository is still in the immediate post-create window, has a clean working tree and usable upstream, and contains the latest `origin/main` after fetching and pruning. Stop without applying, pulling, rebasing, or merging if the freshness preflight fails.
 2. Run the cleanup script with the intended project shape.
 3. Preserve or insert the README template version badge during cleanup.
 4. Inspect the diff and confirm changes are limited to template-maintainer artifact removal, inherited guidance rewrites, and project-type scaffold normalization.

.codex/skills/powershell-authoring/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: powershell-authoring
+description: Author Windows PowerShell 5.1 Desktop functions, modules, and scripts with the template conventions.
+---
+
+# Windows PowerShell Authoring
+
+- Target Windows PowerShell 5.1 Desktop, full .NET Framework, and Windows-only behavior; do not use PowerShell 6+ syntax or platform variables.
+- Use advanced functions, approved verbs, PascalCase parameters, useful validation, comment-based help, terminating errors, and structured output.
+- Place `SupportsShouldProcess` around only the mutation; avoid hidden side effects and `Write-Host` for functional output.

.codex/skills/powershell-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: "Windows PowerShell Authoring"
+short_description: "Author Windows PowerShell 5.1 code"
+default_prompt: "Use $powershell-authoring to implement this Windows PowerShell 5.1 change."

.codex/skills/powershell-external-services/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: powershell-external-services
+description: Implement or review Windows PowerShell 5.1 integrations with Graph, REST, credentials, deprecations, and testable boundaries.
+---
+
+# Windows PowerShell External Services
+
+- Prefer Microsoft Graph PowerShell when supported; justify raw REST calls.
+- Verify service contracts rather than inventing cmdlets, parameters, or API behavior.
+- Keep credentials and tokens out of source and output; isolate integration boundaries for mocking and tests.
+- Preserve Windows PowerShell 5.1 compatibility and document deprecated service migrations.

.codex/skills/powershell-external-services/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: "Windows PowerShell External Services"
+short_description: "Implement Windows PowerShell service integrations"
+default_prompt: "Use $powershell-external-services to implement this Windows PowerShell 5.1 integration."

.codex/skills/powershell-testing-review/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: powershell-testing-review
+description: Test or review Windows PowerShell 5.1 changes using Pester, mocks, analyzer expectations, and repository validation.
+---
+
+# Windows PowerShell Testing And Review
+
+- Test observable contracts and failure behavior with Pester under Windows PowerShell 5.1 Desktop.
+- Mock filesystem, network, service, time, and environment access; do not require live services or credentials.
+- Review help, `ShouldProcess`, validation, errors, secrets, stable output, and Windows PowerShell compatibility.

.codex/skills/powershell-testing-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: "Windows PowerShell Testing And Review"
+short_description: "Test and review Windows PowerShell 5.1 changes"
+default_prompt: "Use $powershell-testing-review to validate this Windows PowerShell 5.1 change."

.codex/skills/readme-alignment/SKILL.md

@@ -52,7 +52,7 @@ powershell.exe -NoProfile -File .\scripts\Invoke-ReadmeAlignment.ps1 -OutputForm
 
 When the user requests alignment changes, use this sequence:
 
-1. Confirm the repo is a supported downstream repository.
+1. Confirm the repo is a supported downstream repository with a clean working tree and usable upstream, then fetch and prune `origin` and confirm it contains `origin/main`. Stop without applying, pulling, rebasing, or merging if the freshness preflight fails.
 2. Create or switch to a non-main branch before applying changes.
 3. Run the alignment script:
 

.codex/skills/runtime-policy-update/SKILL.md

@@ -31,13 +31,14 @@ If a requested version or compatibility decision is unclear, inspect the current
 
 Use this order:
 
-1. Update `eng/runtime-policy.json` first.
+1. Confirm a clean working tree and usable upstream, fetch and prune `origin`, and verify the branch contains `origin/main`. Stop without editing, pulling, rebasing, or merging if the freshness preflight fails.
+2. Update `eng/runtime-policy.json` first.
 2. Align policy-managed configuration:
    - `.github/workflows/ci.yml`
    - `.vscode/settings.json`
    - `src/TemplateModule.psd1`
    - `templates/module/ModuleName/ModuleName.psd1`
-3. Update generated Markdown:
+4. Update generated Markdown:
 
    ```powershell
    powershell.exe -NoProfile -File .\scripts\Update-GeneratedMarkdown.ps1

.codex/skills/template-version-release/SKILL.md

@@ -29,6 +29,8 @@ Before acting, identify:
 
 If the next version or bump level is unclear, inspect the change impact and ask before editing release metadata.
 
+Before modifying release metadata, confirm a clean working tree and usable upstream, fetch and prune `origin`, and verify the branch contains `origin/main`. Stop without editing, pulling, rebasing, or merging if the freshness preflight fails.
+
 ## Pre-Merge Release Prep
 
 When preparing a release PR:
@@ -100,7 +102,8 @@ The workflow is complete when:
 - `scripts/Test-TemplateVersion.ps1` passes before the release PR is opened or updated
 - after merge, `main` is fast-forwarded and the lightweight `vX.Y.Z` tag is pushed
 - `scripts/Test-TemplateVersion.ps1 -CheckTag` passes after tagging
-- a GitHub Release exists for `vX.Y.Z` with notes derived from the matching `CHANGELOG.md` section`n- GitHub shows the pushed tag as verified and associated with the intended merged release commit
+- a GitHub Release exists for `vX.Y.Z` with notes derived from the matching `CHANGELOG.md` section
+- GitHub shows the pushed tag as verified and associated with the intended merged release commit
 - the merged local branch has been cleaned up after the remote branch deletion or merge is confirmed
 
 ## Stop Conditions