Pi CLI Orchestrator - Cross-AI Task Delegation
A Pi session MAY dispatch this skill. Pi has no in-process delegation of its own, so the CLI
is the only way a Pi session can hand work out; being inside Pi is not a reason to refuse.
What still refuses: the shared runtime rejects a dispatch from inside a fan-out lineage, and one
whose kind already appears in the dispatch stack. Those bound a runaway spawn chain and are
unchanged. The sibling cli-X packets keep their own guards; this carve-out is Pi's alone.
Orchestrate Pi's terminal coding agent for headless coding, read-only tool-constrained reviews, JSON event-stream integrations, RPC clients, and Pi-native resource discovery.
The pinned contract is the source for confirmed command behavior: Pi contract pin.
Pi-native skills, prompt templates, and some package surfaces remain documented but unconfirmed unless a source says otherwise.
Core principle: use Pi for the surfaces it exposes, delegate research and review lineages to the shared runtime, validate the returned output, and keep the calling AI as conductor.
1. WHEN TO USE
Activation Triggers
- Headless Pi dispatch: use when the task explicitly requests Pi, pi.dev, or the Pi coding agent.
- Cross-AI validation: use for an independent implementation attempt, code review, or second opinion through Pi.
- JSON event output: use when a caller needs Pi's line-delimited event stream.
- RPC integration: use when a long-lived stdin/stdout protocol is explicitly requested.
- Pi-native resources: use when the task concerns Pi skills, prompt templates, extensions, or installed packages.
- Community package delegation: use when the task explicitly names pi-mcp-extension.
When NOT to Use
- Pi is not installed or cannot be found on PATH.
- The task is a small in-process change that the calling AI already understands.
- The task requires a feature that belongs to the shared deep-loop runtime rather than this packet.
- A community package is requested without approval to install or trust project-local files.
2. SMART ROUTING
The cli-external-orchestration hub routes a Pi dispatch here: the request names Pi, pi.dev or the Pi coding agent, or needs Pi's JSON event stream, an RPC client, an independent second opinion, or Pi-native skills, extensions and packages.
hub-router.json scores that request, the winning workflowMode is cli-pi, and the hub loads this SKILL.md first.
The hub root ROUTER.md names this packet's first leaves, so leaf selection stays in the hub router rather than in this file.
command -v pi decides whether the route exists at all, and the probe runs before every dispatch.
It loads references/cli-reference.md and assets/prompt-quality-card.md first on every run, before any intent selection.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Execution Ownership
This packet owns provider-specific routing, the availability probe, and prompt construction.
For research and review lineages, the shared deep-loop runtime owns process construction and execution. The runtime supports the cli-pi executor kind, and its fan-out command builder is implemented with print mode, a provider-qualified --model, and --thinking from reasoningEffort, so a lineage dispatches through the executor kind directly.
That runner accepts only the research and review loop types, so a single build or doc dispatch uses the child dispatch envelope in providers-and-models.md §5.
Do not add a packet-local wrapper, spawn path, or command builder.
Five providers are reachable: openai (the ChatGPT sign-in, named openai-codex before Pi 1.0), opencode-go, llmgateway (DevPass, the operator's LLM Gateway plan, metered per token with a 3x credit bonus), minimax and mistral (the operator's Mistral subscription, a Pi builtin, direct dispatch only).
llmgateway is not a Pi builtin. It exists only because .pi/models.json declares it, and its setup, credentials and removal are in .pi/custom-providers.md.
Closed roster: non-roster models are FORBIDDEN. Dispatch ONLY the models in references/providers-and-models.md §2. That file is the single place the ids, thinking ceilings and per-provider id shapes are recorded, and this file names the providers without restating their models.
The deep-loop fan-out hard-rejects any off-roster id (isPiModelAllowed over PI_SUPPORTED_MODELS). Even a direct pi --model invocation must not use an unlisted id.
To add a fan-out model, amend the roster and PI_SUPPORTED_MODELS; a direct-dispatch-only row needs the roster alone.
The pinned contract confirms that headless Pi uses print mode, that JSON mode emits JSONL events, and that RPC mode is a persistent JSONL protocol. These are different contracts. Do not treat RPC as a one-shot print invocation. See cli-reference.md and integration-patterns.md.
Dispatch-Critical Gotchas
The full flag glossary and pinned-contract citations are in the ALWAYS-loaded cli-reference.md. Gotchas that silently break a dispatch and must be honored at routing time:
- Redirect stdin on every non-interactive dispatch:
</dev/null. Without it pi -p inherits the
parent terminal's stdin and hangs indefinitely, emitting nothing at all — not a partial answer,
not an error. Because print mode buffers until completion, an empty log is also what a working
dispatch looks like mid-run, so the deadlock is indistinguishable from a slow model and has been
mistaken for one for over an hour. The sibling cli-opencode packet carries the same rule for
opencode run; it applies here for exactly the same reason.
--offline is required for any automated or CI dispatch. pi --verbose without --offline hung for over two minutes with no reachable network path in the pinned contract's live probe. Any non-interactive dispatch through this packet must pass --offline explicitly rather than rely on a fast failure.
- The exit code is never an availability or auth signal. An identical unauthenticated
pi -p dispatch returned exit 0 on the first run and exit 1 on every subsequent run in the pinned contract. Every guard in this packet checks output text (No API key found...), never exit code.
- An invalid
.pi/extensions/*.ts fails the whole session, not just that extension. The pinned contract confirmed Pi validates extensions must export a factory function; a broken one blocks the entire dispatch with Extension does not export a valid factory function rather than skipping it with a warning.
- The default provider is
google, not Anthropic. pi --help documents --provider <name> (default: google). Do not assume an Anthropic-first default when you compose a dispatch that omits --provider.
This repository's .pi/settings.json overrides that builtin: defaultProvider is llmgateway and defaultModel is deepseek-v4.1-flash-1017, so a run naming no model goes there rather than to google.
pi install/pi list require --approve to see or modify project-local package config. Without it, both commands behave as if no packages exist, even when one is installed — the trust gate applies to reads, not only writes.
- The operator's global Pi packages load in a dispatched child, and pi-blackhole compacts it mid-run. pi-blackhole's config (
~/.pi/agent/pi-blackhole/pi-blackhole-config.json) auto-compacts at compactAfterTokens, 272,000 here, with midRunCompaction: "resume".
The compaction replaces everything the child has read with a structural summary, so a child still reading when it fires starts reading again and can loop without ever editing.
Set PI_BLACKHOLE_PASSIVE=true in the child's environment, which the package documents as switching off its background workers and its auto-compaction.
The deep-loop fan-out's cli-pi environment filter passes this one variable through, so a value exported in the shell that runs the fan-out reaches every Pi child, and any variable outside the filter's list is still stripped.
Pi's own compaction is off in .pi/settings.json, so the child keeps its model's full context window.
Dispatch Lifecycle
- Verify the binary with command -v pi.
- Classify the request as print, JSON, RPC, read-only tool-constrained review, native-resource inspection, or generation.
- Compose the prompt using prompt-quality-card.md.
- Pass a research or review lineage to the shared deep-loop runtime; run a single build or doc dispatch with the child dispatch envelope in providers-and-models.md §5.
- Capture stdout and stderr separately when the runtime allows it.
- Validate the output, changed files, and required tests before handback.
Headless Modes
| Requested result |
Pi surface |
Guardrail |
| One prompt and final response |
print mode with -p or --print |
Inspect output, not exit code alone |
| Structured events |
--mode json |
Parse one JSON object per line |
| Long-lived integration |
--mode rpc |
Keep stdin/stdout as a JSONL protocol |
| Read-only review |
print mode plus --tools read,grep,find,ls |
Treat the tool allowlist as the write boundary |
The print, JSON, RPC, and tool flags above are from the live help capture and the pinned contract. The read-only pattern is a caller-selected restriction, not a separate Pi plan mode.
Provider Preflight
Pi reports missing provider credentials in output. The pinned contract observed the same failure with different exit codes across otherwise identical invocations. Never use an exit code alone to claim that a dispatch reached a model. If the output reports a missing API key, stop and surface the provider requirement.
Native Resources
Pi's native resource surfaces are documented separately because their discovery behavior is not uniformly live-confirmed:
Classifier Calls
Pi carries classifier models that answer a typed question over JSON state instead of chatting. The
classifier types are choice, bool and score, documented in the installed package's
docs/models.md. A Pi worker reaches them three ways:
- a codemode script calls
models.getModelOfType("classifier", provider, id), then
models.classify(model, { state, questions }), and needs "defaultTools": ["+codemode"] in settings
- an extension calls
ctx.modelRegistry.classify() and needs no codemode
- the SDK's
ModelRuntime exposes create(), getModelOfType, getAvailableOfType and classify
Credentials stay in Pi's own store. Pi resolves them from its own configuration, so a classifier call
passes no key, and an answer is evidence for the caller's decision, never permission. When the service
reports token counts, result.usage carries them with their cost.
Prompt Construction
The caller remains responsible for task scope, files, acceptance criteria, and verification. Use the prompt templates as scaffolds, not as a substitute for reading the target mode's skill contract. Pass an established spec folder to a non-interactive child when the parent workflow requires it.
4. RULES
✅ ALWAYS
- Run command -v pi before every dispatch.
- Delegate research and review lineages to the shared deep-loop runtime. It rejects every other loop type, so a single build or doc dispatch uses the child dispatch envelope in providers-and-models.md §5.
- Choose print, JSON, or RPC deliberately. RPC is persistent and is not a print-mode alias.
- Capture and inspect output text for provider and extension failures.
- Use the prompt-quality card's two-tier precedence rule.
- Apply the least-permissive tool set that satisfies the task.
- Validate Pi-generated changes with the repository's code and test gates.
- Keep the current runtime as conductor and Pi as delegated executor.
- Treat Pi-native discovery claims as confirmed only when backed by the pinned contract or a linked live documentation page.
- Compose every dispatch as
{resolved agent persona + task prompt}, never a bare task. Resolve the persona from the ACTIVE runtime's agent directory (AGENTS.md §9; never hardcode a runtime) and map each subtask to the right agent (code, review, design, deep-research, markdown).
Core Pi has no native persona surface on pi -p, so INLINE the persona block into the payload, because the child cannot resolve agent paths by reference.
A persona-less leaf runs as a generic assistant, dropping its tool-scope, verification gates, and output contract. Canonical contract: ../../sk-prompt/assets/cli-prompt-quality-card.md "Persona Injection".
- Set
AI_SESSION_CHILD=1 in the dispatched child's env AND state the exemption in the prompt. The variable makes the waiver true. It does not make it observable.
The reader being waived is a model, and a model cannot see an environment variable, so a child given only the variable still stops to ask the documentation-scope question and writes nothing, at exit code zero.
Copy the preamble from shared/references/child-dispatch-preamble.md to the top of every non-interactive prompt.
- Give a build dispatch one change per brief: name the file, the edit, and the check that proves it. A brief that asks the child to read a subsystem before it edits spends its context first.
A DeepSeek V4.1 Flash build brief carrying five changes across five runtime files read about 995,000 characters in 25 minutes and wrote nothing. Chain the changes as separate dispatches and check each diff before sending the next.
- Route a classifier question through Pi's own surfaces:
models.classify() in a codemode script, ctx.modelRegistry.classify() in an extension, or the SDK's ModelRuntime, and leave the credential to Pi's own store.
⛔ NEVER
- Never dispatch when command -v pi fails.
- Never dispatch Pi from inside a fan-out lineage, or when cli-pi already appears in the dispatch stack; the shared runtime refuses both.
- Never build a second Pi adapter inside this packet.
- Never trust exit code alone as proof of model execution.
- Never claim that skill or prompt-template flattening has been live-verified here.
- Never install pi-mcp-extension without explicit package and trust review.
- Never treat community packages as Pi first-party features.
- Never use a bare single-token pi alias in routing metadata.
- Never pass secrets or provider keys in prompts.
- Never read a classifier answer as permission. It is evidence for the caller's decision, and the caller owns the consequence.
⚠️ ESCALATE IF
- Pi is missing from PATH.
- The task needs a successful provider dispatch but no credentials are available.
- The task depends on a native discovery behavior still marked unconfirmed.
- The task requests an install or project-local package change without trust approval.
- The task requests RPC lifecycle behavior that the shared runtime does not yet support.
5. REFERENCES
Core References
- cli-reference.md - Confirmed CLI flags, modes, auth failure behavior, model selection, and command examples
- providers-and-models.md - Authenticated provider/model roster, the
--thinking effort scale, and the GPT-6 and GPT-6.1 Terra ceiling cross-map
- pi-tools.md - Pi capabilities with no sibling analog (RPC, native extensions/prompts, tool surface)
- integration-patterns.md - Conductor/executor patterns, cross-validation, and anti-patterns
- agent-delegation.md - Pi's built-in tool surface and the delegation boundary
- native-skills-and-extensions.md - Pi-native discovery surfaces with confidence labels
- mcp-and-third-party-packages.md - MCP and community package boundaries
Templates and Assets
External Sources
6. SUCCESS CRITERIA
Dispatch Completion
- Pi is present on PATH before launch.
- The selected mode matches the requested output contract.
- Output is captured and checked for auth, extension, and package errors.
- Any workspace changes pass the calling workflow's verification gates.
- Research and review lineages run through the shared deep-loop runtime.
Packet Quality
- References are loaded progressively and remain packet-local.
- Unconfirmed Pi-doc behavior is labeled as unconfirmed.
- Community packages are clearly separated from Pi's first-party CLI.
- No nested advisor identity is introduced under cli-pi.
7. INTEGRATION POINTS
Hub Integration
The hub owns advisor identity, mode registration, and router policy. This packet owns only the Pi workflow contract. The packet must not add description.json or graph-metadata.json.
Deep-Loop Integration
The shared runtime is the sole process adapter. The packet supplies the selected mode, validated prompt, and runtime requirements. Runtime support is a prerequisite for an end-to-end dispatch.
Code and Spec Integration
sk-code owns surface detection and code verification. system-spec-kit owns Gate 3, spec folders, memory, and continuity. Include the parent spec folder in delegated prompts when the workflow has already established one.
Tool Roles
- Bash runs the availability probe and the shared runtime entry point.
- Read, Glob, and Grep inspect prompts, references, and returned changes.
- This packet does not grant new external tools.
8. REFERENCES AND RELATED RESOURCES
The router discovers markdown resources dynamically. Start with the CLI reference and prompt-quality card, then load only the references matching the task. Use prompt-templates.md for repeatable prompt construction.
Related skills: cli-opencode, cli-claude-code, cli-codex, cli-cursor, and cli-devin for sibling CLI dispatch; sk-code for code standards; system-deep-loop for execution; and system-spec-kit for packet handback.
1---2name: cli-pi3description: "Pi CLI executor for guarded headless coding, JSON/RPC integration, native skills/extensions, and community-package delegation."4allowed-tools: [Bash, Read, Glob, Grep]5version: 1.5.22.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/cli-pi8---910# Pi CLI Orchestrator - Cross-AI Task Delegation1112> **A Pi session MAY dispatch this skill.** Pi has no in-process delegation of its own, so the CLI13> is the only way a Pi session can hand work out; being inside Pi is not a reason to refuse.14>15> What still refuses: the shared runtime rejects a dispatch from inside a fan-out lineage, and one16> whose kind already appears in the dispatch stack. Those bound a runaway spawn chain and are17> unchanged. The sibling cli-X packets keep their own guards; this carve-out is Pi's alone.1819Orchestrate Pi's terminal coding agent for headless coding, read-only tool-constrained reviews, JSON event-stream integrations, RPC clients, and Pi-native resource discovery.20The pinned contract is the source for confirmed command behavior: [Pi contract pin](../../../specs/cli-external-orchestration/z_archive/031-cli-pi-creation/001-pi-contract-pin/implementation-summary.md).21Pi-native skills, prompt templates, and some package surfaces remain documented but unconfirmed unless a source says otherwise.2223**Core principle**: use Pi for the surfaces it exposes, delegate research and review lineages to the shared runtime, validate the returned output, and keep the calling AI as conductor.2425---2627## 1. WHEN TO USE2829### Activation Triggers3031- **Headless Pi dispatch**: use when the task explicitly requests Pi, pi.dev, or the Pi coding agent.32- **Cross-AI validation**: use for an independent implementation attempt, code review, or second opinion through Pi.33- **JSON event output**: use when a caller needs Pi's line-delimited event stream.34- **RPC integration**: use when a long-lived stdin/stdout protocol is explicitly requested.35- **Pi-native resources**: use when the task concerns Pi skills, prompt templates, extensions, or installed packages.36- **Community package delegation**: use when the task explicitly names pi-mcp-extension.3738### When NOT to Use3940- Pi is not installed or cannot be found on PATH.41- The task is a small in-process change that the calling AI already understands.42- The task requires a feature that belongs to the shared deep-loop runtime rather than this packet.43- A community package is requested without approval to install or trust project-local files.4445---4647## 2. SMART ROUTING4849The `cli-external-orchestration` hub routes a Pi dispatch here: the request names Pi, pi.dev or the Pi coding agent, or needs Pi's JSON event stream, an RPC client, an independent second opinion, or Pi-native skills, extensions and packages.50`hub-router.json` scores that request, the winning `workflowMode` is `cli-pi`, and the hub loads this `SKILL.md` first.51The hub root `ROUTER.md` names this packet's first leaves, so leaf selection stays in the hub router rather than in this file.52`command -v pi` decides whether the route exists at all, and the probe runs before every dispatch.53It loads `references/cli-reference.md` and `assets/prompt-quality-card.md` first on every run, before any intent selection.54Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5556---5758## 3. HOW IT WORKS5960### Execution Ownership6162This packet owns provider-specific routing, the availability probe, and prompt construction.63For research and review lineages, the shared deep-loop runtime owns process construction and execution. The runtime supports the `cli-pi` executor kind, and its fan-out command builder is implemented with print mode, a provider-qualified `--model`, and `--thinking` from `reasoningEffort`, so a lineage dispatches through the executor kind directly.64That runner accepts only the `research` and `review` loop types, so a single build or doc dispatch uses the child dispatch envelope in [providers-and-models.md](./references/providers-and-models.md) §5.65Do not add a packet-local wrapper, spawn path, or command builder.6667**Five providers are reachable:** `openai` (the ChatGPT sign-in, named `openai-codex` before Pi 1.0), `opencode-go`, `llmgateway` (**DevPass**, the operator's LLM Gateway plan, metered per token with a 3x credit bonus), `minimax` and `mistral` (the operator's Mistral subscription, a Pi builtin, direct dispatch only).68`llmgateway` is not a Pi builtin. It exists only because `.pi/models.json` declares it, and its setup, credentials and removal are in [.pi/custom-providers.md](../../../../.pi/custom-providers.md).6970**Closed roster: non-roster models are FORBIDDEN.** Dispatch ONLY the models in [references/providers-and-models.md](./references/providers-and-models.md) §2. That file is the single place the ids, thinking ceilings and per-provider id shapes are recorded, and this file names the providers without restating their models.71The deep-loop fan-out hard-rejects any off-roster id (`isPiModelAllowed` over `PI_SUPPORTED_MODELS`). Even a direct `pi --model` invocation must not use an unlisted id.72To add a fan-out model, amend the roster and `PI_SUPPORTED_MODELS`; a direct-dispatch-only row needs the roster alone.7374The pinned contract confirms that headless Pi uses print mode, that JSON mode emits JSONL events, and that RPC mode is a persistent JSONL protocol. These are different contracts. Do not treat RPC as a one-shot print invocation. See [cli-reference.md](./references/cli-reference.md) and [integration-patterns.md](./references/integration-patterns.md).7576### Dispatch-Critical Gotchas7778The full flag glossary and pinned-contract citations are in the ALWAYS-loaded [cli-reference.md](./references/cli-reference.md). Gotchas that silently break a dispatch and must be honored at routing time:7980- **Redirect stdin on every non-interactive dispatch: `</dev/null`.** Without it `pi -p` inherits the81 parent terminal's stdin and hangs indefinitely, emitting **nothing at all** — not a partial answer,82 not an error. Because print mode buffers until completion, an empty log is also what a working83 dispatch looks like mid-run, so the deadlock is indistinguishable from a slow model and has been84 mistaken for one for over an hour. The sibling `cli-opencode` packet carries the same rule for85 `opencode run`; it applies here for exactly the same reason.86- **`--offline` is required for any automated or CI dispatch.** `pi --verbose` without `--offline` hung for over two minutes with no reachable network path in the pinned contract's live probe. Any non-interactive dispatch through this packet must pass `--offline` explicitly rather than rely on a fast failure.87- **The exit code is never an availability or auth signal.** An identical unauthenticated `pi -p` dispatch returned exit `0` on the first run and exit `1` on every subsequent run in the pinned contract. Every guard in this packet checks output text (`No API key found...`), never exit code.88- **An invalid `.pi/extensions/*.ts` fails the whole session, not just that extension.** The pinned contract confirmed Pi validates extensions must export a factory function; a broken one blocks the entire dispatch with `Extension does not export a valid factory function` rather than skipping it with a warning.89- **The default provider is `google`, not Anthropic.** `pi --help` documents `--provider <name> (default: google)`. Do not assume an Anthropic-first default when you compose a dispatch that omits `--provider`.90 This repository's `.pi/settings.json` overrides that builtin: `defaultProvider` is `llmgateway` and `defaultModel` is `deepseek-v4.1-flash-1017`, so a run naming no model goes there rather than to `google`.91- **`pi install`/`pi list` require `--approve` to see or modify project-local package config.** Without it, both commands behave as if no packages exist, even when one is installed — the trust gate applies to reads, not only writes.92- **The operator's global Pi packages load in a dispatched child, and pi-blackhole compacts it mid-run.** pi-blackhole's config (`~/.pi/agent/pi-blackhole/pi-blackhole-config.json`) auto-compacts at `compactAfterTokens`, 272,000 here, with `midRunCompaction: "resume"`.93 The compaction replaces everything the child has read with a structural summary, so a child still reading when it fires starts reading again and can loop without ever editing.94 Set `PI_BLACKHOLE_PASSIVE=true` in the child's environment, which the package documents as switching off its background workers and its auto-compaction.95 The deep-loop fan-out's cli-pi environment filter passes this one variable through, so a value exported in the shell that runs the fan-out reaches every Pi child, and any variable outside the filter's list is still stripped.96 Pi's own compaction is off in `.pi/settings.json`, so the child keeps its model's full context window.9798### Dispatch Lifecycle991001. Verify the binary with command -v pi.1012. Classify the request as print, JSON, RPC, read-only tool-constrained review, native-resource inspection, or generation.1023. Compose the prompt using [prompt-quality-card.md](./assets/prompt-quality-card.md).1034. Pass a research or review lineage to the shared deep-loop runtime; run a single build or doc dispatch with the child dispatch envelope in [providers-and-models.md](./references/providers-and-models.md) §5.1045. Capture stdout and stderr separately when the runtime allows it.1056. Validate the output, changed files, and required tests before handback.106107### Headless Modes108109| Requested result | Pi surface | Guardrail |110|---|---|---|111| One prompt and final response | print mode with -p or --print | Inspect output, not exit code alone |112| Structured events | --mode json | Parse one JSON object per line |113| Long-lived integration | --mode rpc | Keep stdin/stdout as a JSONL protocol |114| Read-only review | print mode plus --tools read,grep,find,ls | Treat the tool allowlist as the write boundary |115116The print, JSON, RPC, and tool flags above are from the live help capture and the pinned contract. The read-only pattern is a caller-selected restriction, not a separate Pi plan mode.117118### Provider Preflight119120Pi reports missing provider credentials in output. The pinned contract observed the same failure with different exit codes across otherwise identical invocations. Never use an exit code alone to claim that a dispatch reached a model. If the output reports a missing API key, stop and surface the provider requirement.121122### Native Resources123124Pi's native resource surfaces are documented separately because their discovery behavior is not uniformly live-confirmed:125126- [native-skills-and-extensions.md](./references/native-skills-and-extensions.md) covers skills, prompt templates, and extensions.127- [mcp-and-third-party-packages.md](./references/mcp-and-third-party-packages.md) covers packages, MCP, and community bridges.128- [agent-delegation.md](./references/agent-delegation.md) covers Pi's built-in tool surface and the delegation boundary.129130### Classifier Calls131132Pi carries classifier models that answer a typed question over JSON state instead of chatting. The133classifier types are `choice`, `bool` and `score`, documented in the installed package's134`docs/models.md`. A Pi worker reaches them three ways:135136- a codemode script calls `models.getModelOfType("classifier", provider, id)`, then137 `models.classify(model, { state, questions })`, and needs `"defaultTools": ["+codemode"]` in settings138- an extension calls `ctx.modelRegistry.classify()` and needs no codemode139- the SDK's `ModelRuntime` exposes `create()`, `getModelOfType`, `getAvailableOfType` and `classify`140141Credentials stay in Pi's own store. Pi resolves them from its own configuration, so a classifier call142passes no key, and an answer is evidence for the caller's decision, never permission. When the service143reports token counts, `result.usage` carries them with their cost.144145### Prompt Construction146147The caller remains responsible for task scope, files, acceptance criteria, and verification. Use the prompt templates as scaffolds, not as a substitute for reading the target mode's skill contract. Pass an established spec folder to a non-interactive child when the parent workflow requires it.148149---150151## 4. RULES152153### ✅ ALWAYS1541551. Run command -v pi before every dispatch.1562. Delegate research and review lineages to the shared deep-loop runtime. It rejects every other loop type, so a single build or doc dispatch uses the child dispatch envelope in [providers-and-models.md](./references/providers-and-models.md) §5.1573. Choose print, JSON, or RPC deliberately. RPC is persistent and is not a print-mode alias.1584. Capture and inspect output text for provider and extension failures.1595. Use the prompt-quality card's two-tier precedence rule.1606. Apply the least-permissive tool set that satisfies the task.1617. Validate Pi-generated changes with the repository's code and test gates.1628. Keep the current runtime as conductor and Pi as delegated executor.1639. Treat Pi-native discovery claims as confirmed only when backed by the pinned contract or a linked live documentation page.16410. Compose every dispatch as `{resolved agent persona + task prompt}`, never a bare task. Resolve the persona from the ACTIVE runtime's agent directory (AGENTS.md §9; never hardcode a runtime) and map each subtask to the right agent (code, review, design, deep-research, markdown).165 Core Pi has no native persona surface on `pi -p`, so INLINE the persona block into the payload, because the child cannot resolve agent paths by reference.166 A persona-less leaf runs as a generic assistant, dropping its tool-scope, verification gates, and output contract. Canonical contract: `../../sk-prompt/assets/cli-prompt-quality-card.md` "Persona Injection".16711. Set `AI_SESSION_CHILD=1` in the dispatched child's env AND state the exemption in the prompt. The variable makes the waiver true. It does not make it observable.168 The reader being waived is a model, and a model cannot see an environment variable, so a child given only the variable still stops to ask the documentation-scope question and writes nothing, at exit code zero.169 Copy the preamble from [`shared/references/child-dispatch-preamble.md`](../shared/references/child-dispatch-preamble.md) to the top of every non-interactive prompt.17012. Give a build dispatch one change per brief: name the file, the edit, and the check that proves it. A brief that asks the child to read a subsystem before it edits spends its context first.171 A DeepSeek V4.1 Flash build brief carrying five changes across five runtime files read about 995,000 characters in 25 minutes and wrote nothing. Chain the changes as separate dispatches and check each diff before sending the next.17213. Route a classifier question through Pi's own surfaces: `models.classify()` in a codemode script, `ctx.modelRegistry.classify()` in an extension, or the SDK's `ModelRuntime`, and leave the credential to Pi's own store.173174### ⛔ NEVER1751761. Never dispatch when command -v pi fails.1772. Never dispatch Pi from inside a fan-out lineage, or when cli-pi already appears in the dispatch stack; the shared runtime refuses both.1783. Never build a second Pi adapter inside this packet.1794. Never trust exit code alone as proof of model execution.1805. Never claim that skill or prompt-template flattening has been live-verified here.1816. Never install pi-mcp-extension without explicit package and trust review.1827. Never treat community packages as Pi first-party features.1838. Never use a bare single-token pi alias in routing metadata.1849. Never pass secrets or provider keys in prompts.18510. Never read a classifier answer as permission. It is evidence for the caller's decision, and the caller owns the consequence.186187### ⚠️ ESCALATE IF1881891. Pi is missing from PATH.1902. The task needs a successful provider dispatch but no credentials are available.1913. The task depends on a native discovery behavior still marked unconfirmed.1924. The task requests an install or project-local package change without trust approval.1935. The task requests RPC lifecycle behavior that the shared runtime does not yet support.194195---196197## 5. REFERENCES198199### Core References200201- [cli-reference.md](./references/cli-reference.md) - Confirmed CLI flags, modes, auth failure behavior, model selection, and command examples202- [providers-and-models.md](./references/providers-and-models.md) - Authenticated provider/model roster, the `--thinking` effort scale, and the GPT-6 and GPT-6.1 Terra ceiling cross-map203- [pi-tools.md](./references/pi-tools.md) - Pi capabilities with no sibling analog (RPC, native extensions/prompts, tool surface)204- [integration-patterns.md](./references/integration-patterns.md) - Conductor/executor patterns, cross-validation, and anti-patterns205- [agent-delegation.md](./references/agent-delegation.md) - Pi's built-in tool surface and the delegation boundary206- [native-skills-and-extensions.md](./references/native-skills-and-extensions.md) - Pi-native discovery surfaces with confidence labels207- [mcp-and-third-party-packages.md](./references/mcp-and-third-party-packages.md) - MCP and community package boundaries208209### Templates and Assets210211- [prompt-quality-card.md](./assets/prompt-quality-card.md) - Thin delegator to the canonical prompt-models card212- [prompt-templates.md](./assets/prompt-templates.md) - Print, JSON, RPC, review, and generation scaffolds213214### External Sources215216- [Pi contract pin](../../../specs/cli-external-orchestration/z_archive/031-cli-pi-creation/001-pi-contract-pin/implementation-summary.md) - Local live-verification evidence217- [Pi skills documentation](https://pi.dev/docs/latest/skills) - Documentation-only native skill surface218- [Pi RPC documentation](https://pi.dev/docs/latest/rpc) - Documentation-only RPC surface219- [Pi JSON documentation](https://pi.dev/docs/latest/json) - Documentation-only JSON event stream220221---222223## 6. SUCCESS CRITERIA224225### Dispatch Completion226227- Pi is present on PATH before launch.228- The selected mode matches the requested output contract.229- Output is captured and checked for auth, extension, and package errors.230- Any workspace changes pass the calling workflow's verification gates.231- Research and review lineages run through the shared deep-loop runtime.232233### Packet Quality234235- References are loaded progressively and remain packet-local.236- Unconfirmed Pi-doc behavior is labeled as unconfirmed.237- Community packages are clearly separated from Pi's first-party CLI.238- No nested advisor identity is introduced under cli-pi.239240---241242## 7. INTEGRATION POINTS243244### Hub Integration245246The hub owns advisor identity, mode registration, and router policy. This packet owns only the Pi workflow contract. The packet must not add description.json or graph-metadata.json.247248### Deep-Loop Integration249250The shared runtime is the sole process adapter. The packet supplies the selected mode, validated prompt, and runtime requirements. Runtime support is a prerequisite for an end-to-end dispatch.251252### Code and Spec Integration253254sk-code owns surface detection and code verification. system-spec-kit owns Gate 3, spec folders, memory, and continuity. Include the parent spec folder in delegated prompts when the workflow has already established one.255256### Tool Roles257258- Bash runs the availability probe and the shared runtime entry point.259- Read, Glob, and Grep inspect prompts, references, and returned changes.260- This packet does not grant new external tools.261262---263264## 8. REFERENCES AND RELATED RESOURCES265266The router discovers markdown resources dynamically. Start with the CLI reference and prompt-quality card, then load only the references matching the task. Use [prompt-templates.md](./assets/prompt-templates.md) for repeatable prompt construction.267268Related skills: cli-opencode, cli-claude-code, cli-codex, cli-cursor, and cli-devin for sibling CLI dispatch; sk-code for code standards; system-deep-loop for execution; and system-spec-kit for packet handback.