Agent Guidelines & Governance
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Guidelines & Governance framework establishes a strict, immutable set of rules for AI agents operating within the mt5linux project. This system ensures high-integrity engineering through universal authority, research-first mutation, and technical truth backed by observable evidence. It defines a tiered governance structure where project-specific laws complement the universal core, ensuring that all agents—including the standing documenter and orchestrator—adhere to the same validation and execution standards.
The governance model integrates with the project's technical architecture, specifically enforcing strict protocol compliance and typed boundaries. By mandating the use of specific toolsets (e.g., beads for task tracking and make for validation), the framework prevents architectural drift and ensures continuous project health.
Core Engineering Principles
The "Universal Agent Engineering Core" serves as the primary authority for all agent actions. These principles prioritize truth, evidence-based claims, and the preservation of shared work.
The Tenets of Governance
- Truth with Evidence: Every claim made by an agent must include the exact command, exit status, and decisive output.
- Research Before Mutation: Agents are required to read the current authority and implementation owner before modifying any code.
- Root Cause Focus: Governance forbids the use of shims, stubs, or "old-and-new" coexistence. Agents must fix the canonical owner and complete a full cutover.
- Typed Boundaries: Untrusted inputs must be parsed into canonical types once.
- Continuous Green: No task is considered complete if the project or environment is partially migrated or broken.
Sources: AGENTS.md:7-38, CLAUDE.md:3-8
Workflow and State Management
The project uses the beads (bd) system for execution truth and task tracking. This system manages work plans, memory, status, and evidence.
The diagram above illustrates the mandatory workflow for agents to transition from task initiation to validated closure.
Sources: AGENTS.md:39-44, CLAUDE.md:12-14
Agent Roles and Responsibilities
Governance defines a strict separation of roles to ensure objective validation and implementation quality.
| Role | Primary Responsibility | Key Restrictions |
|---|---|---|
| Orchestrator | Coordinates work, owns semantic Beads state, validates, and approves merges. | Does not implement code directly. |
| Worker | Implements a single Bead in a dedicated branch/worktree. | Never merges or closes tasks. |
| Standing Documenter | Audits, updates, and removes stale ADRs, docs, and docstrings. | Must follow the same validated PR flow as Workers. |
| Governance Helper | Ensures CI/CD alignment and assists in rule enforcement. | Active during PR validation phases. |
Sources: AGENTS.md:45-56
Protocol and Validation Compliance
Agents must adhere to the project's technical boundaries, particularly regarding gRPC service definitions and Pydantic data models.
Strict Protocol Enforcement
The project mandates exact matching of method signatures between protocols and implementations. This is validated through strict inspection of parameter names, kinds, and defaults.
The diagram shows the relationship between defined protocols and their concrete implementations, which agents must maintain without deviation.
Sources: tests/integration/test_protocol_compliance.py:27-111
Validation Requirements
Agents must run native global and changed-scope gates. For Python development, this includes a specific suite of tools:
- Linters/Formatters: Ruff
- Type Checkers: Pyright, Mypy, Pyrefly
- Testing: Pytest with coverage analysis
- Performance: cProfile for hot-path optimization before modification
Sources: AGENTS.md:31-38, AGENTS.md:66-70
Data Governance and Constants
The project enforces a strict separation between shared business constants and test-specific data. Agents must not violate these boundaries.
Constants Separation Rules
- Shared Constants (
c.*): Defined inmt5linux/constants.py. Used for data shared with the MT5 source code (e.g.,OrderType.BUY). - Test-Only Constants (
tc.*): Defined intests/constants.py. Used exclusively in tests (e.g.,SAMPLE_REQUEST_ID).
# Governance Rule: NEVER MIX CONSTANTS
# Correct: Shared MT5 constant
assert mt5.ORDER_TYPE_BUY == c.Order.OrderType.BUY
# Correct: Test-only constant
assert request.price == tc.TEST_PRICE_BASE
Sources: mt5linux/constants.py:539-588
Pydantic Model Governance
All trading data structures are governed by Pydantic 2 models under the MT5Models container. These models provide:
- Immutability: Models are defined with
frozen=True. - Factory Methods: A universal
from_mt5()method for parsing namedtuples and dicts into typed objects. - Validation Logic: Field constraints (e.g., volume between 0 and 1000) are enforced at the model level.
Sources: mt5linux/models.py:34-97
Conclusion
Agent Guidelines & Governance in the mt5linux project provide an inviolable framework for technical execution. By centralizing authority in AGENTS.md, enforcing strict role separation, and mandating technical truth through evidence and validation, the project ensures that both human and AI agents maintain a high-quality, stable codebase. Stale documentation or bypassed validation gates are treated as defects, ensuring that the living knowledge of the project matches its implementation reality.