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. |
| Comparative Review Orchestration | A repeatable playbook for reviewing a target against reference sources — establishing the frame, building the evidence model before judging, and converting findings into small scoped issues. |
| 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. |
| Spec-Driven Development Templates | A copyable skeleton for every spec-driven artifact — specification, feature addendum, design, implementation doc, guide, reference, research, decision record, standard, orchestration playbook, and decisions register. |
| Evolutionary Development | Grow software as bets under selection — variation, feedback, and survival of the fittest, run as one tight loop. |
| Git Worktrees | How repository-delivery work is implemented locally — a bare-clone and worktree layout for working on several things at once. |
| Session Interactions | Recognised phrases that steer a working session deterministically, why each is defined once as a standard rather than embedded in tool-specific files, and what an interaction may not do. |
| Organization Standard | What every initiative organization must define centrally so humans and agents share the same expectations. |
| Repository Standard | The baseline files and behaviors every repository must expose so it is understandable, secure, and maintainable. |
| Repository Type Property | How a multi-select "Type" custom property classifies every repository in an initiative organization and drives which org-wide controls apply to it. |
| Automation Labels | Why every label that drives automation belongs to exactly one owning function, how namespacing keeps label dimensions disjoint, and why automation ignores labels it does not own. |
| 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. |
| Code Ownership | The three-layer model behind CODEOWNERS — permission, ownership, and enforcement — how the file is resolved and where it is read from, and why ownership without enforcement is decorative. |
| 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. |
| Continuous Delivery and Release | The distinction between integration, delivery, deployment, and release to users — and the four design decisions that follow from it, from build-once promotion to roll-forward recovery. |
| Observability | Why every failure must be registered somewhere queryable, retained long enough for trends to be visible, and written as data rather than prose so an agent can triage it. |
| DevOps Reference | A curated reading list and the principles behind the way of working. |
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.