`feat: introduce terminal-ux-design skill and instruction for delightful command UX`

[stiwicourage]

Summary

Introduce a canonical terminal UX guidance layer in the agentic copilot so that cmdlets, nova CLI routes, and downstream nova init projects share one bar for terminal user experience. The new skill consolidates two complementary frameworks:

• Atlassian's 10 design principles for delightful CLIs — CLI-specific tactics (help, progress, errors, flags, next best step, etc.).
• Jakob Nielsen's 10 usability heuristics for user interface design — general usability heuristics adapted to terminal interfaces (match real world, error prevention, recognition vs. recall, flexibility/efficiency, aesthetic minimalism, etc.).

This issue covers the guidance only; existing commands are audited in separate follow-on issues (#215–#229).

Why

NovaModuleTools and every module scaffolded by nova init expose themselves to users only through a terminal. We currently have no shared standard for help discoverability, progress visibility, human-readable errors, sensible defaults, next-step hints, exit safety, flags-vs-args, terminology that matches users' mental models, error prevention, recognizable defaults, expert shortcuts, or minimal output. New work drifts on personal taste, and reviewer/architect/developer agents have nothing concrete to validate UX choices against.

Scope

• New skill .github/skills/terminal-ux-design/SKILL.md containing both frameworks in our own words:
  • Section Atlassian's 10 design principles for delightful CLIs — one paragraph per principle with explicit PowerShell-cmdlet and nova CLI mappings.
  • Section Jakob Nielsen's 10 usability heuristics for user interface design — one paragraph per heuristic with explicit PowerShell-cmdlet and nova CLI mappings.
  • One combined mapping table with columns for Concern, Concrete PowerShell / nova mechanism, Atlassian principle(s), Nielsen heuristic(s) — so each row makes both framework links explicit.
  • The usual When to use, Expected practices, Common pitfalls, and Definition of done blocks.
• New thin universal instruction .github/instructions/terminal-ux-design.instructions.md with applyTo: "**" that points at the skill and states the rule applies to any code defining a user-facing command or emitting terminal output.
• Add terminal-ux-design to Skills to use in architect.agent.md, powershell-developer.agent.md, and reviewer.agent.md.
• Update .github/copilot-instructions.md task map (design-change, implement-issue, review-change rows) and Related guidance section.
• Run ./scripts/build/Sync-AgenticCopilotScaffold.ps1 and commit the regenerated src/resources/agentic-copilot/ tree so nova init projects inherit the guidance.
• CHANGELOG.md entry under Unreleased → Added.

Out of scope

• Refactoring any existing public command (handled in separate per-command audit issues refactor(Deploy-NovaPackage): align with terminal-ux-design principles #215–refactor(Update-NovaModuleVersion): align with terminal-ux-design principles #229).
• Changes to nova init questions, scaffold inputs, website docs, release automation, workflows, or project.json.
• New automated linters or analyzer rules to enforce the principles.

Acceptance criteria

• .github/skills/terminal-ux-design/SKILL.md exists with both framework sections and one combined mapping table as described above.
• .github/instructions/terminal-ux-design.instructions.md exists with applyTo: "**" and stays ≤ 25 lines.
• architect.agent.md, powershell-developer.agent.md, and reviewer.agent.md list the new skill under Skills to use.
• .github/copilot-instructions.md task map and Related guidance are updated.
• src/resources/agentic-copilot/ is regenerated via Sync-AgenticCopilotScaffold.ps1 and committed.
• CHANGELOG.md has a new entry under Unreleased → Added.
• pwsh -NoLogo -NoProfile -File ./run.ps1 passes locally.
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1 reports no new findings.
• Per-command follow-on audit issues (refactor(Deploy-NovaPackage): align with terminal-ux-design principles #215–refactor(Update-NovaModuleVersion): align with terminal-ux-design principles #229) reference this issue and use both frameworks in their audit checklists.

Validation

• pwsh -NoLogo -NoProfile -File ./run.ps1
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/Sync-AgenticCopilotScaffold.ps1

Recommended follow-on agent

powershell-developer for implementation; reviewer for merge gate.

[stiwicourage]

Problem

NovaModuleTools and every PowerShell module generated by nova init only ever expose themselves to users through a terminal — either as PowerShell cmdlets or as a nova-style CLI. Today the agentic copilot layer has detailed rules for code quality, testing, and release flow, but no canonical guidance for terminal user experience: progress visibility, help discoverability, human-readable errors, sensible defaults, “next best step” hints, exit safety, flags vs. positional arguments, and skim-readable output.

This means:

• New cmdlets and CLI routes are designed ad hoc, with no shared bar for UX.
• AI-assisted changes have nothing concrete to validate UX choices against during review.
• Scaffolded nova init projects inherit our tooling but not a UX baseline, so derived modules drift in different directions.

Why it matters

• Terminal UX is the only UX surface these modules have; consistency directly determines whether users perceive Nova-built tools as polished or rough.
• The reviewer/architect/developer agents need a measurable standard to apply when designing or reviewing commands — without one, they fall back on personal taste.
• Carrying the guidance into the scaffold raises the floor for every downstream project at zero marginal cost, because Sync-AgenticCopilotScaffold.ps1 already mirrors .github/skills/ and .github/instructions/.

Scope

Issue 1 (this design package) introduces the guidance layer only:

• New skill .github/skills/terminal-ux-design/SKILL.md containing Atlassian's 10 design principles for delightful CLIs in our own words, with explicit PowerShell-cmdlet and nova CLI mappings, examples, and a “when to use” / “definition of done” block consistent with existing skills.
• New thin universal instruction .github/instructions/terminal-ux-design.instructions.md (applyTo: "**") that points at the skill and states the rule applies to any code defining a user-facing command or emitting terminal output.
• Agent updates so architect, powershell-developer, and reviewer list terminal-ux-design under Skills to use.
• Task map update in .github/copilot-instructions.md so the new skill is listed as a Primary skill for the design-change, implement-issue, and review-change rows, plus a new entry under Related guidance.
• Scaffold mirroring: no .psd1 changes required. The new skill and instruction are picked up by Sync-AgenticCopilotScaffold.ps1 automatically. Run the sync as part of the implementation PR.
• CHANGELOG.md entry under Unreleased → Added.

A follow-on tracker stream (separate issues, one per public command) audits and brings existing commands in line with the new skill. Templates are provided below.

Out of scope

• Refactoring any existing cmdlet in the same PR as the guidance. Each command gets its own follow-on issue.
• Changes to nova init questions or scaffold inputs.
• Changes to website docs (docs/*.html) — guidance is contributor-facing.
• New automated linters or analyzer rules to enforce the principles (could be a later issue).
• Changes to release automation, workflows, or project.json.

Affected areas and likely files

• .github/skills/terminal-ux-design/SKILL.md (new)
• .github/instructions/terminal-ux-design.instructions.md (new, applyTo: "**", thin pointer)
• .github/agents/architect.agent.md (add skill reference)
• .github/agents/powershell-developer.agent.md (add skill reference)
• .github/agents/reviewer.agent.md (add skill reference)
• .github/copilot-instructions.md (task map + Related guidance update)
• src/resources/agentic-copilot/.github/skills/terminal-ux-design/SKILL.md (generated by sync)
• src/resources/agentic-copilot/.github/instructions/terminal-ux-design.instructions.md (generated by sync)
• src/resources/agentic-copilot/.github/agents/*.agent.md (regenerated by sync)
• src/resources/agentic-copilot/.github/copilot-instructions.md (regenerated by sync)
• src/resources/agentic-copilot/AGENTS.md (regenerated by sync)
• CHANGELOG.md (Unreleased → Added)

Validation and documentation impact

• Run pwsh -NoLogo -NoProfile -File ./run.ps1 (analyzer → build → Test-NovaBuild).
• Run pwsh -NoLogo -NoProfile -File ./scripts/build/Sync-AgenticCopilotScaffold.ps1 and commit the regenerated scaffold tree.
• Verify the existing scaffold tests in tests/ still pass (especially anything covering the scaffold mirror and text-file formatting).
• Run ./scripts/build/Invoke-ScriptAnalyzerCI.ps1 to confirm no analyzer regression.
• Documentation review:
  • README.md: review only; no user-facing CLI behavior changes. Note in the PR description that no README update is needed.
  • CONTRIBUTING.md: add a short cross-reference to the new skill if contributors are pointed at the skill set there (verify during implementation).
  • CHANGELOG.md: add a Documentation (or Added, since the agent surface is changing) entry under Unreleased.
  • RELEASE_NOTE.md: not affected.
  • docs/*.html: not affected.
  • PlatyPS command help (docs/NovaModuleTools/en-US/*.md): not affected by this issue; affected per command in the follow-on issues.

Proposed implementation approach

1. Draft the new skill file using the existing skill template (frontmatter name: and description: matching .github/skills/*/SKILL.md). Structure:
   • When to use
   • Relevant files (cmdlet files, CLI route helpers, Stop-NovaOperation, Write-Progress/Write-Warning callsites, comment-based help)
   • Atlassian's 10 design principles — restated in our own words with one paragraph each; each principle ends with a PowerShell cmdlet and nova CLI mapping line
   • PowerShell mapping table — principle → concrete mechanism (Write-Progress, [CmdletBinding(SupportsShouldProcess)], comment-based help, Stop-NovaOperation with ErrorId + suggestion text, named parameters with short aliases, Ctrl+C/cancellation handling, Write-Warning plus -OverrideWarning/--override-warning)
   • Expected practices
   • Common pitfalls
   • Definition of done
2. Draft the universal instruction as a thin pointer (≤ 25 lines): purpose, scope (“any code defining a user-facing command or emitting terminal output”), and a single rule directing the agent to use the terminal-ux-design skill before adding or changing such code.
3. Add terminal-ux-design under Skills to use in architect.agent.md, powershell-developer.agent.md, and reviewer.agent.md.
4. Update .github/copilot-instructions.md:
   • Add terminal-ux-design to the Primary skills column for design-change, implement-issue, and review-change rows.
   • Add one line under Related guidance: Terminal UX: .github/instructions/terminal-ux-design.instructions.md + terminal-ux-design skill.
5. Run Sync-AgenticCopilotScaffold.ps1 and commit the regenerated src/resources/agentic-copilot/ tree as part of the same PR.
6. Add CHANGELOG.md entry under Unreleased → Added.
7. Run the local quality loop.

Open questions

• None blocking. Minor: confirm during implementation that the instruction file does not need a documentation-separation-style addition for the scaffold sync TextReplacements (it should not, because the skill name does not collide with any replaced identifier).

Recommended follow-on agent

powershell-developer for the implementation of Issue 1. reviewer for the merge gate. After Issue 1 ships, the per-command audit issues (one per public command, template below) should be implemented by powershell-developer and reviewed by reviewer, using the new terminal-ux-design skill as the measuring stick.