Agent Instinct System

# Agent Instinct System

Part of [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills) by [googleadsagent.ai™](https://googleadsagent.ai)

## Description

The Agent Instinct System implements pre-cognitive reflexes — automatic safety checks and validations that fire before every code change, tool call, or output generation. Just as biological reflexes protect organisms from harm faster than conscious thought, agent instincts protect codebases and systems from damage faster than deliberate reasoning. These instincts operate below the level of task-specific logic, forming a universal safety layer that activates regardless of what the agent is doing.

Developed for the Buddy™ agent at [googleadsagent.ai™](https://googleadsagent.ai), where a single incorrect Google Ads API call could burn through a client's entire monthly budget, the instinct system enforces invariants that must never be violated. Budget caps are checked before bid modifications. Destructive operations require confirmation signals. File deletions are validated against protection lists. These checks happen automatically, without the agent needing to "remember" to perform them.

The instinct system is organized into three tiers: reflexes (instant, zero-cost checks like "is this file in the protected list"), gates (lightweight validations like "does this change pass the linter"), and assessments (more expensive checks like "does this modification align with the stated task"). Each tier adds latency but catches increasingly subtle issues.

## Use When

- Agents operate on production systems where mistakes have real consequences
- You need defense-in-depth beyond what a single verification step provides
- Multiple agents or team members work on the same codebase simultaneously
- The agent handles destructive operations (deletions, deployments, API mutations)
- Compliance requirements mandate pre-action validation for AI-generated changes
- You want to prevent entire categories of mistakes rather than catching them after the fact

## How It Works

```mermaid
graph TD
    A[Agent Intent] --> B[Tier 1: Reflexes]
    B -->|Block| C[Immediate Rejection]
    B -->|Pass| D[Tier 2: Gates]
    D -->|Block| E[Rejection + Guidance]
    D -->|Pass| F[Tier 3: Assessments]
    F -->|Block| G[Rejection + Alternative]
    F -->|Pass| H[Action Execution]
    H --> I[Post-Action Audit]
    I --> J[Instinct Learning]
    J --> K{New Pattern?}
    K -->|Yes| L[Add Reflex/Gate]
    K -->|No| M[Log + Continue]
```

When the agent forms an intent to act (write a file, call a tool, generate output), the intent passes through the instinct tiers sequentially. Tier 1 reflexes are hardcoded checks that execute in microseconds: protected file lists, forbidden operation patterns, budget ceiling checks. Tier 2 gates run lightweight validations: syntax checks, dependency verification, scope validation. Tier 3 assessments perform deeper analysis: task alignment verification, impact estimation, side-effect prediction. After execution, post-action audits feed back into the instinct system, allowing it to learn new protective patterns from near-misses.

## Implementation

**Instinct Engine Core:**

```typescript
type InstinctTier = "reflex" | "gate" | "assessment";

interface Instinct {
  name: string;
  tier: InstinctTier;
  check(intent: AgentIntent): Promise<InstinctResult>;
}

interface InstinctResult {
  allow: boolean;
  reason?: string;
  alternative?: string;
}

class InstinctEngine {
  private instincts: Map<InstinctTier, Instinct[]> = new Map([
    ["reflex", []],
    ["gate", []],
    ["assessment", []],
  ]);

  register(instinct: Instinct): void {
    this.instincts.get(instinct.tier)!.push(instinct);
  }

  async evaluate(intent: AgentIntent): Promise<