Ways of Working#
Shared conventions for how work happens across the MSX ecosystem — for humans and agents alike.
This section documents the principles, processes, and norms that every contributor follows. Whether you're opening an issue, writing a commit message, reviewing a pull request, or planning a feature — the answer is here.
Contents#
| Page | Description |
|---|---|
| Workflow | The canonical process from idea to delivery, including how to resolve and enter each workflow stage. |
| Workflow Stages | Procedures for each stage of the canonical Workflow, reached through indexes or direct task-language shortcuts. |
| Contribution Workflow | How a change travels from a branch to a review-ready pull request — draft first, the Copilot review loop, then people. |
| Fleet Orchestration | How one change is rolled out across many repositories through Task or Bug delivery leaves tracked entirely on GitHub. |
| Documentation Model | How every capability is documented — a spec for the why and a design for the how, colocated, concise, and kept evergreen for humans and agents alike. |
| Spec-Driven Development | The specification is the source of truth — the spec (why and what), its design (how), and how a change moves from need to shipped. |
| Evolutionary Development | Grow software as bets under selection — variation, feedback, and survival of the fittest, run as one tight loop. |
| Agentic Development | How ways of working, standards, and documentation are authored once and consumed by both humans and agents. |
| Git Worktrees | How agentic development is implemented locally — a bare-clone and worktree layout for working on several things at once. |
| Organization Standard | What every initiative organization must define centrally so humans and agents share the same expectations. |
| Repository Standard | The baseline files and behaviours every repository must expose so it is understandable, secure, and maintainable. |
| Repository Type Property | How a single "Type" custom property classifies every repository in an initiative organization and drives which org-wide controls apply to it. |
| Principles | The foundational beliefs and product mindset behind every decision. |
| Engineering Taste | The judgment that takes over when the standards run out. |
| Goal-Setting Framework | Mission, OKRs, and Initiatives — the strategy above repository Epics. |
| Definition of Ready and Done | The three gates that bracket every piece of work. |
| Issues | How issues are formatted and organized across the MSX ecosystem. |
| PR Format | Pull request title, description, change types, and labels. |
| Commit Conventions | How commit messages are written. |
| Branching and Merging | Delivery-leaf topic branches, pull-request-only integration, and merge models. |
| Review Etiquette | Tone, scope, severity, and how to disagree well. |
| Repository Segmentation | What belongs in a repository, and when to split or combine. |
| README-Driven Context | Why the README is the front door and the source of truth. |
| Continuous Practices | The Continuous X family, Continuous AI, and the DevOps Dojo pillars. |
| DevOps Reference | A curated reading list and the principles behind how we work. |
Who this is for#
Everyone. If you contribute to an MSX project — by code, review, issue, or discussion — these are the norms you follow. Agents follow them too; they read these pages as context before acting.