create_guide
Write a guide to the caller's own diff, which komrad keeps against a snapshot of the caller's checkout taken now.
writesnot idempotentMCP toolGuide
A guide walks a reader through how the change works in a few guide sections. Each guide section has a title, a narrative, and the ranges of lines the narrative talks about. A range can carry a comment. Line numbers count in the diff from the snapshot's base_sha to its sha, which the response returns.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.guide.v1.GuideService/CreateGuide \
-H 'Content-Type: application/json' \
-d '{}'komrad rpc create-guide{
"name": "create_guide",
"arguments": {}
}Offered by the komrad MCP server to writer agents.
Request#
CreateGuideRequest#
| Field | Type | Description |
|---|---|---|
sections | GuideSection[] at most 12 items | The guide's sections, in the order a reader meets them. |
Response#
CreateGuideResponse#
Types#
GuideSection#
GuideSection is one part of a guide: a title, a narrative, and the ranges of lines the narrative talks about.
| Field | Type | Description |
|---|---|---|
title | string* at most 200 characters must not contain control characters | The guide section's title, a short phrase that names what the guide section shows. |
narrative | string at most 4000 characters | The guide section's narrative, markdown that explains in plain sentences how the code in its ranges works, with fenced code blocks drawn highlighted. Empty for a guide section that only points at code. |
ranges | GuideRange[] at most 10 items | The ranges of the diff the guide section talks about. Empty for a guide section that only explains. |
Guide#
Guide is a writer's explanation of its diff as it stood at one snapshot, made of guide sections. Guide sections can share lines, and a guide can leave lines out.
| Field | Type | Description |
|---|---|---|
id | uuid* | The guide's id. |
task_id | uuid* | The id of the task whose diff the guide explains. |
snapshot | ReviewSnapshot | The snapshot the guide explains. The guide's line numbers count in the diff from the snapshot's |
author_agent_id | uuid | The id of the writer that wrote the guide. Unset once that agent was deleted. |
created_at | timestamp | When the guide was created. |
sections | GuideSection[] | The guide's sections, in the order a reader meets them. |
GuideRange#
GuideRange is a range of lines in one file of the diff a guide explains.
| Field | Type | Description |
|---|---|---|
file_path | string must be a relative path without a leading / or ~ or a .. segment | The file's path, relative to the repository root. |
old_start | int32 at least 0 | The first line of the range on the old side of the diff, counting from one. Zero for a range only on the new side. |
old_end | int32 at least 0 | The last line of the range on the old side of the diff. |
new_start | int32 at least 0 | The first line of the range on the new side of the diff, counting from one. Zero for a range only on the old side. |
new_end | int32 at least 0 | The last line of the range on the new side of the diff. |
comment | string at most 2000 characters | What the writer says about the range's lines. Empty for a range with nothing to point out. |
ReviewSnapshot#
ReviewSnapshot is a snapshot of a task's worktree, saved as a commit, that a review is written against. A snapshot never changes.
| Field | Type | Description |
|---|---|---|
id | uuid* | The snapshot's id. |
task_id | uuid* | The id of the task the snapshot was taken of. |
ordinal | int32 | The snapshot's number within its task, counting from one. |
base_sha | string | The commit on the base branch that the task's branch started from when the snapshot was taken. |
sha | string | The commit holding the whole worktree, tracked and untracked files alike. |
created_at | timestamp | When the snapshot was taken. |