From 2b54f30b91a9dc2ddb28149ffff9dafa73343a72 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:36:06 +0200 Subject: [PATCH 1/3] Add CONTRIBUTING.md so AGENTS.md link resolves Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..72a6a59 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing + +Thanks for helping improve the PSModule documentation. Everything here is a work in progress — if you find a +problem, fix it if it's small, or open an issue if it needs more discussion. + +## Repository layout + +- `src/docs/`: the documentation source, built as a [Zensical](https://zensical.org/) site. +- `src/includes/`, `src/overrides/`: shared snippets and theme customizations for the site. +- `src/zensical.toml`: site configuration and navigation. +- `guidance/`: example PowerShell snippets referenced from the docs. + +## Making changes + +1. Create a worktree/branch for your change (see [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/)). +2. Edit the relevant page(s) under `src/docs/`. Update `src/zensical.toml` navigation if you add or move a page. +3. Open a draft pull request early and push small, incremental commits so the change is easy to review. +4. Merge to `main` once review passes. The `Docs` workflow (`.github/workflows/Docs.yml`) builds and publishes the + site to GitHub Pages on every merge to `main`. + +## Building and previewing locally + +```powershell +pip install zensical +cd src +zensical build --clean +``` + +The built site is written to `src/site/`. See the [Zensical docs](https://zensical.org/docs/setup/basics/) for +live-reloading preview options. + +## Linting + +Pull requests are linted with [super-linter](https://github.com/super-linter/super-linter) via the `Docs` workflow. +Keep Markdown changes consistent with the surrounding style and fix any linter findings reported on the PR. From 59ffc921f75974a3e563695ae95bbeb803b86334 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:36:14 +0200 Subject: [PATCH 2/3] Fix broken Ways-of-Working relative link in Repository-Defaults Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/docs/Modules/Repository-Defaults.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index f26135e..06d4e27 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -54,7 +54,7 @@ Local work should use the organization worktree convention: - `main/` tracks the default branch. - Feature worktrees use `-` directories and `/` branches. -For branch and worktree details, see [Git Worktrees](../../Ways-of-Working/Git-Worktrees.md). +For branch and worktree details, see [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/). ## Default repository layout From 05595106bbb15280040f67d7ad4e7f477e82aa51 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:36:29 +0200 Subject: [PATCH 3/3] Add copy-pasteable AGENTS.md/CLAUDE.md/copilot-instructions.md examples Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/docs/Modules/Repository-Defaults.md | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index 06d4e27..963cd6a 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -138,6 +138,34 @@ Every repository must be usable by an agent that has never seen it before, witho 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. +### Example + +`AGENTS.md`: + +```markdown +# Agents + +This repository is a PowerShell module built with the [PSModule](https://github.com/PSModule) framework. + +- Read this repository's own [README](README.md) and [CONTRIBUTING](CONTRIBUTING.md) first. +- For module layout, build/test/pack/publish behavior, and repository conventions, see + [PSModule/docs](https://psmodule.io/docs/), starting with + [Process-PSModule](https://psmodule.io/docs/Modules/Process-PSModule/). +- For org-wide coding standards and ways of working, see [MSXOrg/docs](https://msxorg.github.io/docs/). +``` + +`CLAUDE.md`: + +```markdown +@AGENTS.md +``` + +`.github/copilot-instructions.md`: + +```markdown +Follow the instructions in [AGENTS.md](../AGENTS.md). +``` + ## Managed file distribution Shared repository files are managed through [`PSModule/Distributor`](https://github.com/PSModule/Distributor). Distributor is the source of truth for managed file content and file-set membership.