⚙️ [Maintenance]: Agents can coordinate substantial module work consistently (#533)

Agents and contributors can now coordinate substantial module work
across focused sessions and author reusable PSModule plugin skills with
consistent process guidance.

## New: Module development orchestration skill

The `psmodule-module-development-orchestration` skill guides a parent
session through decomposition, branch selection, child-session handoffs,
review, integration, stop conditions, and report-back. It follows
trunk-based development for existing modules and reserves integration
branches for the documented bootstrap exception.

## New: Plugin skill authoring guidance

The documentation now explains how to write focused plugin skills and
the `psmodule-skill-authoring` skill points authors to that shared
guidance. Common process rules remain linked to the canonical
Process-PSModule and MSX ways of working instead of being duplicated
across skills.

---
<details>
<summary>Technical details</summary>

- Added
`.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md`.
- Added
`.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md`.
- Added `docs/content/guides/writing-plugin-skills.md`.
- Updated `.github/plugin/README.md`, `docs/content/index.md`, and
`docs/zensical.toml` for discoverability.
- Corrected stale MSX documentation paths and verified the live
destinations.
- Kept orchestration and skill-authoring procedures focused on
agent-specific behavior; organization-wide process rules remain linked
to canonical MSX guidance.
- Implementation plan progress: orchestration skill, skill-authoring
guidance, plugin discoverability, documentation navigation,
branch-policy decisions, canonical-link migration, and repository-native
validation guidance are complete; no follow-up implementation work is
included.
- Standards and framework alignment:

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/plugin/**` (Copilot plugin skills and README) | MSX agentic
development and Markdown | Process-PSModule plugin conventions and
orchestration guide | Aligned |
| `docs/content/**`, `docs/zensical.toml` (documentation) | MSX Markdown
and natural-language guidance | Process-PSModule documentation model and
site navigation | Aligned |

- Validation: `git diff --check`, metadata and navigation review, strict
Zensical build, 26 unique MSX URL checks with all responses in the 2xx
range, Analyze, Lint, Lint code base, Build, and CodeQL passed. Publish
was skipped as expected for this draft.
- Issue convergence sweep: this change implements the agent-operational
and skill-authoring portions of the orchestration guidance; no
additional open issues were fully satisfied by the diff.

</details>

<details>
<summary>Relevant issues (or links)</summary>

### Related work

- Depends on #455
- References #482

</details>

---------

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

Author: MariusStorhaug

.github/plugin/README.md

@@ -30,6 +30,14 @@ skill for upgrading Process-PSModule consumer repositories to framework v8.
 It also provides
 [`psmodule-zensical-migration`](./psmodule/skills/psmodule-zensical-migration/SKILL.md)
 for migrating legacy MkDocs sites to the Process-PSModule Zensical design.
+The
+[`psmodule-module-development-orchestration`](./psmodule/skills/psmodule-module-development-orchestration/SKILL.md)
+skill coordinates substantial module work across parent and child sessions
+using the repository's trunk-based development and bootstrap guidance.
+The
+[`psmodule-skill-authoring`](./psmodule/skills/psmodule-skill-authoring/SKILL.md)
+skill keeps plugin skills thin and points shared authoring guidance to the
+documentation site.
 Verify the installation with:
 
 ```console

.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: psmodule-module-development-orchestration
+description: Coordinate substantial PSModule development across a parent session and narrowly scoped child sessions while preserving trunk-based delivery, reviewability, and release readiness.
+---
+
+# Orchestrate substantial PSModule development
+
+Use this skill when a module change needs multiple independent workstreams,
+explicit dependencies, or coordinated integration. First read the repository
+[module development orchestration guide](../../../../../docs/content/guides/module-development-orchestration.md).
+That guide is the source of common user and agent process. This skill adds only
+the session-specific operating contract below.
+
+## Decide and decompose
+
+Keep small, coherent changes in one session. Create a parent/orchestrator
+session when the work crosses capabilities or code, tests, documentation, or
+workflow surfaces; has dependencies; or needs parallel review.
+
+The parent owns the outcome, boundaries, dependency order, shared decisions,
+integration, release readiness, and final report. Give each child one
+reviewable deliverable. Every handoff must include:
+
+- the objective and acceptance evidence;
+- allowed files and explicit exclusions;
+- dependencies, base branch, and PR target;
+- repository-native validation;
+- the parent session or communication channel for report-back.
+
+## Agent operating contract
+
+For an existing module, use a short-lived topic branch from the default branch
+and target the default branch. Use the integration-branch exception only for a
+brand-new module's load-bearing first-release core, as described in the
+[module bootstrap guide](../../../../../docs/content/get-started/module-bootstrap.md).
+Use a stacked PR only for a genuine dependency.
+
+Each child must:
+
+1. Inspect local guidance, the module layout, and the assigned surface before
+   editing.
+2. Stay within the handoff; make adjacent work a new child task.
+3. Open a draft PR early, push small commits, and include the required Copilot
+   co-author trailer in each commit.
+4. Run the validation named in the handoff and record commands and outcomes.
+5. Report the draft PR URL and target, changed and excluded files, validation,
+   decisions or risks, blockers, and follow-up work before requesting
+   integration.
+
+The parent reviews each child diff and acceptance criterion, integrates through
+the normal PR flow, and reruns affected checks after each dependent merge. Do
+not bypass review with a direct default-branch push or modify another session's
+PR or issue without explicit ownership.
+
+Use the PSModule
+[validation before review](../../../../../docs/content/guides/validating-before-review.md)
+guidance and [versioning and releases](../../../../../docs/content/guides/versioning-and-releases.md)
+for the common validation and release-readiness gates. Keep the coordinated PR
+in draft when the integrated result is not ready.
+
+## Stop conditions
+
+Stop and report to the parent instead of guessing when scope, ownership,
+acceptance evidence, branch target, release intent, or a required dependency is
+ambiguous; when validation fails without a known owner; or when integration
+would modify unrelated work. Do not silently expand scope, merge unreviewed
+changes, or claim release readiness.
+
+## References
+
+- [Module development orchestration](../../../../../docs/content/guides/module-development-orchestration.md)
+- [PSModule repository standard](../../../../../docs/content/reference/repository-standard.md)
+- [Structuring your module](../../../../../docs/content/guides/structuring-your-module.md)
+- [MSX Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
+- [MSX Workflow](https://msx.no/docs/Ways-of-Working/Workflow/)
+- [MSX Branching and Merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/)
+- [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/)

.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: psmodule-skill-authoring
+description: Author and maintain thin PSModule plugin skills that keep shared process in documentation and agent-specific behavior in SKILL.md.
+---
+
+# Author PSModule plugin skills
+
+Use this skill when creating or updating a skill in the PSModule plugin. First
+read the shared
+[writing plugin skills guide](../../../../../docs/content/guides/writing-plugin-skills.md);
+it is the source of common authoring, structure, validation, and maintenance
+guidance.
+
+## Agent-specific contract
+
+- Inspect the existing plugin, skill conventions, README, and manifest before
+  editing.
+- Keep common user and repository guidance in the linked documentation. Put
+  only the skill's trigger, agent operating sequence, handoff/report contract,
+  and stop conditions in `SKILL.md`.
+- Preserve the plugin's scope and make adjacent work a separate change.
+- Open a draft PR early, use small commits, and report the PR URL, files,
+  validation, decisions, and blockers to the owning session.
+- Stop and report instead of guessing when the skill boundary, source-of-truth
+  document, plugin ownership, or validation requirement is unclear.

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

@@ -321,4 +321,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

@@ -28,7 +28,7 @@ works. For PSModule-specific build, layout, and process guidance:
 
 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/guides/validating-before-review.md

@@ -5,7 +5,7 @@ description: PSModule-specific validation checks that extend the shared MSXOrg B
 
 # Validating before review
 
-Use this page after scaffolding a module change or implementing a function and before you finish self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msx.no/docs/Agents/implement/) with the PSModule-specific validation checks that module repositories must pass.
+Use this page after scaffolding a module change or implementing a function and before you finish self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msx.no/docs/Ways-of-Working/Workflow-Stages/Implement/) with the PSModule-specific validation checks that module repositories must pass.
 
 Do not repeat the shared workflow here. Follow the shared branch → draft PR → implement → test → self-review loop first, then run this PSModule pass to confirm the change still fits the module's design, documentation, and PowerShell standards.
 
@@ -79,15 +79,15 @@ 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.
 
 ## Where this connects
 
 - [MSX Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build)
-- [MSX Implement guidance](https://msx.no/docs/Agents/implement/)
+- [MSX Implement guidance](https://msx.no/docs/Ways-of-Working/Workflow-Stages/Implement/)
 - [PowerShell module standard](../reference/powershell-module-standard.md)
 - [Module types](../reference/module-types.md)
 - [Structuring your module](structuring-your-module.md)

docs/content/guides/writing-plugin-skills.md

@@ -0,0 +1,94 @@
+---
+title: Writing plugin skills
+description: Design, author, validate, and maintain thin PSModule plugin skills that point to shared documentation.
+---
+
+# Writing plugin skills
+
+Use this guide when creating or changing a skill in the PSModule plugin. A
+skill is an operational entry point for an agent; shared process and policy
+belongs in the documentation structure so people and agents can use the same
+source of truth.
+
+## Keep skills thin
+
+Put common explanations, repository policy, standards, and user-facing
+procedures in the appropriate `docs/content/` page. Keep `SKILL.md` focused on
+the agent-specific information needed to apply that guidance:
+
+- when the skill should be used and when it should not;
+- the agent's operating sequence and required handoffs;
+- explicit stop conditions and escalation boundaries;
+- the repository-specific validation and report-back contract.
+
+The skill should link to the shared guide near its beginning. Do not copy
+organization-wide MSX rules, module standards, or long tutorials into the
+skill. Link to the canonical source instead.
+
+## Skill structure
+
+Create one directory per skill:
+
+```text
+.github/plugin/<plugin-name>/skills/<skill-name>/
+└── SKILL.md
+```
+
+Use lowercase, descriptive, hyphen-separated identifiers. Start `SKILL.md`
+with front matter containing the matching `name` and a concise `description`.
+The description should make the skill discoverable without embedding the full
+procedure.
+
+After the front matter, include:
+
+1. a short purpose statement and the link to the shared documentation;
+2. agent-specific operating instructions;
+3. explicit stop conditions;
+4. references to related repository and canonical MSX guidance.
+
+Prefer short imperative instructions, checklists, and handoff fields over
+background material. Do not include stale vendor-specific model recommendations
+or obsolete tool instructions. If a procedure changes for both users and
+agents, update the documentation guide first and reduce the skill to a pointer
+plus the remaining agent contract.
+
+## Plugin integration
+
+Inspect the existing plugin before editing. Preserve its `plugin.json`
+metadata and directory conventions. Add the new skill to the plugin README's
+discoverability list with a repository-relative link. Do not add a second
+manifest or duplicate marketplace registration for an individual skill.
+
+Keep the skill's scope explicit. If it coordinates child sessions or other
+agents, define the parent owner, child boundary, expected handoff, validation,
+report-back, and stop conditions. Do not silently broaden a skill into
+unrelated repository work.
+
+## Validation
+
+Run the smallest existing checks that cover the changed surfaces:
+
+- `git diff --check`;
+- repository Markdown and natural-language lint when available;
+- plugin and marketplace metadata parsing;
+- `zensical build --clean` when documentation or navigation changes.
+
+Review every relative link from the skill and guide, the final plugin README
+entry, and the diff for duplicated policy, stale instructions, accidental
+generated files, or unrelated changes. Report the draft PR URL, files changed,
+validation outcomes, policy decisions, and blockers to the owning session.
+
+## Maintenance rule
+
+When shared process changes, update the documentation page and its navigation,
+then make each dependent skill point to the revised source. When only an
+agent-specific trigger, handoff, stop condition, or tool boundary changes,
+update the skill without duplicating the common documentation.
+
+## References
+
+- [PSModule process plugin](https://github.com/PSModule/Process-PSModule/tree/main/.github/plugin)
+- [MSX Agentic Development](https://msx.no/docs/Capabilities/agentic-development/)
+- [MSX Documentation Model](https://msx.no/docs/Ways-of-Working/Documentation-Model/)
+- [MSX Markdown standard](https://msx.no/docs/Coding-Standards/Markdown/)
+- [MSX Natural Language standard](https://msx.no/docs/Coding-Standards/Natural-Language/)

docs/content/index.md

@@ -44,6 +44,7 @@ Task-oriented deep dives into the pipeline's functionality.
 | [Skipping framework tests](guides/skipping-framework-tests.md) | Skip individual framework tests on a per-file basis. |
 | [Versioning and releases](guides/versioning-and-releases.md) | Label-driven versioning, prereleases, and what a release produces. |
 | [Validating before review](guides/validating-before-review.md) | The PSModule validation pass before a draft pull request is marked ready. |
+| [Writing plugin skills](guides/writing-plugin-skills.md) | Author and maintain thin plugin skills that point to shared documentation. |
 | [Module development orchestration](guides/module-development-orchestration.md) | Coordinate substantial work across an orchestrator session and narrowly scoped child sessions. |
 
 ## Reference
@@ -89,4 +90,4 @@ Cross-org standards and reusable solution documentation are now canonical in [MS
 
 - [Coding Standards](https://msx.no/docs/Coding-Standards/)
 - [Capabilities](https://msx.no/docs/Capabilities/)
-- [Frameworks](https://msx.no/docs/Frameworks/)
+- [Frameworks](https://msx.no/docs/Capabilities/)

docs/content/reference/repository-standard.md

@@ -175,7 +175,7 @@ See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule)
 
 `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.
+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/Capabilities/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.
 
 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.
 

docs/zensical.toml

@@ -33,6 +33,7 @@ nav = [
     {"Skipping framework tests" = "guides/skipping-framework-tests.md"},
     {"Versioning and releases" = "guides/versioning-and-releases.md"},
     {"Validating before review" = "guides/validating-before-review.md"},
+    {"Writing plugin skills" = "guides/writing-plugin-skills.md"},
     {"Module development orchestration" = "guides/module-development-orchestration.md"},
   ]},
   {"Reference" = [