Add support for Pi (pi.dev)

[carlosapgomes]

Hey! I'd love to see OpenSpec work with Pi (https://pi.dev), a minimal terminal coding agent I've been using. It's built around the Agent Skills standard, so it should fit nicely with OpenSpec's existing skill files.

What Pi supports:

• Skills in .pi/skills/ (same spec as OpenSpec already uses)
• Prompt templates in .pi/prompts/ that become /commands

My plan:

Add Pi to the tools list with both skills and prompt template support. The adapter would generate files to .pi/prompts/opsx-{command}.md so users can type /opsx-new, /opsx-apply, etc.

Skills would still work via /skill:openspec-* for anyone who prefers that, but the prompt templates give a smoother experience.

Quick example of what Pi expects:

  ---
  description: Start a new OpenSpec change
  ---

  Create a new change following the OpenSpec workflow...

Happy to submit a PR if this sounds good. Just wanted to check the approach first.

Carlos.

[1code-async]

Task completed.

The enrichment comment has been posted on issue #732. Here's a summary of what was included:

Key findings:

• Not a duplicate — no existing Pi support anywhere in the codebase. Issue Add support for oh-my-pi agent toolkit #713 (oh-my-pi) is a different tool.
• Clean fit — Pi's .pi/prompts/ with YAML frontmatter (description only) maps almost identically to the existing Kiro adapter pattern, making this one of the simplest adapter types to implement.

Implementation guide provided:

1. Create src/core/command-generation/adapters/pi.ts (with example code based on the Kiro adapter)
2. Export from adapters/index.ts
3. Register in registry.ts
4. Add tool definition to config.ts (AI_TOOLS array)
5. Add tests to adapters.test.ts
6. Update docs/supported-tools.md

Design notes: Confirmed the opsx-{command} naming convention aligns with other tools, and flagged issue #727 (active bug around command naming) as something to verify against.

Comment: #732 (comment)

---

View full conversation

Powered by 1Code

[1code-async]

Codebase Analysis & Implementation Guide

Thanks for the detailed proposal, @carlosapgomes! Here's a breakdown of what's needed based on the current codebase architecture.

Not a Duplicate

No existing Pi support exists in the codebase. There are no adapters, config entries, or prior work related to Pi. Issue #713 ("Add support for oh-my-pi agent toolkit") is a different tool.

Architecture Overview

OpenSpec uses a well-established adapter pattern for tool support. Each tool requires changes in 6 files. Based on Pi's description (skills in .pi/skills/, prompts in .pi/prompts/), this maps cleanly to the existing pattern — very similar to the Kiro adapter which also uses a prompts/ directory with description-only frontmatter.

Files to Modify/Create

Here's the complete checklist:

1. Create the adapter — src/core/command-generation/adapters/pi.ts (new file)

Pi's prompt format (description frontmatter + markdown body) matches the pattern in kiro.ts:15-30 almost exactly. A Pi adapter would look like:

import path from 'path';
import type { CommandContent, ToolCommandAdapter } from '../types.js';

export const piAdapter: ToolCommandAdapter = {
  toolId: 'pi',

  getFilePath(commandId: string): string {
    return path.join('.pi', 'prompts', `opsx-${commandId}.md`);
  },

  formatFile(content: CommandContent): string {
    return `---
description: ${content.description}
---

${content.body}
`;
  },
};

The ToolCommandAdapter interface is defined at src/core/command-generation/types.ts:32-48 — just toolId, getFilePath(), and formatFile().

2. Export from adapter index — src/core/command-generation/adapters/index.ts

Add: export { piAdapter } from './pi.js'; (see line 29)

3. Register in the registry — src/core/command-generation/registry.ts

• Add import: import { piAdapter } from './adapters/pi.js'; (after line 30)
• Add registration: CommandAdapterRegistry.register(piAdapter); in the static block (after line 61)

4. Add tool definition — src/core/config.ts

Add entry to the AI_TOOLS array (line 20-45):

{ name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },

5. Add tests — test/core/command-generation/adapters.test.ts

Follow the existing test pattern (starts at line 27) — test toolId, getFilePath(), and formatFile().

6. Update docs — docs/supported-tools.md

Add Pi to the tool directory table (line 14-38) and the tool IDs list (line 59).

Design Considerations

On the proposed /opsx-{command} naming: The approach of generating to .pi/prompts/opsx-{command}.md aligns with how most other tools work (Kiro, Amazon Q, GitHub Copilot all use the opsx- prefix). This is the right call.

Skills vs. Commands delivery: OpenSpec supports a delivery mode ('both', 'skills', 'commands') via global config (src/core/global-config.ts). Since Pi supports both skills (.pi/skills/) and prompt templates (.pi/prompts/), the 'both' mode will work naturally — skills go to .pi/skills/openspec-*/SKILL.md and commands go to .pi/prompts/opsx-*.md.

No special handling needed: Unlike Codex (global scope) or Qwen (TOML format), Pi uses standard project-scoped markdown with YAML frontmatter — the simplest adapter type.

Related Issues

• Add support for oh-my-pi agent toolkit #713 — "Add support for oh-my-pi agent toolkit" (different tool, but similar adapter work)
• Proposal: use a standard .agent/skills folder for all agents that support it #689 — "Proposal: use a standard .agent/skills folder for all agents" (relevant to skills directory conventions)
• [Bug Report] prompts and skills are not exact compatible with commands like "/opsx-new" in version 1.1.1 #727 — "Prompts and skills not compatible with /opsx-new commands" (active bug around command naming — worth verifying Pi prompt invocation works)