Skip to content

Commit 95d3ffa

Browse files
MariusStorhaugMariusStorhaug
authored
📖 [Docs]: Agentic development framework documented (#51)
The MSX documentation now defines Agentic Development as an adoptable framework for organization-scoped docs and memory repositories. Agents get explicit guidance for resolving the correct project context before acting, and the docs now define a Natural Language coding standard with US English as the project dialect. > ⚠️ This PR has no linked issue. Consider creating one for traceability. ## New: Agentic Development framework A new framework section documents how each organization owns a `docs` repository for canonical knowledge and a `memory` repository for durable agent working context. The framework describes the organization as the project boundary and explains how product repositories adopt it through thin pointer files rather than duplicated process knowledge. The new pages cover: - organization anatomy across `dnb.ghe.com/AI-Platform`, `github.com/MSXOrg`, and `github.com/PSModule`; - the contract for `docs` and `memory` repositories; - OKF-style Markdown and frontmatter expectations; - index-driven navigation as the project mindmap; - deterministic context resolution by host, organization, repository, path, and task; - client adapter behavior for `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and path-scoped instructions. ## New: Natural Language coding standard A new coding standard defines how English prose is written across docs, issues, pull requests, comments, prompts, agent instructions, error messages, release notes, and memory. The standard sets **US English** as the project dialect and gives concrete rules for clear, evergreen, agent-readable prose. It covers: - US spelling and vocabulary; - direct and specific language; - small pages and evergreen prose; - executable agent-facing instructions; - inclusive, impersonal wording; - useful error messages and warnings; - PR and release-note wording; - prompt and memory-note quality. ## Changed: Agents segment project context before loading standards The local agent pointer files now tell agents to segment work before loading project standards or memory. For this repository, agents resolve the current project as `github.com/MSXOrg/docs` and use MSXOrg context unless the task explicitly asks for another organization. This prevents a multi-root or multi-project workspace from accidentally applying PSModule or AI-Platform standards to MSXOrg work, or vice versa. ## Technical Details - Added `src/docs/Frameworks/Agentic-Development/index.md`. - Added `src/docs/Frameworks/Agentic-Development/spec.md`. - Added `src/docs/Frameworks/Agentic-Development/design.md`, including a Mermaid context-resolution flow. - Added `src/docs/Coding-Standards/Natural-Language.md`. - Added the framework and standard to generated indexes and `src/zensical.toml` navigation. - Updated `AGENTS.md` and `.github/copilot-instructions.md` with explicit host/org/repo/path/task segmentation guidance. - Updated the new and changed documentation to use US English. - Validation completed locally: - `pwsh .github/scripts/Test-DocumentationLink.ps1` - `pwsh .github/scripts/Update-DocumentationIndex.ps1 -Check` - `python -m zensical build --clean`
1 parent bec4ac3 commit 95d3ffa

8 files changed

Lines changed: 579 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
Follow the instructions in [AGENTS.md](../AGENTS.md).
2+
3+
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.

‎src/docs/Coding-Standards/Natural-Language.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Natural Language
3+
description: Plain-language writing rules for docs, issues, pull requests, comments, prompts, and agent-facing text — with US English as the project dialect.
4+
---
5+
6+
# Natural Language
7+
8+
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.
9+
10+
This standard defines the writing style for English prose in the MSX ecosystem. The project dialect is **US English**.
11+
12+
## Use US English
13+
14+
Use US spelling and vocabulary in all new and changed prose.
15+
16+
| Use | Avoid |
17+
| --- | --- |
18+
| behavior | behaviour |
19+
| color | colour |
20+
| customize | customise |
21+
| organization | organisation |
22+
| organize | organise |
23+
| license | licence |
24+
| labeled | labelled |
25+
| serializes | serialises |
26+
| center | centre |
27+
| analyze | analyse |
28+
| optimize | optimise |
29+
| artifact | artefact |
30+
31+
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.
32+
33+
## Write for the next reader
34+
35+
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.
36+
37+
- Lead with the point.
38+
- State one idea per paragraph.
39+
- Prefer concrete nouns and active verbs.
40+
- Use examples when they shorten the explanation.
41+
- Link to canonical docs instead of restating them.
42+
- Remove words that do not change meaning.
43+
44+
## Be direct and specific
45+
46+
Prefer specific, observable language over vague intent.
47+
48+
| Prefer | Avoid |
49+
| --- | --- |
50+
| The workflow fails when the version label is missing. | There may be some issues with labels. |
51+
| Add `NoRelease` to documentation-only PRs. | Make sure docs PRs are handled correctly. |
52+
| The agent reads `AGENTS.md` before editing files. | The agent should probably look at the instructions. |
53+
54+
Use **MUST**, **SHOULD**, and **MAY** only when a sentence is intentionally normative. If a rule is optional, say what trade-off decides it.
55+
56+
## Keep pages small
57+
58+
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.
59+
60+
A good page:
61+
62+
- has one primary concept;
63+
- starts with the current rule or model;
64+
- links outward instead of duplicating context;
65+
- can be read in one sitting;
66+
- gives agents enough context to act correctly.
67+
68+
## Write evergreen prose
69+
70+
Write the current truth, not the history of how it became true.
71+
72+
- Use present tense.
73+
- Do not include changelog language in the body.
74+
- Do not write "currently", "new", or "recently" unless time is the subject.
75+
- Do not keep obsolete caveats as warnings after the caveat is gone.
76+
- Let git history and pull requests carry the timeline.
77+
78+
Good:
79+
80+
> The docs repository owns organization-wide standards.
81+
82+
Avoid:
83+
84+
> We recently moved organization-wide standards into the docs repository.
85+
86+
## Make agent-facing text executable
87+
88+
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.
89+
90+
Prefer:
91+
92+
```markdown
93+
Before editing:
94+
95+
1. Resolve the host, organization, repository, path, and task.
96+
2. Read the organization docs index.
97+
3. Read relevant organization memory.
98+
4. Read the repository README and local instructions.
99+
5. Apply path-specific instructions for files being changed.
100+
```
101+
102+
Avoid:
103+
104+
```markdown
105+
Understand the project and follow the right process.
106+
```
107+
108+
## Use inclusive, impersonal language
109+
110+
Use language that keeps focus on the work.
111+
112+
- Prefer `the user`, `the contributor`, `the maintainer`, or `the agent` when a role matters.
113+
- Use `you` in guides and instructions when it makes action clearer.
114+
- Avoid blame language. Say what failed and what fixes it.
115+
- Avoid idioms that are hard to translate or parse literally.
116+
117+
## Error messages and warnings
118+
119+
Error messages are documentation at the failure boundary. They should help the reader recover.
120+
121+
A good error message includes:
122+
123+
1. what failed;
124+
2. why it failed, when known;
125+
3. what to do next.
126+
127+
Prefer:
128+
129+
```text
130+
Release label is missing. Add exactly one of Major, Minor, Patch, or NoRelease.
131+
```
132+
133+
Avoid:
134+
135+
```text
136+
Invalid labels.
137+
```
138+
139+
## Pull requests and release notes
140+
141+
PR titles and descriptions are written for the user of the change first, then the reviewer. Describe the outcome, not the internal implementation.
142+
143+
| Prefer | Avoid |
144+
| --- | --- |
145+
| `📖 [Docs]: Agentic development framework documented` | `Update framework docs` |
146+
| `Agents segment project context before loading standards.` | `Refactor AGENTS.md instructions.` |
147+
148+
Technical implementation details belong in a clearly named technical section at the bottom of the PR body.
149+
150+
## Prompts
151+
152+
Prompts are requests, not guesses. A good prompt names the desired outcome, the scope, and the constraints.
153+
154+
Prefer:
155+
156+
```text
157+
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.
158+
```
159+
160+
Avoid:
161+
162+
```text
163+
Make something for agents.
164+
```
165+
166+
## Memory notes
167+
168+
Memory notes should be short, factual, and reusable. They should not be a transcript of a session.
169+
170+
Include:
171+
172+
- the durable lesson;
173+
- the affected project or repository;
174+
- links to the issue, PR, file, or command that proves it;
175+
- the date when the fact was learned, if timing matters.
176+
177+
Do not include secrets, private personal notes, or speculation.
178+
179+
## Where this connects
180+
181+
- [Documentation](Documentation.md) — where documentation lives and what it explains.
182+
- [Markdown](Markdown.md) — Markdown syntax and linted formatting rules.
183+
- [Agentic Development](../Ways-of-Working/Agentic-Development.md) — how agents consume the same docs as humans.
184+
- [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md) — why the README is the repository front door.

‎src/docs/Coding-Standards/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The baseline pages apply to all code and come first; the per-language standards
2222
| [Functions](Functions.md) | One responsibility, contracts in the signature, and validation at the boundary. |
2323
| [Error Handling](Error-Handling.md) | Fail fast, never swallow, and write messages that help the next person. |
2424
| [Documentation](Documentation.md) | Help that lives next to the code and explains the why. |
25+
| [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. |
2526
| [Testing](Testing.md) | The executable specification — test-first, locally runnable, deterministic. |
2627
| [Performance](Performance.md) | Scale with the input, measure before optimizing, clarity first. |
2728
| [Security](Security.md) | Least privilege, secret hygiene, and the OWASP baseline. |

0 commit comments

Comments
 (0)