Package Exports

covenant-framework

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (covenant-framework) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Covenant Framework

A governance framework for multi-agent AI systems.

Website · Whitepaper · Glossary · Contributing

The Covenant Framework provides structure, lifecycle management, and quality controls for AI agent orchestration. It solves the coordination problems that emerge when multiple agents work together: who follows what rules, how they communicate, when they stop and reflect, and how the system recovers from failure.

Runs inside Claude Code or OpenAI Codex CLI with no external dependencies.

Install

New project:

git clone https://github.com/asalsali/covenant-framework-community.git my-project
cd my-project && claude

Existing project (Claude Code):

curl -sL https://raw.githubusercontent.com/asalsali/covenant-framework-community/main/install.sh | bash

Existing project (Codex on Windows):

irm https://raw.githubusercontent.com/asalsali/covenant-framework-community/main/install-codex.ps1 | iex

Existing project (Codex on macOS/Linux):

curl -sL https://raw.githubusercontent.com/asalsali/covenant-framework-community/main/install.sh | bash -s -- --runtime codex

Via npm:

npx covenant-framework init

How it works

You talk to the Interpreter -- the single agent that speaks to you. It reads your request, checks system state, proposes a plan with specific agents, and waits for your approval. You say "go" and agents spawn, execute, write exit reports, and shut down. The system remembers what it learned for next time.

You: I want to build a REST API for user management

Interpreter: I'll spawn an Analyst to research your existing codebase,
then a Writer to implement the API. Here's the plan...

You: go

No configuration files to write. No SDK to learn. No dashboard to set up.

What's inside

Component	Description
Constitution	36 sections of immutable rules every agent inherits. The governance layer.
12 Agent types	Interpreter, Analyst, Writer, Synthesist, Guardian, Shepherd, Scribe, Stress Tester, Futility Review, Goal Challenge, James (mediator), Executor
16 Commands	`/spawn`, `/consolidate`, `/checkpoint`, `/audit`, `/remember`, and 11 more
4 Runtime hooks	Agent gate, token logging, shutdown orchestration, session checks
Orientation	Shared state file keeping every agent aligned on current focus and risks
Memory system	Exit reports, structured memos, semantic memory, consolidation cycles

Architecture

         YOU
          |
    [Interpreter]          -- the only agent that talks to you
      /    |    \
 [Analyst] [Writer] [...]  -- spawned agents, scoped mandates

Three roles govern the system:

User -- source of all mandates. Your intent clarifies over time through interaction.
Interpreter -- carries your authority while operating under the same constraints as every other agent.
Orientation -- a shared config file every agent reads to stay aligned.

Agent lifecycle

SPAWN  -->  GENESIS PHASE  -->  EXECUTE  -->  SHUTDOWN
  |              |                 |              |
  |         Read mandate,     Work within     Write exit report,
  |         Constitution,     mandate         archive, notify
  |         prior learnings   boundaries      parent
  |              |                 |              |
  Three gates:   Form world       Communicate    Leave findings
  overlap,       model before     via memos      for next
  scope,         first action     and reports    generation
  memory

Community vs Network

This is the Community Edition -- free and fully functional. The Network Edition adds advanced runtime enforcement for teams and production deployments.

	Community (Free)	Network
Constitution (36 sections)	Full	Full
Agent definitions (all 12)	Yes	Yes
Core commands (16)	Yes	Yes
Advanced commands (+22)	--	Yes
Core hooks (4)	Yes	Yes
Advanced hooks (+7)	--	Yes
Trust & skills registries	--	Yes
Domain system	--	Yes
Input policy enforcement	--	Yes

The tier boundary is at the hook level, not the agent level. Agent definitions are markdown files with zero runtime cost -- they all ship free. Hooks are runtime enforcement -- that is the paid value.

Benchmark results

Terminal-Bench 2.0, 89 tasks: 67.4% (no-retry), vs 42% for an ad-hoc prompted baseline on the same model. Constitution-derived governance beats ad-hoc prompting by 25 percentage points.

Full methodology: Whitepaper (PDF)

Project structure

covenant-framework/
  CLAUDE.md                 # The Constitution (36 sections)
  COMPLIANCE.md             # Project-specific policy layer
  install.sh                # Install into existing projects
  .claude/
    agents/                 # 12 agent definitions
    commands/               # 16 slash commands
    hooks/                  # 4 lifecycle hooks + lib/ modules
    settings.json           # Hook wiring
  registry/                 # Agent registry, orientation, templates
  memory/                   # Exit reports, memos, semantic memory

Extending

Add an agent: Create .claude/agents/<name>.md -- see CONTRIBUTING.md.

Add a command: Create .claude/commands/<name>.md.

Add a hook: Create .claude/hooks/<name>.sh, wire it in settings.json.

Requirements

Claude Code or OpenAI Codex CLI
Python 3.x (for hooks)
bash (native on macOS/Linux, Git Bash on Windows)

Support the project

If the Covenant Framework is useful to you, consider supporting its development:

License

Covenant Public License v1.0 -- see LICENSE.