RepoPilot

CALL when the user or agent is about to add, upgrade, trust, fork, or deploy an npm package or public GitHub repository. Returns a lean repository-level recommendation, confidence, evidence gaps, CVEs, maintenance, ownership, license, CI/tests, Scorecard, freshness, and next actions. DO NOT use for code navigation. Pass exactly one of repo or package. A favourable result does not validate an exact package version or compatibility.

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "minLength": 3,
      "description": "Public GitHub repository as owner/repo or a github.com URL."
    },
    "package": {
      "type": "string",
      "minLength": 1,
      "description": "npm package name, for example lodash or npm:@scope/pkg. To judge a specific VERSION rather than the package as a whole, use evaluate_dependency_change instead."
    },
    "owner": {
      "type": "string",
      "minLength": 1,
      "description": "Repository owner, when repo carries only the bare name. Optional: prefer the single owner/repo form in repo."
    }
  },
  "oneOf": [
    {
      "required": [
        "repo"
      ]
    },
    {
      "required": [
        "package"
      ]
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "check_dependency"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL immediately before adding or upgrading an npm dependency. Answers "is this exact version safe to take on" from registry metadata, advisory deltas, provenance, license, and repository evidence, and returns blockers, warnings, a recommendation, and a verification plan. Example: {"dependency":"lodash","to_version":"4.17.21"} — every field is top-level, never nested under a "change" key. Only `dependency` is required — omit to_version to evaluate the latest published version, exactly as `npm install <pkg>` would. to_version also accepts a dist-tag ("latest") or a SemVer range ("^4.17.0"); it resolves to one exact version, reported back in change.to_version. Everything RepoPilot can infer is inferred, and every default, repair, and resolution is listed in input_adjustments. Evaluates only; never installs or edits anything.

{
  "type": "object",
  "properties": {
    "dependency": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(@[^/\\s]+/)?[^@/\\s][^/\\s]*$",
      "description": "A STRING: the npm package name on its own, with no version and no surrounding object — \"lodash\", \"@types/node\". Not {\"name\":...}, not {\"lodash\":\"^4.17.0\"}, not a list, and never wrapped in a top-level {\"change\":{...}} object — every field here is top-level. The version goes in to_version, the currently installed one in from_version."
    },
    "to_version": {
      "type": [
        "string",
        "number"
      ],
      "minLength": 1,
      "maxLength": 128,
      "description": "The version you intend to install — an exact version (\"4.18.1\"), a dist-tag (\"latest\"), or a SemVer range (\"^4.17.0\"). A quoted string is preferred; a bare JSON number (\"to_version\": 19) is also accepted and read as the string \"19\". Omit to evaluate the latest published version."
    },
    "from_version": {
      "type": [
        "string",
        "number",
        "null"
      ],
      "maxLength": 128,
      "description": "The version currently installed, or omitted when adding a new dependency. A bare JSON number is accepted the same way as to_version. Supplying it produces a before/after advisory comparison."
    },
    "dependency_type": {
      "type": "string",
      "enum": [
        "runtime",
        "development",
        "optional",
        "peer"
      ],
      "default": "runtime",
      "description": "Where the dependency goes, in THESE words: \"runtime\" for a dependencies entry, \"development\" for devDependencies. The manifest and CLI spellings (\"dev\", \"devDependencies\", \"--save-dev\", \"prod\") are mapped onto these and reported in input_adjustments."
    },
    "package_manager": {
      "type": "string",
      "enum": [
        "npm",
        "pnpm",
        "yarn",
        "bun"
      ],
      "description": "Optional. Only affects the commands and lockfile named in the verification plan. Inferred from project.lockfile_path when you send a project snapshot, and assumed to be npm otherwise."
    },
    "project": {
      "type": "object",
      "description": "Optional, source-free facts about the project you are changing. Supplying it adds Node/peer/license compatibility and a command-level verification plan. Omit it entirely and compatibility comes back \"unknown\" - read that as not checked, never as no problem found. Every field is optional; anything missing is defaulted and reported in input_adjustments, never rejected. Never send source code.",
      "properties": {
        "dependency_usage": {
          "type": "object",
          "description": "Optional local call shapes for this dependency under native Node with default conditions. No source, paths, local names or call arguments. Coverage is always partial; transpiled/bundled code is unsupported.",
          "additionalProperties": false,
          "required": [
            "schema_version",
            "runtime",
            "coverage",
            "uses"
          ],
          "properties": {
            "schema_version": {
              "type": "integer",
              "const": 1
            },
            "coverage": {
              "type": "string",
              "const": "partial"
            },
            "runtime": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "node",
                "platform",
                "arch"
              ],
              "properties": {
                "node": {
                  "type": "string",
                  "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
                  "maxLength": 32
                },
                "platform": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$",
                  "maxLength": 32
                },
                "arch": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$",
                  "maxLength": 32
                }
              }
            },
            "uses": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "loader",
                  "export_path"
                ],
                "properties": {
                  "loader": {
                    "type": "string",
                    "enum": [
                      "require",
                      "import"
                    ]
                  },
                  "export_path": {
                    "type": "array",
                    "maxItems": 2,
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$",
                      "maxLength": 100
                    }
                  }
                }
              }
            }
          }
        },
        "package_manager": {
          "type": "string",
          "enum": [
            "npm",
            "pnpm",
            "yarn",
            "bun"
          ]
        },
        "node_version": {
          "type": "string",
          "maxLength": 64
        },
        "direct_dependencies": {
          "type": "object",
          "maxProperties": 200,
          "additionalProperties": {
            "type": "string",
            "maxLength": 128
          }
        },
        "installed_versions": {
          "type": "object",
          "maxProperties": 200,
          "additionalProperties": {
            "type": "string",
            "maxLength": 128
          }
        },
        "scripts": {
          "type": "array",
          "maxItems": 30,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          }
        },
        "manifest_path": {
          "type": "string",
          "maxLength": 512
        },
        "lockfile_path": {
          "type": "string",
          "maxLength": 512
        },
        "lockfile_sha256": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{64}$"
        },
        "head_sha": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{7,64}$"
        },
        "license_policy": {
          "type": "object",
          "properties": {
            "allow": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 64
              }
            },
            "deny": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 64
              }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "policy_profile": {
      "type": "string",
      "enum": [
        "permissive",
        "balanced",
        "strict"
      ],
      "default": "balanced",
      "description": "Named team dependency policy. Strict requires provenance and denies package install hooks. Must be spelled exactly — a near-miss spelling is rejected rather than guessed, because reading it wrong would answer under a policy you did not ask for."
    },
    "intent": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional free text describing why you are making this change. Advisory only; it changes no verdict."
    }
  },
  "required": [
    "dependency"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "dependency": "lodash",
      "to_version": "4.17.21"
    },
    {
      "dependency": "express",
      "from_version": "4.18.2",
      "to_version": "^5.0.0"
    },
    {
      "dependency": "zod",
      "to_version": "3.23.8",
      "project": {
        "package_manager": "pnpm",
        "node_version": "20.11.0",
        "direct_dependencies": {
          "zod": "^3.22.0"
        },
        "installed_versions": {
          "zod": "3.22.4"
        },
        "scripts": [
          "build",
          "test"
        ]
      },
      "policy_profile": "strict"
    }
  ]
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "evaluate_dependency_change"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL after changing the manifest/lockfile and running local checks. Compares the exact evaluated target with the resolved result and caller-reported proof receipts, reports missing/failed evidence and residual risk, and labels receipts as caller asserted. It never runs commands or stores diff/check output.

{
  "type": "object",
  "properties": {
    "evaluation": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "const": "1"
        },
        "evaluation_id": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "policy_profile": {
          "type": "string",
          "enum": [
            "permissive",
            "balanced",
            "strict"
          ]
        },
        "change": {
          "type": "object",
          "properties": {
            "ecosystem": {
              "type": "string",
              "const": "npm"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 214
            },
            "from_version": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 128
            },
            "to_version": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "dependency_type": {
              "type": "string",
              "enum": [
                "runtime",
                "development",
                "optional",
                "peer"
              ]
            }
          },
          "required": [
            "ecosystem",
            "name",
            "from_version",
            "to_version",
            "dependency_type"
          ],
          "additionalProperties": false
        },
        "baseline_fingerprint": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "baseline_project_snapshot": {
          "type": "string",
          "const": "not_supplied",
          "description": "Present only when the evaluation was made without a project snapshot. Part of the signed identity — pass it back verbatim."
        },
        "baseline_lockfile_sha256": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-fA-F0-9]{64}$"
        },
        "target_integrity": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 512
        },
        "baseline_advisory_ids": {
          "type": "array",
          "maxItems": 50,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        },
        "target_advisory_ids": {
          "type": "array",
          "maxItems": 50,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        },
        "repository_evidence": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "complete",
                "partial",
                "unavailable"
              ]
            },
            "recommendation": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "proceed_with_review",
                "review",
                "avoid",
                null
              ]
            },
            "headline": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 500
            },
            "evidence_gaps": {
              "type": "array",
              "maxItems": 20,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            }
          },
          "required": [
            "status",
            "recommendation",
            "headline",
            "evidence_gaps"
          ],
          "additionalProperties": false
        },
        "evaluation_findings": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]{0,127}$"
              },
              "severity": {
                "type": "string",
                "enum": [
                  "blocker",
                  "warning",
                  "info"
                ]
              },
              "source": {
                "type": "string",
                "enum": [
                  "npm_registry",
                  "deps_dev",
                  "repopilot",
                  "project_snapshot",
                  "caller_receipt"
                ]
              },
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "remediation": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "required": [
              "code",
              "severity",
              "source",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required_checks": {
          "type": "array",
          "maxItems": 12,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]{0,63}$"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "snapshot",
                  "command",
                  "diff"
                ]
              },
              "required": {
                "type": "boolean"
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "command_hint": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "required": [
              "id",
              "kind",
              "required",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "schema_version",
        "evaluation_id",
        "policy_profile",
        "change",
        "baseline_fingerprint",
        "baseline_lockfile_sha256",
        "target_integrity",
        "baseline_advisory_ids",
        "target_advisory_ids",
        "repository_evidence",
        "evaluation_findings",
        "required_checks",
        "expires_at"
      ],
      "additionalProperties": false,
      "description": "The verification_context object exactly as evaluate_dependency_change returned it, passed back unchanged. Its signature covers every field, so edit nothing inside it. Sending the whole evaluate result instead is accepted; the receipt is read out of its verification_context."
    },
    "after": {
      "type": "object",
      "properties": {
        "dependency_usage": {
          "type": "object",
          "description": "Optional local call shapes for this dependency under native Node with default conditions. No source, paths, local names or call arguments. Coverage is always partial; transpiled/bundled code is unsupported.",
          "additionalProperties": false,
          "required": [
            "schema_version",
            "runtime",
            "coverage",
            "uses"
          ],
          "properties": {
            "schema_version": {
              "type": "integer",
              "const": 1
            },
            "coverage": {
              "type": "string",
              "const": "partial"
            },
            "runtime": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "node",
                "platform",
                "arch"
              ],
              "properties": {
                "node": {
                  "type": "string",
                  "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
                  "maxLength": 32
                },
                "platform": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$",
                  "maxLength": 32
                },
                "arch": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$",
                  "maxLength": 32
                }
              }
            },
            "uses": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "loader",
                  "export_path"
                ],
                "properties": {
                  "loader": {
                    "type": "string",
                    "enum": [
                      "require",
                      "import"
                    ]
                  },
                  "export_path": {
                    "type": "array",
                    "maxItems": 2,
                    "items": {
                      "type": "string",
                      "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$",
                      "maxLength": 100
                    }
                  }
                }
              }
            }
          }
        },
        "package_manager": {
          "type": "string",
          "enum": [
            "npm",
            "pnpm",
            "yarn",
            "bun"
          ]
        },
        "node_version": {
          "type": "string",
          "maxLength": 64
        },
        "direct_dependencies": {
          "type": "object",
          "maxProperties": 200,
          "additionalProperties": {
            "type": "string",
            "maxLength": 128
          }
        },
        "installed_versions": {
          "type": "object",
          "maxProperties": 200,
          "additionalProperties": {
            "type": "string",
            "maxLength": 128
          }
        },
        "scripts": {
          "type": "array",
          "maxItems": 30,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          }
        },
        "manifest_path": {
          "type": "string",
          "maxLength": 512
        },
        "lockfile_path": {
          "type": "string",
          "maxLength": 512
        },
        "lockfile_sha256": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{64}$"
        },
        "head_sha": {
          "type": "string",
          "pattern": "^[a-fA-F0-9]{7,64}$"
        },
        "license_policy": {
          "type": "object",
          "properties": {
            "allow": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 64
              }
            },
            "deny": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "type": "string",
                "maxLength": 64
              }
            }
          },
          "additionalProperties": false
        },
        "resolved_changes": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 214
              },
              "from_version": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 128
              },
              "to_version": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "direct": {
                "type": "boolean"
              },
              "dependency_type": {
                "type": "string",
                "enum": [
                  "runtime",
                  "development",
                  "optional",
                  "peer"
                ]
              },
              "integrity": {
                "type": "string",
                "maxLength": 512
              }
            },
            "required": [
              "name",
              "from_version",
              "to_version",
              "direct"
            ],
            "additionalProperties": false
          }
        },
        "resolved_graph_complete": {
          "type": "boolean"
        }
      },
      "required": [
        "package_manager",
        "direct_dependencies",
        "resolved_changes"
      ],
      "additionalProperties": false
    },
    "diff": {
      "type": "string",
      "maxLength": 200000
    },
    "checks": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "command": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "exit_code": {
            "type": "integer",
            "minimum": 0,
            "maximum": 255
          },
          "summary": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [
          "id",
          "command",
          "exit_code"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "evaluation",
    "after",
    "checks"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "verify_dependency_change"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL to investigate behavior in public source: supply question and relevant path_hints found from actual usages, for up to four files with commit-pinned line citations. checked_sha selects a commit; base_sha adds before/after excerpts; pr selects a public PR and observes its head's GitHub check runs. source_ranges retrieves missing context at pinned revisions, up to 40 lines per range. Selection is bounded, not exhaustive or proof of compatibility. Without question, returns the cached repository decision brief. Pass exactly one of repo or package. Example: {repo:'expressjs/multer',question:'How are file size limits handled?',path_hints:['lib/make-middleware.js']}.

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "minLength": 3,
      "description": "Public GitHub repository as owner/repo or a github.com URL."
    },
    "package": {
      "type": "string",
      "minLength": 1,
      "description": "npm package name, for example lodash or npm:@scope/pkg. To judge a specific VERSION rather than the package as a whole, use evaluate_dependency_change instead."
    },
    "owner": {
      "type": "string",
      "minLength": 1,
      "description": "Repository owner, when repo carries only the bare name. Optional: prefer the single owner/repo form in repo."
    },
    "question": {
      "type": "string",
      "minLength": 1,
      "maxLength": 600
    },
    "checked_sha": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{40}$",
      "description": "Immutable head revision; required with source_ranges."
    },
    "base_sha": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{40}$",
      "description": "Compare source at this base commit; omit when using pr."
    },
    "pr": {
      "type": "integer",
      "minimum": 1,
      "description": "Public PR number in repo. Requires question. Omit base_sha."
    },
    "path_hints": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 4096
      },
      "description": "Scope retrieval to these repository-relative files or directories. Requires question."
    },
    "source_ranges": {
      "type": "array",
      "maxItems": 4,
      "description": "Read only these exact ranges, at most two per file/side and 40 lines per range. Requires question and checked_sha; base side also requires base_sha. Paths must fall within path_hints when supplied. Omit pr for base ranges.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path",
          "start_line",
          "end_line"
        ],
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "start_line": {
            "type": "integer",
            "minimum": 1,
            "description": "First line, inclusive, 1-based."
          },
          "end_line": {
            "type": "integer",
            "minimum": 1,
            "description": "Last line, inclusive; from start_line through start_line + 39."
          },
          "side": {
            "type": "string",
            "enum": [
              "head",
              "base"
            ],
            "default": "head"
          }
        }
      }
    }
  },
  "oneOf": [
    {
      "required": [
        "repo"
      ]
    },
    {
      "required": [
        "package"
      ]
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "analyze_repo"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL before editing an unfamiliar public repository, or to find where a bug or feature lives. Pass the issue or task text (up to 4000 characters; include the error and expected behaviour) and checked_sha when you know it. Returns files ranked for the task at that commit (provenance task_localizer), the owning layer, a bounded reading order, dependency consumers, test/verification obligations, analyzed-vs-checked SHA relation, evidence provenance, and a short-lived verification contract. To rank files, task text is sent to RepoPilot's model provider; it is never persisted or echoed. Rankings are suggestions: read the files before acting.

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "minLength": 3,
      "description": "Public GitHub repository as owner/repo or a github.com URL."
    },
    "package": {
      "type": "string",
      "minLength": 1,
      "description": "npm package name, for example lodash or npm:@scope/pkg. To judge a specific VERSION rather than the package as a whole, use evaluate_dependency_change instead."
    },
    "owner": {
      "type": "string",
      "minLength": 1,
      "description": "Repository owner, when repo carries only the bare name. Optional: prefer the single owner/repo form in repo."
    },
    "task": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    },
    "checked_sha": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{40}$"
    },
    "intent": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "dependency_change",
            "bug_fix",
            "feature",
            "refactor",
            "unknown"
          ]
        },
        "dependency": {
          "type": "string",
          "maxLength": 214
        },
        "from_version": {
          "type": "string",
          "maxLength": 128
        },
        "to_version": {
          "type": "string",
          "maxLength": 128
        }
      },
      "required": [
        "kind"
      ],
      "additionalProperties": false
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 12
    },
    "path_hints": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 512
      },
      "description": "Optional repository-relative files or directories to prioritize."
    }
  },
  "required": [
    "task"
  ],
  "oneOf": [
    {
      "required": [
        "repo"
      ]
    },
    {
      "required": [
        "package"
      ]
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "plan_repo_task"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL before substantial code work in an unfamiliar repository when the agent needs key files, entry points, architecture hypotheses, a reading order, and verify-before-trusting guidance. Returns the cached CLAUDE.md-style artifact or Cursor rules. Do not call again if the artifact is already in context. Takes NO artifact id: name the repository itself. Minimal call: {"repo":"vercel/next.js"}. Pass exactly one of repo or package, each a plain string.

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "minLength": 3,
      "description": "Public GitHub repository as owner/repo or a github.com URL."
    },
    "package": {
      "type": "string",
      "minLength": 1,
      "description": "npm package name, for example lodash or npm:@scope/pkg. To judge a specific VERSION rather than the package as a whole, use evaluate_dependency_change instead."
    },
    "owner": {
      "type": "string",
      "minLength": 1,
      "description": "Repository owner, when repo carries only the bare name. Optional: prefer the single owner/repo form in repo."
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "cursor"
      ],
      "default": "markdown",
      "description": "Optional. markdown for CLAUDE.md-style guidance (the default); cursor for .mdc rules."
    }
  },
  "description": "Name one repository (or one npm package) as a plain string. There is no artifact id in this contract. Minimal valid call: {\"repo\":\"vercel/next.js\"}.",
  "oneOf": [
    {
      "required": [
        "repo"
      ]
    },
    {
      "required": [
        "package"
      ]
    }
  ],
  "examples": [
    {
      "repo": "vercel/next.js"
    },
    {
      "repo": "vercel/next.js",
      "format": "cursor"
    },
    {
      "package": "lodash"
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "get_artifact"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL when the user is choosing between exactly two dependencies or repositories. Returns the preferred candidate for each use case, material trade-offs, confidence, and evidence gaps. Each target is owner/repo, a GitHub URL, an npm package name, or npm:@scope/pkg. Cached full analyses are preferred; a miss uses bounded live GitHub/OpenSSF evidence with limited confidence and explicit unknowns rather than guessing.

{
  "type": "object",
  "properties": {
    "a": {
      "type": "string",
      "minLength": 1,
      "description": "First repo or npm package target."
    },
    "b": {
      "type": "string",
      "minLength": 1,
      "description": "Second repo or npm package target."
    }
  },
  "required": [
    "a",
    "b"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "compare_repos"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}

CALL before merging a pull request or after producing a local diff. Returns a deterministic 0-10 change-shape score with receipts for size, spread, missing tests, sensitive paths, hotspots, and blast radius. Pass repo+pr OR diff; repo may accompany diff for cached hotspot context. This prioritizes review and never approves a merge.

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "minLength": 3,
      "description": "owner/repo or a github.com URL."
    },
    "pr": {
      "type": [
        "number",
        "string"
      ],
      "description": "Positive pull request number, used with repo."
    },
    "diff": {
      "type": "string",
      "minLength": 1,
      "description": "Raw unified git diff to score directly."
    },
    "files": {
      "type": "array",
      "minItems": 1,
      "maxItems": 250,
      "description": "Privacy-preserving changed-file facts; contains no source or diff hunks.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "previousPath": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "additions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          },
          "deletions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          },
          "status": {
            "type": "string",
            "enum": [
              "added",
              "modified",
              "removed",
              "renamed",
              "copied",
              "changed"
            ]
          },
          "line_counts_known": {
            "type": "boolean",
            "description": "False when Git could not provide text line counts; zeroes are then placeholders, not measured size."
          }
        },
        "required": [
          "path",
          "additions",
          "deletions",
          "status"
        ],
        "additionalProperties": false
      }
    },
    "contract_id": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{32}$",
      "description": "Optional short-lived contract_id returned by plan_repo_task."
    },
    "base_sha": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{40}$"
    },
    "head_sha": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{40}$"
    },
    "proofs": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "obligation_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "status": {
            "type": "string",
            "enum": [
              "passed",
              "failed",
              "skipped"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "client_reported",
              "github_check"
            ]
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 86400000
          }
        },
        "required": [
          "obligation_id",
          "status",
          "source"
        ],
        "additionalProperties": false
      }
    }
  },
  "oneOf": [
    {
      "required": [
        "diff"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "pr"
            ]
          },
          {
            "required": [
              "files"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "repo",
        "pr"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "diff"
            ]
          },
          {
            "required": [
              "files"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "files"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "diff"
            ]
          },
          {
            "required": [
              "pr"
            ]
          }
        ]
      }
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "tool": {
      "type": "string",
      "const": "check_change_risk"
    },
    "status": {
      "type": "string"
    },
    "agent": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "limited",
            "none"
          ]
        },
        "evidence_gaps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "summary",
        "confidence",
        "evidence_gaps",
        "next_actions"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "schema_version",
    "tool",
    "status",
    "agent"
  ],
  "additionalProperties": true
}