Project Guard

Project Guard is a local-first governance layer for AI coding agents.

Its goal is to help a Coding Agent satisfy the user's actual requirement with the Smallest Safe Change: a change that is local, controlled, safe for future maintenance, and appropriate to the request. Project Guard helps find or prevent scope expansion, duplicate implementation, unnecessary architecture or dependencies, requirement drift, and risky repository changes.

Project Guard is not an AI architect, a semantic-correctness verifier, or a security sandbox. It does not prove that code is correct, complete, or free of security issues.

v0.6.0 is the current release candidate. v0.5.0 is published on PyPI; several platform integrations remain Experimental because their behavior depends on the platform's Hook or Plugin runtime.

Installation

Requires Python 3.12 or newer.

Install the published package:

pip install project-guard

Verify the installation:

project-guard --version
project-guard --help

The version command should report:

0.6.0

Project Guard does not install or authenticate Claude Code, Codex, Cline, TRAE, or GitHub Copilot. Install and authenticate those platform tools separately according to their own documentation.

Quick Start

From a Git repository that you want to govern:

cd your-project
project-guard inspect .
project-guard context .
project-guard prepare . "Add a --limit option to this CLI"

prepare does not modify production code. It records repository facts, engineering boundaries, and a Coding Agent handoff in these Guard-owned files:

.project-guard-plan.json
.project-guard-contract.json
.project-guard-instructions.md
.project-guard-skill.md
.project-guard-agent-prompt.md

The .project-guard-task-contract.json file is different: it is created and maintained by the Coding Agent during the governed task.

How It Works

User request
    -> Project Guard prepare
    -> Engineering Contract and Coding Skill
    -> Coding Agent
    -> Agent-owned Task Contract
    -> implementation and focused tests
    -> Git Diff
    -> Project Guard Review

The user defines the requirement. Project Guard provides repository facts, boundaries, and structured artifacts. The Coding Agent performs the semantic interpretation and implementation. Review independently audits the resulting diff.

Language-aware Repository Intelligence

Project Guard keeps Python's AST-based indexing and adds lightweight structural indexing for:

• Python - AST-based symbols and imports
• Java - classes, interfaces, methods, imports, and inheritance signals
• JavaScript / TypeScript - classes, functions, imports, exports, and type/interface signals
• Go - named types, functions, methods, imports, and CLI entry hints
• Rust - structs, enums, traits, functions, use relationships, and entry hints
• HTML - script, stylesheet, form, id, and class references
• Other text files - filename and text-search fallback

This is lightweight heuristic repository intelligence, not full compiler semantic analysis. It does not provide type resolution, a call graph, or complete understanding of every language construct. Malformed or complex source may therefore produce only text-level evidence.

Core Commands

Run project-guard <command> --help for the exact options supported by the installed version.

project-guard inspect PATH
    Print a repository health overview.

project-guard context PATH
    Generate compact Markdown context for a Coding Agent.

project-guard plan PATH REQUEST
    Check a request's structure, scope, and repository signals before coding.

project-guard prepare PATH REQUEST
    Generate the five Guard artifacts and an Agent handoff.

project-guard run PATH REQUEST
    Run a governed local Claude Code task and review the result.

project-guard review PATH
    Independently audit the current Git Diff against Guard and Task Contracts.

project-guard score PATH
    Print an AI coding readiness score.

The most explicit manual review command is:

project-guard review .

Before using review options, confirm the installed syntax with:

project-guard review --help

Guard Artifacts

The five files generated by prepare represent the Guard's view of the request:

• .project-guard-plan.json - plan and candidate-scope signals
• .project-guard-contract.json - the Engineering Contract
• .project-guard-instructions.md - task-specific governance instructions
• .project-guard-skill.md - the fixed Coding Skill
• .project-guard-agent-prompt.md - the Agent handoff

The Agent-owned .project-guard-task-contract.json records explicit requirements, inferences, assumptions, planned production files, and scope amendments. prepare does not create it.

Platform Integrations

Most integrations use a one-time project-level command:

project-guard init-<platform> .

The generated configuration stays in the target repository. Project Guard does not require its own remote governance service or daemon. Platform trust, authentication, and enablement remain platform-specific.

Support Matrix

Platform	Initialization	Status
Claude Code	project-guard init-claude .	Verified - real coding E2E
Codex CLI	project-guard init-codex .	Experimental - real coding E2E verified
Codex Desktop	project-guard init-codex .	Experimental - real coding E2E verified
Cline CLI Plugin	project-guard init-cline-plugin .	Experimental - real coding E2E verified
TRAE IDE	project-guard init-trae .	Experimental - real coding E2E verified
GitHub Copilot CLI	project-guard init-copilot .	Experimental - real coding E2E verified
GitHub Copilot IDE	project-guard init-copilot .	Experimental - limited integration
Cline file Hook	project-guard init-cline .	Legacy experimental

Windsurf and Cursor were investigated but are not integrated platforms in this release.

The example used in the platform E2E records is:

Add a --limit option that controls how many items are displayed.
Keep the change minimal and add a focused test if appropriate.

After initialization, users continue to enter a normal natural-language request in the platform. The following sections describe the platform specific steps and limits.

Claude Code

Initialize the repository once:

cd your-project
project-guard init-claude .
claude

Then use Claude Code normally. The project-level flow is:

UserPromptSubmit
    -> Project Guard prepare
    -> governance context
    -> Claude Code
    -> Task Contract
    -> coding and Review

All prompts in an opted-in repository currently trigger preparation, including ordinary questions. There is no coding-intent classifier. A real coding E2E has been verified. The explicit project-guard run workflow remains available as a fallback; because Claude Code remains interactive, it may require /exit before the final Review resumes.

Codex CLI

Initialize and start Codex:

project-guard init-codex .
codex

The first use may show:

Hooks need review

Inspect the project Hook and explicitly trust it through Codex's own security flow. Do not bypass the prompt.

The verified path is:

UserPromptSubmit
    -> Project Guard prepare
    -> Hook context
    -> Codex reads Guard artifacts
    -> Task Contract
    -> coding

Codex CLI real coding E2E has been verified, but the integration remains Experimental because Hook trust and compatibility can vary by environment and version.

Codex Desktop

Use the same project initialization:

project-guard init-codex .

Then open the repository in Codex Desktop, create a new Agent task, and enter the request normally.

The tested Desktop flow generated Guard artifacts, exposed the governance context, and completed a real coding task. An earlier experiment did not observe the project Hook; a later task in the same repository did. This does not prove that CLI trust is required for Desktop or that trust is shared between CLI and Desktop.

Cline CLI Plugin

The recommended Cline CLI integration is the project-local Plugin:

project-guard init-cline-plugin .
cline

This installs:

.cline/plugins/project-guard.js

The Plugin uses Cline's beforeModel runtime to run prepare and add a short governance message to the current model request. A real Cline CLI coding E2E has been verified.

The Plugin currently has no beforeTool, shell, or MCP enforcement and no automatic TaskComplete Review. Task Contract creation remains Agent/model-guided.

Detailed evidence: docs/cline-plugin-e2e.md.

Legacy Cline file Hook

The older file Hook remains available for compatibility and historical tests:

project-guard init-cline .

It installs .cline/hooks/ files. Automatic discovery was not reliably observed in the tested Cline CLI environment, so it is not recommended for new setups.

TRAE IDE

Initialize the repository:

project-guard init-trae .

This creates:

.trae/hooks.json

In the tested Windows TRAE environment, the configuration was recognized but was not enabled automatically. After initialization, open:

TRAE -> Settings -> Hooks -> Project

Enable the configured project Hooks manually. Only then should you use the TRAE Agent normally.

The verified path is:

UserPromptSubmit
    -> Project Guard prepare
    -> governance context
    -> TRAE Agent

Read-only and coding E2E were verified in the tested Windows TRAE environment.

Detailed evidence: docs/trae-e2e.md.

GitHub Copilot CLI

Install and authenticate GitHub Copilot CLI separately. Project Guard does not install Copilot, log in to GitHub, manage tokens, or manage a subscription.

Initialize the repository:

project-guard init-copilot .
copilot

This installs:

.github/hooks/project-guard.json

The current transparent path is:

userPromptTransformed
    -> Project Guard prepare
    -> modifiedTransformedPrompt
    -> Copilot CLI Agent

Read-only and coding E2E were verified for GitHub Copilot CLI on Windows. However, in the coding E2E the Agent recognized the Task Contract requirement but created .project-guard-task-contract.json after the production edits. Task Contract ordering therefore remains model-guided, not enforced.

Detailed evidence: docs/copilot-cli-e2e.md.

GitHub Copilot IDE

The repository initialization command is the same:

project-guard init-copilot .

The IDE remains Experimental - limited integration. The Copilot CLI transparent E2E result must not be extrapolated to the IDE. A full transparent governance loop has not been verified there.

Manual Governance Workflow

For a platform without a verified transparent integration, or when you want an explicit handoff, use:

User request
    -> project-guard prepare
    -> Coding Agent reads .project-guard-agent-prompt.md
    -> Agent Task Contract
    -> coding and focused tests
    -> Git Diff
    -> project-guard review

Example:

project-guard prepare . "Add CSV export support"

Provide .project-guard-agent-prompt.md and the generated governance files to the Coding Agent. When coding is complete, run:

project-guard review .

Use project-guard review --help before adding optional Contract, Plan, Instructions, Skill, or Task Contract paths.

Scope Amendments

If the Agent discovers that a necessary production file is outside the approved scope, it should not silently expand the scope. The intended flow is:

Scope Amendment
    -> reason
    -> user approval
    -> Task Contract update
    -> continue

possible scope means a file may be used if necessary; it does not mean the Agent should modify it automatically. Review checks approved amendments and the actual Git Diff.

Review

Project Guard Review is an independent governance audit based on:

Engineering Contract
    + Agent Task Contract
    + approved Scope Amendments
    + actual Git Diff

Depending on the current findings, output can include PASS, WARNING, or VIOLATION, together with risk levels such as LOW, MEDIUM, or HIGH. Review does not prove code correctness, test completeness, absence of bugs, or absence of security vulnerabilities.

Known Limitations

• Project Guard does not prove semantic correctness.
• Task Contract creation and adherence remain Agent/model-guided.
• Task Contract ordering can differ by platform.
• There is no universal preToolUse or beforeTool enforcement.
• There is no shell enforcement or MCP enforcement.
• There is no automatic universal Review lifecycle.
• Hook trust and enablement differ by platform.
• Copilot IDE remains a limited integration.
• Cline file Hook is a legacy experiment.
• Platform updates may change Hook or Plugin behavior.
• Project Guard does not provide a remote governance service, but the Agent platform may have its own data handling and privacy behavior.

E2E Verification Records

Detailed records are kept separately:

• Codex E2E
• Cline CLI Plugin E2E
• TRAE IDE E2E
• GitHub Copilot CLI E2E

Development Installation

Regular users do not need to clone Project Guard or use an editable install. Use the development installation when developing Project Guard itself, modifying its source, or running its test suite:

git clone https://github.com/wangboning757-creator/project-guard.git
cd project-guard
pip install -e ".[dev]"
python -m pytest
python -m ruff check .

Release and Distribution

Project Guard v0.6.0 is the next release candidate. v0.5.0 is published as project-guard on PyPI. The release uses the local-first CLI and does not add a remote Project Guard server.

Publishing workflow details are documented in docs/publishing.md. Future changes should preserve the published package's version immutability and use a new release version for package-content changes.