workstation

Use on any NixOS host (devbox on Hetzner, cloudbox on GCP) when SSH connection fails, host key mismatch, NixOS issues, CPU/IO contention (high load), or verifying the host is properly configured

Launch headless opencode sessions from CLI. Use when you need to start a new opencode session in the background to work on a task in parallel, or when spawning work on a specific directory.

How to apply configuration changes to NixOS hosts (devbox, cloudbox). Use when you need to rebuild the system, apply home-manager changes, or recover from issues.

Use when setting up or rotating PagerDuty MCP auth for OpenCode on macOS Keychain or cloudbox sops, or when debugging missing PagerDuty tools.

Use when setting up or rotating Rollbar MCP auth for OpenCode on macOS Keychain or cloudbox sops, when triaging a Rollbar error paged via PagerDuty, or when debugging missing Rollbar tools.

Documents the OpenCode agent set — what each does, when to use it, and why the others were cut. Use when questioning agent choices or considering adding/removing agents.

Use when operating, deploying, debugging, or extending the aigateway LLM cost-capture proxy on cloudbox — routing opencode's Vertex providers through it, querying the per-request cost ledger (gateway_request_log), adding model prices, or rolling routing back.

Use when an opencode-serve pool member is unresponsive/wedged, when the serve-canary restarted a serve overnight, or when tuning the serve units' memory limits. Covers the "alive but frozen" failure mode, the canary timer, and where its forensics dumps land.

Use when adding, editing, or moving an OpenCode skill, or debugging why a newly-added skill is not picked up.

Activate beads (bd) issue tracking for persistent task memory across sessions. Use when work spans multiple sessions, has complex dependencies, or needs to survive compaction. For simple single-session linear tasks, use TodoWrite instead.

Resolves a beads (bd) schema-migration block across clones — bd "refusing to auto-apply N pending schema migrations (vNN->vMM)" on a remote-backed database (#4259), or writes blocked after a bd version bump, or post-migration write failures like "Field 'id' doesn't have a default value" (Error 1105). Use when any repo's bd shows that guard, or to migrate all beads DBs on a machine after upgrading bd. Covers single-migrator discipline, the DoltHub-vs-git split-remote trap, adopt-vs-migrate, flaky embedded-clone recovery (standalone-dolt graft), stopping a stale bd daemon, the 0037 stripped-UUID-default repair, and fresh-clone verification.

Use when setting up, rotating, or debugging the DevCycle feature-flag MCP for OpenCode on macOS Keychain or cloudbox sops. Covers why the hosted remote endpoint is unusable (no dynamic client registration) and the local dvc-mcp + client-credentials setup.

Use when authenticating OpenCode to Notion's hosted MCP server for the first time on a host, re-authenticating after token revocation, or debugging a stuck OAuth callback during `opencode mcp auth notion`.

Use when opencode on any host (devbox, cloudbox, macOS) feels sluggish, slow, or frozen; when attach TUIs burn CPU or a session shows the busy/working shimmer forever; when opencode.db has grown to gigabytes; after canary serve restarts leave sessions stuck mid-turn; or when porting the sweeper/canary/DB-maintenance tooling to another host.

This skill explains the workstation monorepo structure, how NixOS (devbox) and nix-darwin (macOS) are organized with standalone home-manager, and how to navigate the configuration. Use this when onboarding or trying to understand how either platform is configured.

Use when acting as the morning workspace agent after a nightly reset (recommend/reopen sessions, then coordinate them as a swarm; it runs in a dedicated ~/morning dir (outside the workstation repo) and lands as a `morning` window in `main`, still reachable over Telegram), or when debugging from any project why an opencode session did or didn't land in /tmp/reset-workspace-last-manifest.txt. For the full mechanism and operations, defer to the workstation repo-local `resetting-workspace` skill.

Use when the user wants a fresh start on cloudbox — to kill all nvims, clear stale sessions, restart opencode-serve, or understand the nightly reset.

Use when searching OpenCode session history for PRs, Jira tickets, commands, or any text across past sessions.

Use when reading or writing Jira tickets, fetching Confluence pages, searching with JQL, adding comments, or downloading Atlassian attachments from this devbox.

How the Atlassian instance is configured across macOS and cloudbox. Use when adding, removing, or debugging Atlassian instance profiles.

How secrets are stored, decrypted, and used on the devbox. Use when adding, removing, or debugging secrets.

Use when planning a multi-piece task to decide whether to swarm (spawn parallel coordinator + worker sessions) or do the work serially in one session. Covers the heuristic, the topology, and the spin-up sequence.

Use when you need to drive this Mac remotely from cloudbox (hands-off darwin-rebuild / opencode cutover), or to understand/operate the security posture that keeps the public-IP cloudbox from reaching the Mac unattended. Covers opening the on-demand reverse-SSH window, the passwordless-root toggle, teardown, and revoking the cloudbox SSH key in JumpCloud.

Use when sending messages to other opencode sessions on the same machine (swarm coordination), or when you receive a <swarm_message> envelope as the text of a user-message turn.

Use when a merged PR's change still needs to reach its Kubernetes environments -- watching a merged commit roll out to UAT/PROD until the new image is live and pods are healthy, or diagnosing a stuck rollout (deploy not bumped, CrashLoopBackOff, ImagePullBackOff, restart spike). Work-only; kubectl/AKS-based.

Use when opening a pull request OR when an open PR you authored needs attention -- waiting on CI, reviewer comments, or anything between "PR created" and "PR landed". The PR is your responsibility until it lands; this skill covers the whole arc, not just the create step.

Policy for keeping org-identifying metadata out of public source. Use when adding new config, writing skill docs, or reviewing for company references before committing.

Use when a kubectl write operation (patch, scale, set env, exec, delete, rollout restart) against a Wonder production AKS cluster fails with a Forbidden / RBAC error, or when you need to self-activate the time-boxed Azure "Kubernetes Service RBAC Writer" role via PIM. Explains the read-vs-write Azure RBAC model and points to the Confluence runbook that holds the exact subscription, cluster, role-definition, and scope IDs (kept out of source control).

Send ChatGPT queries from any remote NixOS host (devbox or cloudbox) via the ask-question CLI. Use when /ask-question fails with "Server not running" or when setting up chatgpt-relay for the first time on a new host.

Use when investigating an opencode or Vertex/gemini LLM call surge on cloudbox, attributing LLM traffic by agent/model/session, or querying/debugging the durable LLM audit log.

Measures OpenCode prompt caching efficiency and API costs via SQLite analysis. Use when investigating API costs, evaluating cache hit rates, or checking if upstream caching fixes have landed.

Set up Slack MCP server with xoxp User OAuth token. Use for initial setup or token rotation. Covers macOS (Keychain) and cloudbox (sops).

Guide for provisioning the cloudbox GCP VM from scratch with nixos-anywhere. Use when rebuilding the cloudbox or setting up a new GCP ARM instance.

How NixOS hosts (devbox, cloudbox) automatically update self-packaged dependencies (currently just `beads`) via GitHub Actions and apply the resulting flake-locked changes via a systemd timer. Use when debugging update failures or understanding the update flow.

Use when copy/paste doesn't work over mosh/SSH, or clipboard not syncing between local and remote, or setting up terminal remoting with gclpr or OSC 52

Use when you need to share a screenshot with OpenCode running on a remote NixOS host (devbox or cloudbox) over SSH, since Ctrl+V image paste doesn't work remotely

Use when posting any reply to a GitHub PR — whether reviewing fresh, replying to a Gemini/human inline comment, or summarizing a session's work. Covers the response-shape decision (threaded vs top-level), inline comment posting via gh CLI, and the gh API gotchas.

Reclaim disk space on any NixOS host (devbox, cloudbox) or macOS. Covers Nix store/generations, Python caches (uv/pip), application caches (Playwright, datalab), and project-specific bloat. Use when disk space is low or for regular maintenance.

Draft a technical research question and send to ChatGPT for investigation

Use when fetching raw test logs or build logs from a BuildBuddy invocation by URL/invocation ID — bypasses the bazel/UI truncation that hides large test stdout (multi-MB JUnit logs, dependency dumps, etc.). Provides the bb-test-log helper and the underlying enterprise API flow.