You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/agents/docs-site.agent.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
14
14
- Update `docs/*.html` when end-user workflows, examples, or website wording change.
15
15
- Preserve the separation between CLI-oriented website docs and PowerShell cmdlet help.
16
16
- Check whether source, tests, help docs, and website docs still agree after a change.
17
+
- Keep command-surface-toggle pages honest by splitting CLI-only and PowerShell-only wording into the matching `data-command-visibility` blocks instead of mixing both spellings in shared prose.
17
18
18
19
## Inputs to inspect
19
20
@@ -37,15 +38,18 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused,
37
38
- Treat `docs/*.html` as end-user website docs, not cmdlet help.
38
39
- Keep CLI and cmdlet surfaces clearly separated.
39
40
- Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as installing NovaModuleTools with `Install-Module`.
41
+
- On pages with the surface toggle, only show `--option` spellings in command-line-visible blocks and only show `-Parameter` spellings in PowerShell-visible blocks unless the wording is fully surface-neutral.
40
42
41
43
## Definition of done
42
44
43
45
- The changed website docs reflect the current behavior.
44
46
- CLI-oriented docs do not drift into cmdlet-help wording.
47
+
- Surface-specific labels, flags, and parameter names match the active website command surface.
45
48
- Relevant contributor docs and changelog were reviewed for follow-up impact.
46
49
47
50
## Must not do
48
51
49
52
- Must not mix cmdlet syntax into CLI docs when a CLI variant exists.
53
+
- Must not leave shared always-visible HTML copy with both CLI flags and PowerShell parameters when the page already has the command-surface toggle.
50
54
- Must not use `docs/*.html` as a duplicate of `docs/NovaModuleTools/en-US/*.md`.
51
55
- Must not leave installation/documentation exceptions implicit; state them clearly.
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+10-9Lines changed: 10 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,15 +37,15 @@ For new or not-yet-scoped work, use the `architect` agent with `.github/prompts/
37
37
38
38
The table below shows how to route work. Prompts are the task entry points; each prompt delegates to its agent, which uses the listed skills, which in turn enforce the listed instructions.
- The `external help file` field must always use the module name, not the command name: `NovaModuleTools-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `<ModuleName>-Help.xml` under `dist/<ModuleName>/en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help.
67
67
- Keep the H1 title equal to the exact command name.
68
68
- Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`.
69
+
- In `## RELATED LINKS`, use only a bulleted list of Markdown links. Do not use bare URLs or backticked command names as list items.
70
+
- Prefer relative links to sibling command-help files when the related topic has a matching file in `docs/NovaModuleTools/en-US/`, for example `[Invoke-NovaBuild](./Invoke-NovaBuild.md)`.
71
+
- Do not use GitHub blob URLs in shipped command help. If a relative command-help link is not suitable after PlatyPS validation, use the related topic's `novamoduletools.com``HelpUri` instead.
69
72
- Keep at least one example under `## EXAMPLES`.
70
73
- Keep parameter sections as `### -ParameterName` blocks with the PlatyPS-generated YAML metadata code block.
71
74
- Only hand-edit parameter metadata when PlatyPS cannot infer it correctly, especially `DefaultValue` and `SupportsWildcards`.
- Use `Update-MarkdownCommandHelp` after command or parameter changes so syntax, aliases, and parameter metadata stay synchronized with the implementation.
83
86
- Use `Test-MarkdownCommandHelp` as the quick structural gate before handoff; use `Import-MarkdownCommandHelp` diagnostics when you need more detail.
84
87
- Use existing valid files under `docs/NovaModuleTools/en-US/` as the structural template before inventing a new layout.
88
+
- Validate any new `RELATED LINKS` target style through the real PlatyPS import/export path before applying it repo-wide.
85
89
- Keep command help separate from contributor docs and project/site docs.
- Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`NovaModuleTools-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime.
91
95
- Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`.
92
96
- Reviewers should flag any new public entry point that does not add its matching command-help file in the same change.
97
+
- Reviewers should flag `RELATED LINKS` entries that use GitHub blob URLs, plain URLs, or bare/backticked command names instead of Markdown links.
93
98
- Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet.
Use the `terminal-ux-design` skill when a change touches any user-facing command, terminal output, prompt, help surface, progress indicator, warning, error message, or scaffold guidance for those surfaces.
8
+
9
+
This applies to:
10
+
11
+
- PowerShell cmdlets
12
+
-`% nova` CLI routes
13
+
- private helpers that shape user-visible terminal behavior
14
+
- contributor docs, command help, and scaffold content that teach those workflows
15
+
16
+
Keep PowerShell cmdlet UX and `% nova` CLI UX distinct, but hold both to the same terminal UX bar.
17
+
18
+
The skill is authoritative for:
19
+
20
+
- Atlassian's 10 design principles for delightful CLIs
21
+
- Jakob Nielsen's 10 usability heuristics for user interface design
Copy file name to clipboardExpand all lines: .github/skills/docs-site/SKILL.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,17 +24,20 @@ Use this skill when changing `docs/*.html`, end-user examples, installation guid
24
24
- Use CLI-oriented examples when the workflow has a `nova` variant.
25
25
- Mention PowerShell cmdlets only when no CLI equivalent exists for that scenario.
26
26
- Keep installation guidance explicit about PowerShell-only steps such as `Install-Module`.
27
+
- On pages with the command-surface toggle, keep option/parameter wording aligned with the active surface by using `data-command-visibility="command-line"` and `data-command-visibility="powershell"` blocks instead of one shared paragraph that mixes CLI flags with PowerShell parameters.
27
28
- Recheck the matching command-help markdown when public behavior changes.
28
29
29
30
## Common pitfalls
30
31
31
32
- Mixing `Get-/Set-/Invoke-/Install-` cmdlets into CLI docs where `nova` exists
33
+
- Leaving `--option` text visible in PowerShell mode, or `-Parameter` text visible in command-line mode, because the surrounding prose was not split by `data-command-visibility`
32
34
- Duplicating cmdlet help text in website docs instead of adapting it for end users
33
35
- Forgetting that `docs/NovaModuleTools/en-US/*.md` and `docs/*.html` serve different audiences
34
36
- Updating website docs without reviewing changelog or contributor-doc impact
35
37
36
38
## Verification
37
39
38
40
- Read the touched HTML page as an end-user flow
41
+
- Toggle the page mentally between PowerShell and command-line surfaces and confirm the visible option/parameter names still match that surface
39
42
- Check whether the same behavior is documented consistently in help markdown or contributor docs
40
43
- Use docs-only validation when no executable behavior changed
0 commit comments