@ghx-dev/core 0.2.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ghx",
-  "description": "GitHub execution router for AI agents — 66 capabilities with deterministic routing and normalized output",
-  "version": "0.2.0",
+  "description": "GitHub execution router for AI agents — 70 capabilities with deterministic routing and normalized output",
+  "version": "0.2.1",
   "author": {
     "name": "Arye Kogan"
   },

package/README.md

@@ -14,16 +14,16 @@ Typed GitHub execution router for AI agents. Deterministic routing across CLI an
 
 ## Why ghx
 
-Agents instructed to "use `gh` CLI" for common PR and issue operations waste significant tokens on research, trial-and-error, and output parsing. Benchmarked across 27 runs on standard PR workflows:
+Agents instructed to "use `gh` CLI" for common PR and issue operations waste significant tokens on research, trial-and-error, and output parsing. Benchmarked across 40 runs on standard PR and issue workflows (MCP mode benchmark coming soon):
 
 | Metric | Improvement |
 |---|---|
-| Active tokens | **-37%** fewer tokens consumed |
-| Latency | **-32%** faster end-to-end |
-| Tool calls | **-33%** fewer tool invocations |
-| Success rate | **100%** (zero regressions) |
+| Tool calls | **-55%** (PR review), **-47%** (issue triage) |
+| Active tokens | **-88%** (PR review), **-41%** (thread resolution) |
+| Latency | **-57%** (PR review), **-26%** (thread resolution) |
+| Success rate | **100%** both modes |
 
-ghx eliminates the discovery phase: agents call typed capabilities, get validated results back in a stable envelope.
+Full report: [Codex 5.3 Benchmark](https://github.com/aryeko/ghx/blob/main/reports/codex-5.3-benchmark/README.md)
 
 ## Installation
 
@@ -84,6 +84,20 @@ Every capability returns a stable envelope:
 }
 ```
 
+## Chain: Batch Operations
+
+Batch multiple operations into a single tool call:
+
+```bash
+ghx chain --steps - <<'EOF'
+[
+  {"task":"issue.labels.remove","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["triage"]}},
+  {"task":"issue.labels.add","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["enhancement"]}},
+  {"task":"issue.comments.create","input":{"owner":"acme","name":"repo","issueNumber":42,"body":"Triaged."}}
+]
+EOF
+```
+
 ## Quick Start (Library API)
 
 ```ts
@@ -104,28 +118,21 @@ if (result.ok) {
 }
 ```
 
-Need a custom GraphQL transport? Use `createGithubClient(transport)` instead -- see the [advanced usage section](#custom-graphql-transport).
+Need a custom GraphQL transport? See [Custom GraphQL Transport](#custom-graphql-transport).
 
 ## Agent Onboarding
 
-Install ghx as a project skill for Claude Code:
+<details>
+<summary>Install ghx as a project skill for Claude Code</summary>
 
 ```bash
 npx @ghx-dev/core setup --scope project --yes
 npx @ghx-dev/core setup --scope project --verify
 ```
 
-### Setup Skill Source
-
-The canonical setup skill content is stored in:
-
-- `skills/using-ghx/SKILL.md` (package root)
-
-During build/publish it is copied to:
-
-- `dist/skills/using-ghx/SKILL.md`
+The canonical setup skill content is stored in `skills/using-ghx/SKILL.md` (package root). During build/publish it is copied to `dist/skills/using-ghx/SKILL.md`. `ghx setup` writes this content to `.agents/skills/ghx/SKILL.md` in user or project scope.
 
-`ghx setup` writes this content to `.agents/skills/ghx/SKILL.md` in user or project scope.
+</details>
 
 ## Agent Tools
 
@@ -152,25 +159,18 @@ console.log(explainCapability("repo.view"))
 const result = await tool.execute("repo.view", { owner: "aryeko", name: "ghx" })
 ```
 
-## 69 Capabilities
+## 70 Capabilities
 
-**Repository** -- `repo.view`, `repo.labels.list`, `repo.issue_types.list`
+| Domain | Count | Examples |
+|---|---|---|
+| Repository | 3 | `repo.view`, `repo.labels.list` |
+| Issues | 23 | create/update/close, labels, assignees, milestones, relations |
+| Pull Requests | 21 | diff, threads, reviews, checks, merge, branch update |
+| Workflows and CI | 11 | runs, jobs, logs, dispatch, rerun, cancel, artifacts |
+| Releases | 5 | view, list, create, update, publish |
+| Projects v2 | 7 | items, fields, add/remove issues |
 
-**Issues** -- `issue.view`, `issue.list`, `issue.comments.list`, `issue.create`, `issue.update`, `issue.close`, `issue.reopen`, `issue.delete`, `issue.labels.update`, `issue.assignees.update`, `issue.milestone.set`, `issue.comments.create`, `issue.linked_prs.list`, `issue.relations.get`, `issue.parent.set`, `issue.parent.remove`, `issue.blocked_by.add`, `issue.blocked_by.remove`
-
-**Pull Requests (read)** -- `pr.view`, `pr.list`, `pr.threads.list`, `pr.reviews.list`, `pr.diff.files`, `pr.checks.list`, `pr.merge.status`
-
-**Pull Requests (execute)** -- `pr.threads.reply`, `pr.threads.resolve`, `pr.threads.unresolve`, `pr.update`, `pr.reviews.submit`, `pr.reviews.request`, `pr.merge`, `pr.checks.rerun.failed`, `pr.checks.rerun.all`, `pr.branch.update`, `pr.assignees.add`, `pr.assignees.remove`
-
-**CI Diagnostics** -- `workflow.runs.list`, `workflow.job.logs.get`
-
-**Releases** -- `release.list`, `release.get`, `release.create_draft`, `release.update`, `release.publish_draft`
-
-**Workflow Controls** -- `workflow.list`, `workflow.get`, `workflow_dispatch.run`, `workflow_run.view`, `workflow_run.rerun_failed`, `workflow_run.rerun_all`, `workflow_run.cancel`, `workflow_run.artifacts.list`
-
-**Projects v2** -- `project_v2.org.get`, `project_v2.user.get`, `project_v2.fields.list`, `project_v2.items.list`, `project_v2.item.add_issue`, `project_v2.item.field.update`
-
-For exact input/output contracts, see the [operation card registry](https://github.com/aryeko/ghx/tree/main/packages/core/src/core/registry/cards).
+Full list: `ghx capabilities list` or [operation card registry](https://github.com/aryeko/ghx/tree/main/packages/core/src/core/registry/cards).
 
 ## Result Envelope
 
@@ -218,7 +218,8 @@ type ResultEnvelope<TData = unknown> = {
 - GitHub Cloud and GitHub Enterprise hosts (`GH_HOST` supported)
 - Route adapters: CLI and GraphQL
 
-## Public Exports
+<details>
+<summary>Public Exports</summary>
 
 Root (`@ghx-dev/core`):
 
@@ -233,7 +234,11 @@ Subpaths:
 
 - `@ghx-dev/core/cli` -- CLI entrypoint
 
-## Custom GraphQL Transport
+</details>
+
+<details>
+<a id="custom-graphql-transport"></a>
+<summary>Custom GraphQL Transport</summary>
 
 For full control over the GraphQL layer, pass your own transport to `createGithubClient`:
 
@@ -263,6 +268,8 @@ const result = await executeTask(
 )
 ```
 
+</details>
+
 ## Documentation
 
 - [Documentation Hub](https://github.com/aryeko/ghx/blob/main/docs/README.md)

package/dist/cards/issue.assignees.add.yaml

@@ -27,6 +27,7 @@ routing:
   fallbacks: [cli]
 graphql:
   operationName: IssueAssigneesAdd
+  operationType: mutation
   documentPath: src/gql/operations/issue-assignees-add.graphql
   resolution:
     lookup:

package/dist/cards/issue.assignees.remove.yaml

@@ -27,6 +27,7 @@ routing:
   fallbacks: [cli]
 graphql:
   operationName: IssueAssigneesRemove
+  operationType: mutation
   documentPath: src/gql/operations/issue-assignees-remove.graphql
   resolution:
     lookup:

package/dist/cards/issue.assignees.set.yaml

@@ -26,6 +26,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueAssigneesUpdate
+  operationType: mutation
   documentPath: src/gql/operations/issue-assignees-update.graphql
   resolution:
     lookup:

package/dist/cards/issue.close.yaml

@@ -23,6 +23,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueClose
+  operationType: mutation
   documentPath: src/gql/operations/issue-close.graphql
   resolution:
     lookup:

package/dist/cards/issue.comments.create.yaml

@@ -23,6 +23,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueCommentCreate
+  operationType: mutation
   documentPath: src/gql/operations/issue-comment-create.graphql
   resolution:
     lookup:

package/dist/cards/issue.comments.list.yaml

@@ -43,6 +43,7 @@ routing:
     - CLI fallback uses gh api graphql with bounded cursor pagination for comments.
 graphql:
   operationName: IssueCommentsList
+  operationType: query
   documentPath: src/gql/operations/issue-comments-list.graphql
 cli:
   command: api graphql

package/dist/cards/issue.create.yaml

@@ -25,6 +25,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueCreate
+  operationType: mutation
   documentPath: src/gql/operations/issue-create.graphql
   resolution:
     lookup:

package/dist/cards/issue.delete.yaml

@@ -22,6 +22,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueDelete
+  operationType: mutation
   documentPath: src/gql/operations/issue-delete.graphql
   resolution:
     lookup:

package/dist/cards/issue.labels.add.yaml

@@ -27,6 +27,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueLabelsAdd
+  operationType: mutation
   documentPath: src/gql/operations/issue-labels-add.graphql
   resolution:
     lookup:

package/dist/cards/issue.labels.remove.yaml

@@ -27,6 +27,7 @@ routing:
   fallbacks: [cli]
 graphql:
   operationName: IssueLabelsRemove
+  operationType: mutation
   documentPath: src/gql/operations/issue-labels-remove.graphql
   resolution:
     lookup:

package/dist/cards/issue.labels.set.yaml

@@ -26,6 +26,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueLabelsUpdate
+  operationType: mutation
   documentPath: src/gql/operations/issue-labels-update.graphql
   resolution:
     lookup:

package/dist/cards/issue.list.yaml

@@ -42,6 +42,7 @@ routing:
     - Prefer CLI for low-latency structured fetches when gh authentication is available.
 graphql:
   operationName: IssueList
+  operationType: query
   documentPath: src/gql/operations/issue-list.graphql
 cli:
   command: issue list

package/dist/cards/issue.milestone.clear.yaml

@@ -21,6 +21,7 @@ routing:
   fallbacks: [cli]
 graphql:
   operationName: IssueMilestoneSet
+  operationType: mutation
   documentPath: src/gql/operations/issue-milestone-set.graphql
   resolution:
     lookup:

package/dist/cards/issue.milestone.set.yaml

@@ -23,6 +23,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueMilestoneSet
+  operationType: mutation
   documentPath: src/gql/operations/issue-milestone-set.graphql
   resolution:
     lookup:

package/dist/cards/issue.relations.blocked_by.add.yaml

@@ -21,4 +21,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueBlockedByAdd
+  operationType: mutation
   documentPath: src/gql/operations/issue-blocked-by-add.graphql

package/dist/cards/issue.relations.blocked_by.remove.yaml

@@ -21,4 +21,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueBlockedByRemove
+  operationType: mutation
   documentPath: src/gql/operations/issue-blocked-by-remove.graphql

package/dist/cards/issue.relations.parent.remove.yaml

@@ -19,6 +19,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueParentRemove
+  operationType: mutation
   documentPath: src/gql/operations/issue-parent-remove.graphql
   resolution:
     lookup:

package/dist/cards/issue.relations.parent.set.yaml

@@ -21,4 +21,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueParentSet
+  operationType: mutation
   documentPath: src/gql/operations/issue-parent-set.graphql

package/dist/cards/issue.relations.prs.list.yaml

@@ -31,4 +31,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueLinkedPrsList
+  operationType: query
   documentPath: src/gql/operations/issue-linked-prs-list.graphql

package/dist/cards/issue.relations.view.yaml

@@ -51,4 +51,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueRelationsGet
+  operationType: query
   documentPath: src/gql/operations/issue-relations-get.graphql

package/dist/cards/issue.reopen.yaml

@@ -23,6 +23,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueReopen
+  operationType: mutation
   documentPath: src/gql/operations/issue-reopen.graphql
   resolution:
     lookup:

package/dist/cards/issue.update.yaml

@@ -26,6 +26,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueUpdate
+  operationType: mutation
   documentPath: src/gql/operations/issue-update.graphql
   resolution:
     lookup:

package/dist/cards/issue.view.yaml

@@ -28,6 +28,7 @@ routing:
     - Prefer GraphQL for structured fetch; CLI fallback if gh auth unavailable.
 graphql:
   operationName: IssueView
+  operationType: query
   documentPath: src/gql/operations/issue-view.graphql
 cli:
   command: issue view

package/dist/cards/pr.assignees.add.yaml

@@ -23,7 +23,11 @@ output_schema:
       items: { type: string }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: PrAssigneesAdd
+  operationType: mutation
+  documentPath: src/gql/operations/pr-assignees-add.graphql
 cli:
   command: pr edit

package/dist/cards/pr.assignees.remove.yaml

@@ -23,7 +23,11 @@ output_schema:
       items: { type: string }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: PrAssigneesRemove
+  operationType: mutation
+  documentPath: src/gql/operations/pr-assignees-remove.graphql
 cli:
   command: pr edit

package/dist/cards/pr.branch.update.yaml

@@ -17,7 +17,11 @@ output_schema:
     updated: { type: boolean }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: PrBranchUpdate
+  operationType: mutation
+  documentPath: src/gql/operations/pr-branch-update.graphql
 cli:
   command: pr update-branch

package/dist/cards/pr.create.yaml

@@ -3,7 +3,7 @@ version: "1.0.0"
 description: Create a pull request.
 input_schema:
   type: object
-  required: [owner, name, title, head]
+  required: [owner, name, title, head, base]
   properties:
     owner: { type: string, minLength: 1 }
     name: { type: string, minLength: 1 }
@@ -24,7 +24,11 @@ output_schema:
     draft: { type: boolean }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: PrCreate
+  operationType: mutation
+  documentPath: src/gql/operations/pr-create.graphql
 cli:
   command: pr create

package/dist/cards/pr.diff.files.yaml

@@ -38,6 +38,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrDiffListFiles
+  operationType: query
   documentPath: src/gql/operations/pr-diff-list-files.graphql
 cli:
   command: pr view

package/dist/cards/pr.list.yaml

@@ -42,6 +42,7 @@ routing:
     - Prefer CLI for low-latency structured fetches when gh authentication is available.
 graphql:
   operationName: PrList
+  operationType: query
   documentPath: src/gql/operations/pr-list.graphql
 cli:
   command: pr list

package/dist/cards/pr.merge.status.yaml

@@ -24,6 +24,7 @@ routing:
   fallbacks: [cli]
 graphql:
   operationName: PrMergeStatus
+  operationType: query
   documentPath: src/gql/operations/pr-merge-status.graphql
 cli:
   command: pr view

package/dist/cards/pr.merge.yaml

@@ -15,15 +15,21 @@ input_schema:
   additionalProperties: false
 output_schema:
   type: object
-  required: [prNumber, method, queued, deleteBranch]
+  required: [prNumber, method, isMethodAssumed, queued, deleteBranch]
   properties:
     prNumber: { type: integer, minimum: 1 }
     method: { type: string, enum: [merge, squash, rebase] }
+    isMethodAssumed: { type: boolean, description: "true when method was not specified by the caller and defaults to merge" }
     queued: { type: boolean }
     deleteBranch: { type: boolean }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  # GQL limitation: deleteBranch: true unsupported, triggers CLI fallback
+  operationName: PrMerge
+  operationType: mutation
+  documentPath: src/gql/operations/pr-merge.graphql
 cli:
   command: pr merge

package/dist/cards/pr.reviews.list.yaml

@@ -42,6 +42,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrReviewsList
+  operationType: query
   documentPath: src/gql/operations/pr-reviews-list.graphql
 cli:
   command: pr view

package/dist/cards/pr.reviews.request.yaml

@@ -20,12 +20,15 @@ output_schema:
     prNumber: { type: integer, minimum: 1 }
     reviewers:
       type: array
-      minItems: 1
       items: { type: string, minLength: 1 }
     updated: { type: boolean }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: PrReviewsRequest
+  operationType: mutation
+  documentPath: src/gql/operations/pr-reviews-request.graphql
 cli:
   command: pr edit

package/dist/cards/pr.reviews.submit.yaml

@@ -52,6 +52,7 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrReviewSubmit
+  operationType: mutation
   documentPath: src/gql/operations/pr-review-submit.graphql
   resolution:
     lookup:

package/dist/cards/pr.threads.list.yaml

@@ -93,6 +93,7 @@ routing:
     - Prefer GraphQL for review-thread semantics and unresolved filtering.
 graphql:
   operationName: PrCommentsList
+  operationType: query
   documentPath: src/gql/operations/pr-comments-list.graphql
 cli:
   command: api graphql

package/dist/cards/pr.threads.reply.yaml

@@ -22,4 +22,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrCommentReply
+  operationType: mutation
   documentPath: src/gql/operations/pr-comment-reply.graphql

package/dist/cards/pr.threads.resolve.yaml

@@ -19,4 +19,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrCommentResolve
+  operationType: mutation
   documentPath: src/gql/operations/pr-comment-resolve.graphql

package/dist/cards/pr.threads.unresolve.yaml

@@ -19,4 +19,5 @@ routing:
   fallbacks: []
 graphql:
   operationName: PrCommentUnresolve
+  operationType: mutation
   documentPath: src/gql/operations/pr-comment-unresolve.graphql

package/dist/cards/pr.update.yaml

@@ -23,7 +23,12 @@ output_schema:
     draft: { type: boolean }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  # GQL limitation: draft-only updates fall back to CLI
+  operationName: PrUpdate
+  operationType: mutation
+  documentPath: src/gql/operations/pr-update.graphql
 cli:
   command: pr edit

package/dist/cards/pr.view.yaml

@@ -28,6 +28,7 @@ routing:
     - Prefer GraphQL for structured fetch; CLI fallback if gh auth unavailable.
 graphql:
   operationName: PrView
+  operationType: query
   documentPath: src/gql/operations/pr-view.graphql
 cli:
   command: pr view

package/dist/cards/project_v2.fields.list.yaml

@@ -7,6 +7,8 @@ input_schema:
   properties:
     owner: { type: string, minLength: 1 }
     projectNumber: { type: integer, minimum: 1 }
+    first: { type: integer, minimum: 1 }
+    after: { type: [string, "null"] }
   additionalProperties: false
 output_schema:
   type: object
@@ -21,6 +23,15 @@ output_schema:
           id: { type: [string, "null"] }
           name: { type: [string, "null"] }
           dataType: { type: [string, "null"] }
+          options:
+            type: [array, "null"]
+            items:
+              type: object
+              required: [id, name]
+              properties:
+                id: { type: string }
+                name: { type: string }
+              additionalProperties: false
         additionalProperties: false
     pageInfo:
       type: object
@@ -31,7 +42,12 @@ output_schema:
       additionalProperties: false
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  # GQL limitation: user fallback handled in domain handler
+  operationName: ProjectV2FieldsListOrg
+  operationType: query
+  documentPath: src/gql/operations/project-v2-fields-list-org.graphql
 cli:
   command: project field-list

package/dist/cards/project_v2.items.field.update.yaml

@@ -17,13 +17,16 @@ input_schema:
   additionalProperties: false
 output_schema:
   type: object
-  required: [itemId, updated]
+  required: [itemId]
   properties:
-    itemId: { type: [string, "null"] }
-    updated: { type: boolean }
+    itemId: { type: string }
   additionalProperties: false
 routing:
-  preferred: cli
-  fallbacks: []
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: UpdateProjectV2ItemField
+  operationType: mutation
+  documentPath: src/gql/operations/project-v2-item-field-update.graphql
 cli:
   command: project item-edit