agent-governance-core

A universal, indexable agent-governance corpus: a stack-agnostic, runtime-agnostic orchestration kernel plus opt-in packs. Extracted and generalized from a single project's AGENTS.md + .github/skills/ + .github/engram/ corpus so it can be reused across repositories, languages, cloud platforms, and agent harnesses (Claude Code, Gemini CLI, GPT-based agents, local-model harnesses, ...) without dragging along project-specific — or harness-specific — content.

Why this shape

Three independent problems, one manifest:

1. Scale/indexability — a single giant AGENTS.md gets re-read in full every session regardless of what the task needs. core/ splits the orchestration protocol into small, numbered modules; MANIFEST.json is the router an agent reads once to know what exists and where, then fetches only what a task's triggers require — the same lazy-load pattern this environment's own ToolSearch uses for deferred tools.
2. Reuse across stacks/languages — the original corpus hard-coded Terraform/GCP assumptions into otherwise-generic reasoning protocols. stacks/ isolates that: a stack pack is a self-contained bundle of skills + additive rows into core protocols, activated per consuming repo via a local governance-manifest.json — never baked into core/.
3. Reuse across agent runtimes — some core rules (e.g. the Persistence Portability Gate in core/02-memory-bootstrap.md) can be mechanically enforced with a hook, not just stated in prose — but how depends entirely on which agent harness is running the corpus, and most harnesses' capabilities have never been verified here. runtimes/ isolates that the same way stacks/ isolates language-specific content: a runtime pack documents one harness's verified capability and implements the mechanical side, while core/ never assumes any specific harness's hook mechanism exists. See runtimes/CONTRACT.md.

Layout

MANIFEST.json                  # the index/router — read this first
core/
  00-kernel.md .. 07-feedback-protocol.md   # the numbered orchestration protocol (was AGENTS.md §0-§7)
  skills/<name>/SKILL.md       # domain-agnostic skills (system-foresight, sre-audit, gitops-pipeline, ...)
patterns/                      # meta-governance: how to author/evolve rules and skills in this corpus
stacks/<name>/                 # language/infra-specific authoring knowledge
  PACK.md                      # what this pack activates, what core sections it extends
  skills/<name>/SKILL.md       # stack-specific skills (e.g. Terraform/HCL authoring)
runtimes/<name>/                # agent-harness-specific mechanical enforcement (hooks, config)
  CAPABILITY.md                # verified interception capability for this harness, or explicit "none"
  hooks/, *.template            # the actual hook scripts / config snippets, if any
templates/                     # scaffolding a consuming repo copies on init (never read at runtime)
scripts/init-governance.sh     # bootstrap: syncs core + active packs into a consuming repo

Using this in another repo

1. In the consuming repo, copy scripts/consumer-manifest.example.json to governance-manifest.json and list which stacks and runtimes to activate (empty lists are valid — core-only).
2. Run ./scripts/init-governance.sh /path/to/consuming-repo. This syncs core/, patterns/, any declared stack packs, and any declared runtime packs into <repo>/.github/governance/, and — only on first run — scaffolds AGENTS.md and .github/engram/{INDEX.md,agent-behavioral-preferences.md} from templates/. Runtime pack config snippets (e.g. a .hook-snippet.template) are copied as files only — the script never auto-edits your agent runtime's own settings/config file; merge those by hand.
3. Re-run the script any time agent-governance-core updates, or when you add/remove a pack in the manifest. It syncs .github/governance/ idempotently; it never touches an existing AGENTS.md beyond the one-time scaffold, so your repo's "Project-Specific" section and any local architecture constraints are never clobbered.
4. Requires jq (manifest parsing) and rsync.

Adding a new stack pack

A stack pack is warranted when a genuinely new language/platform/domain needs authoring guidance that core's domain-agnostic protocols can't derive from first principles (see patterns/pattern-skill-authoring.md → New Skill Gate before writing one). At minimum:

• stacks/<name>/PACK.md — activation condition, skills registered, which core sections it adds rows/sections to (never forks them)
• stacks/<name>/skills/<skill>/SKILL.md — the actual authoring protocol(s)
• Register the pack in MANIFEST.json under stacks.available

Keep stack-specific content out of core/ — if a core skill needs a tool-specific example, point to the stack pack instead of naming the tool inline (see patterns/pattern-agents-rule-authoring.md → Universal Scope test).

Adding a new runtime pack

Read runtimes/CONTRACT.md in full before writing one — in particular, never fabricate a hook mechanism you have not verified against that harness's actual current documentation or behavior. A runtime pack that honestly documents "no interception capability" is a complete, valid pack — it is not a placeholder waiting to be filled in. Build one only when a real session on that harness needs it (same evidence bar as stack packs), not speculatively.

What did not migrate here

Project-specific decisions, incident postmortems, bugfix records, and architecture constraints (e.g. a specific data pipeline's PII-handling boundary) stay in the originating project's own .github/engram/ — they are facts about that project, not universal rules. Only the meta-governance patterns for how to write and evolve rules (patterns/) are universal and migrated here.