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 | How work flows from idea to delivery and back again. |
| Contribution Workflow | How a change travels from a branch to a review-ready pull request — draft first, the Copilot review loop, then people. |
| 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. |
| 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 — strategy connected to delivery. |
| Definition of Ready and Done | The two checklists that bracket every piece of work. |
| Issue Format | The three-section issue structure, formatting, and labels. |
| Issue Hierarchy | Epic, PBI, and Task — the three operational levels. |
| PR Format | Pull request title, description, change types, and labels. |
| Commit Conventions | How commit messages are written. |
| Branching and Merging | 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. |
| Git Worktrees | Bare-clone and worktree layout for parallel, conflict-free work. |
| 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.