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

2026-04-23 15:58:19 -05:00
parent c98f27f461
commit 7ba6f90e14
4 changed files with 258 additions and 0 deletions
@@ -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.