Copy page

Microservices

AI Agent Governance

AI Agent Governance

Relevant source files

The following files were used as context for generating this wiki page:

• .devin/config.local.json
• .devin/rules/always-check-rules-first.md

The Primebrick v3 Microservices repository implements a rigorous governance framework for AI agents (such as Devin) to ensure architectural consistency, safety, and adherence to project-specific workflows. This framework is centralized in the .devin/ directory and consists of mandatory rule-checking protocols, specialized skills, and execution sandboxing.

The core philosophy of this governance is "Rules-First": agents are prohibited from performing any action—including planning or file operations—without first validating the operation against the governance files .devin/rules/always-check-rules-first.md:4-17 .

Governance Architecture

The governance system bridges natural language instructions with technical execution through three primary domains:

1. Workflow Control: Manages the "Tic-Toc" planning cycle and ensures that agents do not deviate from the established analysis-before-action methodology.
2. Operational Guardrails: Defines the technical limits of agent interaction, including file system access and error recovery limits.
3. Skill & Tool Whitelisting: Controls which terminal commands and specialized procedures an agent is permitted to execute.

System Mapping: Governance to Code

The following diagram illustrates how the governance framework (Natural Language Space) controls the execution environment (Code Entity Space).

AI Agent Execution Flow

Code
graph TD
    subgraph "Natural Language Space (Rules)"
        R1[".devin/rules/always-check-rules-first.md"]
        R2[".devin/rules/tic-toc-planning.md"]
        R3[".devin/rules/code-guardrails.md"]
    end

    subgraph "Code Entity Space (Execution)"
        E1["Exec(pnpm)"]
        E2["Exec(git)"]
        E3["ai-plans/"]
        E4["src/db/migrations/"]
    end

    R1 -->|Mandatory Trigger| R2
    R1 -->|Mandatory Trigger| R3
    R2 -->|Generates| E3
    R3 -->|Controls| E4
    R3 -->|Validates| E1
    R3 -->|Validates| E2

Sources: .devin/rules/always-check-rules-first.md:1-17 , .devin/config.local.json:1-12

---

Workflow & Planning Rules (Tic-Toc)

The "Tic-Toc" cycle is the mandatory planning protocol. Agents must never jump directly into code modification. Instead, they follow a two-step "Analysis" and "Execution" phase.

• Analysis Phase: The agent identifies the scope and generates a structured plan in the ai-plans/ directory.
• PROCEED Gate: The agent must pause for human or rule-based validation before moving to the "Toc" (execution) phase.
• Data Fidelity: This domain enforces strict naming conventions (e.g., snake_case for database entities) and a zero-rename policy to maintain schema integrity.

For details, see Workflow & Planning Rules (Tic-Toc).

Code Guardrails & File Operation Rules

To prevent cascading errors and "hallucination loops," the governance framework imposes strict operational limits.

• Self-Correction Limits: Agents are restricted to a maximum of 2 self-correction retries for any failing command. If it fails a third time, the task enters a BLOCKED state .devin/rules/always-check-rules-first.md:25-26 .
• Atomic Operations: All file changes must be atomic and committed with clear, descriptive messages following the GitFlow standard.
• Scope Locking: Agents are forbidden from modifying files outside the identified task scope to prevent "feature creep" or accidental breaking of unrelated microservices.

For details, see Code Guardrails & File Operation Rules.

Agent Skills & Execution Permissions

The repository utilizes a specialized skills framework and a strict command whitelist to ensure the agent's environment is secure and predictable.

Permission Type	Allowed Commands	Purpose
Package Management	pnpm, npm list, npx	Dependency resolution and script execution .devin/config.local.json:4-8
Environment	powershell, cd	Navigation and Windows-compatible execution .devin/config.local.json:6-7
Version Control	git	Atomic commits and branch management .devin/config.local.json:9-9

The feature skill is the primary execution unit, guiding the agent through a standard implement → test → fix → summarize lifecycle.

For details, see Agent Skills & Execution Permissions.

Sources: .devin/config.local.json:1-12 , .devin/rules/always-check-rules-first.md:4-26

---