# Self Operations

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-davisjam-model-based-agentic-software-engineering-self-operations`
- **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-operations
- **Website:** https://davisjam.github.io/model-based-agentic-software-engineering/

## Install

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

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

## About

# self-operations — run the repo like a DevOps engineer

You are operating **the way the work is done** in this repository — the agent fleet and the substrate that
produces it. Your job is a DevOps engineer's: keep it running, know how it works, improve it when you
touch it. This is the *operate* half of the pair; **[`self-governance`](../self-governance/SKILL.md) is the
*harden* half.** Operate routes a break to its fix; when a failure *recurs*, hand it to self-governance.
The two are **two lenses on one substrate**, not competitors: self-governance is the *design-time* census of
controls (what exists, what's missing, how to mint one); this skill is their *run-time* operation. A
mechanism lives in that census **and** is run here — the same thing seen design-time vs run-time.

Read [`principles.md`](principles.md) — the portable operating mindset (positive-first, route-to-class,
observability-first RCA, typed runbooks, semantic-gap placement, freedom-to-improve). The rest of this
skill is the map you operate against and the bootstrap that fits it to *this* repo.

## How to use this skill

1. **Orient positive first.** Read the lifecycle map below — know the healthy baseline before you hunt
   a break. Most sessions are steady-state operation.
2. **When something breaks,** find the symptom's *class* in your Part B catalog (match the class, not the
   example that seeded the row), follow its resolving doc, and run the matching runbook's typed steps.
3. **If the cause is unknown,** RCA observability-first (`principles.md` A.3) — an observability gap is
   itself the first finding.
4. **After resolving,** if this failure has happened **more than once**, run the partner `self-governance`
   skill (interpret-failure mode) to classify the class and design the control — a registered, designed
   control, never an inline hack. Governance is design.

## The core lifecycles (the map — know normal before you hunt a break)

Every agent-fleet repo manages the same five core lifecycles (plus cron/scheduling and the operator's own
hooks where present). The *structure* is shared; only the bindings differ (your Part B).

| Lifecycle | The resource you manage | Healthy baseline | Symptom classes |
|---|---|---|---|
| **L1 · manage-agents** | the fleet: dispatch, monitor, land, tombstone, **recover** | agents ≤ cap; each has a live record; landed work cleaned up | agent died mid-flight; orphaned worktree; dispatch refused (resource); wrong-branch commit |
| **L2 · manage-context** | the operator's + agents' context windows | in-flight state banked; a fresh session reconstructs it | near compaction with unsaved state; post-compaction rebuild; idle capacity, queued work |
| **L3 · manage-git-repo** | landing work onto the mainline | ready work lands; mainline releasable; stale branches reaped | a worktree won't land; mainline un-releasable; a wrong landed commit; branch sprawl |
| **L4 · manage-deploy** | shipping | staged deploys reach green; hotfixes don't ship HEAD | deploy won't green; smoke hangs on one case; a prod bug report; hotfix-without-HEAD |
| **L5 · manage-dev-env** | the machine/host | disk/compute headroom; toolchain present; VM healthy | pressure sheds work; disk exhausted; a host tool vanished; VM mis-sized |
| **(L-cron)** | scheduled automation | scheduler live; its alerts consumed | an alert blocks new work; the scheduler broke its own fix; a queued conflict needs hands |
| **(L6 · govern-your-own-loop)** | the operator's own decision loop — hooks that fire a skipped reflex at its moment | each ambient must-do judgment is backed by a fail-open, windowed, telemetered hook | a recurrence never converted to a control; a durable lesson written to the wrong store |

The problems above are **universal**; only the *solutions* (your tools, your docs) are repo-specific.

## Bootstrap — fit the map to this repo (generate Part B)

*Discover as much as you can yourself; ask the human only for what you can't determine, and confirm the
shape before you commit it.*

- **Auto-discover (inspect the repo, don't ask).** Find how agents are dispatched, where the operational
  docs live, the deploy command(s), the host/VM (container runtime, disk sites), the scheduler/cron if any,
  and the mainline-landing path. Read the house-rules doc and the docs index if present.
- **Map to the lifecycles.** For each L1–L5 (+cron and your own loop where present), fill the healthy
  baseline and the symptom→doc rows from what you found. Cite real files/sections; the ref-lint checks them.
- **Ask the human only for the gaps** — and *state your assumptions so they correct rather than supply.*
- **Confirm the lifecycle models + runbooks with the human.** Walk them through the drafted models (right
  five? a baseline they'd state differently?) and runbooks (does each problem match a real failure? are the
  solution steps right, and correctly typed?). Their operational judgment is what inspection can't supply.
- **Emit Part B** as the typed source-of-truth (a pointer catalog + a runbook catalog) and wire the
  reference-validity lint — because a non-executable index earns trust from a ref-check, not from tests.
  Don't hand-roll it: start from the scaffolds in [`templates/`](templates/) —
  [pointers-starter.yaml](templates/pointers-starter.yaml) (the lifecycle + docs-map + symptom schema, with
  the `ref`+`#anchor` grammar in its header), [runbooks-starter.yaml](templates/runbooks-starter.yaml) (the
  typed-step schema — RUNNABLE / JUDGMENT-AUTOMATABLE / JUDGMENT-IRREDUCIBLE, one required field per kind),
  and [gen-and-lint-partb-starter.py](templates/gen-and-lint-partb-starter.py) (one stdlib+PyYAML script that
  renders Part B between provenance markers *and* lints it — file-exists, anchor-resolves, and
  counts-derived-never-quoted). Edit the YAML SSOTs, regenerate, let the lint keep the two honest.

## Examples — read one before you author Part B

Need the shape before you write? Read a shipped example under [`examples/`](examples/) and adapt it in
place. Pick by what you want to see:

- **A lifecycle model** → one per lifecycle in [`examples/`](examples/):
  [L1 manage-agents](examples/lifecycle-L1-manage-agents.md) ·
  [L2 manage-context](examples/lifecycle-L2-manage-context.md) ·
  [L3 manage-git-repo](examples/lifecycle-L3-manage-git-repo.md) ·
  [L4 manage-deploy](examples/lifecycle-L4-manage-deploy.md) ·
  [L5 manage-dev-env](examples/lifecycle-L5-manage-dev-env.md) ·
  [L6 govern-your-own-loop](examples/lifecycle-L6-govern-your-own-loop.md) — each a filled-in model
  (purpose, healthy baseline, symptom classes, owned runbooks).
- **A runbook** → [recover-the-fleet](examples/runbook-recover-the-fleet.md) ·
  [drain-an-un-releasable-mainline](examples/runbook-drain-unreleasable-mainline.md) ·
  [reclaim-a-full-disk](examples/runbook-reclaim-a-full-disk.md) ·
  [get-a-red-deploy-green](examples/runbook-get-a-red-deploy-green.md) ·
  [rca-an-ambiguous-signal](examples/runbook-rca-an-ambiguous-signal.md) ·
  [recover-a-broken-scheduler](examples/runbook-recover-a-broken-scheduler.md) ·
  [keep-the-tree-clean](examples/runbook-keep-the-tree-clean.md) ·
  [query-the-caused-by-mix](examples/runbook-query-the-caused-by-mix.md) ·
  [audit-model-code-drift](examples/runbook-audit-model-code-drift.md) ·
  [convert-a-recurring-failure-to-a-control](examples/runbook-convert-recurring-failure-to-control.md) —
  each shows the typed steps
  end to end (a RUNNABLE line, a JUDGMENT-AUTOMATABLE carried brief, a JUDGMENT-IRREDUCIBLE escalation),
  opening with its universal problem statement, then illustrative solution steps. The
  [drift-audit](examples/runbook-audit-model-code-drift.md) one is the sharpest case of the split this
  skill's runbooks are built on: it mechanizes the enumerate-and-diff of a typed model against the code it
  claims, and reserves the human for the one question a machine can't answer — is this drift a real
  divergence or an intended as-built gap? The
  [convert-a-recurring-failure-to-a-control](examples/runbook-convert-recurring-failure-to-control.md) one is
  the operate↔govern bridge: it is what you run when a break RECURS — confirm genuine recurrence, hand the
  class to the partner [`self-governance`](../self-governance/SKILL.md) skill, design the control as a
  first-class artifact, and surface the open design forks.
- **The runnable hook library** → [`hooks/`](hooks/) — a self-contained, stdlib-only Claude Code hook
  substrate you copy into your `.claude/` and adapt, in three independently-adoptable layers: **(1)** the
  reflection substrate (a Template-Method `ReflectionFacet` base + typed registry, a shared once-per-window
  Stop emitter, three generic example facets — failure→control, memory-vs-runbook, bank-consistency — and
  the measured-leash query); **(2)** the typed hook substrate (a machine-checkable hook-output schema + a
  registry that catches an inject-on-a-block-only-event bug *at construction*, plus a conformance test);
  **(3)** the banking substrate (an atomic dual-write status banker + a skill-usage measured leash) — the
  runnable half of [L2 manage-context](examples/lifecycle-L2-manage-context.md). The runnable complement to
  the [L6 govern-your-own-loop](examples/lifecycle-L6-govern-your-own-loop.md) model — read its
  [`README.md`](hooks/README.md) for the wiring + how-to-add-a-facet, and its five-part hook discipline.
  The pattern behind all three layers is **the meta-hook**: register every control into one typed seam
  per event, so your governance layer is portable across agent harnesses and readable as a census from
  one place (see [the meta-hook](hooks/README.md#the-meta-hook-one-registration-seam-per-event)).
- **Design + Epic + handoff templates** → [`templates/`](templates/) — when operating spills into
  *building* (an infra change, or the design → ratify → build → DoD feature-dev flow), author from the
  shipped [Epic template](templates/EPIC-TEMPLATE-starter.md) and
  [design-doc template](templates/design-doc-template-starter.md): they carry the required sections +
  Definition-of-Done, so a design's ratification lands *committed in the doc* (a `§G` block), not stranded in
  conversation. For L2 banking, the [emit-handoff scaffold](templates/emit-handoff-starter.py) machine-fills
  the reconstructable handoff sections from git state so re-banking is a narrative diff, not a rewrite.

Copy a sample's shape, swap in this repo's tools, drop the rest.

## Notes

- **Make it fire — cite, don't mirror.** Don't paraphrase this skill's map into your always-loaded
  CLAUDE.md: a mirrored skill is applied *ambiently* and never *invoked*, so you lose its structured value
  (the lifecycle map, the symptom→doc routing, the typed runbooks) and the two copies drift. Instead —
  keep a one-line reflex in CLAUDE.md, **cite** this skill, and wire a **trigger** (a turn-end /
  operations reflection nudge) that pushes "invoke the operate skill" the moment a substrate break or an
  RCA is in hand. The skill earns its keep when *invoked* at the decision point, not paraphrased in boot
  context. (The failure it prevents: skills that fire ~never because their content was mirrored, not cited.)
- **This skill is soft.** It aims you at how the substrate works and where a break resolves; it doesn't
  execute or block. The one hard control it recommends is a reference-validity lint over your Part B.
- **Partner with self-governance.** This routes to the fix; that classifies a recurring failure's class
  and designs the durable control. Two soft skills — one operates the substrate, one hardens it.
- **Use the `self-communicate` skill when you write a runbook, a handoff, or a banking doc.** Reach for
  [`self-communicate`](../self-communicate/SKILL.md): its shared lexicon's **Operations** cluster keeps the
  terms consistent, and its engineering register keeps a runbook readable and correctly shaped.
- **Stay in the operations lane.** This governs *operating the repo*, not the product's domain logic.

## 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:** no
- **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-operations
- 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%.