feat: establish guidance chain (AGENTS.md, CONTRIBUTING.md, copilot-instructions.md, slim README) (#32)

## Summary

Establishes the local guidance and onboarding chain for agents and
contributors before any template slimming work happens.

This is PR 1 of a planned multi-PR simplification for
`Template-PSModule`.

## Changes

- **`AGENTS.md`** — OKF-style pointer file with the discovery order:
local README → local CONTRIBUTING → `.github/PSModule.yml` →
PSModule/docs → MSXOrg/docs. Points agents to the canonical guidance in
PSModule/docs and MSXOrg/docs. Does not duplicate any process knowledge.
- **`CLAUDE.md`** — Claude Code entry point that imports `AGENTS.md` so
Claude reads the same instructions.
- **`.github/copilot-instructions.md`** — VS Code / GitHub Copilot entry
point that points to `AGENTS.md`.
- **`CONTRIBUTING.md`** — Self-contained contribution workflow for this
template repository. Covers branching, PR flow, issue format, and code
standards with links to the canonical docs.
- **`README.md`** — Slimmed to describe the template's purpose and the
post-creation checklist. Removes the filled-in module example content
that was misleading for a template repo. Points contributors and agents
to the right places.

## What this does NOT do

This PR does not perform the large repo slimming/deletion work planned
for subsequent PRs.

## Checklist

- [x] AGENTS.md follows the thin-pointer pattern from [Agentic
Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/)
- [x] CLAUDE.md and copilot-instructions.md point back to AGENTS.md, no
duplication
- [x] CONTRIBUTING.md is self-contained and references canonical docs
- [x] README.md describes template purpose only
- [x] Discovery order matches the coordinated plan

---------

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

Author: MariusStorhaug

.github/mkdocs.yml

@@ -27,15 +27,6 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@da180bac16b13bfbcdf08b2e4e221b5b49e5ff28 # v6.1.4
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@fb1bdb8fefd243292f779d2a856a38db6fe6daf4 # v6.1.13
     secrets:
-      APIKEY: ${{ secrets.APIKEY }}
-      TestData: >-
-        {
-          "secrets": {
-            "TEST_SECRET": "${{ secrets.TEST_SECRET }}"
-          },
-          "variables": {
-            "TEST_VARIABLE": "${{ vars.TEST_VARIABLE }}"
-          }
-        }
+      APIKey: ${{ secrets.APIKEY }}

.github/workflows/Process-PSModule.yml

@@ -0,0 +1,64 @@
+[project]
+site_name = "-{{ REPO_NAME }}-"
+repo_name = "-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
+repo_url = "https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
+
+[project.theme]
+variant = "classic"
+language = "en"
+logo = "Assets/icon.png"
+favicon = "Assets/icon.png"
+features = [
+    "navigation.instant",
+    "navigation.instant.progress",
+    "navigation.indexes",
+    "navigation.top",
+    "navigation.tracking",
+    "navigation.expand",
+    "search.suggest",
+    "search.highlight",
+    "content.code.copy"
+]
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+primary = "black"
+accent = "light-blue"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+primary = "black"
+accent = "light-blue"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to system preference"
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+[project.markdown_extensions.toc]
+permalink = true
+
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.md_in_html]
+[project.markdown_extensions.pymdownx.details]
+[project.markdown_extensions.pymdownx.superfences]
+
+[[project.extra.social]]
+icon = "fontawesome/brands/discord"
+link = "https://discord.psmodule.io"
+name = "-{{ REPO_OWNER }}- on Discord"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/-{{ REPO_OWNER }}-/"
+name = "-{{ REPO_OWNER }}- on GitHub"

.github/zensical.toml

@@ -0,0 +1,32 @@
+# Agents
+
+## Main directive
+
+Everything is a work in progress and can be improved.
+If you find a problem or improvement, fix if small; otherwise open an issue.
+
+## Repo guidance
+
+- [`README.md`](README.md) — what this repository is and its purpose as a template.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to contribute to this repository.
+
+## PSModule Framework guidance
+
+Regarding repo structure, module source code and how the Process-PSModule workflow works.
+For PSModule-specific build, layout, and process guidance:
+
+- [Template quickstart](https://psmodule.github.io/docs/Modules/Process-PSModule/template-quickstart/) — how to create a new module from this template.
+- [Repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) — the expected repository layout and required files.
+- [Module anatomy](https://psmodule.github.io/docs/Modules/Process-PSModule/module-anatomy/) — source layout and framework conventions.
+- [Build, test, pack, publish](https://psmodule.github.io/docs/Modules/Process-PSModule/build-test-pack-publish/) — the CI/CD pipeline.
+- [Standards](https://psmodule.github.io/docs/Modules/Standards/) — PowerShell module coding standards.
+- [PSModule/memory](https://github.com/PSModule/memory) — durable cross-session agent working memory for the PSModule organization.
+
+## Org-wide guidance
+
+For cross-cutting ways of working and standards:
+
+- [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) — how agents and humans collaborate in this ecosystem.
+- [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — contribution workflow, branching, PRs, issues.
+- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) — language-level conventions.
+- [MSXOrg/memory](https://github.com/MSXOrg/memory) — durable agent working memory: gotchas, knowledge, and agent role notes.

AGENTS.md

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

CLAUDE.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thank you for contributing to this module.
+Read [`AGENTS.md`](AGENTS.md) first for the full guidance chain and documentation references.
+
+## Before you start
+
+1. Read [`README.md`](README.md) to understand what the module does.
+2. Familiarise yourself with the [repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) that this repository must satisfy.
+3. Check the open issues and pull requests to avoid duplicate work.
+
+## Workflow
+
+This project follows the [MSXOrg contribution workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/):
+
+1. Open or pick up an issue that describes the change.
+2. Create a branch from `main` following the `<type>/<issue>-<short-slug>` convention (e.g. `feat/42-add-security-md`).
+3. Make small, focused commits and push often.
+4. Open a **draft PR** as soon as the change has a basic shape — early feedback is preferred.
+5. Run the **Copilot review loop**: request a Copilot review, address its feedback, and repeat until it reports a clean round. File an issue for any out-of-scope findings rather than expanding the PR.
+6. Mark the PR ready for review and enable auto-merge. It lands automatically once the required checks pass and a reviewer approves.
+
+For branching details, see [Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/).
+
+## Pull requests
+
+- Keep PRs small and focused on a single deliverable.
+- The PR title should follow the [commit conventions](https://msxorg.github.io/docs/Ways-of-Working/Commit-Conventions/).
+
+For PR format guidance, see [PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/).
+
+## Issues
+
+Use GitHub Issues to report bugs, request features, or propose improvements.
+Follow the [issue format](https://msxorg.github.io/docs/Ways-of-Working/Issue-Format/) guidance.
+
+## Code standards
+
+PowerShell in this module follows the [PSModule Standards](https://psmodule.github.io/docs/Modules/Standards/) and the
+[MSXOrg Coding Standards](https://msxorg.github.io/docs/Coding-Standards/).
+
+## Questions
+
+Open a GitHub Discussion or file an issue if something is unclear.

CONTRIBUTING.md

@@ -1,69 +1,29 @@
-# {{ NAME }}
+# Template-PSModule
 
-{{ DESCRIPTION }}
+The canonical starting template for new PowerShell modules in the PSModule organization.
 
-## Prerequisites
-
-This uses the following external resources:
-- The [PSModule framework](https://github.com/PSModule/Process-PSModule) for building, testing and publishing the module.
-
-## Installation
-
-To install the module from the PowerShell Gallery, you can use the following command:
-
-```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
-```
-
-## Usage
-
-Here is a list of example that are typical use cases for the module.
-
-### Example 1: Greet an entity
-
-Provide examples for typical commands that a user would like to do with the module.
+## Purpose
 
-```powershell
-Greet-Entity -Name 'World'
-Hello, World!
-```
+Use this template when creating a new PowerShell module repository.
+It provides the CI/CD framework wiring, required community files, and starter layout that every PSModule module repository needs.
 
-### Example 2
+For step-by-step instructions, see the [template quickstart](https://psmodule.github.io/docs/Modules/Process-PSModule/template-quickstart/).
 
-Provide examples for typical commands that a user would like to do with the module.
+## After creating a repository from this template
 
-```powershell
-Import-Module -Name PSModuleTemplate
-```
+1. Replace the `{{ NAME }}` and `{{ DESCRIPTION }}` placeholders throughout the repository.
+2. Replace the starter function, test, and example with your module's first real command.
+3. Set the repository description and custom properties on GitHub.
+4. Confirm `.github/PSModule.yml` only overrides defaults when your module needs different behavior.
+5. Open a draft pull request and run the full CI pipeline.
 
-### Find more examples
+See [repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) for the full checklist.
 
-To find more examples of how to use the module, please refer to the [examples](examples) folder.
-
-Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
-To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
-
-## Documentation
+## Prerequisites
 
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
+Modules built from this template use the [PSModule framework](https://github.com/PSModule/Process-PSModule) for building, testing, and publishing.
 
 ## Contributing
 
-Coder or not, you can contribute to the project! We welcome all contributions.
-
-### For Users
-
-If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
-product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
-Please see the issues tab on this project and submit a new issue that matches your needs.
-
-### For Developers
-
-If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
-You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
-
-## Acknowledgements
-
-Here is a list of people and projects that helped this project in some way.
+To contribute to this template itself, read the [Contribution guidelines](CONTRIBUTING.md).
+For agents and AI tools, start with [`AGENTS.md`](AGENTS.md).

README.md

@@ -1,19 +1,7 @@
-<#
-  .SYNOPSIS
-    This is a general example of how to use the module.
+<#
+    .SYNOPSIS
+        Basic module usage example.
 #>
 
-# Import the module
-Import-Module -Name 'PSModule'
-
-# Define the path to the font file
-$FontFilePath = 'C:\Fonts\CodeNewRoman\CodeNewRomanNerdFontPropo-Regular.tff'
-
-# Install the font
-Install-Font -Path $FontFilePath -Verbose
-
-# List installed fonts
-Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular'
-
-# Uninstall the font
-Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular' | Uninstall-Font -Verbose
+Import-Module -Name '{{ NAME }}'
+Get-PSModuleTest -Name 'World'