feat: add Open Plugins v1.0.0 plugin manifest and command files

.plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "gor",
+  "version": "1.0.0",
+  "description": "GitHub CLI — manage PRs, issues, repos, CI, releases, search, codespaces, and more via the GitHub API",
+  "author": {
+    "name": "kerryhatcher"
+  },
+  "repository": "https://github.com/kerryhatcher/gor",
+  "homepage": "https://github.com/kerryhatcher/gor",
+  "license": "MIT OR Apache-2.0",
+  "keywords": ["github", "cli", "git", "pr", "issues", "ci", "devops"]
+}

AGENTS.md

@@ -310,3 +310,46 @@ Always create a story file before implementing a new command or subcommand.
 - `docs/research/research-architecture.md` — Crate ecosystem and architecture patterns
 - `docs/research/research-docs.md` — Documentation best practices
 - `docs/research/research-deployment.md` — Distribution and release automation
+
+---
+
+## Open Plugins Integration
+
+gor bundles an [Open Plugins](https://open-plugins.com/) v1.0.0 plugin manifest
+and command files, so CherryPi and other conformant agent tools can discover
+gor as an installable plugin.
+
+### Plugin structure
+
+```text
+.plugin/plugin.json       # Manifest: name, version, metadata
+commands/*.md             # Command files teaching agents how to use gor
+```
+
+Each `.md` file in `commands/` is loaded as a namespaced command available
+at `/gor:<name>` (e.g. `/gor:pr`, `/gor:repo`).
+
+### Installing the plugin
+
+Any conformant agent tool that scans Open Plugins directories will discover
+gor automatically when the repo root or a symlink is in the search path:
+
+```bash
+ln -s /path/to/gor ~/.local/share/cherrypi/plugins/gor
+```
+
+Or install via cargo and copy the plugin directory:
+
+```bash
+cargo install gor-cli
+cp -r .plugin commands ~/.local/share/cherrypi/plugins/gor/
+```
+
+### Key principles
+
+- The manifest (`name: "gor"`) namespaces all commands as `gor:<name>`.
+- Command files are documentation-first: they teach the AI how to invoke `gor`
+  with the right flags and `--json` output.
+- Changes to the CLI surface (new subcommands, changed flags) should be
+  reflected in the corresponding command file.
+- Adding a new command group? Create a matching `commands/<group>.md`.

commands/auth.md

@@ -0,0 +1,81 @@
+---
+description: Authenticate with GitHub — login, logout, status, token, and git credential setup
+---
+
+# GitHub Authentication via gor
+
+Use the `gor` CLI to authenticate with GitHub. Supports fine-grained PATs,
+classic PATs, and OAuth device flow.
+
+## Login
+
+Authenticate via OAuth device flow (opens a browser):
+
+```bash
+gor auth login
+```
+
+Or provide a token directly from a file or pipe:
+
+```bash
+gor auth login --with-token < ~/.gh-token
+```
+
+## Check status
+
+Verify you're authenticated and see which host and user:
+
+```bash
+gor auth status
+```
+
+## Logout
+
+Remove stored credentials:
+
+```bash
+gor auth logout
+```
+
+## View token
+
+Print the current token. Use `--secure` to mask the output (shows only first
+and last few characters):
+
+```bash
+gor auth token
+gor auth token --secure
+```
+
+> **Warning:** Tokens grant full API access. Never expose them in logs,
+> terminal history, screenshots, or agent output. Use `--secure` whenever
+> possible to reduce accidental disclosure.
+
+## Configure git credential helper
+
+Set up git to use `gor` as a credential helper (so git commands authenticate
+via your stored token):
+
+```bash
+gor auth setup-git
+gor auth setup-git --hostname github.mycompany.com
+```
+
+## Environment variables
+
+The following env vars are read automatically (no `auth login` needed):
+
+| Variable | Purpose |
+|---|---|
+| `GH_TOKEN` or `GITHUB_TOKEN` | Token for github.com |
+| `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN` | Token for GHES |
+| `GH_HOST` | Target hostname for GHES |
+
+## GitHub Enterprise Server
+
+Target a GHES instance on any command:
+
+```bash
+gor --hostname github.mycompany.com auth status
+gor --hostname github.mycompany.com repo view org/repo
+```

commands/ci.md

@@ -0,0 +1,43 @@
+---
+description: Manage GitHub Actions — workflows, runs, caches, and CI/CD operations
+---
+
+# CI/CD via gor
+
+Use the `gor` CLI to manage GitHub Actions workflows, runs, and caches.
+
+## Workflows
+
+```bash
+gor workflow list -R owner/repo
+gor workflow view .github/workflows/ci.yml -R owner/repo
+gor workflow run .github/workflows/ci.yml -R owner/repo
+gor workflow run .github/workflows/ci.yml -R owner/repo --ref main
+gor workflow enable .github/workflows/ci.yml -R owner/repo
+gor workflow disable .github/workflows/ci.yml -R owner/repo
+```
+
+## Workflow runs
+
+```bash
+gor run list -R owner/repo
+gor run list -R owner/repo --branch main --workflow ci.yml
+gor run view 1234567890 -R owner/repo
+gor run watch 1234567890 -R owner/repo
+gor run cancel 1234567890 -R owner/repo
+gor run rerun 1234567890 -R owner/repo --failed-jobs
+gor run download 1234567890 -R owner/repo --dir ./artifacts
+```
+
+## Cache management
+
+```bash
+gor cache list -R owner/repo
+gor cache list -R owner/repo --json key,size_in_bytes,ref
+
+# Delete by exact key
+gor cache delete --key "node-linux-pnpm-" -R owner/repo
+
+# Delete all caches
+gor cache delete --all -R owner/repo
+```

commands/codespace.md

@@ -0,0 +1,26 @@
+---
+description: Manage GitHub Codespaces — list, create, stop, delete, and SSH
+---
+
+# Codespaces via gor
+
+Use the `gor` CLI to manage GitHub Codespaces.
+
+```bash
+# List
+gor codespace list
+gor codespace list --json name,repository,state,branch
+
+# Create
+gor codespace create owner/repo
+gor codespace create owner/repo --branch feature-branch
+
+# SSH (positional: codespace name)
+gor codespace ssh my-codespace-name
+
+# Stop (positional: codespace name)
+gor codespace stop my-codespace-name
+
+# Delete (positional: codespace name, use --yes to skip prompt)
+gor codespace delete my-codespace-name --yes
+```

commands/gist.md

@@ -0,0 +1,23 @@
+---
+description: Manage Gists — list, view, create, edit, and delete
+---
+
+# Gists via gor
+
+Use the `gor` CLI to manage GitHub gists.
+
+```bash
+gor gist list
+gor gist list --limit 10 --json id,description,files
+
+gor gist view GIST_ID
+gor gist view GIST_ID --json id,description,files,created_at
+
+gor gist create file.md --desc "A useful snippet"
+gor gist create file1.rs file2.rs --desc "Rust examples" --public
+
+gor gist edit GIST_ID --desc "Updated description"
+gor gist edit GIST_ID --add new_file.rs --filename old_name:new_name
+
+gor gist delete GIST_ID
+```

commands/issue.md

@@ -0,0 +1,53 @@
+---
+description: Manage GitHub Issues — list, view, create, comment, close, and edit
+---
+
+# Issues via gor
+
+Use the `gor` CLI to manage GitHub issues.
+
+## List issues
+
+```bash
+gor issue list -R owner/repo
+gor issue list -R owner/repo --state closed --label bug
+gor issue list -R owner/repo --json number,title,labels,assignees
+```
+
+## View an issue
+
+```bash
+gor issue view 123 -R owner/repo
+gor issue view 123 -R owner/repo --json number,title,body,comments
+```
+
+## Create an issue
+
+```bash
+gor issue create -R owner/repo --title "Bug found" --body "Steps to reproduce..."
+gor issue create -R owner/repo --title "Feature request" --label enhancement
+```
+
+## Modify an issue
+
+```bash
+gor issue comment 123 -R owner/repo --body "I can reproduce this"
+gor issue close 123 -R owner/repo
+gor issue reopen 123 -R owner/repo
+gor issue edit 123 -R owner/repo --title "Updated title"
+```
+
+## Locking and pins
+
+```bash
+gor issue lock 123 -R owner/repo --reason spam
+gor issue unlock 123 -R owner/repo
+gor issue pin 123 -R owner/repo
+gor issue unpin 123 -R owner/repo
+```
+
+## Transfer to another repository
+
+```bash
+gor issue transfer 123 -R owner/repo target-owner/target-repo
+```

commands/label.md

@@ -0,0 +1,19 @@
+---
+description: Manage repository labels — list, create, edit, delete, and clone
+---
+
+# Labels via gor
+
+Use the `gor` CLI to manage repository labels.
+
+```bash
+gor label list -R owner/repo
+gor label list -R owner/repo --json name,color,description
+
+gor label create bug -R owner/repo --color d73a4a --description "Bug report"
+gor label edit bug -R owner/repo --name bug --color d73a4a
+gor label delete bug -R owner/repo
+
+# Clone labels: source is positional, target via -R
+gor label clone source-owner/source-repo -R target-owner/target-repo
+```

commands/other.md

@@ -0,0 +1,50 @@
+---
+description: Additional commands — browse, API, config, orgs, projects, rulesets, extensions, attestations, copilot, classroom
+---
+
+# Additional Commands via gor
+
+```bash
+# Browse — open in browser
+gor browse                     # Open current repo
+gor browse --issue 123         # Open issue
+gor browse --pr 42             # Open PR
+gor browse --settings          # Open repo settings
+
+# API — arbitrary REST calls
+gor api /repos/owner/repo
+gor api /repos/owner/repo/issues --method POST --field title="Bug"
+gor api graphql -f query="query { viewer { login } }"
+
+# Config
+gor config list
+gor config set --host github.com git_protocol ssh
+
+# Organizations
+gor org list
+gor org view my-org
+
+# Projects (GitHub Projects v2)
+gor project list -R owner/repo
+gor project view PROJECT_NUMBER -R owner/repo
+gor project item-add PROJECT_NUMBER -R owner/repo --title "Task"
+
+# Rulesets
+gor ruleset list -R owner/repo
+gor ruleset view RULESET_ID -R owner/repo
+
+# Extensions
+gor extension list
+gor extension install owner/repo
+
+# Attestations
+gor attestation verify path/to/artifact
+
+# Copilot
+gor copilot status
+gor copilot usage --org my-org
+
+# Classroom
+gor classroom list
+gor classroom view ASSIGNMENT_ID
+```