Repository navigation
[documentation-writing-alignment] Give plugin agents precise executable instructions #555
Description
Context and request
Agents need direct, scoped instructions that describe supported work without conversational or obsolete status wording. This delivery owns three SKILL.md files under .github/plugin/psmodule/skills/: psmodule-module-development-orchestration, psmodule-pester-migration, and psmodule-skill-authoring.
Evidence and expected result
The Pester migration skill says compatibility must be "green", describes name templates as "now expressions", and refers to "The current Process-PSModule flow". Preserve the exact migration and test-state constraints, but state conditions with precise, durable language. The orchestration skill's direct numbered agent contract is an accepted format, not a defect to convert into passive prose.
Apply the pinned MSX Natural Language, Writing Guide, Markdown, Documentation, and Documentation Model. The artifact templates support imperative, verifiable steps. Keep the existing skill format and links to the shared guides; do not copy guide or playbook templates into SKILL.md.
Read the official STE description, STEMG FAQ, and relevant Issue 9 rules. The read-only local PDF matches the official MD5 9c720341c350ed77943b2c73d01c716f. Consulted rules cover approved meanings and technical terms (1.1-1.3, 1.5-1.12), en-US (1.14), active voice (3.6), clear sentences (4.1-4.2), imperative instructions and conditions (5.1-5.4), and descriptive paragraphs (6.1-6.6). No manual copy or extraction is published. This review does not certify full STE conformance.
Acceptance evidence defined before each edit
All three assigned skills are read in full at baseline 64ffb1d87f86bd5d487891fdb140b78385a00531.
| Surface and baseline wording | Expected wording or retained condition | Source and verification |
|---|---|---|
| Pester: "after compatibility is green" | State that required compatibility checks pass before optional adoption. Keep the optional feature list and all acceptance runs unchanged. | MSX Natural Language: specific and observable language. Official Pester migration guide: optional assertion and parallel features are not required for migration. |
| Pester: "A green workflow" and "make a migration green" | State that a workflow or migration checks pass. Preserve the warning that one passing workflow does not cover every test set and the prohibition on disabling failures. | MSX Natural Language: avoid idioms. Pester inventory, Step 5, and Step 7 define the existing scope. |
| Pester: name-template contents "are now expressions" | Name Pester v6 as the actor that evaluates template contents as PowerShell expressions. Keep the literal-text escape example unchanged. | Official name-template contract; MSX evergreen prose. |
| Pester: "The current Process-PSModule flow" | Describe the build, download, import, and framework path-selection behavior in the present tense without a status qualifier. | Baseline module-local workflow and path selection. |
Pester: "The current Process-PSModule workflows reference that action at v5.1.0" |
Remove the obsolete action-revision claim. Require separate checks of the action revision and its Pester installation policy without an arbitrary example or a copied moving pin. Preserve all Pester/runtime versions. | At the common baseline, the module-local workflow and test action use action v5.1.1 and Pester [6.1.0,7.0.0). An action revision is not a Pester module version. |
| Pester: "Fail loudly", "new default", and "blind rename" | State the existing test failure, coverage-default exception, and assertion behavior-review conditions directly. Keep all examples and exceptions. | MSX precise, evergreen prose; Issue 9 rules 1.3, 4.1, and 5.3. |
| Orchestration: several actions in numbered step 3 and a long stop-condition sentence | Split actions and conditions into direct sentences. Preserve the numbered order, each handoff field, every stop condition, the bootstrap exception, and parent ownership. | MSX executable agent instructions; Issue 9 rules 5.2-5.4. The linked orchestration guide remains the shared process source. |
| Authoring: several actions in one draft-PR bullet and a trailing stop condition | Split draft, commit, and report actions. Put the unclear-scope condition before the stop instruction. Keep all report fields, ownership boundaries, and source links. | MSX executable agent instructions; Issue 9 rules 5.2-5.4. The linked authoring guide remains the shared process source. |
Acceptance criteria
- All three skills have a full manual review and concrete before/after or justified no-change evidence.
- Agent actions remain imperative, ordered, scoped, and verifiable. Descriptions use clear present-tense en-US prose.
- Skill names, triggers, relative links, front matter keys and values, headings, handoffs, stop conditions, normative force, exact commands, Pester/runtime versions, and public test-state constraints remain unchanged.
- General migration procedures keep the version-specific conditions needed to perform them. No framework upgrade or migration occurs in this change.
- Shared process links remain canonical; the change neither duplicates policy nor restructures the plugin.
- Small commits and an early draft PR record existing Markdown/link/metadata checks and source limitations. No scan is treated as proof of full STE conformance.
Technical decisions
Edit only:
.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md.github/plugin/psmodule/skills/psmodule-pester-migration/SKILL.md.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md
Plugin README/metadata and the v8/Zensical skills remain with existing proposal owners. The shared authoring and orchestration guides are owned by another focused writing delivery, so this task may read but not edit them. #551 owns no documentation or native-help changes; this task changes no tests. All source, guides, indexes, workflows, and configuration remain read-only.
Keep the Pester 6.1.0 target, Windows PowerShell 5.1 / PowerShell 7.4+ compatibility, staged major-version migration, optional feature gates, prepared-module/public-interface contract, explicit fixture ownership, and failure handling. Keep the generic version-specific migration procedure. Preserve front matter, headings, every fenced example, inline identifiers, and link destinations, with one documented exception: remove the obsolete inline action-revision example v5.1.0. This is a factual prose correction, not an action, dependency, Pester, or runtime version change.
Use the pinned Task and PR format. Open one draft PR after the first coherent commit. Push small follow-ups and leave it in draft. Do not merge, enable auto-merge or Agent merge, or create more sessions.
Validation baseline
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml <three assigned SKILL.md paths>: PASS, 3 files, 0 issues; markdownlint-cli2 0.24.0 / markdownlint 0.42.0.git diff --check: PASS on the clean baseline.- Existing
.github/linters/.textlintrcdefines terminology rules. The first textlint run returned exit 1 with no rules loaded. The debug run identified the missingtextlint-rule-terminologypackage. After restoring only the existing configured rule/filter in the external tool cache, the baseline textlint run passes (exit 0). No repository dependency or configuration changes occur. - The repository has no dedicated skill front-matter or documentation-link check. Read-only parsing with the available PyYAML package passes for all 3 skill headers. All 8 relative-link occurrences resolve to existing files. Both unchanged plugin/marketplace JSON manifests parse. Compare exact protected text against the baseline after editing. No repository enforcement tooling is added.
- The initial open-PR path check found no overlap with the three owned paths. Recheck before each commit. Other open proposals own the excluded plugin README/manifests and v8/Zensical skills.
Delivery evidence
The first coherent commit, 780422b (Pester prose only), is pushed. PSModule/Process-PSModule#568 is opened in draft before the orchestration and authoring follow-up. At that commit, Markdown and existing-config textlint pass. The baseline comparison confirms unchanged front matter, headings, link labels and destinations, ordered inline syntax, version-token counts, and all 17 fenced examples. The open-PR path check before that commit finds no competing owner for the assigned paths.
The second commit, fe6a441517e94f09296a10e0c83df18b75697dfc, contains only the orchestration/authoring sentence changes and is pushed. Early draft review identifies a flaw in the first Pester edit: retaining v5.1.0 as an arbitrary example hides the known source mismatch. The third commit, 9c191e2669957ff5b3a9c4649222a07191b462ee, removes that example entirely and is pushed. The protected-token comparison permits only this single removal; all other inline syntax, version tokens, and fenced examples remain exact. The shared-guide owner makes the corresponding source-backed correction in a separate delivery. No shared-guide edit is needed in this PR.
Final acceptance evidence
PSModule/Process-PSModule#568 is open in draft, targets main, and has pushed head 9c191e2669957ff5b3a9c4649222a07191b462ee. The PR base and scoped comparison baseline are both 64ffb1d87f86bd5d487891fdb140b78385a00531. The remote branch and PR head match the local head. The worktree is clean. The final diff contains exactly 3 files, 42 added lines, and 42 removed lines.
All three assigned files have a full manual read and review. No assigned file is a no-change outcome.
| Reviewed and changed path | Concrete before/after result | Retained contract |
|---|---|---|
.github/plugin/psmodule/skills/psmodule-pester-migration/SKILL.md |
"after compatibility is green" becomes "after the required compatibility checks pass"; "are now expressions" names Pester v6 as the evaluator; moving workflow status becomes present-tense behavior; the obsolete action-revision claim is removed. | Pester 6.1.0, Windows PowerShell 5.1 / PowerShell 7.4+, staged major upgrades, required/optional distinctions, prepared module state, public-interface tests, explicit fixtures, failure handling, all examples, acceptance runs, and source references. |
.github/plugin/psmodule/skills/psmodule-module-development-orchestration/SKILL.md |
The draft/push/trailer step uses three direct sentences. Validation and recording use separate sentences. The integration-report condition precedes the report action. Each stop condition states the stop-and-report action. | The same numbered sequence, parent ownership, all handoff fields, normal default-branch policy, bootstrap exception, genuine-dependency rule, integration gates, six ambiguity conditions, ownerless validation failure, and unrelated integration changes. |
.github/plugin/psmodule/skills/psmodule-skill-authoring/SKILL.md |
The guide is the explicit subject of the source statement. Draft, commit, and report actions use separate sentences. The unclear-scope condition precedes "stop and report". | The trigger, shared-guide link, inspection step, thin-skill boundary, adjacent-work exclusion, all report fields, ownership, and no-guessing condition. |
The before-edit source and delivered source are immutable. The source-backed expectations above identify the applicable MSX/STE rules and technical contracts.
The obsolete-revision regression (assert 'v5.1.0' not in text) fails at the second commit and passes after the third. The protected comparison removes exactly one old inline/version token, v5.1.0, before comparison. Every other inline syntax token retains its order, and every other version-token count remains exact. In particular, no Pester/runtime constraint, action reference, dependency, command, or workflow changes.
Reviewed no-change evidence
The three skills retain all front-matter keys and values, names/descriptions/triggers, headings and anchors, link labels and destinations, table rows, and all 17 fenced examples. The complete per-repository Pester checklist and Step 7 acceptance/report/reference section compare exactly with the baseline. The generic version-specific migration procedure remains; this change does not convert it into release history or refactor it into shared policy.
Manual review compares every changed instruction with its original condition and normative force. The action-revision verification remains mandatory as an imperative. Optional assertions, shuffle, and parallel execution remain optional. Module-local tests still use the framework-prepared built module and its public interface. Explicit import/manifest/removal tests retain their narrow exception. Missing fixtures still fail instead of producing empty defaults, hidden imports, skipped tests, or silent success.
The following repository files are read in full as supporting context or contract evidence and remain unchanged by this PR:
AGENTS.mdREADME.md.github/plugin/README.md.github/plugin/marketplace.json.github/plugin/psmodule/plugin.jsondocs/content/get-started/module-bootstrap.mddocs/content/guides/module-development-orchestration.mddocs/content/guides/writing-plugin-skills.mddocs/content/guides/writing-module-tests.mddocs/content/reference/test-specification.md.github/actions/Test-PSModule/action.yml.github/actions/Test-PSModule/src/main.ps1.github/workflows/Test-ModuleLocal.yml.github/workflows/Linter.yml.github/workflows/Release.yml.github/linters/.markdown-lint.yml.github/linters/.textlintrc.github/linters/.codespellrc
.github/workflows/workflow.yml is inspected only at lines 1-180 for workflow/caller context and remains unchanged. This is not a full-file prose review.
The following read-only link targets are resolved to existing files but do not receive a full prose review:
docs/content/guides/validating-before-review.mddocs/content/guides/versioning-and-releases.mddocs/content/guides/structuring-your-module.mddocs/content/reference/repository-standard.md
Excluded paths and work
The plugin README and manifests above are edit-excluded and remain with their existing owners. These two skills are excluded from both the prose review and editing:
.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md.github/plugin/psmodule/skills/psmodule-zensical-migration/SKILL.md
All other repository paths are edit-excluded. This includes the shared guides, all other docs/content/** pages and indexes, docs/zensical.toml, .github/zensical.toml, all source and tests, native help, .github/actions/**, .github/workflows/**, .github/scripts/**, and .github/linters/**. Read-only source inspection does not transfer ownership or authorize an edit. No plugin metadata redesign, copied shared policy, skill refactor, consumer migration, framework upgrade, site/navigation redesign, or new repository enforcement tool is included.
The existing mock-policy contradiction in the reference sources remains outside this writing delivery and is tracked by #563. This PR does not select or weaken a mock policy. #534 retains the separate thin-skill refactor; #559 owns the shared-guide corrections; #561 owns the excluded v8/Zensical skills.
Final validation commands and results
The following commands run successfully at the pushed head:
$SkillFiles = @(
'.github\plugin\psmodule\skills\psmodule-module-development-orchestration\SKILL.md'
'.github\plugin\psmodule\skills\psmodule-pester-migration\SKILL.md'
'.github\plugin\psmodule\skills\psmodule-skill-authoring\SKILL.md'
)
git diff --check 64ffb1d87f86bd5d487891fdb140b78385a00531 HEAD
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml @SkillFiles
npx --no-install --package=textlint@15.8.0 --package=textlint-rule-terminology --package=textlint-filter-rule-comments textlint --config .github\linters\.textlintrc @SkillFiles| Check | Result and scope |
|---|---|
git diff --check <baseline> HEAD |
PASS, no whitespace errors. |
| Existing-config Markdown lint | PASS, 3 files, 0 issues; markdownlint-cli2 0.24.0 / markdownlint 0.42.0. |
| Existing-config textlint | PASS, textlint 15.8.0. The baseline missing-rule failure is resolved by restoring only the existing configured rule/filter in the external tool cache. |
| Read-only Python/PyYAML header inspection | PASS, all 3 headers parse with unchanged keys/values and matching skill directory names. |
| Read-only JSON inspection | PASS, 2 unchanged plugin/marketplace manifests parse. |
| Read-only relative-target inspection | PASS, all 8 relative-link occurrences resolve to 7 existing target files. No same-file or cross-file fragment is present in those links. |
Read-only git show <baseline>:<path> comparison |
PASS, front matter, headings, link labels/destinations, table rows, all 17 fenced blocks, and remaining ordered inline/version tokens are exact; only the obsolete action-revision token is removed. |
| Obsolete action-revision regression | Expected FAIL before the review correction; PASS after it. |
| Changed-path and ownership check | PASS, exactly the 3 owned paths differ. Each pre-commit open-PR path check finds no competing owner, excluding this PR from the later checks. |
| Pushed-state check | PASS, local HEAD, git ls-remote --heads origin plugin-instruction-writing, and PR head all equal 9c191e2669957ff5b3a9c4649222a07191b462ee; worktree clean. |
| Repository Linter | PASS, completed successfully for the exact final head; super-linter 8.7.0. |
| Analyze (actions) | PASS on the final head. |
| CodeQL | PASS on the final head. |
The Python checks are read-only inspection using available standard-library modules and PyYAML, not added repository enforcement tooling. No dedicated skill front-matter or documentation-link checker exists in this snapshot. No Pester suite, module migration, or site build runs for these skill-prose-only edits. No such result is claimed.
The full manual review and these checks apply the cited writing practices; they do not prove full ASD-STE100 conformance. All required writing sources are available. The manual and extraction remain local. No source-access or implementation blocker remains.
Standards pass, convergence, and handoff state
The final standards pass compares all changed prose with the pinned MSX chapters, applicable guide/playbook templates, official STE sources, and the linked framework/technical sources. Each changed surface is recorded as "Fixed in this PR" in the PR's Technical details. Common guide links and their ownership remain unchanged.
The issue-convergence sweep searches open writing-alignment titles, plugin-related titles/bodies, and Pester titles. It reads the relevant asks in #534, #559, #561, and #563. No additional issue is fully delivered by this diff. Only #555 has a closing reference. The GitHub parent-issue endpoint returns "No parent issue found"; the sweep uses the scoped writing leaves and component searches instead.
The PR remains open in draft, assigned to its author, with no labels. GitHub auto-merge is unset. Agent merge is disabled and its merge action is false. No merge occurs. The plugin-only paths do not match the repository release workflow's publication filter, so no release decision block or release:* label applies. The delivery issue remains open for review and merge.
Implementation plan
- Read all three assigned skills in full, the pinned writing rules and Task/PR formats, the official STE sources, and the relevant technical sources.
- Define before/after acceptance evidence before editing; record source-backed no-change boundaries.
- Complete the baseline Markdown, natural-language, relative-link, and front-matter checks.
- Edit Pester prose, compare protected contracts, recheck PR path ownership, commit, push, and open the early draft PR.
- Edit the orchestration and authoring instructions, preserve all handoffs and stop conditions, validate, recheck PR path ownership, commit, and push.
- Remove the obsolete action-revision example identified in early draft review; verify the single protected-token exception against the pinned workflow source, rerun checks, recheck PR path ownership, commit, and push.
- Review the complete diff against the pinned standards and framework sources; record the issue-convergence search scope and result.
- Run final checks, update this issue and the draft PR with reviewed/no-change/excluded paths and acceptance results, and verify the pushed head SHA and draft state.
Activity
MariusStorhaug commentedon Nov 4, 2026
The Task plan records the full three-skill review, pinned source rules, and before-edit acceptance evidence. The workflow source uses action v5.1.1, so the prose will retain v5.1.0 as an example rather than a claim about a moving revision. No version, test, workflow, metadata, or shared-guide change is planned. Baseline Markdown lint passes. The existing textlint rule package is missing from the local tool cache; the configured packages are being restored before editing.
MariusStorhaug commentedon Nov 4, 2026
Baseline Markdown, existing-config textlint, header/JSON parsing, and all 8 relative-link checks pass. The first coherent Pester prose commit is pushed, and #568 is open in draft. Exact protected contracts and all 17 fenced examples are unchanged. The reviewed orchestration/authoring sentence changes are the next small commit.
MariusStorhaug commentedon Nov 4, 2026
Early draft review found that converting the stale v5.1.0 action claim into an arbitrary example hides the verified mismatch with the baseline v5.1.1 pin. The current Task plan replaces that approach: remove the obsolete example, keep the separate action-revision/Pester-policy checks, and document exactly one removed action-revision token in the protected comparison. All Pester/runtime compatibility constraints, fenced commands, workflows, and dependencies remain unchanged. The orchestration/authoring follow-up is already pushed as fe6a441.
MariusStorhaug commentedon Nov 4, 2026
The focused writing delivery is pushed as three small commits at head 9c191e2 in draft #568. The Task body records all completed plan steps, all three full skill reviews, concrete before/after evidence, the full reviewed/no-change/excluded path inventory, source citations, and check commands/results. The review correction removes only the obsolete action-revision example; Pester/runtime constraints, commands, all 17 fenced examples, headings, links, and other protected syntax remain unchanged. Local checks and all final-head GitHub checks pass. No blocker remains for this prose-only delivery. The PR and issue remain open for review and merge; no merge or auto-merge is performed, and Agent merge is disabled.