Reference canonical repository files without duplication

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.claude/CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD041 -->
+@../AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD041 -->
+Follow the instructions in [AGENTS.md](../AGENTS.md).

.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md

@@ -200,4 +200,4 @@ workflow validation.
 - [Pester v6 quick start](https://pester.dev/docs/v6/quick-start)
 - [Pester `New-PesterConfiguration` command](https://pester.dev/docs/commands/New-PesterConfiguration)
 - [Pester `Invoke-Pester` command](https://pester.dev/docs/commands/Invoke-Pester)
-- [MSX PR format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/)
+- [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/)

AGENTS.md

@@ -17,10 +17,10 @@ works. For PSModule-specific build, layout, and process guidance:
 
 - [Process-PSModule docs](https://psmodule.io/Process-PSModule/) —
   repository structure, module anatomy, and the build/test/pack/publish pipeline.
-- [Repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) —
+- [Repository standard](https://psmodule.io/Process-PSModule/reference/repository-standard/) —
   the expected repository layout and required files.
-- [Standards](https://psmodule.github.io/docs/Modules/Standards/) — PowerShell module
-  coding standards.
+- [PowerShell module standard](https://psmodule.io/Process-PSModule/reference/powershell-module-standard/) —
+  PowerShell module coding standards.
 - [PSModule/memory](https://github.com/PSModule/memory) — durable cross-session agent
   working memory for the PSModule organization.
 
@@ -36,7 +36,7 @@ audit or migration skills.
 
 For cross-cutting ways of working and standards:
 
-- [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) —
+- [Agentic Development](https://msx.no/docs/Capabilities/agentic-development/) —
   how agents and humans collaborate in this ecosystem.
 - [Ways of Working](https://msx.no/docs/Ways-of-Working/) — contribution
   workflow, branching, PRs, issues.

docs/content/get-started/repository-setup.md

@@ -29,51 +29,15 @@ If you plan to create many modules, use a glob pattern for the API key permissio
 
 ## 3. Add the caller workflow
 
-Create `.github/workflows/Process-PSModule.yml` in the module repository:
-
-```yaml
-name: Process-PSModule
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '0 0 * * *'
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-    types:
-      - closed
-      - opened
-      - reopened
-      - synchronize
-      - labeled
-      - unlabeled
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: false
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
-    secrets:
-      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
-      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
-      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
-```
-
-Every permission in that block is required. GitHub App installation tokens perform repository writes. A push to `main` publishes a stable release after the full pipeline passes;
-the pull-request trigger handles CI, prereleases, and prerelease cleanup. See
-[Workflow inputs](../reference/workflow-inputs.md) for what each permission is used for, and
-[Calling the workflow](../guides/calling-the-workflow.md) for passing test secrets and variables.
+Keep the
+[canonical caller workflow](https://github.com/PSModule/Template-PSModule/blob/main/.github/workflows/Process-PSModule.yml)
+from `Template-PSModule`. Do not reconstruct it from a documentation example.
+The template owns its triggers, concurrency, permissions, secrets, and
+Process-PSModule major-version reference.
+
+See [Workflow inputs](../reference/workflow-inputs.md) for the reusable
+workflow contract and [Calling the workflow](../guides/calling-the-workflow.md)
+for supported `TestData` customization.
 
 ## 4. Add the settings file
 

docs/content/guides/calling-the-workflow.md

@@ -5,65 +5,27 @@ description: How to call the Process-PSModule reusable workflow — the caller w
 
 # Calling the workflow
 
-To use the workflow, create a new file in the `.github/workflows` directory of the module repository and add the following content.
+Use
+[`Template-PSModule/.github/workflows/Process-PSModule.yml`](https://github.com/PSModule/Template-PSModule/blob/main/.github/workflows/Process-PSModule.yml)
+as the caller workflow. Copy the complete file instead of reconstructing it
+from documentation snippets. The template owns its triggers, concurrency,
+permissions, standard secrets, and controlled `@v8` reference.
+
 For documentation site generation, keep the canonical
 `Template-PSModule/.github/zensical.toml`; Process-PSModule resolves it into the
 staged site's `zensical.toml`.
 
 For the exact inputs, secrets, and permissions the reusable workflow declares, see
 [Workflow inputs](../reference/workflow-inputs.md).
 
-<details>
-<summary>Workflow suggestion</summary>
-
-```yaml
-name: Process-PSModule
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '0 0 * * *'
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-    types:
-      - closed
-      - opened
-      - reopened
-      - synchronize
-      - labeled
-      - unlabeled
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: false
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
-    secrets:
-      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
-      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
-      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
-```
-
-</details>
-
 Stable releases are evaluated from a push to the default branch. A merged pull request supplies its version label and
 release notes; a direct default-branch push or a manual dispatch uses the default `Patch` bump and commit-based notes.
 Keep the `pull_request` trigger for CI, prereleases, and prerelease cleanup.
 
-The concurrency key keeps a pull request distinct from a default-branch push, so the close-event cleanup and the
-resulting stable release do not serialize as one run. Keep `cancel-in-progress: false`: a release-capable run mutates
-the PowerShell Gallery, GitHub Releases, and tags, so later runs must queue rather than interrupt it.
+The template's concurrency key keeps a pull request distinct from a
+default-branch push. It cancels superseded pull-request validation while
+allowing release-capable branch runs to finish because they can mutate the
+PowerShell Gallery, GitHub Releases, and tags.
 The reusable workflow uses its own prefixed concurrency group, so it cannot queue behind the caller while the caller
 waits for it to finish.
 

docs/content/guides/structuring-your-module.md

@@ -27,6 +27,8 @@ The goal is a stable repository anatomy so both humans and automation know exact
 
 ```plaintext
 <ModuleName>/
+├── .claude/
+│   └── CLAUDE.md                               # Claude Code route to AGENTS.md
 ├── .github/                                   # Workflow config, doc/site templates, automation policy
 │   ├── linters/                               # Rule sets applied by shared lint steps
 │   │   ├── .markdown-lint.yml                 # Markdown rules enforced via super-linter
@@ -37,6 +39,7 @@ The goal is a stable repository anatomy so both humans and automation know exact
 │   ├── CODE_OF_CONDUCT.md                      # Community participation rules
 │   ├── CODEOWNERS                             # Default reviewers enforced by Process-PSModule checks
 │   ├── CONTRIBUTING.md                         # Repository-local contribution workflow
+│   ├── copilot-instructions.md                 # Copilot route to AGENTS.md
 │   ├── dependabot.yml                         # Dependency update cadence handled by GitHub
 │   ├── PSModule.yml                           # Settings parsed to drive matrices
 │   ├── release.yml                            # Release automation template invoked on publish
@@ -54,6 +57,7 @@ The goal is a stable repository anatomy so both humans and automation know exact
 │   └── <ModuleName>.Tests.ps1                 # Simple: one root-level module suite
 ├── .gitattributes                             # Normalizes line endings across platforms
 ├── .gitignore                                 # Excludes build artifacts from source control
+├── AGENTS.md                                  # Cross-client agent guidance router
 ├── LICENSE                                    # License text surfaced in manifest metadata
 └── README.md                                  # Repository overview rendered on GitHub and docs landing
 ```

docs/content/guides/validating-before-review.md

@@ -78,7 +78,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR 
    Check:
 
    - naming, documentation, error handling, testing expectations, and security posture align with the relevant pages under [MSX Coding Standards](https://msx.no/docs/Coding-Standards/)
-   - the change follows the shared "written once, referenced everywhere" rule by linking canonical guidance instead of copying it into local docs or code comments, as described in [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/)
+   - the change follows the shared "written once, referenced everywhere" rule by linking canonical guidance instead of copying it into local docs or code comments, as described in [Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
    - the draft PR description, issue progress, and any follow-up issues reflect what actually shipped and what still belongs out of scope
 
    This is the last author-side gate before a PSModule draft PR is ready for independent review.

docs/content/reference/repository-standard.md

@@ -92,7 +92,8 @@ Module repositories use the PSModule framework layout:
 | `.github/SUPPORT.md` | Support expectations and where users ask for help. |
 | `.github/CODE_OF_CONDUCT.md` | Community conduct expectations. |
 | `AGENTS.md` | Agent onboarding entry point. Points agents to the canonical guidance at `https://psmodule.io/Process-PSModule/`. |
-| `CLAUDE.md` | Claude Code entry point. Imports `AGENTS.md` so Claude reads the same instructions. |
+| `.claude/CLAUDE.md` | Claude Code entry point. Imports the root `AGENTS.md`. |
+| `.github/copilot-instructions.md` | Route for Copilot surfaces that do not read `AGENTS.md` directly. |
 | `.github/PSModule.yml` | Module workflow configuration overrides. |
 | `.github/workflows/Process-PSModule.yml` | Caller workflow that runs the module's CI/CD by calling the shared Process-PSModule workflow. |
 | `.github/zensical.toml` | Canonical generated-site configuration copied from `Template-PSModule`. |
@@ -125,19 +126,16 @@ The module repository owns a caller workflow; the framework owns the reusable wo
 | Caller workflow | The module repository | `.github/workflows/Process-PSModule.yml` |
 | Reusable workflow | [`PSModule/Process-PSModule`](https://github.com/PSModule/Process-PSModule) | `.github/workflows/workflow.yml` |
 
-The caller workflow declares the triggers, concurrency, and permissions for the module repository, and delegates the work:
+The caller workflow declares the triggers, concurrency, and permissions for the
+module repository, then delegates the work. Copy
+[`Template-PSModule/.github/workflows/Process-PSModule.yml`](https://github.com/PSModule/Template-PSModule/blob/main/.github/workflows/Process-PSModule.yml)
+instead of maintaining another example here.
 
-```yaml
-jobs:
-  Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@<commit-sha> # <version tag>
-    secrets:
-      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
-      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
-      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
-```
-
-Name the caller file `Process-PSModule.yml`, matching [`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule) and every existing module repository. `workflow.yml` is the reusable workflow's own filename inside `PSModule/Process-PSModule` and belongs only in the `uses:` reference. Pin the reference to a commit SHA with the version tag in a trailing comment so Dependabot can update it.
+Name the caller file `Process-PSModule.yml`. `workflow.yml` is the reusable
+workflow's own filename inside `PSModule/Process-PSModule` and belongs only in
+the `uses:` reference. Process-PSModule is initiative-owned automation with a
+controlled release process, so the template uses the floating `@v8` major
+reference permitted by the MSX GitHub Actions standard.
 
 ## Required common files
 
@@ -160,7 +158,8 @@ Required baseline files for module repositories:
 | `.github/SUPPORT.md` | Support channel and issue-routing expectations. |
 | `.github/CODE_OF_CONDUCT.md` | Community participation rules. |
 | `AGENTS.md` | Cross-tool agent instructions pointing to the canonical guidance at `https://psmodule.io/Process-PSModule/`. |
-| `CLAUDE.md` | Claude Code entry point that imports `AGENTS.md`. |
+| `.claude/CLAUDE.md` | Claude Code entry point that imports the root `AGENTS.md`. |
+| `.github/copilot-instructions.md` | Route to `AGENTS.md` for Copilot surfaces that need their own filename. |
 | `.github/dependabot.yml` | Configures ecosystem-appropriate dependency-update pull requests. For PowerShell module repositories the `github-actions` ecosystem is expected; add any other ecosystems the module actually develops in. |
 | `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. |
 | `.github/pull_request_template.md` | Scaffolds pull requests in the MSX PR Format (PR Manager) style — an icon + change-type + user-facing-outcome title, user-facing description sections, an optional technical-details block, and a related-issues block. |
@@ -185,13 +184,25 @@ community health 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 at [psmodule.io/Process-PSModule](https://psmodule.io/Process-PSModule/).
-- `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.
-
-See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule) for a concrete implementation example of `AGENTS.md` and `CLAUDE.md`.
-
-`AGENTS.md` and `CLAUDE.md` are the required set. `AGENTS.md` is the entry point that AGENTS.md-aware runtimes read directly, so a repository is usable by an agent without a per-runtime copy of the same pointer.
-
-Runtime-specific adapter files such as `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` are optional. MSX treats them as client adapters that *may* add runtime-specific loading or path rules, described in [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) and its [capability specification](https://msx.no/docs/Capabilities/agentic-development/spec/). Add one when a runtime needs loading or path rules that `AGENTS.md` cannot express, and keep it pointing at `AGENTS.md` rather than restating it. `Template-PSModule` ships without one.
+- `.claude/CLAUDE.md`: a thin file that imports the root router with
+  `@../AGENTS.md`.
+- `.github/copilot-instructions.md`: a thin link to `../AGENTS.md` for Copilot
+  surfaces that do not read the root router directly.
+
+See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule)
+for the concrete implementation.
+
+`AGENTS.md`, `.claude/CLAUDE.md`, and
+`.github/copilot-instructions.md` are the required set. `AGENTS.md` is the
+entry point that AGENTS.md-aware runtimes read directly.
+
+Additional runtime-specific adapters and
+`.github/instructions/*.instructions.md` are optional. MSX treats them as
+client routes or path-scoped caveats, described in
+[Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
+and its
+[capability specification](https://msx.no/docs/Capabilities/agentic-development/spec/).
+Keep routes pointing at `AGENTS.md` rather than restating it.
 
 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.