@gallopsystems/agent-skills 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/copier-template/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "copier-template",
+  "description": "Maintain a Copier project template and propagate updates to generated repos: template anatomy, testing changes, releasing versions, and applying copier update in descendants with conflict resolution.",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: copier-template
+description: Maintain a Copier project template and propagate updates to generated ("descendant") repos. Covers template anatomy (copier.yml, jinja, tasks), testing template changes, tagging/releasing versions, the automated update-notification PR pattern, and applying copier update in descendants with conflict resolution.
+---
+
+# Copier Template Maintenance & Propagation
+
+Patterns for the full lifecycle of a [Copier](https://copier.readthedocs.io/) project template: authoring changes, testing them, releasing versions, and rolling updates out to every repo generated from the template.
+
+## When to Use This Skill
+
+- Editing the template repo (questions, scaffold files, tasks, CI)
+- "Upstream this pattern to the template" — porting something proven in a descendant
+- Tagging/releasing a new template version
+- Applying a template update in a descendant repo (often via an automated "template update available" PR)
+- Debugging `copier copy`/`copier update` failures
+
+## Mental Model
+
+- The **template repo** holds `copier.yml` (questions + settings + tasks) and a `template/` subdirectory of scaffold files (some `.jinja`-suffixed for substitution). **Git tags (`v*`) are the version protocol**; GitHub Releases are the changelog protocol.
+- Each **descendant** carries `.copier-answers.yml` recording its answers and `_commit: vX.Y.Z` — the template version it's on. Never hand-edit this file; `copier update` maintains it.
+- `copier update` re-renders from old-tag → newest tag and three-way merges against local changes. **It always jumps to the latest tag** (unless `--vcs-ref` pins one) — a notification PR advertising v1.5.0 may actually land v1.8.0 if the template moved on.
+- Run copier via `uvx copier ...` (no global install needed). Templates with `_tasks` require `--trust` — without it copier refuses to render at all. Non-interactive contexts also need `--defaults` (and `--data key=value` for required questions without defaults).
+
+## Direction of Change
+
+**Prove patterns in a real descendant first, then upstream.** Build and merge the feature in one generated project; once proven, port it into `template/` with jinja-aware adaptations. The upstream PR body should cite the originating repo/PR and include validation evidence (a project generated from the branch passing typecheck/lint/tests). Exception: infra-only changes (CI jobs, hooks config) can go straight to the template. For risky changes, stage the rollout — hand-run script in one repo first, graduate to the template once the win is proven.
+
+When working in a descendant and a fix belongs in the template too: fix the symptom locally *and* make the corresponding change in the template repo (verify you have the right repo with `git remote -v` — don't trust the directory name).
+
+## Releasing a Template Version
+
+After merging to the template's main:
+
+```bash
+git checkout main && git pull --ff-only
+git tag --sort=-v:refname | head -5          # see existing versions
+git cat-file -t v<latest>                     # match the tag type convention (lightweight vs annotated)
+git tag v<X.Y.Z> && git push origin v<X.Y.Z>
+gh release create v<X.Y.Z> --title "v<X.Y.Z> — <summary>" --notes "$(cat <<'EOF'
+## Changes
+- ...
+
+## Upgrading
+Run `uvx copier update --trust --defaults` in your project.
+
+Full diff: <template-repo-url>/compare/v<prev>...v<X.Y.Z>
+EOF
+)"
+```
+
+- Semver: patch = fixes/dep bumps; minor = new features, questions, or components; major = breaking structure changes.
+- **Always create the GitHub Release, not just the tag.** Descendant notification PRs link to `/releases/tag/<version>` — a tag without a release produces dead links downstream.
+
+## Automated Update Notification
+
+The template ships its descendants a checker workflow (daily cron + `workflow_dispatch`) that compares `.copier-answers.yml`'s `_commit` against the template's highest remote tag:
+
+```bash
+git ls-remote --tags --refs --sort=-v:refname <template-url> 'v*' | head -1
+```
+
+If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with an `--allow-empty` commit and opens a PR whose body contains the version delta, release-notes/compare links, and step-by-step instructions an agent can execute. Hard-won details to keep if reimplementing: an explicit `permissions: contents: write, pull-requests: write` block (default token can't open PRs), a static branch name (dated branches caused duplicate PRs), and comparing **tag versions, not commit SHAs**.
+
+## Further Reading
+
+- **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)
+- **Applying an update in a descendant** (the conflict-resolution procedure): [applying-updates.md](applying-updates.md)

package/plugins/copier-template/skills/copier-template/applying-updates.md

@@ -0,0 +1,87 @@
+# Applying a Template Update in a Descendant
+
+Usually triggered by the automated "template update available" PR — its body contains the runbook; this file is the full procedure with the judgment calls spelled out.
+
+## The sequence
+
+```bash
+gh pr view <n> --json title,body                 # read the bot PR's instructions
+git checkout chore/template-update && git pull   # the bot's static branch
+
+# clean tree required — copier refuses otherwise
+git stash --include-untracked -m "wip before template update"   # if dirty
+
+uvx copier update --trust --defaults
+
+# triage
+git status --short            # UU = unmerged (inline conflict markers)
+find . -name '*.rej'          # hunks copier couldn't apply
+grep _commit .copier-answers.yml   # confirm the new version
+```
+
+Note the version it reports: `copier update` goes to the **latest** tag, which may be newer than the one the bot PR advertised. A multi-version jump means several releases' worth of changes land at once — budget for more conflicts.
+
+## Resolving conflicts
+
+Copier writes diff3-style inline markers:
+
+```
+<<<<<<< before updating
+<your project's current content>
+||||||| last update
+<what the old template version had>
+=======
+<what the new template version has>
+>>>>>>> after updating
+```
+
+Survey all conflict blocks first: `awk '/^<<<<<<< /,/^>>>>>>> /' <file>`.
+
+**Decision procedure per file** — check `git log --oneline -- <file>`:
+
+| File history | Resolution |
+|---|---|
+| Hand-customized in this project | Keep ours (project side) |
+| Untouched scaffold since generation | Take theirs (template side) |
+| Shared file with both kinds of changes (login page, CI workflow, app config) | Merge both — keep project customizations *and* add the template's new feature |
+
+Mechanical resolutions with perl (whole-block operations, safe for multi-line):
+
+```bash
+# keep ours: delete the entire conflict block (template side discarded)
+perl -0pi -e 's/^<<<<<<< before updating\n(.*?)^\|\|\|\|\|\|\| last update\n.*?^>>>>>>> after updating\n/$1/gms' <file>
+
+# keep both sides (ours then theirs)
+perl -0pi -e 's/^<<<<<<< before updating\n(.*?)^\|\|\|\|\|\|\| last update\n.*?^=======\n(.*?)^>>>>>>> after updating\n/$1$2/gms' <file>
+```
+
+**`.rej` files**: copier couldn't apply a hunk (the local file diverged too far). Read the `.rej`, re-apply its *intent* manually — and check whether copier dropped project-specific content nearby (e.g. local vars in `.env.example`) — then `rm` the `.rej`.
+
+**Review the non-conflicted changes too.** Copier silently overwrites scaffold-owned files, and a new template assumption can be wrong for this project (e.g. a type coercion that assumes numeric IDs in a project using string IDs). `git diff` every copier-touched app-code file; revert what doesn't fit, and consider whether the template itself needs a fix.
+
+Final sweep before staging:
+
+```bash
+grep -rn '<<<<<<<\|>>>>>>>' . --exclude-dir=node_modules
+```
+
+## Validate, commit, hand back
+
+```bash
+git add -A   # includes .copier-answers.yml — it must be committed with the update
+yarn install && yarn typecheck && yarn lint && yarn fmt:check && yarn test:run
+```
+
+Commit as `chore: update to template vX.Y.Z` with a body listing the notable upstream changes **and each conflict resolution with its rationale** — that's the audit trail for the squash-merge. Then retitle the bot PR (`gh pr edit <n> --title "chore: update to template vX.Y.Z"`), push, watch CI, and ask the user before merging. The bot's empty placeholder commit is fine — it disappears in the squash.
+
+**If something fails after the update**, prove whether it's pre-existing before blaming the update: `git worktree add /tmp/<proj>-main origin/main`, reuse node_modules (symlink), rerun the failing check there. A byte-identical failure on main means fix-forward in this PR, not a regression.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Destination repository is dirty; cannot continue` | `git stash --include-untracked` — plain `git stash` misses untracked files (including editor swap files), which still count as dirty |
+| Copier refuses to render at all | Template has `_tasks` — add `--trust` |
+| Hangs or fails in non-interactive shells | Add `--defaults` (and `--data key=value` for questions without defaults) |
+| Update landed a version you didn't expect | `copier update` always targets the latest tag; pin with `--vcs-ref v<X.Y.Z>` if you need a specific one |
+| Template change is wrong for this project | Revert locally, note it in the commit body, open a template issue/PR if other descendants are affected |

package/plugins/copier-template/skills/copier-template/template-authoring.md

@@ -0,0 +1,89 @@
+# Template Anatomy & Testing Changes
+
+## copier.yml settings
+
+```yaml
+_subdirectory: template        # only this dir is rendered; repo root holds copier.yml, test.sh, README
+_templates_suffix: .jinja      # only .jinja files get substitution; everything else copies verbatim
+_skip_if_exists:
+  - ".env"                     # never clobber these on update
+```
+
+## Questions
+
+```yaml
+project_name:
+  type: str
+  validator: "{% if not project_name %}Required{% endif %}"
+database_name:
+  type: str
+  default: "{{ project_name }}"     # defaults can reference earlier answers
+include_ci:
+  type: bool
+  default: true
+```
+
+Feature toggles as `include_*` booleans defaulting `true` keep `copier copy --defaults` producing a fully-featured project.
+
+## Conditional files via filename templating
+
+A file named `{% if include_ci %}ci.yml{% endif %}.jinja` renders to `ci.yml` when the flag is true and to an empty filename (skipped) when false. This works for plain files too — the filename is always templated, only contents need the `.jinja` suffix.
+
+## The self-rendering answers file
+
+```
+template/{{_copier_conf.answers_file}}.jinja
+```
+
+containing:
+
+```yaml
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+{{ _copier_answers|to_nice_yaml }}
+```
+
+This is what writes `.copier-answers.yml` into every descendant.
+
+## Tasks
+
+Gate scaffold-time tasks so they run on first copy only, never on update:
+
+```yaml
+_tasks:
+  - command: createdb {{ database_name }}
+    when: "{{ _copier_operation == 'copy' }}"
+```
+
+- **Task order is load-bearing**: anything importing generated artifacts must run after the generator (e.g. seed after codegen); `git init` before installing git hooks.
+- Tasks needing env vars: `bash -c 'set -a && source .env && set +a && <cmd>'`.
+- Tasks gated on a question flag: combine conditions in `when`.
+- Prefer post-gen install tasks (e.g. `npx <tool> add ...`) over vendoring third-party files into the template — vendored copies go stale.
+
+## Escaping `${{ }}` in templated GitHub workflows
+
+Jinja eats GitHub Actions expressions in `.jinja` workflow files. Two working escapes:
+
+```
+{% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+${{ '{{' }} secrets.GITHUB_TOKEN {{ '}}' }}
+```
+
+`{% raw %}` blocks are cleaner when a whole region is Actions syntax; the inline form suits one-offs inside otherwise-templated lines.
+
+## Testing template changes
+
+A `test.sh` that generates a real project and runs its full gate:
+
+```bash
+tmp=$(mktemp -d)
+trap 'dropdb --if-exists <test-dbs>; rm -rf "$tmp"' EXIT
+uvx copier copy --trust --defaults --vcs-ref HEAD \
+  --data project_name=smoke-test --data project_description=test \
+  . "$tmp"
+cd "$tmp" && yarn install && yarn lint && yarn fmt:check && yarn test:run
+```
+
+- **`--vcs-ref HEAD` tests committed HEAD instead of the last tag** — without it, copier renders the latest *tag* and your changes are silently absent.
+- For *uncommitted* working-tree validation: `cp -r` the template to a temp dir, `rm -rf .git` in the copy, and `copier copy` from there.
+- When the generated project reveals a bug, **fix it in `template/` source and re-render** — never only in the generated copy. Re-sync (`cp` the fixed file into the generated project) to re-verify without a full regeneration.
+- Generating a project is also how template-level type/lint bugs get caught — run the descendant's typecheck against the freshly generated output as part of any nontrivial template PR, and say so in the PR body.

package/plugins/doctl/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "doctl",
-  "description": "Manage DigitalOcean App Platform deployments with the doctl CLI: auth contexts, listing apps, monitoring deployments, and checking logs.",
-  "version": "1.0.0",
+  "description": "Manage DigitalOcean resources with the doctl CLI: auth contexts, App Platform deployments and logs, app specs and secrets, repo-to-app resolution, databases, Spaces, and droplets.",
+  "version": "1.1.0",
   "author": {
     "name": "yeedle"
   }

package/plugins/doctl/skills/doctl/SKILL.md

@@ -1,93 +1,119 @@
 ---
 name: doctl
-description: Manage DigitalOcean App Platform deployments with doctl CLI. Covers auth contexts, listing apps, monitoring deployments, and checking logs.
+description: Manage DigitalOcean resources with the doctl CLI. Covers auth contexts, App Platform (deployments, logs, env vars/secrets via app specs), mapping a git repo to its app, managed databases, Spaces keys, and droplets.
 ---
 
 # DigitalOcean doctl CLI Patterns
 
-This skill provides patterns for managing DigitalOcean resources via the `doctl` CLI, focused on App Platform.
+Patterns for managing DigitalOcean resources via the `doctl` CLI, centered on App Platform.
 
 ## When to Use This Skill
 
 Use this skill when:
 - Deploying or monitoring apps on DigitalOcean App Platform
-- Switching between DigitalOcean auth contexts
-- Checking deployment status or logs
-- Listing apps and their deployments
+- Checking deployment status, build failures, or runtime logs
+- Adding/changing env vars or secrets on a deployed app
+- Working with managed databases, Spaces, or droplets
+- Figuring out which DO account/app corresponds to the current repo
 
 ## Auth Contexts
 
 doctl supports named auth contexts for managing multiple accounts/teams.
 
 ```bash
-# Switch to a named context
-doctl auth switch --context <context-name>
+doctl auth list                          # list contexts; (current) marks the active one
+doctl account get --context <name>       # cheap probe: is this context valid, which account is it?
+```
+
+**Prefer the `--context` flag over switching.** Every doctl command accepts `--context <name>` (before or after the subcommand). This targets one account for one command without mutating global state — important when a session touches multiple accounts:
 
-# List available contexts
-doctl auth list
+```bash
+doctl apps list --context <ctx>
+for ctx in $(doctl auth list); do doctl apps list --context "$ctx"; done
 ```
 
-Always switch context before running commands against a specific account.
+Only use `doctl auth switch --context <name>` when the user explicitly wants the default changed.
+
+**`doctl auth init --context <name>` is interactive** (it prompts for a pasted token) — an agent cannot complete it. Ask the user to run it themselves.
 
-## App Platform
+## Resolving the Current Repo to a Context + App
 
-### Listing Apps
+App specs embed their source repo, so "check prod logs" is answerable from inside any repo:
 
 ```bash
-# List all apps (shows ID, name, ingress URL, deployment status)
-doctl apps list
+repo=$(git remote get-url origin | sed -E 's#.*github.com[:/]##; s#\.git$##')
+for ctx in $(doctl auth list); do
+  doctl apps list --context "$ctx" -o json 2>/dev/null | jq -r --arg ctx "$ctx" --arg repo "$repo" \
+    '.[] | select([.spec.services[]?, .spec.static_sites[]?, .spec.workers[]?, .spec.jobs[]?]
+      | any(.github.repo == $repo)) | "\($ctx)\t\(.spec.name)\t\(.id)"'
+done
 ```
 
-Key columns: `ID`, `Spec Name`, `Default Ingress`, `Active Deployment ID`, `In Progress Deployment ID`.
+This costs one API call per context — resolve once per session and reuse the `(context, app-id)` pair. If a repo backs multiple apps (e.g. staging + prod, or one repo deployed to several accounts), list the matches and ask the user which one they mean. Apps deployed without a git source won't be found this way.
 
-The app ID is a UUID — you'll need it for all subsequent commands.
-
-### Monitoring Deployments
+## App Platform Basics
 
 ```bash
-# List recent deployments for an app
-doctl apps list-deployments <app-id>
+doctl apps list --context <ctx>                    # ID, Spec.Name, DefaultIngress, deployment IDs
+doctl apps list-deployments <app-id>               # recent deployments: ID, Cause, Progress, Phase
+doctl apps get <app-id> --format DefaultIngress,ActiveDeployment.Phase,InProgressDeployment.ID
+doctl apps list-domains <app-id>                   # custom domains (there is no Domains column)
 ```
 
-Key columns: `ID`, `Cause`, `Progress` (e.g. `6/6`), `Phase`.
-
-Deployment phases:
-- `PENDING_BUILD` — queued
-- `BUILDING` — build in progress
-- `DEPLOYING` — deploying built artifacts
-- `ACTIVE` — successfully deployed and serving traffic
-- `SUPERSEDED` — replaced by a newer deployment
-- `ERROR` — deployment failed
+Most commands require the app UUID, not the name — get it from `doctl apps list`.
 
-The `Cause` column shows which commit triggered the deploy.
+The `Cause` column tells you *why* a deployment happened: `commit <sha> pushed to <repo>` for git pushes vs `app spec updated` for config changes.
 
-### Deployment Logs
+Deployment phases: `PENDING_BUILD` → `BUILDING` → `DEPLOYING` → `ACTIVE`. Terminal failure states: `ERROR`, `CANCELED`. `SUPERSEDED` means replaced by a newer deployment.
 
-```bash
-# Get build logs for a specific deployment
-doctl apps logs <app-id> --deployment <deployment-id> --type build
+### Deploying
 
-# Get runtime logs
-doctl apps logs <app-id> --type run
+Apps connected to GitHub auto-deploy on push to the configured branch. To redeploy without a code change (config refresh, transient build failure):
 
-# Follow logs in real-time
-doctl apps logs <app-id> --type run --follow
+```bash
+doctl apps create-deployment <app-id> --format ID,Phase
 ```
 
-Log types: `build`, `deploy`, `run`, `run_restarted`.
+### Waiting for a deployment
 
-### Getting App Details
+Poll bounded, with a fixed or escalating interval — never an unbounded `--follow`/watch in an agent context:
 
 ```bash
-# Get full app spec (useful for seeing components, env vars, routes)
-doctl apps get <app-id>
+for i in $(seq 1 90); do
+  PHASE=$(doctl apps get-deployment <app-id> <deployment-id> --format Phase --no-header | tr -d ' ')
+  case "$PHASE" in
+    ACTIVE) echo deployed; break;;
+    ERROR|CANCELED|SUPERSEDED) echo "failed: $PHASE"; exit 1;;
+  esac
+  sleep 20
+done
+```
 
-# Get app spec as yaml
-doctl apps spec get <app-id>
+## Logs
+
+```bash
+doctl apps logs <app-id> --type run --tail 500          # bounded runtime logs
+doctl apps logs <app-id> <component> --type build       # component is a POSITIONAL arg, not a flag
+doctl apps logs <app-id> --type run --follow            # live tail (interactive use only)
 ```
 
-## Common Gotchas
+- Log types: `build`, `deploy`, `run` (default). There is no `--component` flag — pass the component name as the second positional argument.
+- Always use `--tail N` and grep (`| grep -iE 'error|timeout|oom'`) rather than dumping everything — run logs can contain live secrets.
+- **Logs rotate on each deployment and retention is short.** Yesterday's crash logs are usually gone after today's deploy (unless log forwarding is configured). Capture logs immediately after triggering the thing you're observing.
+- Run logs are only retrievable from the **active** deployment — `--deployment <old-id> --type run` fails with a 400 (`phase final_cleanup`). Build logs of older deployments are fine.
+- A brand-new app has no logs until its first deployment starts (`no deployment found for app`).
+- To tell a crash-restart from a deploy-restart, compare timestamps against `list-deployments` Created times.
+
+## Output Formats: `--format`, `-o json`
+
+- **Column names differ per subcommand** and doctl version. `apps list --format ActiveDeployment.Phase` fails (`unknown column`) — but the same column works on `apps get`. Nested names use dots (`Spec.Name`, not `SpecName`). On `unknown column`, fall back to `-o json | jq` rather than guessing.
+- **`-o json` returns an array even for a single resource** — use `.[0].spec...`, not `.spec...`.
+- **`apps spec get` always emits YAML** — it silently ignores `-o json`. Don't pipe it to a JSON parser.
+- **A bad `--format` on a mutating command does NOT roll back the mutation.** `doctl apps update ... --format BadColumn` applies the update, then errors. Do not re-run the command — verify state instead.
+- Empty fields render as the literal string `<nil>`; `--no-header` keeps column padding — `tr -d ' '` before string-comparing.
+- `--http-retry-max` (global flag) auto-retries 429/5xx responses.
+
+## Further Reading
 
-- **Column names in `--format`**: doctl's `--format` flag is picky about column names. If you get `unknown column` errors, run the command without `--format` first to see available columns, then filter with standard tools like `head`.
-- **Deployment auto-trigger**: Apps connected to GitHub auto-deploy on push to the configured branch. No manual deploy needed unless auto-deploy is off.
-- **App ID vs Name**: Most commands require the app UUID, not the human-readable name. Get it from `doctl apps list`.
+- **App specs — env vars, secrets, creating apps**: see [spec-management.md](spec-management.md)
+- **Databases, Spaces, droplets, DNS**: see [other-services.md](other-services.md)

package/plugins/doctl/skills/doctl/other-services.md

@@ -0,0 +1,56 @@
+# Databases, Spaces, Droplets, DNS
+
+## Managed Databases
+
+```bash
+doctl databases list --format ID,Name,Engine,Version,NumNodes,Size
+doctl databases connection <db-id> --format URI --no-header   # full credentialed URI
+doctl databases ca <db-id>                                    # cluster CA certificate
+```
+
+- **The connection URI contains live credentials** — treat command output as a secret. Don't echo it into logs; pipe it directly to where it's needed.
+- **Check `Version`** and keep CI/local database versions in sync with production — a test suite running `postgres:15` against a pg-18 production cluster hides version-specific behavior.
+- Connections use port 25060 with `sslmode=require`. **TLS trap**: some clients (e.g. newer `pg-connection-string`) silently upgrade `require` to `verify-full`, which rejects DO's CA under the default trust store. Fix: supply the CA from `doctl databases ca <db-id>` explicitly, or configure ssl options in code rather than relying on the URI.
+
+## Spaces
+
+**`doctl spaces` manages access keys only — not buckets.** Create and manage buckets with the `aws` CLI (or s3cmd) against the Spaces endpoint:
+
+```bash
+aws s3 mb s3://<bucket> --endpoint-url https://<region>.digitaloceanspaces.com
+```
+
+Keys:
+
+```bash
+doctl spaces keys create <name> --grants 'bucket=<bucket>;permission=readwrite' -o json > /tmp/key.json
+doctl spaces keys list
+doctl spaces keys delete <ACCESS_KEY>      # no --force flag; prompts — use `yes |` when non-interactive
+```
+
+- Grant permissions: `read`, `readwrite`, `fullaccess`. An empty `bucket=` grants all buckets.
+- **The secret key is shown exactly once, at creation.** Capture it to a temp file with `-o json`, never print it, and delete the file after storing it where it belongs.
+- Unlike most doctl delete commands, `spaces keys delete` has no `--force` flag (it errors `unknown flag`).
+- Bootstrap pattern: create a temporary `fullaccess` key to create the bucket, mint a bucket-scoped `readwrite` key for the app, swap it in, then delete the full-access key.
+
+## Droplets
+
+```bash
+doctl compute ssh-key list                  # find key IDs (match yours via ssh-keygen -l -E md5)
+doctl compute droplet create <name> --region <region> --size s-1vcpu-1gb \
+  --image ubuntu-24-04-x64 --ssh-keys <key-id> --enable-monitoring --wait
+doctl compute droplet list --format Name,PublicIPv4,Status
+doctl compute ssh <droplet-name>            # ssh by name (interactive)
+doctl compute firewall list --format Name,InboundRules,DropletIDs
+```
+
+`--wait` blocks until the droplet is active, so the IP is immediately available from `droplet list`. For non-interactive remote commands prefer plain ssh: `ssh -o StrictHostKeyChecking=accept-new root@<ip> "<cmd>"`.
+
+## DNS
+
+Domain commands live under `compute` — `doctl domains ...` fails with `unknown command`:
+
+```bash
+doctl compute domain list
+doctl compute domain records list <domain>
+```

package/plugins/doctl/skills/doctl/spec-management.md

@@ -0,0 +1,74 @@
+# App Specs: Env Vars, Secrets, Creating Apps
+
+The app spec is the single source of truth for an App Platform app's configuration (components, env vars, routes, instance sizes). Most config changes are a GET → edit → PUT round-trip.
+
+## Changing Env Vars / Secrets (the standard workflow)
+
+```bash
+doctl apps spec get <app-id> > /tmp/spec.yaml
+# edit /tmp/spec.yaml — add under the relevant service's envs:
+#   - key: MY_SECRET
+#     scope: RUN_AND_BUILD_TIME
+#     type: SECRET
+#     value: <plaintext>
+doctl apps update <app-id> --spec /tmp/spec.yaml
+rm /tmp/spec.yaml        # the temp file held plaintext secrets
+```
+
+Facts that matter:
+
+- **`type: SECRET` values are submitted as plaintext and encrypted on ingest.** They read back as `EV[1:...]` blobs and can never be read back in plaintext via doctl.
+- **Existing `EV[...]` blobs survive the round-trip unchanged** — you do not need to re-supply secret values when editing other parts of the spec.
+- **DO encrypts whatever literal string you submit.** A placeholder like `VALUE_TO_SET` gets encrypted and deployed as the real value. Never put placeholder text in a SECRET value — keep the `EV[...]` blob or paste the real plaintext.
+- **`apps update --spec` triggers a new deployment** (Cause: `app spec updated`). The update command's own output may show a blank `In Progress Deployment ID` even though a deployment was created — confirm with `doctl apps list-deployments <app-id> | head -3`.
+- To verify a secret landed: `doctl apps spec get <app-id> | grep -A3 MY_SECRET` (expect an `EV[...]` value).
+- To inspect env config without the YAML: `doctl apps get <app-id> -o json | jq '.[0].spec.services[0].envs[] | {key, scope, type}'` (note the `.[0]` — json output is an array).
+- The only way to read a runtime env value is a console session into the running container — see "apps console" below.
+
+Env `scope` values: `RUN_TIME`, `BUILD_TIME`, `RUN_AND_BUILD_TIME`. Env vars can live at the app level (shared) or per-component.
+
+## Validating Specs: `--schema-only` for Update Specs
+
+`doctl apps spec validate spec.yaml` calls the propose endpoint, which simulates app **creation**. A spec pulled from a live app fails validation with:
+
+```
+secret env value must not be encrypted before app is created
+```
+
+This is a false alarm — `apps update` accepts `EV[...]` values fine. To pre-validate a spec destined for `apps update`, use:
+
+```bash
+doctl apps spec validate spec.yaml --schema-only
+```
+
+Full (non-schema-only) validation is still useful for specs that will be passed to `apps create`.
+
+## Creating an App
+
+```bash
+doctl apps create --spec .do/app.yaml --context <ctx> [--project-id <project-uuid>]
+doctl projects list --format ID,Name        # to find the project ID
+```
+
+- Convention: keep a sanitized spec in the repo (e.g. `.do/app.yaml`) with SECRET keys listed but values empty; inject real values into a temp copy at create time and delete it after.
+- Specs can also be piped inline: `doctl apps create --spec - <<'EOF' ... EOF` (same for `update`).
+- **GitHub-access 400**: `POST /v2/apps: 400 ... GitHub user does not have access to <org>/<repo>` means the DigitalOcean GitHub App isn't installed/authorized on that org. This is fixed in the browser (GitHub → Settings → Applications), not via doctl — hand it to the user, then retry the create.
+- `DefaultIngress` is empty (`<nil>`) until the first deployment goes ACTIVE. Fetch it afterward: `doctl apps get <app-id> --format DefaultIngress --no-header`.
+- No logs exist until the first deployment starts.
+
+## Instance Sizes / Pricing
+
+```bash
+doctl apps tier instance-size list
+doctl apps tier instance-size list -o json | jq '[.[] | {slug, monthly: .usd_per_month_cost}] | sort_by(.monthly)'
+```
+
+Use the slug in the spec's `instance_size_slug`.
+
+## apps console — Interactive Only
+
+`doctl apps console <app-id> <component>` opens an ephemeral shell in a running component — the only way to read live secret values or poke the runtime environment. But:
+
+- There is **no `--command` flag**, and piping stdin fails (`error setting terminal to raw mode: inappropriate ioctl for device`). It requires a real TTY.
+- An agent cannot drive it. Hand the user the exact command to run themselves, or reproduce the container environment locally with `docker run` instead.
+- Instances are ephemeral — nothing done in a console session persists.

package/plugins/git-github/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "git-github",
+  "description": "Git and GitHub (gh CLI) workflows for agents: the branch-to-PR loop, reading PR/CI state, debugging failed Actions runs, repair ladders for stuck git states, gh api recipes, and release flows.",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/git-github/skills/git-github/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: git-github
+description: Git and GitHub (gh CLI) workflows for agents - the branch-to-PR loop, reading PR and CI state, debugging failed GitHub Actions runs, getting unstuck from rejected pushes and rebase messes, gh api recipes, and release flows.
+---
+
+# Git + GitHub Workflows
+
+Battle-tested git and `gh` patterns for working in repos as an agent: the everyday branch→PR loop, interrogating PR/CI state, and recovering from the states git gets itself into.
+
+## Ground Rules
+
+- **Never push to the default branch unless the user explicitly says to.** "Commit and push" means the current branch. If on the default branch, branch first.
+- **Destructive operations require explicit user authorization**: `push --force` (even with lease, outside your own just-rebased branch), deleting remote branches, closing PRs you didn't open, `reset --hard`, `--no-verify`.
+- **Quote pathspecs containing brackets.** zsh globs `[id].get.ts` into `no matches found` — write `git add 'server/api/[id].get.ts'`. This bites on every bracketed-route codebase.
+- **Prefer `git -C <path>`** over `cd <path> && git ...` — compound cd commands trigger permission prompts and reset the shell cwd.
+- **Branch naming**: follow the repo's convention (`feat/`, `fix/`, `chore/`, `ci/`). If an issue tracker (e.g. Linear) suggests a branch name for the ticket, use it verbatim — it powers the tracker↔GitHub integration (auto-close on merge).
+- **Bounded polling, never unbounded watching.** `gh run watch` / `--watch` can die on network timeouts mid-wait; in agent contexts prefer a bounded loop with escalating sleeps (30/60/90s).
+
+## The Branch → PR Loop
+
+```bash
+# 1. Start from fresh main
+git checkout main && git pull --ff-only
+git checkout -b feat/<short-description>
+
+# 2. Commit with a heredoc (multi-line messages survive quoting)
+git commit -m "$(cat <<'EOF'
+feat(scope): one-line summary
+
+Why this change exists, not just what it does.
+EOF
+)"
+
+# 3. Push and open the PR with a structured body
+git push -u origin feat/<short-description>
+gh pr create --title "feat(scope): one-line summary" --body "$(cat <<'EOF'
+## What
+...
+
+## Why
+...
+
+## Notes for reviewers
+...
+EOF
+)"
+```
+
+- **Keep the PR description current.** After material scope changes, `gh pr edit <n> --body "$(cat <<'EOF' ... EOF)"`.
+- Merge style: `gh pr merge <n> --squash --delete-branch`; verify with `gh pr view <n> --json state,mergedAt`.
+- After merge: `git switch main && git pull --ff-only`, clean up `[gone]` branches, start the next branch from fresh main.
+- One concern per PR — hotfixes and review findings go in separate PRs unless told otherwise.
+- Stacked PRs: `gh pr create --base <parent-branch>`; after the parent merges, retarget with `gh pr edit <n> --base main` (and see [getting-unstuck.md](getting-unstuck.md) for rebasing onto main after the parent was squash-merged).
+
+## Reading PR and CI State
+
+```bash
+gh pr view <n> --json mergeable,mergeStateStatus,reviewDecision,state,mergedAt
+gh pr view <n> --json body -q .body          # read the current description
+gh pr diff <n>                                # the review workhorse; --name-only for the file list
+gh pr checks <n>                              # CI status table
+gh pr checks <n> --json name,bucket,link --jq '.[] | select(.bucket=="fail")'
+```
+
+- `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY` → branch conflicts with base; `BEHIND` → needs update.
+- Bounded CI wait: `until gh pr checks <n> 2>&1 | grep -qvE 'pending'; do sleep 30; done` — or check, sleep 30/60/90, re-check.
+
+## Pre-push Hook Noise
+
+When a push fails inside a compound command (or behind lefthook/husky pre-push hooks), the hook's lint/test output drowns the real git error. Isolate it:
+
+```bash
+git push -u origin <branch> > /tmp/push.log 2>&1; echo "exit=$?"
+grep -E '! \[reject|error:|fatal:' /tmp/push.log
+```
+
+Do not bypass failing hooks with `--no-verify` unless the user says to.
+
+## Further Reading
+
+- **Debugging failed Actions runs** (the full playbook): [actions-debugging.md](actions-debugging.md)
+- **Repair ladders** — rejected pushes, blocked checkouts, rebase/conflict recovery, shallow clones, worktrees: [getting-unstuck.md](getting-unstuck.md)
+- **gh api recipes** — PR comments, reading files without checkout, repo settings, PAT gotchas: [gh-api-recipes.md](gh-api-recipes.md)
+- **Releases & publishing** — tags, gh release, npm Trusted Publishing, release-please: [releases.md](releases.md)
+- **External review loop** — using the codex CLI as an adversarial pre-merge reviewer: [external-review.md](external-review.md)

package/plugins/git-github/skills/git-github/actions-debugging.md

@@ -0,0 +1,102 @@
+# Debugging Failed GitHub Actions Runs
+
+The playbook, in the order that actually works.
+
+## 1. Start from the PR, not the run
+
+```bash
+gh pr checks <n> --watch --interval 20 --fail-fast=false   # interactive sessions
+gh pr checks <n>                                            # one-shot snapshot for poll loops
+```
+
+The output includes run/job links with the IDs you need. `--required` limits to required checks.
+
+For branch pushes without a PR, find the run:
+
+```bash
+rid=$(gh run list --branch <branch> --limit 1 --json databaseId,status,conclusion --jq '.[0].databaseId')
+```
+
+## 2. Get the failing-step logs
+
+```bash
+gh run view <run-id> --log-failed 2>&1 | tail -50
+```
+
+This is the first command of every failure investigation. When noisy, narrow it:
+
+```bash
+gh run view <run-id> --log-failed | grep -E 'FAIL|error|✗'
+# aggregate TypeScript errors by code:
+gh run view <run-id> --log-failed | grep -oE 'error TS[0-9]+' | sort | uniq -c | sort -rn
+```
+
+Runner log lines are prefixed with `job\tstep\ttimestamp` — strip before aggregating:
+
+```bash
+sed -E 's/^[^\t]*\t[^\t]*\t[0-9T:.Z-]* //'
+```
+
+and file paths are absolute on the runner — strip `s#^/home/runner/work/<repo>/<repo>/##` to get repo-relative paths.
+
+## 3. Need context before the failure?
+
+`--log-failed` shows only the failing step. For surrounding context:
+
+```bash
+gh run view <run-id> --json status,conclusion,jobs --jq '{status, conclusion, jobs: [.jobs[] | {name, status, conclusion}]}'
+gh run view <run-id> --job <job-id> --log | grep -E '<pipeline markers>'
+gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs | tail -60    # raw dump, last resort
+```
+
+## 4. Flaky or real? Check main
+
+```bash
+gh run list --branch main --limit 3 --json databaseId,status,conclusion
+```
+
+If main is red with the same failure, the problem isn't your branch. If it looks like a flake:
+
+```bash
+gh run rerun <run-id> --failed     # reruns only the failed jobs
+```
+
+Note: `gh run rerun --job <id>` only works on failed jobs within the retention window ("job cannot be rerun" otherwise).
+
+## 5. Reproduce locally before fixing
+
+Run the exact failing command from the workflow (`yarn test:run -- <file>`, `yarn fmt:check`, etc.). For environment-dependent failures (Linux vs macOS differences, missing gitignored fixtures, float-precision diffs in generated output), reproduce inside the CI image:
+
+```bash
+docker run --rm -v "$PWD":/work -w /work node:22 bash -c \
+  'yarn install --immutable && <failing command>'
+```
+
+## 6. Fix → push → re-watch → merge
+
+```bash
+git push
+sleep 30 && gh pr checks <n>          # then 60s, 90s — escalating, bounded
+gh pr merge <n> --squash --delete-branch
+gh pr view <n> --json state,mergedAt
+git switch main && git pull --ff-only
+```
+
+## Watching: bounded polls beat unbounded watches
+
+`gh run watch <id> --exit-status` is convenient but long watches can die with a GraphQL network timeout, losing the wait entirely. In agent contexts prefer:
+
+```bash
+for s in 30 60 90 90 90; do
+  sleep $s
+  state=$(gh run view <run-id> --json status,conclusion --jq '"\(.status)/\(.conclusion)"')
+  echo "$state"; [[ "$state" == completed/* ]] && break
+done
+```
+
+## Common root causes (in observed frequency order)
+
+1. **Formatter/lint check failures** — fix is `yarn fmt` (or the repo's equivalent), commit, push.
+2. **Test-only bugs** — assumptions that break under the CI harness (e.g. transaction-rollback test isolation).
+3. **Environment differences** — CI Linux vs local macOS: gitignored fixture files missing in CI, locale/precision output diffs.
+4. **Genuine flakes** — rerun `--failed`; if it recurs, it's not a flake.

package/plugins/git-github/skills/git-github/external-review.md

@@ -0,0 +1,39 @@
+# External Review Loop (codex as adversarial reviewer)
+
+Use OpenAI's `codex` CLI as an independent reviewer of your own work before a human sees it. The loop: review → triage → fix fair findings → commit → re-review, until clean.
+
+## Invocation
+
+```bash
+codex review --base main 2>&1 | tail -120     # review branch vs base (the default move)
+codex review --base origin/main ...           # when local main may be stale
+codex review --uncommitted ...                # working-tree changes, pre-commit
+codex review --commit <sha> ...               # single commit
+codex review <PR-number>                      # codex reads the PR description for intent
+```
+
+- Steer with a positional prompt: `codex review --base main "Focus on X, Y. Report only issues genuinely worth fixing."` For long briefs use `"$(cat /tmp/review-prompt.md)"` or stdin via `-` (with `--title` for display context). A good brief states the feature context, prioritized focus areas (security first), what to skip (style/lint), and a mandated output format ("P0/P1/P2 punch list, file:line per finding").
+- Reviews take minutes. Run in the background redirecting to a file (`codex review --base main > /tmp/review-r1.txt 2>&1`), then read the file when the process exits.
+- **Exit code is 0 even with findings** — judge clean/dirty from the text, not `$?`.
+- Print `git branch --show-current` and `git rev-parse --short HEAD` around the review so it's unambiguous which state was reviewed — stale-state false positives (reviewing before a push/amend landed) are the most common confusion.
+- Older CLI versions reject `--base` combined with a prompt (`cannot be used with '[PROMPT]'`); pass the prompt alone, use stdin `-`, or upgrade.
+
+## The loop
+
+1. Commit and push the work, then run the review.
+2. **Triage every finding before touching code.** Codex emits `[P1]/[P2]/[P3] — file:line` with rationale. Verify each at the cited location, then classify: fair (fix it), stale (already fixed, or presupposes old state — say so), or judgment call (present to the user with a recommendation). Never silently drop a finding — rebut it explicitly.
+3. Fix the fair ones; keep provenance in the commit message: `(codex review, P2)` or `fix: address codex review round 3`.
+4. Push and re-review. Small PRs converge in 1–3 rounds; large or security-sensitive features can take 6+.
+5. **Brief later rounds.** List prior findings and their fixes ("don't re-flag these"), point fresh eyes at not-yet-audited surfaces, and demand a verdict: "P0/P1 only, skip nitpicks — or say plainly: no issues, ship it."
+6. Once correctness is clean, optionally flip the lens for one final pass: "Do NOT look for bugs — those have been reviewed exhaustively. Review ONLY for over-engineering and simplification opportunities." Present those findings; don't auto-implement them.
+
+## Conventions
+
+- Record the outcome in the PR body's verification section: `codex review --base main: clean (after iterating on N findings — ...)`.
+- Findings that arrive after the PR merged go in a **follow-up PR** referencing the original — never amend a merged branch.
+- The user arbitrates dismissals of borderline findings.
+- To run the loop unattended, set a session goal (Stop hook), e.g.: "run `codex review` on this PR and fix any finding you judge important. Repeat until there are no findings that need to be addressed." **Phrase the escape clause carefully** — state explicitly whose judgment ends the loop ("findings *the assistant* deems dismissible"). An ambiguous "or you think they don't need addressing" can wedge the hook: the checker may read "you" as the user, so the agent's own dismissal never satisfies the goal.
+
+## Sibling pattern: plan review
+
+The same adversarial-reviewer move works pre-code: pipe a written plan to `codex exec -` with a critique prompt ("review this plan — focus on bloat and YAGNI"). Useful before large implementations; findings adjust the plan, not the code.

package/plugins/git-github/skills/git-github/getting-unstuck.md

@@ -0,0 +1,106 @@
+# Getting Unstuck: Repair Ladders for Common Git Failures
+
+Each section is a failure you'll actually hit, with the sequence that resolves it.
+
+## Rejected push (remote has new commits)
+
+```
+! [rejected]  <branch> -> <branch> (fetch first)
+```
+
+The ladder — each step unblocks the next:
+
+```bash
+git stash push -u -m "wip before rebase"     # only if the tree is dirty
+git pull --rebase origin <branch>
+git push
+git stash pop
+```
+
+- `git pull --rebase` refuses to run with unstaged changes (`cannot pull with rebase: You have unstaged changes`) — hence stash first, always with `-u` (untracked files) and a descriptive `-m`.
+- If the dirty files are unrelated WIP, scope the stash: `git stash push -u -m "wip" -- <paths>` so the rest of the tree stays put.
+- `fatal: Need to specify how to reconcile divergent branches` → same fix: `git pull --rebase origin <branch>`.
+
+## Checkout/merge blocked by local changes
+
+`error: Your local changes to the following files would be overwritten by checkout` — same stash-first pattern: stash, switch/merge, pop.
+
+## Rebasing a stacked branch after its base was squash-merged
+
+After the parent PR squash-merges, your stacked branch "contains" commits main already has in squashed form. A plain rebase replays them all and conflicts everywhere. Instead, replay only your own commits:
+
+```bash
+git log --oneline main..HEAD                  # identify your commits
+git merge-base HEAD origin/main               # sanity-check the old fork point
+git rebase --onto origin/main <old-base-sha>  # replay only commits after <old-base-sha>
+```
+
+During the rebase:
+- **`--ours`/`--theirs` are inverted during rebase**: `--ours` is the *new base* (main), `--theirs` is *your branch's* change. `git checkout --ours <file> && git add <file>` keeps main's version.
+- Commits that were already squash-merged become empty → `git rebase --skip` (or `git cherry-pick --skip` in cherry-pick flows; `--allow-empty` if you want the empty commit).
+- "dropping <sha> ... patch contents already upstream" is rebase doing its job — verify afterward with `git log origin/main..HEAD` rather than assuming commits vanished.
+- If you rebased a detached `HEAD`, reattach the branch: `git checkout -B <branch>`.
+
+Then force-push: `git push --force-with-lease origin <branch>`, and confirm the PR recovered with `gh pr view <n> --json mergeable,mergeStateStatus`.
+
+If a rebase goes sideways: `git rebase --abort`, re-inspect with `git log --oneline origin/main..HEAD`, try again with a better plan.
+
+## Lockfile / generated-file conflicts during rebase
+
+Don't hand-merge lockfiles. Take one side wholesale and regenerate:
+
+```bash
+git checkout --ours yarn.lock && git add yarn.lock
+git rebase --continue
+yarn install        # regenerate to match the merged manifest; commit if it changed
+```
+
+## `--force-with-lease` rejected as stale
+
+A bare `--force-with-lease` compares against your remote-tracking ref. If the branch was fetched into a local ref or `FETCH_HEAD` only (common in CI/sandbox checkouts), every lease push fails. Fix: make sure `refs/remotes/origin/<branch>` exists —
+
+```bash
+git fetch origin '+refs/heads/<branch>:refs/remotes/origin/<branch>'
+```
+
+— or pass an explicit lease: `--force-with-lease=<branch>:<expected-sha>`.
+
+## Shallow clones silently imply single-branch
+
+`git clone --depth=N` narrows the fetch refspec to the default branch, so `git fetch origin <other-branch> && git checkout <other-branch>` fails even though the branch exists. Fix with an explicit refspec:
+
+```bash
+git fetch origin '+refs/heads/<branch>:refs/remotes/origin/<branch>'
+git checkout -B <branch> origin/<branch>
+```
+
+## `fatal: couldn't find remote ref <branch>`
+
+You guessed the branch name. `git branch -a` / `git fetch origin` first — or skip the guessing entirely with `gh pr checkout <n>`, which fetches the PR head regardless of branch naming.
+
+## `gh pr create` → "Head sha can't be blank / No commits between X and Y"
+
+The branch has no commits ahead of its base (or wasn't pushed). Commit and/or `git push -u` first.
+
+## Migrations vs a moving main
+
+When main gained DB migrations while your PR was open: migrate down locally, rebase onto main, **rename your migration files so their timestamps sort after main's**, re-run migrations. Migration order is part of the merge.
+
+## Worktrees: fix CI without disturbing WIP
+
+```bash
+git worktree add ../<repo>-hotfix <branch>                 # existing branch
+git worktree add -b <new-branch> ../<repo>-hotfix origin/main
+# ... fix, commit, push from the worktree ...
+git worktree remove --force ../<repo>-hotfix && git worktree prune
+```
+
+Caveat: hooks that run package scripts may fail inside a worktree if they resolve modules from the main checkout — run installs in the worktree first.
+
+## `git diff --cached` can't take a range
+
+`git diff --stat --cached main..` → usage error (exit 129). The cached diff is against a single commit: `git diff --stat --cached main`.
+
+## Long-diverged automation branches
+
+A bot-maintained branch diverged 3-vs-105 commits is not worth merging — `git reset --hard origin/<branch>` (destructive: requires explicit user authorization) and re-apply the local delta on top.

package/plugins/git-github/skills/git-github/gh-api-recipes.md

@@ -0,0 +1,73 @@
+# gh api Recipes
+
+Read-only `gh api` patterns for inspecting repos and PRs without checking anything out.
+
+## PR feedback lives in TWO places — fetch both
+
+Inline review comments and conversation-tab comments are different endpoints. When addressing PR feedback, always check both:
+
+```bash
+# Inline review comments (attached to lines of the diff)
+gh api repos/<owner>/<repo>/pulls/<n>/comments \
+  --jq '[.[] | {id, path, line, body, user: .user.login}]'
+
+# Conversation-tab comments
+gh api repos/<owner>/<repo>/issues/<n>/comments \
+  --jq '[.[] | {id, body, user: .user.login, created_at}]'
+
+# Review states/bodies (approve / request-changes verdicts)
+gh api repos/<owner>/<repo>/pulls/<n>/reviews --jq '[.[] | {state, body, user: .user.login}]'
+```
+
+Reply at the conversation level with `gh pr comment <n> --body "..."` (there's no clean CLI path for threaded inline replies).
+
+Repo-wide recent PR comments, newest first:
+
+```bash
+gh api 'repos/<owner>/<repo>/issues/comments?sort=created&direction=desc&per_page=30' --paginate \
+  --jq '.[] | select(.pull_request_url != null) | {pr: .pull_request_url, body, created_at}'
+```
+
+## Reading files and history without a checkout
+
+```bash
+# Read one file off any branch (URL-encode brackets in paths: %5Bid%5D)
+gh api 'repos/<owner>/<repo>/contents/<path>?ref=<branch>' --jq '.content' | base64 -d
+
+# Full file tree
+gh api 'repos/<owner>/<repo>/git/trees/<branch>?recursive=1' --jq '.tree[].path'
+
+# Per-file commit history
+gh api 'repos/<owner>/<repo>/commits?path=<file>&per_page=5' \
+  --jq '.[] | {sha: .sha[0:7], msg: .commit.message, date: .commit.author.date}'
+
+# Which files a PR touches (with per-file status)
+gh api repos/<owner>/<repo>/pulls/<n>/files --jq '.[] | {filename, status, additions, deletions}'
+```
+
+(`gh pr diff <n>` and `gh pr diff <n> --name-only` cover the common cases without the api call.)
+
+## Repo settings audit
+
+```bash
+# Merge policy
+gh api repos/<owner>/<repo> --jq '{allow_merge_commit, allow_squash_merge, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message}'
+
+# Branch protection
+gh api repos/<owner>/<repo>/branches/<branch>/protection
+```
+
+## Deploy keys (server pulls a private repo)
+
+```bash
+# generate the key on the server, then:
+gh repo deploy-key add - --repo <owner>/<repo> --title "<host>" <<< "$PUBKEY"
+gh repo deploy-key list --repo <owner>/<repo>
+```
+
+## Token and version gotchas
+
+- **Fine-grained PATs can't access some endpoints at all** (e.g. `/notifications`): 403 "Resource not accessible by personal access token". The tell: the response **lacks the `x-accepted-github-permissions` header**, meaning no grantable permission fixes it — you need a classic PAT with the right scope for that one call.
+- For scripted clones with a token, the remote form is `https://x-access-token:<TOKEN>@github.com/<owner>/<repo>.git`.
+- **Pushing workflow files** with an OAuth-scoped token fails with "refusing to allow an OAuth App to update workflow". Fix: `gh auth refresh -h github.com -s repo,workflow`.
+- **`--json` field sets vary by gh version** (`Unknown JSON field: "isLatest"`). The error prints the supported field list — re-run with fields from that list rather than guessing.

package/plugins/git-github/skills/git-github/releases.md

@@ -0,0 +1,53 @@
+# Releases & Publishing
+
+## Tags and GitHub releases
+
+```bash
+# Latest existing version tag, without a local checkout of all tags
+git ls-remote --tags --refs --sort=-v:refname origin 'v*' | head -1
+
+gh release create v<X.Y.Z> --target main --title "v<X.Y.Z>" --notes "$(cat <<'EOF'
+## Changes
+- ...
+EOF
+)"
+```
+
+## npm Trusted Publishing (OIDC, no NPM_TOKEN)
+
+Publish from GitHub Actions with provenance and zero long-lived secrets:
+
+1. On npmjs.com, configure the package's **Trusted Publisher**: the repo and the **exact workflow filename** (e.g. `release.yml`). The match is on the workflow file path — renaming the workflow breaks publishing.
+2. The workflow job needs `permissions: id-token: write` and a registry-aware setup:
+
+```yaml
+permissions:
+  contents: write
+  id-token: write
+steps:
+  - uses: actions/checkout@v5
+  - uses: actions/setup-node@v5
+    with:
+      node-version: 24
+      registry-url: https://registry.npmjs.org
+  - run: npm publish        # no NODE_AUTH_TOKEN needed
+```
+
+3. The published version must be new — Trusted Publishing doesn't bypass the "version already exists" check.
+4. Verify provenance landed:
+
+```bash
+npm view <pkg> dist.attestations.provenance.predicateType
+```
+
+## release-please (tag/changelog automation)
+
+Conventional commits (`feat:`, `fix:`, `chore(release):` etc.) drive everything: release-please opens/updates a release PR collecting changes; merging that PR creates the tag + GitHub release, which triggers the publish workflow. With this in place, never hand-create tags — just merge the release PR.
+
+## Bootstrapping a repo
+
+```bash
+gh repo create <owner>/<name> --private --source=. --remote=origin --push [--description "..."]
+```
+
+If the push step fails inside this compound command (often a pre-push hook), the repo was still created — push separately and read the real error (see SKILL.md on hook noise).