# AI Agent Rules and Skills

# AI Agent Rules and Skills

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

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

- [.devin/rules/always-check-rules-first.md](.devin/rules/always-check-rules-first.md)
- [.devin/rules/code-guardrails.md](.devin/rules/code-guardrails.md)
- [.devin/rules/dal-conventions.md](.devin/rules/dal-conventions.md)
- [.devin/rules/dal-testing.md](.devin/rules/dal-testing.md)
- [.devin/rules/data-model-conventions.md](.devin/rules/data-model-conventions.md)
- [.devin/rules/file-operations.md](.devin/rules/file-operations.md)
- [.devin/rules/temp-files.md](.devin/rules/temp-files.md)
- [.devin/rules/verify-file-creation.md](.devin/rules/verify-file-creation.md)
- [.devin/skills/dal-usage/SKILL.md](.devin/skills/dal-usage/SKILL.md)
- [.devin/skills/feature/SKILL.md](.devin/skills/feature/SKILL.md)
- [AGENTS.md](AGENTS.md)
- [CLAUDE.md](CLAUDE.md)
- [README.md](README.md)

</details>



This page documents the configuration, guardrails, and specialized skills defined for AI agents (specifically Devin) interacting with the `@primebrick/dal-pg` codebase. These rules ensure architectural consistency, maintain the "leaf dependency" status of the DAL, and enforce the "snake_case everywhere" design principle.

## Devin Agent Configuration

The agent behavior is governed by a set of "always-on" rules located in `.devin/rules/`. These rules take precedence over general LLM patterns and are designed to prevent common errors like truncated filenames or architectural leakage.

### Mandatory Operational Rules
*   **Always Check Rules First**: Before any write operation, file creation, or terminal command, the agent must read the `.devin/rules/` directory and `AGENTS.md` to identify applicable constraints [.devin/rules/always-check-rules-first.md:4-17]().
*   **Never Commit Automatically**: Agents are strictly forbidden from executing `git commit` without explicit human instruction [AGENTS.md:3-9]().
*   **File Creation Verification**: To combat a known streaming bug where filenames are truncated, agents must verify the exact filename after a `write` call and delete any partial "sibling" files (e.g., if `package` is created alongside `package.json`) [.devin/rules/verify-file-creation.md:1-30]().
*   **Temporary File Hygiene**: Agents must never create temporary scripts or patches within the project repositories. They must use system temp directories (e.g., `/tmp/`) and clean them up immediately after use [.devin/rules/temp-files.md:5-26]().

### Code Guardrails
The agent follows a "Halt on Failure" policy to prevent hallucinated fixes during development:
*   **Self-Correction Limit**: Maximum of 2 attempts to fix a linter or test failure [.devin/rules/code-guardrails.md:6-7]().
*   **Escalation**: If the error persists after the 2nd attempt, the agent must stop, set its state to **BLOCKED**, and wait for user guidance [.devin/rules/code-guardrails.md:8-10]().
*   **Scope Locking**: Agents cannot alter function signatures or shared structures unless explicitly authorized in a pre-approved plan [.devin/rules/code-guardrails.md:12-15]().

Sources: [.devin/rules/always-check-rules-first.md:1-27](), [.devin/rules/code-guardrails.md:1-15](), [.devin/rules/temp-files.md:1-38](), [.devin/rules/verify-file-creation.md:1-66](), [AGENTS.md:1-10]().

## DAL Conventions and Guardrails

The following conventions are enforced by the agent to maintain the integrity of the Data Access Layer.

### Dependency and Naming
*   **Leaf Dependency**: The DAL must never import from `primebrick-be-v3` or `primebrick-us-v3`. It only depends on `pg`, `pg-query-stream`, and `reflect-metadata` [.devin/rules/dal-conventions.md:3-11]().
*   **Snake_case Everywhere**: This is a "Golden Rule." Database columns, TypeScript properties, and JSON keys must all remain `snake_case`. No DTO transformation or camelCase renaming is permitted [.devin/rules/data-model-conventions.md:12-16]().

### Implementation Guardrails
| Feature | Rule | Source |
| :--- | :--- | :--- |
| **Write Returns** | Always use `RETURNING *` for all inserts, updates, and deletes. | [.devin/rules/dal-conventions.md:24-26]() |
| **Find Defaults** | `throwIfNotFound` is `true` by default; `deletedRecords` is `EXCLUDED` by default. | [.devin/rules/dal-conventions.md:28-36]() |
| **Bulk Strategy** | Use the **TEMP TABLE strategy** for `updateMany` and `upsertMany`. | [.devin/rules/dal-conventions.md:39-44]() |
| **Numeric Types** | `bigint` must be handled via `INT8_OID` to return native `bigint`. | [.devin/rules/dal-conventions.md:46-52]() |
| **Audit** | Audit is port-based and **fire-and-forget**; it must not block the main path. | [.devin/rules/dal-conventions.md:55-60]() |
| **Transactions** | The DAL never commits automatically. | [.devin/rules/dal-conventions.md:86-90]() |

### Data Model Flow (Natural Language to Code Entity)
The following diagram illustrates how the agent maps requirements (Natural Language) to the specific code entities defined in the DAL rules.

**Diagram: Data Model Mapping**
```mermaid
graph TD
    subgraph "Natural Language Space"
        NL1["'Create a new user'"]
        NL2["'Get active records'"]
        NL3["'Update 1000 rows'"]
    end

    subgraph "Code Entity Space"
        CE1["Repository.add() with RETURNING *"]
        CE2["FindOptions { deletedRecords: 'EXCLUDED' }"]
        CE3["TEMP TABLE strategy in updateMany()"]
    end

    NL1 -->|"Rule: RETURNING *"| CE1
    NL2 -->|"Rule: Default Soft-Delete"| CE2
    NL3 -->|"Rule: Set-based Execution"| CE3
```
Sources: [.devin/rules/dal-conventions.md:1-94](), [.devin/rules/data-model-conventions.md:1-47]().

## Testing Rules

AI agents must verify all changes using the existing Vitest suite. Mocking the database is strictly forbidden.

*   **Real PostgreSQL Required**: Tests must run against a real database instance [.devin/rules/dal-testing.md:5-9]().
*   **Idempotent Setup**: Tables must be created via `CREATE TABLE IF NOT EXISTS` [.devin/rules/dal-testing.md:18-19]().
*   **Isolation**: Tables must be cleared between tests using `TRUNCATE RESTART IDENTITY CASCADE` [.devin/rules/dal-testing.md:21-28]().
*   **Type Matrix**: Every new type mapping must be added to `TypeTestEntity` to ensure round-trip fidelity [.devin/rules/dal-testing.md:44-57]().

Sources: [.devin/rules/dal-testing.md:1-71]().

## Invokable Skills

The repository defines specialized skills that the agent can invoke to perform complex tasks.

### dal-usage Skill
This skill provides the agent with a complete reference for bootstrapping and using the DAL gateway.

*   **Bootstrap**: Uses `getDal()` to create a singleton that manages the `pg.Pool` [.devin/skills/dal-usage/SKILL.md:34-46]().
*   **Entity Definition**: Enforces the use of decorators like `@Entity`, `@Key`, and `@AuditableField` [.devin/skills/dal-usage/SKILL.md:54-78]().
*   **Timeout Management**: Documents the use of `statement_timeout` (default 30s) as an anti-throttling measure [.devin/skills/dal-usage/SKILL.md:30-31]().
*   **Manual Transactions**: Uses `withClient(fn, { timeoutMs })` for explicit transaction control [.devin/skills/dal-usage/SKILL.md:144-161]().

### feature Skill
A high-level skill for end-to-end implementation:
1.  Implement the feature.
2.  Write Vitest tests using `SimpleTestEntity` or `TypeTestEntity`.
3.  Run tests and fix failures (within the 2-attempt guardrail).
4.  Summarize changes [.devin/skills/feature/SKILL.md:1-10]().

### Skill Invocation Flow
This diagram shows how the agent transitions from a high-level task to specific DAL skill implementations.

**Diagram: Skill Invocation Logic**
```mermaid
graph LR
    subgraph "Agent Task"
        Task["'Implement bulk upsert'"]
    end

    subgraph "Skill: dal-usage"
        S1["getDal() Singleton"]
        S2["upsertMany() with timeoutMs"]
        S3["Repository Class"]
    end

    subgraph "Code Implementation"
        CI1["src/dal/index.ts"]
        CI2["src/repository/Repository.ts"]
    end

    Task -->|"Invokes"| S2
    S2 -->|"Uses"| S1
    S1 -->|"Defined in"| CI1
    S2 -->|"Implemented in"| CI2
```

Sources: [.devin/skills/dal-usage/SKILL.md:1-176](), [.devin/skills/feature/SKILL.md:1-10]().

---