feat(#194): update documentation for clarity and consistency

- Refine instructions for step-by-step refactoring of unhealthy files
- Remove redundant references to skills in various sections
- Simplify language for better understanding in the guidelines

Author: stiwicourage

scripts/build/Sync-AgenticCopilotScaffold.psd1

@@ -1,4 +1,4 @@
-@{
+@{
     OutputPath = 'src/resources/agentic-copilot'
 
     SourcePaths = @(
@@ -344,7 +344,31 @@
         }
         @{
             Old = '- For step-by-step refactoring of unhealthy files, use the `building-maintainable-code` and `guiding-refactoring-with-code-health` skills together: the first picks the right guideline, the second runs measured maintainability checks between steps.'
-            New = '- For step-by-step refactoring of unhealthy files, use the `building-maintainable-code` for checks between steps.'
+            New = '- For step-by-step refactoring of unhealthy files, use the `building-maintainable-code` skill for checks between steps.'
+        }
+        @{
+            Old = ', `codescene-quality`, `safeguarding-ai-generated-code`'
+            New = ''
+        }
+        @{
+            Old = '`codescene-quality`, `safeguarding-ai-generated-code`, '
+            New = ''
+        }
+        @{
+            Old = ', `codescene-quality`, `workflow guidance`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code`'
+            New = ''
+        }
+        @{
+            Old = '- a `code_health_review`, reviewer, or `./run.ps1` run flags maintainability problems'
+            New = '- a reviewer or `./run.ps1` run flags maintainability problems'
+        }
+        @{
+            Old = '- measuring or driving a single file''s score across steps — use `guiding-refactoring-with-code-health` for that'
+            New = '- measuring or driving a single file''s score across steps — use the step-by-step workflow below for that'
+        }
+        @{
+            Old = '. For risk-bearing files, also run `code_health_review` from the `safeguarding-ai-generated-code` skill.'
+            New = '.'
         }
         @{
             Old = 'CommandInfo  = Get-Command -Module NovaModuleTools'
@@ -362,5 +386,9 @@
             Old = '- `code_health_review` paired with `guiding-refactoring-with-code-health` when iterating on a single unhealthy file'
             New = ''
         }
+        @{
+            Old = ', or `nova` CLI route naming conventions.'
+            New = '.'
+        }
     )
 }

src/resources/agentic-copilot/.github/copilot-instructions.md

@@ -40,9 +40,9 @@ The table below shows how to route work. Prompts are the task entry points; each
 | Task                          | Prompt                                     | Agent                  | Primary skills                                                                       | Primary instructions                                                              |
 | ----------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
 | Design or scope a change      | `design-change.prompt.md`                  | `architect`            | `powershell-module-development`, `workflow guidance`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix`                                   |
-| Implement an issue            | `implement-issue.prompt.md`                | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
-| Review a change               | `review-change.prompt.md`                  | `reviewer`             | `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `documentation`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `workflow guidance` | All `.github/instructions/*.instructions.md`                                       |
-| Improve test coverage         | `improve-test-coverage.prompt.md`          | `test-engineer`        | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `workflow guidance`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer`                                              |
+| Implement an issue            | `implement-issue.prompt.md`                | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
+| Review a change               | `review-change.prompt.md`                  | `reviewer`             | `building-maintainable-code`, `documentation`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `workflow guidance` | All `.github/instructions/*.instructions.md`                                       |
+| Improve test coverage         | `improve-test-coverage.prompt.md`          | `test-engineer`        | `pester-testing`, `building-maintainable-code` | `testing-policy`, `psscriptanalyzer`                                              |
 | Prepare a release             | `prepare-release.prompt.md`                | `release-manager`      | `release-and-changelog`, `markdown-authoring`                                        | `release-policy`, `repository-conventions`                                         |
 | Fix a CI failure              | `fix-ci-failure.prompt.md`                 | `powershell-developer` (or `test-engineer`) | `workflow guidance`, `pester-testing`                                                   | `testing-policy`, `psscriptanalyzer`, `repository-conventions`                     |
 | Update project docs           | (no dedicated prompt — invoke agent)        | `documentation`            | `documentation`, `markdown-authoring`                                                    | `documentation`                                                         |

src/resources/agentic-copilot/.github/instructions/code-quality-matrix.instructions.md

@@ -135,4 +135,4 @@ This file tells Agentic Copilot how to shape source code from the start. Test-sp
 - Flag long mixed-responsibility functions, deep nesting, duplicated blocks, long parameter lists, pass-through helpers, provider-specific branching spread across callers, dead or commented-out code, magic values, and broad or hidden exception handling.
 - When a finding is unit-level (Guidelines 1–4), prefer raising it before component-level findings (Guidelines 5–8). The unit fix usually makes the component fix smaller.
 - When the code smell is test-specific, route that feedback through `.github/instructions/testing-policy.instructions.md` and the `pester-testing` skill instead of stretching this file to cover test-only patterns.
-- For step-by-step refactoring of unhealthy files, use the `building-maintainable-code` for checks between steps.
+- For step-by-step refactoring of unhealthy files, use the `building-maintainable-code` skill for checks between steps.

src/resources/agentic-copilot/.github/instructions/powershell-coding-standards.instructions.md

@@ -24,7 +24,7 @@ Use this file when changing `src/public/`, `src/private/`, or PowerShell build/r
 - Additional functions in a private file are allowed only as related top-level support helpers called from that same file.
 - If two private functions are both called from outside their file, split them into separate same-named files.
 - Do not declare functions inside other functions. Keep private support helpers as sibling top-level functions in the file instead of nested function declarations.
-- Private helper names should not use the public `Invoke-{{ShortName}}*`, `Get-{{ShortName}}*`, `Update-{{ShortName}}*`, or `nova` CLI route naming conventions. Give private helpers clear implementation-focused names that describe what the helper does.
+- Private helper names should not use the public `Invoke-{{ShortName}}*`, `Get-{{ShortName}}*`, `Update-{{ShortName}}*`. Give private helpers clear implementation-focused names that describe what the helper does.
 - Reuse existing adapters and shared helpers before adding new infrastructure calls.
 - Keep direct environment access, Git execution, upload requests, and self-update execution in their approved helper locations. `tests/*Architecture*.Tests.ps1` is authoritative.
 - Prefer explicit workflow-context objects (`[pscustomobject]` / ordered hashtables) for multi-step flows.

src/resources/agentic-copilot/.github/skills/building-maintainable-code/SKILL.md

@@ -11,14 +11,14 @@ Use this skill when:
 
 - adding a new public command or private helper to {{ProjectName}}
 - refactoring a function, file, or domain folder that has grown over time
-- a `code_health_review`, reviewer, or `./run.ps1` run flags maintainability problems
+- a reviewer or `./run.ps1` run flags maintainability problems
 - you want a concrete, PowerShell-aware playbook for the guidelines
 
 Do not use this skill for:
 
 - test-specific guidance — use the `pester-testing` skill
 - release/changelog work — use the `release-and-changelog` skill
-- measuring or driving a single file's score across steps — use `guiding-refactoring-with-code-health` for that
+- measuring or driving a single file's score across steps — use the step-by-step workflow below for that
 
 The companion instruction file is `.github/instructions/code-quality-matrix.instructions.md`. This skill is the actionable workflow that implements those rules.
 
@@ -67,7 +67,7 @@ Follow these steps for any non-trivial PowerShell change.
 1. Read the changed function and surrounding file. Note where it sits in `src/public/`, `src/private/<domain>/`, or `scripts/`.
 2. For each new or heavily changed function, walk the checklist below in order.
 3. If a step requires a refactor, make it the smallest structural step that fixes the specific finding. Do not bundle unrelated cleanup.
-4. After meaningful steps, run `./run.ps1` (analyzer → build → `Test-NovaBuild`). For risk-bearing files, also run `code_health_review` from the `safeguarding-ai-generated-code` skill.
+4. After meaningful steps, run `./run.ps1` (analyzer → build → `Test-NovaBuild`).
 5. Before handoff, normalize every changed text file to exactly one trailing newline.
 
 ### Step 1 — Short units (≤ 15 lines)

src/resources/agentic-copilot/AGENTS.md

@@ -42,9 +42,9 @@ The table below shows how to route work. Prompts are the task entry points; each
 | Task                          | Prompt                                     | Agent                  | Primary skills                                                                       | Primary instructions                                                              |
 | ----------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
 | Design or scope a change      | `design-change.prompt.md`                  | `architect`            | `powershell-module-development`, `workflow guidance`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix`                                   |
-| Implement an issue            | `implement-issue.prompt.md`                | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
-| Review a change               | `review-change.prompt.md`                  | `reviewer`             | `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `documentation`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `workflow guidance` | All `.github/instructions/*.instructions.md`                                       |
-| Improve test coverage         | `improve-test-coverage.prompt.md`          | `test-engineer`        | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `workflow guidance`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer`                                              |
+| Implement an issue            | `implement-issue.prompt.md`                | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` |
+| Review a change               | `review-change.prompt.md`                  | `reviewer`             | `building-maintainable-code`, `documentation`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `workflow guidance` | All `.github/instructions/*.instructions.md`                                       |
+| Improve test coverage         | `improve-test-coverage.prompt.md`          | `test-engineer`        | `pester-testing`, `building-maintainable-code` | `testing-policy`, `psscriptanalyzer`                                              |
 | Prepare a release             | `prepare-release.prompt.md`                | `release-manager`      | `release-and-changelog`, `markdown-authoring`                                        | `release-policy`, `repository-conventions`                                         |
 | Fix a CI failure              | `fix-ci-failure.prompt.md`                 | `powershell-developer` (or `test-engineer`) | `workflow guidance`, `pester-testing`                                                   | `testing-policy`, `psscriptanalyzer`, `repository-conventions`                     |
 | Update project docs           | (no dedicated prompt — invoke agent)        | `documentation`            | `documentation`, `markdown-authoring`                                                    | `documentation`                                                         |