Quick start — put MAGE to work in your repository
MAGE is an engineering methodology, not a framework or toolchain. You apply its principles to the system you already have: make important engineering knowledge explicit, check work against important requirements, and improve the engineering environment as experience reveals what was missing.
The MAGE skills help an agent participate in that work. They divide the work into three complementary responsibilities:
- Self-Governance engineers and improves the environment. It helps identify recurring failures, repeated engineering judgment, missing knowledge, and weak controls, then turn what is learned into durable improvements.
- Self-Operate runs operational lifecycles within that environment. It helps operate recurring processes, respond to failures, and return evidence about deficiencies that may warrant improvement.
- Self-Communicate helps articulate the system to others. It supports clear technical explanation through terminology, prose, rhetoric, diagrams, and other forms of communication. Some of the resulting artifacts may themselves become canonical parts of the engineering environment.
The skills are complementary rather than sequential. Self-Governance may improve structures that Self-Operate later relies on; Self-Operate may reveal deficiencies that call for further governance conversion. Self-Communicate helps people understand the system and its engineering structures, and may contribute durable artifacts where that communication itself belongs in the environment.
Install the MAGE skills
The MAGE plugin installs all three skills:
/plugin marketplace add davisjam/agent-governance-mechanisms
/plugin install mage@agent-governance-mechanismsStart a new Claude Code session after installation.
The skills are source-visible and MIT-licensed. They can inspect your repository and propose changes; consequential writes remain subject to your approval.
If you cannot install a third-party plugin, the skill sources can also be read and adapted directly. You do not need a particular agent platform to apply the MAGE method.
Self-Governance — improve the engineering environment
Reach for Self-Governance when the same failure keeps recurring, engineers repeatedly supply the same judgment, important system knowledge must repeatedly be reconstructed, or an important requirement is not reliably checked.
A useful first step is an audit:
self-governance: audit this repository for places where important knowledge is
repeatedly reconstructed, engineering judgment is repeatedly supplied, failures
recur, or important requirements are not reliably checked.
Prioritize the opportunities by expected benefit and cost. Tell me what you
would improve first and why. Advise only; change nothing.An audit is not a demand to add controls everywhere. MAGE treats durable engineering structure as an investment. A proposed improvement should address a real or anticipated engineering cost and justify the burden of creating and maintaining it.
When you already have a recurring failure in hand, start there instead:
self-governance: examine this recurring failure and determine what the
engineering environment is missing. Propose a durable change that would prevent
the failure, detect it earlier, or reduce the judgment required when it occurs.
Show me the proposed change and its expected cost before modifying anything.The appropriate response might be a model, validator, constraint, safer interface, procedure, or another change to the environment. The point is not to select an item from a catalogue. It is to determine what this engineering system should learn from the failure.
Self-Operate — run the operational lifecycles
Reach for Self-Operate when the problem is not primarily changing the engineering environment but running something within it: deployment, queues, scheduled work, agent fleets, session boundaries, recovery procedures, or another recurring operational lifecycle.
For example:
self-operate: examine how this repository runs and recovers this lifecycle.
Identify the operational states, evidence, known failure conditions, and
recovery procedures already present.
Tell me what is explicit, what is being reconstructed during operation, and
what would make this lifecycle safer and easier to operate. Propose before
changing anything.Self-Operate should use the engineering environment rather than reconstruct it on every run. When operation reveals a recurring deficiency in that environment, the evidence can feed back into Self-Governance.
That feedback is important: operation produces evidence for engineering.
Self-Communicate — articulate the system to others
Reach for Self-Communicate when someone needs to understand the system: its architecture, behavior, rationale, terminology, operation, or another engineering concern.
Self-Communicate works on the problem of explanation. It can help choose the right form, establish consistent terminology, write precise engineering prose, construct diagrams, and audit whether an explanation actually communicates what its audience needs.
For example:
self-communicate: help me explain this system to an engineer who needs to work
with it. Inspect the relevant code and existing engineering material first.
Determine what the audience needs to understand, propose an appropriate
combination of prose and diagrams, and identify terminology that must remain
consistent. Show me the proposed structure before drafting it.Some communication is transient: an explanation for a particular discussion, review, or presentation. Other communication becomes part of the system's durable engineering knowledge. A confirmed architecture description, house lexicon, diagram, or other explanatory artifact may therefore become a canonical part of the engineering environment.
The distinction is purpose, not file type. Self-Communicate helps articulate the system; it does not own every document merely because that document contains prose.
Start with work you are already paying for
You do not need to install a large collection of artifacts or redesign the repository before MAGE becomes useful. Start where the engineering cost is already visible.
- A failure keeps recurring? Use Self-Governance to ask what the environment should learn from it.
- An operational lifecycle repeatedly requires reconstruction or intervention? Use Self-Operate to make the lifecycle explicit and run it against the engineering environment.
- Someone cannot understand an important part of the system reliably? Use Self-Communicate to articulate it clearly—and, when that explanation has enduring value, preserve the resulting artifact.
The skills can lead into one another. Operation exposes deficiencies. Governance changes the environment. Communication makes important aspects of the system intelligible to the people who must understand them.
MAGE is successful when those improvements earn their keep, not when a repository accumulates the largest possible collection of controls or artifacts.