# Agent Skills & Execution Permissions

# Agent Skills & Execution Permissions

<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/skills/feature/SKILL.md](.devin/skills/feature/SKILL.md)

</details>



This page describes the governance framework for AI agents operating within the Primebrick v3 microservices repository. It details the skill-based execution model defined in the `.devin/skills` directory and the security sandbox configuration that restricts command-line operations.

## 1. The "Feature" Skill Framework

The repository utilizes a structured skill framework to guide AI agents through complex, multi-step tasks. The primary operational unit is the `feature` skill, which enforces a specific lifecycle for code modifications to ensure stability and quality.

### 1.1 Implementation Logic
The `feature` skill follows a four-step sequential workflow that bridges the gap between natural language requirements and verified code changes:

1.  **Implement**: The agent performs the requested code modifications based on the repository's architectural standards.
2.  **Test**: The agent is required to author unit or integration tests for the new functionality.
3.  **Fix**: The agent executes the tests and must resolve any failures before proceeding.
4.  **Summarize**: A final report of changes is generated to maintain the audit trail.

### 1.2 Tool Sandboxing
Each skill defines an `allowed-tools` whitelist. This restricts the agent's interaction with the filesystem and environment to a minimal set of capabilities required for the task. For the `feature` skill, the sandbox is limited to:
*   `read`: File inspection.
*   `write`: Code application.
*   `exec`: Command execution (subject to global permissions).
*   `grep`: Content searching.

### Workflow: Feature Skill Execution
The following diagram illustrates the transition from a Natural Language Request to the execution of the `feature` skill steps.

"Natural Language to Execution Flow"
```mermaid
graph TD
    subgraph "Natural Language Space"
        REQ["User Request (e.g., 'Add Email Retry')"]
    end

    subgraph "Agent Skill Space (.devin/skills/feature/SKILL.md)"
        SKILL_DEF["SKILL: feature"]
        STEP1["Step 1: Implement"]
        STEP2["Step 2: Write tests"]
        STEP3["Step 3: Run & Fix failures"]
        STEP4["Step 4: Summarize"]
    end

    subgraph "Code Entity Space"
        EXEC_READ["allowed-tool: read"]
        EXEC_WRITE["allowed-tool: write"]
        EXEC_EXEC["allowed-tool: exec"]
        EXEC_GREP["allowed-tool: grep"]
    end

    REQ --> SKILL_DEF
    SKILL_DEF --> STEP1
    SKILL_DEF --> STEP2
    SKILL_DEF --> STEP3
    SKILL_DEF --> STEP4

    STEP1 -.-> EXEC_WRITE
    STEP2 -.-> EXEC_WRITE
    STEP3 -.-> EXEC_EXEC
    STEP4 -.-> EXEC_READ
```

**Sources:**
*   `feature` skill definition: [.devin/skills/feature/SKILL.md:1-9]()
*   Tool whitelist: [.devin/skills/feature/SKILL.md:4-4]()

---

## 2. Execution Permissions & Whitelisting

While the `feature` skill grants the agent the *ability* to use the `exec` tool, the actual commands that can be run are governed by a global permission whitelist. This prevents the execution of unauthorized binaries or scripts that could compromise the development environment.

### 2.1 config.local.json Specification
The `permissions.allow` array in the configuration file defines the explicit boundary of the agent's shell access. Only the commands listed in this file are permitted for use via the `Exec()` interface.

| Allowed Command | Purpose |
| :--- | :--- |
| `npx` | Running local package binaries (e.g., Prisma, Vitest). |
| `npm list` | Dependency tree inspection. |
| `powershell` | System-level task orchestration on Windows environments. |
| `cd` | Directory navigation within the monorepo. |
| `pnpm` | Package management and workspace script execution. |
| `git` | Version control operations (commits, branch management). |

### 2.2 Command Validation Flow
When an agent attempts to execute a command as part of Step 3 (`Run tests`) of the `feature` skill, the system validates the command against the `config.local.json` whitelist.

"Permission Validation Logic"
```mermaid
graph TD
    subgraph "Skill Step Execution"
        STEP_EXEC["Step 3: Run tests and fix failures"]
    end

    subgraph "Permission Engine (.devin/config.local.json)"
        WL["permissions.allow whitelist"]
        CHK{"Is Command Allowed?"}
    end

    subgraph "System Shell"
        NPX["Exec(npx)"]
        PNPM["Exec(pnpm)"]
        GIT["Exec(git)"]
        DENY["Permission Denied"]
    end

    STEP_EXEC --> CHK
    WL --> CHK
    CHK -- "Yes (matches pnpm)" --> PNPM
    CHK -- "Yes (matches npx)" --> NPX
    CHK -- "Yes (matches git)" --> GIT
    CHK -- "No" --> DENY
```

**Sources:**
*   Permission whitelist: [.devin/config.local.json:2-11]()
*   Execution step: [.devin/skills/feature/SKILL.md:8-8]()

---

## 3. Data Flow: From Request to Verified Code

The integration of skills and permissions ensures a controlled data flow. The agent cannot write code without the `write` tool, and it cannot verify code without the `exec` tool, which is further constrained by the `pnpm` or `npx` whitelist.

### 3.1 Interaction Summary
1.  **Skill Activation**: The agent identifies the task as a `feature` implementation.
2.  **Tool Authorization**: The agent gains access to `read`, `write`, `exec`, and `grep` [.devin/skills/feature/SKILL.md:4-4]().
3.  **Command Execution**: When the agent runs `pnpm test`, the `config.local.json` file is consulted. Since `Exec(pnpm)` is allowed [.devin/config.local.json:8-8](), the command proceeds.
4.  **State Finalization**: Once tests pass, the agent uses the `write` tool to finalize the implementation and the `git` tool [.devin/config.local.json:9-9]() to commit the changes.

**Sources:**
*   Skill steps: [.devin/skills/feature/SKILL.md:6-9]()
*   Allowed binaries: [.devin/config.local.json:3-10]()

---