Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions src/docs/Capabilities/agentic-development/AGENTS.template.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ description: The repository-level agent router template and the guidance for app

# AGENTS.md Template

This document explains the repository-level `AGENTS.md` template. It is not
itself the router that agents load. Copy the contents of the fenced `markdown`
block into an `AGENTS.md` at the repository root.
A repository-level `AGENTS.md` router uses the fenced `markdown` block below,
not the surrounding guidance. Copy that block into an `AGENTS.md` at the
repository root.

The router reads repository-local guidance first, initiative-specific guidance
next, and central organization guidance last.
Expand Down
8 changes: 4 additions & 4 deletions src/docs/Capabilities/agentic-development/conformance.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ description: What a repository must provide to be conformant with the agentic de

# Conformance

Conformance defines the required files, context resolution, and duplication limits for a
repository. This page states the baseline it MUST provide, what it MAY add, and how to
identify a deviation.
Conformance checks assess a repository's required files, context resolution, and
duplication limits. A conformant repository MUST meet the baseline and MAY add
the scoped extensions below.

These checks assess structure and content. Documentation quality requires review; file and
content inspection establishes whether agent context resolves correctly.
Expand Down Expand Up @@ -95,7 +95,7 @@ That answer depends on the same context being assessed.

## Where this connects

- [Spec](spec.md) — the requirements this checklist measures against.
- [Spec](spec.md) — agentic-development conformance requirements.
- [Design](design.md) — the mechanisms each baseline item refers to.
- [MCP Servers](mcp-servers.md) — the shared tool layer the **Uniform** level requires.
- [Plugin Distribution](plugin-distribution.md) — the pointer discipline the duplication checks apply to intents.
Expand Down
4 changes: 2 additions & 2 deletions src/docs/Capabilities/agentic-development/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,13 +265,13 @@ Copilot code review uses the head-branch versions of `AGENTS.md`, client routes,

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — agentic development requirements.
- [MCP Servers](mcp-servers.md) — the shared tool layer every runtime declares in its own format.
- [Plugin Distribution](plugin-distribution.md) — how named intents are packaged and kept pointer-based.
- [Runtime Integration](runtime-integration.md) — what each runtime shape supplies, and why it never supplies process.
- [Agent Interaction](agent-interaction.md) — how agents and humans coordinate through platform artifacts.
- [Advisory Agents](advisory-agents.md) — agents that produce advice rather than commits.
- [Conformance](conformance.md) — the checklist a repository is measured against.
- [Agentic Development framework](index.md) — the framework this design delivers.
- [Agentic Development framework](index.md) — organization-scoped documentation and agent context.
- [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.
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ Recurring workflows can have **named intents**. Examples include "review this pu
"open an issue for this", and "wrap up and hand off". Each intent points to a documented
procedure.

Runtimes expose an intent as a command, skill, named agent, or plugin. This page defines what
that packaged entry point can contain.
Runtimes expose an intent as a command, skill, named agent, or plugin.

## An intent is a pointer

Expand Down Expand Up @@ -79,8 +78,8 @@ The body stays a short route with runtime mechanics.
## Marketplace structure and skill boundaries

The [Plugin Marketplaces design](design-plugin-marketplaces.md) owns marketplace ownership,
repository layout, plugin identities, and skill granularity. This page describes named-intent
distribution and links to those structural rules.
repository layout, plugin identities, and skill granularity. Named-intent
distribution follows those structural rules.

For consumer upgrades, `msx-ways-of-working-consumer-upgrades` is the shared
pointer to [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md).
Expand Down
4 changes: 2 additions & 2 deletions src/docs/Capabilities/agentic-development/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ This is the order in which context is **read**, nearest first. It is not the ord
- [Plugin Distribution](plugin-distribution.md) — how named intents stay pointers to documentation.
- [Agent Interaction](agent-interaction.md) — issues, labels, and pull requests as the coordination substrate.
- [Advisory Agents](advisory-agents.md) — the pattern for automation that advises without deciding.
- [Conformance](conformance.md) — how a repository is measured against this spec.
- [Agentic Development](index.md) — the framework this specification defines.
- [Conformance](conformance.md) — repository checks against the framework's requirements.
- [Agentic Development](index.md) — organization-scoped agent context.
- [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.
2 changes: 1 addition & 1 deletion src/docs/Capabilities/dependency-updates/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ fresh output is drift. Generation MUST preserve surfaces marked

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — dependency-update requirements.
- [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the procedure that turns an update proposal into verified adoption.
- [Repository Governance](../repository-governance/design.md#drift-detection-and-reconciliation) — the reconciliation that compares generated configuration against what is committed.
- [Release Management](../release-management/design.md) — the conditional release decision and output for an update pull request.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: How the deployment spec is delivered with Azure as the service prov

# Deploying Azure from GitHub

This design defines how one combination satisfies the [Deployment spec](../spec.md):
The deployment workflow satisfies the [Deployment spec](../spec.md) with
**Azure** (including Microsoft Entra ID) as the service provider, **GitHub** as
the CI/CD platform, and **Terraform (open source)** as the change engine. The
computed resource effect is a **saved Terraform plan**. Each environment has its
Expand Down
4 changes: 2 additions & 2 deletions src/docs/Capabilities/deployment/designs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ description: How the deployment contract is delivered for each service-provider

# Deployment designs

Each page describes how one service-provider and CI/CD-platform combination
satisfies the [Deployment spec](../spec.md). Add a design here without changing
Each service-provider and CI/CD-platform combination uses a separate design to
satisfy the [Deployment spec](../spec.md). Additional combinations do not change
the technology-independent contract.

<!-- INDEX:START -->
Expand Down
2 changes: 1 addition & 1 deletion src/docs/Capabilities/deployment/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,5 +225,5 @@ Feature: Deployment approves and applies the effect, not just the code

- [Designs](index.md) — how these requirements are delivered for a specific
service provider and CI/CD platform.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec holds only the why and the what.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — the separation between capability requirements and implementation details.
- [PR Format](../../Ways-of-Working/PR-Format.md) — the review that approves the change and its effect.
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ review, merged, or met its applicable

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — downstream release propagation requirements.
- [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md) — the complete-range adoption procedure used by each dependent.
- [Release Management](../release-management/design.md) — produces the release and note this consumes.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md) — SHA pinning, least-privilege permissions, explicit secret passing.
Expand Down
2 changes: 1 addition & 1 deletion src/docs/Capabilities/merge-automation/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ Scope the app's approval to the eligible set the ruleset permits it to satisfy.

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — merge automation requirements.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#gate-merges-with-a-named-status-check) — authoring the named checks this consumes.
- [Dependency Updates](../dependency-updates/design.md) — the auto-merge policy this generalizes. Dependency update PRs are the canonical eligible set.
- [Release Management](../release-management/design.md) — the release a merge triggers on an invoked route.
Expand Down
6 changes: 3 additions & 3 deletions src/docs/Capabilities/powershell-on-github/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ description: Reusable modules, actions, and the Process-PSModule framework imple

# Design

This design implements the [capability requirements](spec.md) through reusable
modules, actions, and the `Process-PSModule` framework.
Reusable modules, actions, and the `Process-PSModule` framework implement the
[capability requirements](spec.md).

## Capability model

Expand All @@ -25,7 +25,7 @@ The model has two paths:
## Operating pattern

- Keep component-level details in initiative/module docs.
- Keep reusable architecture and decision rationale here.
- Keep reusable architecture and decision rationale with the capability.
- Link initiative pages to this capability as canonical context.

## Current canonical references
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@ description: Refresh an owned moving release alias locally and configure Git to

# Accept moved release tags

Use this guide for an MSX-owned producer's intentionally moving Git tag, such as
`v3` or `v3.4`. Refresh the tag when your local clone still resolves it to an
older release.
For an MSX-owned producer's intentionally moving Git tag, such as `v3` or `v3.4`,
refresh the tag when your local clone still resolves it to an older release.

Do not use this procedure for exact version tags such as `v3.4.2`. Exact version
tags are immutable. A moved exact tag is a producer integrity incident, not a
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ passes every target the same frozen version, retained artifact, note envelope,
and release-intent identity.

Targets differ in native version syntax, prerelease channels, deletion, and
consumer resolution. This page makes those differences explicit so adding a
destination does not change the [release-management specification](spec.md).
consumer resolution. Each destination's contract records those differences
without changing the [release-management specification](spec.md).

## Publishing-target contract

Expand Down
8 changes: 4 additions & 4 deletions src/docs/Capabilities/release-management/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ description: Durable release intents, lifecycle transitions, recovery, withdrawa

# Release Management — Design

This page realizes the [release-management specification](spec.md) through
shared, GitHub-native release mechanics, including native producer pipelines.
It defines the durable lifecycle and input contract. The immutable producer
Release management satisfies the [release-management specification](spec.md)
through shared, GitHub-native mechanics, including native producer pipelines.
These mechanics use a durable lifecycle and input contract. The immutable producer
revision's documented interface and verified behavior establish conformance.
Documentation alone does not make a lifecycle control or setting available.

Expand Down Expand Up @@ -675,7 +675,7 @@ controls, and conformance evidence before relying on them. A configuration
example or normative requirement is not proof that an older producer implements
it. Version-specific implementation deltas and required adoption actions belong
in that producer's PR/release record, not a parallel status or migration history
in this design.
in the shared lifecycle contract.

For an incomplete release, an operator MUST NOT work around a
partial release by rerunning against changed metadata or rebuilding under the
Expand Down
13 changes: 6 additions & 7 deletions src/docs/Capabilities/repository-governance/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ rulesets**, and **reconciliation**. The property carries the declaration.
Organization rulesets read it, and reconciliation compares live configuration
with the declared requirements.

This design defines the reconciliation contract. Delivery records provide
evidence that an implementation and its enforcement satisfy this contract.
Delivery records provide evidence that an implementation and its enforcement
satisfy the reconciliation contract.

```mermaid
flowchart LR
Expand Down Expand Up @@ -39,8 +39,7 @@ branch-model and layering obligations
The property mechanism — how conditions target it, why conditions are written as
exclusions, and how an existing condition is migrated onto it without dropping
coverage — is owned by [Repository Type
Property](../../Ways-of-Working/Repository-Type-Property.md). This design does not
restate it.
Property](../../Ways-of-Working/Repository-Type-Property.md).

Moving an organization from a single-select property to a multi-select `Type`
property is a schema change the platform does not perform in place. The migration
Expand Down Expand Up @@ -153,8 +152,8 @@ names.

The [Repository Standard](../../Ways-of-Working/Repository-Standard.md#required-files)
owns the file list, its conditional contribution rule, and which type adds to
it. This design owns only the enforcement: reconciliation checks required local
files on the default branch and resolves effective contribution guidance under
it. Reconciliation checks required local files on the default branch and
resolves effective contribution guidance under
the [contribution rule](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), at
**Block** severity for the files that make a repository contributable and
**Report** severity for the rest.
Expand Down Expand Up @@ -239,7 +238,7 @@ change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — repository governance requirements.
- [Repository Types](design-types.md) — the catalog the rulesets select on.
- [Repository Type Property](../../Ways-of-Working/Repository-Type-Property.md) — the property mechanism and condition migration.
- [Repository Standard](../../Ways-of-Working/Repository-Standard.md) — the required-file sets reconciliation checks.
Expand Down
6 changes: 3 additions & 3 deletions src/docs/Capabilities/vscode-extension-framework/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ description: How the VS Code extension framework is built — a shared reusable

# VS Code Extension Framework — Design

The [spec](spec.md) defines the framework's behavior. The design combines a
**shared reusable workflow** with a **template repository**. It follows the
The framework combines a **shared reusable workflow** with a **template repository**
to meet the [spec](spec.md). It follows the
organization's `Process-*` / `Template-*` convention, which
[Process-PSModule](https://github.com/PSModule/Process-PSModule) uses for PowerShell
modules.
Expand Down Expand Up @@ -244,7 +244,7 @@ The template defines the following repository structure. It follows

## Where this connects

- [Spec](spec.md) — the requirements this design delivers.
- [Spec](spec.md) — VS Code extension lifecycle requirements.
- [Release Management](../release-management/design.md) — the versioning and publication rules that the VSIX pipeline follows.
- [Dependency Updates](../dependency-updates/design.md) — how the extension's dependencies stay current.
- [Merge Automation](../merge-automation/spec.md) — how the pipeline's named status checks gate the merge.
Expand Down
6 changes: 3 additions & 3 deletions src/docs/Capabilities/vscode-extension-framework/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ dependencies current.

A plain Node package that is not a VS Code extension is outside this scope.
Documentation for a specific extension lives in that extension's repository.
This capability documents the framework itself.
The shared capability owns the framework requirements and design.

## Requirements

Expand All @@ -66,7 +66,7 @@ This capability documents the framework itself.
- **Optional marketplace publication.** When configured, the pipeline also publishes the same VSIX to an extension marketplace (the VS Code Marketplace and/or Open VSX). Marketplace publication is opt-in and MUST NOT be a prerequisite for the GitHub-Release install path.
- **A prerelease from an open pull request.** A prerelease VSIX MUST be obtainable from an open pull request for tests before merge. It never becomes the latest stable version.
- **A named status check per merge-blocking stage.** Every stage that must hold a pull request surfaces a named status check, so [Merge Automation](../merge-automation/spec.md) can gate the merge on it.
- **Documentation travels with the extension.** Each extension's user documentation lives in its own repository. The framework builds and publishes that documentation. There is no separate internal-versus-user split. This capability contains the framework's own documentation.
- **Documentation travels with the extension.** Each extension's user documentation lives in its own repository. The framework builds and publishes that documentation. There is no separate internal-versus-user split. Framework documentation belongs to the shared capability.
- **Dependencies kept current.** The extension's pinned dependencies — npm packages and pinned Actions — are kept current and secure through [Dependency Updates](../dependency-updates/spec.md).
- **Standard GitHub primitives only.** The framework uses pull requests, labels, releases, environments, and GitHub Actions. It uses no external release tooling beyond `gh` and the editor's own packaging and publishing CLIs.

Expand All @@ -86,6 +86,6 @@ This capability documents the framework itself.
- [Release Management](../release-management/spec.md) — the versioning and release mechanics this framework drives.
- [Dependency Updates](../dependency-updates/spec.md) — how the extension's dependencies stay current.
- [Merge Automation](../merge-automation/spec.md) — how the framework's status checks gate the merge.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec defines requirements and an extension's docs live in its own repository.
- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — capability requirements and repository-local extension documentation.
- [TypeScript](../../Coding-Standards/TypeScript.md) — the language standard extensions are written to.
- [GitHub Actions](../../Coding-Standards/GitHub-Actions.md) — how the pipeline that delivers this is authored.
Loading
Loading