Make it easy, to move fast, in a safe way#
Every decision — from architecture to commit message — is filtered through those three words.
Easy#
Simplicity is a feature. Make the right thing the easy thing — for users, contributors, and agents alike. Prefer the obvious and limited over the powerful and confusing. Automate what is mechanical so that human attention is saved for decisions that require judgment, context, and care.
The safe and smart choice should be the default choice. Design systems, tools, and workflows so that doing the right thing requires no extra effort — while allowing a deliberate override when necessary.
Fast#
Shift left, ship early, learn fast, iterate. Work flows in small increments — draft PRs, micro-commits, quick reviews. The faster we close the loop between intention and observation, the faster we improve and evolve what we are building.
Safe#
Every decision should be reversible. Every release should be observable. Every failure should teach. Speed requires safety — we can only iterate fast when changes are cheap to undo, easy to monitor, and failures produce learning rather than blame.
What this is#
MSX is the umbrella for everything I build on GitHub. This site is the top of the tree — the vision, principles, and ways of working that every organization, repository, and agent inherits. It is written once, here, and referenced everywhere.
- The why lives in the Vision.
- The how lives in the Ways of Working and the Coding Standards.
- The what — the products that make the vision real — lives across the Initiatives.
This separation is deliberate. The vision is stable; the products that express it come and go. Keep the principles in one place, reference them from many, and the whole system stays coherent as it grows.
Documentation map#
Each area below carries its own index. Start here, read the descriptions, and follow the links inward — section to page — until you reach what you need. Agents work the same way: review the index, then drill down to the document that fits the task.
| Section | Description |
|---|---|
| Vision | The mission and the philosophy of easy, fast, and safe. |
| Initiatives | The products that make the vision real — PSModule, AzActions, TFActions, and the tools built along the way. |
| Ways of Working | How work happens across the ecosystem — for humans and agents alike. |
| Coding Standards | The shared baseline every repository inherits, and the per-language standards that build on it. |
| Capabilities | The capabilities the ecosystem builds, each documented by a spec (why and what) and a design (how and what). |
| Dictionary | Shared vocabulary for the MSX ecosystem — the terms a reader or agent meets across these docs. |
Where the why comes to life#
This site explains the vision. The vision becomes real in the organizations and repositories that adopt it — each one a concrete answer to "what would this look like if it were easy, fast, and safe?"
See the Initiatives for where the principles on this site are put into practice.
Built for humans and agents#
Everything here is written once, for two audiences. A human reads it to understand how we work. An agent reads the same words as context before it acts. There is no separate "agent manual" — the documentation is the manual, and keeping it evergreen keeps both audiences aligned.
Start with the Vision, or jump straight to the Ways of Working.