Cli Pi

Pi CLI Orchestrator - Cross-AI Task Delegation

> CRITICAL — SELF-INVOCATION PROHIBITED > > This skill dispatches to the Pi CLI binary, pi. If the agent reading this skill is already running inside Pi, refuse to construct a Pi invocation. > > A running CLI skill never dispatches itself. The cli-X skills are for cross-AI delegation only.

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](../../../specs/cli-external-orchestration/031-cli-pi-creation/001-pi-contract-pin/implementation-summary.md). 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 execution 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-subagents or pi-mcp-extension.

When NOT to Use

• You ARE Pi already. Refuse if process ancestry indicates a Pi process or the local project heuristic indicates an active Pi context. The guard is intentionally conservative.
• 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

Prerequisite Detection

Run this probe before every dispatch. Do not build a command when it fails.

~~~bash command -v pi || echo "Not installed. Install @earendil-works/pi-coding-agent before dispatch." ~~~

The pinned contract confirms the binary version used for the contract run and the headless entry point. For exact flags and observed failure behavior, load [cli-reference.md](./references/cli-reference.md).

Self-Invocation Guard

Use the following guard before loading a dispatch template:

~~~python def detectselfinvocation(): """Return a signal when the caller is likely already inside Pi.""" # Process ancestry is a documented-but-unconfirmed signal for this packet. try: ancestry = subprocess.check_output( ["ps", "-o", "command=", "-p", str(os.getppid())], text=True, ) if "/pi" in ancestry or ancestry.strip().endswith(" pi"): return ("ancestry", "pi") except (OSError, subprocess.SubprocessError): pass

# The .pi directory is a non-conclusive project heuristic, not proof of an active session. if os.path.isdir(os.path.join(os.getcwd(), ".pi")): return ("project-heuristic", ".pi")

# No first-party environment signal is treated as confirmed here. Absence of a # detected signal is not proof that no Pi session is active. return None

signal = detectselfinvocation() if signal: refuse( "Self-invocation refused: the caller may already be running inside Pi. " "Use a different runtime or a fresh shell session." ) ~~~

The guard deliberately uses only process ancestry and the non-conclusive project heuristic. It does not invent an environment variable or infer safety from a missing signal.

Resource Loading Levels

| Level | Load when | Resources | |---|---|---| | ALWAYS | Every Pi route | references/cli-reference.md, assets/prompt-quality-card.md | | CONDITIONAL | Task names the matching surface | One or more intent-mapped references | | ON_DEMAND | The operator asks for templates or package detail | assets/prompt-templates.md, native-skills-and-extensions.md, mcp-and-third-party-packages.md |

Smart Router

Provider-specific dictionaries (used by the shared helper functions in [system-spec-kit/references/cli/shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md)):

INTENT_SIGNALS = {
    "GENERATION": {"weight": 4, "keywords": ["generate", "create", "build", "write code", "pi coding agent"]},
    "REVIEW": {"weight": 4, "keywords": ["review", "audit", "bug", "second opinion", "cross-validate"]},
    "HEADLESS": {"weight": 4, "keywords": ["pi cli", "pi agent", "headless", "print mode", "json event"]},
    "RPC": {"weight": 4, "keywords": ["rpc", "stdin", "stdout", "jsonl", "persistent process"]},
    "AGENT_DELEGATION": {"weight": 4, "keywords": ["delegate", "subagent", "pi-subagents", "agent bridge"]},
    "NATIVE_RESOURCES": {"weight": 4, "keywords": ["skill", "prompt template", "extension", "pi-mcp-extension", "package"]},
    "PATTERNS": {"weight": 3, "keywords": ["pattern", "workflow", "session", "resume", "continue"]},
    "TEMPLATES": {"weight": 3, "keywords": ["template", "prompt", "how to ask", "pi prompt"]},
}

RESOURCE_MAP = {
    "GENERATION": ["references/cli-reference.md", "assets/prompt-templates.md"],
    "REVIEW": ["references/integration-patterns.md", "references/cli-reference.md"],
    "HEADLESS": ["references/cli-reference.md", "assets/prompt-templates.md"],
    "RPC": ["references/cli-reference.md", "references/integration-patterns.md"],
    "AGENT_DELEGATION": ["references/agent-delegation.md", "references/integration-patterns.md"],
    "NATIVE_RESOURCES": ["references/native-skills-and-extensions.md", "references/mcp-and-third-party-packages.md"],
    "PATTERNS": ["references/integration-patterns.md", "references/cli-reference.md"],
    "TEMPLATES": ["assets/prompt-templates.md", "assets/prompt-quality-card.md"],
}

LOADING_LEVELS = {
    "ALWAYS": ["references/cli-reference.md", "assets/prompt-quality-card.md"],
    "ON_DEMAND_KEYWORDS": ["full reference", "all templates", "deep dive", "mcp extension", "subagent package", "native skills"],
    "ON_DEMAND": ["references/native-skills-and-extensions.md", "references/mcp-and-third-party-packages.md", "assets/prompt-templates.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm that the user wants Pi rather than another cli-X mode",
    "Confirm whether the task is print, JSON, RPC, or interactive",
    "Confirm whether project-local resources may be trusted",
    "Confirm the required verification command before dispatch",
]

Call sequence (using shared helpers from shared-smart-router.md):

1. discover_markdown_resources() — recursively enumerate current .md files under existing references/ and assets/ folders at routing time.
2. _guard_in_skill() + load_if_available() — sandbox paths to this skill, reject non-markdown loads, skip missing files, and suppress duplicates.
3. score_intents(task) and select_intents(scores, ambiguity_delta=1.0) — preserve provider-specific weighted intent scoring and top-2 ambiguity handling.
4. get_routing_key(task, intents) — derive the provider routing key from task/provider context, then fall back to cli-pi.
5. ALWAYS-load LOADING_LEVELS["ALWAYS"], then return UNKNOWN_FALLBACK with UNKNOWN_FALLBACK_CHECKLIST when max score is 0.
6. CONDITIONAL-load RESOURCE_MAP[intent], ON_DEMAND-load keyword matches, and return a notice when no provider-specific knowledge base is available beyond always-load resources.

The route_pi_resources(task) function body lives in [shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md) — substitute ` = pi`.

---

3. HOW IT WORKS

Execution Ownership

This packet owns provider-specific routing, the availability probe, prompt construction, and the self-invocation guard. The shared deep-loop runtime owns process construction and execution. The runtime now supports the cli-pi executor kind — its fan-out command builder is implemented (print mode, provider-qualified --model, --thinking from reasoningEffort), so dispatch through the executor kind directly. Do not add a packet-local wrapper, spawn path, or command builder.

Closed roster — non-roster models are FORBIDDEN. Dispatch ONLY the models in [references/providers-and-models.md](./references/providers-and-models.md) §2. 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 model, amend the roster (spec packet + PI_SUPPORTED_MODELS) first.

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](./references/cli-reference.md) and [integration-patterns.md](./references/integration-patterns.md).

Dispatch Lifecycle

1. Verify the binary with command -v pi.
2. Run the self-invocation guard.
3. Classify the request as print, JSON, RPC, read-only tool-constrained review, native-resource inspection, or generation.
4. Compose the prompt using [prompt-quality-card.md](./assets/prompt-quality-card.md).
5. Pass the request to the shared deep-loop runtime.
6. Capture stdout and stderr separately when the runtime allows it.
7. 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:

• [native-skills-and-extensions.md](./references/native-skills-and-extensions.md) covers skills, prompt templates, and extensions.
• [mcp-and-third-party-packages.md](./references/mcp-and-third-party-packages.md) covers packages, MCP, and community bridges.
• [agent-delegation.md](./references/agent-delegation.md) distinguishes built-in tools from community subagent packages.

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.

Dispatch-Critical Gotchas

The 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:

• **Redirect stdin on every non-interactive dispatch: (default: google). Do not assume an Anthropic-first default when composing a dispatch that omits --provider.
• 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.

---

4. RULES

✅ ALWAYS

1. Run command -v pi before every dispatch.
2. Run the self-invocation guard before constructing a command.
3. Delegate execution to the shared deep-loop runtime.
4. Choose print, JSON, or RPC deliberately. RPC is persistent and is not a print-mode alias.
5. Capture and inspect output text for provider and extension failures.
6. Use the prompt-quality card's two-tier precedence rule.
7. Apply the least-permissive tool set that satisfies the task.
8. Validate Pi-generated changes with the repository's code and test gates.
9. Keep the current runtime as conductor and Pi as delegated executor.
10. Treat Pi-native discovery claims as confirmed only when backed by the pinned contract or a linked live documentation page.
11. 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 §7; 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 — 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".

⛔ NEVER

1. Never dispatch when command -v pi fails.
2. Never dispatch Pi from a Pi session detected by the guard.
3. Never build a second Pi adapter inside this packet.
4. Never trust exit code alone as proof of model execution.
5. Never claim that skill or prompt-template flattening has been live-verified here.
6. Never install pi-subagents or pi-mcp-extension without explicit package and trust review.
7. Never treat community packages as Pi first-party features.
8. Never use a bare single-token pi alias in routing metadata.
9. Never pass secrets or provider keys in prompts.

⚠️ ESCALATE IF

1. Pi is missing from PATH.
2. The self-invocation guard detects ancestry or the .pi heuristic.
3. The task needs a successful provider dispatch but no credentials are available.
4. The task depends on a native discovery behavior still marked unconfirmed.
5. The task requests an install or project-local package change without trust approval.
6. The task requests RPC lifecycle behavior that the shared runtime does not yet support.

---

5. REFERENCES

Core References

• [cli-reference.md](./references/cli-reference.md) - Confirmed CLI flags, modes, auth failure behavior, model selection, and command examples
• [providers-and-models.md](./references/providers-and-models.md) - Authenticated provider/model roster, the --thinking effort scale, and the GPT-5.6 ceiling cross-map
• [pi-tools.md](./references/pi-tools.md) - Pi capabilities with no sibling analog (RPC, native extensions/prompts, tool surface)
• [integration-patterns.md](./references/integration-patterns.md) - Conductor/executor patterns, cross-validation, and anti-patterns
• [agent-delegation.md](./references/agent-delegation.md) - Built-in boundary and community subagent package guidance
• [native-skills-and-extensions.md](./references/native-skills-and-extensions.md) - Pi-native discovery surfaces with confidence labels
• [mcp-and-third-party-packages.md](./references/mcp-and-third-party-packages.md) - MCP and community package boundaries

Templates and Assets

• [prompt-quality-card.md](./assets/prompt-quality-card.md) - Thin delegator to the canonical prompt-models card
• [prompt-templates.md](./assets/prompt-templates.md) - Print, JSON, RPC, review, and generation scaffolds

External So

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

Install and usage instructions live in the source repository linked above.