diff --git a/.changeset/agent-workflows-guide-cleanup.md b/.changeset/agent-workflows-guide-cleanup.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/agent-workflows-guide-cleanup.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/docs/agent-workflows.md b/docs/agent-workflows.md index 4dbcfa842..646d7baac 100644 --- a/docs/agent-workflows.md +++ b/docs/agent-workflows.md @@ -1,158 +1,92 @@ # Agent workflows -Use Hunk with agents in two ways: +There are two ways to combine Hunk with a coding agent: -- **Recommended:** steer a live Hunk window from another terminal with `hunk session ...` -- **Alternative:** load prewritten agent notes from a file with `--agent-context` +- **Recommended:** the agent steers a live Hunk window from another terminal with `hunk session ...` +- **Alternative:** load prewritten agent notes from a JSON sidecar with `--agent-context` -## Recommended workflow: steer a live Hunk window +This page is the short human-facing overview. The generated review skill is the +authoritative agent-facing reference for every session command, flag, and error +message — agents should follow the skill, not this page. The hosted guides live +at [hunk.dev/docs](https://hunk.dev/docs/agents/review-with-an-agent/). -1. Open Hunk in one terminal with a normal review command such as `hunk diff` or `hunk show`. -2. Load the Hunk review skill: [`skills/hunk-review/SKILL.md`](../skills/hunk-review/SKILL.md). -3. Ask the agent to use the skill and review the current session. +## Steer a live Hunk window -A good generic prompt is: +1. Open Hunk in one terminal with a normal review command such as `hunk diff` or `hunk show`, and keep it open. +2. In the agent's terminal, locate the bundled skill with `hunk skill path`. +3. Ask the agent to load that file and use it for the review: ```text Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path. ``` -That skill teaches the agent how to inspect a live Hunk session, navigate it, reload it, and leave inline comments. +The skill teaches the agent to inspect the live session, navigate it, reload +it, and leave inline comments — and to never launch the interactive TUI itself. -## How live session control works - -When a Hunk TUI starts, it registers with a local loopback daemon. `hunk session ...` talks to that daemon to find the right live window and control it. - -Most users only need `hunk session ...`. Use `hunk mcp serve` only for manual startup or debugging of the local daemon. - -If `hunk session list` reports no sessions while Hunk is visibly running, the agent sandbox may be blocking loopback access. Probe the daemon directly: - -```bash -curl -s -X POST http://127.0.0.1:47657/session-api \ - -H 'content-type: application/json' \ - --data '{"action":"list"}' -``` - -If this shows sessions, rerun the command with the agent's network/sandbox escalation. If you run the daemon with a custom `HUNK_MCP_PORT`, use that port instead. - -## The commands you will use most - -### Inspect the current review +## What the agent runs -Start here before navigating or commenting: - -```bash -hunk session list -hunk session get --repo . -hunk session review --repo . --json -``` - -- `list` shows the active Hunk windows -- `get --repo .` confirms which live session matches the current repo -- `review --json` returns the loaded file and hunk structure without dumping the full raw patch - -Only add `--include-patch` when an agent truly needs raw unified diff text: - -```bash -hunk session review --repo . --include-patch --json -``` - -### Move the live window to the right place - -Use `navigate` to jump to the file or hunk you want the user to see: +A typical review looks like: ```bash +hunk session list # find live sessions +hunk session review --repo . --json # file/hunk structure, no raw patch hunk session navigate --repo . --file src/App.tsx --hunk 2 -hunk session navigate --repo . --next-comment +hunk session comment add --repo . --file src/App.tsx --new-line 42 --summary "Check this boundary" +hunk session reload --repo . -- show HEAD~1 # swap what the window shows ``` -Use `reload` when you want the already-open Hunk window to show a different diff or commit: +- `--repo ` selects the session by its loaded repo root; pass a session id instead when several windows share one repo. +- `review --json` keeps raw diff text out of agent context; `--include-patch` opts in per call. +- `comment apply --stdin` applies a JSON batch of notes in one call. -```bash -hunk session reload --repo . -- diff -hunk session reload --repo . -- show HEAD~1 -- README.md -``` +Full syntax, advanced reload targeting (`--session-path`, `--source`), and +error remedies are in the skill +([`skills/hunk-review/SKILL.md`](../skills/hunk-review/SKILL.md)). -Notes: - -- always include `--` before the nested Hunk command in `reload` -- `--hunk` is 1-based -- `--next-comment` and `--prev-comment` are handy when an agent is walking the user through existing notes - -### Add comments - -For one note, use `comment add`: - -```bash -hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" -``` - -For multiple notes, use one stdin batch with `comment apply`: - -```bash -printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' \ - | hunk session comment apply --repo . --stdin -``` - -`comment apply` payload items need: - -- `filePath` -- `summary` -- exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine` +## How live session control works -If you want the UI to jump to the new note, add `--focus` to `comment add` or `comment apply`. +Every normal Hunk TUI registers with a local loopback daemon, and +`hunk session ...` asks that daemon for the right live window. Nothing needs to +be started by hand — `hunk daemon serve` exists only for manual startup or +debugging of the daemon. -For comment cleanup and inspection, use: +If `hunk session list` reports no sessions while Hunk is visibly running, the +agent sandbox is likely blocking loopback access. Probe the daemon directly: ```bash -hunk session comment list --repo . -hunk session comment rm --repo . -hunk session comment clear --repo . --file README.md --yes -hunk session comment clear --repo . --all --yes # also clears human `c` notes +curl -s -X POST http://127.0.0.1:47657/session-api \ + -H 'content-type: application/json' \ + --data '{"action":"list"}' ``` -Agents can remove or bulk-clear human notes for cleanup, but cannot create or edit them through the session CLI. - -## Session targeting - -Most commands can target the live session in a few ways: +If that shows sessions, rerun the session command with the agent's +network/sandbox escalation. With a custom `HUNK_MCP_PORT`, use that port +instead. -- `--repo `: most common; matches the live session by its current repo root -- ``: useful when multiple Hunk windows are open for the same repo -- if only one session exists, Hunk can auto-resolve it +## Load agent notes from a file -`reload` also supports some advanced selectors: - -- `--session-path ` targets the live Hunk window by its current working directory -- `--source ` changes where the replacement `diff` or `show` command runs - -For normal worktree use, prefer `--repo /path/to/worktree`. Reach for `--session-path` and `--source` only when you need to repoint an already-open window to another checkout or path. - -## Alternative workflow: load agent comments from a file - -Use `--agent-context` when you already have agent-written rationale or notes in a JSON sidecar file and want to render them beside the diff. +Use `--agent-context` when agent-written rationale already exists as a JSON +sidecar and should render beside the diff: ```bash hunk diff --agent-context notes.json hunk patch change.patch --agent-context notes.json ``` -For a compact real example, see [`examples/3-agent-review-demo/agent-context.json`](../examples/3-agent-review-demo/agent-context.json). +For a compact real example, see +[`examples/3-agent-review-demo/agent-context.json`](../examples/3-agent-review-demo/agent-context.json). -## Opt into experimental rich notes +## Experimental rich notes (STML) -STML note bodies are experimental and disabled by default. Start a new review with `--experimental` to render sidecar `markup` fields and accept live comments that carry markup: +STML markup note bodies are off by default. Start the review with +`--experimental` to render sidecar `markup` fields and accept live comments +that carry markup: ```bash hunk --experimental diff --agent-context notes.json -# Equivalent: hunk diff --experimental --agent-context notes.json ``` -Normal reviews keep using each annotation's required plain-text `summary` fallback. Opted-in live sessions list `stml` in `hunk session context --json` under `experimentalFeatures`; reload commands cannot change the launch opt-in. - -## Practical defaults - -- start with `hunk session review --repo . --json` -- only add `--include-patch` when the raw patch is actually needed -- use `comment add` for one-off notes and `comment apply` for batches -- prefer `--repo` over `--session-path` unless you have a specific advanced reload case +Plain-text `summary` fields stay required as the fallback, and a reload cannot +change the launch opt-in. Agents check support via `experimentalFeatures` in +`hunk session context --json` and learn the markup language from +`hunk markup guide`.