---
type: "ADR"
title: "Pi agent is skill-only: no prompt templates, invoker deferred"
description: "Pi ships skill-only via `.agents/skills/`; no `.pi/prompts/` templates, and PiInvoker waits for the external orchestrator package."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-06-02T00:00:00Z"
---

## Context and Problem Statement

Pi (`pi-coding-agent`) is a terminal coding harness that supports non-interactive automation via `pi -p`, JSON event streaming via `pi --mode json`, and an RPC mode. The design spike (#1050) raised three questions:

1. Should Pi be skill-only, prompt-template-based, orchestrator-enabled, or all three?
2. Is `pi --mode json` reliable enough for extracting structured results in automated WP cycles?
3. Does generating `.pi/prompts/` slash-command templates add value beyond what Agent Skills already provide?

## Decision Drivers

* Pi natively discovers `.agents/skills/` without any extra configuration — skills are available to Pi users immediately after `spec-kitty init --ai pi`.
* Agent Skills provide identical skill content across all shared-root agents (codex, vibe, pi, letta), avoiding per-agent duplication.
* An orchestrator invoker (`PiInvoker`) belongs in the external `spec-kitty-orchestrator` package, not in this CLI.
* Generating `.pi/prompts/` templates would require a dedicated migration and yield minimal additional value, since Pi users can invoke skills directly without a separate prompt template layer.
* The reliability of `pi --mode json` for structured result extraction has not been validated in a live prototype; committing to a full integration before that validation carries risk.

## Considered Options

* **Option A:** Skill-only — `.agents/skills/spec-kitty.*/SKILL.md` only; no `.pi/prompts/` templates.
* **Option B:** Skills + prompt templates — `.agents/skills/` plus `.pi/prompts/spec-kitty.<command>.md` generated by a new migration.
* **Option C:** Full support — skills + prompt templates + `PiInvoker` in `spec-kitty-orchestrator`, enabling `spec-kitty next --agent pi`.

## Decision Outcome

**Chosen option:** "Option A — skill-only", because Pi discovers `.agents/skills/` natively and the incremental value of prompt templates is unclear without a live prototype. Adding a new migration for `.pi/prompts/` at this stage would front-load complexity before the value is proven.

`PiInvoker` is deferred to the external `spec-kitty-orchestrator` package scope. This decision can be revisited once `pi --mode json` reliability is validated in practice.

### Consequences

#### Positive

* No new migration required; Pi users get skills immediately via `spec-kitty init --ai pi`.
* `AGENT_SKILL_CONFIG` includes `pi`, so skill packages are installed and kept in sync.
* `.pi/` gitignore entry prevents runtime state and session logs from polluting the repository.
* `spec-kitty agent config add pi` is fully supported.

#### Negative

* `spec-kitty next --agent pi` is not supported without `spec-kitty-orchestrator`.
* `.pi/prompts/` is intentionally absent; Pi users cannot use prompt-template-style invocation via spec-kitty.

#### Neutral

* `AGENT_COMMAND_CONFIG` does not include `pi` — this is by design, not an oversight.
* The `pi --mode json` reliability question is left open; a follow-up ADR should be written when a prototype is available.

### Confirmation

This decision is correct if Pi users can successfully run Spec Kitty work packages using `.agents/skills/` discovery without encountering errors related to missing prompt templates. The absence of `pi` from `AGENT_COMMAND_CONFIG` is confirmed by `test_twelve_agent_parity.py:203`.

## Pros and Cons of the Options

### Option A — Skill-only

Skills only; Pi reads `.agents/skills/spec-kitty.*/SKILL.md` natively.

**Pros:**

* Zero new migrations needed.
* Immediate value: skills install on `spec-kitty init --ai pi`.
* Consistent with how codex and letta are integrated.

**Cons:**

* No prompt-template fallback for Pi users who prefer that surface.
* `spec-kitty next --agent pi` remains unsupported until `spec-kitty-orchestrator` adds `PiInvoker`.

### Option B — Skills + prompt templates

Skills plus `.pi/prompts/` generated via a new migration.

**Pros:**

* Users who prefer prompt-template invocation can use that surface.

**Cons:**

* Requires a new migration for a surface whose value is unproven.
* Doubles the maintenance surface (skills + templates must stay in sync).

### Option C — Full support

Skills + prompt templates + `PiInvoker` with `spec-kitty next --agent pi`.

**Pros:**

* Complete first-class integration.

**Cons:**

* `PiInvoker` belongs in `spec-kitty-orchestrator`, not in this CLI package.
* `pi --mode json` reliability is unvalidated; building on it prematurely creates fragile automation.
* Largest scope; highest risk.

## More Information

* Implementation evidence: `src/specify_cli/upgrade/config.py:84` shows `pi` in `AGENT_SKILL_CONFIG`; `tests/specify_cli/test_twelve_agent_parity.py:203` confirms `pi` absent from `AGENT_COMMAND_CONFIG`.
* Related ADR: [2026-06-02-2-letta-agent-skill-only-support.md](/adr/3.x/2026-06-02-2-letta-agent-skill-only-support.md) — same pattern applied to Letta Code.
* Tests: `tests/specify_cli/cli/commands/test_init_pi_letta.py`, `tests/specify_cli/cli/commands/test_agent_config_pi_letta.py`.
