@ghx-dev/core 0.1.1 → 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ghx",
+  "description": "GitHub execution router for AI agents — 66 capabilities with deterministic routing and normalized output",
+  "version": "0.2.0",
+  "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

@@ -119,24 +119,24 @@ npx @ghx-dev/core setup --scope project --verify
 
 The canonical setup skill content is stored in:
 
-- `src/cli/assets/skills/ghx/SKILL.md`
+- `skills/using-ghx/SKILL.md` (package root)
 
 During build/publish it is copied to:
 
-- `dist/cli/assets/skills/ghx/SKILL.md`
+- `dist/skills/using-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,23 +152,21 @@ 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
+## 69 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 (read)** -- `pr.view`, `pr.list`, `pr.threads.list`, `pr.reviews.list`, `pr.diff.files`, `pr.checks.list`, `pr.merge.status`
 
-**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`
+**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** -- `check_run.annotations.list`, `workflow_runs.list`, `workflow_run.jobs.list`, `workflow_job.logs.get`, `workflow_job.logs.analyze`
+**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.get`, `workflow_run.rerun_failed`, `workflow_run.rerun_all`, `workflow_run.cancel`, `workflow_run.artifacts.list`
+**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`
 
@@ -233,7 +231,6 @@ Root (`@ghx-dev/core`):
 
 Subpaths:
 
-- `@ghx-dev/core/agent` -- `createExecuteTool`, `listCapabilities`, `explainCapability`, `MAIN_SKILL_TEXT`
 - `@ghx-dev/core/cli` -- CLI entrypoint
 
 ## Custom GraphQL Transport
@@ -268,11 +265,11 @@ const result = await executeTask(
 
 ## Documentation
 
-- [Architecture overview](https://github.com/aryeko/ghx/blob/main/docs/CODEMAPS/ARCHITECTURE.md)
-- [Module map](https://github.com/aryeko/ghx/blob/main/docs/CODEMAPS/MODULES.md)
-- [File map](https://github.com/aryeko/ghx/blob/main/docs/CODEMAPS/FILES.md)
-- [Operation card registry](https://github.com/aryeko/ghx/blob/main/docs/architecture/operation-card-registry.md)
-- [Publishing guide](https://github.com/aryeko/ghx/blob/main/docs/guides/publishing.md)
+- [Documentation Hub](https://github.com/aryeko/ghx/blob/main/docs/README.md)
+- [Architecture](https://github.com/aryeko/ghx/blob/main/docs/architecture/README.md)
+- [Capabilities Reference](https://github.com/aryeko/ghx/blob/main/docs/capabilities/README.md)
+- [Operation Cards](https://github.com/aryeko/ghx/blob/main/docs/architecture/operation-cards.md)
+- [Publishing Guide](https://github.com/aryeko/ghx/blob/main/docs/contributing/publishing.md)
 
 ## License
 

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

@@ -0,0 +1,50 @@
+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
+  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,50 @@
+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
+  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,47 @@
+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
+  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
@@ -22,3 +24,15 @@ routing:
 graphql:
   operationName: IssueClose
   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:
@@ -22,3 +24,15 @@ routing:
 graphql:
   operationName: IssueCommentCreate
   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.create.yaml

@@ -26,3 +26,14 @@ routing:
 graphql:
   operationName: IssueCreate
   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
@@ -21,3 +23,15 @@ routing:
 graphql:
   operationName: IssueDelete
   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,48 @@
+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
+  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,50 @@
+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
+  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,47 @@
+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
+  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.milestone.clear.yaml

@@ -0,0 +1,40 @@
+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
+  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

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

@@ -3,17 +3,20 @@ version: "1.0.0"
 description: Set issue milestone number or clear with null.
 input_schema:
   type: object
-  required: [issueId, milestoneNumber]
+  required: [owner, name, issueNumber, milestoneNumber]
   properties:
-    issueId: { type: string, minLength: 1 }
-    milestoneNumber: { type: [integer, "null"], minimum: 1 }
+    owner: { type: string, minLength: 1 }
+    name: { type: string, minLength: 1 }
+    issueNumber: { type: integer, minimum: 1 }
+    milestoneNumber: { type: integer, minimum: 1 }
   additionalProperties: false
 output_schema:
   type: object
-  required: [id, milestoneNumber]
+  required: [id, milestoneNumber, updated]
   properties:
     id: { type: string, minLength: 1 }
     milestoneNumber: { type: [integer, "null"] }
+    updated: { type: boolean }
   additionalProperties: false
 routing:
   preferred: graphql
@@ -21,3 +24,19 @@ routing:
 graphql:
   operationName: IssueMilestoneSet
   documentPath: src/gql/operations/issue-milestone-set.graphql
+  resolution:
+    lookup:
+      operationName: IssueMilestoneLookupByNumber
+      documentPath: src/gql/operations/issue-milestone-lookup-by-number.graphql
+      vars:
+        owner: owner
+        name: name
+        issueNumber: issueNumber
+        milestoneNumber: milestoneNumber
+    inject:
+      - target: issueId
+        source: scalar
+        path: repository.issue.id
+      - target: milestoneId
+        source: scalar
+        path: repository.milestone.id

package/dist/{core/registry/cards/issue.blocked_by.add.yaml → cards/issue.relations.blocked_by.add.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.blocked_by.add
+capability_id: issue.relations.blocked_by.add
 version: "1.0.0"
 description: Add a blocked-by relation for an issue.
 input_schema:
@@ -10,10 +10,11 @@ input_schema:
   additionalProperties: false
 output_schema:
   type: object
-  required: [issueId, blockedByIssueId]
+  required: [issueId, blockedByIssueId, added]
   properties:
     issueId: { type: string, minLength: 1 }
     blockedByIssueId: { type: string, minLength: 1 }
+    added: { type: boolean }
   additionalProperties: false
 routing:
   preferred: graphql

package/dist/cards/{issue.blocked_by.remove.yaml → issue.relations.blocked_by.remove.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.blocked_by.remove
+capability_id: issue.relations.blocked_by.remove
 version: "1.0.0"
 description: Remove a blocked-by relation for an issue.
 input_schema:

package/dist/cards/{issue.parent.remove.yaml → issue.relations.parent.remove.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.parent.remove
+capability_id: issue.relations.parent.remove
 version: "1.0.0"
 description: Remove an issue parent relation.
 input_schema:
@@ -20,3 +20,13 @@ routing:
 graphql:
   operationName: IssueParentRemove
   documentPath: src/gql/operations/issue-parent-remove.graphql
+  resolution:
+    lookup:
+      operationName: IssueParentLookup
+      documentPath: src/gql/operations/issue-parent-lookup.graphql
+      vars:
+        issueId: issueId
+    inject:
+      - target: parentIssueId
+        source: scalar
+        path: node.parent.id

package/dist/{core/registry/cards/issue.parent.set.yaml → cards/issue.relations.parent.set.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.parent.set
+capability_id: issue.relations.parent.set
 version: "1.0.0"
 description: Set an issue parent relation.
 input_schema:
@@ -10,10 +10,11 @@ input_schema:
   additionalProperties: false
 output_schema:
   type: object
-  required: [issueId, parentIssueId]
+  required: [issueId, parentIssueId, updated]
   properties:
     issueId: { type: string, minLength: 1 }
     parentIssueId: { type: string, minLength: 1 }
+    updated: { type: boolean }
   additionalProperties: false
 routing:
   preferred: graphql

package/dist/{core/registry/cards/issue.linked_prs.list.yaml → cards/issue.relations.prs.list.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.linked_prs.list
+capability_id: issue.relations.prs.list
 version: "1.0.0"
 description: List pull requests linked to an issue.
 input_schema:

package/dist/cards/{issue.relations.get.yaml → issue.relations.view.yaml}

@@ -1,4 +1,4 @@
-capability_id: issue.relations.get
+capability_id: issue.relations.view
 version: "1.0.0"
 description: Get issue parent/children/blocking relations.
 input_schema: