From e1f73125cf3d8082a5d7f50e8f2effd3a8c8d3fd Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 23 Jul 2026 23:14:53 +0200 Subject: [PATCH 1/4] docs: tidy repository onboarding guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 21 +++++++++++++++++++++ src/docs/Modules/Repository-Defaults.md | 18 +++++++++++++++++- 2 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6ca1a01 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing to PSModule/docs + +This repository is the source of truth for PSModule documentation. + +## Before you change docs + +- Read the relevant page in `src/docs/` first. +- Keep changes small and scoped to one topic. +- Prefer links to canonical docs over duplicating guidance. + +## Working in this repository + +- Use the current branch or worktree for the change. +- Keep commit messages short and specific. +- Open draft pull requests early for reviewable doc updates. + +## Review expectations + +- Make wording changes that improve clarity without widening scope. +- Preserve the existing PSModule doc conventions and link patterns. +- If a linked guide is missing, add it here in the repository instead of relying on inheritance. diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index f26135e..8fcf6de 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://github.com/MSXOrg/docs/blob/main/src/docs/Ways-of-Working/Git-Worktrees.md). ## Default repository layout @@ -136,6 +136,22 @@ Every repository must be usable by an agent that has never seen it before, witho - `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. +Copy-pasteable starters: + +```md +# AGENTS + +Follow the canonical agent guidance in [PSModule/docs](https://github.com/PSModule/docs). +``` + +```md +@AGENTS.md +``` + +```md +Follow [AGENTS.md](../AGENTS.md). +``` + 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 From 73d2b142c88374e420a2eac0e3f40756a9975579 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:34:41 +0200 Subject: [PATCH 2/4] docs: drop copilot-specific onboarding copy Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/docs/Modules/Repository-Defaults.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index 8fcf6de..cb3bc10 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -134,7 +134,6 @@ Every repository must be usable by an agent that has never seen it before, witho - `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`](https://github.com/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. Copy-pasteable starters: @@ -148,10 +147,6 @@ Follow the canonical agent guidance in [PSModule/docs](https://github.com/PSModu @AGENTS.md ``` -```md -Follow [AGENTS.md](../AGENTS.md). -``` - 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 From b7069d3a6a278baa2a6c3b283a752455119aa943 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:43:31 +0200 Subject: [PATCH 3/4] docs: point agent starter at template repo 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 cb3bc10..b1c9350 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -140,7 +140,7 @@ Copy-pasteable starters: ```md # AGENTS -Follow the canonical agent guidance in [PSModule/docs](https://github.com/PSModule/docs). +Follow the template repository's agent guidance in [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule). ``` ```md From 35b0b1a75480f09ee70286597ce8e5ac3b6b9b5b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 25 Jul 2026 14:44:17 +0200 Subject: [PATCH 4/4] docs: replace onboarding starter with template link Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/docs/Modules/Repository-Defaults.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index b1c9350..3530bc1 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -135,17 +135,7 @@ Every repository must be usable by an agent that has never seen it before, witho - `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`](https://github.com/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. -Copy-pasteable starters: - -```md -# AGENTS - -Follow the template repository's agent guidance in [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule). -``` - -```md -@AGENTS.md -``` +See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule) for a concrete implementation example of `AGENTS.md` and `CLAUDE.md`. 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.