diff --git a/src/docs/Capabilities/agentic-development/AGENTS.template.md b/src/docs/Capabilities/agentic-development/AGENTS.template.md index ee1b70b..6439a0e 100644 --- a/src/docs/Capabilities/agentic-development/AGENTS.template.md +++ b/src/docs/Capabilities/agentic-development/AGENTS.template.md @@ -10,16 +10,13 @@ itself the router that agents load. Copy the contents of the fenced `markdown` block into an `AGENTS.md` at the repository root. The router sends agents to repository-local guidance first, then to the -organization's canonical documentation clone. Prepare that clone with Git -using `git clone https://github.com/MSXOrg/docs.git ~/.msxorg/docs`, or -`git -C ~/.msxorg/docs fetch --prune origin` and -`git -C ~/.msxorg/docs pull --ff-only` when it already exists. Use it only -when it is clean and synchronized with its remote default branch. - -Configure Git identity locally for each context clone with -`git -C config --local user.name ""` and -`git -C config --local user.email ""`; do not rely on -global Git configuration. +organization's canonical documentation repository through its public URL. +Before using a linked repository, clone it locally, keep its configuration local +to that clone, and update it from its remote. +Agentic runtimes and local development may materialize that repository in any +context checkout they control. Clone, freshness, and local configuration +mechanics belong to that runtime or development setup, not to this portable +router. Client-specific files such as `.claude/CLAUDE.md` and `.github/copilot-instructions.md` point to the repository router. The shared @@ -34,7 +31,10 @@ Read in this order: 1. `README.md` — what this repository is and how it builds. 2. `.github/CONTRIBUTING.md` — how a change is made and reviewed here. 3. `docs/index.md` — this repository's own documentation. -4. `~/.msxorg/docs/src/docs/index.md` — the organization standards. +4. [MSXOrg/docs](https://github.com/MSXOrg/docs/) — the organization standards. + +Clone each linked repository locally, keep its configuration local to that +clone, and update it before reading it. Read nearest first. A local file never overrides a standard. ```` diff --git a/src/docs/Capabilities/agentic-development/design.md b/src/docs/Capabilities/agentic-development/design.md index d32a7b9..6503215 100644 --- a/src/docs/Capabilities/agentic-development/design.md +++ b/src/docs/Capabilities/agentic-development/design.md @@ -131,9 +131,10 @@ Resolution is deterministic. If the active repository remote is `github.com/PSMo ## Pointer files -`AGENTS.md` is the cross-runtime router. It lists where to read, in order. It -holds nothing else — no context synchronization mechanics, no build commands, -no contribution mechanics, no standards. +`AGENTS.md` is the cross-runtime router. It lists where to read, in order, and +includes one instruction to prepare linked repositories before reading them. It +holds no detailed synchronization mechanics, build commands, contribution +mechanics, or standards. ```markdown # AGENTS @@ -143,7 +144,11 @@ Read in this order: 1. `README.md` — what this repository is and how it builds. 2. `.github/CONTRIBUTING.md` — how a change is made and reviewed here. 3. `docs/index.md` — this repository's own documentation. -4. `~/.msxorg/docs/src/docs/index.md` — the organization standards. +4. [MSXOrg/docs](https://github.com/MSXOrg/docs/) — the organization standards. + +Clone each linked repository locally, keep its configuration local to that +clone, and update it before reading it. + Read nearest first. A local file never overrides a standard. ``` @@ -190,8 +195,8 @@ resolution; the agent does not use a possibly stale local copy. Each GitHub organization has its own organization-named workspace root, such as `~/.msxorg` for MSXOrg or `~/.psmodule` for PSModule. Repository agent files -retain the organization documentation destinations, and the template explains -how to prepare them with Git. +retain public organization documentation destinations; runtime and development +guidance defines how a context checkout is prepared and verified. ## Context freshness diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index 009217c..182bb0b 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -52,10 +52,10 @@ Applies to any organization that wants a shared project knowledge base for agent - **Organization is the project boundary.** The framework MUST resolve project context from the Git host and organization before resolving repository-specific context. - **Canonical docs repository.** Each adopting organization MUST have a `docs` repository that owns the reviewed knowledge base. -- **Predictable project context.** Repository-level agent instructions MUST identify the canonical documentation repository and its local clone path for each adopting organization. +- **Predictable project context.** Repository-level agent instructions MUST identify the canonical documentation repository with a public repository pointer for each adopting organization. - **OKF-style documents.** Knowledge documents MUST be Markdown files with YAML frontmatter, one primary concept per page, and stable paths that act as identity. - **Small pages and indexes.** Documentation SHOULD prefer small pages, each folder SHOULD have an `index.md`, and indexes MUST let a human or agent navigate inward from the root. -- **Thin pointer files.** Product repositories MUST carry an `AGENTS.md` at the repository root that routes an agent from the repository's own files outward to the organization documentation and any inherited ecosystem documentation. It MUST be limited to that route list. It MUST NOT duplicate standards, workflow stages, or reusable process knowledge, and MUST NOT carry build commands, contribution mechanics, or context synchronization steps, each of which has an owning file of its own. +- **Thin pointer files.** Product repositories MUST carry an `AGENTS.md` at the repository root that routes an agent from the repository's own files outward to the organization documentation and any inherited ecosystem documentation. It MUST be limited to that route list and the single context-preparation instruction defined by the template. It MUST NOT duplicate standards, workflow stages, or reusable process knowledge, and MUST NOT carry detailed synchronization procedures, build commands, or contribution mechanics. - **Refresh-first, index-first workflow discovery.** After every canonical context repository passes the Git freshness gate, a human or agent MUST be able to follow the docs root index to Ways of Working, the canonical Workflow, and the procedure for the current stage. - **Stage resolution from work.** Agents MUST infer the current stage from the prompt and current artifacts. Explicit task language MAY shortcut to the matching stage, but the shortcut MUST resolve to the canonical documentation. - **One process source.** Skills, commands, named agents, and tool-specific instruction files MUST NOT redefine Workflow stages. A client convenience MAY link to a stage procedure and add only runtime mechanics.