# Pair Agent

> Pair with a named subagent in the loop — explicit two-mind collaboration on a focused task.

- Skill: `jokerman89/pair-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jokerman89/pair-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/pair-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jokerman89/pair-agent

---


# /pair-agent

Pair-programming style with a named subagent. Operator describes a task; skill brings in a specialist subagent (CodeReviewer, SecurityAuditor, PerformanceAnalyzer, etc.) to ALTERNATE with the main agent on each step. Output: two-perspective trace + final synthesis.

Distinct from `/codex` (outside-voice review post-hoc) and from spawning a subagent for a one-shot question. Pair-mode means the subagent is in the loop alongside the main agent throughout.

`cli_support: [claude-code]` only — subagent orchestration uses the Agent tool, which is Claude Code-native.

## When to use

- Sensitive change where two-perspective review during AUTHORING beats post-hoc review
- Security-sensitive code path — main agent writes, SecurityAuditor inspects each step
- Performance-critical refactor — main agent edits, PerformanceAnalyzer measures each step
- Cross-domain change where one specialist's vocabulary keeps drift in check

## When NOT to use

- Trivial change — pair overhead dominates the task
- Pure post-hoc review — use `/review` or `/codex`
- Subagent name not registered — skill won't invent agents

## Inputs

- Required `--agent <name>` — registered subagent name (e.g. `CodeReviewer`, `SecurityAuditor`, `Architect`, `Refactorer`, `DevOpsToolchain`, `ReadOnly`)
- Required: task description (inline prose)
- Optional `--turns <N>` — how many alternation turns (default: 3)
- Optional `--scope <files>` — restrict subagent's reads to these files

## Workflow

1. **Resolve subagent.** Look up `--agent` in the plugin's subagent fleet (run `/li:catalog` to list the available agents; a repo-local `.claude/agents/` override, if one exists, shadows the fleet by name). If not found: list available + exit.
2. **State the task.** Print the task description so operator sees what both minds will work on.
3. **Turn loop.**
   - **Main turn:** main agent proposes a step (a diff, a decision, an investigation move). Output is shown.
   - **Subagent turn:** subagent reviews the proposal from its specialty. Spawned via Agent tool with focused prompt + scope.
   - **Operator gate:** AskUserQuestion — accept, modify, or skip this step.
4. **Iterate** until `--turns` reached or task complete.
5. **Synthesis.** Final summary: what was built, what subagent flagged, what was kept/skipped.

## Report format

```
Pair Agent: refactor src/lib/dlxClient.ts retry logic
Specialist: PerformanceAnalyzer
Turns: 3

## Turn 1
Main: propose extracting retry into separate function for testability.
PerformanceAnalyzer: structure neutral for perf; recommend benchmarking before + after.
Operator: ACCEPTED.

## Turn 2
Main: apply extraction. Diff shown.
PerformanceAnalyzer: benchmark check — function call overhead negligible (<1µs). No regression.
Operator: ACCEPTED.

## Turn 3
Main: add reset-controller on retry per /investigate finding.
PerformanceAnalyzer: micro-benchmark — adds 50ns per retry, immaterial.
Operator: ACCEPTED.

## Synthesis
3 turns, 3 accepted. PerformanceAnalyzer raised 1 minor concern (resolved via benchmark). No perf regression detected.
Final diff: src/lib/dlxClient.ts +18 -7.
Recommendation: /qa-only before /ship.
```

## Compliance integration

- Each main-agent Edit goes through the active pack's compliance gates + the secret/customer-data block hooks.
- Subagent invocations logged to `.claude/runtime/audit/pair-agent.jsonl`.
- Subagent inherits scope restriction from `--scope`; cannot read outside that set.

## Failure modes

- **Subagent not found:** list the plugin fleet's agents (`/li:catalog`), suggest one. Exit.
- **Subagent disagrees fundamentally with main agent's first proposal:** stop, report the disagreement, ask operator which path to take. Do not auto-resolve.
- **Operator rejects 3 turns in a row:** suspect the wrong specialist was paired. Suggest different `--agent` and exit.
- **Turn budget exhausted, task incomplete:** report partial state. Operator can re-run with higher `--turns`.
- **`Agent` tool unavailable (running in Codex/Copilot):** STOP — this skill is claude-code only. Surface alternative (use `/codex` post-hoc instead).

## Examples

**Security pair on auth refactor:**
```
> /pair-agent --agent SecurityAuditor --turns 4 "refactor JWT validation to use jose library"
[4 turns: main proposes, auditor scans, operator gates]
✓ 3/4 accepted. 1 turn revised after auditor flagged token-leak in error message.
```

**Architect pair on new module:**
```
> /pair-agent --agent Architect "design new src/lib/billing/ module structure"
[3 turns of layout proposals + architectural critique]
✓ Module structure agreed: billing/{api,domain,fixtures}.ts split.
```

**Quick check pair:**
```
> /pair-agent --agent CodeReviewer --turns 1 "review this rename across 12 files"
[Single turn: main shows diff, reviewer checks for missed references]
✓ Reviewer found 2 missed references in tests/. Fix proposed.
```

**DevOps pair on CI/CD change:**
```
> /pair-agent --agent DevOpsToolchain --turns 3 "add a canary stage to the deploy workflow"
[Main proposes pipeline edits, DevOpsToolchain reviews each for SRE/observability gaps]
✓ 3/3 accepted. DevOpsToolchain added a rollback trigger on canary error-rate breach.
```

**Read-only context pair:**
```
> /pair-agent --agent ReadOnly --scope src/lib/ "explain how retry/backoff is wired before I refactor"
[Main asks, ReadOnly explores src/lib/ non-destructively and returns cited findings]
✓ ReadOnly surfaced 3 retry call-sites + 1 undocumented backoff cap.
```

## See also

- `/li:review` — post-hoc diff review (lighter than pair)
- `/li:codex` — outside-voice review post-hoc
- `/li:catalog` — lists the plugin's specialist subagent fleet
- `/li:skillify` — if pair-mode for a specific task becomes recurring, formalize as a skill