# Phase 3: Verification Agent — Specification

**Priority:** P2 · **Effort:** 0.5 days · **Dependencies:** None  
**Reference:** `claude-code-main/src/tools/AgentTool/built-in/verificationAgent.ts`

---

## 1. Problem Statement

Claude Code has a built-in **Verification** agent type that tests plans, runs builds, executes test suites, and performs adversarial probes to produce a PASS/FAIL/PARTIAL verdict. pi-subagents lacks this agent type.

Without a verification agent, the pipeline is: user request → Plan agent plans → General-purpose agent implements → **(missing: verify)**. Adding a verification agent closes this loop, enabling an end-to-end plan→implement→verify workflow.

---

## 2. Design

### 2.1. Agent Identity

```
Type name:    "Verification" (capital V, matching "Explore" and "Plan" convention)
Display name: "Verification"
Description:  "Verification specialist — runs builds, tests, and adversarial probes"
Model:        Parent model (inherit — verification may be complex)
```

### 2.2. Tool Access

The verification agent is **read-only for project files** but can write ephemeral test scripts to `/tmp`. Tool set:

| Tool | Access |
|---|---|
| `read` | ✅ Full |
| `bash` | ✅ Full (for running builds/tests/linters) |
| `grep` | ✅ Full |
| `find` | ✅ Full |
| `ls` | ✅ Full |
| `edit` / `write` | ❌ Denied for project directory |
| `Agent` | ❌ Denied (no sub-spawning) |

### 2.3. System Prompt

The verification system prompt (200+ lines) is the core of this feature. Key sections:

**Identity**: "You are a verification specialist. Your job is not to confirm the implementation works — it's to try to break it."

**Prohibitions**: Creating/modifying/deleting project files, installing dependencies, git writes.

**Allowed writes**: Ephemeral test scripts to `/tmp` or `$TMPDIR`.

**Verification strategy by change type**:
- Frontend: dev server → browser/MCP automation → curl subresources → test suite
- Backend/API: start server → curl endpoints → verify response shapes → error handling → edge cases
- CLI/scripts: run with representative inputs → stdout/stderr/exit codes → edge inputs
- Infrastructure: validate syntax → dry-run where possible
- Library/package: build → test suite → import from fresh context → verify public API
- Bug fixes: reproduce original bug → verify fix → regression → related functionality
- Refactoring: test suite must pass unchanged → diff public API → spot-check behavior

**Required output format**: Every check must include:
```
### Check: [what you're verifying]
**Command run:**
  [exact command]
**Output observed:**
  [actual output]
**Result: PASS** (or FAIL — with Expected vs Actual)
```

**Verdict line** at the end:
```
VERDICT: PASS
VERDICT: FAIL
VERDICT: PARTIAL
```

---

## 3. API Changes

### 3.1. New Default Agent Entry

Added to `src/default-agents.ts`:

```typescript
[
  "Verification",
  {
    name: "Verification",
    displayName: "Verification",
    description: "Verification specialist — runs builds, tests, and adversarial probes",
    builtinToolNames: READ_ONLY_TOOLS,  // Same as Explore/Plan
    extensions: true,
    skills: true,
    model: undefined,  // Inherit parent model
    systemPrompt: VERIFICATION_SYSTEM_PROMPT,
    promptMode: "replace",
    isDefault: true,
  },
],
```

### 3.2. Agent Type Visibility

The Verification agent appears in the `Agent` tool's type list and in `/agents`. No new tools or commands needed.

---

## 4. Testing Plan

| Test | What it verifies |
|---|---|
| Agent type registered | `getAvailableTypes()` includes "Verification" |
| Tool restrictions | `builtinToolNames` matches read-only tools |
| Prompt mode | Uses "replace" mode (full custom prompt, no parent identity) |
| Disallowed tools | edit/write/Agent excluded from tool set |