🚀 Project Charter

A Secure, Stateful Workflow Engine for Autonomous AI Agents

GitHub · Issues · Releases · Changelog

Overview

The Project Charter turns unpredictable LLM prompts into a strictly enforced, resumable state machine. By utilizing the Model Context Protocol (MCP), it allows agents like Claude Code, Cursor, Gemini, and Codex to navigate complex codebase discovery, rule extraction, and governance tasks without breaking your repository.

It actively prevents AI agents from violating architectural guidelines, rewriting bounded modules, or ignoring continuous integration policies by statically enforcing rules extracted from your project's CONVENTIONS.md at runtime.

Table of Contents

• Installation
  • Core CLI
  • MCP Server
• CLI Usage
  • Initialization
  • Enforcing Rules
  • AI Orchestration
  • Auditing
• Configuration
• Architecture / How it works
• Features
• Contributing
• Changelog
• License

Installation

Core CLI

The standard CLI tools can be executed directly via uvx:

uvx --from project-charter charter

MCP Server

To use the MCP server with Claude Code, Cursor, or other MCP clients, use the [mcp] extra:

uvx --from "project-charter[mcp]" charter-mcp

Cursor Configuration

Add the following to your Cursor MCP settings:

• Type: command
• Name: project-charter
• Command: uvx --from "project-charter[mcp]" charter-mcp

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "project-charter": {
      "command": "uvx",
      "args": [
        "--from",
        "project-charter[mcp]",
        "charter-mcp"
      ]
    }
  }
}

CLI Usage

Once installed, the charter command is available everywhere.

Initialization

Set up Project Charter in your repository:

cd my-project
charter init

This scaffolds a .charter state folder and a charter.toml configuration file.

Enforcing Rules

Project Charter can parse your CONVENTIONS.md (or AGENTS.md) file, mathematically extract the constraints, and run deterministic checks.

For example, if your CONVENTIONS.md contains:

# Architectural Boundaries
- The `src/core/` directory is **read-only**.
- UI components must never import from `src/database/`.

# Git Policy
- **Never** run `git push`. Always open a PR.

You can enforce these conventions across your project:

charter enforce

To integrate with CI systems (like GitHub Actions) and get inline annotations:

charter enforce --format=ci --strict

AI Orchestration

To run a skill workflow utilizing your AI agent and verify it against project boundaries:

# Run the workflow
charter run

# Approve a human-gated phase
charter approve

# View current workflow status and compliance
charter status

Auditing

To see exactly what capabilities an AI agent used during a session and what boundaries it attempted to cross:

charter audit

Configuration

Project Charter is configured via a charter.toml file at the root of your project, generated automatically during charter init.

Option	Default	Description
provider	None	The LLM provider to use (e.g., claude, gemini, codex). Can be overridden via --provider flag.

Architecture / How it works

The Project Charter is designed to orchestrate LLM agents securely and reliably by separating prompt text from execution logic. Instead of giving an AI a massive wall of text and hoping it behaves, this suite models complex coding workflows as a strict State Machine governed by Machine-Readable Contracts (IR).

• Skill IR (manifest.yaml): Acts as a technical contract defining explicit read/write globs, expected artifacts, and human review gates.
• Workflow State: State is saved natively into the target repository inside a .charter/<run_id>.json file. It tracks the status of every phase (PENDING, IN_PROGRESS, AWAITING_APPROVAL, COMPLETED), enabling instant resumability.
• Skill Engine: The active orchestrator that evaluates pre-conditions, enforces permissions defined in the IR, and yields control to an agent only for the specific phase that is in progress.

(For a more detailed breakdown, including the execution context and sequence flows, see Architecture Overview)

Features

• Runtime Enforcement: Intercepts tool calls dynamically before they execute to prevent unauthorized modifications to your repository.
• Strict State Machine: Workflows are forced through a deterministic pipeline. The engine prevents agents from skipping steps.
• Resumable Execution: State is persisted automatically at every phase transition. If a task crashes or pauses for human review, the agent resumes right where it left off.
• Human Approval Gates: Critical phases yield to an AWAITING_APPROVAL state, pausing the AI until a human manually approves.
• Glob-Based Permission Enforcer: Validates every AI file read/write against explicit manifest.yaml contracts before execution.
• Multi-Provider Adapters: Built-in support for Claude (Anthropic), Codex (OpenAI), and Gemini (Google) via swappable provider adapters.

Contributing

Please see our Contributing Guidelines to learn how to write new skills, update manifests, and run the test suite.

Changelog

Release history is available in the Changelog.

License

MIT © Nextbridge

Built and maintained by Nextbridge — If Project Charter helped your AI agent navigate your codebase while respecting its rules and conventions, a ⭐ would mean a lot — it helps other developers discover the plugin and build with AI more safely.

---

Keywords: ai, agents, mcp, governance, llm, claude, cursor, workflow, state-machine