Add focused Pi host adapter

.github/workflows/ci.yml

@@ -35,6 +35,7 @@ jobs:
       - name: Install development dependencies
         run: |
           python -m pip install -r requirements-dev.txt
+          npm install --global @earendil-works/pi-coding-agent@0.84.0
           cd project-map-ui
           npm ci
 
@@ -58,4 +59,6 @@ jobs:
           python scripts/check_mcp.py
           python scripts/test_check_activation.py
           python scripts/test_macos_quarantine_bootstrap.py
+          TREEWORK_REQUIRE_PI=1 python scripts/check_pi_adapter.py
+          TREEWORK_REQUIRE_PI=1 python scripts/check_pi_workspace_switch.py
           python scripts/check_packaging.py

AGENTS.md

@@ -1,7 +1,7 @@
 # TreeWork Repository Guidance
 
-This repository contains both an installable Codex plugin and the source used
-to maintain it.
+This repository contains an installable Codex plugin, a focused Pi package
+adapter, and the shared source used to maintain both.
 
 ## Read Before Editing
 
@@ -16,8 +16,11 @@ to maintain it.
 
 ## Repository Boundaries
 
-- `plugins/treework/` is the installable plugin. Keep it free of
-  project history, UI source, prototypes, and maintainer-only documents.
+- `plugins/treework/` is the installable Codex plugin and shared runtime. Keep
+  it free of project history, UI source, prototypes, and maintainer-only
+  documents.
+- `adapters/pi/` is the focused Pi host surface. Reuse the shared Skill, CLI,
+  transactions, and MCP server; do not fork their state or semantics.
 - Agent references explain how to use TreeWork. Do not put Rust modules, API
   internals, migration plans, or frontend architecture there.
 - `project-map-ui/` is source; `plugins/treework/assets/graph-panel/`

CONTRIBUTING.md

@@ -3,16 +3,17 @@
 TreeWork accepts focused fixes and improvements that strengthen the shared
 project-state protocol without adding project-specific policy to the core.
 
-TreeWork currently ships and is release-tested as a Codex plugin. Contributions
+TreeWork currently ships and is release-tested for Codex and Pi. Contributions
 for other coding-agent hosts are welcome when they preserve the same document,
 transaction, lifecycle, and verification semantics through a focused adapter.
 
 ## High-Impact Contribution Areas
 
 - Project Map interaction design, navigation, accessibility, responsive
   behavior, and large-Tree performance.
-- Host adapters for Claude Code, Cursor, Gemini CLI, OpenCode, and other coding
-  agents, with installation documentation and host-specific tests.
+- Improvements to the Pi adapter and focused host adapters for Claude Code,
+  Cursor, Gemini CLI, OpenCode, and other coding agents, with installation
+  documentation and host-specific tests.
 - Controlled evaluations of state recovery, agent handoffs, development drift,
   quality, and operational overhead.
 - Documentation, examples, translations, packaging, and platform support.

Makefile

@@ -4,9 +4,9 @@ PLUGIN_CREATOR ?= $(HOME)/.codex/skills/.system/plugin-creator
 SKILL_CREATOR ?= $(HOME)/.codex/skills/.system/skill-creator
 ARTIFACTS ?= .artifacts
 
-.PHONY: test test-rust test-ui test-runtime validate build-ui package browser-test
+.PHONY: test test-rust test-ui test-runtime test-pi validate build-ui package browser-test
 
-test: test-rust test-ui test-runtime
+test: test-rust test-ui test-runtime test-pi
 
 test-rust:
 	cargo test --manifest-path $(CLI_MANIFEST)
@@ -23,12 +23,18 @@ test-runtime:
 	python3 scripts/test_check_activation.py
 	python3 scripts/test_macos_quarantine_bootstrap.py
 
+# Pi is optional for local contributors, but CI sets TREEWORK_REQUIRE_PI=1.
+test-pi:
+	python3 scripts/check_pi_adapter.py
+	python3 scripts/check_pi_workspace_switch.py
+
 build-ui:
 	cd project-map-ui && npm run build
 
 validate: build-ui
 	git diff --exit-code -- $(PLUGIN)/assets/graph-panel
 	python3 scripts/check_packaging.py
+	python3 scripts/check_pi_adapter.py
 	python3 $(PLUGIN_CREATOR)/scripts/validate_plugin.py $(PLUGIN)
 	python3 $(SKILL_CREATOR)/scripts/quick_validate.py \
 		$(PLUGIN)/skills/treework

README.md

@@ -10,9 +10,10 @@
 
 # TreeWork
 
-TreeWork is a **tree-guided development plugin for Codex**. It helps coding
-agents organize complex projects as branches, prepare the important design
-before coding, and move through long-running work without losing direction.
+TreeWork is a **tree-guided development system for coding agents**. It ships as
+a Codex plugin and a focused Pi host adapter. TreeWork helps agents organize
+complex projects as branches, prepare the important design before coding, and
+move through long-running work without losing direction.
 
 Code inspection shows what exists and retrieval memory recalls fragments, but
 neither reliably tells an Agent what the project has accepted, where work
@@ -23,12 +24,30 @@ scratch.
 
 ## First Install
 
-TreeWork currently targets Codex on macOS and Linux. Native Windows support has
-not been release-tested.
+TreeWork currently targets Codex and Pi on macOS and Linux. Native Windows
+support has not been release-tested.
 
 Runtime prerequisites: Git, Bash, Python 3, Rust, and Cargo. The Project Map
 frontend is bundled; Node.js is needed only for frontend development.
 
+### Pi
+
+Install the focused Pi package directly from this repository:
+
+```bash
+pi install git:github.com/Johnny-xuan/TreeWork
+```
+
+Restart Pi, run `/treework-adapter` to verify the runtime, then invoke
+`/skill:treework` or ask Pi to use TreeWork. The adapter reuses the shipped
+Skill and MCP server, loads read-only tools on demand, ports TreeWork's mutation
+and stop-check guardrails, and provides explicit `/treework-enter` and
+`/treework-return` commands that fork the conversation across cwd-bound Pi
+sessions. See [TreeWork for Pi](adapters/pi/README.md) for
+the complete install, use, verification, and rollback contract.
+
+### Codex guided install
+
 Give the following prompt to a Codex Agent with terminal access:
 
 ```text
@@ -67,7 +86,7 @@ inside the current project until I explicitly approve it.
    new one. Leave project initialization to the new Codex task after I choose.
 ```
 
-### Manual Install
+### Codex manual install
 
 ```bash
 codex plugin marketplace add https://github.com/Johnny-xuan/TreeWork
@@ -171,8 +190,10 @@ TreeWork includes a local, read-only Project Map:
 - **Dependency** shows prerequisites and downstream work for one branch.
 - **Replay** reconstructs accepted TreeWork transitions over time.
 
-After the first Tree is accepted, the Agent opens Project Map in the Codex
-in-app browser. The panel projects accepted state; it does not edit the project.
+After the first Tree is accepted, the Agent uses its host adapter's Project Map
+handoff. Codex opens the localhost URL in its in-app browser; Pi returns the URL
+and opens the system browser only on explicit request. The panel projects
+accepted state; it does not edit the project.
 
 ## Design Rationale
 
@@ -204,7 +225,7 @@ Read the formal model and evaluation design in the
 
 ## Package Contents
 
-The installable plugin lives at
+The installable Codex plugin lives at
 [`plugins/treework`](plugins/treework) and includes:
 
 - the staged project-state Skill and Agent-facing references;
@@ -213,12 +234,16 @@ The installable plugin lives at
 - a local read-only MCP server for Recall and Project Map launch;
 - bundled Project Map assets.
 
-TreeWork stores project state under `.TreeWork/`.
+The Pi package manifest and focused extension live under
+[`adapters/pi`](adapters/pi) and directly reuse that same Skill, runtime, and
+MCP server. TreeWork stores project state under `.TreeWork/`; neither host
+adapter creates a second source of truth.
 
 ## Repository Layout
 
 ```text
-plugins/treework/              Installable Codex plugin
+plugins/treework/              Installable Codex plugin and shared runtime
+adapters/pi/                  Focused Pi extension, tests, and host docs
 project-map-ui/               React/D3/SVG Project Map source
 docs/product/                 Product behavior and UX contracts
 docs/architecture/            Runtime and transaction contracts
@@ -231,7 +256,7 @@ while using TreeWork. Maintainer implementation contracts stay under `docs/`.
 
 ## Community and Help Wanted
 
-TreeWork currently ships and is release-tested as a Codex plugin. Support for
+TreeWork currently ships and is release-tested for Codex and Pi. Support for
 Claude Code, Cursor, Gemini CLI, OpenCode, and other agent hosts is welcome
 through focused host adapters.
 
@@ -268,10 +293,11 @@ make validate
 
 ## Status
 
-`v0.1.7` is the current version. Alignment, declarative Tree construction,
-hierarchy-aligned branch documents, protected branch traversal, Recall, Project
-Map, and Replay form a usable end-to-end loop. Project Map interaction design
-will continue to evolve.
+`v0.1.7` is the current runtime version. Alignment, declarative Tree
+construction, hierarchy-aligned branch documents, protected branch traversal,
+Recall, Project Map, and Replay form a usable end-to-end loop. Codex and Pi host
+surfaces share those semantics. Project Map interaction design will continue to
+evolve.
 
 ## Privacy
 

README.zh-CN.md

@@ -10,9 +10,9 @@
 
 # TreeWork
 
-TreeWork 是一个面向 Codex 的**树引导开发插件**。它帮助 Coding Agent 把复杂
-项目组织成一棵 branch 树，在编码前完成重要设计，并在长期开发中沿着树移动而
-不失去方向。
+TreeWork 是一套面向 Coding Agent 的**树引导开发系统**，同时提供 Codex 插件
+和聚焦的 Pi host adapter。它帮助 Agent 把复杂项目组织成一棵 branch 树，在
+编码前完成重要设计，并在长期开发中沿着树移动而不失去方向。
 
 代码检查能够看到已经实现了什么，检索型记忆能够找回历史片段，但两者都不能
 稳定回答项目已经接受了什么、工作进行到哪里，以及上一个 Agent 为什么停下。
@@ -21,12 +21,29 @@ TreeWork 将已接受的项目结构、branch 状态、Spec、进度、结论和
 
 ## 首次安装
 
-TreeWork 当前面向 macOS 和 Linux 上的 Codex。原生 Windows 支持尚未经过发布
-测试。
+TreeWork 当前面向 macOS 和 Linux 上的 Codex 与 Pi。原生 Windows 支持尚未
+经过发布测试。
 
 运行依赖包括 Git、Bash、Python 3、Rust 和 Cargo。Project Map 前端已经打包；
 只有开发前端时才需要 Node.js。
 
+### Pi
+
+直接从本仓库安装 Pi package：
+
+```bash
+pi install git:github.com/Johnny-xuan/TreeWork
+```
+
+重启 Pi，运行 `/treework-adapter` 验证运行时，然后执行 `/skill:treework` 或直接
+要求 Pi 使用 TreeWork。适配器直接复用仓库中的 Skill 和 MCP 服务，按需加载只读
+工具，移植 TreeWork 的写保护与 stop check，并通过显式的 `/treework-enter` 与
+`/treework-return` 命令 fork cwd 绑定的 Pi 会话，把完整对话移入或移出 branch
+worktree。完整安装、使用、验证与回滚方式见
+[TreeWork for Pi](adapters/pi/README.md)。
+
+### Codex 引导安装
+
 把下面这段 prompt 直接交给一个能够使用终端的 Codex Agent：
 
 ```text
@@ -59,7 +76,7 @@ TreeWork。
    后，再进行项目初始化。
 ```
 
-### 手动安装
+### Codex 手动安装
 
 ```bash
 codex plugin marketplace add https://github.com/Johnny-xuan/TreeWork
@@ -157,8 +174,9 @@ TreeWork 包含一个本地只读 Project Map：
 - **Dependency** 展示某个 branch 的前置依赖和下游工作；
 - **Replay** 按时间重建已接受的 TreeWork 状态转移。
 
-第一个 Tree 被接受后，Agent 会在 Codex 内置浏览器中打开 Project Map。面板只
-投影已接受状态，不直接编辑项目。
+第一个 Tree 被接受后，Agent 使用当前 host adapter 提供的 Project Map 交接。
+Codex 会在内置浏览器中打开本地 URL；Pi 返回该 URL，只有在明确请求时才打开系统
+浏览器。面板只投影已接受状态，不直接编辑项目。
 
 ## 设计理由
 
@@ -188,21 +206,23 @@ Agent 在其中移动的有效方式，同时把局部实现决策留给 Agent
 
 ## 插件内容
 
-可安装插件位于 [`plugins/treework`](plugins/treework)，
-其中包括：
+可安装的 Codex 插件位于 [`plugins/treework`](plugins/treework)，其中包括：
 
 - 分阶段项目状态 Skill 及面向 Agent 的参考文档；
 - Rust 编写的 `tw` 事务运行时；
 - branch 状态转移与完成保护 Hooks；
 - 用于 Recall 和启动 Project Map 的本地只读 MCP 服务；
 - 已打包的 Project Map 资源。
 
-TreeWork 将项目状态保存在 `.TreeWork/` 下。
+Pi package manifest 和聚焦的扩展位于 [`adapters/pi`](adapters/pi)，并直接复用
+同一份 Skill、运行时和 MCP 服务。TreeWork 将项目状态保存在 `.TreeWork/` 下；
+两个 host adapter 都不会创建第二事实源。
 
 ## 仓库结构
 
 ```text
-plugins/treework/              可安装的 Codex 插件
+plugins/treework/              可安装的 Codex 插件及共享运行时
+adapters/pi/                  聚焦的 Pi 扩展、测试与 host 文档
 project-map-ui/               React/D3/SVG Project Map 源码
 docs/product/                 产品行为和交互契约
 docs/architecture/            运行时和 transaction 契约
@@ -215,9 +235,8 @@ paper/                        研究论文源码与图片
 
 ## 社区参与
 
-TreeWork 目前以 Codex 插件形式提供，并以 Codex 作为发布测试目标。欢迎贡献者
-通过聚焦的 host adapter，为 Claude Code、Cursor、Gemini CLI、OpenCode 等
-Agent host 增加支持。
+TreeWork 目前为 Codex 和 Pi 提供发布测试支持。欢迎贡献者通过聚焦的 host
+adapter，为 Claude Code、Cursor、Gemini CLI、OpenCode 等 Agent host 增加支持。
 
 当前特别需要贡献者参与的方向包括：
 
@@ -246,9 +265,10 @@ make validate
 
 ## 当前状态
 
-`v0.1.7` 是当前版本。Alignment、声明式 Tree 构建、与 Tree 层级一致的 branch
-文档、受保护的 branch 移动、Recall、Project Map 和 Replay 已经形成可用的
-端到端闭环。Project Map 的交互设计仍会持续演化。
+`v0.1.7` 是当前运行时版本。Alignment、声明式 Tree 构建、与 Tree 层级一致的
+branch 文档、受保护的 branch 移动、Recall、Project Map 和 Replay 已经形成
+可用的端到端闭环，Codex 与 Pi host surface 共享这些语义。Project Map 的交互
+设计仍会持续演化。
 
 ## 隐私
 

RELEASE-NOTES.md

@@ -1,5 +1,22 @@
 # Release Notes
 
+## Unreleased - Pi Host Adapter
+
+- Adds a focused Pi package that directly reuses TreeWork's Skill, Rust runtime,
+  and read-only MCP server without introducing a second project-state model.
+- Keeps Pi's always-active Agent-tool surface to one deferred loader for Recall,
+  Check, and Project Map; explicit host commands own cwd-bound Enter and Return.
+- Ports machine-owned-state protection and the stop-check boundary to Pi
+  extension lifecycle events.
+- Makes `/treework-enter` wait for Pi to become idle, prepares the conversation
+  fork before the state transition, and recovers cancelled switches by pausing
+  the branch and removing the unused fork.
+- Forks the current Pi conversation into managed branch worktrees and back to
+  the control workspace so cwd-bound tools and project context reload without
+  losing history.
+- Adds guardrail, MCP, package-load, and real offline Pi RPC round-trip tests,
+  plus reversible installation and rollback documentation.
+
 ## v0.1.7 - Hierarchical Branch Artifacts
 
 - Projects branch documents onto the same parent-child hierarchy as the