# SPEC.md — Agent Police Department (Chrome Extension)

## Product Identity
- **Name**: Agent Police Department
- **Tagline**: A police dashboard for your team's AI coding agents
- **Slug**: `agent-police-department-claude-code-agent-governan`
- **Form**: Chrome Extension (Manifest V3)
- **Tech Tier**: Simple

## Problem Statement
Teams adopting AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) lack visibility and governance. 65% of enterprises had security incidents from AI agents by April 2026. Only 30% have comprehensive governance. Small teams (5–50 devs) are priced out of enterprise tools ($10+/seat) and find open-source CLI tools too hard to use.

## Solution
A lightweight Chrome extension that provides real-time visibility into AI coding agent activity, audit trails, and policy violation alerts — all running locally in the browser without a backend server.

## MVP Scope (v1.0)

### Core Features
1. **Agent Activity Monitor**
   - Content scripts detect AI agent interactions on Claude.ai, GitHub, and ChatGPT
   - Captures: tool use, file access, API calls, code generation events
   - Timestamps every event with URL context

2. **Policy Engine (6 Detectors)**
   - Permission Bypass: agent accesses files outside allowed scope
   - Out-of-Scope: agent performs tasks beyond its mandate
   - Self-Permissioning: agent attempts to modify its own permissions
   - Disallowed Tools: agent uses blacklisted tools/APIs
   - Redundant Operations: repeated identical actions
   - Off-Task: agent drifts from assigned task

3. **Real-Time Dashboard (Popup)**
   - Active session count and status
   - Per-agent activity feed (last 50 events)
   - Violation alerts with severity (Low / Medium / High / Critical)
   - Team risk score (0–100)
   - Compliance status indicator

4. **Audit Log**
   - Local storage with 7-day retention
   - Searchable by agent, URL, severity, detector type
   - Export to JSON/CSV
   - Hash-chained integrity verification (tamper-evident)

5. **Policy Management**
   - Default policy YAML loaded on install
   - User can edit rules via popup UI
   - Rule types: allowed domains, allowed tools, file patterns, rate limits

### Architecture
```
manifest.json (V3)
├── background.js (service worker)
│   ├── Event collector
│   ├── Policy engine
│   ├── Audit log storage
│   └── Alert dispatcher
├── content_script.js
│   ├── Claude.ai detector
│   ├── GitHub detector
│   └── ChatGPT detector
├── popup.html + popup.js + popup.css
│   ├── Dashboard UI
│   ├── Policy editor
│   └── Audit log viewer
├── options.html + options.js
│   └── Advanced settings
├── lib/
│   ├── detectors.js (6 violation detectors)
│   ├── policy.js (rule engine)
│   ├── audit.js (storage + integrity)
│   └── hash.js (sha256 chain)
├── default_policy.yaml
└── tests/
    ├── detectors.test.js
    ├── policy.test.js
    └── audit.test.js
```

### Tech Stack
- Chrome Extension Manifest V3
- Vanilla JavaScript (no build step required for MVP)
- Chrome Storage API (local)
- Web Crypto API (SHA-256 for integrity)
- Jest for unit tests
- ESLint for linting

### Data Model
```json
{
  "event": {
    "id": "uuid",
    "timestamp": "ISO8601",
    "agent": "claude-code|cursor|copilot|chatgpt",
    "url": "https://claude.ai/chat/...",
    "type": "tool_use|file_access|code_generation|api_call|permission_request",
    "tool": "read_file|edit_file|bash|api_request",
    "target": "file_path_or_endpoint",
    "outcome": "allowed|denied|violation",
    "severity": "info|low|medium|high|critical"
  },
  "violation": {
    "id": "uuid",
    "event_id": "uuid",
    "detector": "permission_bypass|out_of_scope|...",
    "rule_triggered": "rule_id",
    "severity": "low|medium|high|critical",
    "message": "human readable explanation",
    "timestamp": "ISO8601"
  },
  "policy": {
    "version": 1,
    "rules": [
      {
        "id": "rule_1",
        "type": "allowed_domains",
        "enabled": true,
        "params": { "domains": ["github.com", "claude.ai", "api.openai.com"] }
      },
      {
        "id": "rule_2",
        "type": "disallowed_tools",
        "enabled": true,
        "params": { "tools": ["eval", "exec", "shell"] }
      }
    ]
  }
}
```

### Build Requirements
- `npm test` must pass (Jest)
- `npm run lint` must pass (ESLint)
- Anti-skeleton: every function has real implementation
- No placeholder returns, no TODOs in shipped code
- Secret scan: no API keys, credentials, or tokens in source

### Distribution
- Chrome Web Store (free tier)
- GitHub release with built `.zip`
- Source code at https://git.bunbunlabs.com/bunbun/agent-police-department-claude-code-agent-governan

### Future Roadmap (post-MVP)
- Team sync via cloud backend
- Slack/Discord alerts
- GitHub PR annotations
- SSO integration
- SIEM export (Splunk/Datadog)
- Mobile push notifications

## Verdict
- **Buildable**: Yes — Chrome extension, no backend required
- **Gated**: No — local-only for MVP, no server/DB/auth needed
- **Category**: Chrome Extension