docs(pi): implement milestone M1 - research and shared docs

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 <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.

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.

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/<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.

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.