@polygraph/cursor-plugin 0.4.51

package/skills/pack-and-copy/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: pack-and-copy
+description: Validate a publisher package change against consumer repos by building + packing the publisher and installing the tarballs into each consumer, so consumer CI can run against the unmerged change. USE WHEN a publisher repo (e.g. a design system, shared library, SDK) has a pending change that needs to be tested in downstream repos before its version is merged and published. TRIGGER when user says "pack and copy", "pre-release test in consumers", "test this package change in <consumer>", "install the unreleased version into the apps", or "validate this change against <consumer repo>".
+
+---
+
+# Pack and Copy
+
+Validate a publisher package change against its consumer repos **before** the publisher's version bump is merged and published. The flow is:
+
+1. Build the publisher package(s) — repo-specific, not automatable.
+2. Run `polygraph _pack-and-copy` (or the `pack_and_copy` MCP tool) to pack them and install the tarballs into each consumer, rewriting `package.json` to a `file:` dependency.
+3. Commit the consumer changes, including `.polygraph-packages/*.tgz`, to a branch, open a PR, and let consumer CI validate the change.
+
+This skill covers **steps 1 and 2**. PR creation / CI monitoring is left to the `polygraph` and `await-polygraph-ci` skills.
+
+## Available Tools
+
+Pack-and-copy functionality is available via both an MCP tool and a CLI command. Use whichever is available in your current environment.
+
+| MCP Tool | CLI Equivalent | Description |
+| --- | --- | --- |
+| `pack_and_copy` | `polygraph _pack-and-copy` | Pack publisher packages and install tarballs into consumer repos for pre-release validation. |
+
+Session discovery / inspection tools (`show_session`, `list_repos`, etc.) come from the `polygraph` skill — see that skill's tool table for the full mapping.
+
+## Prerequisites
+
+- An active Polygraph session that includes the publisher repo and one or more consumer repos. If you don't have a session yet, run the `polygraph` skill first to create one.
+- The publisher repo's built artifacts are **packable** — i.e. running `npm pack` in the package directory produces a tarball that, when installed, Just Works. If the publisher needs to be built first, you'll need to do that explicitly.
+
+## Phase 1: Identify Publishers and Consumers
+
+Determine which packages are being changed in the publisher, and which consumer repos need to validate the change.
+
+**If the user specified them**, skip to Phase 2.
+
+**Otherwise**, inspect the session and the publisher's change:
+
+1. Call `show_session(sessionId)` to enumerate the repos in the session and their local paths.
+2. The **publisher** is usually the current repo (where the change is being made). Look at its `package.json` files to find the packages being shipped — the one being changed, or all packages in a monorepo package tree.
+3. The **consumers** are the other repos in the session. Only repos that actually depend on one of the publisher's packages are relevant — the command will auto-skip the rest, but listing them up front keeps the user informed.
+
+Before proceeding, print a short table:
+
+| Publisher package | Publisher path          | Consumer repo | Consumer path     |
+| ----------------- | ----------------------- | ------------- | ----------------- |
+| @org/tokens       | /path/to/ds/packages/tokens | web-app       | /path/to/web-app |
+| @org/button       | /path/to/ds/packages/button | web-app       | /path/to/web-app |
+
+and confirm with the user using `AskUserQuestion` if anything is ambiguous.
+
+## Phase 2: Build the Publisher Packages
+
+**This step is not automatable.** Build commands vary per repo and per package. Ask the user how to build, or inspect the repo for conventions.
+
+Common hints to surface to the user:
+
+- A root-level `package.json` with a `build` script that builds all packages (e.g. `npm run build`, `nx run-many -t build`, `pnpm -r build`).
+- Per-package `build` scripts (check each publisher's `package.json`).
+- A `prepack` script — if one exists, `npm pack` will run it automatically and you don't need a separate build step.
+
+Run the build. Verify the `dist/` or equivalent output exists in each publisher package directory before proceeding.
+
+**If the build fails**, surface the error to the user and stop. Do not attempt to pack a broken package.
+
+## Phase 3: Pack and Copy
+
+Run `polygraph _pack-and-copy` (or the `pack_and_copy` MCP tool), passing a `--pair` for every (publisher, consumer) combination the user wants to test. The command is deterministic: it computes a unique pre-release version, runs `npm pack` in each publisher, copies the tarballs into each consumer's `.polygraph-packages/` directory, rewrites the consumer's `package.json` deps to point at the tarballs via `file:`, and POSTs a summary of published and consumed packages to the Polygraph session so the UI reflects what was packed where.
+
+CLI form:
+
+```bash
+polygraph _pack-and-copy \
+  --session <session-id> \
+  --pair <publisher-path>=<consumer-path> \
+  [--pair <publisher-path>=<consumer-path> ...] \
+  --json
+```
+
+MCP tool form — call `pack_and_copy` with:
+
+- `sessionId` (string, required): the Polygraph session ID
+- `pairs` (array, required): one `{ publisherPath, consumerPath }` object per (publisher, consumer) combination
+- `runScripts` (boolean, optional): enable npm lifecycle scripts during `npm pack` (off by default)
+
+**Notes:**
+
+- `<publisher-path>` / `publisherPath` is the directory containing the publisher package's `package.json` (not necessarily the repo root — for monorepos, this is `packages/<name>/`).
+- `<consumer-path>` / `consumerPath` is the consumer repo's root (where its `package.json` lives).
+- If a consumer doesn't declare a dependency on a publisher's package, that pair is silently skipped for that consumer — the tarball is still produced but not installed there.
+- The command creates a new unique version on each run, but package managers can still keep stale `file:` dependency contents in `node_modules`. Use a forced install on reruns if the consumer still sees old package contents.
+- Consumers' `.polygraph-packages/*.tgz` files **must be tracked and committed** with the consumer branch. Fresh CI clones need those tarballs to install the `file:` dependencies.
+
+Parse the JSON output to get the `published` and `consumed` summaries. Print them back to the user:
+
+```
+Packed:
+- @org/tokens  1.4.2 -> 1.4.3-pg.<session>.<timestamp>
+- @org/button  2.1.0 -> 2.1.1-pg.<session>.<timestamp>
+
+Installed into:
+- web-app: @org/tokens, @org/button
+- docs:    @org/tokens
+```
+
+## Phase 4: Install in Consumers and Commit
+
+For each consumer that received a tarball:
+
+1. Run the consumer's package manager install command, e.g. `npm install`, `pnpm install`, or `yarn install`, so the lockfile and `node_modules/` reflect the new `file:` dep. On reruns in the same worktree, use `npm install --force`, `pnpm install --force`, or `yarn install --force` if the consumer still sees old package contents.
+2. Commit the `package.json`, lockfile, and `.polygraph-packages/*.tgz` changes on a dedicated branch.
+
+3. Push the branch and open a draft PR with a description that explains this is validating an unmerged publisher change.
+
+4. Once CI results come in (see the `await-polygraph-ci` skill), report back. Do **not** merge any consumer PR opened via this flow — these PRs are for validation only and should be closed once the publisher's real version lands.
+
+## Common Pitfalls
+
+- **Forgetting to build**: `npm pack` packs whatever the package's `files` field points at. If `dist/` is stale or missing, the tarball will be broken. Always rebuild before packing unless a `prepack` script does it.
+- **Stale `file:` installs**: package managers may keep old extracted contents for local tarball dependencies after reruns. Use `install --force` if a consumer still sees old package contents.
+- **Peer dependency mismatches**: if the publisher bumps a peer dep, consumers that don't satisfy it may fail to install. Surface this to the user.
+- **Lockfile churn**: installing after a `file:` swap will change the lockfile. That's expected and should be committed alongside the `package.json` and tarball changes.
+- **Multiple publishers in one repo**: pass one `--pair` per publisher package, using the same consumer path. They'll all be bundled into the same `.polygraph-packages/` dir.
+
+## Related Skills
+
+- `polygraph` — session setup, branch push, PR creation.
+- `await-polygraph-ci` — monitor consumer CI after the PRs are opened.

package/skills/polygraph/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: polygraph
+description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; fetching missing git history in a shallow session clone; or tracing a commit or line of code back to the session that produced it. 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", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame", "shallow clone", "missing commit", "bad object", "unshallow", "fetch history".
+
+---
+
+# Working with Polygraph
+
+**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. Before delegating anything, read [`reference/delegation.md`](reference/delegation.md).
+
+Polygraph connects repos and the agent work happening across them. Its central artifact is the session, which groups the repos, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repos or in a single repoto 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 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* repos are worked on in separate Polygraph-managed clones via `spawn_agent`. Resuming is the one qualified case: a `resume_session` with the explicit `reset` consent force-switches branches inside the session's materialized repositories, and can force-move the current working tree when it is itself one of them. Repositories outside the session folder are never modified. Full contract under "Explore an Existing Session".
+
+## Available Tools
+
+Polygraph functionality is available via both MCP tools and CLI commands. Use whichever is available in your current environment.
+
+| MCP Tool | CLI Equivalent | Description |
+| --- | --- | --- |
+| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
+| `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
+| `resume_session` | `polygraph session resume --session <id> --json` | Join an existing session from this conversation: a tracked adoption that performs the full reconstruct. On divergence it stays local by default; `reset` is an explicit, destructive opt-in. Divergence and post-join behavior are under "Explore an Existing Session". |
+| `spawn_agent` | — | Start a child task, or send a follow-up to an active task, in another repository; returns a delegation id. A repeat call for the same (repo, role) is delivered to that task as a follow-up; otherwise a new child starts. See `reference/delegation.md`. |
+| `show_agent` | — | Poll by repo or delegation id; unwaited reads return the child's result. Waited calls are for the poller subagent, not the main conversation. See `reference/delegation.md`. |
+| `stop_agent` | — | Cancel an in-progress child by delegation id; its session is preserved for later read-only context restoration. |
+| `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 |
+| `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. |
+| `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required); metadata only, independent of PR creation or mark-ready. |
+| `link_reference` | — | Link an external reference to a session. |
+| `mark_pr_ready` | — | Mark draft PRs as ready for review |
+| `associate_pr` | — | Associate an existing PR with a session |
+| `add_repo` | — | Add repositories to a running session (pass exact refs directly, skipping `list_repos`). See "Add Repositories to a Session". |
+| `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 |
+| `git_fetch` | `polygraph git fetch` | Fetch git history for a shallow session clone when git fails with "bad object" or missing-commit errors. See "Fetching Git History for Shallow Clones". |
+| `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
+| `logout` | `polygraph auth logout` | Log out of Polygraph |
+| `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
+| `search_sessions` | `polygraph session search` | Find sessions by free-text `query` OR by commit `sha` — pass exactly one. See "Finding the Session Behind a Commit or Line". |
+| `list_accounts` | `polygraph account list` | List available organizations |
+| `select_account` | `polygraph account select` | Select the organization that future commands run against |
+| `whoami` | `polygraph whoami` | Show current auth status and org |
+
+## CLI Statefulness
+
+The Polygraph CLI (`polygraph`) is **stateful**. When you select an organization — via `polygraph account select` or the equivalent MCP tool — that selection is saved globally and all subsequent CLI commands and MCP tool calls operate against it. You do not need to pass the org on every command.
+
+## Setup
+
+Before using Polygraph tools, ensure the CLI is authenticated and an organization is selected.
+
+### Check Authentication
+
+Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check if the user is currently logged in and which organization is active.
+
+- If the user **is logged in** and an org is selected → proceed to the workflow.
+- If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
+- Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
+- After login, an organization must be selected. Use `polygraph account select` (or MCP equivalent) when needed.
+- Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
+
+### Select Organization
+
+After logging in (or if logged in but no org is selected), use `polygraph account select` (or MCP equivalent) to choose the organization that future commands will run against.
+
+## Workflow Overview
+
+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.
+
+2. **Initialize or join Polygraph session** - If you already have a session ID, call `show_session` to fetch details. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. Otherwise, discover candidate repos, select relevant repositories, and create a new session via `list_repos` and `start_session`.
+3. **Delegate work to each repo** - Use `spawn_agent` to start child agents in other repositories (returns immediately with a delegation id). With the default role, delegate only to *other* repos — never to the repo you are in; work on it directly. Delegating into the repo you are in is allowed only with an explicit non-default `role`. Parallel delegation across repos is encouraged. Read [`reference/delegation.md`](reference/delegation.md) before delegating.
+   
+4. **Monitor child agents** - Let the background poller subagent do the waiting. When it exits, read that child's answer with a single unwaited `show_agent(sessionId, id)` — `result.text` is the child's final message.
+5. **Stop child agents** (if needed) - Use `stop_agent` with the delegation id to cancel an in-progress child agent. The agent's session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
+6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
+7. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
+8. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
+9. **Query PR status** - Use `show_session` to check progress.
+10. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
+11. **Archive session** - Use `archive_session` to archive the session when the user requests it.
+
+## Step-by-Step Guide
+
+### Initialize or Join Polygraph Session
+
+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 or you are provided one by a reminder hook), 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`.**
+
+**Hard rule: before doing ad-hoc work in another repository, or reading a session's context untracked, ask whether an existing session already covers this work. If one might and its session ID is not in scope, ask the user for it — never fall back to an ad-hoc clone. To WORK in a session's context, join it via `resume_session` — a tracked adoption. To only read or summarize, `show_session` remains the read path.**
+
+**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.
+
+**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`.
+
+**Case C — No session at all.** Launch the `polygraph-init-subagent` with only `userContext` (no `sessionId`). The subagent will discover candidates and call `start_session` to create a new session.
+
+In case B, direct exact repo refs go straight to `add_repo`; use `list_repos` only when discovery/filtering is needed. In case C, discover candidate repos using `list_repos`, select relevant repositories, and call `start_session`. In case A, just call `show_session`.
+
+**Session ID handling:**
+
+- For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
+- For cases A and B, the session ID already exists; reuse it everywhere
+- The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
+- For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
+
+The subagent will:
+
+1. Use exact repo refs directly when provided for an existing session; otherwise call `list_repos` to discover available repositories
+2. Select relevant repos based on the user context (or include all if uncertain)
+3. Either call `start_session` (case C, no `sessionId`) or call `add_repo` against the existing session (case B). It will never call `start_session` when a `sessionId` was provided.
+4. Call `show_session` to retrieve session details
+5. Return a summary with session URL and repo info
+
+**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 (or the hidden `polygraph session intro -s <sessionId>` via the CLI) — call it with the session ID; it returns the card as markdown. 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.
+
+**For an existing session — after `show_session` returns or the init subagent's summary arrives — show the session details:**
+
+**Session:** POLYGRAPH_SESSION_URL
+
+**Repositories in this session:**
+
+- REPO_FULL_NAME
+
+- REPO_FULL_NAME: from the session repository entries
+- POLYGRAPH_SESSION_URL: from `polygraphSessionUrl`
+
+### Explore an Existing Session
+
+Use this workflow when the user gives a Polygraph session ID and asks to understand, resume, inspect, or investigate prior work.
+
+**Resume is not a work command.** If the user's intent is to resume, reconnect, or reconstruct a prior Polygraph session, join it via `resume_session`, summarize the restored context it returns, then stop. Do not edit files, push branches, add repos, delegate new work, or continue previous changes until the user explicitly asks for changes. Recording the join in the session's history is not making changes to the work. Treat "resume" as context restoration followed by waiting for user instructions.
+
+1. Fetch session context by intent:
+   - To continue work in the session from this conversation, join it via `resume_session` (CLI: `polygraph session resume --session <id> --json`) — a tracked adoption that performs the full reconstruct; the restored session context comes back in the tool result. On a divergent session the join stays on the local conversation by default and returns the divergence evidence; adopting the selected path requires the explicit `reset` consent, a destructive opt-in that force-switches branches in the session's materialized repositories (discarding uncommitted tracked changes there, untracked files survive) and deletes this machine's local session logs.
+   - To only read, inspect, or summarize without joining, prefer `show_session` with `details: true`; otherwise run `polygraph session show --details <session-id>`. This is the read-only path and records nothing.
+2. Treat the detailed output as authoritative context. It should include:
+   - `<summary>` — the session summary.
+   - `<repositories>` — relevant repos, including each repo's `<id>` and `<name>`.
+   - `<pullRequests>` — relevant PRs, including `<url>`, `<repoId>`, `<repoName>`, branch metadata, and `<description>`.
+3. Parse the XML-style blocks and XML-unescape text inside `<summary>` and `<description>`.
+4. Build a repo/PR map:
+   - repo id
+   - repo full name
+   - PR URL
+   - branch
+   - base branch
+   - title
+   - status
+   - PR description
+5. If the request was resume/reconnect/reconstruct only, report the restored session context and wait for the user's next instruction.
+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 (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.
+9. After `add_repo`, call `show_session` again to verify the repo was added, then delegate to that repo.
+10. Fall back to `list_repos` only when the desired repo is not an exact ref and is missing from `<repositories>`, or when the details output came from an older Polygraph version that did not include repo IDs.
+
+When delegating investigation from a PR, include the PR context in the child instruction:
+
+```
+Session: <session-id>
+Repo: <repoName>
+Repo ID: <repoId>
+PR: <url>
+Branch: <branch>
+Base branch: <baseBranch>
+Description:
+<description>
+
+Inspect the PR commits/diff and investigate the requested behavior. Report findings with file paths and concrete evidence.
+```
+
+### Finding the Session Behind a Commit or Line
+
+Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code. 
+**Read [`reference/session-by-commit.md`](reference/session-by-commit.md) before running any lookup.** That reference file holds clear, reliable steps for answering questions related to this.
+
+## Delegating to other repos
+
+Working across more than one repo, or delegating any task? Read [`reference/delegation.md`](reference/delegation.md) first — required. Delegation is the only way to act on other repos, and the reference holds the contract that keeps it cheap and trackable: skipping it leads to re-pasting briefs, polling in the main conversation, and touching other repos' clones directly — each of which burns tokens or breaks session tracking.
+
+<!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
+     rendered by polygraph-mcp's show_agent handler. The dialog targets the parent harness's
+     own UI, NOT this agent. From the agent's vantage point the gate is transient: a
+     `show_agent` poll may briefly see `permission-required` between the child opening the
+     gate and the user picking in the dialog. The agent must NOT resolve it itself. -->
+## Handling permission requests
+
+Your MCP client supports the native permission dialog. When a child agent requests permission, the dialog renders directly in your UI and the user picks — the decision routes back through `polygraph-mcp` automatically.
+
+**Critical: do NOT call `allow_agent` or `deny_agent` yourself.** If `show_agent` briefly reports a child in `permission-required` state with `pendingPermission` populated, that is a transient state the dialog is in the middle of resolving. Your job is to keep polling — the next poll will see the child back in `in-progress` (or `failed` / `cancelled` if the user denied or dismissed).
+
+If you call `allow_agent` while the dialog is already open, you create a race: the user's pick lands first and the explicit allow fails with `Task <id> is in state 'completed', not 'permission-required'`. The child receives the user's choice; your call is wasted work.
+
+The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do NOT advertise elicitation capability (opencode TUI today). They are not part of your flow.
+
+## Publishing and Session Management
+
+### Publish Changes (Push Branches, Create PRs, Mark Ready)
+
+Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), and `associate_pr` (link PRs created outside Polygraph).
+
+**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow.
+
+### Session Description Policy
+
+`description` is user-facing Polygraph session context. It is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (`mark_pr_ready` does not take a description).
+
+**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy.
+
+Use `update_session` directly when the user asks to summarize progress, update the session description, or capture the current state.
+Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
+
+### Linked References
+
+Use `link_reference` to link an external reference to the current Polygraph session.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session receiving the linked reference
+- `reference` (required): Reference metadata with `type`, `url`, and `label`
+- `reference.sessionId` (session references only): The referenced Polygraph session ID when `reference.type` is `session`
+
+When an external resource is mentioned during a Polygraph session and appears relevant to the current work, the parent agent should record it with `link_reference({ sessionId, reference })`. This applies to relevant external resources such as pull requests, GitHub issues, other Polygraph sessions, and Linear issues.
+
+The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command; `show_session` returns a session's existing links as `session.linkedReferences`.
+
+### Add Repositories to a Session
+
+Use `add_repo` to add repositories to an existing Polygraph session after it has already started.
+
+**Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery is only for cases where the user does not know the exact repo.
+
+**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.
+
+### Archive Session
+
+**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.
+
+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. Pass the optional `clean` flag to also remove the local clones Polygraph created for delegated repos.
+
+**When to call:** all work is finished, PRs are created and marked ready, and the user explicitly confirms they are done with the session.
+
+## Other Capabilities
+
+### Retrieving CI Job Logs
+
+`get_ci_logs` retrieves the full plain-text log for a specific CI job — the drill-in tool for investigating a failed job. **ONLY use it when NO CIPE (CI Pipeline Execution) exists for the PR** (`ciStatus[prId].cipeUrl` is null); when a CIPE exists, use the Nx MCP `ci_information` tool instead, and do NOT fetch or poll the `cipeUrl` over HTTP.
+
+When you need to fetch and read a failed job's log, read [`reference/ci-job-logs.md`](reference/ci-job-logs.md) for the parameters, return shape, and the full flow (identify the job from `externalCIRuns`, call `get_ci_logs`, then `Read` the saved log file).
+
+### Fetching Git History for Shallow Clones
+
+Session repos are shallow (`--depth 1`) clones. When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` and retry. Read [`reference/shallow-clone-history.md`](reference/shallow-clone-history.md) for the CLI form, the `depth`/`refs` options, and the redundant-call behavior.
+
+### Print Polygraph Session Details
+
+When asked to print polygraph session details, use `show_session` or `polygraph session show --details <session-id>` and display in the following format.
+
+**Session:** POLYGRAPH_SESSION_URL
+
+| Repo           | PR                 | PR Status | CI Status | Self-Healing        | CI Link          |
+| -------------- | ------------------ | --------- | --------- | ------------------- | ---------------- |
+| REPO_FULL_NAME | [PR_TITLE](PR_URL) | PR_STATUS | CI_STATUS | SELF_HEALING_STATUS | [View](CIPE_URL) |
+
+If the session has a description timeline, also display:
+
+**Description:** SESSION_DESCRIPTION
+
+(Omit the Description line if `description` is empty.)
+
+- REPO_FULL_NAME: from the session repository entries (match repository to PR via `repoId`)
+- PR_URL, PR_TITLE, PR_STATUS: from `pullRequests[]`
+- CI_STATUS: from `ciStatus[prId].status`
+- SELF_HEALING_STATUS: from `ciStatus[prId].selfHealingStatus` (omit or show `-` if null)
+- CIPE_URL: from `ciStatus[prId].cipeUrl` (null if no CIPE — omit the CI Link cell) — a human-facing Nx Cloud link: render it for the user, never fetch, curl, or poll it. CIPE data is only reachable via the Nx MCP `ci_information` tool.
+- POLYGRAPH_SESSION_URL: from `polygraphSessionUrl`
+- SESSION_DESCRIPTION: from the latest/current item in `description`
+
+## Best Practices
+
+1. **Delegate asynchronously** — Use `spawn_agent` which returns immediately with a delegation id, then poll with `show_agent`.
+   
+1. **Read each result once** — when a poller exits, read that child with a single unwaited `show_agent(sessionId, id)`; `result.text` is the child's final message. Only reach for an explicit `tail` if that is not enough.
+1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) before pushing branches or creating PRs
+1. **Link PRs in descriptions** - Reference related PRs in each PR body
+1. **Keep PRs as drafts** until all repos are ready
+1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy
+1. **Test integration** before marking PRs ready
+1. **Coordinate merge order** if there are deployment dependencies
+   
+1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed (pass the delegation id). 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.

package/skills/polygraph/reference/ci-job-logs.md

@@ -0,0 +1,38 @@
+# Retrieving CI Job Logs
+
+Use `get_ci_logs` to retrieve the full plain-text log for a specific CI job. This is the drill-in tool for investigating CI failures after identifying a failed job from the session's CI status.
+
+**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via the Nx MCP `ci_information` tool — do NOT call `get_ci_logs`, and do NOT fetch or poll the `cipeUrl` over HTTP (it is a browser link for the user, not an API). This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+- `repoId` (required): Repository ID (MongoDB ObjectId hex string, from the session repository entry)
+- `jobId` (required): GitHub Actions job ID (from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response)
+
+**Returns:**
+
+- On success: `{ success: true, jobId: number, logFile: string, sizeBytes: number }`
+- On failure: `{ success: false, error: string }`
+
+The tool saves the log to a local temp file and returns the path in `logFile`. Use the `Read` tool to examine the file contents. For large logs, use `offset` and `limit` parameters to read specific sections.
+
+```
+get_ci_logs(
+  sessionId: "<session-id>",
+  repoId: "<repo-id>",
+  jobId: 12345678
+)
+// Returns: { success: true, jobId: 12345678, logFile: "/tmp/ci-logs/job-12345678.log", sizeBytes: 152340 }
+// Then: Read(logFile) to examine the log
+```
+
+**Typical flow:**
+
+1. Use `show_session` to see PR CI status
+2. Check `ciStatus[prId].cipeUrl` — if a CIPE exists, use `ci_information` for logs and skip this tool
+3. If NO CIPE exists, check `ciStatus[prId].externalCIRuns` — examine runs and jobs directly from the session data
+4. For a failed job, call `get_ci_logs(sessionId, repoId, jobId)` to save the log to a file
+5. Use `Read(logFile)` to examine the log content — use `offset`/`limit` for large files
+
+**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.

package/skills/polygraph/reference/delegation.md

@@ -0,0 +1,109 @@
+# Delegation Reference
+
+Delegation is the only way to act on a repository other than the one you are in. Polygraph keeps local clones of the other repos in the session, but they are not yours to touch: never `cd` into them, read their files, or run git in them. Everything happens through `spawn_agent` and `show_agent`.
+
+The flow is **pointer-based**. `spawn_agent` hands you a delegation id. A cheap background subagent watches that id and tells you when it stops moving. You then read the answer yourself, once. Nothing re-pastes the brief, and no log lines pass through a middleman.
+
+## The delegation id
+
+`spawn_agent` returns a short id (e.g. `frontend-1`) that names one child run. It is the handle for everything afterwards — polling, reading the result, following up, stopping. The id pins the repo AND the role, so once you have it you never re-specify either.
+
+Keep every id you are given. Losing one means falling back to `repo` + `role` lookups, which are ambiguous the moment a repo hosts more than one agent.
+
+## Spawning
+
+Call `spawn_agent` directly from the main conversation. This is a fast, non-blocking call that returns an id — it is not polling and does not belong in a subagent.
+
+```
+spawn_agent(
+  sessionId: "<sessionId>",
+  repo: "<org/repo-name>",
+  instruction: "<the task instruction>",
+  role: "<optional role>",
+  context: "<optional context>",
+  agent: "<optional: claude | codex | opencode>",
+  model: "<optional model override>"
+)
+```
+
+`agent` picks the child's harness and `model` overrides its default model; include either only when the user named one.
+
+Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, and what "done" looks like. 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.
+
+**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.
+
+## Waiting
+
+For each id, launch one background poller subagent whose entire job is to block until that child stops moving. Give it the `sessionId` and the `id`, and nothing else.
+
+- **Claude Code** — a background `Task` with `subagent_type: "polygraph:polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Fall back to the bare agent name only if the namespaced form is not found.
+- **OpenCode** — invoke `@polygraph-delegate-subagent`.
+- **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`.
+
+The poller has exactly one tool and cannot read logs. It exits with a few lines naming the repo, the id, and the final status. That message is a doorbell, not a report — it tells you the child is worth reading, and nothing about what the child did.
+
+**Routine polling never happens in the main conversation.** A waited `show_agent` loop run inline floods your context with status noise and is the single largest avoidable cost in a multi-repo session. That is what the poller exists to absorb.
+
+## Reading the result
+
+When a poller exits, read the child's answer yourself with a single **unwaited** `show_agent` — no `waitForTransitionMs`, no `tail`:
+
+```
+show_agent(sessionId: "<sessionId>", id: "<id>")
+```
+
+`result.text` is the child's final message: what it did, what it found, what it wants you to know. This is the payload. Read it once, in the main conversation, and act on it.
+
+One-off unwaited reads like this are cheap and expected inline. It is the *waiting* that belongs in a subagent, not the reading.
+
+## 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:
+
+- Pass an explicit `tail` to `show_agent` to pull recent log lines.
+- Page further back with the `page` param: `tail: 5, page: 2` returns the 5 lines before the newest 5, `page: 3` the window before that.
+- If the user wants to watch the run live, point them at `polygraph agent attach <repo>` (plus `--role <role>` for a non-default agent) — an interactive terminal view for humans, not a command for you to run.
+
+These are deliberate, targeted follow-ups. None of them belongs in a polling loop, and none of them is a reason to go looking at transcript files, `~/.polygraph/sessions`, or anything a harness saved to disk because a tool result was too large. `show_agent` is the supported interface.
+
+## Follow-ups
+
+To send a child more work, call `spawn_agent` again with the SAME `repo` and the SAME `role`. If that (repo, role) still has a live task — working, or paused waiting on you — the orchestrator delivers your instruction to it as a follow-up instead of starting a second run. A (repo, role) pair therefore has at most one active child at a time.
+
+A follow-up returns a **new** delegation id, linked to the previous one by a `continues` reference. The new id is the live handle: poll it, read it, follow up on it. The old id still addresses the earlier turn if you need to look back at it.
+
+After a follow-up, launch a fresh poller subagent for the new id. The old poller has already exited; it does not resume.
+
+## Input-required
+
+When a child needs an answer from you, it stops and the poller exits with status `input-required` and "needs attention."
+
+Read the child with an unwaited `show_agent` as usual. `inputRequiredQuestion` carries the child's verbatim question. Surface it to the user as the child asked it — do not paraphrase or answer on the user's behalf — then send the answer back as an ordinary follow-up `spawn_agent` for the same (repo, role). Poll the new id it returns.
+
+`permission-required` is a different state and is not yours to resolve here; see "Handling permission requests" in the skill.
+
+## Roles
+
+A repository in a session can host several child agents at once, distinguished by **role**:
+
+- **Omit by default.** Set a `role` only when the user very explicitly asked for a named one, or when a skill the user invoked prescribes one (e.g. `adversarial-review` uses `reviewer`). Never invent one.
+- **Purpose.** Roles let independent streams of work run concurrently in one repo — a default agent implementing a feature while a `reviewer` or `ci-investigator` runs alongside. Each (repo, role) pair has at most one active child.
+- **Default role.** An omitted `role` means the default role: `spawn_agent` without `role` starts or follows up with that repo's default-role agent.
+- **Ids pin the role.** A delegation id already identifies one (repo, role) pair, so `show_agent` and `stop_agent` by id need no `role` argument. Pass `role` only when addressing an agent by `repo` instead of by id.
+- **Logs.** Only default-role agents upload logs to the cloud and appear in the multiplexed stream (`polygraph session logs`). A non-default agent's transcript stays on this machine — the user can watch it with `polygraph agent attach <repo> --role <role>`.
+
+## Stopping
+
+Cancel a running child by id:
+
+```
+stop_agent(sessionId: "<sessionId>", id: "<id>")
+```
+
+The response reports `sessionPreserved: true`: the stopped agent's session is kept so its context can be restored later. Restoring is read-only. After a resume, do not continue the prior work or make further changes until the user explicitly asks for them.
+
+## Before publishing
+
+Every delegation must reach a terminal status — `completed`, `failed`, or `cancelled` — before you push branches or open PRs. A poller exiting on `input-required` is not terminal; it means the child is still waiting on you.