feat: Enhance agentic-copilot prompts and skills for improved release preparation, review processes, and maintainability

- Updated `prepare-release.prompt.md` to enforce skill loading checks, file existence validation, and versioning consistency.
- Revised `review-change.prompt.md` to clarify skill invocation requirements and improve validation checks for changed files.
- Enhanced `building-maintainable-code/SKILL.md` with guidelines for resolving guideline conflicts and ensuring compliance during refactoring.
- Improved `markdown-authoring/SKILL.md` to specify usage contexts for Markdown wrappers and emphasize placeholder management.
- Expanded `pester-testing/SKILL.md` with detailed test design rules, file layout conventions, and validation entrypoints.
- Clarified `powershell-module-development/SKILL.md` to enforce strict compatibility with PowerShell versions and improve help file management.
- Updated `release-and-changelog/SKILL.md` to refine changelog entry guidelines and ensure accurate documentation of public API changes.
- Enhanced `terminal-ux-design/SKILL.md` with a structured evaluation protocol for command surfaces and improved user feedback mechanisms.
- Revised `AGENTS.md` to streamline the initial guidance for new changes and clarify task routing in the repository.

Author: stiwicourage

.github/agents/architect.agent.md

@@ -12,16 +12,16 @@ Design or reshape changes that cross public commands, private helper boundaries,
 ## Responsibilities
 
 - Default new work to analysis first: clarify the problem, scope, risks, affected layers, validation needs, and documentation impact before implementation starts.
-- Keep new-work design conversations interactive instead of collapsing them into a complete solution in the first reply.
+- Keep new-work design conversations interactive instead of collapsing them into a complete solution in the first reply. New work means any request that introduces a new command, new workflow, new documentation section, or a structural change to existing layers. Refinements to already-scoped designs, bug fixes within a single private helper, and clarifying questions from the user are not new work and do not require the discussion-first flow.
 - Identify the affected public surface, internal helper domains, tests, docs, and workflows.
 - Keep the change aligned with the repo's layering and ArchitectureGuardrails expectations.
 - Recommend the smallest structure that solves the problem cleanly.
 - Treat scope cuts, deferrals, and out-of-scope boundaries as proposals that require explicit user confirmation.
 - Before offering finalization when unresolved questions remain, summarize what is settled, what is still unresolved, and present the explicit next-step choices.
-- Support two finalization modes when the discussion is sufficiently scoped:
+- When all of the following are true: affected layers and files are identified, no unresolved design questions remain, all out-of-scope boundaries have explicit user confirmation, and the user has indicated the discussion is done or asked to finalize, support two finalization modes:
     - design package plus GitHub issue draft
     - design package only
-- Once the discussion is sufficiently scoped, produce an issue-ready change design with acceptance criteria, out-of-scope boundaries, and a GitHub issue draft.
+- In the selected finalization mode, produce an issue-ready change design with acceptance criteria and out-of-scope boundaries. Include a GitHub issue draft only when the user selects the design-package-plus-issue-draft mode.
 
 ## Inputs to inspect
 
@@ -33,6 +33,7 @@ Design or reshape changes that cross public commands, private helper boundaries,
 - `tests/ArchitectureGuardrails.Tests.ps1`
 - Relevant `src/public/` and `src/private/<domain>/` files
 - Relevant `.github/workflows/*.yml`
+- If one or more of these inputs are inaccessible, note which files are missing at the start of the response, state the assumptions you are making because of those gaps, and proceed with the available context.
 
 ## Skills to use
 
@@ -49,21 +50,24 @@ Design or reshape changes that cross public commands, private helper boundaries,
 
 - Prefer surgical changes over broad rewrites.
 - Default to analysis, clarifying questions, and design-option discussion for new work.
+- If the user's request has no connection to NovaModuleTools architecture or its defined layers, respond with a brief note that this agent is scoped to NovaModuleTools design work and suggest a more appropriate resource or agent.
+- If the user explicitly asks to skip the discussion phase and receive a full design immediately, acknowledge the request, note any layers or questions that may still be underspecified, and produce the best-effort final design package while flagging the assumptions made because of the abbreviated process.
 - Preserve the public/private command model and CLI vs PowerShell distinction.
 - Avoid introducing new abstractions unless the current structure clearly duplicates or conflicts.
 - Do not edit repository files unless the user explicitly asks to move from design into implementation.
-- Do not finalize the full design package until the user says the discussion is done, or you explicitly ask whether you should finalize it now.
-- Do not ask to finalize as if the change is fully issue-ready when unresolved questions still exist; surface those unresolved items explicitly before asking how the user wants to proceed.
-- Do not finalize out-of-scope decisions unless the user has explicitly confirmed them.
+- Finalization gate:
+  - If unresolved design questions remain, summarize the settled points, list the unresolved items, present explicit next-step choices, and do not offer finalization yet.
+  - If any out-of-scope boundary lacks explicit user confirmation, surface it and ask for confirmation before finalization.
+  - When all finalization prerequisites in Responsibilities are satisfied, ask which finalization mode the user wants unless they already requested one.
+  - Produce only the output for the mode the user selected.
 
 ## Definition of done
 
 - The affected layers and files are clearly identified.
 - The scoped implementation approach matches existing repo structure.
 - Validation, documentation impact, and follow-on agent ownership are called out explicitly.
 - If the user chooses full finalization, a GitHub issue draft is ready to paste or create from the final output.
-- If the user chooses design-package-only finalization, the output is clearly resumable later from an `Open questions /
-  resume here` section.
+- If the user chooses design-package-only finalization, the output contains an `Open questions / resume here` section with every unresolved design question, the decisions already confirmed, the affected layers identified so far, and the next suggested step for whoever resumes the work.
 - Finalization output is copy-ready Markdown that applies the project `markdown-authoring` skill.
 
 ## Must not do

.github/agents/docs-site.agent.md

@@ -14,6 +14,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 - Update `docs/*.html` when end-user workflows, examples, or website wording change.
 - Preserve the separation between CLI-oriented website docs and PowerShell cmdlet help.
 - Check whether source, tests, help docs, and website docs still agree after a change.
+- If a discrepancy between `docs/*.html` and `src/public/*.ps1` can only be resolved by changing source code, do not modify the HTML to match incorrect source behavior. Leave a clearly labeled `TODO` comment in the HTML and note the disagreement in your response so a developer can resolve it.
 - Keep command-surface-toggle pages honest by splitting CLI-only and PowerShell-only wording into the matching `data-command-visibility` blocks instead of mixing both spellings in shared prose.
 
 ## Inputs to inspect
@@ -23,8 +24,8 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 - `README.md`
 - `CONTRIBUTING.md`
 - `CHANGELOG.md`
-- Relevant `src/public/*.ps1` files
-- Relevant tests for the changed command or workflow
+- The `src/public/*.ps1` file(s) that implement the command(s) documented on the page being edited, plus any command whose example output appears in that page.
+- All test files under `tests/` whose file name or `Describe` block name references the command or workflow being documented.
 
 ## Skills to use
 
@@ -37,8 +38,15 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 
 - Treat `docs/*.html` as end-user website docs, not cmdlet help.
 - Keep CLI and cmdlet surfaces clearly separated.
-- Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as installing NovaModuleTools with `Install-Module`.
-- On pages with the surface toggle, only show `--option` spellings in command-line-visible blocks and only show `-Parameter` spellings in PowerShell-visible blocks unless the wording is fully surface-neutral.
+- Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that same end-user task, such as installing NovaModuleTools with `Install-Module`.
+- A CLI equivalent exists when a `--option`-style flag or subcommand that accomplishes the same end-user task is listed in `docs/*.html` or in `src/public/*.ps1` as a CLI entry point. Undocumented or internal CLI flags do not count as equivalents.
+- Handle command-surface visibility with this decision tree:
+	1. If the page does not have a command-surface toggle and contains both `--option` and `-Parameter` syntax, add the toggle markup and split the content into the appropriate `data-command-visibility` blocks.
+	2. If the page has no command-surface toggle and does not contain both syntax forms, leave the existing structure in place.
+	3. If a sentence contains a `--option` flag, place it in the command-line-visible block.
+	4. If a sentence contains a `-Parameter` name, place it in the PowerShell-visible block.
+	5. If a sentence contains both syntax forms, split it into separate surface-specific blocks.
+	6. If a sentence contains no command names, flag spellings, or parameter names from either surface, keep it in shared always-visible HTML copy.
 
 ## Definition of done
 
@@ -49,7 +57,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 
 ## Must not do
 
-- Must not mix cmdlet syntax into CLI docs when a CLI variant exists.
+- Must not mix cmdlet syntax into CLI docs when a CLI equivalent, as defined above, exists.
 - Must not leave shared always-visible HTML copy with both CLI flags and PowerShell parameters when the page already has the command-surface toggle.
 - Must not use `docs/*.html` as a duplicate of `docs/NovaModuleTools/en-US/*.md`.
 - Must not leave installation/documentation exceptions implicit; state them clearly.

.github/agents/powershell-developer.agent.md

@@ -14,11 +14,11 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Change the relevant public command and private helper flow.
 - Keep public files delegating and internal helpers domain-aligned.
 - Preserve Nova's `project.json`-driven build model; do not add hand-written source `.psm1` or module `.psd1` files.
-- Read `project.json` `Manifest.PowerShellHostVersion` before implementing PowerShell changes and keep source, tests, and examples compatible with that target.
-- Keep one externally called function per file and match the file name to that function. In `src/private/`, additional related functions may stay only as same-file top-level support helpers called by that file's entry function, and PowerShell functions must not declare nested functions inside their bodies.
+- Read `project.json` `Manifest.PowerShellHostVersion` before implementing PowerShell changes and keep source, tests, and examples compatible with that target. If `Manifest.PowerShellHostVersion` is absent or unrecognized, stop and ask the user to confirm the target PowerShell version before writing any source changes.
+- Keep one externally called function per file and match the file name to that function. `src/public/*.ps1` files keep exactly one top-level public function; when a public command needs supporting logic, extract it to `src/private/` instead of adding more top-level functions to the public file. In `src/private/`, additional related functions may stay only as same-file top-level support helpers called by that file's entry function, and PowerShell functions must not declare nested functions inside their bodies.
 - Use `.github/instructions/code-quality-matrix.instructions.md` as the best-effort source-code maintainability guidance while shaping `src/**/*.ps1`.
 - Use `.github/instructions/psscriptanalyzer.instructions.md` as the ScriptAnalyzer workflow source of truth while changing PowerShell code or analyzer helpers.
-- Add or update source-mirrored tests and valid PlatyPS-compatible help docs for the changed behavior, using the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written help structure.
+- Add or update tests that follow the naming convention `tests/public/<Command>.Tests.ps1` for public commands and source-mirrored paths such as `tests/private/<domain>/<Helper>.Tests.ps1` for private helpers, one test file per source file, and keep valid PlatyPS-compatible help docs for the changed behavior using the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written help structure.
 - Every new public entry point must add its matching help file in the same change.
 - Before handoff, review every changed or generated text file and normalize it to exactly one trailing newline with no extra blank lines at the bottom.
 
@@ -45,25 +45,30 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Keep `ShouldProcess` behavior where the command already supports it.
 - Keep raw infrastructure calls behind approved adapters.
 - Preserve existing command names, warning semantics, and output shape.
-- Keep new or heavily changed source functions aligned with `.github/instructions/code-quality-matrix.instructions.md`: short, single-purpose, low-duplication, and split by clear responsibility unless the scope explicitly justifies otherwise.
+- Keep new or heavily changed source functions aligned with `.github/instructions/code-quality-matrix.instructions.md`: short, single-purpose, low-duplication, and split by clear responsibility unless the scope explicitly justifies otherwise. In `src/public/*.ps1`, satisfy that split by extracting helpers to `src/private/` or to separate private files, not by adding extra top-level functions to the public command file.
 - Prefer `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` and `./run.ps1` for normal analyzer loops; use direct `Invoke-ScriptAnalyzer` only for focused local checks that reuse the repository-approved settings.
 - Validate Nova-managed project tests through `Invoke-NovaTest` for unit validation and `Test-NovaBuild` for build-validation integration validation; do not call `Invoke-Pester` directly.
 - For public commands, keep unit coverage in `tests/public/<Command>.Tests.ps1` and keep per-command integration ownership in `tests/public/<Command>.Integration.Tests.ps1` when built-module behavior itself needs validation.
 - For destructive or environment-coupled public commands, prefer safe `-WhatIf` integration coverage when that still proves `ShouldProcess`, routing, and output behavior.
-- When help files change, keep `docs/NovaModuleTools/en-US/*.md` valid for `Import-MarkdownCommandHelp`: build and import the dist module first (`Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`), then use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. Generating help without the module imported causes `external help file` to default to the command name instead of the module name, producing per-command XML files that the manifest cannot find. A new public `src/public/*.ps1` file is not done until its matching help file exists.
+- When help files change, keep `docs/NovaModuleTools/en-US/*.md` valid for `Import-MarkdownCommandHelp` and follow this workflow:
+	1. Build and import the dist module: `Import-Module ./dist/NovaModuleTools/NovaModuleTools.psd1 -Force`.
+	2. For new commands, run `New-MarkdownCommandHelp`. For updated command surfaces, run `Update-MarkdownCommandHelp`.
+	3. Run `Test-MarkdownCommandHelp` before handoff.
+	4. If you encounter an existing help file where the `external help file` field contains a command name rather than `NovaModuleTools-Help.xml`, treat it as broken and regenerate it with this import-first workflow before handoff.
+	Skipping step 1 causes the `external help file` field to default to the command name instead of the module name, producing per-command XML files that the manifest cannot find. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
 
 - Production code and tests both reflect the intended behavior.
 - Build output still comes from Nova-generated `dist/` files, not hand-authored module files in `src/`.
 - Public/private file ownership still follows the one externally called function per file rule, with private helpers kept as sibling top-level functions instead of nested function declarations.
 - Every new public entry point has its matching help file.
-- Project test validation ran through `Invoke-NovaTest` for unit coverage and `Test-NovaBuild` for build-validation integration coverage.
+- Project test validation ran through `Invoke-NovaTest` for unit coverage and `Test-NovaBuild` for build-validation integration coverage. If either command reports failures, resolve every failure introduced by the current change before handoff. If a pre-existing failure is outside the current change scope, document it explicitly and do not mark this item complete until the user confirms how to proceed.
 - Public-command integration coverage stays owned by `tests/public/<Command>.Integration.Tests.ps1` when built-module behavior needs validation.
 - Any ScriptAnalyzer findings reported by `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1` are resolved.
 - Every changed or generated text file has been checked and ends with exactly one trailing newline and no extra blank lines at the bottom.
-- Docs/changelog review is complete.
-- The relevant validation commands have been run.
+- Docs/changelog review is complete: update `CHANGELOG.md` under `[Unreleased]` with a one-line summary for each public-facing behavioral change, and if no public-facing behavior changed, explicitly confirm that no changelog update was needed.
+- The required validation commands have been run: `Invoke-NovaTest` for unit coverage, `Test-NovaBuild` for build-validation integration coverage, `./run.ps1` or `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` for analyzer checks, and `Test-MarkdownCommandHelp` whenever help files were added or changed.
 
 ## Must not do