| 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:
- Read the specialist's frontmatter from
.pi/agents/<role>.md.
- If
model is one Claude Code can run natively (currently the
anthropic/claude-* family), dispatch via the Agent tool.
- 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_calls 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.
