Feature/194 optional agentic copilot scaffold for initialize novamodule nova init

.codescene/code-health-rules.json

@@ -1,5 +1,5 @@
 {
-  "usage": "Persist this file inside your repositories as .codescene/code-health-rules.json Keep the rules you want to override, remove the rest for simplicity and an easy overview.Override the code health rules by changing the default 1.0 value to a lower relative weight. A value of 0.0 disables the rule. A value of 0.5 still implies a code health hit but only at 50% of the default impact. Note that you can specify multiple rule sets and use the matching-content-path to control to which parts or languages the rules apply. This makes it possible to differentiate between test vs application code, or tailor rules to specific languages. In case multiple rule sets match a piece of content, then we prioritize the first mathcing set of rules.",
+  "usage": "Keep the rules you want to override, remove the rest for simplicity and an easy overview. Override the code health rules by changing the default 1.0 value to a lower relative weight. A value of 0.0 disables the rule. A value of 0.5 still implies a code health hit but only at 50% of the default impact. Note that you can specify multiple rule sets and use the matching-content-path to control to which parts or languages the rules apply. This makes it possible to differentiate between test vs application code, or tailor rules to specific languages. In case multiple rule sets match a piece of content, then we prioritize the first matching set of rules.",
   "rule_sets": [
     {
       "thresholds": [

.github/actions/check-coverage/action.yml

@@ -30,5 +30,5 @@ runs:
         CS_ACCESS_TOKEN: ${{ inputs.access-token }}
       run: |
         set -euo pipefail
-        find "$(pwd)" -name '*.cobertura.xml' -print
+        find "$(pwd)" -name 'coverage.xml' -print
         "$(pwd)/cs-coverage" check --verbose --coverage-files "${{ inputs.coverage-files }}"

.github/agents/architect.agent.md

@@ -37,11 +37,12 @@ Design or reshape changes that cross public commands, private helper boundaries,
 ## Skills to use
 
 - `/powershell-module-development`
-- `/github-actions`
 - `/release-and-changelog`
+- `/markdown-authoring`
+- `/building-maintainable-code`
+- `/github-actions`
 - `/codescene-quality`
 - `/guiding-refactoring-with-code-health`
-- `/markdown-authoring`
 
 ## Constraints
 
@@ -62,6 +63,7 @@ Design or reshape changes that cross public commands, private helper boundaries,
 - 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.
+- Finalization output is copy-ready Markdown that applies the project `markdown-authoring` skill.
 
 ## Must not do
 
@@ -71,4 +73,5 @@ Design or reshape changes that cross public commands, private helper boundaries,
 - Must not create or edit repository files when the task is still in design mode.
 - Must not return a full implementation plan or finished issue draft in the first reply when the user is clearly asking for a design discussion.
 - Must not leave the user guessing whether the final output is a handoff document, paste-ready issue text, or both.
+- Must not return finalization Markdown that skips the project `markdown-authoring` guidance.
 - Must not decide on its own that requested work is out of scope and then finalize the design without the user's confirmation.

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

@@ -27,7 +27,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
 
 ## Skills to use
 
-- `/docs-site-html`
+- `/docs-site`
 - `/markdown-authoring`
 - `/powershell-module-development`
 - `/release-and-changelog`

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

@@ -13,19 +13,27 @@ 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.
-- Add or update tests and documentation for the changed behavior.
+- 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.
+- 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.
+- 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.
 
 ## Inputs to inspect
 
 - The relevant file in `src/public/`
-- Matching helpers in `src/private/build|cli|package|quality|release|scaffold|shared|update/`
+- Matching helpers in `src/private/`
 - Matching test files in `tests/`
 - `project.json`
 
 ## Skills to use
 
 - `/powershell-module-development`
 - `/pester-testing`
+- `/building-maintainable-code`
 - `/codescene-quality`
 - `/guiding-refactoring-with-code-health`
 - `/safeguarding-ai-generated-code`
@@ -36,10 +44,20 @@ 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.
+- 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 `Test-NovaBuild`; do not call `Invoke-Pester` directly.
+- 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.
 
 ## 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 `Test-NovaBuild`.
+- 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.
 
@@ -48,3 +66,4 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 - Must not mix PowerShell cmdlet UX and `nova` CLI UX.
 - Must not add silent fallbacks for invalid or risky behavior.
 - Must not duplicate helpers that already exist elsewhere in the repo.
+- Must not introduce PowerShell 7.x-only constructs into a `5.1` project unless guarded multi-version support is explicitly part of the change.

.github/agents/release-manager.agent.md

@@ -15,6 +15,7 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 - Keep `CHANGELOG.md` accurate and release-ready.
 - Review workflow, docs, and versioning implications together.
 - Produce a release-ready summary that follows `.github/pull_request_template.md` when a release preparation summary is requested.
+- When the release scope is unclear (for example whether the change targets a stable bump, a prerelease, or both), ask one clarifying question before proceeding instead of guessing.
 
 ## Inputs to inspect
 
@@ -29,20 +30,18 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 
 - `/release-and-changelog`
 - `/markdown-authoring`
-- `/github-actions`
 - `/pester-testing`
+- `/github-actions`
 
 ## Constraints
 
 - Treat release automation as high-risk.
 - Keep Keep a Changelog structure intact.
-- Use only the official Keep a Changelog section types in `CHANGELOG.md` and `RELEASE_NOTE.md`: `Added`, `Changed`,
-  `Deprecated`, `Removed`, `Fixed`, and `Security`.
+- Use only the official Keep a Changelog section types in `CHANGELOG.md` and `RELEASE_NOTE.md`: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 - Do not invent extra changelog section headings such as `Documentation`; place documentation-related release notes under the official type that best matches the actual impact.
 - Distinguish contributor docs from end-user docs.
 - Treat `.github/pull_request_template.md` as the authoritative format for structured release summaries.
-- When the release summary is returned as Markdown or copy-ready UI output, it must follow the `markdown-authoring`
-  skill (`.github/skills/markdown-authoring/SKILL.md`).
+- When the release summary is returned as Markdown or copy-ready UI output, it must follow the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`).
 
 ## Definition of done
 

.github/agents/reviewer.agent.md

@@ -14,9 +14,23 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - Start with the highest-risk workflow or public behavior surface.
 - Check for missing tests, doc drift, changelog gaps, and CI/release side effects.
 - Use the PR template categories as the review frame.
+- When the review scope is genuinely ambiguous (for example which subset of files to focus on, or whether a borderline behavior change is intentional), ask one clarifying question before proceeding instead of guessing.
 - Treat CodeScene maintainability and changed-code coverage results as release-blocking signals unless risk is accepted explicitly.
 - If local CodeScene tooling is unavailable, continue the review with normal validation and rely on PR/CI as the effective CodeScene gate.
 - Check whether website docs preserve the CLI-vs-cmdlet separation when `docs/*.html` or help markdown changed.
+- Check that Nova projects still use generated `dist/` module files instead of hand-written source `.psm1` or module `.psd1` files.
+- Check changed PowerShell code, tests, and examples against `project.json` `Manifest.PowerShellHostVersion`; flag PowerShell 7.x-only constructs in projects that target `5.1` unless the change explicitly adds guarded compatibility handling.
+- Check that public commands/classes have matching valid PlatyPS-compatible help and that new source files have source-mirrored tests. Flag help files under `docs/NovaModuleTools/en-US/` that look like plain Markdown, break the required PlatyPS section order, or would fail `Test-MarkdownCommandHelp` / `Import-MarkdownCommandHelp`.
+- Flag any new public entry point that does not add its matching help file in the same change.
+- Flag help files where `external help file` contains a command name instead of the module name. The correct value is `NovaModuleTools-Help.xml`; a per-command name like `Get-Something-Help.xml` means the help was generated without the built module imported.
+- Check analyzer changes and PowerShell validation flow against `.github/instructions/psscriptanalyzer.instructions.md`. Flag direct `Invoke-ScriptAnalyzer` usage that bypasses repository-approved settings or wrapper semantics without a clear reason.
+- Review changed `src/**/*.ps1` against `.github/instructions/code-quality-matrix.instructions.md` and `tests/**/*.ps1` against `.github/instructions/testing-policy.instructions.md`; flag new or heavily changed code that ignores those maintainability rules without a clear, explicit reason.
+- Flag public files that do not keep exactly one top-level function, and flag private files that group multiple externally called functions instead of limiting extra functions to related same-file top-level support helpers. Also flag file/function name mismatches for public commands or externally called private helpers, and flag nested function declarations inside PowerShell functions.
+- Flag broad catch-all test files when focused source-mirrored tests would make ownership clearer.
+- Flag Nova-managed validation that bypasses `Test-NovaBuild` with direct `Invoke-Pester`.
+- Flag any PSScriptAnalyzer rule excludes or suppressions; the code should be fixed instead.
+- Flag unresolved ScriptAnalyzer findings from `run.ps1` or `Invoke-ScriptAnalyzerCI.ps1`; they should be fixed instead of deferred.
+- Flag every changed or generated text file if they do not exactly have one trailing newline with no extra blank lines at the bottom.
 
 ## Inputs to inspect
 
@@ -29,11 +43,12 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 
 - `/codescene-quality`
 - `/safeguarding-ai-generated-code`
-- `/docs-site-html`
+- `/building-maintainable-code`
+- `/docs-site`
 - `/markdown-authoring`
 - `/pester-testing`
-- `/github-actions`
 - `/release-and-changelog`
+- `/github-actions`
 
 ## Constraints
 

.github/agents/test-engineer.agent.md

@@ -13,7 +13,13 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 
 - Add missing Pester coverage for changed behavior.
 - Refactor brittle or duplicated tests into reusable support patterns.
+- Enforce a source-mirrored test layout for new projects and newly added or changed source files.
+- Keep test files and helpers compatible with the project's `project.json` `Manifest.PowerShellHostVersion` target.
+- Use `.github/instructions/testing-policy.instructions.md` as the test-design source of truth while shaping `tests/**/*.ps1`.
+- Use `.github/instructions/psscriptanalyzer.instructions.md` when changing tests, test helpers, or analyzer/CI helpers so the repo-standard analyzer workflow stays intact.
 - Keep CI coverage output compatible with the CodeScene workflow.
+- 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.
+
 
 ## Inputs to inspect
 
@@ -27,21 +33,29 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 
 - `/pester-testing`
 - `/codescene-quality`
+- `/building-maintainable-code`
 - `/github-actions`
 - `/guiding-refactoring-with-code-health`
 - `/safeguarding-ai-generated-code`
 
 ## Constraints
 
-- Prefer targeted tests first, then the full repo quality loop.
+- Prefer the smallest `Test-NovaBuild` scope the project already supports, then the full repo quality loop.
 - Keep test files maintainable; passing tests are not enough if Code Health degrades.
 - Reuse existing fixture and support patterns before adding new ones.
+- Do not group unrelated source files into one broad test file when mirrored `tests/public`, `tests/private`, or `tests/classes` ownership is possible.
+- Do not introduce PowerShell 7.x-only test syntax or APIs into a project that targets `5.1` unless compatibility coverage is explicitly part of the scope.
 - If CodeScene flags a regression, refactor the tests or helpers instead of suppressing the finding.
+- Keep new or heavily changed tests focused, isolated, and easy to scan; split setup or assertion helpers when a test stops being readable.
+- Use `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` as the normal analyzer entrypoint for changed test/helpers, and only fall back to direct `Invoke-ScriptAnalyzer` for focused local investigation with the repository-approved settings.
+- Use `Test-NovaBuild` as the test entrypoint for Nova-managed projects; do not validate with direct `Invoke-Pester`.
 
 ## Definition of done
 
 - The changed behavior is covered.
+- Each new or changed `src/**/*.ps1` file has a matching source-mirrored test, or the cross-cutting owner test is named explicitly.
 - The touched tests are readable and low-duplication.
+- Validation uses `Test-NovaBuild` for project test execution.
 - Validation and CodeScene implications are addressed.
 - The pre-commit CodeScene safeguard is clean before the work is treated as commit-ready when local CodeScene tooling is available.