# AI Agent Governance

# AI Agent Governance

<details>
<summary>Relevant source files</summary>

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

- [.devin/config.local.json](.devin/config.local.json)
- [.devin/rules/always-check-rules-first.md](.devin/rules/always-check-rules-first.md)

</details>



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**
```mermaid
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)](#4.1).

### 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](#4.2).

### 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](#4.3).

**Sources:** [ .devin/config.local.json:1-12 ](), [ .devin/rules/always-check-rules-first.md:4-26 ]()

---