planr 1.8.0 → 1.9.0

package/docs/contracts/PI_INTEGRATION_V1.md

@@ -0,0 +1,164 @@
+# Pi Integration Contract v1
+
+Status: frozen for implementation
+
+Frozen: 2026-07-27
+
+Upstream source probes:
+
+- `earendil-works/pi` `main` commit
+  `a597371bda2af70372d1323d550483b5f4a0ae36` (2026-07-27).
+- Pi release `v0.82.1` commit
+  `b4f293684bba718d59cc1157679bcf6157b3a7f5` (2026-07-27).
+- `nicobailon/pi-subagents` `main` commit `73fb2fc` (2026-07-27).
+
+The Pi repository currently publishes release tags ahead of the fetched
+`main` version line, so this contract records both: `main` is the requested
+source probe, while `v0.82.1` is the latest released runtime/API baseline.
+
+This contract is the implementation boundary for first-class Pi support.
+It follows Pi's native extension model instead of treating every coding agent
+as an MCP host. Pi core deliberately ships without MCP, subagents, plan mode,
+or permission popups. It natively discovers Agent Skills and can run their CLI
+workflows through its built-in `bash` tool.
+
+## Frozen artifact and discovery policy
+
+`planr install pi` owns exactly the repository paths in the executable
+contract below. Workflow files are copied byte-for-byte from the canonical
+`plugins/planr/skills` sources. Pi-specific role bodies exist only because
+`pi-subagents` frontmatter is not interchangeable with Claude/Cursor role
+frontmatter: it uses `thinking`, explicit tool/skill inheritance controls, and
+project agents under `.pi/agents/**/*.md`.
+
+Pi loads `.pi/skills/` only after the repository is trusted. Interactive Pi
+asks for trust; non-interactive `-p`, JSON, and RPC runs ignore untrusted
+project resources by default. A headless operator who has deliberately chosen
+to trust the repository passes `--approve` for that run. Planr never writes
+Pi's user trust store or `.pi/settings.json`.
+
+`pi-subagents` is optional. When installed, it discovers both Planr roles.
+Without it, the role files are inert and the same Planr skills remain usable
+in the parent Pi session or separate Pi processes.
+
+```json
+{
+  "contract_version": 1,
+  "pi_main_revision": "a597371bda2af70372d1323d550483b5f4a0ae36",
+  "pi_release": {
+    "tag": "v0.82.1",
+    "revision": "b4f293684bba718d59cc1157679bcf6157b3a7f5"
+  },
+  "pi_subagents_revision": "73fb2fc",
+  "artifacts": [
+    {"target": ".pi/agents/planr-reviewer.md", "source": "plugins/planr/agents/pi/planr-reviewer.md", "kind": "agent"},
+    {"target": ".pi/agents/planr-worker.md", "source": "plugins/planr/agents/pi/planr-worker.md", "kind": "agent"},
+    {"target": ".pi/skills/planr-goal/SKILL.md", "source": "plugins/planr/skills/planr-goal/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-loop/SKILL.md", "source": "plugins/planr/skills/planr-loop/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-loop/agents/planr-reviewer.md", "source": "plugins/planr/skills/planr-loop/agents/planr-reviewer.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/agents/planr-worker.md", "source": "plugins/planr/skills/planr-loop/agents/planr-worker.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/references/host-dispatch.md", "source": "plugins/planr/skills/planr-loop/references/host-dispatch.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-loop/references/recovery-and-verification.md", "source": "plugins/planr/skills/planr-loop/references/recovery-and-verification.md", "kind": "skill_asset"},
+    {"target": ".pi/skills/planr-plan/SKILL.md", "source": "plugins/planr/skills/planr-plan/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-review/SKILL.md", "source": "plugins/planr/skills/planr-review/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-status/SKILL.md", "source": "plugins/planr/skills/planr-status/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-summary/SKILL.md", "source": "plugins/planr/skills/planr-summary/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-task-graph/SKILL.md", "source": "plugins/planr/skills/planr-task-graph/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-verify-web/SKILL.md", "source": "plugins/planr/skills/planr-verify-web/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr-work/SKILL.md", "source": "plugins/planr/skills/planr-work/SKILL.md", "kind": "skill"},
+    {"target": ".pi/skills/planr/SKILL.md", "source": "plugins/planr/skills/planr/SKILL.md", "kind": "skill"}
+  ],
+  "mcp": {"supported": false, "artifacts": []},
+  "extensions": {"emitted": false, "artifacts": []},
+  "hooks": {"supported": false, "artifacts": []},
+  "settings": {"emitted": false, "artifacts": []},
+  "trust": {
+    "project_resources_require_trust": true,
+    "interactive": "Pi prompts the operator",
+    "headless": "pass --approve only after choosing to trust the repository"
+  },
+  "observed_client": {
+    "environment": "PI_CODING_AGENT",
+    "accepted_value": "true",
+    "stored_value": "pi",
+    "advisory_only": true
+  },
+  "client_all_includes_pi": false,
+  "headless": {
+    "command": "pi --approve --model <provider/model> --thinking <level> -p \"<prompt>\""
+  }
+}
+```
+
+## Pi role contract
+
+Both role files use `pi-subagents` project-agent frontmatter:
+
+- `name` is exactly `planr-worker` or `planr-reviewer`;
+- `systemPromptMode: replace`;
+- `inheritProjectContext: true`;
+- `inheritSkills: false`;
+- `skills` names exactly `planr-work` or `planr-review`;
+- the worker tool allowlist includes read/search, `bash`, `edit`, and `write`;
+- the reviewer tool allowlist includes read/search and mutation-capable `bash`,
+  but omits the `edit` and `write` tools;
+- the reviewer declares `acceptanceRole: read-only` and
+  `completionGuard: false`, so pi-subagents treats the bash-enabled validator
+  as non-implementation work without changing its tool access;
+- no role pins `model`, `thinking`, `fallbackModels`, provider credentials, or
+  extensions.
+
+Model and thinking selection remain external host policy. Operators can use
+Pi or `pi-subagents` settings/overrides, while Planr records only requested and
+observed evidence.
+
+## Merge and overwrite policy
+
+- Missing target: write the canonical packaged source.
+- Existing identical content: unchanged.
+- Existing different content: preserve without `--force`; replace only that
+  target with `--force`.
+- `--no-mcp` and `--no-hooks` are accepted for install-command parity but
+  change no Pi path because the v1 artifact set contains neither.
+- Dry-run enumerates the same paths the corresponding write reconciles.
+- `project init --client pi` provisions the same skills and roles without
+  writing any other Pi artifact.
+- `--client all` remains the legacy Codex, Claude Code, and Cursor expansion.
+
+## Runtime observation boundary
+
+Pi documents that commands launched by its built-in tools receive
+`PI_CODING_AGENT=true`. Planr accepts only that exact value as advisory
+`runs.observed_client=pi`. Other values and other ambient `PI_*` variables are
+ignored. The marker is not authentication, authorization, proof of model,
+proof of `pi-subagents`, or worker identity.
+
+Pi has no Planr hook in v1. Run `planr prime` manually after startup or
+compaction when a fresh state block is useful. Agent Skills remain the primary
+entry point: `/skill:planr` explicitly loads the router, while natural-language
+requests may trigger Pi's skill discovery.
+
+## Security and CI boundary
+
+Planr installation must not read or write:
+
+- `~/.pi`, Pi auth files, provider keys, OAuth tokens, sessions, transcripts,
+  prompts, responses, model catalogs, package caches, or trust decisions;
+- `.pi/settings.json`, `.pi/extensions/`, `.pi/prompts/`, or an MCP config;
+- global `pi install`, `pi config`, package enablement, or user settings.
+
+Release and CI workflows do not install/invoke Pi, `pi-subagents`, a provider,
+or a live model. Deterministic tests parse the frozen contract, compile/write
+assets into disposable repositories, and validate CLI/docs output.
+
+## Sources
+
+- `packages/coding-agent/README.md` at Pi `v0.82.1`: project trust, skills,
+  extensions, packages, philosophy, CLI, and `PI_CODING_AGENT`.
+- `packages/coding-agent/docs/skills.md` at Pi `v0.82.1`.
+- `nicobailon/pi-subagents` README at `73fb2fc`: project agent discovery,
+  prompt assembly, frontmatter, and model overrides.
+- `nicobailon/pi-subagents` `test/unit/agent-frontmatter.test.ts` and
+  `test/unit/path-resolution.test.ts` at `73fb2fc`.
+- https://github.com/earendil-works/pi
+- https://github.com/nicobailon/pi-subagents

package/docs/documentation/COVERAGE.md

@@ -4,14 +4,14 @@ This is the canonical inventory that maps shipped public surfaces to repository
 
 ## Published route inventory
 
-The site currently owns 62 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+The site currently owns 63 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
 
 | Section | Published routes |
 | --- | --- |
 | Documentation | `/docs` |
 | Getting started | `/docs/getting-started`, `/docs/getting-started/why-planr`, `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle`, `/docs/getting-started/choose-your-interface` |
 | For Agents | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
-| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/grok-build`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
+| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/grok-build`, `/docs/integrations/pi`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
 | Plugins | `/docs/plugins`, `/docs/plugins/switchloom` |
 | Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
 | Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/recipes` |
@@ -65,6 +65,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 | Claude Code | Claude manifest, generated role/install assets | `/docs/integrations/claude-code` |
 | Cursor | Cursor manifest, role/skill/install assets | `/docs/integrations/cursor` |
 | Grok Build | Native role/skill assets and portable project MCP config | `/docs/integrations/grok-build` |
+| Pi | Native Agent Skills, optional pi-subagents roles, and CLI-backed dispatch | `/docs/integrations/pi` |
 | Generic stdio MCP | MCP server and fixture | `/docs/integrations/generic-mcp` |
 | CLI-only and non-first-class hosts | prompt output and CLI | `/docs/integrations/cli-only` |
 | Privacy, secret handling, localhost boundary | safety spec, `src/app/http.rs`, scrub behavior | `/docs/contributing/security-and-privacy` |
@@ -87,7 +88,7 @@ The executable and schema sources decide exact inventory. Editorial pages explai
 
 ## Audit completion checklist
 
-- [x] All 62 current MDX routes are explicitly inventoried.
+- [x] All 63 current MDX routes are explicitly inventoried.
 - [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
 - [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
 - [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.

package/docs/fixtures/mcp-contract.json

@@ -102,13 +102,13 @@
     ]
   },
   "cli_reference_commands": [
-    "planr install codex|claude|cursor|grok",
+    "planr install codex|claude|cursor|grok|pi",
     "planr prompt cli|mcp|http",
     "planr prompt routing",
     "planr agents init",
     "planr agents init --profile|--skill|--route|--default-route|--interactive",
     "planr prime",
-    "planr install codex|claude|cursor|grok [--dry-run] [--no-mcp] [--force] [--no-hooks]",
+    "planr install codex|claude|cursor|grok|pi [--dry-run] [--no-mcp] [--force] [--no-hooks]",
     "planr mcp",
     "planr review annotate",
     "planr review ingest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,6 @@
     "docs:content": "pnpm --filter @planr/docs content",
     "docs:typecheck": "pnpm --filter @planr/docs typecheck",
     "docs:lint": "pnpm --filter @planr/docs lint",
-    "docs:verify-shell": "pnpm --filter @planr/docs verify:shell",
     "docs:verify-onboarding": "cargo build --bin planr && pnpm --filter @planr/docs verify:onboarding && pnpm --filter @planr/docs verify:agent-recipes",
     "docs:verify-agent-recipes": "cargo build --bin planr && pnpm --filter @planr/docs verify:agent-recipes",
     "docs:verify-agent-markdown": "pnpm docs:build && pnpm --filter @planr/docs verify:agent-markdown",

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",

package/plugins/planr/agents/pi/planr-reviewer.md

@@ -0,0 +1,16 @@
+---
+name: planr-reviewer
+description: Reviews one Planr item against its plan, diff, logs, and verification evidence without editing implementation files.
+tools: read, grep, find, ls, bash
+skills: planr-review
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+acceptanceRole: read-only
+completionGuard: false
+---
+
+Use the preloaded `planr-review` skill exactly as written for the single review
+item id you are given. Inspect the actual diff and replay the logged evidence.
+Do not edit implementation files. Close the review once with a specific
+verdict and actionable findings when the target is incomplete.

package/plugins/planr/agents/pi/planr-worker.md

@@ -0,0 +1,14 @@
+---
+name: planr-worker
+description: Implements exactly one picked Planr map item, logs replayable evidence, requests review, and stops.
+tools: read, grep, find, ls, bash, edit, write
+skills: planr-work
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+Use the preloaded `planr-work` skill exactly as written for the single item id
+you are given. Implement only that item. Log changed files and the real
+verification commands you ran. Request review and stop. Never close your own
+review or claim independent verification.

package/plugins/planr/skills/planr-loop/references/host-dispatch.md

@@ -5,6 +5,7 @@ Load this only when the loop has subagents and must bind a provider-neutral Plan
 - Codex: generated `.codex/config.toml` roles are native roles. Bind the exact matching `routing.profile` as `agent_type` with `fork_turns: "none"`. Do not replace binding with prose, `task_name`, or worker identity, and do not wait on an invalid default-role spawn when a generated role is required.
 - Claude Code: plugin agents preload the worker/reviewer skills; standalone installs provision `.claude/agents/`.
 - Cursor: dispatch the provisioned `.cursor/agents/planr-worker.md` and `planr-reviewer.md` roles explicitly.
+- Pi: invoke the repository-native router with `/skill:planr`. If optional `pi-subagents` is already installed, dispatch `.pi/agents/planr-worker.md` and `planr-reviewer.md`; Planr does not install that package. Without it, use separate sequential Pi processes for maker and checker passes and record `single_agent` honestly. Core Pi has no Planr MCP or hooks, so run `planr prime` manually when fresh context is needed. After reviewing and trusting the project resources, exact headless process dispatch has the form `pi --approve --model <provider/model> --thinking <level> -p "Use /skill:planr-work on item <item-id>. Stop after requesting review."`
 - Single-agent hosts: use separate sequential maker/checker passes with a fresh map read; Planr records `single_agent` honestly.
 
 The driver should inspect routing with `planr pick --peek --plan <plan-id>` so the worker takes the actual lease. Host declarations are requests, never proof. Record observed profile/route evidence through worker completion metadata.