Metadata-Version: 2.5
Name: project-charter
Version: 0.1.0
Summary: AI Agent Governance Engine — Generate, validate, and enforce coding conventions
Project-URL: Homepage, https://github.com/saadat-dev/project-charter
Project-URL: Documentation, https://project-charter.dev
Project-URL: Repository, https://github.com/saadat-dev/project-charter
Author: Project Charter Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,cursor,governance,llm,mcp,state-machine,workflow
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: all
Requires-Dist: anthropic>=0.30.0; extra == 'all'
Requires-Dist: click>=8.1; extra == 'all'
Requires-Dist: google-genai>=0.1.0; extra == 'all'
Requires-Dist: mcp[cli]>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.30.0; extra == 'all-providers'
Requires-Dist: google-genai>=0.1.0; extra == 'all-providers'
Requires-Dist: openai>=1.0.0; extra == 'all-providers'
Provides-Extra: claude
Requires-Dist: anthropic>=0.30.0; extra == 'claude'
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Requires-Dist: rich>=13.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.1.0; extra == 'gemini'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# 🚀 Project Charter

**A Secure, Stateful Workflow Engine for Autonomous AI Agents**

[![PyPI](https://img.shields.io/pypi/v/project-charter)](https://pypi.org/project/project-charter/)
[![CI](https://img.shields.io/github/actions/workflow/status/nextbridgehq/project-charter/ci.yml?branch=main)](https://github.com/nextbridgehq/project-charter/actions)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[GitHub](https://github.com/nextbridgehq/project-charter) · [Issues](https://github.com/nextbridgehq/project-charter/issues) · [Releases](https://github.com/nextbridgehq/project-charter/releases) · [Changelog](CHANGELOG.md)


## Overview

The **Project Charter** turns unpredictable LLM prompts into a strictly enforced, resumable state machine. By utilizing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), 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](#installation)
  - [Core CLI](#core-cli)
  - [MCP Server](#mcp-server)
- [CLI Usage](#cli-usage)
  - [Initialization](#initialization)
  - [Enforcing Rules](#enforcing-rules)
  - [AI Orchestration](#ai-orchestration)
  - [Auditing](#auditing)
- [Configuration](#configuration)
- [Architecture / How it works](#architecture--how-it-works)
- [Features](#features)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#license)

## Installation

### Core CLI

The standard CLI tools can be executed directly via `uvx`:

```bash
uvx --from project-charter charter
```

### MCP Server

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

```bash
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`:
```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:

```bash
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:
```markdown
# 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:
```bash
charter enforce
```

To integrate with CI systems (like GitHub Actions) and get inline annotations:
```bash
charter enforce --format=ci --strict
```

### AI Orchestration

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

```bash
# 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:
```bash
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](ARCHITECTURE.md))*

## 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](CONTRIBUTING.md) to learn how to write new skills, update manifests, and run the test suite.

## Changelog

Release history is available in the [Changelog](CHANGELOG.md).

## License

[MIT](LICENSE) © [Nextbridge](https://www.nextbridge.com)

Built and maintained by **[Nextbridge](https://www.nextbridge.com)** — 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`
