📖 [Docs]: Central agent model — descriptions, AGENTS.md/CLAUDE.md pointers, and a git-isolated workspace bootstrap#31
Merged
Conversation
Marius Storhaug (MariusStorhaug)
added
documentation
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 08:59
View session
There was a problem hiding this comment.
Pull request overview
This PR centralizes agent role documentation into a new Agents docs section and adds lightweight, repo-root pointer files (AGENTS.md, CLAUDE.md) so agent runtimes can discover the canonical role descriptions from a single place.
Changes:
- Adds a new
src/docs/Agents/section with role pages (Define, Implement, Reviewer, Security Reviewer, Agent Author) and an index. - Updates Ways of Working principles/docs to describe the new “central descriptions + local pointer files” model (removing the prior
.github-privateframing). - Wires the new section into navigation and adds repo-root pointer files for agent tooling (
AGENTS.mdandCLAUDE.md).
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
src/zensical.toml |
Adds the Agents section and pages to site navigation. |
src/docs/Ways-of-Working/Principles/AI-First-Development.md |
Updates the 3-layer agent context model to reference central Agents docs + per-repo pointer files. |
src/docs/Ways-of-Working/Agentic-Development.md |
Updates the plug-in/distribution model to point at Agents docs and AGENTS.md/CLAUDE.md. |
src/docs/index.md |
Adds Agents to the top-level documentation map index table. |
src/docs/Agents/index.md |
New Agents section landing page + generated index table region. |
src/docs/Agents/define.md |
Defines the Define agent role (issue capture/refinement/planning). |
src/docs/Agents/implement.md |
Defines the Implement agent role (delivery loop to a review-ready PR). |
src/docs/Agents/reviewer.md |
Defines the Reviewer agent role (PR review/approval responsibilities and constraints). |
src/docs/Agents/security-reviewer.md |
Defines the Security Reviewer role (defensive security review output and constraints). |
src/docs/Agents/agent-author.md |
Defines the Agent Author role (maintaining role docs and keeping pointer files thin). |
AGENTS.md |
Adds repo-root agent pointer file referencing canonical Agents + Ways of Working + Coding Standards URLs. |
CLAUDE.md |
Adds Claude-specific entrypoint that imports AGENTS.md via @AGENTS.md. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…y under ~/.msx Adds bootstrap/ (Initialize-MsxWorkspace.ps1 + AGENTS.template.md + README) and documents the model in Agentic Development. Each runtime's native entry file becomes a thin bootstrap that clones MSXOrg/docs and MSXOrg/memory to ~/.msx with repository-local git config; docs change via PR, memory pushes to main.
Marius Storhaug (MariusStorhaug)
changed the title
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:29
View session
… identity default, clone guard Say 'modifies' not 'touches' (git reads global config; script writes only repo-local) across the script, README, template, and Agentic Development; default identity to a GitHub noreply (no personal email in a public script); throw a clear error when the target path exists but is not a git repository.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:36
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:42
View session
Reword the inline identity comment to say the script only writes repo-local config (git still reads global/system); add an explicit README warning to override -UserName/-UserEmail when not the maintainer.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:52
View session
Copilot review round 4 on #31: replace restated rules (branch naming, draft timing, mark-ready criteria) with links to Branching and Merging, Git Worktrees, Contribution Workflow, and Definition of Ready and Done — consistent with 'this file points; it never defines.'
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:00
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:43
View session
…, clarify entry file Copilot review round 8 on #31: reword the remaining 'fast-forwards' overstatements (script .EXAMPLE, README bullet); guard both install snippets against a path that exists but is not a git repo; emit a runtime warning when the default maintainer identity is used; and clarify in Agentic Development that the bootstrap is the user-global entry, distinct from the per-repo AGENTS.md/CLAUDE.md pointers.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:50
View session
Copilot review round 9 on #31: the identity warning now fires when either -UserName or -UserEmail is not explicitly provided, not just -UserEmail.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:56
View session
Copilot review round 10 on #31: drop the restated linter rule from the root AGENTS.md 'Start here'; steer the bootstrap template to user-level Copilot instructions only, keeping per-repo AGENTS.md a thin pointer.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 13:01
View session
Copilot review round 11 on #31: check \0 after the two git config writes (consistent with the other git calls); note the private MSXOrg/memory prerequisite in the README and the template.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 13:12
View session
Reduce both files to bare pointers so agents follow AGENTS.md without extra prose that could distract or conflict. Add the Copilot instructions under .github so Copilot picks them up natively.
Document parameters inline instead of .PARAMETER, add .OUTPUTS, gate state-changing operations with SupportsShouldProcess/ShouldProcess (matching Wait-CopilotReview.ps1), and emit result objects instead of Format-Table plus a status string.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 13:43
View session
Install snippets (README + AGENTS.template) now check \0 after git clone and throw a clear error, so a failed first-time clone fails diagnostically instead of running the script from a missing path. Initialize-MsxWorkspace.ps1 adds ValidateNotNullOrEmpty to -Root, -UserName, and -UserEmail so accidental empty overrides fail early. Addresses Copilot review on PR #31.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 13:51
View session
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The agent model is now complete: agent roles are documented once in a central Agents section, every repository can point to them, and — the new piece — an agent's first instruction bootstraps a single, git-isolated local workspace so it always starts from the same docs and memory.
New: The Agents section
A new Agents section documents the roles agents play — Define, Implement, Reviewer, Security Reviewer, and Agent Author — each grounded in the ways of working rather than restating them.
New: The workspace bootstrap
Each runtime's natively-read entry file (Copilot reads
AGENTS.md; Claude Code readsCLAUDE.md, which imports the same instructions) becomes a thin bootstrap. Its first instruction clones the central repositories to a git-isolated workspace under~/.msx:~/.msx/docs— how work is done (this documentation), read as local files. Changed through pull requests.~/.msx/memory— durable notes and prior session context. Changed by pushing to main.Each clone carries repository-local git config only, so the workspace never touches the global git config or the repository being worked in. Setup is one idempotent script,
bootstrap/Initialize-MsxWorkspace.ps1.New: AGENTS.md and CLAUDE.md pointer files
The repository root carries an
AGENTS.mdand aCLAUDE.mdthat imports it, pointing to the central descriptions.Changed: The agent context model
Agentic Development and AI-First Development now describe agent context as central descriptions in the docs plus per-repository pointer files and the local workspace bootstrap — not organization-wide agent files in a private repository.
Technical Details
bootstrap/:Initialize-MsxWorkspace.ps1(clone/pull plus isolated git config for~/.msx/docsand~/.msx/memory),AGENTS.template.md(the user-global entry instruction), andREADME.md(install steps for Claude Code and Copilot).src/docs/Agents/:index.mdplusdefine,implement,reviewer,security-reviewer,agent-author.AGENTS.mdandCLAUDE.md(importsAGENTS.md).Agentic-Development.mdandPrinciples/AI-First-Development.md: plug-in, distribution, and three-layer models updated; added a "The workspace bootstrap" section; no.github-privatereference remains.zensical.toml: Agents added to navigation; index tables regenerated.MSXOrg/memory(private) holds the memory store; agents push notes there directly to main.Related issues