docs(pi): implement milestone M1 - research and shared docs
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,89 @@
|
||||
# PI RESEARCH
|
||||
|
||||
## Scope
|
||||
|
||||
This document records the pi-specific findings that drive the `pi` variants in this repo. It is intentionally source-backed so later skill work does not rely on memory or assumptions.
|
||||
|
||||
Checked on `2026-04-23`.
|
||||
|
||||
## Primary Sources
|
||||
|
||||
- [pi skills documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
|
||||
- [pi packages documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/packages.md)
|
||||
- [pi extensions documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)
|
||||
- [pi settings documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/settings.md)
|
||||
- [pi coding-agent README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)
|
||||
|
||||
## Findings
|
||||
|
||||
### Skill Discovery
|
||||
|
||||
Pi loads skills from multiple places:
|
||||
|
||||
- global skill roots: `~/.pi/agent/skills/` and `~/.agents/skills/`
|
||||
- project skill roots: `.pi/skills/` and `.agents/skills/`
|
||||
- package resources: `skills/` convention directories or `pi.skills` entries in `package.json`
|
||||
- settings-provided skill paths
|
||||
- explicit `--skill <path>` CLI arguments
|
||||
|
||||
Important discovery details from the skills docs:
|
||||
|
||||
- directories containing `SKILL.md` are discovered recursively
|
||||
- top-level `.md` files are loaded as skills in pi-native roots like `.pi/skills/`
|
||||
- per the upstream skills docs, top-level `.md` files are ignored in `.agents/skills/`
|
||||
|
||||
Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly, both for local copies and for package-based installs.
|
||||
|
||||
### Package Support
|
||||
|
||||
Pi packages are a first-class distribution path. The package docs say pi can load resources through conventional directories like `skills/`, or through explicit `pi` manifest entries in `package.json`.
|
||||
|
||||
Relevant package behaviors:
|
||||
|
||||
- `keywords: ["pi-package"]` makes packages show up in the gallery
|
||||
- `pi.skills` can point at specific skill directories
|
||||
- `files` allowlists should be used to keep tarballs tight
|
||||
- installed pi packages can also ship `extensions/`, `prompts/`, and `themes/`
|
||||
- when pi installs npm or git packages, it runs `npm install`
|
||||
|
||||
Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the pi resources.
|
||||
|
||||
### Settings And Path Overrides
|
||||
|
||||
Pi settings support `packages`, `extensions`, `skills`, `prompts`, and `themes`. In both `~/.pi/agent/settings.json` and `.pi/settings.json`, the `skills` array can point to local files or directories, and the docs explicitly allow absolute paths and `~`.
|
||||
|
||||
Implication for this repo:
|
||||
|
||||
- pi can consume repo-local resources without publishing a package
|
||||
- users can point pi at shared roots like `~/.agents/skills`
|
||||
- workflow skills can document deterministic helper paths and fall back to settings-driven installs when needed
|
||||
|
||||
### Extensions
|
||||
|
||||
Pi extensions are TypeScript modules that can:
|
||||
|
||||
- register custom tools
|
||||
- register commands
|
||||
- intercept lifecycle events and tool calls
|
||||
- add UI interactions and custom components
|
||||
- persist session state
|
||||
|
||||
The coding-agent README explicitly lists advanced behaviors like sub-agents, plan mode, permission gates, MCP integration, and git checkpointing as extension-capable areas.
|
||||
|
||||
Implication for this repo: extensions are a real opportunity for workflow-heavy skills, but they are optional for the initial skill port. The base skill variants should remain usable without any extension dependency.
|
||||
|
||||
### Cross-Harness Compatibility
|
||||
|
||||
The pi skills docs explicitly call out `~/.agents/skills/` as a supported global skill root, and describe adding Codex or Claude skill directories through settings when needed.
|
||||
|
||||
Implication for this repo:
|
||||
|
||||
- existing Superpowers installs exposed through `~/.agents/skills/` can already be visible to pi
|
||||
- pi-specific skill variants still need their own instructions because pi does not share Codex's `update_plan`, plan-mode, or worktree assumptions
|
||||
|
||||
## Decisions Derived From Research
|
||||
|
||||
- Use `skills/<skill>/pi/` for all five skill families.
|
||||
- Publish shared pi guidance in repo docs instead of burying pi assumptions inside each skill.
|
||||
- Use one repo-level pi package in v1.
|
||||
- Assess extensions explicitly, but defer them unless they provide clear v1 value beyond documentation and helper scripts.
|
||||
@@ -0,0 +1,84 @@
|
||||
# PI SUPERPOWERS
|
||||
|
||||
## Purpose
|
||||
|
||||
The pi workflow variants in this repo depend on two shared pieces of setup:
|
||||
|
||||
- Obra Superpowers skills
|
||||
- reviewer-runtime helper scripts
|
||||
|
||||
This guide documents how to make both available to pi without inventing skill-specific setup instructions in three different workflow docs.
|
||||
|
||||
## Superpowers Setup
|
||||
|
||||
Pi can load skills from `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, `.agents/skills/`, package manifests, and settings-defined skill paths. Because of that, there are two supported ways to expose Obra Superpowers to pi.
|
||||
|
||||
### Option 1: Reuse `~/.agents/skills/`
|
||||
|
||||
If you already expose Superpowers through a shared root such as:
|
||||
|
||||
```bash
|
||||
~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
|
||||
```
|
||||
|
||||
pi can discover those skill directories directly. This is only an example path, not a requirement; any shared skill root that pi can read is fine. It is simply the easiest path when Codex and pi share the same machine.
|
||||
|
||||
### Option 2: Add An Explicit Pi Settings Entry
|
||||
|
||||
If you want pi to load a different path, add it in either `~/.pi/agent/settings.json` or `.pi/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
"~/.agents/skills",
|
||||
"/absolute/path/to/obra/superpowers/skills"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Use this when the shared `~/.agents/skills/` root is missing or when you want a pi-specific override.
|
||||
|
||||
## Reviewer Runtime Setup
|
||||
|
||||
The workflow-heavy pi variants expect the helper scripts from `skills/reviewer-runtime/pi/` to be installed in one of these locations:
|
||||
|
||||
1. `.pi/skills/reviewer-runtime/pi/`
|
||||
2. `~/.pi/agent/skills/reviewer-runtime/pi/`
|
||||
|
||||
Supported helper files:
|
||||
|
||||
- `run-review.sh`
|
||||
- `notify-telegram.sh`
|
||||
|
||||
Example global install:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
|
||||
cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
|
||||
chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh
|
||||
```
|
||||
|
||||
Example project-local install:
|
||||
|
||||
```bash
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
|
||||
chmod +x .pi/skills/reviewer-runtime/pi/*.sh
|
||||
```
|
||||
|
||||
## Telegram Notifications
|
||||
|
||||
If you want pi workflow skills to send completion messages, configure:
|
||||
|
||||
- `TELEGRAM_BOT_TOKEN`
|
||||
- `TELEGRAM_CHAT_ID`
|
||||
|
||||
The shared notification behavior matches the existing repo guidance in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md).
|
||||
|
||||
## What This Does Not Assume
|
||||
|
||||
- pi does not automatically provide Codex `update_plan` semantics
|
||||
- pi does not automatically provide plan mode or worktree workflows
|
||||
- pi does not require extensions for the base workflow skills in this repo
|
||||
|
||||
The pi variants must therefore spell out their workflow steps directly and only rely on dependencies documented here.
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
# PI
|
||||
|
||||
## Purpose
|
||||
|
||||
This repo now treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
|
||||
|
||||
The pi support surface is built around the same family layout already used elsewhere in this repo:
|
||||
|
||||
- `skills/atlassian/pi/`
|
||||
- `skills/create-plan/pi/`
|
||||
- `skills/do-task/pi/`
|
||||
- `skills/implement-plan/pi/`
|
||||
- `skills/web-automation/pi/`
|
||||
|
||||
Shared pi guidance lives in:
|
||||
|
||||
- [PI-RESEARCH.md](./PI-RESEARCH.md)
|
||||
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md)
|
||||
|
||||
## Support Strategy
|
||||
|
||||
### Variant Layout
|
||||
|
||||
Each skill family gets a dedicated `pi` variant instead of a pointer-only shim. That keeps pi-specific wording, installation paths, and workflow constraints reviewable in-repo.
|
||||
|
||||
### Shared Workflow Guidance
|
||||
|
||||
The workflow-heavy skills (`create-plan`, `do-task`, `implement-plan`) refer to [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) for:
|
||||
|
||||
- exposing Obra Superpowers to pi
|
||||
- installing the shared reviewer runtime for pi
|
||||
- Telegram notification setup expectations
|
||||
|
||||
### Package Strategy
|
||||
|
||||
V1 uses one repo-level pi package rather than per-skill packages. The package surface is intentionally narrow:
|
||||
|
||||
- only pi skill variants
|
||||
- shared pi docs
|
||||
- pi reviewer-runtime helper sources
|
||||
- a verification script
|
||||
|
||||
The package metadata and allowlist live at repo root so `pi install -l /absolute/path/to/ai-coding-skills` works without extra wrapping.
|
||||
|
||||
## Install Options
|
||||
|
||||
### Local Skill Copy
|
||||
|
||||
Copy a single variant into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` if you only want one skill.
|
||||
|
||||
### Shared Skill Roots
|
||||
|
||||
Pi can load from `~/.agents/skills/`, `.agents/skills/`, `.pi/skills/`, `~/.pi/agent/skills/`, package manifests, or settings-defined skill paths. That makes it possible to keep shared skill roots or repo-local installs.
|
||||
|
||||
### Package Install
|
||||
|
||||
The intended repo-level install flow is:
|
||||
|
||||
```bash
|
||||
pi install -l /absolute/path/to/ai-coding-skills
|
||||
pi list
|
||||
```
|
||||
|
||||
Package details are finalized by the packaging milestone and verified by `scripts/verify-pi-resources.sh` once that script is added in M5.
|
||||
|
||||
## Extension Decision
|
||||
|
||||
Pi extensions are powerful enough to add todo tracking, review orchestration helpers, or sub-agent-like flows, but they are not required for v1.
|
||||
|
||||
Current v1 decision:
|
||||
|
||||
- ship usable pi skill variants without extensions
|
||||
- document the extension opportunities explicitly
|
||||
- only add an extension later if it removes meaningful friction that documentation and helper scripts cannot address cleanly
|
||||
|
||||
This section is intentionally provisional until M4, which records the final v1 extension assessment in this document.
|
||||
|
||||
## Scope Notes
|
||||
|
||||
- Pi variants are written for pi-native behavior, not as thin copies of Codex instructions.
|
||||
- The workflow-heavy skills assume pi can load referenced skills, but they do not assume pi has built-in equivalents for Codex-specific concepts like `update_plan`.
|
||||
- Shared helper scripts are documented with deterministic install paths so workflow instructions stay reproducible.
|
||||
@@ -8,6 +8,9 @@ This directory contains user-facing docs for each skill.
|
||||
- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
|
||||
- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.
|
||||
- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
|
||||
- [PI.md](./PI.md) — Pi support overview, variant strategy, package direction, and extension decision.
|
||||
- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed pi findings that inform the repo's pi variants and packaging choices.
|
||||
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — Shared Obra Superpowers and reviewer-runtime setup for pi workflow skills.
|
||||
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
|
||||
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user