Standardize module README + repository, agent, and module-type defaults#61
Open
Marius Storhaug (MariusStorhaug) wants to merge 9 commits into
Open
Standardize module README + repository, agent, and module-type defaults#61Marius Storhaug (MariusStorhaug) wants to merge 9 commits into
Marius Storhaug (MariusStorhaug) wants to merge 9 commits into
Conversation
Trimming a module README must not delete unique information. Adds a content-preservation rule (keep/trim/relocate, never drop), makes the capabilities showcase mandatory for implemented modules, carves out an upstream attribution and licensing exception, fixes the copy/paste-hostile Get-Help example, and extends README validation.
Contributor
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
The README publishes as the module landing page; a bare top-level docs/ is not published by the docs build. Correct the relocation guidance to only published homes (README, group overview pages under src/functions/public, comment-based help) and state that a longer README is acceptable rather than deleting narrative content to shorten it.
…7.6+ - Rename README showcase heading Capabilities -> Usage (Examples allowed); disallow Capabilities and add to README validation. - Each repo stands on its own: carries own governance files, no reliance on org .github fallback; README has no Contributing section (repo ships self-contained CONTRIBUTING.md). - Add agent onboarding files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) to required files + Distributor mandatory sets, pointing to PSModule/docs and MSXOrg/docs. - Placeholder guard: a module exporting any real command is not a placeholder. - Modern PowerShell only: minimum 7.6, track current + LTS; drop 5.1 accommodation. - New Module-Types.md (integration/API + data modules) + Naming.md rules (REST->verb, ConvertTo/From + Format/Import/Export); Hashtable is the data-module reference; Context for user + module settings.
Marius Storhaug (MariusStorhaug)
changed the title
This was referenced Jul 11, 2026
Clarify Repository-Defaults scope so agent onboarding files and repository self-sufficiency apply to every PSModule repository, while the module file set and layout stay type-specific. This removes the contradiction with the 'every repository' / 'stand on its own' requirements that had excluded PSModule/docs. Dogfood the standard: add AGENTS.md, CLAUDE.md (@AGENTS.md import), and .github/copilot-instructions.md to PSModule/docs, which previously carried none of the required agent onboarding files.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 00:21
View session
There was a problem hiding this comment.
Pull request overview
Updates the PSModule PowerShell module standards to better preserve README content during standardization, formalize module archetype guidance (integration/API vs data), and establish consistent repository/agent onboarding defaults across repos.
Changes:
- Adds a new “Module types” standards page and links it into the PowerShell Modules nav/index.
- Expands repository defaults to require repo-local governance files plus agent onboarding entrypoints (AGENTS.md / CLAUDE.md / copilot-instructions).
- Refines README and naming guidance (Usage showcase requirement, content preservation rules, REST→verb mapping, data-module verb vocabulary) and tightens the PowerShell support policy to modern-only (min 7.6).
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/zensical.toml | Adds “Module types” to the docs navigation. |
| src/docs/PowerShell/Standard/Naming.md | Adds verb conventions for data modules and integration/API modules. |
| src/docs/PowerShell/Modules/Repository-Defaults.md | Updates README standardization rules + adds agent onboarding and repo self-sufficiency requirements. |
| src/docs/PowerShell/Modules/Module-Types.md | New page defining integration/API vs data module conventions and cross-links. |
| src/docs/PowerShell/Modules/index.md | Links to the new Module-Types page from the Modules landing page. |
| src/docs/PowerShell/index.md | Updates the supported PowerShell version policy (modern-only, min 7.6). |
| CLAUDE.md | Adds Claude entrypoint importing AGENTS.md. |
| AGENTS.md | Adds agent onboarding instructions for this docs repository. |
| .github/copilot-instructions.md | Adds Copilot instructions pointing to AGENTS.md. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ound-trip grammar - Repository-Defaults README validation no longer calls examples/ a published surface; it now aligns with the 'relocate only to a published home' rule (group overview page or comment-based help) and states repository-only locations such as examples/ must still be linked from the README. - Naming.md and Module-Types.md: complete the 'so data round-trips' clause -> 'so data can round-trip between the format and the object model'.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 00:31
View session
…n Naming.md Replace the ambiguous ellipsis in 'Remove-…Entry' with the explicit '<Noun>' placeholder so it matches the verb vocabulary in Module-Types.md and is copy/paste-safe.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 00:34
View session
…> template placeholder The README template uses 'Get-Help -Name <Command> -Examples' and the guidance tells authors to replace <Command>, but the validation Select-String only matched '-Name ''CommandName''' and <CommandName>, so a README shipping <Command> unchanged would pass. Add <Command> to the pattern list.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 08:31
View session
…-modules sentence Removed the commas after GitHub and after Domeneshop; the service-client list is part of the subject, not a parenthetical, so 'GitHub and the service-client modules such as ... are integration modules' now reads correctly.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 08:37
View session
…ble rows 'Read from a file or store into objects' read ambiguously (store-into adjacency). Reworded to 'Read objects from a file or store' to parallel the Export- row 'Write objects to a file or store'.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 12, 2026 08:40
View session
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Updates the module README default in
PowerShell/Modules/Repository-Defaults.mdso that standardizing a README does not delete unique information. The README is published as the module's landing page on the docs site (for examplepsmodule.io/<ModuleName>); the per-command reference is generated separately from comment-based help. So the README is often the only published home for prerequisites, platform/dependency notes, authentication and setup guidance, operational behavior (caching, state, update/versioning), and upstream attribution. Deleting it to shorten the README removes it from the site entirely. ## Changes to the standard - Content preservation (keep / trim / relocate, never drop). Preserve unique content; only remove what is genuinely duplicated by the generated command reference. - Publishing model made explicit. The README publishes as the landing page. Content may move out of the README only into another published home — a command group's overview page undersrc/functions/public/<Group>/<Group>.md, or comment-based help. A bare top-leveldocs/folder is not published, so moving content there drops it from the site. A longer README is acceptable for feature-rich modules; do not shorten by deleting. - Capabilities showcase is mandatory for implemented modules. - Upstream attribution exception. Credit, acknowledgements, donation notes, and third-party license notices are retained. - Fixed the copy/paste-hostile help example and extended README validation. ## Gauge Applied on two content-rich repos so the resulting READMEs can be used to judge the definition: - PSModule/NerdFonts#85 — keeps the full README (prerequisites, attribution, usage, caching, update semantics, uninstall) and adds a Documentation pointer. - PSModule/GitHub#638 — keeps the full README (use-cases, platforms, complete authentication guide incl. Azure Key Vault) and adds a Documentation pointer. Follow-up: apply the definition to the remaining standardization PRs, and syncTemplate-PSModule's README.Round 2 additions (scope expanded)
Following review of all 55 rollout PRs, the standard now also:
Capabilities->Usage(Examplesallowed);Capabilitiesis disallowed and checked in README validation..githubfallback; the README has no## Contributingsection (repo ships a self-containedCONTRIBUTING.md).AGENTS.md/CLAUDE.md(@AGENTS.md) /.github/copilot-instructions.mdpointing toPSModule/docs+MSXOrg/docs(added to required-files tables and Distributor mandatory sets).PowerShell/index.md).Modules/Module-Types.md(integration/API + data modules) andNaming.mdrules: REST-method -> verb mapping;ConvertTo/ConvertFrom+Format/Import/Export;Hashtableas the data-module reference;Contextfor user and module settings.Follow-ups filed as separate issues: framework 5.1-compat rules vs modern-only; Distributor rollout of the new mandatory files; data-module naming conformance (Toml/Hashtable).
Round 3: resolve the scope conflict and adopt the standard here
Resolve the scope contradiction in
Repository-Defaults.md. The Scope section excluded documentation repositories such asPSModule/docs, while the Agent onboarding files and Required common files sections require every repository to carry agent onboarding files and to stand on its own. Scope now states that two baseline expectations — agent onboarding files and repository self-sufficiency — apply to every PSModule repository regardless of type, while the concrete file set and layout on the rest of the page stay module-specific.Dogfood the standard in this repository.
PSModule/docspreviously carried none of the required agent onboarding files. This PR adds them so the repo that defines the standard follows it:AGENTS.md— cross-tool entry point pointing to psmodule.io and the MSX documentation.CLAUDE.md—@AGENTS.mdimport..github/copilot-instructions.md— points toAGENTS.md.Copilot review addressed.
examples/is no longer described as a published surface in the README-validation note (aligned with the "relocate only to a published home" rule), and the data round-trip sentence inNaming.md/Module-Types.mdwas completed.Follow-up (out of scope here): an organization-wide rollout of the agent onboarding files is needed — an audit of the org shows 0/58 module repos and 0/4 docs repos currently carry
AGENTS.mdorCLAUDE.md, and only 1 carries.github/copilot-instructions.md. That rollout should go through Distributor's mandatory file sets as this standard describes.