Skip to content

SKILL.md

Latest commit

 

History

History
662 lines (474 loc) · 30.7 KB

SKILL.md

File metadata and controls

662 lines (474 loc) · 30.7 KB
Error in user YAML: (<unknown>): found character that cannot start any token while scanning for the next token at line 3 column 2
---
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.
{% if platform == "claude" %}
allowed-tools:
  - mcp__plugin_polygraph_polygraph-mcp
{% endif %}
---

{% assign has_subagents = false %} {% if platform == "claude" or platform == "opencode" %} {% assign has_subagents = true %} {% endif %}

Multi-Repo Coordination with Polygraph

IMPORTANT: NEVER cd into cloned repositories or access their files directly. ALWAYS use the polygraph_delegate tool to perform work in other repositories.

This skill provides guidance for working on features that span multiple repositories using Polygraph for coordination.

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
polygraph_candidates polygraph repo list Discover candidate workspaces with descriptions and graph relationships
polygraph_init polygraph session start --repo <ids> Initialize a Polygraph session with selected workspaces
polygraph_delegate — Start a task in a child agent in another repository (non-blocking)
polygraph_child_status — Get the status and recent output of child agents
polygraph_stop_child — Stop an in-progress child agent
polygraph_push_branch — Push a local git branch to the remote repository
polygraph_create_prs — Create draft PRs with session metadata linking related PRs
polygraph_get_session polygraph session status <id> Query status of the current session
polygraph_mark_ready — Mark draft PRs as ready for review
polygraph_associate_pr — Associate an existing PR with a session
polygraph_modify_session polygraph session complete <id> Modify or complete a session (complete closes all PRs and seals it)
ci_get_logs — Retrieve full plain-text log for a specific CI job
— polygraph login [--token] Authenticate with Nx Cloud (use --token for headless/CI)
— polygraph session list List all sessions
— polygraph org list / org select Organization management
— polygraph whoami Show current auth status and org

{% if has_subagents %}

Delegation rules: polygraph_candidates and polygraph_init MUST be called via the polygraph-init-subagent as described in step 0. polygraph_delegate and polygraph_child_status MUST ALWAYS be called via background Task subagents (run_in_background: true) as described in step 1 — NEVER call them directly in the main conversation. {% endif %}

CLI Statefulness

The Polygraph CLI (polygraph) is stateful. When you select an organization — via polygraph org 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) 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 the user is not logged in → use polygraph login (or the login MCP tool) to authenticate. After login, an organization must be selected.

Select Organization

After logging in (or if logged in but no org is selected), use polygraph org select (or the equivalent MCP tool) to choose the organization that future commands will run against.

Workflow Overview

{% if has_subagents %}

  1. Initialize or join Polygraph session - If you already have a session ID, call polygraph_get_session to fetch details. Otherwise, launch the polygraph-init-subagent to discover candidate repos, select relevant workspaces, and create a new session.
  2. Delegate work to each repo - Use the polygraph-delegate-subagent to start child agents in other repositories. {% else %}
  3. Initialize or join Polygraph session - If you already have a session ID, call polygraph_get_session to fetch details. Otherwise, discover candidate repos, select relevant workspaces, and create a new session via polygraph_candidates and polygraph_init.
  4. Delegate work to each repo - Use polygraph_delegate to start child agents in other repositories (returns immediately). {% endif %}
  5. Monitor child agents - Use polygraph_child_status to poll progress and get output from child agents.
  6. Stop child agents (if needed) - Use polygraph_stop_child to cancel an in-progress child agent.
  7. Push branches - Use polygraph_push_branch after making commits.
  8. Create draft PRs - Use polygraph_create_prs to create linked draft PRs. Both plan and agentSessionId are required.
  9. Associate existing PRs (optional) - Use polygraph_associate_pr to link PRs created outside Polygraph.
  10. Query PR status - Use polygraph_get_session to check progress.
  11. Mark PRs ready - Use polygraph_mark_ready when work is complete.
  12. Complete session - Use polygraph_modify_session with complete: true to mark the session as completed when the user requests it.

Step-by-Step Guide

0. Initialize or Join Polygraph Session

If you already have a session ID (e.g., passed by the user or provided when Claude was spawned inside an existing session), the session already exists — do NOT create a new one. Instead, call polygraph_get_session to fetch the session details and skip straight to printing the session details below.

{% if has_subagents %}

If you need to create a new session, use the polygraph-init-subagent to discover candidate repos, select relevant workspaces, and initialize the Polygraph session. The subagent handles calling polygraph_candidates and polygraph_init and returns a structured summary. {% else %}

If you need to create a new session, discover candidate repos using polygraph_candidates, select relevant workspaces, and initialize the Polygraph session using polygraph_init. {% endif %}

Session ID is auto-generated:

The polygraph_init tool automatically generates a unique session ID. You do NOT need to pass a session ID when creating a new session. {% if platform == "claude" %}

Launch the init subagent (only when creating a new session):

{% raw %}

Task(
  subagent_type: "polygraph-init-subagent",
  description: "Init Polygraph session",
  prompt: """
    Parameters:
    - userContext: "<description of what the user wants to do>"

    Discover candidates, select relevant repos based on the user context, initialize the session, and return a structured summary.
  """
)

{% endraw %} {% elsif platform == "opencode" %}

Launch the init subagent using @polygraph-init-subagent (only when creating a new session):

Invoke the polygraph-init-subagent agent with the user context. The subagent handles calling polygraph_candidates and polygraph_init and returns a structured summary. {% else %}

Call polygraph_candidates to discover available workspaces, select relevant repos based on user context, then call polygraph_init with the selected workspace IDs. {% endif %}

The subagent will:

  1. Call polygraph_candidates to discover available workspaces
  2. Select relevant repos based on the user context (or include all if uncertain)
  3. Call polygraph_init with the selected workspace IDs
  4. Call polygraph_get_session to retrieve session details
  5. Return a summary with session URL, repos, and workspace info

After receiving the subagent's summary (or after calling polygraph_get_session for an existing session), print the session details:

Session: POLYGRAPH_SESSION_URL

Repositories in this session:

Repo Local Path
REPO_FULL_NAME LOCAL_PATH
  • REPO_FULL_NAME: from workspaces[].vcsConfiguration.repositoryFullName
  • LOCAL_PATH: the absolute path to the local clone of the repo. If you started the session from within a repo, that repo's path is the current working directory. All other repos' paths are available from polygraph_child_status.
  • POLYGRAPH_SESSION_URL: from polygraphSessionUrl

1. Delegate Work to Each Repository

{% if platform == "claude" %}

CRITICAL: polygraph_delegate and polygraph_child_status MUST ALWAYS be called via background Task subagents (run_in_background: true), NEVER directly from the main conversation. Direct calls flood the context window with polling noise and degrade the user experience. This is a hard requirement, not a suggestion.

To delegate work to another repository, use the Task tool with run_in_background: true to launch a background subagent that handles the entire delegate-and-poll cycle. This keeps the noisy polling output hidden from the user — they only see a clean summary when the work completes.

How it works:

  1. You launch a background Task subagent for each target repo
  2. The subagent calls polygraph_delegate to start the child agent, then polls polygraph_child_status with backoff until completion
  3. The subagent returns a summary of what happened
  4. You can check progress anytime by reading the subagent's output file

Launch a background subagent per repo using the polygraph-delegate-subagent:

{% raw %}

Task(
  subagent_type: "polygraph-delegate-subagent",
  run_in_background: true,
  description: "Delegate to <repo-name>",
  prompt: """
    Parameters:
    - sessionId: "<session-id>"
    - target: "<org/repo-name>"
    - instruction: "<the task instruction>"
    - context: "<optional context>"

    Delegate the work, poll for completion, and return a structured summary.
  """
)

{% endraw %}

Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time:

{% raw %}

// Launch subagents for each repo — all return immediately
Task(run_in_background: true, ..., prompt: "...delegate to frontend...")
Task(run_in_background: true, ..., prompt: "...delegate to backend...")

// Check progress later by reading the output files
Read(output_file_from_task_1)
Read(output_file_from_task_2)

{% endraw %}

You MUST ALWAYS use background Task subagents for delegation. NEVER call polygraph_delegate or polygraph_child_status directly in the main conversation — doing so floods the context window with polling output.

1a. Check on Background Subagents

Since delegation runs in background Task subagents, you can check progress by reading the output file returned when the Task was launched:

{% raw %}

Read(output_file_path)

{% endraw %}

Or use Bash to see recent output:

{% raw %}

Bash("tail -50 <output_file_path>")

{% endraw %}

In rare cases where you need to check the raw child agent status directly (e.g., debugging a stuck subagent), you may call polygraph_child_status as a one-off tool call. Do NOT use this for regular polling — that MUST happen in background subagents:

{% raw %}

polygraph_child_status(sessionId: "<session-id>", target: "org/repo-name", tail: 5)

{% endraw %}

Always verify all background subagents have completed before proceeding to push branches and create PRs. {% elsif platform == "opencode" %}

CRITICAL: polygraph_delegate and polygraph_child_status MUST ALWAYS be called via @polygraph-delegate-subagent, NEVER directly from the main conversation. Direct calls flood the context window with polling noise and degrade the user experience. This is a hard requirement, not a suggestion.

Use the polygraph-delegate-subagent agent (@polygraph-delegate-subagent) for each target repository. The subagent handles calling polygraph_delegate to start the child agent, then polls polygraph_child_status with backoff until completion, and returns a structured summary.

For each target repo, invoke @polygraph-delegate-subagent with:

  • sessionId: The Polygraph session ID
  • target: Repository name (e.g., org/repo-name)
  • instruction: The task instruction for the child agent
  • context: Optional additional context

Delegate to multiple repos by launching multiple @polygraph-delegate-subagent invocations.

1a. Check on Child Agents

Use polygraph_child_status to check progress: {% else %}

Use polygraph_delegate to start a child agent in each target repository. The call returns immediately — use polygraph_child_status to poll for completion with backoff.

For each target repo:

  1. Call polygraph_delegate with sessionId, target, and instruction
  2. Poll polygraph_child_status periodically until the child agent completes
  3. Review the child agent's output before proceeding

Delegate to multiple repos by calling polygraph_delegate for each repo, then polling their status.

1a. Check on Child Agents

Use polygraph_child_status to check progress:

{% raw %}

polygraph_child_status(sessionId: "<session-id>", target: "org/repo-name", tail: 5)

{% endraw %}

Always verify all child agents have completed before proceeding to push branches and create PRs. {% endif %}

1b. Stop an In-Progress Child Agent

Use polygraph_stop_child to cancel an in-progress child agent. Use this if a child agent is stuck, taking too long, or if you need to cancel delegated work.

Parameters:

  • sessionId (required): The Polygraph session ID
  • target (required): Repository name or workspace ID of the child agent to stop
polygraph_stop_child(sessionId: "<session-id>", target: "org/repo-name")

After stopping a child agent, always print instructions for the user to continue work manually in the child repo. Get the repo path from the cwd field in the system init log entry (available via polygraph_child_status).

Display:

Child agent for <repo> has been cancelled.

To continue the work manually, run:
  cd <path> && claude --continue

Where <path> is the absolute path to the child repo clone (e.g., /var/folders/.../polygraph/<session-id>/<repo>).

2. Push Branches

Once work is complete in a repository, push the branch using polygraph_push_branch. This must be done before creating a PR.

Parameters:

  • sessionId (required): The Polygraph session ID
  • repoPath (required): Absolute file system path to the local git repository
  • branch (required): Branch name to push to remote
polygraph_push_branch(
  sessionId: "<session-id>",
  repoPath: "/path/to/cloned/repo",
  branch: "polygraph/ad5fa-add-user-preferences"
)

3. Create Draft PRs

Create PRs for all repositories at once using polygraph_create_prs. PRs are created as drafts with session metadata that links related PRs across repos. Branches must be pushed first.

Parameters:

  • sessionId (required): The Polygraph session ID
  • prs (required): Array of PR specifications, each containing:
    • owner (required): GitHub repository owner
    • repo (required): GitHub repository name
    • title (required): PR title
    • body (required): PR description (session metadata is appended automatically)
    • branch (required): Branch name that was pushed
  • plan (required): High-level plan describing the session's purpose. Both plan and agentSessionId must always be provided together to enable session resuming.
  • agentSessionId (required): The Claude CLI session ID. Both plan and agentSessionId must always be provided together to enable session resuming.
polygraph_create_prs(
  sessionId: "<session-id>",
  plan: "Add user preferences feature: UI in frontend, API in backend",
  agentSessionId: "<claude-session-id>",
  prs: [
    {
      owner: "org",
      repo: "frontend",
      title: "feat: Add user preferences UI",
      body: "Part of multi-repo user preferences feature",
      branch: "polygraph/ad5fa-add-user-preferences"
    },
    {
      owner: "org",
      repo: "backend",
      title: "feat: Add user preferences API",
      body: "Part of multi-repo user preferences feature",
      branch: "polygraph/ad5fa-add-user-preferences"
    }
  ]
)

After creating PRs, always print the Polygraph session URL:

**Polygraph session:** POLYGRAPH_SESSION_URL

4. Get Current Polygraph Session

Check the status of a session using polygraph_get_session. Returns the full session state including workspaces, PRs, CI status, and the Polygraph session URL.

Parameters:

  • sessionId (required): The Polygraph session ID

Returns:

  • session.sessionId: The session ID
  • session.polygraphSessionUrl: URL to the Polygraph session UI
  • session.plan: High-level plan describing what this session is doing (null if not set)
  • session.agentSessionId: The Claude CLI session ID that can be used to resume the session (null if not set)
  • session.workspaces[]: Array of connected workspaces, each with:
    • id: Workspace ID
    • name: Workspace name
    • defaultBranch: Default branch (e.g., main)
    • vcsConfiguration.repositoryFullName: Full repo name (e.g., org/repo)
    • vcsConfiguration.provider: VCS provider (e.g., GITHUB)
    • workspaceDescription: AI-generated description of what this workspace does (may be null)
    • initiator: Whether this workspace initiated the session
  • session.dependencyGraph: Graph of workspace dependency edges
  • session.pullRequests[]: Array of PRs, each with:
    • url: PR URL
    • branch: Branch name
    • baseBranch: Target branch
    • title: PR title
    • status: One of DRAFT, OPEN, MERGED, CLOSED
    • workspaceId: Associated workspace ID
    • relatedPRs: Array of related PR URLs across repos
  • session.ciStatus: CI pipeline status keyed by PR ID, each containing:
    • status: One of SUCCEEDED, FAILED, IN_PROGRESS, NOT_STARTED (null if no CIPE and no external CI)
    • cipeUrl: URL to the CI pipeline execution details (null if no CIPE)
    • completedAt: Epoch millis timestamp, set only when the CIPE has completed (null otherwise)
    • selfHealingStatus: The self-healing fix status string from Nx Cloud's AI fix feature (null if no AI fix exists)
    • externalCIRuns: Array of external CI runs (present when no CIPE but external CI data exists, e.g., GitHub Actions). Each run contains:
      • runId: GitHub Actions run ID
      • name: Workflow name
      • status: Run status (completed, in_progress, queued)
      • conclusion: Run conclusion (success, failure, cancelled, timed_out, or null)
      • url: GitHub Actions run URL
      • jobs: Array of jobs in the run, each with:
        • jobId: Job ID (use with ci_get_logs)
        • name: Job name
        • status: Job status
        • conclusion: Job conclusion (or null)
polygraph_get_session(sessionId: "<session-id>")

5. Mark PRs Ready

Once all changes are verified and ready to merge, use polygraph_mark_ready to transition PRs from DRAFT to OPEN status.

Parameters:

  • sessionId (required): The Polygraph session ID
  • prUrls (required): Array of PR URLs to mark as ready for review
  • plan (required): High-level plan describing the session's purpose. Both plan and agentSessionId must always be provided together to enable session resuming.
  • agentSessionId (required): The Claude CLI session ID. Both plan and agentSessionId must always be provided together to enable session resuming.
polygraph_mark_ready(
  sessionId: "<session-id>",
  plan: "Add user preferences feature: UI in frontend, API in backend",
  agentSessionId: "<claude-session-id>",
  prUrls: [
    "https://github.com/org/frontend/pull/123",
    "https://github.com/org/backend/pull/456"
  ]
)

After marking PRs as ready, always print the Polygraph session URL so the user can easily access the session overview. Call polygraph_get_session and display:

**Polygraph session:** POLYGRAPH_SESSION_URL

Where POLYGRAPH_SESSION_URL is from polygraphSessionUrl in the response.

6. Associate Existing PRs

Use polygraph_associate_pr to link pull requests that were created outside of Polygraph (e.g., manually or by CI) to the current session. This is useful when PRs already exist for the branches in the session and you want Polygraph to track them.

Provide either a prUrl to associate a specific PR, or a branch name to find and associate PRs matching that branch across session workspaces.

Parameters:

  • sessionId (required): The Polygraph session ID
  • prUrl (optional): URL of an existing pull request to associate
  • branch (optional): Branch name to find and associate PRs for
  • plan (required): High-level plan describing the session's purpose. Both plan and agentSessionId must always be provided together to enable session resuming.
  • agentSessionId (required): The Claude CLI session ID. Both plan and agentSessionId must always be provided together to enable session resuming.
polygraph_associate_pr(
  sessionId: "<session-id>",
  plan: "Add user preferences feature: UI in frontend, API in backend",
  agentSessionId: "<claude-session-id>",
  prUrl: "https://github.com/org/repo/pull/123"
)

Or by branch:

polygraph_associate_pr(
  sessionId: "<session-id>",
  plan: "Add user preferences feature: UI in frontend, API in backend",
  agentSessionId: "<claude-session-id>",
  branch: "feature/my-changes"
)

Returns the list of PRs now associated with the session.

7. Complete 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.

⚠️ Warning: Completing a session is a destructive action. It will close all associated open and draft PRs. Only complete a session when the user explicitly confirms they want to close all PRs and seal the session.

Use polygraph_modify_session with complete: true 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.)
  • Close all open and draft PRs associated with the session
  • Return a closedPRs list in the response showing which PRs were closed and whether each close succeeded

This is idempotent — completing an already-completed session returns success.

Parameters:

  • sessionId (required): The Polygraph session ID

Returns:

  • sessionId: The session ID
  • completed: Boolean indicating completion status
  • closedPRs: Array of objects for each PR that was closed, each containing:
    • url: The PR URL
    • success: Boolean indicating whether the close succeeded
    • error (optional): Error message if the close failed
polygraph_modify_session(
  sessionId: "<session-id>",
  complete: true
)

When to call:

  • 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

Retrieving CI Job Logs

Use ci_get_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 ci_information — do NOT call ci_get_logs. 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
  • workspaceId (required): Nx Cloud workspace ID (MongoDB ObjectId hex string, from session.workspaces[].id)
  • jobId (required): GitHub Actions job ID (from ciStatus[prId].externalCIRuns[].jobs[].jobId in the get_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.

ci_get_logs(
  sessionId: "<session-id>",
  workspaceId: "<workspace-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 polygraph_get_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 ci_get_logs(sessionId, workspaceId, 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.

Session State for Resume (Required)

The plan and agentSessionId parameters are required on polygraph_create_prs, polygraph_mark_ready, and polygraph_associate_pr. You must always provide both values together. They save session state that enables resuming the Polygraph session later.

  • plan: A high-level description of what this session is doing (e.g., "Add user preferences feature across frontend and backend repos"). This helps anyone resuming the session understand the context.
  • agentSessionId: The Claude CLI session ID for the parent agent. This is the session ID that can be passed to claude --continue to resume exactly where the agent left off.

These fields are saved to the Polygraph session server-side and are available from polygraph_get_session. The Polygraph UI also shows a "Resume Session" section with copy-able commands when these fields are present.

Resuming a Polygraph Session

If a session has a saved agentSessionId, it can be resumed using:

claude --continue <agentSessionId>

This resumes the Claude CLI session that was coordinating the Polygraph work, restoring the full conversation context including which repos were involved, what work was delegated, and what remains to be done.

To check if a session is resumable, call polygraph_get_session and look for the agentSessionId field in the response.

Print Polygraph Session Details

When asked to print polygraph session details, use polygraph_get_session 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_STATUS CI_STATUS SELF_HEALING_STATUS View

If the session has a plan or agentSessionId, also display:

Plan: SESSION_PLAN

Resume: claude --continue AGENT_SESSION_ID

(Omit the Plan line if plan is null. Omit the Resume line if agentSessionId is null.)

Local paths:

  • REPO_FULL_NAME: LOCAL_PATH

  • REPO_FULL_NAME: from workspaces[].vcsConfiguration.repositoryFullName (match workspace to PR via workspaceId)

  • LOCAL_PATH: the absolute path to the local clone of the repo. If you started the session from within a repo, that repo's path is the current working directory. All other repos' paths are available from polygraph_child_status.

  • 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

  • POLYGRAPH_SESSION_URL: from polygraphSessionUrl

  • SESSION_PLAN: from plan

  • AGENT_SESSION_ID: from agentSessionId

Best Practices

{% if platform == "claude" %}

  1. MUST delegate via background subagents — You MUST use Task(run_in_background: true) for every polygraph_delegate and polygraph_child_status call. NEVER call these directly in the main conversation — it floods the context window with polling noise. {% elsif platform == "opencode" %}
  2. MUST delegate via subagents — You MUST use @polygraph-delegate-subagent for every polygraph_delegate and polygraph_child_status call. NEVER call these directly in the main conversation — it floods the context window with polling noise. {% else %}
  3. Delegate asynchronously — Use polygraph_delegate which returns immediately, then poll with polygraph_child_status. {% endif %}
  4. Poll child status before proceeding — Always verify child agents have completed via polygraph_child_status before pushing branches or creating PRs
  5. Link PRs in descriptions - Reference related PRs in each PR body
  6. Keep PRs as drafts until all repos are ready
  7. Test integration before marking PRs ready
  8. Coordinate merge order if there are deployment dependencies {% if platform == "claude" %}
  9. NEVER call polygraph_delegate or polygraph_child_status directly. These MUST ALWAYS go through background Task subagents (run_in_background: true). {% elsif platform == "opencode" %}
  10. NEVER call polygraph_delegate or polygraph_child_status directly. These MUST ALWAYS go through @polygraph-delegate-subagent. {% endif %}
  11. Use polygraph_stop_child to clean up — Stop child agents that are stuck or no longer needed {% if platform == "claude" %}
  12. Always provide plan and agentSessionId — These are required on polygraph_create_prs, polygraph_mark_ready, and polygraph_associate_pr. Always pass both values so the session can be resumed later with claude --continue {% elsif platform == "opencode" %}
  13. Always provide plan and agentSessionId — These are required on polygraph_create_prs, polygraph_mark_ready, and polygraph_associate_pr. Always pass both values so the session can be resumed later with opencode --continue {% else %}
  14. Always provide plan and agentSessionId — These are required on polygraph_create_prs, polygraph_mark_ready, and polygraph_associate_pr. Always pass both values so the session can be resumed later. {% endif %}
  15. Only complete sessions when asked — Only call polygraph_modify_session with complete: true when the user explicitly requests it. Completing a session closes all open/draft PRs and seals the session. Do not automatically complete sessions.