Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
@polygraph/claude-plugin
Advanced tools
@polygraph/claude-plugin - npm Package Compare versions
| { | ||
| "name": "polygraph", | ||
| "version": "0.4.26", | ||
| "version": "0.4.27", | ||
| "description": "AI agent skills and subagents for Polygraph multi-repo coordination", | ||
@@ -5,0 +5,0 @@ "author": { |
@@ -36,2 +36,4 @@ --- | ||
| `repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo. A repo has at most one active child: if it already has one, pass `taskId` to route the message to it instead of starting a new run. | ||
| **Resume/reconstruction is read-only.** If the parent asks you to resume, reconnect, restore, or reconstruct a preserved session without an explicit new change request from the user, do not call `spawn_agent` to continue work. Use `show_agent` only as needed to read status/log context, return a concise restoration summary, and stop. After resuming, wait for explicit user instructions before any child agent makes changes. | ||
@@ -38,0 +40,0 @@ |
@@ -42,3 +42,3 @@ --- | ||
| **Direct-add rule:** If `sessionId` is provided and the prompt names exact repositories to add by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo` directly with those refs in `repoIds`. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT require candidate discovery first. Candidate discovery is account-repo-only; `list_repos` is only for discovery/filtering when the user does not know the exact repo or explicitly wants candidate selection. | ||
| **Direct-add rule:** If `sessionId` is provided and the prompt names exact repositories to add by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo` directly with those refs in `repoIds`. Refs are not limited to organization repos — public open-source repos can be added by `owner/repo` slug or URL, even though they never appear in `list_repos`. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT require candidate discovery first. Candidate discovery is account-repo-only; `list_repos` is only for discovery/filtering when the user does not know the exact repo or explicitly wants candidate selection. | ||
@@ -119,3 +119,3 @@ ## Workflow | ||
| `repoIds` may be repository IDs from discovery, or exact refs provided by the user: short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax. For exact user-provided refs, pass the strings directly and do not call `list_repos` first. | ||
| `repoIds` may be repository IDs from discovery, or exact refs provided by the user: short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax — including repos outside the organization, such as public open-source repos. For exact user-provided refs, pass the strings directly and do not call `list_repos` first. | ||
@@ -122,0 +122,0 @@ ### Step 4: Get Session Details |
+1
-1
| { | ||
| "name": "@polygraph/claude-plugin", | ||
| "version": "0.4.26", | ||
| "version": "0.4.27", | ||
| "description": "AI agent skills and subagents for Polygraph multi-repo coordination", | ||
@@ -5,0 +5,0 @@ "license": "UNLICENSED", |
| --- | ||
| name: polygraph | ||
| description: Guidance for coordinating changes across multiple repositories using Polygraph. Use when working on a feature that affects another repository, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, discovering how code is consumed across repositories, or starting a multi-repo coordination session. TRIGGER when user mentions "polygraph", "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints. | ||
| description: Guidance for working with Polygraph — repositories, sessions, child agents, PRs, and CI. Use when discovering repositories or how code is consumed across them, starting, joining, resuming, or sharing a Polygraph session, handing off progress, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints. | ||
@@ -10,8 +10,10 @@ allowed-tools: | ||
| # Multi-Repo Coordination with Polygraph | ||
| # Working with Polygraph | ||
| **IMPORTANT:** NEVER `cd` into cloned repositories or access their files directly. ALWAYS use the `spawn_agent` tool to perform work in other repositories. | ||
| **IMPORTANT:** Polygraph keeps local clones only for *other* repositories in the session. NEVER `cd` into those clones or access their files directly — work in other repositories ALWAYS happens through the Polygraph MCP `spawn_agent` tool, invoked via background `polygraph-delegate-subagent` Tasks. | ||
| This skill provides guidance for working on features that span multiple repositories using Polygraph for coordination. | ||
| Polygraph connects repositories and the agent work happening across them. Its central artifact is the session, which groups the repositories, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repositories, and also on its own to share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs. | ||
| **Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`. | ||
| ## Available Tools | ||
@@ -25,6 +27,6 @@ | ||
| | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories | | ||
| | `spawn_agent` | — | Start a new child task or send an explicit follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context?, taskId? }`. Output: `{ taskId, message, status: 'delegated' }`. Pass the `taskId` returned by a prior call to route a follow-up message to a specific active task; omit to start a new child run. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. | | ||
| | `spawn_agent` | — | Start a new child task or send an explicit follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context?, taskId? }`. Output: `{ taskId, message, status: 'delegated' }`. Pass the `taskId` returned by a prior call to route a follow-up message to a specific active task; omit to start a new child run. A repo has at most one active child at a time: while a task is active in a repo, pass `taskId` to follow up — never start a second concurrent run in the same repo. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. | | ||
| | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. | | ||
| | `stop_agent` | — | Cancel an in-progress child. Output: `{ taskId, state: 'cancelled', sessionPreserved: true, output, message }`. Because `sessionPreserved: true`, the preserved agent session can be restored later for context, but resume must wait for explicit user instructions before making changes. | | ||
| | `push_branch` | — | Push a local git branch to the remote repository. Requires a session description. | | ||
| | `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. | | ||
| | `create_pr` | — | Create draft PRs with session metadata linking related PRs | | ||
@@ -37,3 +39,3 @@ | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. | | ||
| | `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. | | ||
| | `complete_session` | `polygraph session archive <id>` | Mark a session complete | | ||
| | `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) | | ||
| | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job | | ||
@@ -45,3 +47,3 @@ | — | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) | | ||
| **Delegation rules:** `list_repos` and `start_session` MUST be called via the `polygraph-init-subagent` as described in step 0. Direct `add_repo` is allowed only when the user provides exact repo refs for an existing session. `spawn_agent` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`) as described in the delegation sections below — NEVER call them directly in the main conversation. | ||
| **Delegation rules:** `list_repos` and `start_session` MUST be called via the `polygraph-init-subagent` as described in step 0. Direct `add_repo` is allowed only when the user provides exact repo refs for an existing session. `spawn_agent` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`) as described in the delegation sections below — NEVER call them directly in the main conversation. The subagents are plugin-namespaced: pass `subagent_type: "polygraph:polygraph-init-subagent"` / `"polygraph:polygraph-delegate-subagent"`; fall back to the bare name only if the namespaced form is not found. | ||
@@ -69,4 +71,6 @@ ## CLI Statefulness | ||
| The delegate/monitor/stop steps apply only when working across repos. A single-repo session skips them and still benefits from shared progress, resume, and CI visibility. | ||
| 0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly with those refs and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session. | ||
| 1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification. | ||
| 1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Parallel delegation across repos is encouraged, but only one active child per repo. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification. | ||
@@ -81,3 +85,3 @@ 4. **Monitor child agents** - Use `show_agent` to poll progress and read the flat `children[]` array for each child's `status` and `lastOutputLines`. | ||
| 11. **Mark PRs ready** - Use `mark_pr_ready` when work is complete. | ||
| 12. **Complete session** - Use `complete_session` to mark the session as completed when the user requests it. | ||
| 12. **Archive session** - Use `archive_session` to archive the session when the user requests it. | ||
@@ -88,7 +92,7 @@ ## Step-by-Step Guide | ||
| There are three cases. Pick exactly one before calling any tool. | ||
| There are three cases. Pick exactly one before calling any tool. The case labels are internal routing shorthand — never mention them in anything you show the user. | ||
| **Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.** | ||
| **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely. Print the session details (format below) and proceed. | ||
| **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely, show the session details (format below), and proceed. | ||
@@ -110,3 +114,3 @@ **Case B — Existing session, no repos yet (or user wants to add more).** If the user gives exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, call `add_repo(sessionId, repoIds: [...])` directly with those refs. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT launch the init subagent just to resolve those refs. If the user wants discovery/filtering instead, launch the `polygraph-init-subagent`, passing both the existing `sessionId` and `userContext`. The subagent will discover candidates, select relevant repositories, and call `add_repo` against the existing session — it will NOT call `start_session`. | ||
| Task( | ||
| subagent_type: "polygraph-init-subagent", | ||
| subagent_type: "polygraph:polygraph-init-subagent", | ||
| description: "Init Polygraph session", | ||
@@ -133,5 +137,5 @@ prompt: """ | ||
| **Case C only — new session just created:** After the init subagent completes and creates the new session, render the session welcome card (skip the session-details block below for this case). Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task). | ||
| **When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task). | ||
| **After receiving the subagent's summary (Case B) or after calling `show_session` for an existing session (Case A), print the session details:** | ||
| **For an existing session — after `show_session` returns or the init subagent's summary arrives — show the session details:** | ||
@@ -172,3 +176,3 @@ **Session:** POLYGRAPH_SESSION_URL | ||
| 6. If the user explicitly asked to inspect or investigate prior work, use the PR descriptions and session summary to decide whether more repo investigation is needed. | ||
| 7. If the repo to investigate is already part of the session, delegate directly to that repo. | ||
| 7. If the repo to investigate is already part of the session, delegate directly to that repo (unless it is the repo you are in — investigate that one directly). | ||
| 8. If the repo to investigate is not currently initialized in the session, and either the user provided an exact repo ref or the repo appears in `<repositories>`, call `add_repo` with that ref or repo `<id>` directly. Do not call `list_repos` just to resolve the repo. | ||
@@ -203,3 +207,3 @@ 9. After `add_repo`, call `show_session` again to verify the repo was added, then delegate to that repo. | ||
| Task( | ||
| subagent_type: "polygraph-delegate-subagent", | ||
| subagent_type: "polygraph:polygraph-delegate-subagent", | ||
| run_in_background: true, | ||
@@ -219,3 +223,3 @@ description: "Delegate to <repo-name>", | ||
| 2. Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time. Read the output files later to check progress. | ||
| 2. Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time — one delegation per repo at a time. Read the output files later to check progress. | ||
| 3. For each child, the subagent watches `child.status` in the flat `children[]` response and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped). | ||
@@ -290,2 +294,4 @@ 4. Once all background subagents report a terminal status, continue to `push_branch` + `create_pr`. | ||
| `push_branch` pushes from the local checkout: for the repo you are in, that is your current working directory with your commits; for delegated repos, it is the Polygraph-managed clone the child agent worked in. There is no separate session copy of the current repo. | ||
| **Parameters:** | ||
@@ -557,2 +563,4 @@ | ||
| **Not limited to your organization:** repos outside the org — including public open-source repos — can be added by GitHub `owner/repo` slug or URL. Only `list_repos` discovery is org-scoped, so a repo missing from `list_repos` can still be added directly. | ||
| **Parameters:** | ||
@@ -566,22 +574,16 @@ | ||
| sessionId: "<session-id>", | ||
| repoIds: ["nrwl/ocean"] | ||
| repoIds: ["org/repo-name", "facebook/react"] | ||
| ) | ||
| ``` | ||
| ### 8. Complete Session | ||
| ### 8. Archive Session | ||
| **IMPORTANT: Only call this tool when the user explicitly asks to complete or close the session.** Do not automatically complete sessions as part of the workflow. | ||
| **IMPORTANT: Only call this tool when the user explicitly asks to archive or close the session.** Do not archive sessions automatically as part of the workflow. | ||
| **Warning:** Completing a session seals it from further modifications. Only complete a session when the user explicitly confirms they are done coordinating the session. | ||
| Use `archive_session` (CLI: `polygraph session archive <id>`) to archive the session. Archiving only hides the session from active lists — it can still be resumed and interacted with afterwards. It is idempotent — archiving an already-archived session returns success. | ||
| Use `complete_session` to mark the session as completed. Completing a session will: | ||
| - **Mark the session as completed** and sealed from further modifications (no new PRs, status changes, etc.) | ||
| This is idempotent — completing an already-completed session returns success. | ||
| **Parameters:** | ||
| - `sessionId` (required): The Polygraph session ID | ||
| - `clean` (optional): Remove local session worktrees after marking the session complete | ||
| - `clean` (optional): Remove the local clones Polygraph created for delegated repos after archiving | ||
@@ -591,6 +593,6 @@ **Returns:** | ||
| - `sessionId`: The session ID | ||
| - `completed`: Boolean indicating completion status | ||
| - `completed`: Boolean indicating the session is archived | ||
| ``` | ||
| complete_session( | ||
| archive_session( | ||
| sessionId: "<session-id>" | ||
@@ -600,8 +602,4 @@ ) | ||
| **When to call:** | ||
| **When to call:** all work is finished, PRs are created and marked ready, and the user explicitly confirms they are done with the session. | ||
| - After all cross-repo work is finished | ||
| - All PRs have been created and marked ready for review | ||
| - The user explicitly confirms they want to close all PRs and seal the session | ||
| ## Other Capabilities | ||
@@ -698,2 +696,2 @@ | ||
| 1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed. The child's session is preserved (`sessionPreserved: true`) so the context can be restored later, but after resuming you must wait for explicit user instructions before making changes. | ||
| 1. **Only complete sessions when asked** — Only call `complete_session` when the user explicitly requests it. Completing a session seals it from further modifications. Do not automatically complete sessions. | ||
| 1. **Only archive sessions when asked** — Only call `archive_session` when the user explicitly requests it. Archiving hides the session from active lists; it can still be resumed later. |
No alert changes
Improved metrics
- Total package byte prevSize
99201
2.87%No dependency changes