diff --git a/docs/PI-RESEARCH.md b/docs/PI-RESEARCH.md new file mode 100644 index 0000000..6b446a1 --- /dev/null +++ b/docs/PI-RESEARCH.md @@ -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 ` 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//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//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. diff --git a/docs/PI-SUPERPOWERS.md b/docs/PI-SUPERPOWERS.md new file mode 100644 index 0000000..e643708 --- /dev/null +++ b/docs/PI-SUPERPOWERS.md @@ -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. diff --git a/docs/PI.md b/docs/PI.md new file mode 100644 index 0000000..9610ced --- /dev/null +++ b/docs/PI.md @@ -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//` or `.pi/skills//` 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. diff --git a/docs/README.md b/docs/README.md index 2e3f08c..ae7d154 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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.