PowerShell module repository defaults#

This page defines the default repository contract for PowerShell module repositories in the PSModule organization. It describes what a newly created or maintained module repository should look like before module-specific code, tests, documentation, and managed repository files are considered.

The implementation standard still lives in PowerShell module standard. Type-specific conventions for integration (API) and data modules live in Module types. This page covers repository defaults: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.

Scope#

These defaults apply to repositories whose primary artifact is a PowerShell module published through the PSModule framework.

They do not apply directly to:

• GitHub Action repositories such as Build-PSModule, Invoke-Pester, or Publish-PSModule.
• Documentation repositories such as PSModule/docs.
• Template repositories other than Template-PSModule.
• Test, archive, service, or infrastructure repositories that are not published as module artifacts.

Two baseline expectations still apply to every PSModule repository, including the types listed above. Each repository stands on its own: it carries its own governance and community files instead of relying on the organization .github fallback, and each repository ships the agent onboarding files so an agent can work in it without prior context. What differs by type is the concrete file set and layout: the required files, README shape, and framework wiring on the rest of this page are module defaults, and non-module repositories keep only the equivalent baseline appropriate to their own type. This repository, PSModule/docs, follows those two baseline expectations itself.

Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth.

Repository creation#

Create new module repositories from PSModule/Template-PSModule. The template provides the framework wiring, starter layout, and CI/CD expectations.

After creating the repository:

1. Replace template tokens such as {{ NAME }} and {{ DESCRIPTION }}.
2. Remove scaffold functions, tests, and examples that do not represent the module.
3. Set repository metadata and custom properties.
4. Confirm the README answers the start-page questions and uses Install-PSResource for installation.
5. Confirm required common files are present.
6. Confirm .github/PSModule.yml only overrides defaults when the module needs different behavior.

Required repository metadata#

Each module repository should have:

• A concise GitHub repository description that starts with or clearly says A PowerShell module ....
• RepoType: Module as the repository custom property.
• Topics that help users find the module, when relevant.
• Branch protection and workflow requirements inherited from organization defaults.
• main as the default branch unless there is a documented legacy reason.

The repository description is used as a short landing-page summary in documentation and automation. Keep it user-facing and avoid implementation details.

Default branch and worktrees#

Use main for active module repositories. Legacy repositories that still use master should not be used as examples for new work.

Local work should use the organization worktree convention:

• The bare repository stays at the repository root.
• main/ tracks the default branch.
• Feature worktrees use <type>-<slug> directories and <type>/<slug> branches.

For branch and worktree details, see Git Worktrees.

Default repository layout#

Module repositories use the PSModule framework layout:

Detailed source layout rules live in PowerShell module standard.

Required common files#

Every module repository must carry the same baseline community, governance, and automation files. GitHub's organization-level .github community-file fallback is useful for display defaults, but it is not enough as the long-term PSModule standard because:

• agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior;
• tools such as Dependabot, linters, CODEOWNERS, and release automation read repository-local files;
• reviews need diffs against the actual managed file in the target repository;
• repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files;
• central fallback files in PSModule/.github do not provide a reliable enforcement or update workflow across all repositories.

Required baseline files for module repositories:

Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard.

Each repository must stand on its own. It carries its own copy of every file above and does not depend on the organization .github fallback: that fallback is only surfaced in GitHub's web UI, and agents, linters, and local tooling do not read it.

Agent onboarding files#

Every repository must be usable by an agent that has never seen it before, without special configuration. Each repository carries its own agent entry points that point to the authoritative documentation instead of restating it:

• AGENTS.md: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the canonical agent guidance in PSModule/docs.
• CLAUDE.md: a thin file that imports AGENTS.md with @AGENTS.md so Claude Code reads the same instructions. Claude-specific notes, if any, go below the import.
• .github/copilot-instructions.md: repository instructions for VS Code and GitHub Copilot that point to the same documentation.

These files are the agent equivalent of the README: pointers, not copies. Keep them short so the linked documentation stays the single source of truth. Like the other governance files, they live in the repository itself so it can stand on its own.

Managed file distribution#

Shared repository files are managed through PSModule/Distributor. Distributor is the source of truth for managed file content and file-set membership.

Managed-file distribution follows this contract:

• Type maps a repository to its file-set root (for example Module or Action).
• SubscribeTo declares which optional managed file sets the repository receives.
• Organization-wide mandatory file sets define non-optional governance and supply-chain files for each applicable repository type.
• Distributor delivers changes through a managed-files/update branch and a ⚙️ [Maintenance]: Sync managed files pull request.
• Receiving repositories treat managed files as generated artifacts from Distributor. Local edits in the receiving repository are replaced on the next sync and must be made in Distributor instead.
• Removing a file from a file set does not implicitly delete previously synced copies; deletion is an explicit managed change.

This page defines what files must exist in repositories. Distributor defines how those files are distributed and kept aligned.

Migration for existing repositories#

Repositories that still reflect older distribution behavior should be aligned to this contract:

1. Set or correct repository Type and SubscribeTo properties.
2. Ensure mandatory governance and supply-chain files from this standard exist in the repository.
3. Move any intended local edits in managed files into Distributor source file sets.
4. Sync from Distributor and merge the managed-files/update pull request.
5. Remove unmanaged duplicates or stale files explicitly when they are no longer part of an active file set.

After migration, the repository keeps the required files from this standard, and managed-file content changes are made through Distributor-first updates.

Supply-chain defaults#

Every module repository must include .github/dependabot.yml. Dependabot is part of the repository supply-chain control, not an optional convenience.

Module repositories should configure at least:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    labels:
      - "dependencies"
      - "github-actions"

  - package-ecosystem: "powershell"
    directory: "/"
    schedule:
      interval: "weekly"
    labels:
      - "dependencies"
      - "powershell"

The GitHub Actions ecosystem keeps pinned actions current. The PowerShell ecosystem keeps PowerShell dependency declarations current where Dependabot supports them. Repositories with additional package ecosystems should add them explicitly rather than replacing these defaults.

Dependabot PRs still go through normal review. Automated dependency updates are not a substitute for reviewing release notes, changed permissions, pinned SHAs, or generated lockfiles.

README default#

A module README is a start page, not the command reference or full manual. It brings a reader in, answers the first questions, and sends them to the right documentation surface.

Making the README shorter must not delete unique information. The README is published as the module's landing page on the documentation site (for example psmodule.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 and dependency notes, authentication and setup guidance, operational behavior such as caching, state, or update and versioning semantics, and upstream attribution. Trimming the README must preserve that content: keep it on the landing page, or move it only to another surface that also publishes (a command group's overview page under src/functions/public/<Group>/<Group>.md, comment-based help, or published documentation in docs/). Only remove content that is genuinely duplicated by the generated command reference.

The README answers these questions, in this order:

Module installation examples must use PSResourceGet:

Install-PSResource -Name <ModuleName>

Do not use Install-Module in new module repository documentation. Install-Module belongs only in legacy/historical context where changing it would misrepresent the referenced system.

For implemented modules, use this shape:

# <ModuleName>

<One short paragraph describing what the module is and why it is useful.>

## Installation

Install the module from the PowerShell Gallery:

```powershell
Install-PSResource -Name <ModuleName>
Import-Module -Name <ModuleName>
```

## Capabilities

Use this section as a short showcase and introduction to how the module works. Show the most important things the module makes possible with one to three realistic examples.

The goal is discovery and marketing, not exhaustive command documentation. A reader should understand why the module exists and what kind of tasks it helps with.

```powershell
# Replace this with a real example that demonstrates the module's value.
Get-Command -Module <ModuleName>
```

## Documentation

Documentation is published at [psmodule.io/<ModuleName>](https://psmodule.io/<ModuleName>/).

Use PowerShell help and command discovery for module details:

```powershell
Get-Command -Module <ModuleName>
Get-Help -Name <Command> -Examples
```

In the documentation examples, replace <Command> with a real command exported by the module, for example Get-Help -Name Get-GitHubRepository -Examples, so the snippet runs as written. Do not ship placeholder tokens such as 'CommandName' or <CommandName> as if they were runnable commands.

Implemented modules must include the capabilities or usage showcase before the documentation link. Keep it focused on discovery: show one to three representative outcomes, not every command, parameter, or edge case. A landing page with only an installation snippet and a documentation link is not enough for a module that has working commands.

Keep, trim, or relocate content — do not delete it:

• Keep on the landing page: the overview, prerequisites and requirements (PowerShell version, supported platforms, module or native dependencies), installation, the capabilities showcase, and the short operational notes a reader needs before first use.
• Trim: exhaustive command inventories, parameter tables, and repetitive examples that differ only by a parameter. These come from comment-based help — point to Get-Help and the documentation site instead of restating them.
• Relocate only to a published home — never drop: long-form guides and unique conceptual content (authentication and setup walkthroughs, deep operational detail, end-to-end scenarios) may move out of the README only into a surface that is actually published: a command group's overview page under src/functions/public/<Group>/<Group>.md, comment-based help, or published documentation in docs/ or examples/. Only relocate to unpublished areas if there is no published home for it yet; keep the full content in the README to ensure it reaches users. A longer landing page is acceptable and expected for feature-rich modules; do not shorten by deleting.

Retain upstream attribution and licensing context. Credit, acknowledgements, donation notes, and third-party license notices for wrapped or bundled work must stay in the README, or move to a clearly linked place. The rule below about community and policy sections does not apply to attribution the project is expected to carry.

README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help.

Do not add a community-file or policy link section by default. Readers can find standard repository files such as LICENSE, CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md through GitHub conventions and the repository file tree. Link them only when the module has an unusual rule the user must know before using it, or when it carries required upstream attribution.

Placeholder and in-progress repositories#

If a repository is reserved for a future module or still contains scaffold code, say that directly. Do not leave {{ NAME }}, {{ DESCRIPTION }}, PSModuleTemplate, Greet-Entity, or similar template examples in the README.

Use this shape for placeholder repositories:

# <ModuleName>

<One sentence describing what the module is intended to become.>

## Status

This repository is currently a placeholder. The module source still contains scaffold code, so there are no supported commands or usage examples to document yet.

## Documentation

When this module is implemented, command details should live in PowerShell help and generated documentation rather than being duplicated in this README.

Use the same pattern for in-progress modules with stub commands, but name the stub honestly:

This repository is currently in progress. The current `<CommandName>` command is a stub and throws `NotImplementedException`, so there are no supported conversion commands or usage examples to document yet.

README validation#

Before opening a README-only PR, check that the README follows the default and does not contain leftover scaffolding:

Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName'
Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}'
Select-String -Path README.md -SimpleMatch -Pattern '<Command>', '<CommandName>', "-Name 'CommandName'"
Select-String -Path README.md -Pattern '^## (Commands|Capabilities)$'
Select-String -Path README.md -Pattern '^Install-Module\b'
git diff --check -- README.md

Template-PSModule is the exception: it intentionally keeps {{ NAME }} and {{ DESCRIPTION }} tokens because those are template inputs.

For an implemented module, also confirm the README keeps a capabilities or usage showcase and that any unique content removed from the previous version — prerequisites, setup or authentication guidance, operational notes, or upstream attribution — was relocated to docs/, examples/, or comment-based help rather than deleted.

Documentation ownership#

Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail.

Use these defaults:

• Command synopsis, parameters, examples, links, and outputs live in comment-based help.
• Group overview pages live next to public command groups in src/functions/public/<Group>/<Group>.md.
• Realistic end-to-end scenarios live in examples/.
• Product docs beyond generated command help live under docs/ and publish through GitHub Pages or the initiative's module documentation site.
• README capability examples are short, representative, and user-facing.
• README pages stay focused and stable, and keep the narrative content that has no other published home.

This keeps the repository landing page readable and prevents drift between README content, PowerShell help, and generated documentation.

Release and PR defaults#

Module repositories use the Process-PSModule workflow. Version and release behavior is driven by PR labels and workflow settings.

Default expectations:

• Major, Minor, Patch, and Prerelease labels determine release behavior.
• Documentation-only README standardization PRs use the Docs/NoRelease behavior when available.
• Source changes under src/ are module-impacting and should trigger the full module workflow.
• README and documentation changes should update the site without pretending to be module API changes.

See Versioning for semantic version rules and PowerShell module standard for the Process-PSModule pipeline.

Template maintenance#

Template-PSModule defines the default README shape and starter repository contract. When this page changes a default, update Template-PSModule in the same work item when practical.

The template README may contain tokens, but generated module repositories should not keep them after the initial setup commit.