git ents: docs: add agent skills for the ents comment loop

commit dcf76c9

docs: add agent skills for the ents comment loop

ents-comments drives the CLI loop — enumerate open comments projected onto the working tree, address them, reply, resolve — and covers issues and reviews as comments-on-a-context. ents-zed covers the editor surface and the code-lens-off-by-default gotcha.

docs: add the ents-comments skill for reading and resolving comments docs: add the ents-zed skill for the Zed lens surface Assisted-by: Claude:claude-fable-5

Joseph D. Carpinelli · 1 month ago

tree browse at HEAD · parents: 1ebf59f · comment on this commit

Reviews

No reviews of this commit yet — record a verdict below.

Start a review

.claude/skills/ents-comments/SKILL.md @@ -1,0 +1,144 @@ +--- +name: ents-comments +description: Read, address, and leave git-ents comments — the universal conversational primitive anchored into source. Use when asked to "address the comments", "address all comments in the working tree", act on review feedback, or leave a comment/reply on code. Editor-agnostic: the same `git ents comment` CLI an editor, the web UI, and you all drive. +--- + +# Addressing and leaving ents comments + +A git-ents comment is a body anchored to exact content — a blob, an optional line range, a commit (or the working tree). +Comments live on `refs/meta/comments/*`, one ref each, and carry a `state` (`open` or `resolved`). +Editors, the web UI, and the CLI are three frontends of one mechanism, so a comment left in Zed is the same entity you resolve here. + +Everything below is `git ents comment …`. +Run it from inside the repo. +There is no MCP server and no daemon — just the CLI. + +## The loop: "address all comments in the working tree" + +This is the primary workflow. +A human (or an agent) leaves open comments; you fix the code they point at and resolve them. + +1. **Enumerate open comments, projected onto the working tree.** + Use the porcelain form — it is stable and designed for you to parse: + + ```text + git ents comment list --worktree --open --porcelain + ``` + + Records are blank-line-separated. + Each starts with: + + ```text + <id> <state> <projection> <location> + ``` + + - `<projection>` is `current`, `relocated`, `outdated`, `deleted`, or + + `-` (the comment has no anchor). + It is the anchor projected onto the **working tree's current bytes**, so `current` means the comment still points at the exact code you are looking at. + + - `<location>` is `path:start-end`, or `path` for a whole-file anchor, + + or `-` when there is no anchor or the file is gone. + + - Optional `context <c>` and `parent <id>` lines follow, then the body + + with **every body line prefixed by one tab**. + +2. **Address each open comment.** + Read the location, make the change the comment asks for. + Treat `relocated` as authoritative about where the code moved; treat `outdated`/`deleted` as a signal the comment may no longer apply — read the body and decide, don't blindly resolve. + +3. **Reply if there's something to say**, then **resolve**: + + ```text + git ents comment reply <id> --body "Done — extracted the helper as suggested." + git ents comment resolve <id> + ``` + + Resolving is an ordinary signed mutation on the comment's ref, never a deletion — the thread stays auditable. + Reopen with `git ents comment reopen <id>` if you resolved too early. + +Resolve a comment only once the code actually satisfies it. +If you can't address one, leave a reply explaining why and leave it `open`. + +## Reading one thread + +```text +git ents comment show <id> # projected onto HEAD +git ents comment show <id> --worktree # projected onto the working tree +``` + +Shows state, context, parent, the anchored snippet, and body. +To read a whole conversation on an entity (an issue or review), filter by context: + +```text +git ents comment list --context issues/42 --porcelain +``` + +## Leaving a comment + +A comment must be *about* something: an anchor, a context, a parent, or any combination. +A comment about nothing is refused. + +```text +# Anchor to lines of a file at HEAD: +git ents comment add src/gate.rs --lines 40:52 --body "This branch never runs when epoch is unset." + +# Anchor to uncommitted work — the exact bytes on disk right now: +git ents comment add src/gate.rs --lines 40:52 --worktree --body "..." + +# Whole-file comment (omit --lines); comment on a specific revision with --rev. +# Reply (inherits the parent's aboutness, no anchor needed): +git ents comment reply <id> --body "..." +``` + +Comments are signed with `user.signingkey` by default; `--key <path>` overrides. +Anchoring `--worktree` captures the current on-disk bytes, so a remark about uncommitted code stays pinned to exactly what you read even after it's committed or amended. + +## Issues and reviews are made of comments + +Issues and reviews are their own entities, but their *discussion* is ordinary comments carrying the entity as a `context` — so the same loop above works on them. +A context is the entity's ref path below `refs/meta/`, e.g. `issues/42` or `reviews/<id>`. + +### Issues + +```text +git ents issue list +git ents issue show <id> +git ents issue new --title "Gate rejects a valid signature" --body "..." +git ents issue new # omit --title to compose in $GIT_EDITOR/$EDITOR +git ents issue edit <id> --state closed # also --label, --assignee +git ents comment add --context issues/42 --body "I can repro this." +git ents comment list --context issues/42 --porcelain # the issue's thread +``` + +`issue new` with no `--title` opens an editor on a scratch file: first line is the title, the rest is the body, `#` lines are stripped, an empty title aborts. + +### Reviews + +A review is a verdict plus a body about a commit, and it occupies **two refs**: the entity at `refs/meta/reviews/<id>` and a retention pin at `refs/meta/pins/reviews/<id>` that keeps the reviewed commit reachable. +`review new` writes both. + +```text +git ents review new --target HEAD --verdict approve --body "LGTM." +git ents review new --target <rev> --verdict request-changes --body "..." +git ents review list [--target <rev>] +git ents review show <id> # verdict, body, and its comment thread +# Line-level review notes are just anchored comments in the review's context: +git ents comment add src/gate.rs --lines 40:52 --context reviews/<id> --body "..." +``` + +Verdicts are free-form strings; `approve` and `request-changes` are conventions, not a fixed set. + +## Notes + +- Prefer `--porcelain` for anything you parse; the default output is for + humans and may change. +- `--worktree` is what makes this an *iteration* loop: it projects and + anchors against your live edits, not just committed history. +- Author and time come from each ref's commit chain, never from stored + fields — don't expect an author field in the entity. +- One mechanism everywhere: issues, reviews, and line comments are all + comments-on-a-context or their own small entities on `refs/meta/*`, + the same ones the editor lens and the web UI read and write.

.claude/skills/ents-zed/SKILL.md @@ -1,0 +1,44 @@ +--- +name: ents-zed +description: Use git-ents comments inside the Zed editor via the ents-zed extension and the ents-lens language server. Use when working in Zed and asked to see, leave, or resolve inline comments, or to set up the editor for the ents comment loop. +--- + +# ents in Zed + +The `ents-zed` extension (at `editors/zed/`) registers a language server, `ents-lsp`, that runs `git ents lsp`. +The server projects the repo's comments (`refs/meta/comments/*`) into whatever buffer you have open and lets you leave new ones — no MCP, no network, just an LSP over stdio reusing the local composition root. + +The language server is the same mechanism the CLI and web UI use (`lens.parity`), so a comment left in Zed is readable and resolvable from `git ents comment` and the web, and vice versa. +If you are acting on comments programmatically rather than through the editor, use the `ents-comments` skill (the CLI) instead — it is the same entities. + +## Setup + +1. `git ents lsp` must be on `PATH` (build/install the `git-ents` binary). + The extension launches `git` with `ents lsp` and speaks LSP over stdio. +2. Install the extension as a dev extension: Zed → command palette → + `zed: install dev extension` → pick `editors/zed`. +3. **Turn on code lenses.** + Zed renders LSP code lenses but they are **off by default**. + Enable them, or the inline comment lenses won't show: + - setting: `"code_lens": "on"`, or + - command palette: `editor: toggle code lens`. + +## What renders + +- **Code lenses** at each open comment's projected line (once enabled): + the id, a summary, and View / Reply / Resolve actions. +- **Hint diagnostics** for the same comments — these show inline **even without code lenses enabled**, which is why the server publishes them (`lens.diagnostics`). + They are hints, never warnings or errors. +- **Hover** over a commented range shows the full thread. +- **Code action** on a selection ("leave an ents comment") to compose a + new comment; see the crate's compose flow for how saving creates it. + +## Composing a comment + +Trigger the code action on the lines you want to anchor to. +It opens a template file (git-commit style: first content is the body, `#` lines are ignored, an empty body aborts). +Saving a non-empty body creates the comment, anchored to the working-tree bytes you selected. + +Because everything is the one mechanism, the iteration loop is: leave comments in Zed, then tell an agent to "address all comments in the working tree" (the `ents-comments` skill) — it reads the same open comments, fixes the code, replies, and resolves them, and your next Zed publish reflects the resolutions. + +See `editors/zed/README.adoc` for the authoritative, version-tracked notes on exactly which surfaces the current Zed renders.