Merge pull request #25 from NickyLam/feat/pi-host-adapter

feat(hosts): add Pi coding agent host adapter

Author: phodal

CHANGELOG.md

@@ -5,12 +5,25 @@ observable behavior and compatibility, not every internal refactor.
 
 ## Unreleased
 
+### Added
+
+- Pi (pi.dev) is now a supported analysis-capable source-local host. The
+  repository installs as a pi package (`pi install <repo>`) through a `pi`
+  manifest in `package.json`, registers a `/better-harness` prompt template,
+  and gains a Pi configured-asset provider (settings-declared pi packages,
+  skills, prompt templates, extensions, and `AGENTS.md` context) plus a Pi
+  session-evidence adapter that reads workspace-matching JSONL v3 transcripts
+  under `~/.pi/agent/sessions/` with `PI_CODING_AGENT_DIR` and
+  `PI_CODING_AGENT_SESSION_DIR` overrides. Pi's shell is the `pi` manifest in
+  the existing `package.json`, so the public npm package still ships six host
+  metadata roots and the Qoder runtime bundle remains Qoder-specific.
+
 ### Changed
 
 - The `harness analyze` platform gate now names the full supported set
-  (`qoder, codex, claude, cursor, qwen, copilot`) when it rejects an unsupported
-  `--platform`, matching the session-analysis and asset-baseline gates. The
-  existing error prefix and exit behavior are unchanged.
+  (`qoder, codex, claude, cursor, qwen, copilot, pi`) when it rejects an
+  unsupported `--platform`, matching the session-analysis and asset-baseline
+  gates. The existing error prefix and exit behavior are unchanged.
 
 ## 0.3.0 - 2026-07-27
 

README.md

@@ -343,6 +343,34 @@ Qwen Code produces a self-contained `report.html` with paired `report.md` and
 `findings.json`. Session evidence coverage depends on Qwen Code's available
 transcript paths; missing or partial evidence remains explicit.
 
+### Pi
+
+Install the repository as a [pi package](https://pi.dev/docs/latest/packages):
+
+```bash
+pi install https://github.com/QoderAI/better-harness
+```
+
+Or try it for a single run without changing settings:
+
+```bash
+pi -e git:github.com/QoderAI/better-harness
+```
+
+Pi discovers the `better-harness` Skill and the `/better-harness` prompt
+template through the `pi` manifest in `package.json`. Start a new Pi session
+in the repository you want to review and run the report prompt:
+
+```text
+/better-harness review this project's AI coding workflow and generate a report
+```
+
+Pi defaults to a self-contained `report.html` with paired `report.md` and
+`findings.json` under the repository's `.pi/better-harness` report root. Pi
+session evidence is read from workspace-matching JSONL transcripts under
+`~/.pi/agent/sessions/`; missing evidence stays explicit rather than being
+inferred.
+
 ## Develop and package from source
 
 Development requires Node.js `>=22.20.0 <25.0.0` and npm

README.zh-CN.md

@@ -325,6 +325,31 @@ qwen extensions install QoderAI/better-harness
 Qwen Code 产出自包含的 `report.html`，并配套 `report.md` 与 `findings.json`。
 会话证据覆盖范围取决于 Qwen Code 可用的会话记录路径；缺失或不完整的证据保持显式标注。
 
+### Pi
+
+将本仓库作为 [pi package](https://pi.dev/docs/latest/packages) 安装：
+
+```bash
+pi install https://github.com/QoderAI/better-harness
+```
+
+或在不修改设置的情况下单次试用：
+
+```bash
+pi -e git:github.com/QoderAI/better-harness
+```
+
+Pi 通过 `package.json` 中的 `pi` manifest 发现 `better-harness` Skill 和
+`/better-harness` 提示模板。在需要审查的仓库中启动新的 Pi 会话，运行报告提示词：
+
+```text
+/better-harness 审查此项目的 AI 编码工作流并生成报告
+```
+
+Pi 默认在仓库的 `.pi/better-harness` 报告根目录下生成自包含的 `report.html`
+及配套的 `report.md` 和 `findings.json`。Pi 会话证据读自
+`~/.pi/agent/sessions/` 下与工作区匹配的 JSONL 会话记录；缺失的证据会被明确标注而不会被推断。
+
 <a id="develop-and-package-from-source"></a>
 
 ## 从源码开发和打包

docs/adapters/README.md

@@ -1,9 +1,9 @@
 # Host Adapter Matrix
 
-This is the single entry point for Claude Code, Codex, Qoder, Cursor, Qwen, and
-GitHub Copilot host boundaries. Do not create `docs/adapters/claude-code.md`,
+This is the single entry point for Claude Code, Codex, Qoder, Cursor, Qwen,
+GitHub Copilot, and Pi host boundaries. Do not create `docs/adapters/claude-code.md`,
 `docs/adapters/codex.md`, `docs/adapters/qoder.md`, `docs/adapters/cursor.md`,
-`docs/adapters/qwen.md`, or `docs/adapters/copilot.md` by default.
+`docs/adapters/qwen.md`, `docs/adapters/copilot.md`, or `docs/adapters/pi.md` by default.
 
 Adding another host? Follow
 [Contributing a New Coding Agent Host](contributing-new-coding-agent.md) before
@@ -16,11 +16,13 @@ providers, real session-evidence adapters, and output modes. Canonical product
 judgment stays in `skills/`, `models/`, `references/`, `templates/`, and
 `scripts/<capability>/`.
 
-The `@qoderai/better-harness` npm package includes the Qoder, Claude Code,
-Codex, Cursor, Qwen, and GitHub Copilot plugin metadata roots. The generated
-Qoder runtime bundle includes only the Qoder shell, `.qoder-plugin/`; non-Qoder
-generated host artifacts remain source-local. Claude Code installs its shell
-through the repository's native marketplace manifest.
+The `@qoderai/better-harness` npm package includes six filesystem metadata
+roots for Qoder, Claude Code, Codex, Cursor, Qwen, and Copilot, plus Pi install
+metadata in the existing `package.json`. The generated Qoder runtime bundle
+includes only the Qoder shell, `.qoder-plugin/`; non-Qoder generated host
+artifacts remain source-local. Claude Code installs its shell through the
+repository's native marketplace manifest. Pi installs the repository as a pi
+package through the `pi` manifest in `package.json`.
 
 | Host | Positioning | Shell | Configured Assets | Session Evidence | Default Output | Rules / Prompts | Smoke |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -30,6 +32,7 @@ through the repository's native marketplace manifest.
 | Cursor | Analysis-capable source-local host | `.cursor-plugin/` | `scripts/agent-customize/providers/cursor.mjs` | `scripts/session-analysis/platforms/cursor.mjs` | self-contained HTML + Markdown | `.cursor` + `.codex` compatibility + `AGENTS.md` | `agent --plugin-dir . --mode ask --print` -> Cursor evidence bundle -> validated `html` render |
 | Qwen Code | Analysis-capable source-local host | `qwen-extension.json` | `scripts/agent-customize/providers/qwen.mjs` | `scripts/session-analysis/platforms/qwen.mjs` | self-contained HTML + Markdown | `.qwen` + `QWEN.md` + `AGENTS.md` | `harness prepare --platform qwen` -> finalize with `html-report` validation |
 | GitHub Copilot | Analysis-capable source-local host | `.github/plugin/` | `scripts/agent-customize/providers/copilot.mjs` | `scripts/session-analysis/platforms/copilot.mjs` | self-contained HTML + Markdown | `.github` + `AGENTS.md` + `~/.copilot` | `copilot plugin marketplace add .` -> `copilot plugin install better-harness@better-harness` -> configured-asset baseline -> validated `html` render |
+| Pi | Analysis-capable source-local host | `pi` manifest in `package.json` | `scripts/agent-customize/providers/pi.mjs` | `scripts/session-analysis/platforms/pi.mjs` | self-contained HTML + Markdown | `.pi` + `.agents` + `AGENTS.md` | `pi install <source>` or `pi -e <source>` -> `/better-harness` prompt template -> validated `html` render |
 
 ## Discovery And Evidence
 
@@ -79,13 +82,25 @@ through the repository's native marketplace manifest.
   `.github/plugin/` shell is native Copilot install/discovery metadata included
   in the public npm package; it does not own Copilot evidence collection.
 
+- Pi configured assets are inventoried through
+  `scripts/agent-customize/providers/pi.mjs`, covering `~/.pi/agent`
+  (settings-declared pi packages, skills, prompt templates, extensions, the
+  global `AGENTS.md` context file), the shared `.agents/skills` directories,
+  and project `.pi` assets. Session evidence comes from
+  `scripts/session-analysis/platforms/pi.mjs`, which reads workspace-matching
+  JSONL transcripts under `~/.pi/agent/sessions/--<cwd-slug>--/` and honors the
+  `PI_CODING_AGENT_DIR` and `PI_CODING_AGENT_SESSION_DIR` overrides. Pi
+  discovers the canonical root `skills/` directory and the `prompts/`
+  templates through the `pi` manifest in `package.json`; that manifest is
+  install/discovery metadata and does not own Pi evidence collection.
+
 ## Output Modes
 
 Canonical templates live under `templates/reporting/`.
 
 - `qoder-canvas.md`: Qoder Canvas output contract, covering renderer-owned
   `findings.json`, Canvas-only `canvas.json`, and `report.canvas.tsx`.
-- `html-visual.md`: portable Claude Code/Codex/Cursor/Qwen/Copilot visual output contract, covering
+- `html-visual.md`: portable Claude Code/Codex/Cursor/Qwen/Copilot/Pi visual output contract, covering
   `findings.json`, `report.md`, and `report.html`.
 - Markdown-only output has no visual companion.
 

docs/adapters/contributing-new-coding-agent.md

@@ -134,7 +134,7 @@ sessions, reports, and packaging have different owners. Search for the existing
 host set before editing:
 
 ```bash
-rg -n "qoder|codex|claude|cursor|qwen|copilot" scripts test references templates docs package.json
+rg -n "qoder|codex|claude|cursor|qwen|copilot|pi" scripts test references templates docs package.json
 ```
 
 Use the results as an inventory, not a replacement template. Typical registration

docs/adrs/directory-structure.md

@@ -76,7 +76,7 @@ scripts/
   core-change-watch/               # [active] static structure/core-path/history evidence
   session-analysis.mjs                 # [active] thin shim; new exports -> scripts/session-analysis/
   session-analysis/                    # [active] session evidence collection/normalization
-    platforms/<host>.mjs               # Qoder/Codex/Claude/Cursor/Qwen/Copilot host adapters
+    platforms/<host>.mjs               # Qoder/Codex/Claude/Cursor/Qwen/Copilot/Pi host adapters
     ides/<ide>/                        # target editor-local evidence not covered by host adapters
   <business-capability>/               # [target] new capability owner
     cli.mjs                            # use cli.mjs for new capabilities

docs/community.md

@@ -37,7 +37,7 @@ This is the complete reference. For the common cases, see Start Here above.
 | Style grammar | Yes | `templates/style/` | Directive-only visual language; no runnable skeletons | Selected by report/style routing | Style-template tests and no copied runtime skeletons |
 | Structured knowledge | Candidate only | `knowledge-base/{official,community}/...` | `knowledge.md`, interim `schema.json`, fixtures, namespace uniqueness | Docs-only until registry spec, compiler, and binding tests exist | Namespace check, schema/fixture review, migration note |
 | Examples and operating models | Yes | `case-studies/` | Named example, scope, evidence boundary, non-runtime status | Reference material only unless separately bound | Link/path check; no runtime-policy claims |
-| Host shell and packaging | Thin, or generated only after a split trigger | `.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`, `qwen-extension.json`, future lifecycle shells | Install/discovery metadata and pointers to canonical owners | Public npm package includes all six current metadata roots; the Qoder runtime bundle includes only `.qoder-plugin/`, and generated host artifacts stay source-local | `scripts/npm-package/` verification, or split adapter note plus target builder |
+| Host shell and packaging | Thin, or generated only after a split trigger | `.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`, `qwen-extension.json`, the `pi` manifest in `package.json`, future lifecycle shells | Install/discovery metadata and pointers to canonical owners | Public npm package includes all six current metadata roots; the Qoder runtime bundle includes only `.qoder-plugin/`, and generated host artifacts stay source-local | `scripts/npm-package/` verification, or split adapter note plus target builder |
 
 ## Non-Extension Boundaries
 

docs/concepts.md

@@ -73,7 +73,7 @@ until you need diagnosis. See [../models/routing.md](../models/routing.md).
 | Project evidence | `better-harness core-change-watch` | Project, history, core-path, and diff signals |
 | Change confidence | `hooks/git-scripts/blast-radius` | Symbol-graph blast radius of a change |
 | Dependency governance | `better-harness dependency-governance` | Update automation, audit, stale-dep signals |
-| Session evidence | `better-harness session-analysis` | Normalize Qoder, Codex, Claude, Cursor, Qwen, or Copilot session behavior |
+| Session evidence | `better-harness session-analysis` | Normalize Qoder, Codex, Claude, Cursor, Qwen, Copilot, or Pi session behavior |
 | Agent assets | `better-harness coding-agent-practices inventory` | Inventory configured agent surfaces |
 | Guardrails | `hooks/`, `scripts/agent-guardrails` | Secret scanning and lifecycle checks |
 

docs/glossary.md

@@ -60,7 +60,7 @@ for extension surfaces, read [community.md](community.md).
 | `core-change-watch` | Project, history, core-path, and current-diff evidence collection. | [scripts/core-change-watch](../scripts/core-change-watch) |
 | Blast radius | The symbol-graph reach of a change, computed with tree-sitter (JS/TS, Go, Python) as a git hook. | [hooks/git-scripts/blast-radius](../hooks/git-scripts/blast-radius) |
 | `dependency-governance` | Update-automation, audit, and stale-dependency signals. | [scripts/dependency-governance](../scripts/dependency-governance) |
-| `session-analysis` | Normalizes Qoder, Codex, Claude, Cursor, Qwen, or Copilot agent session behavior into evidence. | [scripts/session-analysis](../scripts/session-analysis) |
+| `session-analysis` | Normalizes Qoder, Codex, Claude, Cursor, Qwen, Copilot, or Pi agent session behavior into evidence. | [scripts/session-analysis](../scripts/session-analysis) |
 | Guardrails | Change-time enforcement: secret scanning and lifecycle hook checks. | [hooks](../hooks), [scripts/agent-guardrails](../scripts/agent-guardrails) |
 
 ## The Action Loop (Report → Change)
@@ -79,7 +79,7 @@ for extension surfaces, read [community.md](community.md).
 |---|---|---|
 | Skill | A repeatable agent workflow defined by `SKILL.md` frontmatter plus a concise workflow. | [community.md](community.md); report use: [report contract](../skills/better-harness/SKILL.md#report-output) |
 | Host adapter | Per-host discovery and evidence-shape glue (e.g. Qoder, Codex); keeps the engine host-neutral. | [adapters/README.md](adapters/README.md) |
-| Host shell | Thin host metadata (`.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`, `qwen-extension.json`, or a future lifecycle shell) that exposes canonical behavior without owning product logic; the public npm package ships all six current metadata roots, while the Qoder runtime bundle includes only `.qoder-plugin/`. | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| Host shell | Thin host metadata (`.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`, `qwen-extension.json`, the `pi` manifest in `package.json`, or a future lifecycle shell) that exposes canonical behavior without owning product logic; the public npm package ships all six current metadata roots, while the Qoder runtime bundle includes only `.qoder-plugin/`. | [ARCHITECTURE.md](ARCHITECTURE.md) |
 | Canonical owner | The single directory that owns a behavior's product judgment; host shells and mirrors point back to it. | [ARCHITECTURE.md](ARCHITECTURE.md) |
 
 ## "I Want To… → Use"