<div align="center">

Pattern 8 (P8)

Zero-Trust Governance Framework to stop AI Agents from hallucinating, breaking things, and bypassing your rules. <br/>

"Your prompt is merely a suggestion. P8 is the law."

🇨🇳 简体中文 · Architecture (源码导读)

</div>

---

Table of Contents

• The Problem
• Quick Start
• Architecture
• Project Structure
• How It Works: Law vs. Police
• The 5 Patterns
• Anatomy of a SKILL
• The 5 Built-in SKILLs
• MCP Enforcement Engine
• Data Flow
• CLI Reference
• IDE Integration
• Pre-commit Hooks
• Creating Custom SKILLs
• Contributing
• License

---

The Chaos vs. The Law

Are you tired of AI coding agents (Claude, Cursor, Devin) ignoring your instructions, deleting the wrong files, or pushing code without tests?

Prompts are not enough. Prompt injection defence is impossible. To truly control an agent, constraints must be enforced at the OS and code level.

❌ Without P8 (The Chaos)

• Agent decides to skip writing tests because it's "too trivial".
• Agent runs rm -rf by mistake during a multi-step refactor.
• Agent outputs a feature without ever writing a design doc.
• Agent ignores your 5,000-word system prompt because its context window is full.

🛡️ With P8 (The Law)

• MCP SecurityGuard intercepts and blocks dangerous commands at the OS level.
• MCP Reviewer forces the agent into a strict retry-loop if output doesn't match the template.yaml.
• Pre-commit Hooks ensure the agent hasn't tampered with the rules themselves.
• Inversion Pattern forces the agent to stop and ask you clarifying questions instead of hallucinating.

---

⚡ Zero to Hero in 30 Seconds

Take absolute control of your codebase with 3 commands:

# 1. Install the enforcer (Python 3.8+)
pip install pattern8

# 2. Add handcuffs to your current project
p8 init

# 3. Done. Your Agents are now under control.
p8 list

💡 For Chinese-language teams: p8 init --lang zh generates all SKILL files with Chinese annotations.

---

🏛️ Architecture Overview

P8 is NOT an AI Agent framework. It does not call LLMs or drive pipelines.
P8 is a governance layer — a set of enforceable rule files + a runtime enforcement engine that constrains how any AI Agent works on your project.

┌─────────────────────────────────────────────────────────────────────────┐
│                            YOUR PROJECT                                │
│                                                                        │
│  ┌──────────────────────────┐    ┌──────────────────────────────────┐  │
│  │    📜 LAW (Editable)      │    │    🚔 POLICE (Read-Only Engine)  │  │
│  │                          │    │                                  │  │
│  │  skills/                 │    │  src/p8/enforcement/             │  │
│  │  ├── prd/                │──→ │  ├── mcp_server.py    (Gateway) │  │
│  │  ├── bug_fix/            │    │  ├── security_guard.py (Block)  │  │
│  │  ├── code_review/        │    │  └── reviewer.py      (Audit)  │  │
│  │  ├── refactor/           │    │                                  │  │
│  │  └── feature_dev/        │    │  Runs as MCP stdio server       │  │
│  │                          │    │  Agent ↔ MCP ↔ Police           │  │
│  │  AGENTS.md               │    └──────────────────────────────────┘  │
│  │  .cursor/rules/*.mdc     │                                          │
│  └──────────────────────────┘    ┌──────────────────────────────────┐  │
│                                  │    🔗 HOOKS (Git-level)          │  │
│                                  │    hooks/pre-commit              │  │
│                                  └──────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Key Insight: The Agent can read SKILL.md, checklist.yaml, and template.yaml (the "law"). But it cannot read guidelines.yaml or security.yaml (the "audit criteria"). This prevents the Agent from gaming the audit.

---

📂 Project Structure

pattern8/
├── src/p8/                          # Python package (pip install pattern8)
│   ├── __init__.py                  #   Package metadata (version)
│   ├── cli.py                       #   CLI entry point (click-based)
│   └── enforcement/                 #   🚔 Enforcement engine
│       ├── __init__.py
│       ├── mcp_server.py            #     MCP protocol gateway (3 Resources + 2 Tools)
│       ├── security_guard.py        #     OS-level command blocker (regex blacklist)
│       └── reviewer.py              #     Static rule audit engine (format + rules)
│
├── skills/                          # 📜 Built-in SKILL rules (English)
│   ├── prd/                         #   Product Requirements Document
│   │   ├── SKILL.md                 #     Pipeline definition (frontmatter + steps)
│   │   ├── assets/
│   │   │   ├── checklist.yaml       #     Inversion: pre-flight questions
│   │   │   └── template.yaml        #     Generator: output format
│   │   └── references/
│   │       ├── guidelines.yaml      #     🔒 Reviewer audit rules (hidden from Agent)
│   │       └── security.yaml        #     🔒 SecurityGuard blacklist (hidden from Agent)
│   ├── bug_fix/                     #   Bug Fix (same structure)
│   ├── code_review/                 #   Code Review (same structure)
│   ├── feature_dev/                 #   Feature Development (same structure)
│   └── refactor/                    #   Refactoring (same structure)
│
├── skills_zh/                       # 📜 Built-in SKILL rules (Chinese)
│   └── (same structure as skills/)
│
├── hooks/
│   └── pre-commit                   # 🔗 Git hook: SKILL integrity + secret scan
│
├── AGENTS.md                        # Global agent behavior instructions
├── .cursor/rules/
│   └── p8-enforcement.mdc          # Cursor IDE injection rules
│
├── tests/
│   ├── test_p8.py                   # CLI + SKILL management tests
│   └── test_enforcement.py          # SecurityGuard + Reviewer + MCP tests
│
├── .github/workflows/
│   └── ci.yml                       # CI: pytest on Python 3.11-3.13 × Ubuntu/macOS
│
├── pyproject.toml                   # Build config (hatchling)
├── CONTRIBUTING.md                  # Contributor guide
├── CHANGELOG.md                     # Version history
└── LICENSE                          # MIT

---

🚔 How It Works: Law vs. Police

P8 separates Law (editable rules) from Police (read-only execution engine):

Developer-editable (Law)              Read-only Engine (Police)
┌──────────────────────┐          ┌──────────────────────────┐
│ SKILL.md             │          │ SecurityGuard            │
│ checklist.yaml       │  read →  │  ↳ regex blacklist       │
│ template.yaml        │          │  ↳ OS command hooks      │
│ guidelines.yaml  🔒  │          │ Reviewer                 │
│ security.yaml    🔒  │          │  ↳ static rule engine    │
│                      │          │  ↳ P8AuditError rollback │
│ "The Constitution"   │          │ "The Police"             │
└──────────────────────┘          └──────────────────────────┘
                ↕ Agent calls via MCP ↕

You write the Law in simple Markdown and YAML. The Police engine enforces them automatically via MCP (Model Context Protocol). Files marked with 🔒 are deliberately hidden from the Agent so it cannot read the security parameters used to audit it.

---

🔐 The 5 Enforcement Patterns

Every SKILL enforces 5 patterns in sequence. These are the backbone of P8's governance philosophy:

| # | Pattern | What It Does | Controlled By | |---|---------|-------------|---------------| | 1 | Pipeline | Tasks execute in a strict ordered sequence. No step may be skipped. | SKILL.md | | 2 | Inversion | Before starting, the Agent must verify all preconditions. If info is missing, it stops and asks — no guessing. | assets/checklist.yaml | | 3 | Generator | Output must follow a strict template. Every section must be filled. No freestyle. | assets/template.yaml | | 4 | Tool Wrapper | Before executing OS commands, the Agent must pass through a security checkpoint. Blacklisted operations are rejected. | references/security.yaml 🔒 | | 5 | Reviewer | After completing output, a static audit engine scores the result. Non-compliant output triggers rollback + retry (up to 3×). | references/guidelines.yaml 🔒 |

Why are patterns 4 and 5 hidden? If the Agent can read the exact audit criteria, it can game the system by producing output that technically passes but is semantically garbage. By hiding them, the audit stays honest.

---

🧬 Anatomy of a SKILL

Each SKILL is a self-contained directory with 4 YAML config files and 1 Markdown pipeline definition:

skills/<skill_name>/
├── SKILL.md                    #