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 — 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.
Edit this page