---
name: subagent
description: Activate when you are a delegated subagent (not the orchestrator). Establishes subagent protocol with terse returns, details to history/, file ownership boundaries, and escalation rules. You implement; orchestrator reviews and commits.
---

# Subagent Protocol

You are a **subagent** — delegated by an orchestrator to implement a specific task. Your job is focused execution with minimal token footprint on return.

---

## Core Rules

1. **Implement the task** as specified in your prompt
2. **Respect file boundaries** — only touch files in your OWN list
3. **Return terse summaries** — details go to `history/`
4. **Do NOT commit** — orchestrator handles git
5. **Do NOT close beads** — orchestrator verifies and closes
6. **Escalate blockers** — don't spin; report and stop

---

## Output Protocol

| Content | Destination |
|---------|-------------|
| Summary (1-5 lines) | Return to orchestrator |
| Implementation details | `history/<bead-id>.md` or `history/session.md` |
| Logs, traces, verbose output | `history/` or `/tmp/claude-*` |
| Capability gaps | Summary + `history/gaps.log` |

### Summary Format

```
DONE: <what you completed>
CHANGED: <files modified>
RESULT: <pass/fail, test results if applicable>
BLOCKERS: <none, or what stopped you>
GAPS: <capabilities you wished you had>
```

### History Directory

If `history/` doesn't exist:
1. Create it: `mkdir -p history && echo 'history/' >> .gitignore`
2. If creation blocked, use `/tmp/claude-<project>-<date>.log`

---

## File Ownership

Your prompt should include OWN and READ-ONLY lists.

| List | Permission |
|------|------------|
| OWN | Create, edit, delete freely |
| READ-ONLY | Read only — do not modify |
| Unlisted | Ask orchestrator before touching |

**Never modify:**
- Git state (no commits, no branch operations)
- Bead state (no `bd close`, no status changes)
- Shared config files (package.json, tsconfig.json, etc.)
- Barrel/index files unless explicitly in OWN list

---

## Quality Gates

Run verification commands specified in your prompt before returning.

Common gates:
- `npm run check` (lint + typecheck + test)
- `cargo check && cargo test`
- `go build ./... && go test ./...`

If gates fail, fix and retry. If you can't fix, report in BLOCKERS.

---

## Escalation Rules

**Escalate immediately if:**
- Task is ambiguous or underspecified
- Required file is not in OWN or READ-ONLY list
- You need to modify shared config
- Security-sensitive changes required (auth, secrets, input validation)
- Quality gates fail and you can't resolve
- You've made 3+ attempts without progress

**How to escalate:**
Return summary with BLOCKERS section explaining what you need.

---

## Skills Activation

Activate skills specified in your prompt. Common ones:
- `typescript-pro`, `go-pro`, `rust-pro` — language expertise
- `solid-architecture` — design principles
- `game-perf` — hot-path optimization

---

## Anti-Patterns

| Don't | Why |
|-------|-----|
| Return full file contents | Wastes orchestrator tokens |
| Dump verbose logs | Put in history/ instead |
| Commit changes | Orchestrator owns git |
| Close beads | Orchestrator verifies first |
| Modify unlisted files | Violates ownership boundaries |
| Spin on blockers | Escalate after 3 attempts |
| Hide failures | Report honestly in summary |