Agentic Governance

Portable enterprise skills, MCP context servers, and repo-local overlays for agents that need to keep real software work coherent across sessions.

Agentic Governance is the missing layer between "the agent can code" and "the whole program stays bounded, reviewable, and safe to resume."

It packages two things together:

• a governed delivery workflow: enterprise-* skills for discover, plan, contract, build, review, forge, verify, harness, PR review, and compound learning
• the context machinery those skills need: Cortex source retrieval, skills-index policy retrieval, vault/task evidence lookup, tech-stack detection, and generated repo-local overlays

The point is not to replace GSD, Superpowers, Compound Engineering, or any other execution system. The point is to give execution systems a durable control plane so they stop losing the plot when the work spans branches, agents, PRs, checks, and fresh sessions.

What This Repo Gives You

Install this into a repo and it will:

1. read the target repo's tech stack
2. install the generic enterprise skills into your Codex home
3. install the MCP server source for code, skill, and vault context
4. generate repo-local overlays such as <repo-slug>-enterprise-build
5. write portable repo profile and trap artifacts
6. fail closed when setup, proof, or public-release hygiene is incomplete

That means a new machine or fresh repo does not need hand-written local prompt glue. It can detect the stack, create the right overlays, and give the agent a workflow that knows what proof level the repo needs.

Quick Start

From this repo:

npm run enterprise:install -- --target /path/to/your-repo --codex-home ~/.codex

The installer writes target-repo artifacts:

.codex/enterprise-state/repo-profile.json
.codex/enterprise-state/repo-traps.json
.codex/repo-skills/<repo-slug>-enterprise-*/SKILL.md
.codex/repo-skills/<repo-slug>-enterprise-manifest.json

It installs reusable local assets:

~/.codex/skills/enterprise-*
~/.codex/mcp-servers/cortex-engine
~/.codex/mcp-servers/skills-index
~/.codex/mcp-servers/vault-index

Then validate the portable enterprise kit:

npm run governance:validate
npm run enterprise:validate
npm run enterprise:evals
npm run mcp:test
npm run mcp:audit
npm run public:sanitize
npm test

The New Skills

The extracted enterprise skill family lives in enterprise-skills/:

• enterprise: routes the work and refuses unsafe shortcuts
• enterprise-discover: reads the repo and creates portable profile state
• enterprise-brainstorm: turns vague intent into a technical design
• enterprise-stack-review: locks stack decisions with incumbent bias
• enterprise-plan: creates implementation plans with proof and boundary rules
• enterprise-contract: locks postconditions and build packets
• enterprise-build: executes the mechanical build with bounded paths
• enterprise-review: attacks the implementation against the contract
• enterprise-pr-review: closes PR conversations without hiding real bugs
• enterprise-forge: adversarially tries to break the current diff
• enterprise-verify: reruns fresh proof against current code
• enterprise-harness: final readiness gate
• enterprise-compound: records reusable learning
• enterprise-debug: root-cause debugging for broken lanes

Each stage has an eval contract. The validator checks that the skills are not just prose sitting in a folder:

npm run enterprise:evals

The MCP Servers

The extracted MCP servers live in mcp-servers/:

• cortex-engine: AST and symbol-level code intelligence so agents can locate source truth before reading huge files or guessing
• skills-index: token-aware skill, policy, and bootstrap retrieval so agents load the right guidance instead of every prompt in the house
• vault-index: structured vault/task/evidence lookup and coordination state for long-running work

They are included as source packages with package locks, not vendored node_modules. The repo tests them directly:

npm run mcp:test
npm run mcp:audit

Tech-Stack Detection And Overlays

The installer uses scripts/detect-tech-stack.cjs to infer a target repo's shape from common files:

• package.json and lockfiles
• pyproject.toml, requirements.txt, go.mod, Cargo.toml
• .github/workflows/*
• render.yaml, vercel.json, Dockerfile

Those facts become repo-local overlay hints:

• what runtime, framework, frontend, database, and test stack is already in use
• whether live data proof should be mandatory
• whether headless browser proof should be mandatory
• which repo-local overlays should wrap the generic enterprise-* skills

The generic skills stay publishable. The generated overlays make them local.

Why We Built This

Most coding agents can help with the next action:

• plan a task
• write code
• run tests
• review a diff

Real projects fail in messier places:

• a fresh session resumes from the wrong story
• a branch carries stale proof
• review comments get resolved without being fixed
• a "small" change quietly widens into adjacent ownership
• the agent remembers confidence but not evidence
• the repo has no durable record of what is allowed, blocked, verified, or safe to merge

Agentic Governance treats that as a control problem, not a vibes problem.

The core idea is simple: important work should resume from artifacts, not from transcript momentum. The repo profile, traps, overlays, stage gates, packet boundaries, evidence logs, and PR review state become the thing the agent must obey.

How This Differs From GSD, Superpowers, And Similar Systems

GSD, Superpowers, Compound Engineering, and similar tools are valuable execution systems. They give agents rhythm, discipline, and methods for doing a slice of work well.

Agentic Governance adds the control layer around those slices.

System	Strong at	Where Agentic Governance Adds Control
GSD	Context shape and execution cadence	Durable packet truth, repo overlays, explicit proof gates, cross-session state
Superpowers	Planning, TDD, review, verification discipline	Wave state, owned/forbidden surfaces, typed blockers, artifact-based resume
Compound Engineering	Brainstorm-plan-work-review rhythm	Objective map, bounded continuation, evidence-backed closeout
Ralph-style loops	Iterating hard on one task	Keeps the loop inside one packet so it cannot choose scope by itself

Short version:

• execution systems help the agent work
• Agentic Governance helps the work stay governed

Governance Artifacts

The portable governance core still exists in this repo. It uses:

• objective-map.json
• wave-state.json
• packets/<packet-id>.json
• evidence-log.json
• blockers.json

These artifacts define what is active, what is owned, what is forbidden, what is blocked, what evidence exists, and what can close honestly.

The starter governance skills live in skills/, and examples live in examples/.

Benchmark Proof

This project came out of a multi-session benchmark using the actual Superpowers plugin in two branches:

• Superpowers alone
• Superpowers under Agentic Governance

Both branches got through early waves. Later, the plain branch reset to an earlier commit while newer workflow artifacts still existed. The repo was no longer telling one coherent truth.

The governed branch kept wave state, packet state, contracts, and evidence aligned across fresh sessions.

The narrow claim:

Agentic Governance did not make the executor smarter. It made the work harder to lose.

More detail:

• docs/examples/superpowers-ab-test.md
• docs/proof/founder-style-proof.md
• docs/proof/white-paper-proof.md

Public-Release Hygiene

This repo is intended to be public. The release checks include:

• no local absolute user paths
• no known local project identifiers
• no private-key blocks
• no secret-looking token assignments
• no vendored node_modules
• high-severity npm audit checks for the MCP packages

Run:

npm run public:sanitize
npm run mcp:audit

Repo Guide

• docs/ENTERPRISE_KIT.md: portable enterprise skills, MCP servers, installer, and release checks
• docs/PROTOCOL.md: governance artifact contract and adapter rules
• docs/COMPARISON.md: positioning against GSD, Superpowers, Compound Engineering, and Ralph-style loops
• docs/guides/use-with-superpowers.md: use Agentic Governance with Superpowers
• docs/examples/compound-engineering-walkthrough.md: concrete adapter walkthrough
• enterprise-skills/: extracted enterprise delivery skills
• mcp-servers/: extracted MCP server source packages
• skills/: portable governance and adapter skills
• templates/: starter governance artifact shapes
• scripts/: installers, validators, audit helpers, and renderers
• tests/: repository-level smoke and install tests

Honest Positioning

Good claim:

Agentic Governance packages portable enterprise skills, MCP context servers, tech-stack overlays, and governance artifacts so agent work can stay bounded, resumable, reviewable, and evidence-backed.

Bad claim:

Agentic Governance replaces execution tools or guarantees perfect autonomous delivery.

That would be theater. The actual value is better than theater: the work gets a memory made of artifacts, proof, and boundaries.