feat(#194): enhance agentic Copilot scaffold with identifier replacements and documentation updates

- Update design and review prompts for consistency in section naming
- Introduce identifier replacement lists in scaffold content functions
- Adjust documentation references to use project-specific naming conventions

Author: stiwicourage

.github/agents/architect.agent.md

@@ -37,12 +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`
-- `/building-maintainable-code`
-- `/markdown-authoring`
 
 ## Constraints
 

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

@@ -25,7 +25,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style.
 ## 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`
 

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

@@ -30,8 +30,8 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 
 - `/release-and-changelog`
 - `/markdown-authoring`
-- `/github-actions`
 - `/pester-testing`
+- `/github-actions`
 
 ## Constraints
 

scripts/build/Sync-AgenticCopilotScaffold.ps1

@@ -165,56 +165,29 @@ function Split-AgenticContentByCodeFence {
     return ,$segments.ToArray()
 }
 
-function Invoke-AgenticInlineCodeAwareReplace {
-    param(
-        [Parameter(Mandatory)][string]$Text,
-        [Parameter(Mandatory)][string]$Old,
-        [Parameter(Mandatory)][AllowEmptyString()][string]$New
-    )
-
-    $result = [System.Text.StringBuilder]::new()
-    $isInsideInlineCode = $false
-    $i = 0
-    while ($i -lt $Text.Length) {
-        $character = $Text[$i]
-        if ($character -eq '`') {
-            $isInsideInlineCode = -not $isInsideInlineCode
-            [void]$result.Append($character)
-            $i++
-            continue
-        }
-
-        if (-not $isInsideInlineCode -and $i + $Old.Length -le $Text.Length -and $Text.Substring($i, $Old.Length) -eq $Old) {
-            [void]$result.Append($New)
-            $i += $Old.Length
-            continue
-        }
-
-        [void]$result.Append($character)
-        $i++
-    }
-
-    return $result.ToString()
-}
-
 function ConvertTo-AgenticScaffoldContent {
     param(
         [Parameter(Mandatory)][string]$Content,
-        [Parameter(Mandatory)][object[]]$ReplacementList
+        [Parameter(Mandatory)][object[]]$ReplacementList,
+        [AllowNull()][AllowEmptyCollection()][object[]]$IdentifierReplacementList
     )
 
     $segments = Split-AgenticContentByCodeFence -Content $Content
     $rebuilt = [System.Text.StringBuilder]::new()
     foreach ($segment in $segments) {
-        if ($segment.Kind -eq 'Fenced') {
-            [void]$rebuilt.Append($segment.Text)
-            continue
+        $segmentText = $segment.Text
+        if ($segment.Kind -ne 'Fenced') {
+            foreach ($replacement in $ReplacementList) {
+                $segmentText = $segmentText.Replace([string]$replacement.Old, [string]$replacement.New)
+            }
         }
 
-        $segmentText = $segment.Text
-        foreach ($replacement in $ReplacementList) {
-            $segmentText = Invoke-AgenticInlineCodeAwareReplace -Text $segmentText -Old ([string]$replacement.Old) -New ([string]$replacement.New)
+        if ($IdentifierReplacementList) {
+            foreach ($identifier in $IdentifierReplacementList) {
+                $segmentText = $segmentText.Replace([string]$identifier.Old, [string]$identifier.New)
+            }
         }
+
         [void]$rebuilt.Append($segmentText)
     }
 
@@ -251,7 +224,8 @@ function Write-AgenticMirroredFile {
     param(
         [Parameter(Mandatory)][object]$SourceFile,
         [Parameter(Mandatory)][string]$TargetRoot,
-        [Parameter(Mandatory)][object[]]$ReplacementList
+        [Parameter(Mandatory)][object[]]$ReplacementList,
+        [AllowNull()][AllowEmptyCollection()][object[]]$IdentifierReplacementList
     )
 
     $targetPath = Join-Path $TargetRoot ($SourceFile.RelativePath -replace '/', [System.IO.Path]::DirectorySeparatorChar)
@@ -261,7 +235,7 @@ function Write-AgenticMirroredFile {
     }
 
     $sourceContent = Get-Content -LiteralPath $SourceFile.SourcePath -Raw
-    $targetContent = ConvertTo-AgenticScaffoldContent -Content $sourceContent -ReplacementList $ReplacementList
+    $targetContent = ConvertTo-AgenticScaffoldContent -Content $sourceContent -ReplacementList $ReplacementList -IdentifierReplacementList $IdentifierReplacementList
     Set-Content -LiteralPath $targetPath -Value $targetContent -Encoding utf8 -NoNewline
 }
 
@@ -285,7 +259,8 @@ function Get-AgenticGeneratedMirrorContent {
     param(
         [Parameter(Mandatory)][string]$RootPath,
         [Parameter(Mandatory)][string]$SourceRelativePath,
-        [object[]]$ReplacementList
+        [object[]]$ReplacementList,
+        [AllowNull()][AllowEmptyCollection()][object[]]$IdentifierReplacementList
     )
 
     $sourcePath = Resolve-AgenticRepositoryPath -RootPath $RootPath -RelativePath $SourceRelativePath
@@ -295,10 +270,17 @@ function Get-AgenticGeneratedMirrorContent {
 
     $sourceContent = Get-Content -LiteralPath $sourcePath -Raw
     $banner = "<!-- Generated from $SourceRelativePath by scripts/build/Sync-AgenticCopilotScaffold.ps1. Do not edit by hand. -->`n`n"
-    $body = if ($null -eq $ReplacementList -or $ReplacementList.Count -eq 0) {
+    $hasReplacements = $ReplacementList -and $ReplacementList.Count -gt 0
+    $hasIdentifiers = $IdentifierReplacementList -and $IdentifierReplacementList.Count -gt 0
+    $body = if (-not $hasReplacements -and -not $hasIdentifiers) {
         $sourceContent
     } else {
-        ConvertTo-AgenticScaffoldContent -Content $sourceContent -ReplacementList $ReplacementList
+        $effectiveReplacements = if ($hasReplacements) {
+            $ReplacementList
+        } else {
+            @()
+        }
+        ConvertTo-AgenticScaffoldContent -Content $sourceContent -ReplacementList $effectiveReplacements -IdentifierReplacementList $IdentifierReplacementList
     }
 
     return $banner + $body
@@ -309,7 +291,8 @@ function Invoke-AgenticGeneratedMirrorPlan {
         [Parameter(Mandatory)][string]$RootPath,
         [Parameter(Mandatory)][string]$ScaffoldStagingRoot,
         [Parameter(Mandatory)][object[]]$GeneratedMirrorList,
-        [object[]]$ReplacementList
+        [object[]]$ReplacementList,
+        [AllowNull()][AllowEmptyCollection()][object[]]$IdentifierReplacementList
     )
 
     foreach ($mirror in $GeneratedMirrorList) {
@@ -319,7 +302,7 @@ function Invoke-AgenticGeneratedMirrorPlan {
         }
 
         if ($mirror.ScaffoldTarget) {
-            $scaffoldContent = Get-AgenticGeneratedMirrorContent -RootPath $RootPath -SourceRelativePath $mirror.Source -ReplacementList $ReplacementList
+            $scaffoldContent = Get-AgenticGeneratedMirrorContent -RootPath $RootPath -SourceRelativePath $mirror.Source -ReplacementList $ReplacementList -IdentifierReplacementList $IdentifierReplacementList
             Write-AgenticGeneratedMirrorPath -TargetRoot $ScaffoldStagingRoot -RelativeTarget $mirror.ScaffoldTarget -Content $scaffoldContent
         }
     }
@@ -358,11 +341,11 @@ function Invoke-AgenticCopilotScaffoldSync {
         }
 
         foreach ($sourceFile in $sourceFileList) {
-            Write-AgenticMirroredFile -SourceFile $sourceFile -TargetRoot $stagingRoot -ReplacementList $manifest.TextReplacements
+            Write-AgenticMirroredFile -SourceFile $sourceFile -TargetRoot $stagingRoot -ReplacementList $manifest.TextReplacements -IdentifierReplacementList $manifest.IdentifierReplacements
         }
 
         if ($manifest.ContainsKey('GeneratedMirrors') -and $manifest.GeneratedMirrors) {
-            Invoke-AgenticGeneratedMirrorPlan -RootPath $RootPath -ScaffoldStagingRoot $stagingRoot -GeneratedMirrorList $manifest.GeneratedMirrors -ReplacementList $manifest.TextReplacements
+            Invoke-AgenticGeneratedMirrorPlan -RootPath $RootPath -ScaffoldStagingRoot $stagingRoot -GeneratedMirrorList $manifest.GeneratedMirrors -ReplacementList $manifest.TextReplacements -IdentifierReplacementList $manifest.IdentifierReplacements
         }
 
         if (Test-Path -LiteralPath $TargetRoot) {

scripts/build/Sync-AgenticCopilotScaffold.psd1

@@ -27,6 +27,17 @@
         }
     )
 
+    IdentifierReplacements = @(
+        @{
+            Old = 'NovaModuleTools'
+            New = '{{ProjectName}}'
+        }
+        @{
+            Old = '-Nova*'
+            New = '-{{ShortName}}*'
+        }
+    )
+
     ExcludedPaths = @(
         '.github/agents/docs-site.agent.md'
         '.github/instructions/documentation-separation.instructions.md'
@@ -247,18 +258,10 @@
             Old = 'quality tooling tooling'
             New = 'quality tooling'
         }
-        @{
-            Old = 'NovaModuleTools'
-            New = '{{ProjectName}}'
-        }
         @{
             Old = '- Must not mix PowerShell cmdlet UX and `nova` CLI UX.'
             New = ''
         }
-        @{
-            Old = '-Nova*'
-            New = '-{{ShortName}}*'
-        }
         @{
             Old = ', and the `nova` CLI routing model.'
             New = '.'
@@ -339,5 +342,25 @@
             Old = '- Preserve the distinction between public PowerShell cmdlets and `% nova` CLI behavior.'
             New = ''
         }
+        @{
+            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.'
+        }
+        @{
+            Old = 'CommandInfo  = Get-Command -Module NovaModuleTools'
+            New = 'CommandInfo  = Get-Command -Module {{ProjectName}}'
+        }
+        @{
+            Old = '- Treating maintainability 9.x as the goal. Aim for 10.0 on touched files in this repository.'
+            New = ''
+        }
+        @{
+            Old = '- `code_health_review` and `pre_commit_code_health_safeguard` from `safeguarding-ai-generated-code` before suggesting a commit'
+            New = ''
+        }
+        @{
+            Old = '- `code_health_review` paired with `guiding-refactoring-with-code-health` when iterating on a single unhealthy file'
+            New = ''
+        }
     )
 }

src/resources/agentic-copilot/.github/agents/architect.agent.md

@@ -30,18 +30,16 @@ Design or reshape changes that cross public commands, private helper boundaries,
 - `.github/copilot-instructions.md`
 - `.github/prompts/design-change.prompt.md`
 - `.github/instructions/*.instructions.md`
-- `tests/ArchitectureGuardrails.Tests.ps1`
+- `tests/*Architecture*.Tests.ps1`
 - Relevant `src/public/` and `src/private/<domain>/` files
-- Relevant `.github/workflows/*.yml`
+- Relevant workflow files, when present
 
 ## Skills to use
 
 - `/powershell-module-development`
-- `/github-actions`
 - `/release-and-changelog`
-
-- `/building-maintainable-code`
 - `/markdown-authoring`
+- `/building-maintainable-code`
 
 ## Constraints
 

src/resources/agentic-copilot/.github/agents/powershell-developer.agent.md

@@ -25,7 +25,7 @@ Implement PowerShell command and helper changes in the {{ProjectName}} style.
 ## 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`
 
@@ -44,7 +44,7 @@ Implement PowerShell command and helper changes in the {{ProjectName}} style.
 - 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`: use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. A new public `src/public/*.ps1` file is not done until its matching help file exists.
+- When help files change, keep `docs/{{ProjectName}}/en-US/*.md` valid for `Import-MarkdownCommandHelp`: use `New-MarkdownCommandHelp` for new files, `Update-MarkdownCommandHelp` after command-surface changes, and `Test-MarkdownCommandHelp` before handoff. A new public `src/public/*.ps1` file is not done until its matching help file exists.
 
 ## Definition of done
 

src/resources/agentic-copilot/.github/agents/release-manager.agent.md

@@ -22,15 +22,14 @@ Handle versioning, changelog shaping, release-flow documentation, and publish au
 - `CHANGELOG.md`
 - `project.json`
 - `.github/pull_request_template.md`
-- `.github/workflows/Publish.yml`
+- release workflow files, when present
 - Relevant package, release, and publish tests
 - `README.md` / `CONTRIBUTING.md`
 
 ## Skills to use
 
 - `/release-and-changelog`
 - `/markdown-authoring`
-- `/github-actions`
 - `/pester-testing`
 
 ## Constraints

src/resources/agentic-copilot/.github/agents/reviewer.agent.md

@@ -17,10 +17,10 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 - 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 quality tooling maintainability and changed-code coverage results as release-blocking signals unless risk is accepted explicitly.
 - If local quality tooling is unavailable, continue the review with normal validation and rely on PR/CI as the effective quality tooling gate.
-- Check whether project docs preserve the CLI-vs-cmdlet separation when `docs/*.html` or help markdown changed.
+- Check whether project docs preserve the CLI-vs-cmdlet separation when project docs 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`.
+- 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/{{ProjectName}}/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.
 - 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.
@@ -35,17 +35,16 @@ Review changes for correctness, maintainability, test coverage, workflow safety,
 
 - The change diff
 - `.github/pull_request_template.md`
-- Relevant files in `src/`, `tests/`, `docs/`, and `.github/workflows/`
+- Relevant files in `src/`, `tests/`, `docs/`, and workflow files, when present
 - `README.md`, `CONTRIBUTING.md`, and `CHANGELOG.md` when touched
 
 ## Skills to use
 
 - `/building-maintainable-code`
-- `/docs-site`
+- `/documentation`
 - `/markdown-authoring`
 - `/pester-testing`
 - `/release-and-changelog`
-- `/github-actions`
 
 ## Constraints
 

src/resources/agentic-copilot/.github/agents/test-engineer.agent.md

@@ -24,16 +24,15 @@ Improve or maintain the repository's Pester coverage, coverage-gate behavior, an
 
 - `tests/*.Tests.ps1`
 - `tests/*TestSupport.ps1`
-- `scripts/build/ci/Invoke-NovaModuleToolsCI.ps1`
-- `.github/workflows/Tests.yml`
+- repository CI helper scripts, when present
+- workflow files, when present
 - quality tooling findings when available
 
 ## Skills to use
 
 - `/pester-testing`
 
 - `/building-maintainable-code`
-- `/github-actions`
 
 ## Constraints