Lightweight AI Agent Protocol Enforcement Engine
Make your AI coding assistant follow the rules — mechanically, not politely.
Python 3.9+ License: MIT Tests: 63 Zero Runtime Deps
AI coding assistants have a structural problem: they can be told to follow rules, but nothing stops them from skipping steps. "Always run QA before marking done" is aspirational — until enforcement is mechanical.
ProtocolForge makes protocol enforcement a gate, not a suggestion.
When the rules aren't met, the engine blocks completion. The AI can't argue with a state machine.
| Feature | Description |
|---|---|
| 🔒 Mechanical Enforcement | Hook-based gates that AI cannot bypass |
| 🤖 Agent Routing | Intelligent task-to-agent matching via tags, domains, and roles |
| 📝 Structured Memory | Correlation IDs, validation, and secret scanning |
| 🔐 Supply Chain Integrity | SHA256 manifest verification for all files |
| 📊 Multi-format Reports | Markdown, HTML, and JSON report generation |
| 🌐 Cross-platform | Windows, macOS, and Linux support |
| 📦 Zero Dependencies | Pure Python stdlib (PyYAML optional) |
# Install pip install protocolforge # Initialize in a project protocolforge init . # Execute a protocol protocolforge execute protocols/code-review.yaml # List available agents protocolforge agents list # Route a task protocolforge route "Fix authentication security issue" --tags auth,security # Validate a protocol protocolforge validate protocols/deployment.yaml
┌──────────────────────┐
│ ProtocolForge │
│ │
│ Protocol Engine │ ← YAML/JSON definitions
│ + Hook System │ ← Mechanical gates
└──────────┬───────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Agent │ │ Memory │ │ Integrity │
│ Registry │ │ Manager │ │ Verifier │
│ + Router │ │ + Scanner │ │ (SHA256) │
└──────────────┘ └──────────────┘ └──────────────┘
Define protocols in YAML:
name: code-review version: "1.0.0" description: "Standard code review protocol" triggers: [file_edit, code_change] on_violation: block steps: - name: syntax_check description: "Verify code syntax" step_type: validation required: true - name: qa_review description: "Run QA verification" step_type: gate required: true dependencies: [syntax_check] on_failure: block - name: security_scan description: "Security vulnerability scan" step_type: review required: true dependencies: [syntax_check] - name: final_approval description: "Final approval gate" step_type: gate required: true dependencies: [qa_review, security_scan] on_failure: block
Five hook phases enforce the protocol:
| Phase | What It Does |
|---|---|
sessionStart |
Bootstrap session, inject memory |
beforeFileEdit |
Pre-edit validation |
afterFileEdit |
Track file modifications |
subagentStart |
Track agent invocations |
subagentStop |
Record review completion |
stop |
The gate — blocks if requirements not met |
Agents are domain specialists with structured metadata:
from protocolforge.agents import AgentRegistry, AgentRouter # Create registry with default agents registry = AgentRegistry.create_default_registry() # Route a task router = AgentRouter(registry) result = router.route(RoutingContext( task_description="Fix the authentication bug", tags=["auth", "security"], domains=["backend"], )) print([a.slug for a in result.selected_agents])
Structured memory with secret scanning:
from protocolforge.memory import MemoryManager mgr = MemoryManager() entry = mgr.append( file="session-handoff", kind="state", status="done", summary="Implemented OAuth2 flow", tags=["auth", "backend"], ) # ⚠️ Raises ValueError if secrets are detected!
SHA256 manifest verification:
from protocolforge.integrity import SupplyChainVerifier verifier = SupplyChainVerifier() verifier.build_manifest(project_root) verifier.save_manifest() # Verify later report = verifier.verify(project_root) print(f"Clean: {report.is_clean}, Tampered: {report.tampered}")
# Run all 63 tests python -m pytest tests/ -v # With coverage python -m pytest tests/ --cov=protocolforge --cov-report=html
- Python 3.9+
- PyYAML (optional, for YAML protocol definitions)
- No other runtime dependencies
MIT License — see LICENSE for details.
轻量级 AI Agent 协议执行引擎 —— 让你的 AI 编码助手必须遵守规则,而非仅靠提示词。
- 🔒 机械式协议执行 — Hook 门控机制,AI 无法跳过必经步骤
- 🤖 智能 Agent 路由 — 基于标签、领域、角色的精准匹配
- 📝 结构化记忆系统 — 关联 ID 防伪造,30+ 种密钥泄漏检测
- 🔐 供应链完整性 — SHA256 清单校验,防篡改
- 📊 多格式报告 — Markdown / HTML / JSON 一键导出
- 📦 零运行依赖 — 纯 Python 标准库
pip install protocolforge
protocolforge init .
protocolforge execute protocols/code-review.yaml- 用 YAML 定义协议流程和门控检查点
- Hook 系统在关键阶段拦截 AI 操作
- 门控未通过 → 阻断执行,返回 followup_message
- 所有步骤完成 → 放行
輕量級 AI Agent 協議執行引擎 —— 讓你的 AI 編碼助手必須遵守規則,而非僅靠提示詞。
- 🔒 機械式協議執行 — Hook 閘門機制,AI 無法跳過必經步驟
- 🤖 智慧 Agent 路由 — 基於標籤、領域、角色的精準匹配
- 📝 結構化記憶系統 — 關聯 ID 防偽造,30+ 種密鑰洩漏偵測
- 🔐 供應鏈完整性 — SHA256 清單校驗,防竄改
- 📊 多格式報告 — Markdown / HTML / JSON 一鍵匯出
- 📦 零運行依賴 — 純 Python 標準庫
pip install protocolforge
protocolforge init .
protocolforge execute protocols/code-review.yaml- 以 YAML 定義協議流程與閘門檢查點
- Hook 系統在關鍵階段攔截 AI 操作
- 閘門未通過 → 阻斷執行,返回 followup_message
- 所有步驟完成 → 放行