Skip to content

Commit dd17a44

Browse files
MariusStorhaugMariusStorhaug
authored
📖 [Docs]: Organization and repository standards now defined (#20)
MSX now defines organization-level and repository-level standards for the files and behaviours every initiative should make consistent. Initiative repositories can keep their implementation designs local while the central docs define the shared why and what. > ⚠️ This PR has no linked issue. Consider creating one for traceability. ## New: Organization standards A new Organization Standard page defines what each initiative organization must document centrally: required file families, managed-file ownership, mandatory versus optional file sets, linter configuration ownership, and agent/human alignment. ## New: Repository standards A new Repository Standard page defines the baseline files and behaviours each repository should expose, including README, license, contribution, security, support, code of conduct, Dependabot, CODEOWNERS, pull request templates, release configuration, linter configuration, and Git defaults. ## Changed: Standards separate spec from initiative implementation The central MSX docs now state the shared requirements while initiative repositories keep the implementation guidance and rollout design. PSModule and Distributor are referenced as examples of an initiative-specific implementation path, not as the universal MSX design. ## Technical Details - Adds `src/docs/Ways-of-Working/Organization-Standard.md`. - Adds `src/docs/Ways-of-Working/Repository-Standard.md`. - Adds both pages to the Ways of Working navigation in `src/zensical.toml`. - Regenerates `src/docs/Ways-of-Working/index.md`.
1 parent 01105dd commit dd17a44

4 files changed

Lines changed: 234 additions & 0 deletions

File tree

‎src/docs/Ways-of-Working/Organization-Standard.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Organization Standard
3+
description: What every initiative organization must define centrally so humans and agents share the same expectations.
4+
---
5+
6+
# Organization Standard
7+
8+
An MSX initiative organization is a collection of repositories that share one way of working. The organization standard defines the shared contract: what every repository can expect from the organization, where the source of truth lives, and which files must be managed consistently.
9+
10+
This page owns the **why** and **what**. Initiative repositories own the implementation design: how they distribute files, which automation enforces the contract, and how exceptions are handled.
11+
12+
## Required organization docs
13+
14+
Each initiative must have a central documentation repository that defines its implementation guidance. The central docs answer how the initiative applies MSX standards to its own repositories.
15+
16+
The initiative docs must describe:
17+
18+
- Repository types used by the initiative.
19+
- Required files for each repository type.
20+
- Managed-file source locations and update workflow.
21+
- Required custom properties, labels, branch protection, and review rules.
22+
- How humans and agents discover the relevant standards before making changes.
23+
- How initiative-specific exceptions are requested and reviewed.
24+
25+
The MSX docs remain the ecosystem-level source of truth. Initiative docs may specialize, but must not contradict this site.
26+
27+
## Required organization file standards
28+
29+
Every initiative organization must define standards for these shared file families:
30+
31+
| File family | Standard owns |
32+
| --- | --- |
33+
| Community health files | Code of conduct, contribution guide, support policy, security policy, and license expectations. |
34+
| Repository context | README defaults, documentation ownership, and repository metadata expectations. |
35+
| Review workflow | Pull request template, review routing, CODEOWNERS, labels, and change-type conventions. |
36+
| Supply chain | Dependabot configuration, dependency update labels, security update behavior, and review expectations. |
37+
| Linters and enforcement | Linter configuration derived from the written standards. |
38+
| Agent context | Instructions, prompts, hooks, and any repository-local agent guidance. |
39+
| Release automation | Release notes, changelog categorization, and release workflow defaults where applicable. |
40+
41+
These standards must be written down before broad alignment work starts. File alignment without a written standard only spreads local preference faster.
42+
43+
## Repository-local files are the enforceable surface
44+
45+
GitHub's special organization `.github` repository can provide fallback community files, but it is not the MSX enforcement model. Repository-local files are still required because they are what humans, agents, linters, Dependabot, CODEOWNERS, release workflows, and pull requests actually read and review.
46+
47+
Use organization-level `.github` fallbacks only as a convenience, never as the only copy of a required standard file.
48+
49+
## Managed files
50+
51+
Shared files should be managed from a central source and delivered to repositories through pull requests. Direct pushes to repository default branches are not the standard path.
52+
53+
A managed-file system must:
54+
55+
- Keep source files in one central repository for the initiative.
56+
- Preserve relative paths exactly as they should appear in target repositories.
57+
- Create or update repository-local files by pull request.
58+
- Make ownership clear in the pull request body.
59+
- Avoid creating duplicate pull requests for the same managed branch.
60+
- Log which repositories changed, which were already aligned, and which failed.
61+
- Never silently delete previously distributed files without an explicit cleanup decision.
62+
63+
PSModule currently explores this through `PSModule/Distributor`. That repository is an implementation example for the PSModule initiative, not the MSX-wide design. Other initiatives may build a different distributor as long as it satisfies this standard.
64+
65+
## Mandatory and optional file sets
66+
67+
Organizations must distinguish mandatory files from optional or type-specific files.
68+
69+
| Kind | Meaning |
70+
| --- | --- |
71+
| Mandatory | Files that every applicable repository must carry, even without local subscription. |
72+
| Global optional | Files available to all repository types, but still selected intentionally. |
73+
| Type-specific | Files that apply only to a repository type, such as a PowerShell module, GitHub Action, Terraform module, or docs repo. |
74+
| Repository-specific | Local files that are intentionally owned by one repository and not managed centrally. |
75+
76+
Security, contribution, conduct, support, dependency update, and license files are candidates for mandatory file sets. Linter settings, agent instructions, and workflow defaults may be global or type-specific depending on the initiative.
77+
78+
## Linter configuration ownership
79+
80+
The written standard defines the rule. The linter configuration enforces the rule.
81+
82+
Most linter configuration belongs under `.github/linters/`, because super-linter and similar workflow tooling read that path consistently. Examples include markdownlint, codespell, textlint, and PSScriptAnalyzer settings.
83+
84+
Some tools require repository-root configuration because their own config discovery works that way. Examples include Prettier or language package-manager files. When a root config is required, document why in the initiative guidance.
85+
86+
Do not change a linter config to make a warning disappear unless the written standard changes with it.
87+
88+
## Agent and human alignment
89+
90+
Humans and agents must read the same standards. Do not create a separate hidden agent process that contradicts the public docs.
91+
92+
Agent files are allowed when they point to, summarize, or operationalize the central standard. They must not become a second source of truth.
93+
94+
## Where this connects
95+
96+
- [Repository Standard](Repository-Standard.md) — the repository-level contract every repository must satisfy.
97+
- [Documentation Model](Documentation-Model.md) — why specs own why and what, while designs own implementation.
98+
- [Dependency Updates](../Capabilities/dependency-updates/spec.md) — the supply-chain update capability every repository inherits.
99+
- [GitHub Actions](../Coding-Standards/GitHub-Actions.md) — workflow authoring and enforcement rules.

‎src/docs/Ways-of-Working/Repository-Standard.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Repository Standard
3+
description: The baseline files and behaviours every repository must expose so it is understandable, secure, and maintainable.
4+
---
5+
6+
# Repository Standard
7+
8+
A repository is the smallest unit of ownership in the MSX ecosystem. It must explain what it is, how to contribute, how security is handled, how dependencies are kept current, and which standards govern its automation.
9+
10+
This page defines the repository-level contract. Initiative documentation defines implementation details such as exact file templates, managed-file source paths, and rollout automation.
11+
12+
## Required files
13+
14+
Every repository must carry the files that make it understandable and governable on its own.
15+
16+
| File | Requirement |
17+
| --- | --- |
18+
| `README.md` | Explains the repository purpose, current capabilities, and where to find deeper docs. |
19+
| `LICENSE` | States the legal terms for reuse and redistribution. |
20+
| `CONTRIBUTING.md` | Explains how to contribute or links to the initiative contribution guide. |
21+
| `SECURITY.md` | Explains supported versions and private vulnerability reporting. |
22+
| `SUPPORT.md` | Explains where users ask for help. |
23+
| `CODE_OF_CONDUCT.md` | Defines expected community behaviour. |
24+
| `.github/dependabot.yml` | Configures dependency and supply-chain update pull requests. |
25+
| `.github/CODEOWNERS` | Routes reviews to responsible owners. |
26+
| `.github/pull_request_template.md` | Guides contributors to provide change type, impact, validation, and links. |
27+
| `.github/release.yml` | Defines release-note categories where GitHub releases are generated. |
28+
| `.github/linters/*` | Stores linter configuration derived from the written standards. |
29+
| `.gitattributes` | Defines Git file handling defaults. |
30+
| `.gitignore` | Defines files that should not enter version control. |
31+
32+
Repository types may require additional files. For example, a PowerShell module may require `.github/PSModule.yml`, while a GitHub Action may require `action.yml`.
33+
34+
## README defaults
35+
36+
The README is the repository front door. It must be short enough to stay current and specific enough that a human or agent can understand the repository before reading source code.
37+
38+
A README should include:
39+
40+
- What the repository is.
41+
- What it currently does.
42+
- How to install or use the artifact, if applicable.
43+
- Where generated or detailed documentation lives.
44+
- How to contribute or where to find contribution guidance.
45+
- Status if the repository is a placeholder, archive, experiment, or in progress.
46+
47+
Do not leave template placeholders such as `{{ NAME }}`, `{{ DESCRIPTION }}`, `YourModuleName`, or fake example commands in a repository README after the initial setup commit.
48+
49+
## Dependency and supply-chain defaults
50+
51+
Every repository that has external dependencies must configure automated update pull requests. Dependabot is the default GitHub-native mechanism unless the initiative documents a different implementation.
52+
53+
At minimum, repositories with GitHub Actions must include a `github-actions` ecosystem entry. Repositories with language, package, container, or infrastructure dependencies must include the relevant ecosystems too.
54+
55+
Dependency update pull requests must:
56+
57+
- Use labels that identify the dependency category and ecosystem.
58+
- Keep update-level labels separate from release-bump labels.
59+
- Pass the same CI and review gates as human-authored changes.
60+
- Keep SHA-pinned actions pinned to immutable commit SHAs with a version comment when possible.
61+
- Be reviewed before merge, even when auto-merge is allowed for low-risk updates.
62+
63+
See [Dependency Updates](../Capabilities/dependency-updates/spec.md) for the central requirements.
64+
65+
## Linter configuration defaults
66+
67+
Linter configuration must be repository-local when the CI job reads it from the repository. Most shared linter configs live under `.github/linters/`.
68+
69+
Examples:
70+
71+
| Config | Typical location |
72+
| --- | --- |
73+
| markdownlint | `.github/linters/.markdown-lint.yml` |
74+
| codespell | `.github/linters/.codespellrc` |
75+
| textlint | `.github/linters/.textlintrc` |
76+
| PSScriptAnalyzer | `.github/linters/.powershell-psscriptanalyzer.psd1` |
77+
| actionlint | `.github/linters/actionlint.yml` |
78+
| zizmor | `.github/linters/zizmor.yaml` |
79+
80+
When a tool only discovers config at the repository root, keep it there and document why. The written standard still owns the rule; the config is the derived enforcement.
81+
82+
## Pull request defaults
83+
84+
Repository pull requests must use the PR Manager style for title and description when a release note may be generated from the PR.
85+
86+
Default title pattern:
87+
88+
```text
89+
<Icon> [<Change type>]: <User-facing outcome>
90+
```
91+
92+
The description should lead with user-facing impact, then issue links when available, then user-facing change sections, with technical details at the bottom.
93+
94+
Repository templates may be simpler than the full PR Manager body, but they must gather enough information to reconstruct it.
95+
96+
## Managed files
97+
98+
A repository must treat centrally managed files as owned by the initiative, not by local preference. If a managed file needs to change, update the managed source and let automation open repository pull requests.
99+
100+
Local changes to managed files are allowed only as a temporary exception and should be reconciled back into the managed source.
101+
102+
Managed-file pull requests should clearly say:
103+
104+
- Which system produced the PR.
105+
- Which files are managed.
106+
- Where to propose changes to the source files.
107+
- Whether files were created, overwritten, or left unmanaged.
108+
109+
## Initiative implementation guidance
110+
111+
The central standard deliberately stops at the requirement level. Initiative repositories own implementation design.
112+
113+
An initiative should document:
114+
115+
- Which repository types it uses.
116+
- Which files are mandatory for each type.
117+
- Which files are optional subscriptions.
118+
- Which files are generated or managed.
119+
- Which custom properties, labels, and teams are required.
120+
- How the distributor or equivalent automation discovers repositories.
121+
- How exceptions are approved.
122+
123+
For example, PSModule can define its module-specific managed files in `PSModule/docs` and implement distribution in `PSModule/Distributor`. MSX only defines that such a standard and distribution path must exist.
124+
125+
## Where this connects
126+
127+
- [Organization Standard](Organization-Standard.md) — what an initiative organization must define centrally.
128+
- [README-Driven Context](Readme-Driven-Context.md) — why the README is the front door.
129+
- [PR Format](PR-Format.md) — the PR Manager-style title and description format.
130+
- [GitHub Actions](../Coding-Standards/GitHub-Actions.md) — workflow and automation standards.
131+
- [Dependency Updates](../Capabilities/dependency-updates/spec.md) — supply-chain update requirements.

‎src/docs/Ways-of-Working/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ This section documents the principles, processes, and norms that every contribut
2121
| [Spec-Driven Development](Spec-Driven-Development.md) | The specification is the source of truth — the spec (why and what), its design (how), and how a change moves from need to shipped. |
2222
| [Evolutionary Development](Evolutionary-Development.md) | Grow software as bets under selection — variation, feedback, and survival of the fittest, run as one tight loop. |
2323
| [Agentic Development](Agentic-Development.md) | How ways of working, standards, and documentation are authored once and consumed by both humans and agents. |
24+
| [Organization Standard](Organization-Standard.md) | What every initiative organization must define centrally so humans and agents share the same expectations. |
25+
| [Repository Standard](Repository-Standard.md) | The baseline files and behaviours every repository must expose so it is understandable, secure, and maintainable. |
2426
| [Principles](Principles/index.md) | The foundational beliefs and product mindset behind every decision. |
2527
| [Engineering Taste](Engineering-Taste.md) | The judgment that takes over when the standards run out. |
2628
| [Goal-Setting Framework](Goal-Setting.md) | Mission, OKRs, and initiatives — strategy connected to delivery. |

‎src/zensical.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ nav = [
3131
{"Spec-Driven Development" = "Ways-of-Working/Spec-Driven-Development.md"},
3232
{"Evolutionary Development" = "Ways-of-Working/Evolutionary-Development.md"},
3333
{"Agentic Development" = "Ways-of-Working/Agentic-Development.md"},
34+
{"Organization Standard" = "Ways-of-Working/Organization-Standard.md"},
35+
{"Repository Standard" = "Ways-of-Working/Repository-Standard.md"},
3436
{"Principles" = [
3537
"Ways-of-Working/Principles/index.md",
3638
{"Purpose and Direction" = "Ways-of-Working/Principles/Purpose-and-Direction.md"},

0 commit comments

Comments
 (0)