📖 [Docs]: Agent context resolves through organization repositories

[Marius Storhaug (MariusStorhaug)]

Agents resolve canonical MSXOrg and PSModule documentation through the repositories that own it.

Changed: Documentation sources use real repository identities

The Agentic Development design identifies MSXOrg/docs and PSModule/Process-PSModule without prescribing where either repository is cloned locally.

Changed: Shared context is documentation-only

Obsolete context-store guidance is removed. Runtime and development setup own local checkout placement. The newly agreed root router and canonical AGENTS.md template from main remain unchanged.

---

Technical details

• The latest main is integrated in merge commit a4dc148.
• The final diff preserves AGENTS.md, AGENTS.template.md, conformance, and runtime integration from main.
• Agentic Development spec and design allow a canonical documentation repository whose name is not docs.
• Local and CI validation are being rerun after removing filesystem-location guidance.
• Issue convergence sweep: no additional open issue is fully satisfied by this diff.

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Capabilities/agentic-development/{index,spec,design}.md	Documentation Model, Natural Language, Markdown	Agentic Development	Aligned
Related documentation	Natural Language, Markdown	Agentic Development and Repository Governance	Aligned
.github/plugin/**, src/docs/Initiatives/PSModule.md	Natural Language, Markdown	Agent Plugin and PSModule guidance	Aligned

Relevant issues (or links)

• Resolves Align agent context paths with organization repositories #191

[Copilot]

Pull request overview

This PR updates the agentic-development “canonical context” model to be repository-addressable by identity (e.g., MSXOrg/docs, PSModule/Process-PSModule) and to support multiple delivery methods (CLI/web/published site/refreshed local clones), while explicitly failing closed on the former ~/.msx/ layout.

Changes:

• Refactors the bootstrap contract from project-based (-Project, DocsUrl/MemoryUrl) to repository-based (-Repository, Name/Path/Url/Kind) coordinates, including updated tests.
• Introduces canonical org clone roots under ~/.msxorg/ and ~/.psmodule/, and adds explicit diagnostics + non-fallback behavior for recognized former ~/.msx/ paths.
• Updates agentic-development documentation and router examples to describe repository identity, entry files, published docs URLs, privacy status, and preferred clone paths.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/Initialize-MsxWorkspace.Tests.ps1	Updates test suite to validate repository-coordinate bootstrap behavior, canonical paths, and legacy-layout diagnostics.
bootstrap/Initialize-MsxWorkspace.ps1	Implements repository-addressable bootstrap inputs, path normalization/collision checks, and former-layout warnings.
bootstrap/AGENTS.template.md	Updates the seed/refresh instructions and environment variables to the new canonical clone layout and repository list.
bootstrap/README.md	Rewrites bootstrap docs to describe repository identity, canonical sources, and legacy layout non-fallback behavior.
AGENTS.md	Updates repo router to the new directive + source-repository addressing format.
CONTRIBUTING.md	Updates contributor guidance to the new canonical memory location under ~/.msxorg/memory.
src/docs/Capabilities/index.md	Updates the capability index description for Agentic Development (within generated index table markers).
src/docs/Capabilities/agentic-development/index.md	Updates capability overview and frontmatter to match repository-addressable context model.
src/docs/Capabilities/agentic-development/spec.md	Updates requirements terminology from “docs repo” to designated documentation source repositories + repository-identity rules.
src/docs/Capabilities/agentic-development/design.md	Updates design guidance, pointer-file examples, and canonical topology to org-addressable local roots.
src/docs/Capabilities/agentic-development/conformance.md	Updates conformance requirements to reflect repository-addressable sources and freshness expectations.
src/docs/Capabilities/agentic-development/memory-template.md	Updates template wording to align with “memory source repository” and documentation-source terminology.
src/docs/Ways-of-Working/Git-Worktrees.md	Updates worktree layout examples to the new canonical clone roots and PSModule documentation repo.
src/docs/Ways-of-Working/Repository-Standard.md	Updates example references from PSModule/docs to PSModule/Process-PSModule.
src/docs/Initiatives/PSModule.md	Updates PSModule initiative framing to make PSModule/Process-PSModule the canonical docs source.
.github/plugin/msx/skills/msx-ways-of-working-agentic-development/SKILL.md	Updates skill link target to the new Agentic Development capability location.

Suppressed comments (2)

bootstrap/Initialize-MsxWorkspace.ps1:402

• These Test-Path checks validate repository-controlled paths, but they use -Path (wildcard-aware). Use -LiteralPath so that path validation and origin verification can’t be confused by wildcard characters in configured repository paths.

    $contextPath = Join-Path $Root $repository.RelativePath
    $gitEntry = Join-Path $contextPath '.git'
    if ($repository.Kind -eq 'memory' -and (Test-Path $gitEntry -PathType Container)) {
        Assert-ContextOrigin -GitPath $contextPath -RepositoryUrl $repository.Url
    } elseif ($repository.Kind -eq 'docs') {

bootstrap/Initialize-MsxWorkspace.ps1:392

• Test-Path is called with -Path on repository-controlled paths. Because -Path treats wildcards, a repository Path containing characters like [/]/?/* could cause the safety checks to test a different filesystem location than the later git operations. Use -LiteralPath for these validations to avoid wildcard expansion.

This issue also appears on line 398 of the same file.

    $memoryGitEntry = Join-Path $memoryPath '.git'
    if (Test-Path $memoryGitEntry -PathType Leaf) {
        throw "Memory context '$memoryPath' is a worktree, but memory requires a simple checkout with a .git directory."
    }
    if ((Test-Path $memoryPath) -and -not (Test-Path $memoryGitEntry -PathType Container)) {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

Previously missed (2) — in code that hasn't changed since the last review.

AGENTS.md:5

• The repository router no longer states the conformance-required precedence rule that local files must not override an organization standard. Read nearest first plus the source list can be read as a "local overrides" policy unless the conflict precedence is explicit (and conformance.md still requires it).

Read nearest first, prefer documentation over memory, and always use the newest version.

This repository is `github.com/MSXOrg/docs`. Read these sources in order:

src/docs/Capabilities/agentic-development/design.md:185

• The router examples don’t include the conformance-required precedence statement (that local files never override an organization standard, and memory never overrides documentation). Since these examples are copy/paste scaffolds, omitting precedence here encourages non-conformant routers.

This issue also appears on line 212 of the same file.

Use a CLI, the web, published documentation, or a refreshed local clone, whichever
provides the newest accessible source.

bootstrap/Initialize-MsxWorkspace.ps1:564

• This uses New-Item -Path, which treats wildcard characters (like [ and ]) as patterns. Since repository paths are intended to be treated literally, this should use -LiteralPath (and the same applies to other New-Item calls that build parent directories from configured paths).

                New-Item -ItemType Directory -Path (Split-Path -Parent $backingPath) -Force | Out-Null

src/docs/Capabilities/agentic-development/design.md:213

• Same as the MSXOrg example above: the PSModule router example should include the explicit conflict precedence line required by conformance, so a copied router doesn’t imply that repository-local files override standards.

Use a CLI, the web, published documentation, or a refreshed local clone, whichever
provides the newest accessible source.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

tests/Initialize-MsxWorkspace.Tests.ps1:394

• The literal-path preflight test uses New-Item -Path to create directories under $literalRoot (which contains [ / ]). -Path performs wildcard expansion, so literal-path-workspace[1] can match literal-path-workspace1, undermining the test's intent and potentially creating the fixture in the wrong location. Use literal directory creation instead (same approach used in the bootstrap implementation).

        New-Item -ItemType Directory -Path (Join-Path $literalRoot 'context1/docs/.git') -Force | Out-Null
        New-Item -ItemType Directory -Path (Join-Path $literalRoot 'context1/memory/.git') -Force | Out-Null

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/docs/Capabilities/agentic-development/spec.md:56

• This requirement says sources are named as <organization>/<repository>, but the spec also describes resolving project scope by Git host and uses fully qualified examples like github.com/MSXOrg. Adding a short clarification that the host is already resolved (and therefore implied) would prevent readers from thinking host is intentionally excluded from identity.

- **Repository identity is authoritative.** A router MUST name each source as `<organization>/<repository>`. CLI, web, published-site, and refreshed-local-clone access are interchangeable delivery methods.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/docs/Capabilities/agentic-development/spec.md:69

• Grammar: “MUST stop local resolution rather than become stale fallbacks” is ungrammatical. Use “rather than becoming …” (or rephrase) so the requirement reads cleanly.

- **Fresh context before use.** Agents MUST use the newest accessible source version. Remote CLI, web, and published documentation MAY satisfy this directly. A local clone MUST be fetched and exactly synchronized with its remote default branch before its contents are read. Dirty, locally ahead, diverged, wrong-branch, or unreachable local clones MUST stop local resolution rather than become stale fallbacks.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/docs/Capabilities/agentic-development/spec.md:86

• The success-criteria bullet still references docs/index.md, but this PR changes the model to “start at the designated documentation repository’s entry index” (and the canonical source may not be a repo named docs). This line should be updated to avoid contradicting the revised contract.

- A new product repository can adopt the framework by adding a router and the client routes that reach it, without copying standards pages.
- An agent reads the repository's own README and CONTRIBUTING before it reads an organization standard, and still applies the organization standard when the two disagree.
- A human or agent can follow `docs/index.md` → Ways of Working → Workflow → the current stage procedure without knowing a file path in advance.
- A prompt such as `Review this PR <link>` reaches the Review procedure directly, while `Make this issue <description>` reaches Define, without a parallel process definition.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/docs/Capabilities/agentic-development/spec.md:85

• The success criteria still hard-codes docs/index.md as the entry point. With the updated contract (designated documentation repository + its entry index), this should refer to the documentation repository’s entry index instead of a fixed path that may not exist (and may not be under docs/).

- An agent working in `<host>/<org>/<repo>` for any adopting organization resolves its designated documentation repository as the canonical project context, with no change to the framework.
- A new product repository can adopt the framework by adding a router and the client routes that reach it, without copying standards pages.
- An agent reads the repository's own README and CONTRIBUTING before it reads an organization standard, and still applies the organization standard when the two disagree.
- A human or agent can follow `docs/index.md` → Ways of Working → Workflow → the current stage procedure without knowing a file path in advance.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.