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

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. Repo-local linter config wins where it disagrees.
+
+## 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
+
+- Work on a `<type>/<description>` branch in its own [worktree](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/); open a **draft** pull request early.
+- Run the [Copilot review loop](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/) until it is clean.
+- Mark ready only when the change meets the [Definition of Ready for Review](https://msxorg.github.io/docs/Ways-of-Working/Definition-of-Ready-and-Done/), then enable auto-merge.
+- Documentation is validated by lint, link, and index 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,5 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+Claude Code does not read `AGENTS.md` automatically, so this file imports it — the line above pulls in the shared instructions every agent follows. Keep any Claude-specific notes below the import; everything else lives in [AGENTS.md](AGENTS.md) and the documentation it points to.

bootstrap/AGENTS.template.md

@@ -0,0 +1,29 @@
+# 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, fast-forwards the rest):
+
+```powershell
+if (-not (Test-Path ~/.msx/docs)) { git clone https://github.com/MSXOrg/docs.git ~/.msx/docs }
+pwsh ~/.msx/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).
+
+## 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,93 @@
+#!/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 fast-forwards what is
+    already present.
+
+.PARAMETER Root
+    The workspace root under which 'docs' and 'memory' are placed. Defaults to ~/.msx.
+
+.PARAMETER UserName
+    The git author name written to each clone's local config.
+
+.PARAMETER UserEmail
+    The git author email written to each clone's local config.
+
+.EXAMPLE
+    ./Initialize-MsxWorkspace.ps1
+    Clones missing repositories and fast-forwards existing ones under ~/.msx.
+
+.EXAMPLE
+    ./Initialize-MsxWorkspace.ps1 -Root /work/.msx -Verbose
+    Uses a custom workspace root and logs each step.
+#>
+[CmdletBinding()]
+param(
+    [Parameter()]
+    [string] $Root = (Join-Path $HOME '.msx'),
+
+    [Parameter()]
+    [string] $UserName = 'Marius Storhaug',
+
+    [Parameter()]
+    [string] $UserEmail = 'MariusStorhaug@users.noreply.github.com'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$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' }
+)
+
+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')) {
+        Write-Verbose "Updating $path"
+        git -C $path fetch origin --quiet
+        try {
+            git -C $path pull --ff-only --quiet
+        } catch {
+            Write-Warning "Could not fast-forward '$path' (local changes?). 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."
+        }
+        Write-Verbose "Cloning $($repo.Url) into $path"
+        git clone --quiet $repo.Url $path
+    }
+
+    # Isolated identity: repository-local config only, never global or inherited.
+    git -C $path config user.name $UserName
+    git -C $path config user.email $UserEmail
+
+    [pscustomobject]@{ Repository = $repo.Name; Path = $path; Changes = $repo.Changes }
+}
+
+$results | Format-Table -AutoSize
+Write-Output 'MSX workspace ready. Read docs and memory here; docs change through pull requests, memory pushes to main.'

bootstrap/README.md

@@ -0,0 +1,38 @@
+# 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`, fast-forwards 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**.
+
+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
+if (-not (Test-Path ~/.msx/docs)) { git clone https://github.com/MSXOrg/docs.git ~/.msx/docs }
+pwsh ~/.msx/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. Use the contents of `AGENTS.template.md` as your user-level Copilot instructions, or copy it into a repository as `AGENTS.md`.
+
+## 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.

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.

src/docs/Agents/implement.md

@@ -0,0 +1,69 @@
+---
+title: Implement
+description: Take a planned issue and deliver it as a review-ready pull request — branch, build, self-review, and finalize.
+---
+
+# Implement
+
+Take a planned issue and deliver working software in a review-ready pull request. Owns the full delivery loop: branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the release note. Implement builds; it does not plan from scratch or review others' work.
+
+## When to use
+
+Implement an issue, build a feature, fix a bug, create a branch, open a pull request, respond to review feedback, or finalize a pull request. Given an initiative rather than a task, pick the next unfinished sub-issue.
+
+## Input
+
+A Task issue number or URL with its three sections populated.
+
+## Flow
+
+### 1. Orient
+
+1. Read the issue fully — all three sections per [Issue Format](../Ways-of-Working/Issue-Format.md).
+2. Read the repository README first per [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md).
+3. Identify the stack and load the relevant [Coding Standards](../Coding-Standards/index.md). Repo-local linter config wins where it disagrees with a published standard.
+
+### 2. Branch and draft pull request
+
+Use [git worktrees](../Ways-of-Working/Git-Worktrees.md) for every issue.
+
+1. Create a worktree from the default branch per [Branching and Merging](../Ways-of-Working/Branching-and-Merging.md).
+2. Push an initial commit and immediately open a **draft** pull request so CI attaches from the first push.
+3. Link the issue with a closing keyword, and assign the pull request.
+
+### 3. Build
+
+For each task in the plan:
+
+1. Implement the change and self-review the staged diff.
+2. Commit per [Commit Conventions](../Ways-of-Working/Commit-Conventions.md) — one logical change per commit.
+3. Update the issue as each task completes — do not batch.
+4. Push regularly so CI runs against current work.
+
+When the plan is wrong, stop and document the conflict in a comment, then update the plan before resuming. Out-of-scope problems go to [Define](define.md).
+
+### 4. Self-review and respond
+
+1. Run the [Copilot review loop](../Ways-of-Working/Contribution-Workflow.md#the-copilot-review-loop) until it reports a clean round.
+2. Triage each thread and CI failure per [Review Etiquette](../Ways-of-Working/Review-Etiquette.md): fix in scope and propagate the same fix elsewhere; file a follow-up for out-of-scope; reply, then resolve.
+
+### 5. Finalize and hand off
+
+When the change meets the [Definition of Ready for Review](../Ways-of-Working/Definition-of-Ready-and-Done.md):
+
+1. Finalize the title, release-note description, and label per [PR Format](../Ways-of-Working/PR-Format.md).
+2. Mark the pull request ready and enable auto-merge per [Branching and Merging](../Ways-of-Working/Branching-and-Merging.md).
+
+## Operating rules
+
+1. Micro-commits, one logical change each, with descriptive messages.
+2. Progress is visible — issues updated as tasks complete, not in bulk.
+3. Draft pull request from the start; stay in the issue's scope.
+4. Mark ready only when the change meets the Definition of Ready for Review — never with open tasks.
+5. No planning from scratch (that is [Define](define.md)); no reviewing others' pull requests (that is [Reviewer](reviewer.md)).
+
+## Where this connects
+
+- [Contribution Workflow](../Ways-of-Working/Contribution-Workflow.md) — the draft-first loop this runs.
+- [Definition of Ready and Done](../Ways-of-Working/Definition-of-Ready-and-Done.md) — the gate this hands off at.
+- [PR Format](../Ways-of-Working/PR-Format.md) and [Branching and Merging](../Ways-of-Working/Branching-and-Merging.md) — packaging and landing.