Skip to content

📖 [Docs]: Agentic development framework documented#51

Merged
Marius Storhaug (MariusStorhaug) merged 6 commits into
mainfrom
docs/agentic-development-framework
Jul 18, 2026
Merged

📖 [Docs]: Agentic development framework documented#51
Marius Storhaug (MariusStorhaug) merged 6 commits into
mainfrom
docs/agentic-development-framework

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Jul 18, 2026

Copy link
Copy Markdown
Member

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

@MariusStorhaug Marius Storhaug (MariusStorhaug) added documentation Improvements or additions to documentation NoRelease No release required labels Jul 18, 2026
@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review July 18, 2026 16:23
@MariusStorhaug
Marius Storhaug (MariusStorhaug) merged commit 95d3ffa into main Jul 18, 2026
19 checks passed
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the docs/agentic-development-framework branch July 18, 2026 16:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation NoRelease No release required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant