Skip to content

Commit 09a56e9

Browse files
benvinegarbenvinegar
authored
docs: add bundled Pi review skill (#42)
* docs: add bundled Pi review skill * docs: focus Pi skill on MCP review * docs: clarify MCP-first Hunk workflow
1 parent 7f1f9d1 commit 09a56e9

5 files changed

Lines changed: 275 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,31 @@ Ready-to-run demo diffs live in [`examples/`](examples/README.md).
9898

9999
Each example includes the exact command to run from the repository root.
100100

101+
## Pi integration
102+
103+
Hunk ships a bundled Pi skill named `hunk-review`.
104+
105+
Use it from a local checkout:
106+
107+
```bash
108+
pi install /path/to/hunk
109+
# or rely on Pi's project/package discovery while working inside the repo
110+
```
111+
112+
Or install it from the published package:
113+
114+
```bash
115+
pi install npm:hunkdiff
116+
```
117+
118+
Then load it in Pi with:
119+
120+
```bash
121+
/skill:hunk-review
122+
```
123+
124+
The skill explains what Hunk is and how to use Hunk's MCP tools for live code review.
125+
101126
## Config
102127

103128
Hunk reads config from:

‎package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
"files": [
1111
"bin",
1212
"dist/npm",
13+
"skills",
1314
"README.md",
1415
"LICENSE"
1516
],
@@ -72,5 +73,10 @@
7273
"react": "^19.2.4",
7374
"zod": "^4.3.6"
7475
},
75-
"license": "MIT"
76+
"license": "MIT",
77+
"pi": {
78+
"skills": [
79+
"./skills"
80+
]
81+
}
7682
}

‎skills/hunk-review/SKILL.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
name: hunk-review
3+
description: Use when the task involves Hunk or Hunk MCP review sessions. Helps Pi briefly explain what Hunk is, prefer live Hunk MCP inspection over shell parsing, inspect current review focus, navigate hunks, and leave inline review comments.
4+
compatibility: Requires Hunk from this repo or the published hunkdiff package. Works best with a real TTY for interactive review.
5+
---
6+
7+
# Hunk Review
8+
9+
Use this skill when working with Hunk itself or when the user wants a code-review workflow centered on Hunk.
10+
11+
When this skill activates, start by briefly explaining what Hunk is in plain language before jumping into MCP details.
12+
13+
## What Hunk is
14+
15+
Hunk is a review-first terminal diff viewer for agent-authored changesets.
16+
17+
Keep these product rules in mind:
18+
- the main pane is one top-to-bottom multi-file review stream
19+
- the sidebar is for navigation, not single-file mode switching
20+
- layouts are `auto`, `split`, and `stack`
21+
- `[` and `]` navigate hunks across the full review stream
22+
- agent notes belong beside the code they explain
23+
24+
## Default rule: prefer live MCP review
25+
26+
If a live Hunk session already exists, prefer Hunk's MCP tools over launching new shell commands or scraping terminal output.
27+
28+
The MCP daemon is local-only and brokers commands to one or more live Hunk sessions.
29+
30+
Important behavior:
31+
- normal Hunk sessions auto-start and register with the daemon when MCP is enabled
32+
- `hunk mcp serve` exists for manual startup or debugging
33+
- `HUNK_MCP_DISABLE=1` disables MCP registration for a session
34+
- one daemon can serve many Hunk sessions
35+
36+
## Recommended MCP review loop
37+
38+
Use this flow by default:
39+
1. `list_sessions`
40+
2. `get_selected_context`
41+
3. `navigate_to_hunk` only if the current focus is wrong
42+
4. `comment`
43+
44+
Use `get_session` only when you need broader session metadata.
45+
46+
Guidelines:
47+
- if multiple sessions are live, pass `sessionId` explicitly
48+
- prefer `get_selected_context` before navigating blindly
49+
- use `navigate_to_hunk` for hunk-level movement; do not invent extra remote-control behavior
50+
- use `comment` for concise inline review notes tied to real diff lines
51+
- prefer `reveal: true` unless the user wants a quieter action
52+
53+
For concrete MCP tool behavior and examples, read [references/mcp-review.md](references/mcp-review.md).
54+
55+
## Start Hunk only when needed
56+
57+
If no live Hunk session exists and the user wants an interactive review UI, launch Hunk itself with a minimal command and let it auto-start/register with the MCP daemon.
58+
59+
After launching Hunk, go back to `list_sessions` rather than suggesting manual daemon management.
60+
61+
Inside the Hunk repo, prefer the source entrypoint:
62+
63+
```bash
64+
bun run src/main.tsx -- diff
65+
bun run src/main.tsx -- show HEAD~1
66+
```
67+
68+
Outside the repo, prefer the installed CLI:
69+
70+
```bash
71+
hunk diff
72+
hunk show
73+
```
74+
75+
For more CLI entrypoints, read [references/commands.md](references/commands.md).
76+
77+
## Repo-specific review notes
78+
79+
When using Hunk for agent changes:
80+
- prefer a real TTY or tmux session over redirected stdout captures
81+
- use `hunk diff --agent-context .hunk/latest.json` when the repo has fresh review notes
82+
- refresh `.hunk/latest.json` after code changes if the repo expects it
83+
- keep `.hunk/latest.json` concise and review-oriented
84+
- if new files should show up before commit, use `git add -N <path>`
85+
86+
## What this skill should steer Pi toward
87+
88+
Prefer a skill over a prompt dump:
89+
- keep always-loaded context small
90+
- load the full Hunk workflow only when the task is actually about review
91+
- use Hunk's existing MCP tools rather than ad hoc shell parsing
92+
93+
Prefer review-oriented actions:
94+
- inspect the current live diff session
95+
- move to the right hunk only when needed
96+
- attach concise inline review comments
97+
- keep agent rationale spatially tied to the code

‎skills/hunk-review/references/commands.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Hunk commands for Pi
2+
3+
## Source repo vs installed CLI
4+
5+
Launching Hunk normally should auto-start/register the MCP daemon when MCP is enabled, so Pi usually does not need to run `hunk mcp serve` first.
6+
7+
If Pi is operating inside the Hunk source repo, prefer the source entrypoint so review and validation target the current checkout:
8+
9+
```bash
10+
bun run src/main.tsx -- diff
11+
bun run src/main.tsx -- show HEAD~1
12+
bun run src/main.tsx -- patch -
13+
bun run src/main.tsx -- pager
14+
```
15+
16+
Otherwise use the installed CLI:
17+
18+
```bash
19+
hunk diff
20+
hunk show
21+
hunk patch -
22+
hunk pager
23+
```
24+
25+
## Common review entrypoints
26+
27+
### Review working tree changes
28+
29+
```bash
30+
hunk diff
31+
hunk diff --staged
32+
hunk diff main...feature
33+
```
34+
35+
### Review commits
36+
37+
```bash
38+
hunk show
39+
hunk show HEAD~1
40+
hunk stash show
41+
```
42+
43+
### Review direct file pairs
44+
45+
```bash
46+
hunk diff before.ts after.ts
47+
```
48+
49+
### Review patch input
50+
51+
```bash
52+
git diff --no-color | hunk patch -
53+
```
54+
55+
### Review with agent rationale sidecar
56+
57+
```bash
58+
hunk diff --agent-context .hunk/latest.json
59+
```
60+
61+
Use this when the repo keeps `.hunk/latest.json` fresh for review. Keep that file concise, narrative, and hunk-oriented.
62+
63+
## TTY guidance
64+
65+
For interactive verification:
66+
- prefer a real terminal or tmux pane
67+
- do not rely on redirected stdout captures for behavior verification
68+
- if testing local Hunk source changes, use `bun run src/main.tsx -- ...` instead of an installed `hunk` binary

‎skills/hunk-review/references/mcp-review.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Hunk MCP review flow
2+
3+
Hunk MCP is a local-only loopback daemon that brokers commands to one or more live Hunk review sessions.
4+
5+
## Daemon model
6+
7+
- Normal Hunk sessions auto-start and register with the daemon when MCP is enabled.
8+
- Manual startup is available via:
9+
10+
```bash
11+
hunk mcp serve
12+
```
13+
14+
- Disable MCP registration for one Hunk session with:
15+
16+
```bash
17+
HUNK_MCP_DISABLE=1 hunk diff
18+
```
19+
20+
## Current tool surface
21+
22+
The review-oriented MCP tools are:
23+
- `list_sessions`
24+
- `get_session`
25+
- `get_selected_context`
26+
- `navigate_to_hunk`
27+
- `comment`
28+
29+
## Recommended agent flow
30+
31+
### 1. Discover the target session
32+
33+
Call `list_sessions` first.
34+
35+
If no session exists but the user wants interactive review, launch Hunk (`hunk diff`, `hunk show`, or the source entrypoint in this repo), then come back and call `list_sessions` again.
36+
37+
Use `sessionId` explicitly whenever more than one live session exists.
38+
39+
### 2. Inspect current focus
40+
41+
Call `get_selected_context` to see:
42+
- current file
43+
- current hunk index
44+
- selected hunk old/new ranges
45+
- whether agent notes are visible
46+
- live comment count
47+
48+
This is the best way to respect what the human reviewer is already looking at.
49+
50+
### 3. Move only when needed
51+
52+
If the current focus is wrong, call `navigate_to_hunk` with either:
53+
- `hunkIndex`, or
54+
- `side` + `line`
55+
56+
Prefer hunk-level movement over adding broader remote-control actions.
57+
58+
### 4. Leave inline review notes
59+
60+
Call `comment` with:
61+
- `sessionId`
62+
- `filePath`
63+
- `side`
64+
- `line`
65+
- `summary`
66+
- optional `rationale`
67+
- optional `author`
68+
- usually `reveal: true`
69+
70+
Use concise review comments tied to actual diff lines.
71+
72+
## Practical guidance for Pi
73+
74+
- Prefer MCP tools over scraping terminal text when a live Hunk session already exists.
75+
- Use `get_session` when you need broad session metadata; use `get_selected_context` for fast focus-aware checks.
76+
- In multi-session setups, never assume the sole-session fallback is still safe after new windows open.
77+
- Keep comments review-oriented rather than conversational.
78+
- If the user wants silent inspection rather than visible interaction, avoid unnecessary navigation and only comment when asked.

0 commit comments

Comments
 (0)