Add `Invoke-NovaAgenticCopilotScaffold` and `% nova copilot` for applying/updating the Agentic Copilot scaffold in existing projects

[stiwicourage]

Summary

Add a dedicated Nova workflow that applies or refreshes the Agentic Copilot scaffold in an existing PowerShell project.

This should support both:

• projects that do not yet have the Nova Agentic Copilot scaffold
• projects that already have an older scaffold version and need to refresh to the latest Nova scaffold

Problem

Today Nova can scaffold Agentic Copilot guidance during Initialize-NovaModule, but it does not provide a supported way to add or refresh that scaffold in an existing project.

Users should be able to stand in a project root and run a Nova command that applies the latest scaffold safely and explicitly.

Proposed scope

• add public cmdlet Invoke-NovaAgenticCopilotScaffold
• add flat CLI command % nova copilot
• default target path to the current location
• require ShortName on every run
• read ProjectName and Description from project.json
• prompt before overwrite by default
• allow non-interactive execution only through -OverrideWarning / --override-warning
• reuse Nova's existing src/resources/agentic-copilot scaffold content and token replacement behavior
• overwrite only these Nova-managed paths:
  • .github/agents/**
  • .github/instructions/**
  • .github/prompts/**
  • .github/skills/**
  • .github/copilot-instructions.md
  • .github/pull_request_template.md
  • AGENTS.md
  • CONTRIBUTING.md
• add these files only when missing:
  • README.md
  • CHANGELOG.md
  • RELEASE_NOTE.md

Acceptance criteria

1. Invoke-NovaAgenticCopilotScaffold -ShortName NMT applies the scaffold in a valid project root after explicit confirmation.
2. % nova copilot --short-name NMT performs the same workflow from the CLI.
3. Existing managed Agentic Copilot scaffold files are refreshed from the latest Nova scaffold.
4. Existing README.md, CHANGELOG.md, and RELEASE_NOTE.md are not overwritten.
5. Missing README.md, CHANGELOG.md, and RELEASE_NOTE.md are created.
6. The command fails clearly when project.json is missing or invalid.
7. The command fails clearly when ShortName is missing or invalid.
8. -OverrideWarning / --override-warning skips the prompt.
9. The change includes source-mirrored Pester coverage and CLI routing coverage.
10. The change updates help and contributor-facing docs as needed.

Implementation notes

• keep the public cmdlet thin and delegate to private scaffold helpers
• add a separate scaffold workflow for existing-project apply/update instead of extending Initialize-NovaModule
• extract reusable Agentic Copilot template logic from the current init-specific helper instead of duplicating it
• keep the CLI route flat as % nova copilot for now
• do not persist ShortName in project.json
• do not infer ShortName from existing scaffold files
• keep overwrite policy limited to approved Nova-managed scaffold paths

Out of scope

• storing ShortName in project.json
• inferring ShortName from existing files
• selective file-by-file merge/diff workflows
• nova copilot apply or other future copilot subcommands
• expanding Nova ownership to arbitrary .github/ content outside the approved path set

Validation and documentation

Expected follow-up work:

• add/update Pester tests for the public command, scaffold workflow, and CLI route
• update command help in docs/NovaModuleTools/en-US/
• review and update README.md
• review and update CHANGELOG.md
• review and update RELEASE_NOTE.md

Recommended implementation agent

powershell-developer

[stiwicourage]

Problem

Nova can scaffold Agentic Copilot guidance during Initialize-NovaModule, but it does not currently support applying or refreshing that scaffold in an existing PowerShell project.

The requested feature should let a user stand in a project root and apply Nova's latest Agentic Copilot scaffold onto that project, including first-time setup and refresh of older scaffold content.

Why it matters

• Existing Nova-managed PowerShell projects need a supported way to adopt the Agentic Copilot workflow after project creation.
• Projects that already contain an older Nova scaffold need a safe, explicit way to refresh to the latest scaffold version.
• Keeping this flow inside Nova avoids manual copy/paste drift across .github/, AGENTS.md, and contributor guidance files.

Scope

• Add a new public PowerShell command: Invoke-NovaAgenticCopilotScaffold
• Add a new flat CLI command: % nova copilot
• Default the target path to the current project root
• Require an explicit short name on every run
• Read project metadata from project.json for token replacement
• Prompt before overwrite by default
• Allow non-interactive execution only through -OverrideWarning / --override-warning
• Apply Nova's src/resources/agentic-copilot scaffold onto an existing project
• Overwrite only Nova-managed Agentic Copilot scaffold paths:
  • .github/agents/**
  • .github/instructions/**
  • .github/prompts/**
  • .github/skills/**
  • .github/copilot-instructions.md
  • .github/pull_request_template.md
  • AGENTS.md
  • CONTRIBUTING.md
• Add these files only when missing, without overwriting existing copies:
  • README.md
  • CHANGELOG.md
  • RELEASE_NOTE.md
• Reuse the existing Agentic Copilot template root and token replacement behavior already used by nova init

Acceptance criteria

1. Running Invoke-NovaAgenticCopilotScaffold -ShortName <name> in a valid project root applies the scaffold after explicit confirmation.
2. Running % nova copilot --short-name <name> performs the same workflow from the CLI.
3. Existing managed Agentic Copilot files are refreshed from Nova's current scaffold content.
4. Existing README.md, CHANGELOG.md, and RELEASE_NOTE.md are preserved.
5. Missing README.md, CHANGELOG.md, and RELEASE_NOTE.md are created from the scaffold.
6. The workflow fails clearly when project.json is missing or invalid.
7. The workflow fails clearly when ShortName is missing.
8. -OverrideWarning / --override-warning skips the overwrite prompt.
9. The new command is covered by source-mirrored Pester tests and CLI routing tests.

Out of scope

• Persisting ShortName into project.json
• Inferring ShortName from existing scaffold files
• Generic merge logic for user-edited managed files
• Diff preview or selective file-by-file apply
• Additional CLI subcommands such as nova copilot apply, nova copilot diff, or nova copilot doctor
• Rewriting the existing Initialize-NovaModule flow beyond extracting shared scaffold logic
• Treating arbitrary .github/ content as Nova-owned outside the approved managed path set

Affected areas and likely files

Public command surface

• src/public/InvokeNovaAgenticCopilotScaffold.ps1
• docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md
• tests/public/InvokeNovaAgenticCopilotScaffold.Tests.ps1

Private scaffold domain

Likely new files:

• src/private/scaffold/GetNovaAgenticCopilotScaffoldWorkflowContext.ps1
• src/private/scaffold/InvokeNovaAgenticCopilotScaffoldWorkflow.ps1
• src/private/scaffold/GetNovaAgenticCopilotManagedPathSet.ps1
• src/private/scaffold/GetNovaAgenticCopilotDefaultDocumentPathSet.ps1

Likely refactor/extract from existing init-specific scaffold logic:

• src/private/scaffold/InitializeNovaModuleAgenticCopilotScaffold.ps1
• src/private/scaffold/GetNovaModuleAgenticCopilotTemplateRoot.ps1

Recommended extraction target so both init and existing-project apply can share behavior cleanly:

• token-map construction
• README token expansion behavior
• normalized file writing
• template-to-destination copy with per-path overwrite policy

CLI routing

• src/private/cli/ConvertFromNovaCopilotCliArgument.ps1
• src/private/cli/InvokeNovaCliCopilotCommand.ps1
• src/private/cli/InvokeNovaCliCommandRoute.ps1
• src/private/cli/GetNovaCliArgumentRoutingState.ps1
• CLI help definition files/helpers as needed for % nova copilot

Tests likely touched:

• tests/private/cli/ConvertFromNovaCopilotCliArgument.Tests.ps1
• tests/private/cli/InvokeNovaCliCopilotCommand.Tests.ps1
• tests/private/cli/InvokeNovaCliCommandRoute.Tests.ps1
• tests/private/cli/GetNovaCliArgumentRoutingState.Tests.ps1

Shared project metadata access

Likely reused as-is:

• src/private/shared/GetNovaProjectInfoContext.ps1
• src/private/shared/Read-ProjectJsonData.ps1

Guardrails and repo wiring

• tests/ArchitectureGuardrails.Tests.ps1
• tests/AgenticCopilotScaffoldSync.Tests.ps1 only if scaffold source content changes
• README.md
• CHANGELOG.md
• RELEASE_NOTE.md

Validation and documentation impact

Validation

• pwsh -NoLogo -NoProfile -File ./run.ps1
• Test-NovaBuild
• targeted command coverage for:
  • Invoke-NovaAgenticCopilotScaffold
  • % nova copilot
• verify ArchitectureGuardrails allowlist updates for the new public command/helper surface
• run CodeScene pre-commit safeguard before handoff/commit because the change touches AI-managed scaffolding behavior

Documentation impact

Update these because the change affects contributor workflow and public command/CLI behavior:

• README.md
• CHANGELOG.md
• RELEASE_NOTE.md
• docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md

Website docs under docs/*.html are likely optional unless you want end-user GitHub Pages guidance for adopting the Agentic Copilot scaffold in existing projects.

Proposed implementation approach

1. Add a dedicated public workflow

Create Invoke-NovaAgenticCopilotScaffold as a thin public cmdlet that:

• defaults -Path to the current location
• requires -ShortName
• supports Nova-style warning bypass through -OverrideWarning
• keeps native PowerShell mutation semantics through SupportsShouldProcess
• delegates all real behavior into a private scaffold workflow context + workflow pair

This keeps the public command aligned with existing Nova patterns instead of overloading Initialize-NovaModule.

2. Add a flat CLI route

Add % nova copilot as a single-action route now.

Recommended CLI shape:

% nova copilot --short-name NMT
% nova copilot --path /repo --short-name NMT
% nova copilot --path /repo --short-name NMT --override-warning

Recommended CLI notes:

• prompt by default
• --override-warning skips the prompt
• no extra apply subcommand yet
• no extra --confirm / -c contract for this route because confirmation is already the default behavior

3. Split reusable scaffold logic from init-specific logic

Do not duplicate the current Initialize-NovaModuleAgenticCopilotScaffold behavior.

Instead, extract shared pieces so both flows can reuse them:

• template root resolution
• token replacement
• README-aware content generation
• file content normalization
• file write helper
• path filtering rules

Then keep two thin entry workflows:

• init flow: create new scaffold as part of project creation
• copilot flow: apply/update scaffold onto an existing project with managed overwrite policy

4. Use explicit path ownership rules

Model the apply behavior around two path sets:

• Managed overwrite set: always refreshed from Nova after confirmation
• Default-document add-only set: only copied when missing

This keeps the behavior predictable and avoids treating unrelated project files as Nova-owned.

5. Build the token map from project metadata plus explicit short name

For the existing-project flow:

• ProjectName from project.json
• Description from project.json
• ShortName from the command parameter every time

This avoids schema expansion and avoids fragile inference from prior scaffold content.

6. Keep failure modes explicit

The workflow should stop with a structured Nova error when:

• project.json is missing
• project.json is invalid
• ShortName is empty or invalid
• the target path is not a project root
• confirmation is declined

Open questions

None blocking at this stage.

Small implementation detail to decide during coding if needed:

• whether the default prompt text should say install or update, or use neutral wording such as apply the Nova Agentic Copilot scaffold

Recommended follow-on agent

powershell-developer