From d77d3ca37ceaf525a671c3fddb4147405b386d7a Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 14:55:49 +0200 Subject: [PATCH 1/4] Document agentic development framework --- .github/copilot-instructions.md | 2 + AGENTS.md | 17 +- .../Frameworks/Agentic-Development/design.md | 272 ++++++++++++++++++ .../Frameworks/Agentic-Development/index.md | 19 ++ .../Frameworks/Agentic-Development/spec.md | 94 ++++++ src/docs/Frameworks/index.md | 1 + src/zensical.toml | 5 + 7 files changed, 408 insertions(+), 2 deletions(-) create mode 100644 src/docs/Frameworks/Agentic-Development/design.md create mode 100644 src/docs/Frameworks/Agentic-Development/index.md create mode 100644 src/docs/Frameworks/Agentic-Development/spec.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3884664..bc4546c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1 +1,3 @@ Follow the instructions in [AGENTS.md](../AGENTS.md). + +Before loading project standards or memory, segment the work by host, organization, repository, path, and current task. This repository is `github.com/MSXOrg/docs`; use MSXOrg docs and memory unless the user explicitly asks for another organization. Apply path-specific instructions only after the project segment is resolved. diff --git a/AGENTS.md b/AGENTS.md index 505539b..7225932 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,8 +5,9 @@ This repository is the central documentation for the MSX ecosystem. Everything a ## 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. +2. Resolve the project segment before loading standards: host, organization, repository, path, and task. This repository is `github.com/MSXOrg/docs`; use MSXOrg context unless the task explicitly asks for another organization. +3. Read the [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — how work flows from idea to delivery. +4. Load the [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) relevant to the change. ## Roles @@ -25,6 +26,18 @@ Agent behaviour is authored once, as documentation, in the [Agents](https://msxo - [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). +## Context segmentation + +Before acting, segment the work by scope: + +1. **Host** — `github.com` or `dnb.ghe.com`. +2. **Organization** — the project boundary, such as `MSXOrg`, `PSModule`, or `AI-Platform`. +3. **Repository** — the product, docs, or memory repository receiving the change. +4. **Path** — the file area and any path-specific standards that apply. +5. **Task** — the issue, prompt, branch, PR, diagnostics, and open files. + +Load only the docs and memory for the resolved organization. Do not apply another organization's standards or memory unless the user explicitly asks for cross-organization work. + ## 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/). diff --git a/src/docs/Frameworks/Agentic-Development/design.md b/src/docs/Frameworks/Agentic-Development/design.md new file mode 100644 index 0000000..c4fb6b4 --- /dev/null +++ b/src/docs/Frameworks/Agentic-Development/design.md @@ -0,0 +1,272 @@ +--- +title: Design +description: How the agentic development framework is built — OKF documentation, org memory, thin repo pointers, and deterministic context resolution. +--- + +# Agentic Development — Design + +The behaviour in the [spec](spec.md) is delivered by an organization-level documentation and memory pair, adopted by each product repository through thin pointer files. The design keeps project knowledge in one reviewed place, keeps working memory in one durable place, and lets each agent runtime adapt without copying process knowledge. + +## Organization anatomy + +The GitHub organization is the project boundary. The host distinguishes work from personal projects; the organization selects the project context. + +```text +// + docs/ # canonical knowledge base; changes through pull requests + memory/ # durable agent and team memory; versioned working knowledge + / # product or component repository + / +``` + +Current project scopes follow the same shape: + +| Host | Organization | Docs | Memory | +| --- | --- | --- | --- | +| `dnb.ghe.com` | `AI-Platform` | `AI-Platform/docs` | `AI-Platform/memory` | +| `github.com` | `MSXOrg` | `MSXOrg/docs` | `MSXOrg/memory` | +| `github.com` | `PSModule` | `PSModule/docs` | `PSModule/memory` | + +## Repository roles + +### `docs` + +The `docs` repository is the canonical knowledge base. It owns: + +- vision, principles, and ways of working; +- coding standards and documentation standards; +- framework and capability specs and designs; +- project glossary and onboarding; +- agent role descriptions and integration guidance. + +Changes to `docs` happen through pull requests because this repository defines durable project intent. + +### `memory` + +The `memory` repository is the durable working-memory store. It owns: + +- recurring gotchas and lessons learned; +- active project context that should survive a single chat session; +- agent role working knowledge; +- issue, PR, and incident notes worth reusing; +- project-specific preferences that are factual rather than private user preference. + +Memory pages stay short and factual. They are safe to read before work begins and safe to improve when a lesson is learned. + +### Product repositories + +Product repositories carry local context and thin pointers: + +```text +/ + AGENTS.md + CLAUDE.md + .github/ + copilot-instructions.md + instructions/ + .instructions.md + README.md + docs/ +``` + +The repository owns only repository-specific nuance: build commands, architecture notes, local exceptions, and path-scoped rules. Cross-cutting standards remain in `docs`; reusable lessons remain in `memory`. + +## OKF page model + +Both `docs` and `memory` use the [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) style: Markdown with YAML frontmatter, one concept per page, paths as stable identity, and indexes as navigation maps. + +Minimum page frontmatter: + +```yaml +--- +title: Agentic Development +description: One-line description of the page. +--- +``` + +Memory pages MAY add scope-oriented metadata when it helps agents filter context: + +```yaml +--- +title: GitHub Actions cache gotchas +description: Reusable notes for cache failures and permissions. +scope: project +tags: + - github-actions + - cache + - gotcha +--- +``` + +The body stays concise. If a page grows into multiple concepts, split it and link through the nearest `index.md`. + +## Indexes as the mindmap + +Indexes are the navigation layer. An agent starts at the root index, reads descriptions, then drills inward until it reaches the relevant page. + +```text +docs/ + index.md + Ways-of-Working/index.md + Coding-Standards/index.md + Frameworks/index.md + Frameworks/Agentic-Development/index.md + +memory/ + index.md + agents/index.md + knowledge/index.md + gotchas/index.md +``` + +Every index describes what sits below it. Generated indexes are preferred where tooling exists; manually maintained indexes are acceptable when the memory repository is intentionally lightweight. + +## Context resolution flow + +```mermaid +flowchart TD + start["Agent receives task"] --> policy["System and client policy"] + policy --> user["User-global preferences"] + user --> locate["Detect host, org, and repo"] + + locate --> host{"Which project scope?"} + host -->|"dnb.ghe.com / AI-Platform"| aip["AI-Platform context"] + host -->|"github.com / MSXOrg"| msx["MSXOrg context"] + host -->|"github.com / PSModule"| psmodule["PSModule context"] + + aip --> aipdocs["Read AI-Platform/docs index"] + aipdocs --> aipmemory["Read AI-Platform/memory index"] + + msx --> msxdocs["Read MSXOrg/docs index"] + msxdocs --> msxmemory["Read MSXOrg/memory index"] + + psmodule --> psdocs["Read PSModule/docs index"] + psdocs --> psmemory["Read PSModule/memory index"] + + aipmemory --> repo["Read repository pointer files"] + msxmemory --> repo + psmemory --> repo + + repo --> path["Apply path-specific instructions"] + path --> task["Read issue, PR, branch, diff, diagnostics, and open files"] + task --> act["Plan and act with the selected project personality"] + + act --> newpath{"New file path touched?"} + newpath -->|"Yes"| path + newpath -->|"No"| done["Respond, commit, or open PR"] +``` + +Resolution is deterministic. If the active repository remote is `github.com/PSModule/Json`, the selected project context is `PSModule`; if it is `github.com/MSXOrg/docs`, the selected project context is `MSXOrg`. Multi-root workspaces use the active file, explicit user prompt, current terminal directory, or branch repository to select the project. Ambiguity is resolved by asking the user before acting. + +## Pointer files + +`AGENTS.md` is the cross-runtime pointer file. It identifies the project, names the canonical docs and memory roots, and lists local nuance. + +```markdown +# Agent Instructions + +This repository belongs to `github.com/MSXOrg`. + +Canonical project context: + +- `github.com/MSXOrg/docs` +- `github.com/MSXOrg/memory` + +Before changing files: + +1. Segment the work by host, organization, repository, path, and task. +2. Read the relevant index in the resolved project docs repository. +3. Read relevant project memory for the resolved organization. +4. Read this repository's README and local docs. +5. Apply path-specific instructions for the files being changed. + +This file points; it does not define process knowledge. +``` + +`CLAUDE.md` stays a thin import: + +```markdown +@AGENTS.md +``` + +`.github/copilot-instructions.md` points Copilot to the same root and adds only Copilot-specific loading guidance: + +```markdown +Follow `AGENTS.md`. + +Segment the work by host, organization, repository, path, and task before loading project standards or memory. Resolve organization docs and memory before editing. Use path-specific instruction files when their `applyTo` pattern matches a file being read, generated, reviewed, or edited. +``` + +Path-specific instruction files are reserved for local rules that cannot live centrally because they apply only to a repository path. + +## Local workspace + +A local bootstrap makes central context predictable: + +```text +~/.msx/ + AI-Platform/ + docs/ + memory/ + MSXOrg/ + docs/ + memory/ + PSModule/ + docs/ + memory/ +``` + +The bootstrap clones missing repositories and fast-forwards existing clones when possible. It writes repository-local git configuration only. If a context repository cannot update, the agent uses the local copy and reports that it may be stale. + +## Memory writing rules + +Agents write memory only when a lesson is likely to matter again. Good memory is: + +- short and factual; +- scoped to the organization; +- linked to the issue, PR, repository, or document that proves it; +- free of secrets, credentials, and private personal notes; +- updated or removed when it becomes wrong. + +Session-specific notes stay out of durable memory unless they become reusable project knowledge. + +## Client behaviour + +Different clients load different files, but the framework keeps the same dependency direction: + +| Client | Adapter | Behaviour | +| --- | --- | --- | +| Cross-client agents | `AGENTS.md` | Read the shared project pointer and local nuance. | +| Claude Code | `CLAUDE.md` | Import `AGENTS.md`; add no duplicated process knowledge. | +| GitHub Copilot in VS Code | `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` | Read project pointers, then apply path-specific instructions when files match. | +| Copilot coding agent | `AGENTS.md`, `.github/copilot-instructions.md`, setup workflow | Prepare the local context before implementation and follow the same project roots. | +| Copilot code review | Base-branch instructions | Review using trusted base-branch instructions rather than instructions changed by the PR under review. | + +## Failure modes + +| Failure | Design response | +| --- | --- | +| Repository does not identify its organization context | Infer from remote URL; ask when ambiguous. | +| Docs or memory clone is missing | Bootstrap it before work; if unavailable, continue only with explicit warning. | +| Pointer file duplicates central standards | Replace duplicated content with links during review. | +| Memory conflicts with docs | Docs win; memory is corrected or removed. | +| Two organizations are open in one workspace | Select by active repository; ask before cross-project changes. | +| A client ignores one pointer format | Add a thin adapter for that client that points to the same canonical roots. | + +## Adoption path + +1. Create or identify the organization `docs` repository. +2. Create or identify the organization `memory` repository. +3. Add `docs/index.md` and `memory/index.md` as the two root maps. +4. Add framework docs, standards, and agent role descriptions to `docs`. +5. Add starter memory sections to `memory`. +6. Add thin pointer files to each product repository. +7. Add a bootstrap that keeps local docs and memory clones present. +8. Review new work for pointer discipline: facts live once, links point to them. + +## Where this connects + +- [Spec](spec.md) — the requirements this design delivers. +- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) — the way-of-working standard this framework implements. +- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why spec and design are split. +- [README-Driven Context](../../Ways-of-Working/Readme-Driven-Context.md) — why local repository context remains the front door. diff --git a/src/docs/Frameworks/Agentic-Development/index.md b/src/docs/Frameworks/Agentic-Development/index.md new file mode 100644 index 0000000..c72923c --- /dev/null +++ b/src/docs/Frameworks/Agentic-Development/index.md @@ -0,0 +1,19 @@ +--- +title: Agentic Development +description: The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behaviour. +--- + +# Agentic Development + +The Agentic Development framework makes an organization the operating boundary for human and agent work. Each organization owns a `docs` repository for canonical knowledge and a `memory` repository for accumulated working context; every product repository points to those two roots and adds only local nuance. + +A repository adopts the framework by carrying thin agent pointer files and by letting agents resolve context through the organization first, then the repository, then the current task. + + + +| Page | Description | +| --- | --- | +| [Spec](spec.md) | Requirements for the agentic development framework — org-scoped documentation, memory, and pointer files that make agents behave correctly per project. | +| [Design](design.md) | How the agentic development framework is built — OKF documentation, org memory, thin repo pointers, and deterministic context resolution. | + + diff --git a/src/docs/Frameworks/Agentic-Development/spec.md b/src/docs/Frameworks/Agentic-Development/spec.md new file mode 100644 index 0000000..182962e --- /dev/null +++ b/src/docs/Frameworks/Agentic-Development/spec.md @@ -0,0 +1,94 @@ +--- +title: Spec +description: Requirements for the agentic development framework — org-scoped documentation, memory, and pointer files that make agents behave correctly per project. +--- + +# Agentic Development — Spec + +## Premise + +An agent does useful work only when it knows which project it is serving, which standards apply, and what the team has already learned. That context MUST be project-scoped, durable, reviewable, and readable by humans and agents alike. The project boundary is the GitHub organization: `dnb.ghe.com/AI-Platform`, `github.com/MSXOrg`, `github.com/PSModule`, and any future organization that adopts the framework. + +Each organization owns two canonical repositories: + +- `docs` — the reviewed knowledge base: vision, standards, workflows, specs, designs, glossary, onboarding, and project-wide rules. +- `memory` — the durable agent working memory: lessons learned, recurring gotchas, active context, agent role knowledge, and project-specific operating notes. + +Product repositories do not copy that knowledge. They carry thin pointer files that identify the organization context and direct agents to the relevant `docs` and `memory` roots before acting. + +### Principles + +This framework rests on the [Principles](../../Ways-of-Working/Principles/index.md): + +- **[Documentation lives close to the thing it documents](../../Ways-of-Working/Principles/Engineering-Practices.md#documentation-lives-close-to-the-thing-it-documents).** Organization-wide ways of working live in the organization `docs` repository; repository-specific nuance lives in the repository. +- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** Standards and memory are plain files in git. Changes are reviewed, diffed, and reverted like code. +- **[Written once, referenced everywhere](../../Ways-of-Working/Agentic-Development.md#principles).** Agent instructions point to canonical docs and memory rather than duplicating them. +- **[AI-first development](../../Ways-of-Working/Principles/AI-First-Development.md).** Humans create durable context; agents consume that context and leave useful improvements behind. + +## Scope + +Applies to any organization that wants a shared project knowledge base and memory store for agents across multiple repositories. + +**In scope** + +- Organization-level `docs` and `memory` repositories. +- Markdown documents with YAML frontmatter, following the [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) model. +- Thin repository pointer files such as `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, and path-scoped instruction files. +- Deterministic context resolution by host, organization, repository, path, and task. +- Human-reviewed changes to canonical knowledge through pull requests. +- Durable agent memory that can be shared by every person and agent working in the organization. + +**Out of scope** + +- A vendor-specific runtime implementation for one agent client. +- Secret storage, credential distribution, or production access management. +- Replacing issue tracking, pull requests, or code review. +- A central database or service for context retrieval. + +## Requirements + +- **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. +- **Canonical memory repository.** Each adopting organization MUST have a `memory` repository that owns durable project memory and agent working knowledge. +- **OKF-style documents.** Knowledge and memory 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 and memory 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 pointer files that identify the organization context and link to the canonical docs and memory roots. Pointer files MUST NOT duplicate standards or process knowledge. +- **Segmentation before loading.** Local agent files MUST instruct agents to segment work by host, organization, repository, path, and task before loading project standards or memory. +- **Client adapters.** Tool-specific files such as `CLAUDE.md`, `.github/copilot-instructions.md`, and `.github/instructions/*.instructions.md` MAY add runtime-specific loading rules, but MUST point back to the same canonical docs and memory. +- **Deterministic context resolution.** Agents MUST resolve context in layers: system and client policy, user preferences, organization docs, organization memory, repository pointers, path-specific instructions, then current task context. +- **Local-first availability.** The docs and memory repositories SHOULD be available locally in a predictable workspace so agents can read them without relying on search or web access. +- **Reviewed knowledge changes.** Changes to the `docs` repository MUST happen through pull requests. Changes to memory MAY be lighter-weight, but MUST remain versioned in git. +- **No cross-project bleed.** An agent working in one organization MUST NOT apply another organization's standards or memory unless the current task explicitly asks for cross-organization work. +- **Traceable memory.** Memory entries SHOULD identify the context they came from and SHOULD be short, factual, and linked to the relevant issue, pull request, document, or repository when one exists. + +## Success criteria + +- An agent working in `github.com/PSModule/` reads PSModule docs and memory, not MSXOrg or AI-Platform rules. +- An agent working in `github.com/MSXOrg/` resolves `github.com/MSXOrg/docs` and `github.com/MSXOrg/memory` as the canonical project context. +- An agent working in `dnb.ghe.com/AI-Platform/` resolves `dnb.ghe.com/AI-Platform/docs` and `dnb.ghe.com/AI-Platform/memory` as the canonical project context. +- A new product repository can adopt the framework by adding pointer files without copying standards or memory pages. +- A human can start at `docs/index.md` or `memory/index.md` and navigate to the same context an agent uses. +- Updating a standard in `docs` changes the canonical guidance without editing every repository. +- Capturing a recurring lesson in `memory` makes it available to later agents working in the same organization. + +## Context resolution contract + +The framework uses this normative resolution order: + +1. **System and client policy** — non-project instructions imposed by the agent runtime. +2. **User-global preferences** — the human operator's baseline style and risk posture. +3. **Host and organization** — the project identity, derived from the current repository remote or explicit task. +4. **Organization docs** — the organization `docs` repository root index, then relevant standards, workflows, specs, and designs. +5. **Organization memory** — the organization `memory` repository root index, then relevant lessons, gotchas, and active context. +6. **Repository pointer files** — `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, and related local instructions. +7. **Path-specific instructions** — scoped rules that apply to the files being read, generated, reviewed, or edited. +8. **Current task context** — issue, pull request, prompt, branch, diff, diagnostics, terminal output, and open files. + +A lower layer MAY refine a higher layer, but MUST NOT contradict it unless the higher layer explicitly allows a local exception. + +## Where this connects + +- [Design](design.md) — how these requirements are delivered. +- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) — the existing way-of-working standard this framework operationalizes. +- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — how specs and designs are written and kept evergreen. +- [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) — the Markdown and frontmatter model used for knowledge pages. diff --git a/src/docs/Frameworks/index.md b/src/docs/Frameworks/index.md index 651d865..8eacc0e 100644 --- a/src/docs/Frameworks/index.md +++ b/src/docs/Frameworks/index.md @@ -18,6 +18,7 @@ cover how it works, how to use it, and how to configure it. | Section | Description | | --- | --- | +| [Agentic Development](Agentic-Development/index.md) | The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behaviour. | | [Process-PSModule](Process-PSModule/index.md) | The end-to-end GitHub Actions workflow that builds, tests, versions, and publishes every PSModule PowerShell module — configured through a single settings file. | diff --git a/src/zensical.toml b/src/zensical.toml index e45e900..453cf56 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -121,6 +121,11 @@ nav = [ ]}, {"Frameworks" = [ "Frameworks/index.md", + {"Agentic Development" = [ + "Frameworks/Agentic-Development/index.md", + {"Spec" = "Frameworks/Agentic-Development/spec.md"}, + {"Design" = "Frameworks/Agentic-Development/design.md"}, + ]}, {"Process-PSModule" = [ "Frameworks/Process-PSModule/index.md", {"Pipeline Stages" = "Frameworks/Process-PSModule/pipeline-stages.md"}, From c5f9c15c74dc27bfc4c9684aceaff8cc0b7a996b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 14:59:46 +0200 Subject: [PATCH 2/4] Use US English in agentic development docs --- AGENTS.md | 2 +- src/docs/Frameworks/Agentic-Development/design.md | 6 +++--- src/docs/Frameworks/Agentic-Development/index.md | 2 +- src/docs/Frameworks/index.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7225932..fbaa41f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ This repository is the central documentation for the MSX ecosystem. Everything a ## 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: +Agent behavior 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. diff --git a/src/docs/Frameworks/Agentic-Development/design.md b/src/docs/Frameworks/Agentic-Development/design.md index c4fb6b4..fcebed2 100644 --- a/src/docs/Frameworks/Agentic-Development/design.md +++ b/src/docs/Frameworks/Agentic-Development/design.md @@ -5,7 +5,7 @@ description: How the agentic development framework is built — OKF documentatio # Agentic Development — Design -The behaviour in the [spec](spec.md) is delivered by an organization-level documentation and memory pair, adopted by each product repository through thin pointer files. The design keeps project knowledge in one reviewed place, keeps working memory in one durable place, and lets each agent runtime adapt without copying process knowledge. +The behavior in the [spec](spec.md) is delivered by an organization-level documentation and memory pair, adopted by each product repository through thin pointer files. The design keeps project knowledge in one reviewed place, keeps working memory in one durable place, and lets each agent runtime adapt without copying process knowledge. ## Organization anatomy @@ -230,11 +230,11 @@ Agents write memory only when a lesson is likely to matter again. Good memory is Session-specific notes stay out of durable memory unless they become reusable project knowledge. -## Client behaviour +## Client behavior Different clients load different files, but the framework keeps the same dependency direction: -| Client | Adapter | Behaviour | +| Client | Adapter | Behavior | | --- | --- | --- | | Cross-client agents | `AGENTS.md` | Read the shared project pointer and local nuance. | | Claude Code | `CLAUDE.md` | Import `AGENTS.md`; add no duplicated process knowledge. | diff --git a/src/docs/Frameworks/Agentic-Development/index.md b/src/docs/Frameworks/Agentic-Development/index.md index c72923c..883b383 100644 --- a/src/docs/Frameworks/Agentic-Development/index.md +++ b/src/docs/Frameworks/Agentic-Development/index.md @@ -1,6 +1,6 @@ --- title: Agentic Development -description: The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behaviour. +description: The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behavior. --- # Agentic Development diff --git a/src/docs/Frameworks/index.md b/src/docs/Frameworks/index.md index 8eacc0e..343474c 100644 --- a/src/docs/Frameworks/index.md +++ b/src/docs/Frameworks/index.md @@ -18,7 +18,7 @@ cover how it works, how to use it, and how to configure it. | Section | Description | | --- | --- | -| [Agentic Development](Agentic-Development/index.md) | The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behaviour. | +| [Agentic Development](Agentic-Development/index.md) | The framework for org-scoped docs and memory repositories that give agents project-specific standards, working knowledge, and behavior. | | [Process-PSModule](Process-PSModule/index.md) | The end-to-end GitHub Actions workflow that builds, tests, versions, and publishes every PSModule PowerShell module — configured through a single settings file. | From 1232bfe95601b5e3b794f0442f9754fb48298aed Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 15:08:36 +0200 Subject: [PATCH 3/4] Add natural language coding standard --- src/docs/Coding-Standards/Natural-Language.md | 184 ++++++++++++++++++ src/docs/Coding-Standards/index.md | 1 + src/zensical.toml | 1 + 3 files changed, 186 insertions(+) create mode 100644 src/docs/Coding-Standards/Natural-Language.md diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md new file mode 100644 index 0000000..18269e1 --- /dev/null +++ b/src/docs/Coding-Standards/Natural-Language.md @@ -0,0 +1,184 @@ +--- +title: Natural Language +description: Plain-language writing rules for docs, issues, pull requests, comments, prompts, and agent-facing text — with US English as the project dialect. +--- + +# Natural Language + +Natural language is source code for humans and agents. It drives issues, pull requests, documentation, prompts, comments, error messages, release notes, and memory. Write it with the same care as code: clear, testable, consistent, and easy to change. + +This standard defines the writing style for English prose in the MSX ecosystem. The project dialect is **US English**. + +## Use US English + +Use US spelling and vocabulary in all new and changed prose. + +| Use | Avoid | +| --- | --- | +| behavior | behaviour | +| color | colour | +| customize | customise | +| organization | organisation | +| organize | organise | +| license | licence | +| labeled | labelled | +| serializes | serialises | +| center | centre | +| analyze | analyse | +| optimize | optimise | +| artifact | artefact | + +Do not churn unrelated existing text just to change spelling. Update nearby text when you are already editing it, and keep new pages internally consistent. + +## Write for the next reader + +Assume the reader has competence but no local context. The reader may be a human contributor, a maintainer reviewing a PR, or an agent resolving task context. + +- Lead with the point. +- State one idea per paragraph. +- Prefer concrete nouns and active verbs. +- Use examples when they shorten the explanation. +- Link to canonical docs instead of restating them. +- Remove words that do not change meaning. + +## Be direct and specific + +Prefer specific, observable language over vague intent. + +| Prefer | Avoid | +| --- | --- | +| `The workflow fails when the version label is missing.` | `There may be some issues with labels.` | +| `Add `NoRelease` to documentation-only PRs.` | `Make sure docs PRs are handled correctly.` | +| `The agent reads `AGENTS.md` before editing files.` | `The agent should probably look at the instructions.` | + +Use **MUST**, **SHOULD**, and **MAY** only when a sentence is intentionally normative. If a rule is optional, say what trade-off decides it. + +## Keep pages small + +Natural-language pages follow the same rule as functions: one responsibility. If a page grows into several concepts, split it and add links from the nearest index. + +A good page: + +- has one primary concept; +- starts with the current rule or model; +- links outward instead of duplicating context; +- can be read in one sitting; +- gives agents enough context to act correctly. + +## Write evergreen prose + +Write the current truth, not the history of how it became true. + +- Use present tense. +- Do not include changelog language in the body. +- Do not write "currently", "new", or "recently" unless time is the subject. +- Do not keep obsolete caveats as warnings after the caveat is gone. +- Let git history and pull requests carry the timeline. + +Good: + +> The docs repository owns organization-wide standards. + +Avoid: + +> We recently moved organization-wide standards into the docs repository. + +## Make agent-facing text executable + +Instructions for agents should be ordered, scoped, and verifiable. A good instruction tells the agent where to start, what to load, what not to do, and how to know it is done. + +Prefer: + +```markdown +Before editing: + +1. Resolve the host, organization, repository, path, and task. +2. Read the organization docs index. +3. Read relevant organization memory. +4. Read the repository README and local instructions. +5. Apply path-specific instructions for files being changed. +``` + +Avoid: + +```markdown +Understand the project and follow the right process. +``` + +## Use inclusive, impersonal language + +Use language that keeps focus on the work. + +- Prefer `the user`, `the contributor`, `the maintainer`, or `the agent` when a role matters. +- Use `you` in guides and instructions when it makes action clearer. +- Avoid blame language. Say what failed and what fixes it. +- Avoid idioms that are hard to translate or parse literally. + +## Error messages and warnings + +Error messages are documentation at the failure boundary. They should help the reader recover. + +A good error message includes: + +1. what failed; +2. why it failed, when known; +3. what to do next. + +Prefer: + +```text +Release label is missing. Add exactly one of Major, Minor, Patch, or NoRelease. +``` + +Avoid: + +```text +Invalid labels. +``` + +## Pull requests and release notes + +PR titles and descriptions are written for the user of the change first, then the reviewer. Describe the outcome, not the internal implementation. + +| Prefer | Avoid | +| --- | --- | +| `📖 [Docs]: Agentic development framework documented` | `Update framework docs` | +| `Agents segment project context before loading standards.` | `Refactor AGENTS.md instructions.` | + +Technical implementation details belong in a clearly named technical section at the bottom of the PR body. + +## Prompts + +Prompts are requests, not guesses. A good prompt names the desired outcome, the scope, and the constraints. + +Prefer: + +```text +Create a spec and design for org-scoped agent docs and memory in MSXOrg/docs. Follow the existing spec/design documentation model and use US English. +``` + +Avoid: + +```text +Make something for agents. +``` + +## Memory notes + +Memory notes should be short, factual, and reusable. They should not be a transcript of a session. + +Include: + +- the durable lesson; +- the affected project or repository; +- links to the issue, PR, file, or command that proves it; +- the date when the fact was learned, if timing matters. + +Do not include secrets, private personal notes, or speculation. + +## Where this connects + +- [Documentation](Documentation.md) — where documentation lives and what it explains. +- [Markdown](Markdown.md) — Markdown syntax and linted formatting rules. +- [Agentic Development](../Ways-of-Working/Agentic-Development.md) — how agents consume the same docs as humans. +- [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md) — why the README is the repository front door. diff --git a/src/docs/Coding-Standards/index.md b/src/docs/Coding-Standards/index.md index ce2c228..9acdeed 100644 --- a/src/docs/Coding-Standards/index.md +++ b/src/docs/Coding-Standards/index.md @@ -22,6 +22,7 @@ The baseline pages apply to all code and come first; the per-language standards | [Functions](Functions.md) | One responsibility, contracts in the signature, and validation at the boundary. | | [Error Handling](Error-Handling.md) | Fail fast, never swallow, and write messages that help the next person. | | [Documentation](Documentation.md) | Help that lives next to the code and explains the why. | +| [Natural Language](Natural-Language.md) | Plain-language writing rules for docs, issues, pull requests, comments, prompts, and agent-facing text — with US English as the project dialect. | | [Testing](Testing.md) | The executable specification — test-first, locally runnable, deterministic. | | [Performance](Performance.md) | Scale with the input, measure before optimizing, clarity first. | | [Security](Security.md) | Least privilege, secret hygiene, and the OWASP baseline. | diff --git a/src/zensical.toml b/src/zensical.toml index 453cf56..29d1f29 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -75,6 +75,7 @@ nav = [ {"Functions" = "Coding-Standards/Functions.md"}, {"Error Handling" = "Coding-Standards/Error-Handling.md"}, {"Documentation" = "Coding-Standards/Documentation.md"}, + {"Natural Language" = "Coding-Standards/Natural-Language.md"}, {"Testing" = "Coding-Standards/Testing.md"}, {"Performance" = "Coding-Standards/Performance.md"}, {"Security" = "Coding-Standards/Security.md"}, From 4e74f615238eaade7d2ec07cb6350df3c0a5d8f8 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 16:33:25 +0200 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Update=20examples?= =?UTF-8?q?=20for=20clarity=20in=20natural=20language=20coding=20standards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/docs/Coding-Standards/Natural-Language.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md index 18269e1..8c238f6 100644 --- a/src/docs/Coding-Standards/Natural-Language.md +++ b/src/docs/Coding-Standards/Natural-Language.md @@ -47,9 +47,9 @@ Prefer specific, observable language over vague intent. | Prefer | Avoid | | --- | --- | -| `The workflow fails when the version label is missing.` | `There may be some issues with labels.` | -| `Add `NoRelease` to documentation-only PRs.` | `Make sure docs PRs are handled correctly.` | -| `The agent reads `AGENTS.md` before editing files.` | `The agent should probably look at the instructions.` | +| The workflow fails when the version label is missing. | There may be some issues with labels. | +| Add `NoRelease` to documentation-only PRs. | Make sure docs PRs are handled correctly. | +| The agent reads `AGENTS.md` before editing files. | The agent should probably look at the instructions. | Use **MUST**, **SHOULD**, and **MAY** only when a sentence is intentionally normative. If a rule is optional, say what trade-off decides it.