📖 [Docs]: Bootstrap the MSX vision and ways-of-working site#1
Draft
Marius Storhaug (MariusStorhaug) wants to merge 32 commits into
Draft
📖 [Docs]: Bootstrap the MSX vision and ways-of-working site#1Marius Storhaug (MariusStorhaug) wants to merge 32 commits into
Marius Storhaug (MariusStorhaug) wants to merge 32 commits into
Conversation
Marius Storhaug (MariusStorhaug)
added
the
documentation
Marius Storhaug (MariusStorhaug)
force-pushed
the
docs/bootstrap-vision-site
branch
4 times, most recently
from
f9de6f5 to
949e034
Compare
Marius Storhaug (MariusStorhaug)
force-pushed
the
docs/bootstrap-vision-site
branch
from
949e034 to
6a9852a
Compare
… development, documentation model Per-language Coding Standards (GitHub Actions, Markdown, PowerShell, Terraform); Capabilities specs+designs (release-management, dependency-updates, downstream-release-propagation); Ways of Working: Agentic Development and Documentation Model; switch the docs index generator from Python to PowerShell (generate-indexes.ps1, run with -Check in CI).
…showcase) New MSXOrg-only "Initiatives" section placed early in the nav (right after Vision), presented like a company Products page. Absorbs and replaces Ecosystem: PSModule, AzActions, TFActions and VS Code Extensions each get a page. Repoint the front page and Vision links and cascade to Initiatives; regenerate index tables.
super-linter (textlint) requires "end-to-end" (PSModule initiative page) and "colocated" (Documentation Model description, which feeds the generated Ways of Working index).
ES modules, strict-mode typing, pinned dependencies, and the Prettier/ESLint/Vitest toolchain; builds on the language-agnostic baseline. Linked from the VS Code Extensions initiative. TypeScript is the only new language added (Shell/Python/Go/Dockerfile out of scope).
Convert the single PowerShell page into a nested standard: index.md holds the shared conventions and toolchain, with Functions, Classes, and Scripts pages each carrying doc requirements, formatting, and section structure. Repoint the nav and the GitHub Actions cross-link.
Split the single Principles page into a Principles/ folder: index.md (overview + generated table + "why these matter") and one page per theme (Purpose and Direction, AI-First Development, Software Design, Engineering Practices, Planning and Delivery) plus References. Heading levels shifted so every anchor slug is preserved; repointed all inbound links across Vision, Coding Standards, Capabilities specs, and Ways of Working; nested the nav.
A new top-level Dictionary section defining the ecosystem-specific vocabulary (Initiative, Capability, Spec, Design, Directive, Coding Standard, Principle/Practice/Philosophy, Ways of Working, Vision, Shift Left, Least privilege) plus essential shared terms, generalized from the PSModule dictionary and referencing Zensical. Each ecosystem term links to the page that covers it in full.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 16:51
View session
There was a problem hiding this comment.
Pull request overview
Bootstraps the MSX “top-of-tree” documentation site (vision, ways-of-working, coding standards, and capability specs/designs) using Zensical, with supporting automation for index generation and GitHub Pages publishing.
Changes:
- Adds Zensical site configuration + full navigation tree and theme/JS overrides.
- Introduces the initial docs corpus across Vision, Initiatives, Ways of Working, Coding Standards, Capabilities, and Dictionary.
- Adds CI automation: lint/build/publish workflow, index-generation tooling, and repo lint/dependency config.
Reviewed changes
Copilot reviewed 73 out of 74 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
src/zensical.toml |
Zensical site config + nav |
src/overrides/assets/javascripts/tablesort.js |
Table sorting enhancement |
src/includes/links.md |
Shared link definitions stub |
src/includes/abbreviations.md |
Shared abbreviations glossary |
src/docs/index.md |
Site home page + index |
src/docs/Vision/index.md |
Vision landing page |
src/docs/Initiatives/index.md |
Initiatives index page |
src/docs/Initiatives/PSModule.md |
Initiative page: PSModule |
src/docs/Initiatives/AzActions.md |
Initiative page: AzActions |
src/docs/Initiatives/TFActions.md |
Initiative page: TFActions |
src/docs/Initiatives/VS-Code-Extensions.md |
Initiative page: VS Code extensions |
src/docs/Ways-of-Working/index.md |
Ways of Working index |
src/docs/Ways-of-Working/Workflow.md |
Workflow specification page |
src/docs/Ways-of-Working/Contribution-Workflow.md |
PR flow + Copilot loop |
src/docs/Ways-of-Working/Documentation-Model.md |
Spec/design documentation model |
src/docs/Ways-of-Working/Agentic-Development.md |
Agent consumption model |
src/docs/Ways-of-Working/Principles/index.md |
Principles index page |
src/docs/Ways-of-Working/Principles/Purpose-and-Direction.md |
Principles: purpose/direction |
src/docs/Ways-of-Working/Principles/AI-First-Development.md |
Principles: AI-first |
src/docs/Ways-of-Working/Principles/Software-Design.md |
Principles: software design |
src/docs/Ways-of-Working/Principles/Engineering-Practices.md |
Principles: engineering practices |
src/docs/Ways-of-Working/Principles/Planning-and-Delivery.md |
Principles: planning/delivery |
src/docs/Ways-of-Working/Principles/References.md |
Principles references list |
src/docs/Ways-of-Working/Engineering-Taste.md |
Judgment defaults (“taste”) |
src/docs/Ways-of-Working/Goal-Setting.md |
OKR/initiative framework |
src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md |
DoR/DoD checklists |
src/docs/Ways-of-Working/Issue-Format.md |
Standard issue template spec |
src/docs/Ways-of-Working/Issue-Hierarchy.md |
Epic/PBI/Task hierarchy |
src/docs/Ways-of-Working/PR-Format.md |
PR title/description conventions |
src/docs/Ways-of-Working/Commit-Conventions.md |
Commit message conventions |
src/docs/Ways-of-Working/Branching-and-Merging.md |
Branch/merge model |
src/docs/Ways-of-Working/Review-Etiquette.md |
Review etiquette guidance |
src/docs/Ways-of-Working/Repository-Segmentation.md |
Repo boundary guidance |
src/docs/Ways-of-Working/Readme-Driven-Context.md |
README as repo “front door” |
src/docs/Ways-of-Working/Git-Worktrees.md |
Worktree-based repo layout |
src/docs/Ways-of-Working/Continuous-Practices.md |
Continuous X / Continuous AI |
src/docs/Ways-of-Working/DevOps-Reference.md |
DevOps reading list + synthesis |
src/docs/Coding-Standards/index.md |
Coding standards index |
src/docs/Coding-Standards/Naming.md |
Naming baseline standard |
src/docs/Coding-Standards/Code-Layout.md |
Code layout baseline standard |
src/docs/Coding-Standards/Functions.md |
Functions baseline standard |
src/docs/Coding-Standards/Error-Handling.md |
Error handling baseline standard |
src/docs/Coding-Standards/Documentation.md |
Documentation baseline standard |
src/docs/Coding-Standards/Testing.md |
Testing baseline standard |
src/docs/Coding-Standards/Performance.md |
Performance baseline standard |
src/docs/Coding-Standards/Security.md |
Security baseline standard |
src/docs/Coding-Standards/GitHub-Actions.md |
GitHub Actions standard |
src/docs/Coding-Standards/Markdown.md |
Markdown authoring standard |
src/docs/Coding-Standards/PowerShell/index.md |
PowerShell standards index |
src/docs/Coding-Standards/PowerShell/Functions.md |
PowerShell functions standard |
src/docs/Coding-Standards/PowerShell/Classes.md |
PowerShell classes standard |
src/docs/Coding-Standards/PowerShell/Scripts.md |
PowerShell scripts standard |
src/docs/Coding-Standards/Terraform.md |
Terraform standard |
src/docs/Coding-Standards/TypeScript.md |
TypeScript standard |
src/docs/Capabilities/index.md |
Capabilities index |
src/docs/Capabilities/release-management/index.md |
Release mgmt capability index |
src/docs/Capabilities/release-management/spec.md |
Release mgmt spec |
src/docs/Capabilities/release-management/design.md |
Release mgmt design |
src/docs/Capabilities/dependency-updates/index.md |
Dependency updates index |
src/docs/Capabilities/dependency-updates/spec.md |
Dependency updates spec |
src/docs/Capabilities/dependency-updates/design.md |
Dependency updates design |
src/docs/Capabilities/downstream-release-propagation/index.md |
Downstream propagation index |
src/docs/Capabilities/downstream-release-propagation/spec.md |
Downstream propagation spec |
src/docs/Capabilities/downstream-release-propagation/design.md |
Downstream propagation design |
src/docs/Dictionary/index.md |
Shared vocabulary dictionary |
.github/workflows/Docs.yml |
Lint/build/publish pipeline |
.github/scripts/generate-indexes.ps1 |
Index generation script |
.github/scripts/Wait-CopilotReview.ps1 |
Copilot review wait helper |
.github/linters/.markdown-lint.yml |
markdownlint config |
.github/linters/.codespellrc |
codespell config |
.github/linters/.textlintrc |
textlint terminology config |
.github/dependabot.yml |
Dependabot config (Actions) |
.gitignore |
Ignore build + env artifacts |
README.md |
Repo overview + conventions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…rt, strip BOMs README now points at generate-indexes.ps1 / pwsh / -Check. Docs.yml only cancels in-progress PR runs so a Pages deploy is never cancelled mid-publish. Vendor tablesort.min.js locally instead of the unpkg CDN (self-contained build). Strip UTF-8 BOMs from generate-indexes.ps1 and Wait-CopilotReview.ps1 so shebang/#Requires work cross-platform. (dependabot cooldown is valid GA syntax — kept.)
The vendored tablesort.min.js is third-party minified code and should not be linted (eslint no-redeclare / prettier). Add FILTER_REGEX_EXCLUDE for *.min.(js|css).
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 17:10
View session
…guard README intro list now matches the real sections (Initiatives/Capabilities/Dictionary, no Ecosystem). Add #Requires -Version 7.0 to generate-indexes.ps1.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 17:24
View session
…essible table sort
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 18:15
View session
…les, group Dependabot updates
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 19:36
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 19:45
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 19:55
View session
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 1, 2026 20:04
View session
…n negated-boolean rule
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
MSX Docs is the top-of-tree documentation for the MSX ecosystem — the single home for the vision, principles, ways of working, and coding standards that every organization, repository, and agent inherits. It is written once and referenced everywhere. The site is built with Zensical and published to GitHub Pages at msxorg.github.io/docs.
The vision site
The documentation is organised into four areas:
Each section carries an auto-generated index — a table of its pages with one-line descriptions, built from page front matter — so a reader or an agent can start at the top and drill down, section to page, to the document that fits the task.
MSX is the top org that holds the vision; the organizations and repositories it points to are where that vision is demonstrated. The vision is stable, and the products that express it can change.
Build and publishing
A
Docsworkflow lints the content, builds the site with Zensical, and publishes to GitHub Pages on every push tomain. Pull requests run lint and build; publishing happens on merge.Source layout
src/zensical.toml— site configuration and navigationsrc/docs/**— the documentation contentsrc/includes/**,src/overrides/**— shared snippets and theme assets.github/workflows/Docs.yml— lint, build, and publish.github/scripts/**— documentation tooling (index generation).github/linters/**— linter configuration