[Marius Storhaug (MariusStorhaug)]

Agentic development guidance uses direct en-US and present-tense explanations for context ownership, runtime integration, shared tools, named intents, advisory work, and conformance. The supported contracts and executable examples remain intact. No runtime, configuration, or adoption change is required.

Changed: Agentic development contracts have literal explanations

Contributors, maintainers, integrators, and agents can identify which files own context, how index navigation works, and how runtime mechanics remain separate from process. The template commentary also distinguishes the msx plugin from the msxorg marketplace. This is changed guidance, not evidence that a runtime or enforcement mechanism was implemented.

The specification retains its requirements, the design retains its mechanisms, focused pages retain their reference/addendum purpose, and the decisions index retains its historical-record semantics. Direct imperative instructions remain direct. Existing policy ambiguities are recorded rather than resolved by this prose change.

Technical details

Immutable scope and review sources

The complete scoped comparison is MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082 to MSXOrg/docs@ab46f17c8427780dd9c207087997b7838452560c. Five small logical commits are pushed, and the remote branch matches the candidate. The draft opened after the first complete design improvement. The final worktree is clean.

Criteria were derived from the fixed baseline before editing: Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and the applicable artifact templates. These are the shared writing rules in the table below.

The official STEMG overview, FAQ, and verified local Issue 9 rules and dictionary were consulted. The local PDF MD5 is 9c720341c350ed77943b2c73d01c716f, matching the campaign frame. Reference copies and extracted text remain local. Manual review and automated checks do not establish full STE conformance.

Fully read paths and standards alignment

All 12 owned pages were read fully. Eleven changed; the marketplace design is a justified no-change page. Fixed in this PR identifies changed prose, not a runtime implementation.

Fully read surface	Standards checked	Capability contract checked	Result
src/docs/Capabilities/agentic-development/spec.md	Shared writing rules; specification template	Organization boundary, requirement labels, freshness failures, normative force, success criteria, and nine-layer context order	Fixed in this PR
src/docs/Capabilities/agentic-development/design.md	Shared writing rules; design template	Context ownership, reading/authority order, thin routes, client behavior, and freshness	Fixed in this PR
src/docs/Capabilities/agentic-development/design-plugin-marketplaces.md	Shared writing rules; design template	Marketplace ownership, co-location, writing and upgrade discovery, layout, and versions	Aligned; complete file unchanged
src/docs/Capabilities/agentic-development/mcp-servers.md	Shared writing rules; focused reference purpose	Shared server set, native declarations, credentials, authentication failure, and process ownership	Fixed in this PR
src/docs/Capabilities/agentic-development/runtime-integration.md	Shared writing rules; focused reference purpose	Entry/lifecycle/tool/identity obligations, runtime shapes, setup failures, and permissions	Fixed in this PR
src/docs/Capabilities/agentic-development/plugin-distribution.md	Shared writing rules; focused reference/addendum purpose	Pointer-only intents, portable package boundaries, marketplace discovery, commands, and manifests	Fixed in this PR
src/docs/Capabilities/agentic-development/agent-interaction.md	Shared writing rules; focused reference purpose	Durable artifacts, Task/Bug technical plans, label ownership, agent-reviewing-agent scope, and human merge authority	Fixed in this PR
src/docs/Capabilities/agentic-development/advisory-agents.md	Shared writing rules; focused reference/addendum purpose	Seed-once labels, final human overrides, idempotence, required-early-run scope, attribution, and independent advice	Fixed in this PR
src/docs/Capabilities/agentic-development/conformance.md	Shared writing rules; focused reference purpose	Mandatory baseline, conformance levels, allowed additions, exemptions, and remedies	Fixed in this PR
src/docs/Capabilities/agentic-development/AGENTS.template.md	Shared writing rules; template/instruction format	Router order, local configuration boundary, inherited contribution source, and client routes	Fixed in this PR; executable fence unchanged
src/docs/Capabilities/agentic-development/index.md	Shared writing rules; documentation navigation model	Organization scope and context navigation	Fixed in this PR; generated INDEX block unchanged
src/docs/Capabilities/agentic-development/decisions/index.md	Shared writing rules; decisions-register and decision-record semantics	Empty record inventory and immutable supersession history	Fixed in this PR; history semantics unchanged

Concrete before and after evidence

Page	Before	After
design.md	"plugs into the same shape"	"An adopting organization uses the same model on a public or enterprise GitHub host."
design.md	"the contract lives, it just lives in the file a human would read"	"Each repository-specific contract remains in the file that owns it."
design.md	The agent "drills inward".	"The agent follows index links until it reaches the relevant page."
runtime-integration.md	"integration work is plumbing"	"A runtime supplies capabilities and lifecycle points, not process rules."
mcp-servers.md	"None of that is worth fighting."	"Each runtime uses its native configuration syntax for the same server contract."
plugin-distribution.md	"drift with extra steps"	"A bundled procedure is a snapshot that can differ from its canonical source."
advisory-agents.md	"This gives the agent exactly one turn to speak."	"The agent supplies an initial assessment only when no label from the set exists."
agent-interaction.md	"The separation earns its keep at rejection."	"The issue preserves the request when reviewers reject a proposed implementation."
AGENTS.template.md	"The shared msxorg Agent Plugin"	"The shared msx Agent Plugin from the msxorg marketplace provides skills that point to canonical documentation pages."
spec.md	"Applies to any organization that wants a shared project knowledge base for agents across multiple repositories."	"The framework applies to organizations that share agent context across repositories."
conformance.md	"A framework that cannot be checked is a preference."	"Conformance defines the required files, context resolution, and duplication limits for a repository."
decisions/index.md	"There are currently no decisions recorded for this capability."	"No decision records are listed for this capability."

All 12 expected after-text examples were absent before editing and present in the immutable candidate. The final meaning review also defined two scope counterexamples before correction: the required early-run trigger and an agent reviewing another agent's work. Both explicit actor/trigger checks pass. The intent-copy check compares procedure content instead of treating every documentation change as evidence of copying.

Validation and preserved behavior

Check	Final result
Existing Markdown lint	Passed for all 12 owned files with markdownlint-cli2 0.24.0 / markdownlint 0.42.0 and the repository configuration. npx --no-install used existing tooling.
Relative links and anchors	Passed for 130 files in the checkout and again after index generation in the temporary immutable snapshot. No cross-owned link repair is needed.
Cross-repository links	Repository-level check passed: 7 applicable targets across 134 files. The earlier owned-path run found zero applicable targets and exited 1; that run is not reported as a pass.
Existing Pester suites	Final candidate: 66 passed, 0 failed, 0 skipped across 6 suites with the existing pinned Pester 6.0.1. No dependency was added or upgraded.
CI-equivalent site build	Archived the exact candidate locally, ran the existing index generator and relative-link check, then zensical build --clean. Build reported no issues. Regenerated copies stayed in the temporary snapshot and were removed after verification.
Rendered output	Verified the design adoption statement, template plugin/marketplace distinction, regenerated index en-US spelling, and preserved indexes-as-the-mindmap anchor.
Source preservation	All 12 pages retain headings/anchors, full fenced content, generated INDEX bytes, link targets, normative-force sequence, requirement labels, navigation titles, and exact inline identifiers. Runtime/client/conformance/intent tables, spec success criteria, the complete context-order section, and the marketplace design are unchanged. git diff --check passes.
Final-head CI	Docs run: Lint, Links, Test, and Build passed; Publish skipped as expected for a PR. Cross-repository links run passed. Both apply to ab46f17c8427780dd9c207087997b7838452560c.
Existing Copilot review loop	Clean review on the exact final commit: APPROVED, zero new inline comments, helper exit 0. This remains advisory and does not change draft state.

The complete diff was reviewed for technical meaning in addition to the preservation checks. These results do not prove full ASD-STE100 conformance, runtime behavior, or semantic enforcement by CI.

Accepted differences, contradictions, and exclusions

Exact technical nouns, native syntax, identifiers, direct imperative template/procedure instructions, normative obligations, and historical decision semantics are retained. The Indexes as the mindmap heading remains to preserve its heading and anchor; its explanatory prose is literal. Existing artifact layouts remain intact instead of being restructured to recopy a template. Source INDEX tables remain unchanged; CI regenerates them from the edited front matter.

Four baseline contract questions remain outside this prose change:

• The spec prohibits restating host/org/repo coordinates in a router, while context-resolution step 3 says the router identifies host and organization.
• Conformance requires a router precedence statement; the fenced template omits it, the design example includes it, and the spec limits router content.
• The canonical-context freshness gate requires the fetched default-branch head, while the review-time table cites head-branch instructions. Their scopes need explicit clarification.
• Runtime guidance says advisory-only work needs no write access, while advisory outputs can apply labels. Branch-content writes and artifact writes are not distinguished.

The existing outside-contribution instruction-trust question remains in #123. None of these questions is converted into invented policy or implementation evidence. A separate contract-alignment change is the appropriate follow-up.

Only src/docs/Capabilities/agentic-development/** changes. Shared plugin routers/manifests, actual root/client agent files, plugin README, shared index source pages, other capability parts, configuration, executable code, and tests are excluded. #240 retains its code/test ownership. No repository audit/planning file, enforcement tool, or dependency was added.

The issue convergence pass searched open issues matching agentic in:title,body and router in:title, then checked the existing trust-boundary issue. No additional issue is fully resolved by this diff: #101 requires a defect-tracking contract; #187 requires router-link enforcement; #123 requires trust-boundary findings. The sibling capability-writing Task returned by the search belongs to another part. Only #248 has a closing reference.

The Task's source review, test-first prose verification, five pushed increments, complete-diff meaning review, final checks, and durable evidence are complete. There is no blocker for the requested prose work. The app-managed branch name and continued draft state follow the explicit campaign instructions.

The PR remains draft. GitHub auto-merge is null. Agent merge is disabled and merge_pr is false. No mark-ready or merge action was taken. The Docs route publishes a website and does not invoke Release Management; no release-decision block, release label, or versioned publication baseline is manufactured.

Related references

• Resolves [documentation-writing-alignment] Clarify agentic development guidance #248
• References Establish the trust boundary for Copilot code review reading instructions from the PR head branch #123 for the existing instruction-trust boundary.
• References An AGENTS.md router can ship with links that resolve to nothing #187 for router-link enforcement outside this prose scope.
• References Require automated and agentic work to track its defects #101 for a separate defect-tracking contract.
• References Keep documentation tooling tests focused on supported behavior #240 as the excluded code/test workstream.

[Copilot]

🟢 Approved

The review has no active issues requiring resolution.

No open issues 🎉

What changed in this PR

This PR rewrites the agentic-development documentation in direct, present-tense prose, clarifying the existing framework without changing repository configuration or runtime behavior.

Changes:

• Clarifies context ownership, index navigation, and reading order.
• Simplifies guidance for runtime integration, shared tools, named intents, conformance, and advisory agents.
• Corrects the template commentary to distinguish the msx plugin from the msxorg marketplace.

File	Description
src/​docs/​Capabilities/​agentic-development/​spec.md	Clarifies framework scope and requirements.
src/​docs/​Capabilities/​agentic-development/​runtime-integration.md	Simplifies runtime integration and permission guidance.
src/​docs/​Capabilities/​agentic-development/​plugin-distribution.md	Clarifies pointer-based intents and distribution.
src/​docs/​Capabilities/​agentic-development/​mcp-servers.md	Explains shared tool declarations and authentication directly.
src/​docs/​Capabilities/​agentic-development/​index.md	Clarifies organization scope and context reading order.
src/​docs/​Capabilities/​agentic-development/​design.md	Makes ownership, navigation, and freshness explanations explicit.
src/​docs/​Capabilities/​agentic-development/​decisions/​index.md	Removes time-dependent wording from the decision-list description.
src/​docs/​Capabilities/​agentic-development/​conformance.md	Simplifies conformance checks and remediation guidance.
src/​docs/​Capabilities/​agentic-development/​AGENTS.template.md	Clarifies template commentary and corrects plugin naming.
src/​docs/​Capabilities/​agentic-development/​agent-interaction.md	Clarifies durable coordination, review, and handover.
src/​docs/​Capabilities/​agentic-development/​advisory-agents.md	Simplifies advice, human-override, and repeat-run guidance.

_{Review effort: Balanced}