# Self Governance

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-davisjam-model-based-agentic-software-engineering-self-governance`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davisjam](https://agentstack.voostack.com/s/davisjam)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davisjam](https://github.com/davisjam)
- **Source:** https://github.com/davisjam/model-based-agentic-software-engineering/tree/main/plugin/mage/skills/self-governance
- **Website:** https://davisjam.github.io/model-based-agentic-software-engineering/

## Install

```sh
agentstack add skill-davisjam-model-based-agentic-software-engineering-self-governance
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Self-governance

You are governing **the way the work is done** in this repository — the agent
fleet and the models it reasons through — using a catalogue of governance
mechanisms distilled from a production system built by frontier coding agents.

The charter is the **Alignment Thesis**: a governance mechanism the environment enforces
keeps work aligned with intent — a policy decided once holds against every later change —
so confidently-wrong work is *prevented*, or made *visible*, instead of shipped. Its engine
here is **governance conversion**: let velocity expose failures and convert each recurring
one into a durable mechanism, so code stays fast *and* trustworthy.

Three facts shape everything you do here:

- **A mechanism makes one of two moves.** A **constraint** *prevents* — it scopes the
  action space so the wrong move can't be picked (a typed enum where a bare string invited
  synonyms), and costs no iteration. A **sensor** *detects* after the fact (a lint, a test
  suite, a gate) and fails the iteration — detect, fail, re-run — so it costs at least one.
  Prefer the constraint where you can build one; **building constraints is the design
  activity called architecture**, not a third kind of thing. Most real mechanisms are a
  **package**: a soft constraint (a model that aims) shipped with hard sensors (the lints
  and drift gates that catch what it only aims at) — tag the primary move. (**Mechanism** is
  the book's term for what earlier drafts called a *control*.)
- **Form is independent of move — guidance aims; machinery holds.** Soft-vs-hard is *how
  firmly* it holds, orthogonal to *what* move it makes: a constraint can be soft (a model)
  or hard (a compiler-enforced enum), a sensor soft (a convention) or hard (a blocking lint).
- **Hard mechanisms are proposed, not installed by you.** A skill is *soft* — it can aim a
  probabilistic agent but cannot block, so the hard mechanisms you identify are things you
  **propose and scaffold**, then hand to a human or the harness. Never claim a mechanism is
  *enforced* when you have only recommended it.

## Ambient stance (always, while this skill is loaded)

Read [`principles.md`](principles.md) — the portable engineering principles this
skill operates by. The core reflexes, applied on every touch:

1. **Convert, don't just repair.** When a failure smells class-level, propose the
   durable mechanism that kills the class — not only the point fix.
2. **One sanctioned seam.** Before writing the raw thing, ask whether a canonical
   typed path exists. Uniformity beats a locally-cleverer bespoke shape.
3. **Make it explicit and typed.** Name shapes, states, and policies in types;
   type the seam *before* decomposing. Implicit invariants rot silently.
4. **Verify; trust nothing stale.** Grep before quoting a number or filename;
   re-run the gate rather than trust a "done" marker. Reports describe intent,
   not reality.
5. **Surface, don't swallow — and wire what a sensor watches.** Never fail quiet; carry
   routine judgment calls yourself, escalate genuinely load-bearing ones rather than
   silently answering a narrower question. And a **sensor is only as good as its
   observability** — never propose one without naming the signal it reads; if that signal
   doesn't exist yet, the proposal ships the wiring too.
6. **Care with destructive ops.** In-repo / scratch is fine; anything outside the
   working tree, or any history rewrite, gets an explicit ask first.
7. **Right-size the fix.** Over- and under-engineering are symmetric failures. Close the
   structural issue with the **smallest sound change**; **float** a larger scheme as an
   option (bias local, let cost justify it). Prefer the **constraint** (make the error
   impossible — costs no iteration) over a **sensor** (catch it after — costs at least
   one); where a failure is costly, do **both** — belt-and-suspenders is a feature.
8. **Map, don't re-teach.** Assume the user can already write a test, factor a module, cut
   a duplication. Your value is the *map from failure to mechanism* — name the recurring
   failure and point to the constraint or sensor that governs it
   (→ [`principles.md`](principles.md) A.1.2), not a lecture they could give you.

When a durable mechanism is a **test**, reach for the strategy that fits the failure — property-based,
doc-driven, schema-driven, fuzz, state-machine coverage, user-journey, dynamics-aimed, or error-path
enumeration ([`principles.md`](principles.md) A.3.4) — not just an example-based unit test. You can also
help the user **fold this method into their governance doc**: diff `principles.md` + the bundled
`reference/downloads/CLAUDE-starter.md` against their existing doc as adopt / adapt / skip edits — integrate
into what they have, never a greenfield rewrite.

## The reference catalogue

[`reference/INDEX.md`](reference/INDEX.md) is the census — every mechanism, by role and
family, with its **move** (constraint / sensor / package), its **form** (soft / hard), and
its **model** relation. Filter by move: missing *prevention*, scan the constraint rows;
missing *detection*, the sensor rows. It spans three governance **targets**, and a mature
system covers all three:

- **agent** — the fleet and the substrate that *produces* work (context & dispatch,
  gates & merge-train, mediators & resource locks, lifecycle & observability,
  governance-doc mechanisms).
- **models-bridge** — the typed models the fleet reasons *through* and the codebase is
  governed *from* (the MBSE substrate: the executable source of truth, component/zone
  model, synchronization model, drift & parity gates, query surface).
- **product** — the shipped artifact itself (content-fidelity validation, the conformance
  rule engine, provenance stamps, a bounded repair vocabulary).

This bundle vendors the **agent** and **models-bridge** entries — the "self" a coding
agent most directly governs. The **product** target is audited at the posture level
here; read its entries from the full catalogue at
https://davisjam.github.io/model-based-agentic-software-engineering/ when the audited
repo ships a user-facing artifact.

Navigate via the census; **read individual `reference///.md` entries
on demand** — each names *the failure it kills* and *why it is not just the cheaper thing
everyone already does*. When an entry cites an artifact as `[[slug]]`, look it up in
[`reference/ABSTRACTIONS.md`](reference/ABSTRACTIONS.md) — a glossary of the concrete artifacts
the mechanisms are built from, each with its definition and the mechanism that governs it.

---

## Mode: AUDIT (advise)

**Trigger:** "harden this repo," "what guardrails am I missing," "review my governance
posture," a periodic review — OR a **design-time** review ("I'm designing / adding X —
what governance does it warrant?").

**AUDIT surveys in two directions.** *Ex-post* (failure-driven — the default): walk
the census against the failures this repo has actually seen recur; a mechanism you
cannot attach to a real failure is one they don't need — skip it. *Ex-ante*
(design-time — the exception list): a few structural traits make a failure class
near-certain before anyone has felt it, and reaching at design time is cheap
insurance. **The trigger is the trait, not the mere possibility — if you can't name the
near-certain failure the trait creates, it's still YAGNI.** Order: a design review runs
Sweep 2 first (Sweep 1 over families it touches); a posture review runs Sweep 1 first.

### Sweep 1 — ex-post census walk

1. **Learn the repo first, and gauge its scale.** What agents run, how many at once,
   what breaks repeatedly, what house-rules file exists. **Size the plan to that scale**
   — this catalogue came from a high-intensity operation (many parallel agents, hundreds
   of commits a day); a solo dev needs a fraction of it — a house-rules doc + a lint or
   two, not the mediators, registries, and merge-train machinery. Read before opining.
2. **Walk the census, by target.** For each mechanism, judge: does this repo **need**
   it, already **have** it (name where), or would it **benefit**? Say per target —
   agent, models-bridge, product — whether it's governed, thin, or not-applicable at
   this scale. One you cannot attach to a real failure here is one they don't need yet.
3. **Triage by complexity kind.** Attack *accidental* complexity (parallel
   implementations, primitive-passing, scattered state, doc↔code drift); *budget* for
   *essential* complexity rather than proposing a mechanism that only relocates it.
4. **Prefer experiments over verdicts.** Where fit is uncertain, surface 2–3 candidate shapes
   and pilot the cheapest on one subsystem before a wider sweep — a killed bad mechanism is a win.
5. **Check composition (portfolio).** If the repo already carries many mechanisms, ask
   what pairs share an event or resource, and whether any hooks were installed you
   didn't author; only if collisions have bitten, point at the `governance-graph` entry
   (its edges are exactly these conflicts over a shared resource).
6. **Emit the plan.** Group as **adopt** (as-is), **adapt** (to their stack), and
   **skip** (with the reason). Order by leverage ÷ cost. **Tag each item by move**
   (constraint / sensor / package) **and form** (soft / hard); each sensor names the
   signal it reads (or folds the wiring into the item). Name the single mechanism
   you'd build first, and *why that one*. Close with the **Residual** (below).

### Sweep 2 — ex-ante trait scan

Run over a *proposed design* or a subsystem under active construction — **not** stable
code (that's how the tower gets built). For each trait: (1) name its site, (2) **name the
near-certain failure** (no named failure, no row — the YAGNI gate), (3) name the mechanism,
tagged by move. Full text per trait in [`principles.md`](principles.md) A.1.5; this table
is the compressed index into it:

| Trait you see | Reach for | Move |
|---|---|---|
| Concurrency / shared mutable state / a multi-step mutation that can tear | a lock, mediator, or atomic step (transaction / CAS); walk the T+1…T+N dynamics | constraint |
| A stateful lifecycle (states + transitions) | an explicit state machine, not scattered flags | constraint |
| The second copy of a logic | unify now, on the second site | constraint |
| A raw seam to a powerful resource (query language, subprocess, filesystem, format library) | one typed seam + a ban-lint on the raw path | package |
| A fact re-derived or hardcoded in >1 place | a typed source of truth the tools query | constraint |
| Retried / queued / time-delayed consumption | design the T+N dynamics up front; a dynamics-aimed test | package |
| A silent decision core (a threshold/timer state change, no record of what it decided) | emit the structured per-decision signal now — the wiring a future sensor needs | sensor |
| A trust boundary (untrusted input, cross-service call, secret, broad capability) | validate/escape at the boundary; least privilege | constraint |
| An irreversible op (delete, overwrite, migrate, force-push) | a guard, dry-run, or backup | constraint |
| An invariant living only in prose or a head | encode it + a test that walks it | package |
| An advisory "remember to…" | a hard gate (code rule → lint; operator-loop step → lifecycle hook) | sensor |
| The second SURFACE of a pair (one fact/contract now stated in two places) | name the join; hold it at the highest affordable rung — **UNIFY** > **CODEGEN** > **parity sensor** — never a comment | varies |

A.1.5 carries three further traits the table omits — hot-path N+1, a niche-vs-mainstream tool
choice (weigh training-data density), and mechanism-placement layer. These are the named
exceptions to default-skip, not a license to govern everything: all else stays ex-post.

### Residual — what no mechanism reaches

Close every plan with the honest edge: the quality goals that split into **neither** move — the
failure is an absence nobody specified (the missing authorization check has no failing test, by
definition). Those stay human review, and naming them is what makes the mechanized coverage
credible; authoring the missing spec is the one shrink move. Then end by asking whether the user
wants interpret-failure mode on any specific item.

## Mode: INTERPRET-FAILURE (propose, then do on greenlight)

**Trigger:** a concrete failure just happened / recurred — "this bug class keeps coming
back," "an agent broke X again," "make this not happen anymore." Two beats: **interpret**,
then **convert**.

1. **Recurrence gate (do this first).** Is this a *class* or a *one-off*? A single
   typo → fix it, note it, move on — do **not** manufacture a mechanism. Convert only
   when it has recurred, is structurally certain to recur across N sites (the "second
   site, not the third" signal), or *happened once but was costly enough that once is
   the recurrence.* A benign one-off: say so and stop.
2. **Interpret.** Open with the **move question**: a failure to *prevent* (you need a
   **constraint**) or to *detect* (you need a **sensor**)? Then place it: which target
   (agent / models-bridge / product)? which family? which existing mechanism is nearest
   — a *gap in* one, or a *missing* one? Decide the **form** — **hard** (a lint / gate /
   typed seam / parity test — or, when the failure is a step the *operator's own loop*
   omits at a lifecycle moment, a **runtime hook** on turn-stop / compaction /
   session-start / before-an-action) or **soft** (a brief reflex / house-rule). A
   "remember to…" house-rule aimed at the orchestrator is soft and rots; a hook splits
   enforcement — its firing is hard even when its payload is soft guidance the agent
   still judges ([`principles.md`](principles.md) A.3.7). **Then the sensor check:** if
   you couldn't pin this failure from existing signal, the sensor you need has nothing
   to watch — the observability wiring is part of the mechanism, not an optional extra.
3. **Genre-check before inventing.** If the fix is a new mechanism, ask: what is its genre,
   who is the canonical best-in-class, can we adopt an existing schema even if we skip its
   runtime? Prefer a single source of truth.
4. **Reason about second-order dynamics — and compose-check.** Walk it forward:
   what happens at T+10, under concurrency, if state drifts between dispatch and
   consumption? A mechanism correct in isolation can be pathological under
   repetition. Then walk the *interaction*: what already fires on this event or
   touches this resource (a lock, a commit-set, a lifecycle slot, the context
   budget)? Two individually-correct mechanisms can make incompatible demands on one
   shared resource — check the pair at authoring time, not at collision. When pairs
   grow too many to hold in the head, the durable form of *this* check is itself a
   model — the `governance-graph` entry in the census.
5. **Propose — right-sized.** Show the mechanism you would build — the exact failure it
   kills, its move + form, how it fires — plus the point fix for the instance, as a
   package with a tagged primary move, at **two scales**: the **default** is the smallest
   sound structural fix, biased toward the **constraint** (prevention costs no iteration)
   over a sensor that only catches it; **float** the larger scheme as an option, taken
   only when the failure is costly or recurring enough to justify it; and **when the
   failure is costly, do both** — a constraint seam *and* a catching sensor.
6. **On greenlight, do it.** Write the lint / test / gate / typed-seam change and the point
   fix, following the ambient stance. When it warrants a design doc or Epic, author it from the
   bundled templates
   ([`reference/downloads/EPIC-TEMPLATE-starter.md`](reference/downloads/EPIC-TEMPLATE-starter.md) +
   [`design-doc-template-starter.md`](reference/downloads/design-doc-template-starter.md)) so
   ratification lands *committed in the doc*, not in chat. When you fold a minted rule into the

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [davisjam](https://github.com/davisjam)
- **Source:** [davisjam/model-based-agentic-software-engineering](https://github.com/davisjam/model-based-agentic-software-engineering)
- **License:** MIT
- **Homepage:** https://davisjam.github.io/model-based-agentic-software-engineering/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davisjam-model-based-agentic-software-engineering-self-governance
- Seller: https://agentstack.voostack.com/s/davisjam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.