OpenClaw Governance (openclaw-gov)

Teaches agents to maintain the governance root: registry.yaml, runbooks, CHANGELOG, and CI drift checks. Pick one workflow below; do not run the full ship path for a read-only audit.

Step 0 — Resolve governance root

Precedence: --root PATH > OPENCLAW_GOVERNANCE_ROOT > nearest governance.config.yaml walking up from cwd > ~/.openclaw/governance.

Workspace override: If the agent workspace AGENTS.md governance stanza (\x3C!-- openclaw-governance:begin -->) declares a Governance root path, use that path as $GOV_ROOT when it differs from the default. The stanza wins over skill defaults for this install.

export GOV_ROOT="${OPENCLAW_GOVERNANCE_ROOT:-$HOME/.openclaw/governance}"
# If AGENTS.md stanza specifies a path, set GOV_ROOT to that path instead.

Version preflight (required)

This skill assumes openclaw-gov v0.5.5+ (--inventory, --staged, inventory schema v2). Before using those flags:

openclaw-gov --version   # expect 0.5.5 or newer

If older, upgrade per Install CLI before --inventory, --staged, --promote, or schema-v2 assumptions.

Shared preflight (before any edit or ship)

Agents share the governance repo with humans. Never overwrite unrelated user work.

cd "$GOV_ROOT"
git status --short --branch

• Dirty worktree with changes outside your task: stop. Do not ship start, --write, --promote, or regen --write. Tell the human what is dirty; offer to scope edits to governance paths only after confirmation.
• Unexpected changes under workflows/ you did not make: read the diff before proceeding.

Then confirm config:

openclaw-gov doctor --validate-config --root "$GOV_ROOT"

Pick a workflow

Material threshold: references/material-change-threshold.md

Governing runbook for material work: workflows/runbooks/main.system_config_change_governance.md under $GOV_ROOT.

Workflow A — Read-only audit

No ship start. No --write, --promote, or regen --write.

openclaw-gov doctor --validate-config --root "$GOV_ROOT"
openclaw-gov discover --root "$GOV_ROOT"
openclaw-gov check --root "$GOV_ROOT"
openclaw-gov regen --check --root "$GOV_ROOT"

Optional JSON (targeted slices only): references/discovery-json-slices.md

Pipe only stdout for --json; human report is on stderr.

Workflow B — Material change

For system updates, cron/workflow/runbook/registry changes, and other material work. Branch before any mutating command.

cd "$GOV_ROOT" && git status --short --branch   # preflight again
openclaw-gov doctor --validate-config --root "$GOV_ROOT"

openclaw-gov ship start --branch "governance/$(date +%Y-%m-%d)-short-topic" --root "$GOV_ROOT"
# ... edit runbooks, registry, CHANGELOG; discover --inventory / --staged / --promote as needed ...

openclaw-gov check --root "$GOV_ROOT"
openclaw-gov regen --check --root "$GOV_ROOT"
# If regen --check fails ONLY because README/RACI markers drifted:
openclaw-gov regen --write --root "$GOV_ROOT"

Regen rule: default to regen --check. Run regen --write only when regen --check fails or you intentionally changed content that regen generates. Do not run regen --write habitually on every doc edit.

Completion checklist (before calling done):

• Live change applied and verified (see Verification)
• Runbook updated under workflows/runbooks/
• workflows/registry.yaml updated if workflow is new or materially changed
• workflows/CHANGELOG.md entry appended
• check and regen --check pass

If the change is material, continue to Workflow C unless site policy says otherwise.

Workflow C — Ship PR

Run Preflight before ship first. Use one commit path below — not both.

Preflight before ship

cd "$GOV_ROOT"
git status --short --branch          # clean or only your intended files
git remote -v                        # origin configured
openclaw-gov doctor --validate-config --root "$GOV_ROOT"
gh auth status 2>/dev/null || true   # only if you will push
openclaw-gov check --root "$GOV_ROOT"
openclaw-gov regen --check --root "$GOV_ROOT"

If worktree is dirty with unrelated changes, stop (see Step 0).

Branch and validate

openclaw-gov ship start \
  --branch "governance/$(date +%Y-%m-%d)-short-topic" \
  --root "$GOV_ROOT"
# ... edits already done on this branch, or make them now ...

openclaw-gov check --root "$GOV_ROOT"
openclaw-gov regen --check --root "$GOV_ROOT"
# If regen --check failed: openclaw-gov regen --write --root "$GOV_ROOT" then re-check

Use an explicit --branch name (date + topic) for audit trails; avoid anonymous default branch names during incidents.

Commit — choose ONE path

Path 1 — Local commit only (human pushes later):

openclaw-gov ship commit \
  -m "docs(governance): describe the change" \
  --no-push \
  --root "$GOV_ROOT"

Path 2 — Commit + push + PR (non-interactive agents):

openclaw-gov ship commit \
  -m "docs(governance): describe the change" \
  --push \
  --root "$GOV_ROOT"

Do not run ship commit and then ship commit --push as two steps.

Publish policy override

Default: ship commit --push uses git push + gh pr create when gh auth login is satisfied.

Site override: If the governing runbook, workspace TOOLS.md, or operator policy defines a stricter path (GitHub MCP only, human must open PR, no direct push), follow that policy instead of the default CLI push. When override applies, use Path 1 (--no-push) and hand off per local docs.

Conventional Commits (required)

Format: type(governance): imperative summary — never vague messages (update, WIP).

Prefer ship commit -m "..." over inferred generic messages.

Post-merge cleanup

After the governance PR merges:

cd "$GOV_ROOT"
git fetch --prune origin
git switch main
git pull --ff-only origin main
git branch -d governance/YYYY-MM-DD-short-topic   # or -D if squash-merged
openclaw-gov check --root "$GOV_ROOT"
openclaw-gov regen --check --root "$GOV_ROOT"

What counts as material

Governance PRs are required for system updates, workflow/cron/runbook changes, and major operational changes you would need to restore from git. Full examples: references/material-change-threshold.md.

Cross-repo: material script-path or cron-payload changes in other repos need a paired governance PR in the same change window.

Verification — local vs external

Local (default, no ask): doctor, discover, check, regen --check, read-only git diff, parsing inventory JSON.

External / side effects (ask first): smoke tests that send telemetry, hit production APIs, restart gateways, run live crons, post to chat, or mutate off-host state. Separate these from governance doc validation. Get explicit approval before running; document what ran in the runbook/CHANGELOG.

NEVER (critical)

1. Do not run discover --write, discover --promote, or regen --write on branch main.
2. Do not edit governance files when git status shows unrelated human changes you did not confirm.
3. Do not pipe full discover --json into context — use references/discovery-json-slices.md.
4. Do not use discover --write on brownfield when discover --staged + --promote is available.
5. Do not call material work "done" without runbook + registry (when needed) + CHANGELOG + passing check.

Discover — pick the right flag

Brownfield: references/brownfield-flow.md. Commands: references/commands.md.

Bootstrap and migration

openclaw-gov init --root "$GOV_ROOT"
openclaw-gov adopt --from /path/to/existing-governance --root "$GOV_ROOT"
openclaw-gov inject-agents --write
openclaw-gov inject-agents --write --prune

Migrating guide: docs/migrating-existing-governance.md

Error rescue

CI gate (governance repos)

openclaw-gov regen --check && openclaw-gov check
openclaw-gov discover --staged --root "$GOV_ROOT"
git diff --exit-code workflows/registry.yaml

Install CLI (operators)

Note: Frontmatter metadata.openclaw.install (kind uv) is for ClawHub/agent auto-install. Humans on Ubuntu should prefer pipx; macOS/containers use pip — same git pin @v0.5.5, not competing products.

Ubuntu (pipx recommended):

pipx install "openclaw-governance @ git+https://github.com/pawlsclick/[email protected]"

Mac / venv:

pip install "openclaw-governance @ git+https://github.com/pawlsclick/[email protected]"