You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix(hosts): integrate pi adapter with current main
Resolve PR #25 against the current public-host entrypoint contract while keeping Pi as an analysis-capable source-local host outside the public Quickstart set until an end-to-end interactive report render is observed.
The integration review hardens normalized package identity and effective resource filters, session-header and workspace isolation, relative session roots, provider-home propagation, prompt frontmatter, and canonical HTML report routing. It also keeps the six filesystem metadata roots distinct from Pi's package.json manifest.
Validated with npm run check (913 tests plus package verification), the documentation link graph, focused Pi provider tests, git diff --check, and pack verification from a materialized staged index.
Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
Copy file name to clipboardExpand all lines: README.md
+37-31Lines changed: 37 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,15 +31,25 @@
31
31
<ahref="docs/community.md">Contribute</a>
32
32
</p>
33
33
34
-
## See it in action
34
+
## Quick start
35
35
36
-
Ask `/better-harness` to review the current task and its surrounding project
37
-
Harness, then generate a durable report:
36
+
Review your coding workflow with: [Claude Code](#claude-code), [Codex Desktop](#codex-desktop), [Codex CLI](#codex-cli), [Qoder Desktop/CLI](#qoder), [Cursor](#cursor), [Qwen Code](#qwen-code), or [GitHub Copilot CLI](#github-copilot).
37
+
38
+
Once installed, ask Better Harness to generate the host's durable report:
38
39
39
40
```text
40
41
/better-harness review this project's AI coding workflow and generate a report
41
42
```
42
43
44
+
Better Harness scopes behavior claims to relevant Task Episodes and the
45
+
surrounding project mechanisms. Qoder produces a Canvas report; Claude Code,
46
+
Codex, Cursor, Qwen Code, and GitHub Copilot produce self-contained HTML with
47
+
paired Markdown. Missing or partial evidence remains explicit. See the
48
+
[Host Adapter Matrix](docs/adapters/README.md) for current coverage and output
49
+
differences.
50
+
51
+
## See it in action
52
+
43
53
The report keeps missing evidence explicit and turns supported gaps into
44
54
prioritized findings with an impact, expected output, scoped repair, and
45
55
acceptance checks.
@@ -141,33 +151,6 @@ The architecture keeps the three evidence domains independent until unified
141
151
analysis by the lead agent. Every result retains a visible evidence source,
142
152
owner, and validation route.
143
153
144
-
## Quick start
145
-
146
-
Pick your coding agent — you can be looking at your first report in minutes:
147
-
148
-
| Coding agent | Setup |
149
-
| --- | --- |
150
-
|**Claude Code**| Add the repository marketplace, install `better-harness@better-harness`, start a new session, then use the report prompt below. |
151
-
|**Codex Desktop**| Add the repository under **Settings > Plugins > + Add > From Marketplace**, install Better Harness, start a new task, then invoke `@better-harness`. |
152
-
|**Codex CLI**| Add the Git marketplace, run `codex plugin add better-harness@better-harness`, then invoke `$better-harness:better-harness`. |
153
-
|**Qoder Desktop / CLI**| Nothing to install when Qoder Desktop is installed — Better Harness is built in and available to both. Open your repository and use the report prompt below. |
154
-
|**GitHub Copilot CLI**| Add the repository marketplace, install `better-harness@better-harness`, start a new session, then use the report prompt below. |
155
-
|**Cursor**| Load the plugin from source — see [Installation](#installation). |
156
-
|**Pi**| Install the repository as a pi package: `pi install https://github.com/QoderAI/better-harness`, start a new session, then use `/better-harness` or `/skill:better-harness`. |
157
-
158
-
Once installed, ask Better Harness to generate the host's durable report:
159
-
160
-
```text
161
-
/better-harness review this project's AI coding workflow and generate a report
162
-
```
163
-
164
-
Better Harness scopes behavior claims to relevant Task Episodes and the
165
-
surrounding project mechanisms. Qoder produces a Canvas report; Claude Code,
166
-
Codex, Cursor, Qwen Code, GitHub Copilot, and Pi produce self-contained HTML
167
-
with paired Markdown. Missing or partial evidence remains explicit. See the
168
-
[Host Adapter Matrix](docs/adapters/README.md) for current coverage and output
169
-
differences.
170
-
171
154
## Installation
172
155
173
156
Installation differs by coding agent. Install Better Harness separately for
@@ -210,6 +193,8 @@ stays explicit rather than being inferred.
210
193
211
194
### Codex
212
195
196
+
<aid="codex-desktop"></a>
197
+
213
198
#### Codex Desktop
214
199
215
200
1. Open **Settings > Plugins**.
@@ -229,6 +214,8 @@ Use `https://github.com/QoderAI/better-harness.git` with Git ref `main`.
229
214
230
215
231
216
217
+
<aid="codex-cli"></a>
218
+
232
219
#### Codex CLI
233
220
234
221
Add the repository source:
@@ -337,6 +324,25 @@ transcripts under `~/.copilot/session-state/`. Copilot records no per-response
337
324
token usage, and VS Code Copilot Chat has no supported durable transcript; both
338
325
remain explicit evidence boundaries.
339
326
327
+
### Qwen Code
328
+
329
+
Install Better Harness as a Qwen Code extension:
330
+
331
+
```bash
332
+
qwen extensions install QoderAI/better-harness
333
+
```
334
+
335
+
Start a new Qwen Code session in the repository you want to review and run the
336
+
report prompt:
337
+
338
+
```text
339
+
/better-harness review this project's AI coding workflow and generate a report
340
+
```
341
+
342
+
Qwen Code produces a self-contained `report.html` with paired `report.md` and
343
+
`findings.json`. Session evidence coverage depends on Qwen Code's available
344
+
transcript paths; missing or partial evidence remains explicit.
345
+
340
346
### Pi
341
347
342
348
Install the repository as a [pi package](https://pi.dev/docs/latest/packages):
@@ -351,7 +357,7 @@ Or try it for a single run without changing settings:
351
357
pi -e git:github.com/QoderAI/better-harness
352
358
```
353
359
354
-
Pi discovers the `better-harness`skill and the `/better-harness` prompt
360
+
Pi discovers the `better-harness`Skill and the `/better-harness` prompt
355
361
template through the `pi` manifest in `package.json`. Start a new Pi session
356
362
in the repository you want to review and run the report prompt:
Copy file name to clipboardExpand all lines: docs/adapters/contributing-new-coding-agent.md
+16-1Lines changed: 16 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,6 +36,21 @@ A shell does not prove configured-asset or session support. A session parser doe
36
36
not prove the Skill is natively discoverable. Do not register one slice merely
37
37
to make another slice appear complete.
38
38
39
+
### Capability levels
40
+
41
+
Not every host lands with full end-to-end support. Be explicit about which of
42
+
these levels the contribution reaches, and do not promote a host to the next
43
+
level until the corresponding evidence exists:
44
+
45
+
| Level | What it means | Minimum evidence | Public visibility |
46
+
| --- | --- | --- | --- |
47
+
| Partial adapter | Some slices work (often shell, configured assets, or sessions) while others are partial or unavailable. | Spec names claimed, partial, and unavailable slices; provider/session tests pass for the claimed subset. | Matrix and docs list the host with explicit limitations; do not add to the public Quickstart list. |
48
+
| Verified install/discovery | The native install, link, or discovery command is smoke-tested and the Skill loads. | Native CLI smoke in an isolated home/config when possible; fallback is a pinned official doc reference plus a recorded evidence boundary. | README Installation section may list the host; still not Quickstart unless the report loop is validated. |
49
+
| Public Quickstart-ready | Full report loop works: install/discovery, configured assets, session evidence (when claimed), output routing, and a validated report render. | End-to-end report generation on a real or representative repository; tests cover the public-entrypoint set. | Host appears in the README Quickstart list, Docusaurus home-page cards, and installation tabs. |
50
+
51
+
A host can be merged at the partial or verified level and later promoted to
52
+
public Quickstart-ready once the report loop evidence is complete.
53
+
39
54
## 2. Verify the Native Host Contract
40
55
41
56
Do not derive a new host contract by renaming another adapter. Record the host
@@ -119,7 +134,7 @@ sessions, reports, and packaging have different owners. Search for the existing
119
134
host set before editing:
120
135
121
136
```bash
122
-
rg -n "qoder|codex|claude|cursor|qwen" scripts test references templates docs package.json
137
+
rg -n "qoder|codex|claude|cursor|qwen|copilot|pi" scripts test references templates docs package.json
123
138
```
124
139
125
140
Use the results as an inventory, not a replacement template. Typical registration
Copy file name to clipboardExpand all lines: docs/docs/concepts/glossary.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -66,7 +66,7 @@ progressive detail you load when a task needs it.
66
66
| --- | --- |
67
67
| Skill | A repeatable agent workflow defined by `SKILL.md` frontmatter plus a concise workflow. |
68
68
| Host adapter | Per-host discovery and evidence-shape glue; keeps the engine host-neutral. |
69
-
| Host shell | Thin host metadata (`.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`) that exposes canonical behavior without owning product logic. |
69
+
| 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/`. |
70
70
| Canonical owner | The single directory that owns a behavior's product judgment; host shells and mirrors point back to it. |
Copy file name to clipboardExpand all lines: docs/docs/hosts/adapter-matrix.md
+4-5Lines changed: 4 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,9 +19,8 @@ host-neutral.
19
19
| Claude Code | Analysis-capable source-local host |`.claude-plugin/`| Workspace-matching local Claude transcripts when present | Self-contained HTML + Markdown |
| Qwen Code | Analysis-capable source-local host |`qwen-extension.json`| Workspace-matching JSONL transcripts under `~/.qwen/projects/<slug>/chats/`| Self-contained HTML + Markdown |
23
-
| GitHub Copilot | Analysis-capable source-local host |`.github/plugin/`| Workspace-matching transcripts under `~/.copilot/session-state/<id>/events.jsonl`| Self-contained HTML + Markdown |
24
-
| Pi | Analysis-capable source-local host |`pi` manifest in `package.json`| Workspace-matching JSONL transcripts under `~/.pi/agent/sessions/`| Self-contained HTML + Markdown |
22
+
| Qwen Code | Analysis-capable source-local host |`qwen-extension.json`| Workspace-matching local Qwen transcripts when present | Self-contained HTML + Markdown |
0 commit comments