---
name: pi-cc-harness
description: Harness-specific guidance — when to dispatch via Claude Code's Agent tool vs /pi:agent, how to monitor a dispatched specialist, and how to interpret /pi:status.
---

# `pi-cc-plugin` for the orchestrator

This skill assumes you're running the GAN-style task-team pipeline
(`harness-orchestrate` skill). Read `pi-cc-usage` first if you haven't.

## The dispatch decision

For every specialist invocation:

1. Read the specialist's frontmatter from `.pi/agents/<role>.md`.
2. If `model` is one Claude Code can run natively (currently the
   `anthropic/claude-*` family), dispatch via the **Agent tool**.
3. Otherwise, dispatch via **`/pi:agent`** (this plugin).

Don't try to short-circuit the decision based on what's "easier". Pi-side
specialists need to be dispatched by pi so pi can supply the model
adapter, the MCP context, and the worktree. Claude-side specialists need
the Agent tool so the orchestrator can stream events directly.

## Threading task context

Every specialist call — pi-side or Claude-side — must carry enough
context for the specialist to act independently: which task they're
acting on, where the relevant files are, what the prior step produced.

For `/pi:agent` dispatches, embed the context in the task brief:

```
/pi:agent implementer Implement the function from .work/AUTOPILOT-123/architect-brief.md. Tests live at tests/auth.test.mjs. Make them green.
```

The specialist sees the entire prompt as their `task` argument. Pi reads
agent frontmatter from `.pi/agents/implementer.md` for its model,
thinking level, tools, etc.

By default `/pi:agent` waits and prints the specialist's output inline, so
the orchestrator can read it directly from the tool result. Add `--bg`
when the specialist is expected to take long enough that you'd rather
fan out other work in the meantime, then pick up the result via
`/pi:result <id>`.

## Polling backgrounded jobs

When you've dispatched with `--bg`, you have two state sources:

| Question | Source |
|---|---|
| Is pi still running? Per-step progress? | `/pi:status <id>` |
| What did the specialist actually produce? | `/pi:result <id>` |

Polling cadence depends on the specialist. Architect/test-writer specialists
are usually 1-3 minutes; implementer can be 10+. Don't poll faster than
every ~30s — pi's status doesn't update that often anyway.

`/pi:status` auto-reconciles `state.json` against pi's status. So if you
poll and see `completed`, that's authoritative even if you didn't run any
explicit cancel/result command in between.

It also forwards pi-subagents' `events.jsonl` raw under an `events:`
block — `subagent.run.started`, `subagent.step.started`, child pi
`tool_call`s tagged `subagentSource: "child"`, `subagent.run.completed`,
etc. Read those events to figure out what the specialist is *actually*
doing right now (e.g. "still grepping" vs "writing the patch") before
you decide whether to wait, nudge, or cancel.

## When `/pi:cancel` is the right move

- Specialist is hung past its expected window. Cancel, escalate to user
  for triage.
- Wrong specialist was dispatched (orchestrator picked the wrong role).
  Cancel, dispatch the right one.

When NOT to cancel:

- Just because the run is "taking longer than I expected." Read the
  `output-N.log` first via `/pi:result` — the specialist may be working
  productively.
- The user said "stop everything." That's a `/exit` — let pi runs
  complete on their own; they're already detached.

## Surfacing errors

`/pi:status` displays per-step errors inline as `step (error)` and
under a `step-errors:` block. Pi-subagents sometimes marks runs as
`complete` even when a step's API call failed (e.g. wrong model name,
provider returning HTTP 400). Always check for that flag before treating
a "completed" run as a real success.

## Composes with

- **`harness-orchestrate`** (in `~/workspace/skills`) — the top-level
  orchestrator skill. Owns the GAN pipeline state machine. This skill is
  the *integration* layer between that pipeline and pi.
- **`pi-cc-usage`** — the per-command reference. Read first.