@ghx-dev/core 0.1.2 → 0.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ghx",
+  "description": "GitHub execution router for AI agents — 70 capabilities with deterministic routing and normalized output",
+  "version": "0.2.1",
+  "author": {
+    "name": "Arye Kogan"
+  },
+  "repository": "https://github.com/aryeko/ghx",
+  "homepage": "https://github.com/aryeko/ghx",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "github-api",
+    "ai-agents",
+    "agentic",
+    "cli",
+    "graphql",
+    "automation",
+    "typescript"
+  ]
+}

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,39 +118,32 @@ 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:
+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.
 
-- `src/cli/assets/skills/ghx/SKILL.md`
+</details>
 
-During build/publish it is copied to:
-
-- `dist/cli/assets/skills/ghx/SKILL.md`
-
-`ghx setup` writes this content to `.agents/skills/ghx/SKILL.md` in user or project scope.
-
-## Agent Tools (`@ghx-dev/core/agent`)
+## Agent Tools
 
 ```ts
 import {
   createExecuteTool,
-  listCapabilities,
+  createGithubClientFromToken,
+  executeTask,
   explainCapability,
-  MAIN_SKILL_TEXT,
-} from "@ghx-dev/core/agent"
-import { createGithubClientFromToken, executeTask } from "@ghx-dev/core"
+  listCapabilities,
+} from "@ghx-dev/core"
 
 // Wire the execute tool to the real engine
 const token = process.env.GITHUB_TOKEN!
@@ -152,27 +159,18 @@ console.log(explainCapability("repo.view"))
 const result = await tool.execute("repo.view", { owner: "aryeko", name: "ghx" })
 ```
 
-`MAIN_SKILL_TEXT` provides a ready-to-use system prompt describing all capabilities.
-
-## 66 Capabilities
-
-**Repository** -- `repo.view`, `repo.labels.list`, `repo.issue_types.list`
-
-**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.comments.list`, `pr.reviews.list`, `pr.diff.list_files`, `pr.status.checks`, `pr.checks.get_failed`, `pr.mergeability.view`
-
-**Pull Requests (execute)** -- `pr.comment.reply`, `pr.comment.resolve`, `pr.comment.unresolve`, `pr.ready_for_review.set`, `pr.review.submit_approve`, `pr.review.submit_request_changes`, `pr.review.submit_comment`, `pr.merge.execute`, `pr.checks.rerun_failed`, `pr.checks.rerun_all`, `pr.reviewers.request`, `pr.assignees.update`, `pr.branch.update`
+## 70 Capabilities
 
-**CI Diagnostics** -- `check_run.annotations.list`, `workflow_runs.list`, `workflow_run.jobs.list`, `workflow_job.logs.get`, `workflow_job.logs.analyze`
+| 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 |
 
-**Releases** -- `release.list`, `release.get`, `release.create_draft`, `release.update`, `release.publish_draft`
-
-**Workflow Controls** -- `workflow.list`, `workflow.get`, `workflow_dispatch.run`, `workflow_run.get`, `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
 
@@ -220,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,10 +232,13 @@ Root (`@ghx-dev/core`):
 
 Subpaths:
 
-- `@ghx-dev/core/agent` -- `createExecuteTool`, `listCapabilities`, `explainCapability`, `MAIN_SKILL_TEXT`
 - `@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`:
 
@@ -266,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

@@ -0,0 +1,51 @@
+capability_id: issue.assignees.add
+version: "1.0.0"
+description: Add assignees to an issue without replacing existing ones.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, assignees]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    assignees:
+      type: array
+      items: { type: string, minLength: 1 }
+      minItems: 1
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [issueNumber, added]
+  properties:
+    issueNumber: { type: integer, minimum: 1 }
+    added:
+      type: array
+      items: { type: string }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: IssueAssigneesAdd
+  operationType: mutation
+  documentPath: src/gql/operations/issue-assignees-add.graphql
+  resolution:
+    lookup:
+      operationName: IssueAssigneesLookupByNumber
+      documentPath: src/gql/operations/issue-assignees-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: assignableId
+        source: scalar
+        path: repository.issue.id
+      - target: assigneeIds
+        source: map_array
+        from_input: assignees
+        nodes_path: repository.assignableUsers.nodes
+        match_field: login
+        extract_field: id
+cli:
+  command: issue edit

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

@@ -0,0 +1,51 @@
+capability_id: issue.assignees.remove
+version: "1.0.0"
+description: Remove specific assignees from an issue.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, assignees]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    assignees:
+      type: array
+      items: { type: string, minLength: 1 }
+      minItems: 1
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [issueNumber, removed]
+  properties:
+    issueNumber: { type: integer, minimum: 1 }
+    removed:
+      type: array
+      items: { type: string, minLength: 1 }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: IssueAssigneesRemove
+  operationType: mutation
+  documentPath: src/gql/operations/issue-assignees-remove.graphql
+  resolution:
+    lookup:
+      operationName: IssueAssigneesLookupByNumber
+      documentPath: src/gql/operations/issue-assignees-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: assignableId
+        source: scalar
+        path: repository.issue.id
+      - target: assigneeIds
+        source: map_array
+        from_input: assignees
+        nodes_path: repository.assignableUsers.nodes
+        match_field: login
+        extract_field: id
+cli:
+  command: issue edit

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

@@ -0,0 +1,48 @@
+capability_id: issue.assignees.set
+version: "1.0.0"
+description: Replace issue assignees.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, assignees]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    assignees:
+      type: array
+      items: { type: string, minLength: 1 }
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [id, assignees]
+  properties:
+    id: { type: string, minLength: 1 }
+    assignees:
+      type: array
+      items: { type: string, minLength: 1 }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: []
+graphql:
+  operationName: IssueAssigneesUpdate
+  operationType: mutation
+  documentPath: src/gql/operations/issue-assignees-update.graphql
+  resolution:
+    lookup:
+      operationName: IssueAssigneesLookupByNumber
+      documentPath: src/gql/operations/issue-assignees-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: assignableId
+        source: scalar
+        path: repository.issue.id
+      - target: assigneeIds
+        source: map_array
+        from_input: assignees
+        nodes_path: repository.assignableUsers.nodes
+        match_field: login
+        extract_field: id

package/dist/cards/issue.close.yaml

@@ -3,9 +3,11 @@ version: "1.0.0"
 description: Close an issue.
 input_schema:
   type: object
-  required: [issueId]
+  required: [owner, name, issueNumber]
   properties:
-    issueId: { type: string, minLength: 1 }
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
   additionalProperties: false
 output_schema:
   type: object
@@ -21,4 +23,17 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueClose
+  operationType: mutation
   documentPath: src/gql/operations/issue-close.graphql
+  resolution:
+    lookup:
+      operationName: IssueNodeIdLookup
+      documentPath: src/gql/operations/issue-node-id-lookup.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: issueId
+        source: scalar
+        path: repository.issue.id

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

@@ -3,9 +3,11 @@ version: "1.0.0"
 description: Create an issue comment.
 input_schema:
   type: object
-  required: [issueId, body]
+  required: [owner, name, issueNumber, body]
   properties:
-    issueId: { type: string, minLength: 1 }
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
     body: { type: string, minLength: 1 }
   additionalProperties: false
 output_schema:
@@ -21,4 +23,17 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueCommentCreate
+  operationType: mutation
   documentPath: src/gql/operations/issue-comment-create.graphql
+  resolution:
+    lookup:
+      operationName: IssueNodeIdLookup
+      documentPath: src/gql/operations/issue-node-id-lookup.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: issueId
+        source: scalar
+        path: repository.issue.id

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,4 +25,16 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueCreate
+  operationType: mutation
   documentPath: src/gql/operations/issue-create.graphql
+  resolution:
+    lookup:
+      operationName: IssueCreateRepositoryId
+      documentPath: src/gql/operations/issue-create-repository-id.graphql
+      vars:
+        owner: owner
+        name: name
+    inject:
+      - target: repositoryId
+        source: scalar
+        path: repository.id

package/dist/cards/issue.delete.yaml

@@ -3,9 +3,11 @@ version: "1.0.0"
 description: Delete an issue.
 input_schema:
   type: object
-  required: [issueId]
+  required: [owner, name, issueNumber]
   properties:
-    issueId: { type: string, minLength: 1 }
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
   additionalProperties: false
 output_schema:
   type: object
@@ -20,4 +22,17 @@ routing:
   fallbacks: []
 graphql:
   operationName: IssueDelete
+  operationType: mutation
   documentPath: src/gql/operations/issue-delete.graphql
+  resolution:
+    lookup:
+      operationName: IssueNodeIdLookup
+      documentPath: src/gql/operations/issue-node-id-lookup.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: issueId
+        source: scalar
+        path: repository.issue.id

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

@@ -0,0 +1,49 @@
+capability_id: issue.labels.add
+version: "1.0.0"
+description: Add labels to an issue without removing existing labels.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, labels]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    labels:
+      type: array
+      items: { type: string, minLength: 1 }
+      minItems: 1
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [id, labels]
+  properties:
+    id: { type: string, minLength: 1 }
+    labels:
+      type: array
+      items: { type: string }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: []
+graphql:
+  operationName: IssueLabelsAdd
+  operationType: mutation
+  documentPath: src/gql/operations/issue-labels-add.graphql
+  resolution:
+    lookup:
+      operationName: IssueLabelsLookupByNumber
+      documentPath: src/gql/operations/issue-labels-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: labelableId
+        source: scalar
+        path: repository.issue.id
+      - target: labelIds
+        source: map_array
+        from_input: labels
+        nodes_path: repository.labels.nodes
+        match_field: name
+        extract_field: id

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

@@ -0,0 +1,51 @@
+capability_id: issue.labels.remove
+version: "1.0.0"
+description: Remove specific labels from an issue.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, labels]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    labels:
+      type: array
+      items: { type: string, minLength: 1 }
+      minItems: 1
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [issueNumber, removed]
+  properties:
+    issueNumber: { type: integer, minimum: 1 }
+    removed:
+      type: array
+      items: { type: string }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: IssueLabelsRemove
+  operationType: mutation
+  documentPath: src/gql/operations/issue-labels-remove.graphql
+  resolution:
+    lookup:
+      operationName: IssueLabelsLookupByNumber
+      documentPath: src/gql/operations/issue-labels-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: labelableId
+        source: scalar
+        path: repository.issue.id
+      - target: labelIds
+        source: map_array
+        from_input: labels
+        nodes_path: repository.labels.nodes
+        match_field: name
+        extract_field: id
+cli:
+  command: issue edit

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

@@ -0,0 +1,48 @@
+capability_id: issue.labels.set
+version: "1.0.0"
+description: Replace issue labels.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber, labels]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    labels:
+      type: array
+      items: { type: string, minLength: 1 }
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [id, labels]
+  properties:
+    id: { type: string, minLength: 1 }
+    labels:
+      type: array
+      items: { type: string, minLength: 1 }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: []
+graphql:
+  operationName: IssueLabelsUpdate
+  operationType: mutation
+  documentPath: src/gql/operations/issue-labels-update.graphql
+  resolution:
+    lookup:
+      operationName: IssueLabelsLookupByNumber
+      documentPath: src/gql/operations/issue-labels-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: labelableId
+        source: scalar
+        path: repository.issue.id
+      - target: labelIds
+        source: map_array
+        from_input: labels
+        nodes_path: repository.labels.nodes
+        match_field: name
+        extract_field: id

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

@@ -0,0 +1,41 @@
+capability_id: issue.milestone.clear
+version: "1.0.0"
+description: Remove the milestone from an issue.
+input_schema:
+  type: object
+  required: [owner, name, issueNumber]
+  properties:
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+  additionalProperties: false
+output_schema:
+  type: object
+  required: [issueNumber, cleared]
+  properties:
+    issueNumber: { type: integer, minimum: 1 }
+    cleared: { type: boolean }
+  additionalProperties: false
+routing:
+  preferred: graphql
+  fallbacks: [cli]
+graphql:
+  operationName: IssueMilestoneSet
+  operationType: mutation
+  documentPath: src/gql/operations/issue-milestone-set.graphql
+  resolution:
+    lookup:
+      operationName: IssueNodeIdLookup
+      documentPath: src/gql/operations/issue-node-id-lookup.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+    inject:
+      - target: issueId
+        source: scalar
+        path: repository.issue.id
+      - target: milestoneId
+        source: "null_literal"
+cli:
+  command: issue edit