@polygraph/claude-plugin 0.5.1 → 0.5.3

package/skills/polygraph/reference/delegation.md

@@ -30,7 +30,29 @@ spawn_agent(
 
 Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, what "done" looks like, and what to report back. The child has its own repo and its own context; it inherits nothing from yours.
 
-Delegate to several repos in parallel by calling `spawn_agent` once per repo before waiting on any of them.
+Delegate to several repos in parallel before waiting on any of them, and prefer one call over N. There are three shapes, the same three `polygraph agent spawn` takes:
+
+- **One repo** — `repo` with an `instruction`.
+- **Several repos, one task** — `repos` with one `instruction`, run verbatim in each.
+- **Several repos, different tasks** — `specFile`, a JSON file you write, whose path you pass.
+
+Batching pays because the shared text is transmitted once rather than once per repo, and every sibling starts from a byte-identical prompt prefix that can be served from cache. Each id still gets its own poller.
+
+The spec file is the many-to-many form. Each entry names a repo and carries its own `instruction`, and optionally its own `context`, `role`, `agent`, and `model`. Whatever the entries share goes in `sharedInstruction` / `sharedContext`, which are prepended to each entry's own text with a blank line between — so the common brief stays one identical prefix and only the per-repo part varies. An entry may carry no `instruction` of its own and rely entirely on the shared one. Being a file, it also carries a brief too large to pass as an argument, and it is straightforward to generate programmatically.
+
+```jsonc
+{
+  "sharedInstruction": "Brief every child gets, verbatim.",
+  "sharedContext": "Optional background every child gets.",
+  "agents": [
+    { "repo": "api", "instruction": "Add the expand parameter to the endpoint." },
+    { "repo": "people", "instruction": "Consume it in the client.", "context": "This repo still pins the old SDK." },
+    { "repo": "planets", "role": "reviewer", "agent": "codex", "instruction": "Review the change against the shared brief." }
+  ]
+}
+```
+
+One qualifier is load-bearing: share only what is genuinely shared. Flattening several different tasks into one `sharedInstruction` to look efficient produces worse work, and the round trips to repair it cost more than the batch saved. Work that differs belongs in each entry's own `instruction`, which is what the file is for.
 
 **Own-repo rule.** With the default role, `repo` must be a repository other than the one you are working in — never delegate into your own repo with the default role; work on it directly (ordinary local subagents are fine for that). Delegating into your own repo IS allowed with an explicit non-default `role`, because each (repo, role) pair is a separate agent slot and the child then runs alongside your own default-role work without colliding with it.
 
@@ -75,6 +97,8 @@ show_agent(sessionId: "<sessionId>", id: "<id>")
 
 One-off unwaited reads like this are cheap and expected inline. It is the *waiting* that belongs in a subagent, not the reading.
 
+When several pollers have exited, a **batch read** collects their results in one unwaited call: pass the list of ids and correlate each result by its delegation id.
+
 ## When the result is not enough
 
 Only if `result.text` is missing, truncated, or the child failed in a way you cannot explain from it:

package/skills/polygraph/reference/publish-changes.md

@@ -1,6 +1,6 @@
 # Publishing Changes Reference
 
-The branch-to-PR flow: push branches, create draft PRs, mark them ready, and associate PRs created outside Polygraph. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy — read [`session-description.md`](session-description.md) before writing one.
+The branch-to-PR flow: push branches, create draft PRs, mark them ready, associate PRs created outside Polygraph, and update associated PRs. `push_branch`, `create_pr`, and `associate_pr` all require a `description` following the Session Description Policy — read [`session-description.md`](session-description.md) before writing one. `update_pr` does not require a session timeline description.
 
 ## Push Branches
 
@@ -151,3 +151,50 @@ associate_pr(
 ```
 
 **Returns** the list of PRs now associated with the session.
+
+## Update an Associated PR
+
+Use the MCP `update_pr` tool to update one PR already associated with the named Polygraph session. Do not use `gh` or call Ocean HTTP directly. `mark_pr_ready` remains a separate operation.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID.
+- `prUrl` (required): The URL of a PR already associated with the session.
+- `title` (optional): Replacement PR title.
+- `body` (optional): Replacement user-authored PR body. Pass an empty string to clear it. The managed Polygraph session footer remains server-owned.
+- `labels` (optional): A collection update with `mode` and `values`.
+- `assignees` (optional): A collection update with `mode` and `values`.
+
+Omitted fields remain unchanged. For `labels` and `assignees`:
+
+- `{ mode: "set", values: [...] }` replaces the complete collection. An empty `values` list clears it. Use `set` only when you intend to replace every value because it can remove labels or assignees applied by humans.
+- `add` and `remove` preserve unrelated values and require a non-empty `values` list.
+
+Set the complete label collection and clear the user-authored body:
+
+```
+update_pr(
+  sessionId: "<session-id>",
+  prUrl: "https://github.com/org/repo/pull/123",
+  body: "",
+  labels: {
+    mode: "set",
+    values: ["documentation", "release-note"]
+  }
+)
+```
+
+Add an assignee while leaving the title, body, labels, and other assignees unchanged:
+
+```
+update_pr(
+  sessionId: "<session-id>",
+  prUrl: "https://github.com/org/repo/pull/123",
+  assignees: {
+    mode: "add",
+    values: ["octocat"]
+  }
+)
+```
+
+Metadata updates do not require a session timeline `description`.

package/skills/polygraph/reference/session-description.md

@@ -4,7 +4,7 @@
 
 `description` is user-facing Polygraph session context.
 
-`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
+`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). Metadata updates through `update_pr` do not require a session timeline description, and `mark_pr_ready` does not take one. The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
 
 ```markdown
 ## Goal