<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-02-1-pi-agent-skill-only-support/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-02-1-pi-agent-skill-only-support/</id>
  <title>Pi agent is skill-only: no prompt templates, invoker deferred</title>
  <updated>2026-06-02T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-02-1-pi-agent-skill-only-support/"/>
  <summary>Pi ships skill-only via `.agents/skills/`; no `.pi/prompts/` templates, and PiInvoker waits for the external orchestrator package.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Pi (&lt;code dir=&quot;auto&quot;&gt;pi-coding-agent&lt;/code&gt;) is a terminal coding harness that supports non-interactive automation via &lt;code dir=&quot;auto&quot;&gt;pi -p&lt;/code&gt;, JSON event streaming via &lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt;, and an RPC mode. The design spike (#1050) raised three questions:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Should Pi be skill-only, prompt-template-based, orchestrator-enabled, or all three?&lt;/li&gt;
&lt;li&gt;Is &lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt; reliable enough for extracting structured results in automated WP cycles?&lt;/li&gt;
&lt;li&gt;Does generating &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; slash-command templates add value beyond what Agent Skills already provide?&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Pi natively discovers &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; without any extra configuration — skills are available to Pi users immediately after &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --ai pi&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Agent Skills provide identical skill content across all shared-root agents (codex, vibe, pi, letta), avoiding per-agent duplication.&lt;/li&gt;
&lt;li&gt;An orchestrator invoker (&lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt;) belongs in the external &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; package, not in this CLI.&lt;/li&gt;
&lt;li&gt;Generating &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; templates would require a dedicated migration and yield minimal additional value, since Pi users can invoke skills directly without a separate prompt template layer.&lt;/li&gt;
&lt;li&gt;The reliability of &lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt; for structured result extraction has not been validated in a live prototype; committing to a full integration before that validation carries risk.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A:&lt;/strong&gt; Skill-only — &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.*/SKILL.md&lt;/code&gt; only; no &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; templates.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Skills + prompt templates — &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; plus &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/spec-kitty.&amp;#x3C;command&gt;.md&lt;/code&gt; generated by a new migration.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Full support — skills + prompt templates + &lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;, enabling &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent pi&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option A — skill-only”, because Pi discovers &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; natively and the incremental value of prompt templates is unclear without a live prototype. Adding a new migration for &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; at this stage would front-load complexity before the value is proven.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt; is deferred to the external &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; package scope. This decision can be revisited once &lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt; reliability is validated in practice.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;No new migration required; Pi users get skills immediately via &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --ai pi&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AGENT_SKILL_CONFIG&lt;/code&gt; includes &lt;code dir=&quot;auto&quot;&gt;pi&lt;/code&gt;, so skill packages are installed and kept in sync.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.pi/&lt;/code&gt; gitignore entry prevents runtime state and session logs from polluting the repository.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config add pi&lt;/code&gt; is fully supported.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent pi&lt;/code&gt; is not supported without &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; is intentionally absent; Pi users cannot use prompt-template-style invocation via spec-kitty.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; does not include &lt;code dir=&quot;auto&quot;&gt;pi&lt;/code&gt; — this is by design, not an oversight.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt; reliability question is left open; a follow-up ADR should be written when a prototype is available.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is correct if Pi users can successfully run Spec Kitty work packages using &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; discovery without encountering errors related to missing prompt templates. The absence of &lt;code dir=&quot;auto&quot;&gt;pi&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; is confirmed by &lt;code dir=&quot;auto&quot;&gt;test_twelve_agent_parity.py:203&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a--skill-only&quot;&gt;Option A — Skill-only&lt;/h3&gt;
&lt;p&gt;Skills only; Pi reads &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.*/SKILL.md&lt;/code&gt; natively.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero new migrations needed.&lt;/li&gt;
&lt;li&gt;Immediate value: skills install on &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --ai pi&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Consistent with how codex and letta are integrated.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No prompt-template fallback for Pi users who prefer that surface.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent pi&lt;/code&gt; remains unsupported until &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; adds &lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b--skills--prompt-templates&quot;&gt;Option B — Skills + prompt templates&lt;/h3&gt;
&lt;p&gt;Skills plus &lt;code dir=&quot;auto&quot;&gt;.pi/prompts/&lt;/code&gt; generated via a new migration.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Users who prefer prompt-template invocation can use that surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires a new migration for a surface whose value is unproven.&lt;/li&gt;
&lt;li&gt;Doubles the maintenance surface (skills + templates must stay in sync).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-c--full-support&quot;&gt;Option C — Full support&lt;/h3&gt;
&lt;p&gt;Skills + prompt templates + &lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent pi&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Complete first-class integration.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;PiInvoker&lt;/code&gt; belongs in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;, not in this CLI package.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pi --mode json&lt;/code&gt; reliability is unvalidated; building on it prematurely creates fragile automation.&lt;/li&gt;
&lt;li&gt;Largest scope; highest risk.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Implementation evidence: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/config.py:84&lt;/code&gt; shows &lt;code dir=&quot;auto&quot;&gt;pi&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;AGENT_SKILL_CONFIG&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_twelve_agent_parity.py:203&lt;/code&gt; confirms &lt;code dir=&quot;auto&quot;&gt;pi&lt;/code&gt; absent from &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Related ADR: &lt;a href=&quot;/adr/3.x/2026-06-02-2-letta-agent-skill-only-support/&quot;&gt;2026-06-02-2-letta-agent-skill-only-support.md&lt;/a&gt; — same pattern applied to Letta Code.&lt;/li&gt;
&lt;li&gt;Tests: &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/test_init_pi_letta.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/test_agent_config_pi_letta.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
