From 1b56a597345a3b65af4e5bd531f522e878268bea Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:00:08 +0200 Subject: [PATCH 1/6] feat: add module development orchestration skill Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/plugin/README.md | 4 + .../SKILL.md | 137 ++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 .github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md diff --git a/.github/plugin/README.md b/.github/plugin/README.md index 5b0f9e43..91239f6d 100644 --- a/.github/plugin/README.md +++ b/.github/plugin/README.md @@ -30,6 +30,10 @@ 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. Verify the installation with: ```console diff --git a/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md new file mode 100644 index 00000000..b3bb8da1 --- /dev/null +++ b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md @@ -0,0 +1,137 @@ +--- +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 is large enough to need several independent +workstreams, explicit dependencies, or coordinated review. Use the repository +[module development orchestration guide](../../../../../docs/content/guides/module-development-orchestration.md) +as the detailed process reference. Do not copy organization-wide rules into +this skill; follow the canonical [MSX Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/), +[Workflow](https://msx.no/docs/Ways-of-Working/Workflow/), and +[Branching and Merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/) +guidance. + +## Decide whether coordination is warranted + +Coordinate through a parent session when the work has two or more genuinely +independent deliverables, crosses code/tests/documentation/workflow boundaries, +has dependencies that need an explicit order, or needs parallel review and +integration. Keep the work in one session when it is a small change, a single +coherent function, a focused documentation correction, or a change one agent +can implement and validate without handoffs. + +Before splitting work, inspect the repository README, local agent guidance, +module layout, relevant tests, workflow, documentation, and existing +validation commands. Establish the requested outcome, constraints, acceptance +evidence, and files that are in scope. + +## Decompose and hand off + +The parent/orchestrator owns the overall outcome, scope, dependency order, +integration decisions, release readiness, and final report. Decompose by +coherent deliverable rather than by arbitrary file count. Each child handoff +must state: + +- the narrow objective and acceptance criteria; +- the allowed files and the files it must not change; +- dependencies and the expected branch/PR target; +- repository-native validation to run; +- the expected report-back format, including changed files, validation, + decisions, blockers, and draft PR URL. + +Children own their assigned deliverable end to end: inspect before editing, +open a draft PR early, use small commits with the required Copilot co-author +trailer, validate their scope, and report back. A child must stop and notify +the parent when requirements conflict, its scope expands, a dependency is +missing, validation exposes an unrelated failure, or the requested branch +target is unclear. It must not silently absorb adjacent work. + +## Branch and pull-request policy + +For an existing module, use trunk-based development by default: + +1. Create a short-lived topic branch from the default branch. +2. Open a draft PR targeting the default branch as soon as the first coherent + increment is pushed. +3. Keep independent child PRs separate and merge them through normal review. +4. Use a stacked PR only when a real dependency makes a separate target branch + necessary, and follow the canonical MSX stacked-PR procedure. + +Do not create a long-lived integration branch for ordinary feature work. The +only exception is a brand-new module with no usable release whose +load-bearing core has not landed. In that bootstrap case, use the +[module bootstrap guide](../../../../../docs/content/get-started/module-bootstrap.md): +keep one narrowly scoped integration branch for the core, let focused child +PRs target it, and open the integration PR to the default branch when the core +is coherent. Once the first release is on the default branch, return to the +ordinary trunk-based policy. + +Never target an existing documentation PR, issue, or unrelated worktree +instead of the agreed branch. Do not merge, close, retarget, or modify another +session's PR or issue without explicit ownership from the parent. + +## Integrate and review + +The parent reviews each child PR against its acceptance criteria and the +repository contract before integration. Confirm that: + +- the child diff stays within its handoff and preserves unrelated behavior; +- dependent work is integrated in dependency order; +- tests, lint, build/package, workflow, and documentation changes are wired + together rather than merely passing in isolation; +- generated files, permissions, release labels, and public module behavior + receive deliberate review. + +Merge through the agreed PR flow; do not bypass review with direct default +branch pushes. After each merge, refresh dependent branches and rerun affected +checks before integrating the next dependent change. Resolve conflicts by +preserving the repository's current source of truth, not by taking whichever +branch happens to be newer. + +## Validate and assess release readiness + +Use the repository's own commands and local guidance. At minimum, run the +smallest relevant checks for the changed surface, then escalate when results +show a broader dependency: + +- build the module and run the affected Pester tests; +- run the repository's PSScriptAnalyzer/lint and workflow validation; +- build documentation when documentation or navigation changed; +- review the final diff, PR checks, public exports, version/release labels, and + required artifacts. + +Apply the PSModule +[validation before review](../../../../../docs/content/guides/validating-before-review.md) +checklist. A change is release-ready only when all child work is integrated, +required checks are green or explicitly blocked and owned, documentation and +tests match the delivered behavior, and the release intent follows +[versioning and releases](../../../../../docs/content/guides/versioning-and-releases.md). +For a bootstrap integration branch, release readiness means the minimum +load-bearing core is coherent; do not expand the exception to unrelated v1 +features. + +## Report back and stop + +The parent report must include the draft PR URL, files changed, commits, +validation commands and outcomes, policy decisions (especially branch target +and any bootstrap exception), unresolved blockers, and the next integration +step. The parent should not mark the work complete or the PR ready for review +until every child has reported and the combined result has passed the +repository-native validation and review gates. + +Stop instead of guessing when scope, ownership, branch target, release intent, +or acceptance evidence is ambiguous; when a required dependency or credential +is unavailable; when validation fails without an understood owner; or when +integration would modify unrelated work. Record the blocker and return control +to the parent. + +## 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 PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) +- [MSX Implement guidance](https://msx.no/docs/Agents/implement/) From 99fd20c6557b43d43f5034edeac6de0a8187b3ab Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:04:37 +0200 Subject: [PATCH 2/6] docs: keep orchestration skill focused Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../SKILL.md | 184 ++++++------------ 1 file changed, 62 insertions(+), 122 deletions(-) diff --git a/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md index b3bb8da1..8119c031 100644 --- a/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md +++ b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md @@ -5,133 +5,73 @@ description: Coordinate substantial PSModule development across a parent session # Orchestrate substantial PSModule development -Use this skill when a module change is large enough to need several independent -workstreams, explicit dependencies, or coordinated review. Use the repository -[module development orchestration guide](../../../../../docs/content/guides/module-development-orchestration.md) -as the detailed process reference. Do not copy organization-wide rules into -this skill; follow the canonical [MSX Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/), -[Workflow](https://msx.no/docs/Ways-of-Working/Workflow/), and -[Branching and Merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/) -guidance. - -## Decide whether coordination is warranted - -Coordinate through a parent session when the work has two or more genuinely -independent deliverables, crosses code/tests/documentation/workflow boundaries, -has dependencies that need an explicit order, or needs parallel review and -integration. Keep the work in one session when it is a small change, a single -coherent function, a focused documentation correction, or a change one agent -can implement and validate without handoffs. - -Before splitting work, inspect the repository README, local agent guidance, -module layout, relevant tests, workflow, documentation, and existing -validation commands. Establish the requested outcome, constraints, acceptance -evidence, and files that are in scope. - -## Decompose and hand off - -The parent/orchestrator owns the overall outcome, scope, dependency order, -integration decisions, release readiness, and final report. Decompose by -coherent deliverable rather than by arbitrary file count. Each child handoff -must state: - -- the narrow objective and acceptance criteria; -- the allowed files and the files it must not change; -- dependencies and the expected branch/PR target; -- repository-native validation to run; -- the expected report-back format, including changed files, validation, - decisions, blockers, and draft PR URL. - -Children own their assigned deliverable end to end: inspect before editing, -open a draft PR early, use small commits with the required Copilot co-author -trailer, validate their scope, and report back. A child must stop and notify -the parent when requirements conflict, its scope expands, a dependency is -missing, validation exposes an unrelated failure, or the requested branch -target is unclear. It must not silently absorb adjacent work. - -## Branch and pull-request policy - -For an existing module, use trunk-based development by default: - -1. Create a short-lived topic branch from the default branch. -2. Open a draft PR targeting the default branch as soon as the first coherent - increment is pushed. -3. Keep independent child PRs separate and merge them through normal review. -4. Use a stacked PR only when a real dependency makes a separate target branch - necessary, and follow the canonical MSX stacked-PR procedure. - -Do not create a long-lived integration branch for ordinary feature work. The -only exception is a brand-new module with no usable release whose -load-bearing core has not landed. In that bootstrap case, use the -[module bootstrap guide](../../../../../docs/content/get-started/module-bootstrap.md): -keep one narrowly scoped integration branch for the core, let focused child -PRs target it, and open the integration PR to the default branch when the core -is coherent. Once the first release is on the default branch, return to the -ordinary trunk-based policy. - -Never target an existing documentation PR, issue, or unrelated worktree -instead of the agreed branch. Do not merge, close, retarget, or modify another -session's PR or issue without explicit ownership from the parent. - -## Integrate and review - -The parent reviews each child PR against its acceptance criteria and the -repository contract before integration. Confirm that: - -- the child diff stays within its handoff and preserves unrelated behavior; -- dependent work is integrated in dependency order; -- tests, lint, build/package, workflow, and documentation changes are wired - together rather than merely passing in isolation; -- generated files, permissions, release labels, and public module behavior - receive deliberate review. - -Merge through the agreed PR flow; do not bypass review with direct default -branch pushes. After each merge, refresh dependent branches and rerun affected -checks before integrating the next dependent change. Resolve conflicts by -preserving the repository's current source of truth, not by taking whichever -branch happens to be newer. - -## Validate and assess release readiness - -Use the repository's own commands and local guidance. At minimum, run the -smallest relevant checks for the changed surface, then escalate when results -show a broader dependency: - -- build the module and run the affected Pester tests; -- run the repository's PSScriptAnalyzer/lint and workflow validation; -- build documentation when documentation or navigation changed; -- review the final diff, PR checks, public exports, version/release labels, and - required artifacts. - -Apply the PSModule +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) -checklist. A change is release-ready only when all child work is integrated, -required checks are green or explicitly blocked and owned, documentation and -tests match the delivered behavior, and the release intent follows -[versioning and releases](../../../../../docs/content/guides/versioning-and-releases.md). -For a bootstrap integration branch, release readiness means the minimum -load-bearing core is coherent; do not expand the exception to unrelated v1 -features. - -## Report back and stop - -The parent report must include the draft PR URL, files changed, commits, -validation commands and outcomes, policy decisions (especially branch target -and any bootstrap exception), unresolved blockers, and the next integration -step. The parent should not mark the work complete or the PR ready for review -until every child has reported and the combined result has passed the -repository-native validation and review gates. - -Stop instead of guessing when scope, ownership, branch target, release intent, -or acceptance evidence is ambiguous; when a required dependency or credential -is unavailable; when validation fails without an understood owner; or when -integration would modify unrelated work. Record the blocker and return control -to the parent. +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/Ways-of-Working/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/) -- [MSX Implement guidance](https://msx.no/docs/Agents/implement/) From 8bd01aef2c91da100dc70ba2a79aad8e6de36428 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:11:08 +0200 Subject: [PATCH 3/6] feat: add plugin skill authoring guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/plugin/README.md | 4 + .../skills/psmodule-skill-authoring/SKILL.md | 26 +++++ docs/content/guides/writing-plugin-skills.md | 101 ++++++++++++++++++ docs/content/index.md | 1 + docs/zensical.toml | 1 + 5 files changed, 133 insertions(+) create mode 100644 .github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md create mode 100644 docs/content/guides/writing-plugin-skills.md diff --git a/.github/plugin/README.md b/.github/plugin/README.md index 91239f6d..81774b3e 100644 --- a/.github/plugin/README.md +++ b/.github/plugin/README.md @@ -34,6 +34,10 @@ 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 diff --git a/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md b/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md new file mode 100644 index 00000000..a5edb53e --- /dev/null +++ b/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md @@ -0,0 +1,26 @@ +--- +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, include the required Copilot + co-author trailer, 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. diff --git a/docs/content/guides/writing-plugin-skills.md b/docs/content/guides/writing-plugin-skills.md new file mode 100644 index 00000000..f05815a4 --- /dev/null +++ b/docs/content/guides/writing-plugin-skills.md @@ -0,0 +1,101 @@ +--- +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//skills// +└── 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. + +## Contribution and validation + +Work on a dedicated branch, open a draft pull request early, and use small +commits. Include the required co-author trailer in every commit: + +```text +Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> +``` + +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/Ways-of-Working/Agentic-Development/) +- [MSX Documentation Model](https://msxorg.github.io/docs/Ways-of-Working/Documentation-Model/) +- [MSX Markdown standard](https://msxorg.github.io/docs/Coding-Standards/Markdown/) +- [MSX Natural Language standard](https://msxorg.github.io/docs/Coding-Standards/Natural-Language/) diff --git a/docs/content/index.md b/docs/content/index.md index b7c550f5..4f1ef177 100644 --- a/docs/content/index.md +++ b/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. | ## Reference diff --git a/docs/zensical.toml b/docs/zensical.toml index 38152659..939788e6 100644 --- a/docs/zensical.toml +++ b/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"}, ]}, {"Reference" = [ {"Module development foundations" = "reference/module-development-foundations.md"}, From a7f060944d35629e3aba66d5a104ab6813ad8b79 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:17:54 +0200 Subject: [PATCH 4/6] docs: remove contribution requirements from skill guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../psmodule/skills/psmodule-skill-authoring/SKILL.md | 5 ++--- docs/content/guides/writing-plugin-skills.md | 9 +-------- 2 files changed, 3 insertions(+), 11 deletions(-) diff --git a/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md b/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md index a5edb53e..ea39b15a 100644 --- a/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md +++ b/.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md @@ -19,8 +19,7 @@ guidance. 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, include the required Copilot - co-author trailer, and report the PR URL, files, validation, decisions, and - blockers to the owning session. +- 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. diff --git a/docs/content/guides/writing-plugin-skills.md b/docs/content/guides/writing-plugin-skills.md index f05815a4..e2243600 100644 --- a/docs/content/guides/writing-plugin-skills.md +++ b/docs/content/guides/writing-plugin-skills.md @@ -64,14 +64,7 @@ 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. -## Contribution and validation - -Work on a dedicated branch, open a draft pull request early, and use small -commits. Include the required co-author trailer in every commit: - -```text -Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> -``` +## Validation Run the smallest existing checks that cover the changed surfaces: From 715ec5c849f03d542a1342a9e88fb16d6de415ab Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:21:47 +0200 Subject: [PATCH 5/6] docs: update MSX guidance links Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md | 2 +- docs/content/guides/writing-plugin-skills.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md b/.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md index 1d4201c3..0c27e026 100644 --- a/.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md +++ b/.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/) diff --git a/docs/content/guides/writing-plugin-skills.md b/docs/content/guides/writing-plugin-skills.md index e2243600..a8943a8d 100644 --- a/docs/content/guides/writing-plugin-skills.md +++ b/docs/content/guides/writing-plugin-skills.md @@ -89,6 +89,6 @@ update the skill without duplicating the common documentation. - [PSModule process plugin](https://github.com/PSModule/Process-PSModule/tree/main/.github/plugin) - [MSX Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) -- [MSX Documentation Model](https://msxorg.github.io/docs/Ways-of-Working/Documentation-Model/) -- [MSX Markdown standard](https://msxorg.github.io/docs/Coding-Standards/Markdown/) -- [MSX Natural Language standard](https://msxorg.github.io/docs/Coding-Standards/Natural-Language/) +- [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/) From a80ed86543dc875047b28a8cc2556ff2a971f9a0 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Fri, 4 Sep 2026 21:33:24 +0200 Subject: [PATCH 6/6] docs: repair MSX documentation links Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../psmodule-module-development-orchestration/SKILL.md | 2 +- AGENTS.md | 2 +- docs/content/guides/validating-before-review.md | 6 +++--- docs/content/guides/writing-plugin-skills.md | 2 +- docs/content/index.md | 2 +- docs/content/reference/repository-standard.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md index 8119c031..92c04d52 100644 --- a/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md +++ b/.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md @@ -71,7 +71,7 @@ changes, or claim release readiness. - [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/Ways-of-Working/Agentic-Development/) +- [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/) diff --git a/AGENTS.md b/AGENTS.md index 1bc74e3d..d9a84527 100644 --- a/AGENTS.md +++ b/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. diff --git a/docs/content/guides/validating-before-review.md b/docs/content/guides/validating-before-review.md index def8c02f..4be25bfd 100644 --- a/docs/content/guides/validating-before-review.md +++ b/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,7 +79,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. @@ -87,7 +87,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR ## 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) diff --git a/docs/content/guides/writing-plugin-skills.md b/docs/content/guides/writing-plugin-skills.md index a8943a8d..cbc5a9c1 100644 --- a/docs/content/guides/writing-plugin-skills.md +++ b/docs/content/guides/writing-plugin-skills.md @@ -88,7 +88,7 @@ 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/Ways-of-Working/Agentic-Development/) +- [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/) diff --git a/docs/content/index.md b/docs/content/index.md index 4f1ef177..2bd1fc71 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -89,4 +89,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/) diff --git a/docs/content/reference/repository-standard.md b/docs/content/reference/repository-standard.md index dbe7a6d0..6348b69b 100644 --- a/docs/content/reference/repository-standard.md +++ b/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.