Skip to content

Commit 828fe3a

Browse files
Resolve module-scope conflict; adopt agent onboarding files in docs repo
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.
1 parent cbf0b5d commit 828fe3a

4 files changed

Lines changed: 23 additions & 0 deletions

File tree

.github/copilot-instructions.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Follow the instructions in [AGENTS.md](../AGENTS.md).

AGENTS.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Agents
2+
3+
This repository holds the source for the [PSModule](https://psmodule.io) documentation, published at [psmodule.io/docs](https://psmodule.io/docs). Everything an agent needs to work here is documentation — read it the same way a new contributor would.
4+
5+
## Start here
6+
7+
1. Read this file, then the [README](README.md) for what this repository is and how it builds.
8+
2. Read the [PSModule documentation](https://psmodule.io/docs) for the framework's why, how, and what — its standards, conventions, and style guides. The source for those pages lives under `src/docs/` in this repository.
9+
3. Read the [MSX documentation](https://msxorg.github.io/docs) for the organization-level principles and ways of working that sit above any single repository.
10+
11+
## Working in this repository
12+
13+
- Documentation pages live under `src/docs/`; the published site navigation is defined in `src/zensical.toml`. Add a new page to both.
14+
- The PowerShell standards and style guides under `src/docs/` are the source of truth for content changes — follow the page you are changing.
15+
- Keep each page the single source of truth: link to the canonical page instead of restating its content elsewhere.
16+
17+
## The rule
18+
19+
This file points; it never defines. Standards and process live in the documentation and are referenced by their canonical location — never copied here.

CLAUDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

src/docs/PowerShell/Modules/Repository-Defaults.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ They do not apply directly to:
1515
- Template repositories other than `Template-PSModule`.
1616
- Test, archive, service, or infrastructure repositories that are not published as module artifacts.
1717

18+
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](#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.
19+
1820
Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth.
1921

2022
## Repository creation

0 commit comments

Comments
 (0)