@chankov/agent-skills 0.1.0

package/docs/pi-extensions.md

@@ -0,0 +1,163 @@
+# pi Extensions
+
+A catalog of the pi extensions in this repo — what each one does, how to run it, the
+supporting data it needs, and how the ported set differs from upstream.
+
+---
+
+## Attribution
+
+The 15 orchestration, UI, safety, and messaging extensions documented here — together
+with their supporting agent definitions, design specs, the `coms-net` hub server, and the
+`justfile` — are ported from the **`pi-vs-claude-code`** project:
+
+- **Author:** [disler](https://github.com/disler) (IndyDevDan)
+- **Source:** <https://github.com/disler/pi-vs-claude-code>
+- **License:** MIT — Copyright (c) 2026 IndyDevDan
+
+Ported files retain their original authorship; this repo adapts them to its layout and
+conventions. Runtime design specs for the imported harnesses live in `docs/pi-specs/`.
+
+---
+
+## What these extensions are
+
+`.pi/extensions/` ships three always-on **utility** extensions — `mcp-bridge`,
+`chrome-devtools-mcp`, and `compact-and-continue`. pi auto-discovers that directory, so
+those three layer onto every session.
+
+The 15 documented below are different: each is a **session harness**. They reshape the
+whole pi session — some remove every codebase tool and leave only an orchestration tool,
+some replace the footer, some gate every tool call. They are **mutually exclusive by
+design**: run one per session (at most two stacked, e.g. an orchestrator `+ minimal`),
+not all at once. Because of that they live in **`.pi/harnesses/`** — a directory pi does
+*not* auto-discover — so a plain `pi` run never loads them.
+
+### Selective loading — read this first
+
+pi auto-discovers every extension directory under a project's `.pi/extensions/` and loads
+all of them. If the 15 harnesses lived there, a plain `pi` run would load them all at once
+— footers would fight, orchestrators would collide, and `coms` / `coms-net` would abort
+startup with duplicate CLI-flag registrations. So the harnesses live in `.pi/harnesses/`
+instead, and you load exactly one (or two) explicitly:
+
+- through the `justfile` — `just ext-agent-team`, `just ext-tilldone`, …
+- or directly — `pi -e .pi/harnesses/<name>/index.ts`
+
+When you consume this repo from another project, point `pi -e` at the harness file you
+want, or symlink that one directory into *its* `.pi/harnesses/` — never drop the harnesses
+into `.pi/extensions/`, and never load all 15 (see
+[pi-setup.md](pi-setup.md#optional-pi-extensions)).
+
+---
+
+## Setup
+
+```bash
+just install            # one-time — installs runtime deps for extensions + harnesses
+just ext-minimal        # launch pi with a harness
+just --list             # see every recipe
+```
+
+`just install` runs `npm install` for both dependency roots: `.pi/extensions/` for the
+utilities (`@modelcontextprotocol/sdk`, `typebox`) and `.pi/harnesses/` for the harnesses
+(`@sinclair/typebox`, `yaml`). The `@mariozechner/pi-*` packages are provided by the pi
+runtime itself.
+
+---
+
+## Catalog
+
+| Extension | Category | What it does | Run |
+|-----------|----------|--------------|-----|
+| [minimal](../.pi/harnesses/minimal/README.md) | UI | Model name + 10-block context meter footer | `just ext-minimal` |
+| [tool-counter](../.pi/harnesses/tool-counter/README.md) | UI | Rich two-line footer: model, branch, cwd, tokens, cost, tool tally | `just ext-tool-counter` |
+| [tool-counter-widget](../.pi/harnesses/tool-counter-widget/README.md) | UI | Per-tool call counts in a widget above the editor | `just ext-tool-counter-widget` |
+| [session-replay](../.pi/harnesses/session-replay/README.md) | UI | `/replay` scrollable timeline overlay of session history | `just ext-session-replay` |
+| [purpose-gate](../.pi/harnesses/purpose-gate/README.md) | Focus | Forces you to declare session intent before working | `just ext-purpose-gate` |
+| [tilldone](../.pi/harnesses/tilldone/README.md) | Focus | Agent must define tasks before using any other tool | `just ext-tilldone` |
+| [damage-control](../.pi/harnesses/damage-control/README.md) | Safety | Blocks destructive tool calls and aborts the turn | `just ext-damage-control` |
+| [damage-control-continue](../.pi/harnesses/damage-control-continue/README.md) | Safety | Same rules, but the agent keeps working with corrective feedback | `just ext-damage-control-continue` |
+| [subagent-widget](../.pi/harnesses/subagent-widget/README.md) | Orchestration | `/sub <task>` background subagents with live stacking widgets | `just ext-subagent-widget` |
+| [agent-team](../.pi/harnesses/agent-team/README.md) | Orchestration | Dispatcher-only orchestrator with a grid dashboard | `just ext-agent-team` |
+| [agent-chain](../.pi/harnesses/agent-chain/README.md) | Orchestration | Sequential agent pipeline orchestrator | `just ext-agent-chain` |
+| [system-select](../.pi/harnesses/system-select/README.md) | Orchestration | `/system` to pick an agent persona as the system prompt | `just ext-system-select` |
+| [pi-pi](../.pi/harnesses/pi-pi/README.md) | Orchestration | Meta-agent that builds pi agents via parallel expert research | `just ext-pi-pi` |
+| [coms](../.pi/harnesses/coms/README.md) | Messaging | Peer-to-peer messaging between pi agents on one machine | `just local-coms` |
+| [coms-net](../.pi/harnesses/coms-net/README.md) | Messaging | HTTP/SSE communication network across hosts (needs the hub) | `just coms` |
+
+Each extension directory has its own `README.md` with the full description, command/tool
+surface, requirements, and per-extension upstream changes.
+
+---
+
+## Environment variables
+
+The `justfile` sets `dotenv-load`, so a `.env` file at the repo root is auto-loaded
+(`.env` is gitignored). Only a few extensions need keys:
+
+| Variable | Needed by | Purpose |
+|----------|-----------|---------|
+| `FIRECRAWL_API_KEY` | `pi-pi` | Expert agents crawl current pi documentation via Firecrawl |
+| `PI_COMS_NET_AUTH_TOKEN` | `coms-net` | Shared secret — required to bind a LAN/remote hub |
+| `PI_COMS_NET_PORT` | `coms-net` | Pin the hub port so the URL is stable across restarts |
+| `PI_COMS_NET_SERVER_URL` | `coms-net` | Hub URL for clients (blank = auto-discover the local `server.json`) |
+
+For `127.0.0.1`-only `coms-net` use, the hub auto-generates a token — no env needed.
+
+---
+
+## Supporting data
+
+These ported files are runtime dependencies of the extensions above:
+
+- **`.pi/agents/`** — symlinks back to the canonical personas in `agents/`
+  (`scout`, `planner`, `plan-reviewer`, `builder`, `documenter`, `code-reviewer`,
+  `test-engineer`, `security-auditor`), the pi-local `bowser.md`, the `pi-pi/`
+  research experts, plus `teams.yaml` and `agent-chain.yaml`. Read by `agent-team`,
+  `agent-chain`, `system-select`, and `pi-pi`. The earlier `reviewer` and
+  `red-team` personas were folded into `code-reviewer` and `security-auditor`;
+  the team and chain configs already reference the canonical names.
+- **`.pi/damage-control-rules.yaml`** — the destructive-command / protected-path rule set
+  for `damage-control` and `damage-control-continue`.
+- **`.pi/skills/bowser/`** — a pi-runtime skill for headless Playwright browser
+  automation, used by the `bowser` agent persona. Kept separate from the core
+  engineering `skills/`.
+- **`scripts/coms-net-server.ts`** — the HTTP/SSE hub server for `coms-net`. Pure Node
+  built-ins; run it with `node --experimental-strip-types scripts/coms-net-server.ts`
+  (Node >= 22.6, or `just coms-net-server`).
+- **`docs/pi-specs/`** — the original design specifications: `agent-forge` (the
+  `agent-team` design), `agent-workflow` (`agent-chain`), `damage-control`, and `pi-pi`.
+
+---
+
+## Upstream changes
+
+What changed relative to `disler/pi-vs-claude-code`:
+
+- **Theme code removed.** Every ported extension imported `applyExtensionDefaults` from a
+  shared `themeMap.ts`. That import and its `session_start` call site were stripped from
+  all 15 files; `themeMap.ts` and the 11 `.pi/themes/*.json` palettes are not ported.
+  Extensions render against pi's active theme.
+- **Layout converted.** Flat `extensions/<name>.ts` files became
+  `.pi/harnesses/<name>/index.ts` directories, each with its own `package.json` and
+  `README.md`. They live under `.pi/harnesses/` — *not* `.pi/extensions/` — because pi
+  auto-discovers and loads everything in `.pi/extensions/`, and these 15 are
+  mutually-exclusive harnesses that must be loaded one at a time.
+- **Tooling switched to npm.** `bun` / `bun.lock` are not used; the `justfile` recipes
+  point at the new paths and use npm. The `coms-net` hub launches via
+  `node --experimental-strip-types` instead of `bun`.
+
+### Not ported
+
+- The `pure-focus`, `theme-cycler`, and `cross-agent` extensions.
+- `themeMap.ts` and all 11 `.pi/themes/*.json` theme palettes.
+- The Claude Code `statusLine` config and `status_lines/status_line.py`, and the
+  `plan_w_team.md` command (it depended on team-agent files absent from the source).
+
+### A note on `.pi/settings.json`
+
+Upstream shipped a `.pi/settings.json` that only set the (now-stripped) theme and
+registered a prompt directory. This repo already keeps pi prompts in the standard
+`.pi/prompts/` location, so no `.pi/settings.json` is shipped — it would carry nothing
+useful.

package/docs/pi-setup.md

@@ -0,0 +1,416 @@
+# pi Setup
+
+This guide explains how to use Agent Skills with [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) — the terminal coding agent from `pi-mono`. Unlike some harnesses, pi has a **native Agent Skills implementation**, so no prompt hacks are needed for skills: this repo drops in directly.
+
+This repo also ships pi-native **prompt templates** for the lifecycle slash commands (`/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, `/ship`). These commands add workflow orchestration on top of the underlying skills.
+
+## Overview
+
+pi natively supports:
+
+- `AGENTS.md` / `CLAUDE.md` context files (auto-loaded from cwd, parent dirs, and global config)
+- Skill discovery from well-known directories (`.agents/skills/`, `.pi/skills/`, `~/.pi/agent/skills/`)
+- Explicit skill invocation via `/skill:<name>`
+- Automatic skill loading by the model when intent matches
+- Prompt-template slash commands from `.pi/prompts/*.md`
+
+This means you get near-parity with Claude Code:
+
+- Skills are selected automatically based on intent
+- Workflows are enforced via `AGENTS.md`
+- Users can explicitly trigger any skill with `/skill:<name>`
+- Users can start lifecycle workflows with `/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, and `/ship`
+
+No plugin, wrapper, or custom system prompt is required for the core workflow.
+
+**Recommended companion package:** install [`pi-ask-user`](https://github.com/edlsh/pi-ask-user) alongside these skills. It adds an interactive `ask_user` tool and bundles an `ask-user` skill, which is already used by this repo's current pi setup for high-stakes or ambiguous decisions.
+
+---
+
+## Installation
+
+The recommended install is **project-scoped using symlinks**:
+
+- `.agents/skills/` exposes the skills.
+- `.pi/prompts/` exposes the lifecycle slash commands.
+
+pi walks upward from the current working directory looking for project configuration, so once the symlinks exist, every pi session started from inside (or below) the repo picks up the skills and commands automatically. The `AGENTS.md` at the repo root is loaded the same way.
+
+1. Clone the repository somewhere stable:
+
+```bash
+git clone https://github.com/chankov/agent-skills.git /path/to/agent-skills
+```
+
+2. From the project where you want to use the skills, symlink `skills/` into a pi-discoverable path:
+
+```bash
+cd /path/to/your-project
+mkdir -p .agents
+ln -s /path/to/agent-skills/skills .agents/skills
+```
+
+3. From the same project, symlink the pi-native lifecycle commands into pi's prompt-template directory:
+
+```bash
+mkdir -p .pi
+ln -s /path/to/agent-skills/.pi/prompts .pi/prompts
+```
+
+This exposes:
+
+```text
+/spec
+/plan
+/build
+/test
+/review
+/code-simplify
+/ship
+```
+
+If `.pi/prompts` already exists as a real directory, keep it and symlink the individual command files instead:
+
+```bash
+ln -s /path/to/agent-skills/.pi/prompts/spec.md .pi/prompts/spec.md
+ln -s /path/to/agent-skills/.pi/prompts/plan.md .pi/prompts/plan.md
+ln -s /path/to/agent-skills/.pi/prompts/build.md .pi/prompts/build.md
+ln -s /path/to/agent-skills/.pi/prompts/test.md .pi/prompts/test.md
+ln -s /path/to/agent-skills/.pi/prompts/review.md .pi/prompts/review.md
+ln -s /path/to/agent-skills/.pi/prompts/code-simplify.md .pi/prompts/code-simplify.md
+ln -s /path/to/agent-skills/.pi/prompts/ship.md .pi/prompts/ship.md
+```
+
+4. Install the recommended `pi-ask-user` pi package:
+
+```bash
+pi install npm:pi-ask-user
+```
+
+This adds:
+
+- the interactive `ask_user` tool
+- the bundled `ask-user` skill
+
+5. Verify pi can see everything:
+
+```bash
+pi
+# then type:
+/skill:
+# pi should autocomplete the full list of agent-skills, plus ask-user if pi packages are enabled
+
+# then type:
+/
+# pi should autocomplete /spec, /plan, /build, /test, /review, /code-simplify, and /ship
+```
+
+That's it. `AGENTS.md` is already at the repo root and is auto-loaded when pi starts.
+
+### Optional: pi extensions
+
+This repo also ships pi **extensions** under `.pi/extensions/`. Extensions are TypeScript modules that register tools and commands directly with pi. They come in two kinds: **always-on utilities** that layer onto any session, and selectable **harnesses** that reshape a whole session.
+
+The always-on utilities:
+
+- `mcp-bridge/` — a reusable factory that turns any stdio MCP server into a pi extension. This is a library consumed by wrapper extensions. Symlink it alongside wrappers so relative imports resolve; when pi discovers it directly, it intentionally registers no tools or commands by itself.
+- `chrome-devtools-mcp/` — bridges the [`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp) server into pi as native tools, unlocking the `browser-testing-with-devtools` skill on pi.
+- `compact-and-continue/` — registers the `request_compaction` tool that queues pi context compaction to run after the current agent turn ends, optionally resuming work from a self-contained continuation prompt. Used by `/build` to offer a "Compact & continue" option at slice-approval time.
+
+To install, symlink the directories into your project's `.pi/extensions/`:
+
+```bash
+mkdir -p .pi/extensions
+ln -s /path/to/agent-skills/.pi/extensions/mcp-bridge            .pi/extensions/mcp-bridge
+ln -s /path/to/agent-skills/.pi/extensions/chrome-devtools-mcp   .pi/extensions/chrome-devtools-mcp
+ln -s /path/to/agent-skills/.pi/extensions/compact-and-continue  .pi/extensions/compact-and-continue
+```
+
+Install the shared runtime dependencies used by the symlinked extensions once in the `agent-skills` clone:
+
+```bash
+cd /path/to/agent-skills/.pi/extensions
+npm ci
+# If this clone does not have package-lock.json yet, run: npm install
+```
+
+Because the project extensions are symlinks into the clone, these dependencies are reused by every project that links the same extension directories.
+
+Verify by starting `pi` and running `/chrome_devtools-status` — expect `Chrome DevTools MCP connected. Registered N tool(s).`
+
+#### Extension harnesses — orchestration, safety, messaging
+
+This repo also ships **15 session harnesses** ported from [disler](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) project (MIT):
+
+- **Orchestration** — `agent-team`, `agent-chain`, `pi-pi`, `subagent-widget`, `system-select`
+- **Safety** — `damage-control`, `damage-control-continue`
+- **Focus** — `purpose-gate`, `tilldone`
+- **UI** — `minimal`, `tool-counter`, `tool-counter-widget`, `session-replay`
+- **Pi-to-Pi messaging** — `coms`, `coms-net`
+
+Unlike the utilities above, each harness reshapes the entire pi session, and they are **mutually exclusive** — you load one per session, not all at once. pi auto-discovers and loads *everything* under `.pi/extensions/`, so the harnesses deliberately live in a separate directory — **`.pi/harnesses/`** — which pi does *not* auto-discover. **Never copy or symlink a harness into `.pi/extensions/`**: that would load it on every plain `pi` run, and stacking all 15 aborts startup (`coms` and `coms-net` register clashing CLI flags). Load a single harness explicitly instead — there is nothing to symlink:
+
+```bash
+# from the agent-skills clone, via the bundled justfile
+just --list                       # list every harness recipe
+just ext-agent-team               # launch pi with one harness
+
+# or directly, from anywhere — point pi -e at the harness file
+pi -e /path/to/agent-skills/.pi/harnesses/tilldone/index.ts
+```
+
+The harnesses have their own runtime dependencies (`yaml`, `@sinclair/typebox`) declared in `.pi/harnesses/package.json` — separate from the extension deps above. Install both at once with `just install` from the clone, or run `npm ci` in `.pi/harnesses/` as well. The [pi extension catalog](pi-extensions.md) has the full list, per-extension `README.md` pointers, required environment variables (for `coms-net` and `pi-pi`), and what changed from upstream.
+
+Each extension — utility or harness — has its own `README.md` describing what it provides.
+
+> Why a generic `mcp-bridge` exists: pi does not yet have first-class MCP infrastructure. The bridge is a stopgap that lets pi consume MCP servers today; it will be deprecated once pi gains native MCP support.
+
+### Keeping skills up to date
+
+Because `.agents/skills`, `.pi/prompts`, and `.pi/extensions` are symlinks into the cloned `agent-skills` repo, running `git pull` in that clone updates every skill, lifecycle command, and extension in place — no re-copy required.
+
+### Alternative scopes
+
+- **Global install** — symlink skills into `~/.pi/agent/skills/` and prompts into `~/.pi/agent/prompts/` to make them available in every pi session on the machine, regardless of cwd. You may also symlink `AGENTS.md` into `~/.pi/agent/AGENTS.md` for global workflow context.
+- **Copy instead of symlink** — use `cp -R /path/to/agent-skills/skills .agents/skills` and `cp -R /path/to/agent-skills/.pi/prompts .pi/prompts` if you're on a platform where symlinks are awkward (e.g. plain Windows without developer mode). You'll need to re-copy after updates.
+
+### Recommended companion skill
+
+If you install `pi-ask-user`, pi will also discover its bundled `ask-user` skill from the installed pi package. This is a strong complement to `agent-skills` because it gives the agent a structured way to stop and ask for an explicit decision before:
+
+- architectural or API trade-offs
+- destructive or costly-to-reverse changes
+- ambiguous requirements
+- preference-dependent implementation choices
+
+That matches the repo's current pi setup, where `ask-user` is available as a recommended decision-gating skill.
+
+### Future work
+
+pi supports extensions and skill discovery "from pi packages." Publishing `agent-skills` as a first-class pi package would let users install via pi's own mechanism — out of scope for this guide, but tracked as a future integration.
+
+---
+
+## How It Works
+
+### 1. Skill Discovery
+
+pi searches these locations for skills (all are merged):
+
+```
+.agents/skills/           ← this install (walked upward from cwd)
+.pi/skills/               ← project scope
+~/.agents/skills/         ← global convention
+~/.pi/agent/skills/       ← pi global config
+<pi packages>             ← bundled/installed pi packages (e.g. `pi-ask-user`)
+```
+
+Each skill lives in:
+
+```
+skills/<skill-name>/SKILL.md
+```
+
+### 2. Context Files
+
+`AGENTS.md` (and `CLAUDE.md`) are auto-loaded and concatenated from:
+
+- `~/.pi/agent/AGENTS.md` (global)
+- Every parent directory walking up from cwd
+- The current directory
+
+The repo's `AGENTS.md` encodes the intent-to-skill mapping and workflow rules that make skill selection behave like Claude Code.
+
+### 3. Prompt Templates
+
+pi also searches for prompt templates in:
+
+```
+.pi/prompts/*.md          ← this command install (walked upward from cwd)
+~/.pi/agent/prompts/*.md  ← pi global command config
+<pi packages>             ← bundled/installed pi packages
+```
+
+Each Markdown file becomes a slash command by filename. For example:
+
+```
+.pi/prompts/spec.md          → /spec
+.pi/prompts/code-simplify.md → /code-simplify
+```
+
+These lifecycle commands are not replacements for skills. They are workflow entry points that add orchestration and tell the agent which skills to load and follow for the current phase.
+
+### 4. Invocation
+
+Three ways to trigger the workflow:
+
+- **Explicit skill:** type `/skill:<name>` (e.g. `/skill:spec-driven-development`)
+- **Lifecycle command:** type `/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, or `/ship`
+- **Automatic:** describe intent in natural language — the model reads `AGENTS.md` and loads the matching skill
+
+### 5. Lifecycle Mapping
+
+The development lifecycle is encoded in both `AGENTS.md` and the pi prompt templates:
+
+- DEFINE → `/spec` → `spec-driven-development`
+- PLAN → `/plan` → `planning-and-task-breakdown`
+- BUILD → `/build` → `incremental-implementation` + `test-driven-development`
+- VERIFY → `/test` → `test-driven-development`; use `debugging-and-error-recovery` when tests or builds fail
+- REVIEW → `/review` → `code-review-and-quality`
+- SIMPLIFY → `/code-simplify` → `code-simplification`
+- SHIP → `/ship` → `shipping-and-launch`
+
+---
+
+## Usage Examples
+
+### Example 1: Feature Development
+
+User:
+```
+Add authentication to this app
+```
+
+pi behavior:
+- Reads `AGENTS.md`, detects feature work
+- Auto-loads `spec-driven-development`
+- Produces a spec before writing code
+- Progresses to `planning-and-task-breakdown` and implementation skills
+
+Equivalent explicit forms:
+```
+/spec Add authentication to this app
+/skill:spec-driven-development
+```
+
+---
+
+### Example 2: Bug Fix
+
+User:
+```
+This endpoint is returning 500 errors
+```
+
+pi behavior:
+- Auto-loads `debugging-and-error-recovery`
+- Reproduces → localizes → fixes → adds guards
+
+Equivalent explicit forms:
+```
+/test This endpoint is returning 500 errors
+/skill:debugging-and-error-recovery
+```
+
+---
+
+### Example 3: Code Review
+
+User:
+```
+Review this PR
+```
+
+pi behavior:
+- Auto-loads `code-review-and-quality`
+- Applies structured review (correctness, design, readability, security, tests)
+
+Equivalent explicit forms:
+```
+/review
+/skill:code-review-and-quality
+```
+
+---
+
+## Agent Expectations (Critical)
+
+For the skill system to deliver its value, the agent must:
+
+- Check whether a skill applies before acting
+- Invoke the matching skill when one applies
+- Never skip required workflows (spec, plan, test, etc.)
+- Not jump directly to implementation on non-trivial work
+
+These rules are enforced by `AGENTS.md`, which pi auto-loads.
+
+---
+
+## Verification
+
+After installing, confirm the integration works:
+
+1. Run `pi` from inside the repo (or any subdirectory).
+2. Type `/skill:` and confirm the skill list autocompletes with entries like `spec-driven-development`, `incremental-implementation`, `code-review-and-quality`, and `ask-user`.
+3. Type `/` and confirm the lifecycle commands autocomplete: `/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, and `/ship`.
+4. Run `/spec design a new feature for X` — confirm pi expands the command and invokes `spec-driven-development`.
+5. Ask: *"fix this bug"* — confirm pi invokes `debugging-and-error-recovery`, or run `/test` to start a TDD/debugging workflow explicitly.
+6. Give pi an ambiguous or high-stakes request and confirm it can use the `ask_user` tool / `ask-user` skill to request an explicit decision.
+
+If skill autocomplete is empty, check that `.agents/skills` points to a directory containing `<skill-name>/SKILL.md` files and that pi was not started with `--no-skills`.
+
+If lifecycle command autocomplete is empty, check that `.pi/prompts` points to a directory containing the command Markdown files and run `/reload` or restart pi.
+
+If extension loading reports `Cannot find module '@modelcontextprotocol/sdk/client/index.js'`, the extension runtime dependencies are not installed. Run:
+
+```bash
+cd /path/to/agent-skills/.pi/extensions
+npm ci
+```
+
+The harnesses install separately — if a harness reports `Cannot find module 'yaml'` or `'@sinclair/typebox'`, run `npm ci` in `.pi/harnesses/` as well (or `just install` from the clone, which does both).
+
+Then run `/reload` or restart pi.
+
+---
+
+## Limitations
+
+- Automatic skill loading depends on the underlying model's compliance with `AGENTS.md` rules.
+- Prompt-template commands expand into instructions; they do not mechanically execute `/skill:<name>`. The pi-specific prompt templates therefore explicitly tell the agent which skills to load and follow.
+- Windows without developer mode may not support symlinks — use the copy variant instead.
+- Global `AGENTS.md` applies to every project when using the global-install alternative; pi concatenates context files, so this is usually additive, not destructive, but be aware of it.
+
+---
+
+## Recommended Workflow
+
+Just use natural language:
+
+- "Design a feature"
+- "Plan this change"
+- "Implement this"
+- "Fix this bug"
+- "Review this"
+
+Or invoke lifecycle commands when you want the full workflow prompt:
+
+- `/spec`
+- `/plan`
+- `/build`
+- `/test`
+- `/review`
+- `/code-simplify`
+- `/ship`
+
+Or invoke individual skills directly when you want precise control:
+
+- `/skill:spec-driven-development`
+- `/skill:planning-and-task-breakdown`
+- `/skill:incremental-implementation`
+- `/skill:debugging-and-error-recovery`
+- `/skill:code-review-and-quality`
+
+---
+
+## Summary
+
+pi integration works by leveraging pi's **native** Agent Skills and prompt-template support:
+
+- Symlink `skills/` into `.agents/skills/`
+- Symlink `.pi/prompts/` into the target project's `.pi/prompts/`
+- Install the recommended `pi-ask-user` pi package for interactive decision gating
+- Let pi auto-load `AGENTS.md` from the repo root
+- Use `/skill:<name>`, lifecycle commands like `/spec`, or natural language to trigger workflows
+
+The result is a fully agent-driven, production-grade engineering workflow — with minimal setup: one symlink for this repo's skills, one symlink for lifecycle commands, plus an optional but recommended `pi-ask-user` install for interactive decision gating.