📖 [Docs]: Central agent model — descriptions, AGENTS.md/CLAUDE.md pointers, and a git-isolated workspace bootstrap

.github/copilot-instructions.md

@@ -0,0 +1 @@
+Follow the instructions in [AGENTS.md](../AGENTS.md).

AGENTS.md

@@ -0,0 +1,30 @@
+# Agents
+
+This repository is the central documentation for the MSX ecosystem. Everything an agent needs to work here — and the roles agents play across the ecosystem — is documentation, read the same way a new teammate would.
+
+## Start here
+
+1. Read this file, then the [README](README.md) for what this repository is and how it builds.
+2. Read the [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — how work flows from idea to delivery.
+3. Load the [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) relevant to the change.
+
+## Roles
+
+Agent behaviour is authored once, as documentation, in the [Agents](https://msxorg.github.io/docs/Agents/) section. Use the role that fits the task:
+
+- [Define](https://msxorg.github.io/docs/Agents/define/) — capture, refine, and plan a change into an issue.
+- [Implement](https://msxorg.github.io/docs/Agents/implement/) — deliver a planned issue as a review-ready pull request.
+- [Reviewer](https://msxorg.github.io/docs/Agents/reviewer/) — review a pull request for delivery, taste, and security.
+- [Security Reviewer](https://msxorg.github.io/docs/Agents/security-reviewer/) — a structured, defensive security pass.
+- [Agent Author](https://msxorg.github.io/docs/Agents/agent-author/) — create and maintain these roles and pointers.
+
+## How work happens here
+
+- [Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/) and [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/) — the branch model and where to work.
+- [Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/) — the draft-first, Copilot-review loop through to a ready pull request.
+- [Definition of Ready and Done](https://msxorg.github.io/docs/Ways-of-Working/Definition-of-Ready-and-Done/) — when a change is ready for review and when it lands.
+- This repository's build and checks — see the [README](README.md).
+
+## The rule
+
+This file points; it never defines. Process knowledge lives in the docs and is referenced by canonical URL — never copied here. See [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/).

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

bootstrap/AGENTS.template.md

@@ -0,0 +1,41 @@
+# MSX workspace
+
+The single starting point for any agent, in any repository. Before doing anything else, make sure the central workspace exists locally, then read from it.
+
+## First — bootstrap the workspace
+
+The workspace is a git-isolated clone of the central repositories under `~/.msx`. Set it up (idempotent — clones what is missing, attempts to fast-forward the rest):
+
+```powershell
+$docs = Join-Path $HOME '.msx/docs'
+if ((Test-Path $docs) -and -not (Test-Path (Join-Path $docs '.git'))) {
+    throw "$docs exists but is not a git repository. Remove it and re-run."
+}
+if (-not (Test-Path (Join-Path $docs '.git'))) {
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $docs) | Out-Null
+    git clone https://github.com/MSXOrg/docs.git $docs
+    if ($LASTEXITCODE -ne 0) {
+        throw "git clone of MSXOrg/docs failed (exit $LASTEXITCODE). Check network access and github.com credentials, then re-run."
+    }
+}
+pwsh (Join-Path $docs 'bootstrap/Initialize-MsxWorkspace.ps1')
+```
+
+This produces:
+
+- `~/.msx/docs` — how work is done: ways of working, coding standards, and agent roles. The same content published at <https://msxorg.github.io/docs/>.
+- `~/.msx/memory` — what has been learned before: durable notes and prior session context.
+
+Each clone has repository-local git config only; it never modifies the global git config or the repository being worked in (git still reads them, but only repository-local config is written).
+
+> `MSXOrg/memory` is private — the bootstrap needs access to it (and working github.com credentials) for the memory clone.
+
+## Then — read before acting
+
+1. Read the relevant pages under `~/.msx/docs` for the task at hand.
+2. Read `~/.msx/memory` for prior decisions, pitfalls, and context.
+
+## Two write rules
+
+- **Docs change through pull requests.** Branch inside `~/.msx/docs` and open a pull request; never push its `main`.
+- **Memory pushes to main.** Commit and push notes directly inside `~/.msx/memory`; no pull request.

bootstrap/Initialize-MsxWorkspace.ps1

@@ -0,0 +1,113 @@
+#!/usr/bin/env pwsh
+#Requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Clone or update the MSX central workspace (docs + memory) in a git-isolated location under $HOME.
+
+.DESCRIPTION
+    The single starting point for every agent. It ensures the central
+    documentation and memory repositories exist locally under one dedicated
+    workspace, so an agent reads the same evergreen docs and the same prior
+    memory regardless of which repository it is working in.
+
+    The workspace is deliberately kept separate from the repositories an agent
+    works in:
+
+    - Each clone gets repository-local git config only. Nothing here modifies the
+      global git config or the working repository's config; git still reads global
+      and system config as usual, but this script writes only repository-local config.
+    - Documentation (MSXOrg/docs) is context and is changed through pull requests
+      only; this script never pushes its main branch.
+    - Memory (MSXOrg/memory) is append-only context; notes are committed and
+      pushed to main directly, without a pull request.
+
+    The script is idempotent: it clones what is missing and attempts to
+    fast-forward what is already present, leaving a repository unchanged (with a
+    warning) when it cannot fast-forward.
+
+.EXAMPLE
+    ./Initialize-MsxWorkspace.ps1
+    Clones missing repositories and attempts to fast-forward existing ones under ~/.msx.
+
+.EXAMPLE
+    ./Initialize-MsxWorkspace.ps1 -Root /work/.msx -Verbose
+    Uses a custom workspace root and logs each step.
+
+.OUTPUTS
+    [pscustomobject] with Repository, Path, and Changes for each workspace repository.
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    # The workspace root under which 'docs' and 'memory' are placed.
+    [Parameter()]
+    [ValidateNotNullOrEmpty()]
+    [string] $Root = (Join-Path $HOME '.msx'),
+
+    # The git author name written to each clone's local config.
+    [Parameter()]
+    [ValidateNotNullOrEmpty()]
+    [string] $UserName = 'Marius Storhaug',
+
+    # The git author email written to each clone's local config.
+    [Parameter()]
+    [ValidateNotNullOrEmpty()]
+    [string] $UserEmail = 'MariusStorhaug@users.noreply.github.com'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ((-not $PSBoundParameters.ContainsKey('UserName')) -or (-not $PSBoundParameters.ContainsKey('UserEmail'))) {
+    Write-Warning "Using part of the default maintainer identity ($UserName <$UserEmail>). Pass both -UserName and -UserEmail to attribute your own commits (memory pushes to main)."
+}
+
+$repositories = @(
+    [pscustomobject]@{ Name = 'docs'; Url = 'https://github.com/MSXOrg/docs.git'; Changes = 'pull requests' }
+    [pscustomobject]@{ Name = 'memory'; Url = 'https://github.com/MSXOrg/memory.git'; Changes = 'push to main' }
+)
+
+if ($PSCmdlet.ShouldProcess($Root, 'Create workspace root')) {
+    New-Item -ItemType Directory -Force -Path $Root | Out-Null
+}
+
+$results = foreach ($repo in $repositories) {
+    $path = Join-Path $Root $repo.Name
+    if (Test-Path (Join-Path $path '.git')) {
+        if ($PSCmdlet.ShouldProcess($path, 'Fetch and fast-forward')) {
+            Write-Verbose "Updating $path"
+            git -C $path fetch origin --quiet
+            if ($LASTEXITCODE -ne 0) {
+                throw "git fetch failed for '$path' (exit $LASTEXITCODE). Check network access and credentials for $($repo.Url)."
+            }
+            git -C $path pull --ff-only --quiet
+            if ($LASTEXITCODE -ne 0) {
+                Write-Warning "Could not fast-forward '$path' (local changes or diverged history). Left as-is."
+            }
+        }
+    } else {
+        if (Test-Path $path) {
+            throw "Cannot clone into '$path': it exists but is not a git repository. Remove it or choose a different -Root."
+        }
+        if ($PSCmdlet.ShouldProcess($repo.Url, "Clone into '$path'")) {
+            Write-Verbose "Cloning $($repo.Url) into $path"
+            git clone --quiet $repo.Url $path
+            if ($LASTEXITCODE -ne 0) {
+                throw "git clone failed for $($repo.Url) (exit $LASTEXITCODE). Check access and credentials (MSXOrg/memory is private)."
+            }
+        }
+    }
+
+    # Isolated identity: write repository-local config only. Git still reads
+    # global and system config; the script never writes to them.
+    if ($PSCmdlet.ShouldProcess($path, 'Set repository-local git identity')) {
+        git -C $path config user.name $UserName
+        if ($LASTEXITCODE -ne 0) { throw "git config user.name failed for '$path' (exit $LASTEXITCODE)." }
+        git -C $path config user.email $UserEmail
+        if ($LASTEXITCODE -ne 0) { throw "git config user.email failed for '$path' (exit $LASTEXITCODE)." }
+    }
+
+    [pscustomobject]@{ Repository = $repo.Name; Path = $path; Changes = $repo.Changes }
+}
+
+$results

bootstrap/README.md

@@ -0,0 +1,52 @@
+# Bootstrap
+
+The single starting point for agents: a git-isolated local clone of the MSX central repositories under `~/.msx`, plus the instruction that sends every agent there first.
+
+## Contents
+
+- `Initialize-MsxWorkspace.ps1` — idempotent setup. Clones `MSXOrg/docs` and `MSXOrg/memory` under `~/.msx`, attempts to fast-forward them if present, and writes a repository-local git identity so the workspace never modifies the global git config.
+- `AGENTS.template.md` — the user-global entry instruction. It bootstraps the workspace, then points the agent at the docs and memory. Install it once per machine (below).
+
+## The model
+
+- `~/.msx/docs` is **read context** — the ways of working, coding standards, and agent roles. Changes to it go through **pull requests**.
+- `~/.msx/memory` is **append-only context** — durable notes and session history. Changes to it are **pushed to main**.
+
+> **Prerequisite:** `MSXOrg/memory` is a private repository — the bootstrap needs access to it (and working github.com credentials) to clone or update memory.
+
+Keeping the workspace separate and git-isolated means an agent reads the same docs and memory in every repository, and its commits there use the workspace identity rather than whatever the working repository or the global config happens to be set to.
+
+## Install (once per machine)
+
+Run the bootstrap:
+
+```powershell
+$docs = Join-Path $HOME '.msx/docs'
+if ((Test-Path $docs) -and -not (Test-Path (Join-Path $docs '.git'))) {
+    throw "$docs exists but is not a git repository. Remove it and re-run."
+}
+if (-not (Test-Path (Join-Path $docs '.git'))) {
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $docs) | Out-Null
+    git clone https://github.com/MSXOrg/docs.git $docs
+    if ($LASTEXITCODE -ne 0) {
+        throw "git clone of MSXOrg/docs failed (exit $LASTEXITCODE). Check network access and github.com credentials, then re-run."
+    }
+}
+pwsh (Join-Path $docs 'bootstrap/Initialize-MsxWorkspace.ps1')
+```
+
+Wire it into the tools so it runs as the first instruction:
+
+- **Claude Code** reads `CLAUDE.md`. Add an import to `~/.claude/CLAUDE.md`:
+
+  ```text
+  @~/.msx/docs/bootstrap/AGENTS.template.md
+  ```
+
+- **Copilot** reads `AGENTS.md` natively. Install the contents of `AGENTS.template.md` as your **user-level** Copilot instructions so it applies in every repository. Per-repository `AGENTS.md` files stay thin pointers to the central docs — don't put the bootstrap there.
+
+## Identity
+
+The script writes a repository-local git identity to each clone. The default is the maintainer's GitHub **noreply** identity, so no personal email is written into git config and commits still attribute to the maintainer. Override it with `-UserName` / `-UserEmail`, or point it at a dedicated agent account when one exists.
+
+> **Override this if you are not the maintainer.** With the default, commits — including memory pushes to `main` — are attributed to the maintainer's account. Pass `-UserName` and `-UserEmail` (for example `-UserEmail 'you@users.noreply.github.com'`), or point the script at a dedicated agent account, so your commits are attributed correctly.

src/docs/Agents/agent-author.md

@@ -0,0 +1,49 @@
+---
+title: Agent Author
+description: Create and maintain the agent role descriptions and the per-repository pointer files that reference them.
+---
+
+# Agent Author
+
+Create and maintain the agent roles in this section, and the per-repository pointer files that reference them. Every role description is grounded in the [Ways of Working](../Ways-of-Working/index.md); every pointer file stays thin. Agent Author keeps descriptions and pointers honest — it does not encode standards into either.
+
+## When to use
+
+Create a new agent role, update an existing one, review agent quality, or refactor a bloated agent file back into a thin pointer over the docs.
+
+## Flow
+
+### 1. Gather requirements
+
+1. Identify the role — the single job it owns, and its boundary.
+2. Identify the docs pages that govern that role; confirm they exist.
+3. Identify what the role must **not** do — boundaries prevent scope creep.
+
+### 2. Author the description
+
+Write the role as a page in this section, following the shape of its siblings: front matter (`title`, `description`), a one-paragraph role and boundary, when to use, a numbered flow, operating rules, and a "Where this connects" list.
+
+- **Link, don't inline.** If a standard exists in the docs, link to it — never paste it in.
+- **Procedural, not conversational.** Numbered imperatives, no filler.
+- **Keyword-rich description.** The front-matter `description` is the discovery surface.
+
+### 3. Keep pointers thin
+
+A repository never carries a copy of a role. Its `AGENTS.md` — and the `CLAUDE.md` that imports it — point to these pages and add only repo-specific nuance and the genuinely tool-specific settings (permission scopes, model choice) that cannot be expressed as a pointer. When a new runtime is adopted, add a thin pointer; do not move process knowledge into it. See [Agentic Development](../Ways-of-Working/Agentic-Development.md).
+
+### 4. Validate
+
+1. Front-matter YAML parses cleanly.
+2. Every link resolves, and the body duplicates no doc content.
+3. The role is added to the navigation so its index row generates.
+
+## Operating rules
+
+1. Docs are the source of truth. If a standard is missing, propose adding it to the docs — do not embed it in an agent.
+2. One agent, one job. Multiple roles mean multiple pages.
+3. Update the navigation when adding or removing a role.
+
+## Where this connects
+
+- [Agentic Development](../Ways-of-Working/Agentic-Development.md) — the pointer model this maintains.
+- [Documentation Model](../Ways-of-Working/Documentation-Model.md) — how these pages stay evergreen.

src/docs/Agents/define.md

@@ -0,0 +1,58 @@
+---
+title: Define
+description: Capture, refine, and plan a change into an actionable issue ready for implementation.
+---
+
+# Define
+
+Take something someone wants — a feature, a bug, an improvement, external feedback, or a production signal — and turn it into a planned, actionable issue. The output is either a single Task with its three sections populated, or a decomposed initiative with structured sub-issues. Define plans work; it does not build it.
+
+## When to use
+
+Capture a desire for change, write an issue, plan work, decompose an epic, refine a bug report, create sub-issues, structure a feature request, or turn feedback into a task.
+
+## Input
+
+A description of a desired change, a feedback issue from a non-contributor (treated as input, never modified), a platform signal (error, failed run, alert), or an existing issue to refine.
+
+## Flow
+
+### 1. Capture
+
+Turn the input into an issue with Section 1 (context and request).
+
+1. Search for duplicates first — propose consolidation rather than creating a new issue.
+2. Frame from the user's perspective per [Issue Format](../Ways-of-Working/Issue-Format.md).
+3. Acceptance criteria must be user-observable and testable.
+
+### 2. Refine
+
+Ground the issue so anyone reading it agrees on what "done" means, up to the [Definition of Ready](../Ways-of-Working/Definition-of-Ready-and-Done.md).
+
+1. Pain before solution — push back on implementation-framed requests.
+2. Make assumptions explicit.
+3. Acceptance criteria answerable yes or no by a non-author.
+4. Ask one question at a time when interactive.
+
+### 3. Plan
+
+Decide how the work will happen and record the decisions.
+
+1. **Task** — one deliverable, one pull request. Populate the technical decisions and the implementation plan per [Issue Format](../Ways-of-Working/Issue-Format.md).
+2. **Larger work** — decompose into child issues per [Issue Hierarchy](../Ways-of-Working/Issue-Hierarchy.md).
+3. Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve.
+4. Record decisions with their rationale and the alternatives considered.
+5. Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue.
+
+## Operating rules
+
+1. Tone is impersonal. The issue description is the source of truth; comments record what changed.
+2. External references are hyperlinks.
+3. Do not modify a feedback issue from a non-contributor — create an internal issue and cross-link.
+4. Stop when the issue is plannable. Do not build, branch, or open pull requests — that is [Implement](implement.md).
+
+## Where this connects
+
+- [Workflow](../Ways-of-Working/Workflow.md) — the loop this opens.
+- [Issue Format](../Ways-of-Working/Issue-Format.md) and [Issue Hierarchy](../Ways-of-Working/Issue-Hierarchy.md) — issue structure and levels.
+- [Definition of Ready and Done](../Ways-of-Working/Definition-of-Ready-and-Done.md) — the readiness bar this aims for.