From fc7c8526180f94b9977a01aa9638e6edbf04fdc1 Mon Sep 17 00:00:00 2001 From: Josh Mabry Date: Wed, 28 Oct 2026 15:30:03 -0700 Subject: [PATCH] chore: cut tool-schema token cost ~43% (text only) Rewrite every github_* @tool docstring as one terse paragraph: what it does, when vs siblings, and the hard call-time constraints (merge confirm/sha guard, issue body gate, review guards, release confirm, 20000-char read cap + paging footer). No tool, parameter, type, default or required-ness changes. Workflow narrative (PR review, fix-round threads, CI triage, filing, merging, releasing) moves to a new skills/github/SKILL.md the host auto-loads. Schema chars (write: true, 38 tools): 33,287 -> 18,996 (-42.9%). Read-only 19 tools: 15,313 -> 9,054 (-40.9%). Co-Authored-By: Claude Opus 5.5 --- PROTO.md | 5 ++ read_tools.py | 179 ++++------------------------------------- release_tools.py | 84 ++----------------- review_tools.py | 38 +-------- skills/github/SKILL.md | 72 +++++++++++++++++ write_tools.py | 166 +++----------------------------------- 6 files changed, 115 insertions(+), 429 deletions(-) create mode 100644 skills/github/SKILL.md diff --git a/PROTO.md b/PROTO.md index 32141c6..3f9bc53 100644 --- a/PROTO.md +++ b/PROTO.md @@ -47,6 +47,7 @@ review_tools.py # 3 verdict tools (comment/approve/request-changes, gua gh_issue.py # /issue chat command logic + repo resolution (resolve_repo, default_repo_error) api.py # routers — public PAGES (view/workspace/new-issue) + gated data routes (config/status/issues/prs/issue) view.py # PAGE = read-only board; NEW_ISSUE_PAGE = file-an-issue form; shared setup card. --pl-* themed +skills/github/SKILL.md # workflow manual (review / fix round / CI / issues / merge / release) — host auto-loads skills/ tests/ # host-free pytest (gating + version coherence + routes via TestClient + the no-raise sweep) ``` @@ -191,6 +192,10 @@ run the resolution via `asyncio.to_thread`; checkout remotes are cached 10 min. - **Host-free.** NEVER import `graph.*` / `plugins.*` at module top — the suite runs with only `requirements-dev.txt`. Keep any host imports lazy (inside functions). +- **Tool descriptions are paid on EVERY model call** (the schema rides each request). Keep each + `@tool` docstring a terse single paragraph: what it does, when to use it vs siblings, and + hard call-time constraints (guards, caps, refusals). Workflow narrative and examples go in + `skills/github/SKILL.md`, not the docstring. - **`@tool` docstrings must be PLAIN string literals** — an f-string docstring makes `__doc__` None and the tool ships with no description (the model can't see it). - **Every tool requires an `owner/name` repo** — validate with `bad_repo()`. The diff --git a/read_tools.py b/read_tools.py index 9520fcc..673fb87 100644 --- a/read_tools.py +++ b/read_tools.py @@ -290,19 +290,7 @@ def _repos() -> list[str]: @tool async def github_get_pr(number: int, repo: str = "", body_max_chars: int = 0) -> str: - """Fetch a GitHub pull request — the merge-readiness picture in one call: title, - state, draft?, author, branch + head commit sha (and the merge commit once merged), - review decision, mergeability + merge state, a - checks summary (N pass / N fail / N pending + the failing check names), the - reviews (author, verdict, excerpt), changed files, and the body. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - body_max_chars: Body characters to fetch, capped at 60000. 0 (or negative) - uses the remaining 12000-character response budget. Do not round-trip-edit - a truncated body; fetch it in full with a larger limit first. - """ + """Fetch one PR's merge-readiness picture: title, state, draft, author, branch, head sha (merge commit once merged), review decision, mergeability + merge state, checks summary (pass/fail/pending + failing names), reviews, changed files, body. body_max_chars: up to 60000; 0 = fit the 12000-char response budget. Never round-trip-edit a truncated body; refetch it in full first.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -360,15 +348,7 @@ async def github_get_pr(number: int, repo: str = "", body_max_chars: int = 0) -> @tool async def github_get_issue(number: int, repo: str = "", body_max_chars: int = 0) -> str: - """Fetch a GitHub issue: title, state, author, labels, and body. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue number. - body_max_chars: Body characters to fetch, capped at 60000. 0 (or negative) - uses the remaining 12000-character response budget. Do not round-trip-edit - a truncated body; fetch it in full with a larger limit first. - """ + """Fetch an issue: title, state, author, labels, body. body_max_chars: up to 60000; 0 = fit the 12000-char response budget. Never round-trip-edit a truncated body; refetch it in full first.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -390,13 +370,7 @@ async def github_get_issue(number: int, repo: str = "", body_max_chars: int = 0) @tool async def github_list_issues(repo: str = "", state: str = "open", limit: int = 20) -> str: - """List GitHub issues for a repo. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - state: ``open`` | ``closed`` | ``all`` (default ``open``). - limit: Max issues to return (1-50, default 20). - """ + """List a repo's issues. state: open | closed | all; limit 1-50.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -435,13 +409,7 @@ async def github_list_issues(repo: str = "", state: str = "open", limit: int = 2 @tool async def github_get_commit_diff(ref: str, repo: str = "", max_chars: int = 8000) -> str: - """Fetch a commit's metadata + unified diff. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - ref: Commit SHA (or ref) to inspect. - max_chars: Truncate the diff at this many characters (default 8000). - """ + """Fetch a commit's metadata + unified diff (ref: SHA or ref; diff cut at max_chars).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -459,13 +427,7 @@ async def github_get_commit_diff(ref: str, repo: str = "", max_chars: int = 8000 @tool async def github_pr_diff(number: int, repo: str = "", max_chars: int = 12000) -> str: - """Fetch a pull request's full unified diff — for reviewing the change itself. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - max_chars: Truncate the diff at this many characters (default 12000). - """ + """Fetch a PR's full unified diff, for reviewing the change itself (cut at max_chars).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -481,15 +443,7 @@ async def github_pr_diff(number: int, repo: str = "", max_chars: int = 12000) -> @tool async def github_ci_runs(repo: str = "", branch: str = "", limit: int = 15) -> str: - """List recent GitHub Actions runs for a repo — for CI triage. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - branch: Optional branch filter (e.g. ``main``). - limit: Max runs to return (capped at 50). - - Feed a failing run's id to ``github_run_failure`` to see why it failed. - """ + """List recent GitHub Actions runs (optional branch filter; limit up to 50) for CI triage. Pass a failing run's id to github_run_failure.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -523,13 +477,7 @@ async def github_ci_runs(repo: str = "", branch: str = "", limit: int = 15) -> s @tool async def github_run_failure(run_id: int, repo: str = "", max_lines: int = 40) -> str: - """Explain why a GitHub Actions run failed — the error lines from its failed steps. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - run_id: The run id (``databaseId`` from ``github_ci_runs``). - max_lines: Cap on error lines returned (capped at 80). - """ + """Explain why an Actions run failed: the error lines from its failed steps. run_id = databaseId from github_ci_runs; max_lines up to 80.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -557,23 +505,7 @@ async def github_run_failure(run_id: int, repo: str = "", max_lines: int = 40) - # registering an fs project per repo. ─────────────────────────────────────────── @tool async def github_read_file(path: str, repo: str = "", ref: str = "", start_line: int = 1, end_line: int = 0) -> str: - """Read a file's raw contents from a GitHub repo — the whole file or a line range. - - Output is capped at 20000 chars per call. A longer read is cut at a LINE boundary - (never mid-line; the file is NOT broken there) and ends with a marker such as - ``… [truncated: showed lines 1-540 of 870 (20000-char cap); continue with start_line=541]``. - A ranged read ends with ``… [showed lines A-B of N; …]``. Page a large file with - ``start_line``/``end_line`` — don't guess at the rest or read another version instead. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - path: Path to the file within the repo (e.g. ``docs/guide.md``). For a directory - use ``github_repo_contents``; for a file as it is IN a PR use ``github_read_pr_file``. - ref: Optional branch / tag / SHA (default: the repo's default branch). - start_line: First line to return, 1-based (default 1). - end_line: Last line to return, inclusive; 0 (default) = to the end of the file - (still subject to the 20000-char cap). - """ + """Read a file from a repo at ref (empty = default branch), whole or start_line..end_line (1-based, inclusive; end_line 0 = to the end). Output capped at 20000 chars per call: a longer read is cut at a LINE boundary (the file isn't broken there) and ends with a footer like `… [truncated: showed lines 1-540 of 870 (20000-char cap); continue with start_line=541]`. Page on with start_line; don't guess the rest or read another version. Directory: github_repo_contents; a file as it is in a PR: github_read_pr_file.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -604,27 +536,7 @@ async def github_read_file(path: str, repo: str = "", ref: str = "", start_line: async def github_read_pr_file( number: int, path: str, repo: str = "", start_line: int = 1, end_line: int = 0 ) -> str: - """Read a file as it exists IN a pull request — at the PR's head commit. - - Use this for every code-context read while reviewing a PR. Unlike - ``github_read_file``, there is no ref to get wrong: the head SHA is resolved - server-side from the PR number, so the file you get is the PR's version, - including anything the PR adds. - - Output is capped at 20000 chars per call. A longer read is cut at a LINE boundary - (never mid-line; the file is NOT broken there) and ends with a marker such as - ``… [truncated: showed lines 1-540 of 870 (20000-char cap); continue with start_line=541]``. - A ranged read ends with ``… [showed lines A-B of N; …]``. Page a large file with - ``start_line``/``end_line`` — don't guess at the rest or read the base version instead. - - Args: - number: PR number. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - path: Path to the file within the repo (e.g. ``src/lib/queries.ts``). - start_line: First line to return, 1-based (default 1). - end_line: Last line to return, inclusive; 0 (default) = to the end of the file - (still subject to the 20000-char cap). - """ + """Read a file as it is IN a pull request, at the PR's head (resolved from the number, so no ref to get wrong; includes files the PR adds). Use for every code-context read while reviewing a PR. start_line/end_line: 1-based, inclusive; end_line 0 = to the end. Output capped at 20000 chars per call, cut at a LINE boundary with a footer ending `continue with start_line=N`; page on, don't guess the rest or read the base version.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -665,21 +577,7 @@ async def github_read_pr_file( @tool async def github_path_exists(path: str, repo: str = "", ref: str = "") -> str: - """Check whether a path exists in a GitHub repo — the grounding probe for - review claims about external references. - - A diff is often only correct if something OUTSIDE it exists (a cross-repo - `COPY --from` path, a workspace package, an action ref). The answer is - authoritative: EXISTS means the assumption holds (don't invent a problem - around it); MISSING means the dependency is really absent (that's the - finding). A tool error means UNVERIFIED — report a Gap, never a severity. - - Args: - repo: Repository as ``owner/name`` — may be a DIFFERENT repo than the - PR under review (that is the point). Omit for the default repo. - path: Repo-relative path to check (file or directory). - ref: Optional branch / tag / SHA (default: the repo's default branch). - """ + """Check whether a path (file or dir) exists in a repo at ref (empty = default branch); the repo may differ from the PR under review. Grounds review claims about things outside a diff (cross-repo COPY --from path, workspace package, action ref). EXISTS = the assumption holds, don't invent a problem; MISSING = really absent, that's the finding; a tool error = UNVERIFIED, report a Gap, never a severity.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -709,13 +607,7 @@ async def github_path_exists(path: str, repo: str = "", ref: str = "") -> str: @tool async def github_repo_contents(repo: str = "", path: str = "", ref: str = "") -> str: - """List the contents (files + dirs) of a path in a GitHub repo. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - path: Directory path within the repo (default: repo root). - ref: Optional branch / tag / SHA (default: the repo's default branch). - """ + """List the files + dirs at a path in a repo (default: root) at ref (empty = default branch).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -749,14 +641,7 @@ async def github_repo_contents(repo: str = "", path: str = "", ref: str = "") -> @tool async def github_list_prs(repo: str = "", state: str = "open", limit: int = 30) -> str: - """List pull requests — the PR board: number, title, author, state, draft?, branch, - review decision and merge state per row. Use ``github_get_pr`` for one PR's full picture. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - state: ``open`` (default) | ``closed`` | ``merged`` | ``all``. - limit: Max PRs to return (1-100, default 30). - """ + """List PRs, one row each: number, title, author, state, draft, branch, review decision, merge state. state: open | closed | merged | all; limit 1-100. One PR in full: github_get_pr.""" from .api import fetch_prs repo = resolve_repo(repo, default_repo) or "" @@ -790,15 +675,7 @@ async def github_list_prs(repo: str = "", state: str = "open", limit: int = 30) @tool async def github_issue_comments(number: int, repo: str = "", limit: int = 30) -> str: - """Read the comment thread on an issue or pull request (a PR is an issue for - comments): author, date and body per comment, newest ``limit`` in chronological - order. Use it to catch up on a discussion before replying or deciding. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue or PR number. - limit: Max comments to return (1-100, default 30 — the most recent ones). - """ + """Read the comment thread on an issue or PR: author, date, body; the newest `limit` (1-100) in chronological order. Catch up here before replying or deciding.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -830,17 +707,7 @@ async def github_issue_comments(number: int, repo: str = "", limit: int = 30) -> @tool async def github_review_threads(number: int, repo: str = "", include_resolved: bool = False) -> str: - """List a pull request's review THREADS (the inline, resolvable conversations — - CodeRabbit's and reviewers' line comments), with the thread id you pass to - ``github_reply_thread`` / ``github_resolve_thread``. Unresolved review threads keep a - PR's QA check from clearing, so after a fix round, read them here, then answer and - resolve each one. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Pull request number. - include_resolved: Also list already-resolved threads (default: unresolved only). - """ + """List a PR's inline review THREADS (resolvable line comments, e.g. CodeRabbit's) with the thread ids github_reply_thread / github_resolve_thread take; unresolved only unless include_resolved. Unresolved threads keep the PR's QA check from clearing, so after a fix round read, answer and resolve each.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -895,16 +762,7 @@ async def github_review_threads(number: int, repo: str = "", include_resolved: b @tool async def github_search_issues(query: str, repo: str = "", state: str = "open", limit: int = 20) -> str: - """Search a repo's issues by text — DEDUPE BEFORE FILING: call this with the - gist of a problem before ``github_create_issue`` and reference or reopen a - match instead of filing a duplicate. Returns number, state, title and URL per hit. - - Args: - query: Free-text search (GitHub issue search syntax; e.g. ``"default_repo" label:bug``). - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - state: ``open`` (default) | ``closed`` | ``all``. - limit: Max results (1-100, default 20). - """ + """Search a repo's issues (GitHub search syntax, e.g. `"default_repo" label:bug`); returns number, state, title, URL. DEDUPE BEFORE FILING: search the gist before github_create_issue and reference or reopen a match instead. state: open | closed | all; limit 1-100.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -939,12 +797,7 @@ async def github_search_issues(query: str, repo: str = "", state: str = "open", @tool async def github_status() -> str: - """Check whether the GitHub CLI is installed and authenticated, and which repo the - other github_* tools default to. Call this FIRST when any github_* tool returns an - authentication / not-found / CLI error, or before GitHub work on a fresh machine — - it says exactly what's wrong and what the operator must do (install `gh`, run - `gh auth login`, or paste a token in Settings ▸ GitHub). Takes no arguments. - """ + """Check that gh is installed + authenticated (as whom) and which repo the github_* tools default to; their `repo` arg is owner/name, omit it for that default. Call FIRST when a github_* tool returns an auth / not-found / CLI error, or on a fresh machine: it says what the operator must fix (install gh, `gh auth login`, or a token in Settings ▸ GitHub).""" from .status import compute_and_report, summarize_status # The getters may parse git remotes (blocking, cached) — off the event loop. diff --git a/release_tools.py b/release_tools.py index 0cceefd..176464f 100644 --- a/release_tools.py +++ b/release_tools.py @@ -89,17 +89,7 @@ def get_release_read_tools(default_repo="") -> list: @tool async def github_run_jobs(run_id: int, repo: str = "") -> str: - """Show one GitHub Actions run and every job in it — status and conclusion per job. - - Args: - run_id: The run's id (from github_dispatch_workflow or github_ci_runs). - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - - Use it to watch a multi-job workflow (a desktop build's per-platform legs, a - release's publish steps): the run is done when its status is ``completed``, and - it succeeded only if its conclusion is ``success``. A failed job's log is one - github_run_failure call away. - """ + """Show one Actions run and each job's status + conclusion (run_id from github_dispatch_workflow or github_ci_runs), to watch a multi-job workflow. Done when status is `completed`; succeeded only if conclusion is `success`. A failed job's log: github_run_failure.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -129,16 +119,7 @@ async def github_run_jobs(run_id: int, repo: str = "") -> str: @tool async def github_release(tag: str, repo: str = "") -> str: - """Show a GitHub release by tag: draft / prerelease, whether it is the repo's Latest - release, its assets (name and size) and the start of its notes. - - Args: - tag: The release tag, e.g. ``v1.4.0``. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - - "Latest" is GitHub's promoted release, not the newest tag: a release created - with latest=false only becomes Latest when something promotes it. - """ + """Show a release by tag: draft / prerelease, assets (name, size), the start of its notes, and whether it is Latest (GitHub's promoted release, not the newest tag: a latest=false release isn't Latest until promoted).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo) or _bad_tag(tag): return err @@ -172,15 +153,7 @@ async def github_release(tag: str, repo: str = "") -> str: @tool async def github_release_asset(tag: str, name: str, repo: str = "") -> str: - """Read the text of one small asset attached to a release (e.g. ``release-notes.md``). - - Args: - tag: The release tag, e.g. ``v1.4.0``. - name: The asset's exact file name. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - - Returns the asset's text (up to 200 KB). Binary assets aren't readable here. - """ + """Read the text (up to 200 KB) of one release asset by its exact file name, e.g. release-notes.md. Binary assets aren't readable.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo) or _bad_tag(tag): return err @@ -213,19 +186,7 @@ def get_release_write_tools(default_repo="") -> list: async def github_dispatch_workflow( workflow: str, repo: str = "", inputs: str = "", ref: str = "main", confirm: bool = False ) -> str: - """Start a manually-dispatched (workflow_dispatch) GitHub Actions workflow and return - the run it started. - - Args: - workflow: The workflow FILE name (e.g. ``prepare-release.yml``) or its numeric id. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - inputs: The workflow's inputs as ``key=value`` pairs, comma or newline separated - (e.g. ``bump=minor, dry_run=true`` or ``tag=v1.4.0``). - ref: The branch or tag whose copy of the workflow runs (default ``main``). - confirm: Must be true — a dispatch has real effects (opens PRs, builds, publishes). - - Returns the new run's id and url — watch it with github_run_jobs. - """ + """Start a workflow_dispatch workflow (FILE name, e.g. prepare-release.yml, or numeric id) from ref (default main); returns the run id + URL, watch it with github_run_jobs. inputs: key=value pairs, comma or newline separated. confirm must be true: a dispatch has real effects (opens PRs, builds, publishes).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -274,20 +235,7 @@ async def github_dispatch_workflow( async def github_create_tag( tag: str, sha: str, repo: str = "", message: str = "", verify_version: bool = True, confirm: bool = False ) -> str: - """Create an ANNOTATED tag at an exact commit and push it (via the git API). - - Args: - tag: The tag to create, e.g. ``v1.4.0``. - sha: The FULL 40-character commit sha to tag — for a release, the release PR's - merge commit, not whatever main points at now. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - message: The tag message (default ``Release ``). - verify_version: Check first that ``pyproject.toml`` at that commit declares the - tag's version (default true; skipped when the repo has no pyproject.toml). - confirm: Must be true — a pushed tag triggers release workflows and is never moved. - - Refuses when the tag already exists: a published tag is never moved. - """ + """Create and push an ANNOTATED tag at an exact commit. sha: the FULL 40-char sha; for a release, the release PR's merge commit, not current main. verify_version checks that pyproject.toml at that commit declares the tag's version (skipped if absent). confirm must be true: a pushed tag triggers release workflows. Refuses if the tag exists; a published tag is never moved.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo) or _bad_tag(tag): return err @@ -364,14 +312,7 @@ async def github_create_tag( @tool async def github_edit_release(tag: str, notes: str, repo: str = "", confirm: bool = False) -> str: - """Replace a release's notes (its body on the GitHub release page). - - Args: - tag: The release tag, e.g. ``v1.4.0``. - notes: The complete new notes, in Markdown. They REPLACE the old body. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - confirm: Must be true — the release page is public. - """ + """Replace a release's notes: `notes` is the complete new Markdown body. confirm must be true: the release page is public.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo) or _bad_tag(tag): return err @@ -394,18 +335,7 @@ async def github_edit_release(tag: str, notes: str, repo: str = "", confirm: boo async def github_upload_release_asset( tag: str, name: str, content: str, repo: str = "", clobber: bool = False, confirm: bool = False ) -> str: - """Upload text as a release asset under exactly ``name`` (e.g. ``release-notes.md``). - - Args: - tag: The release tag, e.g. ``v1.4.0``. - name: The asset's file name — it is published under exactly this name. - content: The asset's text. - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - clobber: Replace an existing asset of the same name (default false: refuse). - confirm: Must be true — release assets are public, and some are read by updaters. - - Read it back with github_release_asset to check what landed. - """ + """Upload text as a release asset published under exactly `name`. clobber=true replaces a same-name asset (default: refuse). confirm must be true: assets are public and some are read by updaters. Check it with github_release_asset.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo) or _bad_tag(tag): return err diff --git a/review_tools.py b/review_tools.py index 29670fc..36787d1 100644 --- a/review_tools.py +++ b/review_tools.py @@ -146,17 +146,7 @@ def get_review_tools(default_repo="") -> list: @tool async def github_review_comment(number: int, body: str, repo: str = "") -> str: - """Post a formal non-blocking COMMENT review on a pull request. - - The always-safe verdict: use it for findings while CI is still running, for - observations that shouldn't block a merge, or when a blocking verdict was - refused by its guards. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - body: The review body (findings, observations — markdown). - """ + """Post a non-blocking COMMENT review on a PR: the always-safe verdict, for findings while CI runs, observations that shouldn't block a merge, or when a blocking verdict was refused.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -166,18 +156,7 @@ async def github_review_comment(number: int, body: str, repo: str = "") -> str: @tool async def github_review_approve(number: int, body: str, repo: str = "") -> str: - """Post a formal APPROVE review on a pull request. GUARDED. - - Refused (with comment-instead guidance) while any check run is still - running, when CI cannot be read at all, or on a PR this agent authored. - An APPROVE clears the way to merge — it must reflect the PR's settled, - verified state, never a guess. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - body: The review body (what was verified, any non-blocking notes). - """ + """Post an APPROVE review on a PR. GUARDED: refused while any check is still running, when CI can't be read, or on a PR this agent authored. Approve only the settled, verified state, never a guess; body says what you verified.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -189,18 +168,7 @@ async def github_review_approve(number: int, body: str, repo: str = "") -> str: @tool async def github_review_request_changes(number: int, body: str, repo: str = "") -> str: - """Post a formal REQUEST_CHANGES review on a pull request. GUARDED. - - Refused (with comment-instead guidance) while any check run is still - running, when CI cannot be read at all, or on a PR this agent authored. - A broken-CI block must rest on a check that COMPLETED with a failure you - read — never on one still running or one you couldn't see. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - body: The review body — every blocking finding with file:line evidence. - """ + """Post a REQUEST_CHANGES review on a PR. GUARDED: refused while any check is still running, when CI can't be read, or on a PR this agent authored. A broken-CI block must rest on a check that COMPLETED failing and that you read. body: every blocking finding with file:line evidence.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err diff --git a/skills/github/SKILL.md b/skills/github/SKILL.md new file mode 100644 index 0000000..65ed992 --- /dev/null +++ b/skills/github/SKILL.md @@ -0,0 +1,72 @@ +--- +name: github +description: >- + Use when doing GitHub work through the github_* tools — reviewing a PR, answering + review threads after a fix round, triaging CI, filing or deduping issues, merging, or + cutting a release (dispatch → watch → tag → notes → assets). The tool descriptions + carry the call-time rules; this is the workflow manual behind them. +--- + +# GitHub — workflows for the github_* tools + +**Repo argument.** Every tool's `repo` is `owner/name`; omit it to use the agent's +configured default (`github_status` names it). Any auth / not-found / "gh missing" error: +call `github_status` first — it says exactly what the operator must fix. + +## Reviewing a PR + +1. `github_get_pr` — merge-readiness: review decision, merge state, checks summary + (failing names), the latest review per reviewer, changed files. +2. `github_pr_diff` for the change; `github_read_pr_file` for every code-context read + (the PR's head version — no ref to get wrong). Use `github_read_file` only for a + file on a branch / tag / SHA outside the PR. +3. Claims about things OUTSIDE the diff (a cross-repo `COPY --from` path, a workspace + package, an action ref): ground them with `github_path_exists`, possibly in another + repo. EXISTS = don't invent a problem; MISSING = the finding; tool error = a Gap. +4. Verdict: `github_review_comment` is always allowed. `github_review_approve` / + `github_review_request_changes` are refused while checks run, when CI is unreadable, + and on your own PR — fall back to a comment review when refused. + +**Paging big files.** Reads are capped at 20000 chars, cut at a line boundary, with a +footer: `… [truncated: showed lines 1-540 of 870 (20000-char cap); continue with +start_line=541]`, `… [showed lines A-B of N; end of file]` for a full range. Continue +with the `start_line` it names. A 404 on a file read lists the nearest existing parent +directory — fix the path from that listing rather than guessing siblings. + +## After a fix round + +`github_review_threads` → for each finding, `github_reply_thread` (what changed and +where) with `resolve=true`. Unresolved threads keep the QA check red and block +auto-merge; a PR-level `github_comment` does not clear them. + +## CI triage + +`github_ci_runs` (optionally by branch) → `github_run_failure ` for the +failing steps' error lines; `github_run_jobs` for per-job status of one run. + +## Filing issues + +`github_search_issues` with the gist first; reference or reopen a match. Then +`github_create_issue`; the body gate (same as `/issue`) wants `## Problem` (or +Motivation/Context), plus `## Steps to reproduce` / Evidence / Expected-vs-actual for a +bug, or `## Proposed direction` / `## Acceptance` for a feature. A refused body comes +back with a scaffold — fill it in and retry. + +## Merging + +`github_merge_pr` with `dry_run=true` to preview, then `confirm=true`. Pass the FULL head +`sha` you reviewed so a later push makes GitHub refuse instead of merging unreviewed code +(not combinable with `delete_branch`). A single-commit squash lands that commit's subject, +not the PR title — set `subject` when the title is what should land on main. + +## Releasing + +1. `github_dispatch_workflow` (e.g. `prepare-release.yml`, `inputs: bump=minor`, + `confirm=true`) → returns the run id. +2. `github_run_jobs ` until `completed`; success only if conclusion is `success`. +3. `github_create_tag` at the release PR's MERGE commit (full sha), `confirm=true`; + `verify_version` checks `pyproject.toml` there. Tags are never moved. +4. `github_release ` to check draft / Latest / assets. "Latest" is GitHub's promoted + release, not the newest tag. +5. `github_edit_release` (full replacement notes) / `github_upload_release_asset`, then + read an asset back with `github_release_asset`. diff --git a/write_tools.py b/write_tools.py index 16864a1..d9ad3ae 100644 --- a/write_tools.py +++ b/write_tools.py @@ -115,26 +115,7 @@ def _emit(topic: str, data: dict) -> None: async def github_create_issue( title: str, repo: str = "", body: str = "", labels: str = "", kind: str = "generic" ) -> str: - """Create a GitHub issue. Search first (``github_search_issues``) so you don't file - a duplicate. The body is GATED like the `/issue` command: it needs a substantive - description (>= 80 chars) with a ``## Problem`` (or Motivation/Context) section; a - ``bug`` also needs a ``## Steps to reproduce`` / Evidence / Expected-vs-actual - section; a ``feature`` needs a ``## Proposed direction`` or ``## Acceptance`` - section. A body that fails the gate is NOT posted — the tool returns what's - missing plus a scaffold to fill in. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - title: Issue title. - body: Issue body (Markdown) — use headings for the sections above. - labels: Optional comma-separated label names. - kind: ``generic`` (default) | ``bug`` | ``feature`` — picks the gate's required - sections and adds the type label (``bug`` / ``enhancement``). A ``generic`` - call whose ``labels`` include ``bug`` / ``enhancement`` is treated as that - kind (the repo's CI gate keys on the label). - - Returns the new issue URL, or the gate's "Not filed — missing …" with a scaffold. - """ + """Create an issue; returns its URL. Search first (github_search_issues) so you don't file a duplicate. The body is GATED like /issue; a failing body is NOT posted (you get what's missing + a scaffold): at least 80 chars with a `## Problem` (or Motivation/Context) section; kind=bug also needs `## Steps to reproduce` / Evidence / Expected-vs-actual; kind=feature needs `## Proposed direction` or `## Acceptance`. kind also adds the type label (bug / enhancement); a generic call labelled bug / enhancement is gated as that kind. labels: comma-separated.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -158,15 +139,7 @@ async def github_create_issue( @tool async def github_comment(number: int, body: str, repo: str = "") -> str: - """Add a comment to a GitHub issue or pull request. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue or PR number (a PR is an issue for commenting). - body: The comment body (Markdown). - - Returns the new comment URL. - """ + """Comment on an issue or PR (Markdown); returns the comment URL.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -178,17 +151,7 @@ async def github_comment(number: int, body: str, repo: str = "") -> str: @tool async def github_create_pr(head: str, title: str, repo: str = "", body: str = "", base: str = "main") -> str: - """Open a pull request. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - head: The branch with the changes. - title: PR title. - body: PR body (Markdown). - base: Base branch to merge into (default ``main``). - - Returns the new PR URL. - """ + """Open a PR from head into base; returns its URL.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -218,18 +181,7 @@ async def github_create_pr(head: str, title: str, repo: str = "", body: str = "" @tool async def github_edit_pr(number: int, repo: str = "", title: str = "", body: str = "", state: str = "") -> str: - """Edit a pull request's title/body and/or its draft state. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - title: New title (omit to leave unchanged). - body: New body / description (omit to leave unchanged). - state: ``ready`` to mark ready for review, ``draft`` to convert back to a - draft, or empty to leave the state unchanged. - - Returns the PR URL (or a short summary of what changed). - """ + """Edit a PR's title / body (omit = unchanged) and/or draft state: state=ready marks it ready for review, draft converts it back, empty leaves it.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -258,16 +210,7 @@ async def github_edit_pr(number: int, repo: str = "", title: str = "", body: str @tool async def github_edit_issue(number: int, repo: str = "", title: str = "", body: str = "") -> str: - """Edit a GitHub issue's title and/or body. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue number. - title: New title (omit to leave unchanged). - body: New body / description, Markdown (omit to leave unchanged). - - Returns the issue URL (gh's stdout), or an Error when neither title nor body is given. - """ + """Edit an issue's title and/or body (omit = unchanged; at least one is required). Returns the issue URL.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -295,28 +238,7 @@ async def github_merge_pr( dry_run: bool = False, confirm: bool = False, ) -> str: - """Merge a pull request. IRREVERSIBLE — guarded. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: PR number. - method: ``squash`` (default), ``merge``, or ``rebase``. - delete_branch: Delete the head branch after merging (default False). - subject: Merge-commit subject line. Squash/merge only — refused on rebase, - which GitHub ignores. A single-commit squash uses that COMMIT's subject, - not the PR title, unless subject is set — so fixing the PR title alone - does not fix the subject that lands on main. - body: Merge-commit body. Squash/merge only — refused on rebase. - sha: The FULL head commit sha you verified (reviews, checks). When set, the merge - happens only if the PR's head is still exactly that commit — a push after - your check makes GitHub refuse instead of merging unreviewed code. Can't be - combined with delete_branch. - dry_run: If true, report what WOULD be merged without merging. - confirm: Must be true to actually merge — a guard against accidental or - autonomous merges even when the per-agent write gate is on. - - Returns the merge result, a dry-run preview, or a refusal asking for confirm. - """ + """Merge a PR. IRREVERSIBLE: refused unless confirm=true (even with the write gate on); dry_run=true previews instead. method: squash | merge | rebase. subject / body set the merge commit (squash/merge only, refused on rebase); a single-commit squash lands that COMMIT's subject, not the PR title, unless subject is set. sha: the FULL head sha you verified; the merge then happens only if the head is still that commit (can't combine with delete_branch).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -386,17 +308,7 @@ async def github_merge_pr( async def github_close( number: int, repo: str = "", kind: str = "issue", reopen: bool = False, comment: str = "" ) -> str: - """Close (or reopen) an issue or pull request. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue or PR number. - kind: ``issue`` (default) or ``pr`` — they use different gh subcommands. - reopen: If true, reopen instead of close. - comment: Optional comment to post alongside a close (ignored on reopen). - - Returns a short confirmation. - """ + """Close an issue or PR, or reopen it (reopen=true). kind: issue | pr. comment is posted with a close (ignored on reopen).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -415,17 +327,7 @@ async def github_close( async def github_set_labels( number: int, repo: str = "", add: str = "", remove: str = "", kind: str = "issue" ) -> str: - """Add and/or remove labels on an issue or pull request. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue or PR number. - add: Comma-separated label names to add. - remove: Comma-separated label names to remove. - kind: ``issue`` (default) or ``pr``. - - Returns a short confirmation. - """ + """Add and/or remove labels (comma-separated) on an issue or PR (kind: issue | pr). A label that doesn't exist yet: github_create_label first.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -446,19 +348,7 @@ async def github_set_labels( @tool async def github_create_label(name: str, repo: str = "", color: str = "", description: str = "") -> str: - """Create a new label in a repository (`gh label create`). Does NOT overwrite an - existing label — no ``--force`` — so a label that already exists is reported as - such, not an error trace, and its color/description are left untouched. Use this - before ``github_set_labels`` when the label you want to apply doesn't exist yet. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - name: The label name. - color: Optional 6-character hex color (no leading ``#``); gh picks a random one if omitted. - description: Optional label description. - - Returns a short confirmation, or a readable "already exists" message. - """ + """Create a repo label (color: 6-char hex without #; random if omitted). Never overwrites: an existing label is reported and left untouched.""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -481,17 +371,7 @@ async def github_create_label(name: str, repo: str = "", color: str = "", descri async def github_set_assignees( number: int, repo: str = "", add: str = "", remove: str = "", kind: str = "issue" ) -> str: - """Add and/or remove assignees on an issue or pull request. - - Args: - repo: Repository as ``owner/name``. Omit to use the agent's configured default repo. - number: Issue or PR number. - add: Comma-separated GitHub usernames to assign. - remove: Comma-separated GitHub usernames to unassign. - kind: ``issue`` (default) or ``pr``. - - Returns a short confirmation. - """ + """Add and/or remove assignees (comma-separated usernames) on an issue or PR (kind: issue | pr).""" repo = resolve_repo(repo, default_repo) or "" if err := bad_repo(repo): return err @@ -512,19 +392,7 @@ async def github_set_assignees( @tool async def github_reply_thread(thread_id: str, body: str, resolve: bool = False) -> str: - """Reply INSIDE a pull request review thread (an inline, resolvable conversation — a - CodeRabbit or reviewer line comment), optionally resolving it in the same call. Use it - after a fix round to answer each finding where it was raised — say what changed and - where — then resolve it; a PR-level ``github_comment`` does NOT answer or clear a - thread. Get thread ids from ``github_review_threads``. - - Args: - thread_id: The review-thread id (``PRRT_…``) from ``github_review_threads``. - body: The reply (Markdown). - resolve: Also resolve the thread after replying (default False). - - Returns the reply URL (and whether the thread is now resolved). - """ + """Reply INSIDE a PR review thread (thread_id PRRT_… from github_review_threads); resolve=true also resolves it. After a fix round, answer each finding where it was raised (what changed, where); a PR-level github_comment does NOT answer or clear a thread.""" if err := _bad_thread_id(thread_id): return err if not (body or "").strip(): @@ -542,17 +410,7 @@ async def github_reply_thread(thread_id: str, body: str, resolve: bool = False) @tool async def github_resolve_thread(thread_id: str, unresolve: bool = False) -> str: - """Resolve (or unresolve) a pull request review thread. Unresolved threads keep a PR's - QA check from clearing and so block auto-merge; resolve one only once its finding is - fixed or answered (prefer ``github_reply_thread`` with ``resolve=true`` so the answer - is on the thread). Get thread ids from ``github_review_threads``. - - Args: - thread_id: The review-thread id (``PRRT_…``) from ``github_review_threads``. - unresolve: Re-open a resolved thread instead (default False). - - Returns a short confirmation. - """ + """Resolve (or unresolve=true) a PR review thread (id from github_review_threads). Unresolved threads block the QA check and auto-merge; resolve only once the finding is fixed or answered, preferably via github_reply_thread with resolve=true.""" if err := _bad_thread_id(thread_id): return err mutation = "unresolveReviewThread" if unresolve else "resolveReviewThread"