Govern

Govern — Decision Lifecycle Orchestrator

Overview

Takes a development decision and runs it through a five-phase lifecycle — route the right artifact (or none), discuss it through an adversarial critic panel scaled to the decision's weight, gate it behind an explicit human sign-off, write the durable record to docs/, then link it to the commit/PR and recommend the next step. Every governed decision lands with AI-provenance attached and a human's name on it. An agent proposes; a human approves.

When to Use

• A substantial, ambiguous design or architecture choice — behavior, public API, data schema, a dependency swap, a module boundary, security posture, or anything hard to reverse with more than one defensible approach.
• Triggers: "should I X or Y", "write an ADR for X", "decide between A and B", "record this decision".

When NOT to use

• Behavior-preserving refactors, objective improvements (warning removal, a speedup), dev-invisible tweaks — exempt; just build.
• Trivial one-line fixes or throwaway prototype/spike code — the artifact overhead loses.
• Auditing artifacts that already exist — use gov-review. Installing the policy block — use gov-init.

Input

• $ARGUMENTS — the decision to govern (free text). If empty, ask the user what decision to govern; never guess.
• artifact:adr|rfd|design|auto — optional explicit artifact override. auto or absent lets the router choose.
• rich — optional flag requesting the richer ADR (MADR) variant.

Constants

• MAXDISCUSSITERATIONS: 3 | MAXPANELAGENTS: 4 | TASK_DIR: .mz/task/
• DECISIONSDIR: docs/decisions/ | RFCSDIR: docs/rfcs/ | DESIGN_DIR: docs/design/
• Default statuses: ADR proposed | RFD prediscussion | design draft

Core Process

Phase Overview

| Phase | Goal | Details | Loop? | | ----- | -------------------------------------- | ------------------- | ------------------ | | 0 | Setup | inline below | — | | 1 | Propose — route the artifact (or none) | phases/propose.md | — | | 2 | Discuss — weight-scaled critic panel | phases/discuss.md | max 3 (heavy only) | | 3 | Decide — human sign-off gate | phases/decide.md | feedback loop | | 4 | Record — write durable artifact | phases/record.md | — | | 5 | Enforce — link commit/PR, recommend | phases/enforce.md | — |

Phase 0: Setup (inline)

1. Parse $ARGUMENTS: the decision text, an optional artifact: override (adr/rfd/design/auto), and the optional rich flag. Empty decision → AskUserQuestion; never guess.
2. Derive task_name = _govern_ where ` is today's date (underscores) and is a snake_case summary of the decision (max 20 chars). On same-day collision append v2, v3`.
3. Resume check (before creating the directory) — read .mz/task//state.md if it exists:

• No file → fresh task; proceed.
• Status complete or aborted_by_user → auto-suffix _v2/_v3, log the bump to chat, proceed fresh.
• Status running or failed → present a Resume gate via AskUserQuestion (Resume re-enters at the recorded Phase; Restart archives the dir to _archived_/ and starts fresh; New suffixes _v2). The human sign-off in Phase 3 never auto-resumes — re-present it.

1. Create .mz/task//. Write state.md per the inline v2 contract (State Management below): first line schema_version: 2, then Status: running, Phase: 0, PhaseName: setup, Started: , Iteration: 0, FilesWritten: [], phase_complete: false, what_remains: [], plus Decision: , ArtifactOverride: , Rich: .
2. Dispatch gov-provenance-recorder to write .mz/task//provenance.md for this run — pass the task dir, the authoring agent (gov-artifact-writer, the agent that will write the durable record), the exact model id, the current ISO timestamp, and the trigger origin (user-prompt for a direct /govern, automation when the governance policy directed this invocation). It initializes human_signoff: pending. Append provenance.md to FilesWritten.
3. Emit a setup block: task_name, decision summary, override, rich flag, provenance path + derived trigger.

Read phases/propose.md and proceed to Phase 1.

Phase 1: Propose

Dispatch gov-router to run the two-gate selection and write routing.md. If ARTIFACT: none → record a one-line exemption note, keep provenance, update state, and stop at Phase 1 (report to the user — no discussion, no gate). Otherwise draft the populated artifact into .mz/task//draft.md and carry WEIGHT forward. See phases/propose.md.

Phase 2: Discuss

Weight-scaled. heavy → four opus critics in one parallel message (manifest first), then gov-discussion-synthesizer; loop the draft against the synthesis up to MAX_DISCUSS_ITERATIONS, escalating at the cap. light → one gov-critic-quick pass whose output is the verdict. ARTIFACT: none never reaches here. See phases/discuss.md.

Phase 3: Decide

The human sign-off gate — the whole point of the pipeline. This orchestrator (not a subagent) emits the verbatim draft.md plus the verdict and the AI-provenance block as a plan-style chat message, then a short Approve/Reject AskUserQuestion selector beneath it. Approve → stamp human_signoff, advance status, go to Phase 4. Reject → write nothing to docs/. Any other reply is feedback → revise and re-present. No auto-approve bypass exists on this gate. See phases/decide.md.

Phase 4: Record

Dispatch gov-artifact-writer (only after sign-off is stamped) to write the durable docs//NNNN-slug.md with sequential numbering, the embedded provenance fence, and an initial status from the configured vocabulary. Append the path to FilesWritten. See phases/record.md.

Phase 5: Enforce

Detect git context (commit, branch, optional open PR — read-only), append a ## Provenance / Links section to the artifact, advance status where appropriate, and recommend the next skill (never auto-invoke). Mark state complete, what_remains: []. See phases/enforce.md.

Techniques

Techniques: delegated to phase files — see the Phase Overview table above.

Common Rationalizations

Common Rationalizations: delegated to phase files — propose.md (skipping the router), discuss.md (skipping the panel), decide.md (skipping the human gate).

Red Flags

• You drafted to docs/ before the human sign-off gate passed, or while provenance.md still read human_signoff: pending.
• You routed from memory instead of dispatching gov-router, or skipped the discuss panel on a heavy decision.
• You auto-approved the Phase 3 gate, or treated critic consensus as the human's approval. There is no auto-approve here.
• You auto-invoked the recommended next skill in Phase 5 instead of recommending it.

Verification

Verification: delegated to phase files. Each phase emits a visible block; the final enforce block lists the artifact path, status, sign-off signature, git links, and the recommended next step, with state.md marked complete and what_remains: [].

Error Handling

Detect → escalate via AskUserQuestion → never guess. Empty decision, an unreadable reference/template, an agent returning BLOCKED (retry once, then escalate), and MAX_DISCUSS_ITERATIONS hit without convergence (offer accept-with-unresolved / guidance / abort) all escalate. Always save state before dispatching agents.

State Management

State persists to .mz/task//state.md. Schema is v2: the file's first line is schema_version: 2, and alongside the skill's existing Status / Phase / Started keys it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.

Append every produced artifact to FilesWritten (routing.md, provenance.md, draft.md, discuss/discussion files, the docs/ artifact). Record human_signoff only after the Phase 3 gate. Never rely on conversation memory for cross-phase state — context compaction destroys specific paths and decisions.

Source & license

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

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

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