switchroom 0.13.2 → 0.13.4

package/skills/buildkite-agent-runtime/SKILL.md

@@ -1,509 +0,0 @@
----
-name: buildkite-agent-runtime
-description: >
-  ALWAYS use this skill when the user's message begins with "Inside a
-  Buildkite step," — that prefix is a hard trigger regardless of what
-  follows. Specifically fires on the exact phrasings: "Inside a Buildkite
-  step, Get or update a step attribute, please.", "Inside a Buildkite
-  step, Please upload artifacts from a step.", "Inside a Buildkite step,
-  Help me add an annotation.", "Inside a Buildkite step, Please add an
-  annotation.", "Inside a Buildkite step, Could you upload pipeline
-  dynamically for me?", "Inside a Buildkite step, Help me request an OIDC
-  token inside a step.", "Inside a Buildkite step, acquire a distributed
-  lock", "Inside a Buildkite step, retrieve a cluster secret at runtime",
-  "Inside a Buildkite step, redact secrets from logs", "Inside a
-  Buildkite step, set or get meta-data between steps".
-  Use when the user wants to call the `buildkite-agent` binary from inside
-  a running job step — annotating builds, uploading or downloading artifacts,
-  setting or getting meta-data between steps, uploading dynamic pipeline YAML,
-  requesting an OIDC token, acquiring distributed locks, getting or updating
-  a step attribute, redacting secrets from logs, or fetching cluster secrets
-  at runtime.
-  Also triggers on natural phrasings including: "Help me add an annotation.",
-  "Please add an annotation.", "Please upload artifacts from a step.",
-  "Could you upload pipeline dynamically for me?",
-  "Help me request an OIDC token inside a step.",
-  "Get or update a step attribute, please.",
-  "pls acquire a distributed lock", "gonna need to add an annotation",
-  "quick q — can i get or update a step attribute", and typo'd variants
-  like "request an IDC token inside a step", "retrieve a custer secret at runtime".
-  Also fires on `buildkite-agent annotate`, `buildkite-agent artifact upload/download`,
-  `buildkite-agent meta-data set/get`, `buildkite-agent pipeline upload`,
-  `buildkite-agent oidc request-token`, `buildkite-agent step`,
-  `buildkite-agent lock`, `buildkite-agent env`, `buildkite-agent secret get`,
-  `buildkite-agent redactor add`, `buildkite-agent tool sign/verify`, or any
-  `buildkite-agent` subcommand invoked inside a running job step.
-  Do NOT use when the user is provisioning or configuring rather than calling
-  from inside a step — cluster/queue/token provisioning is
-  `buildkite-agent-infrastructure`, and OIDC trust setup (the IdP side, vs
-  in-step `oidc request-token`) is `buildkite-secure-delivery`. Do NOT use
-  for authoring `.buildkite/pipeline.yml` step definitions — that's
-  `buildkite-pipelines`. Do NOT use when the user's message starts with
-  "Using the Buildkite CLI," — that prefix routes to `buildkite-cli`
-  even when the action is "upload artifacts", "list builds", or any
-  other phrasing that also names a `buildkite-agent` capability; the
-  `bk` CLI and the in-step `buildkite-agent` binary are distinct
-  surfaces, and the "Using the Buildkite CLI," prefix is load-bearing
-  for `buildkite-cli`.
----
-
-# Buildkite Agent Runtime
-
-The `buildkite-agent` binary provides subcommands for interacting with Buildkite from within running job steps — creating annotations, uploading artifacts, sharing state between jobs, generating dynamic pipelines, requesting OIDC tokens, and more. This skill covers the command syntax, flags, and patterns for every in-job subcommand.
-
-## Quick Start
-
-A step that runs tests, annotates failures, uploads coverage, and stores a result flag for downstream jobs:
-
-```yaml
-steps:
-  - label: ":test_tube: Tests"
-    command: |
-      if ! make test 2>&1 | tee test-output.txt; then
-        buildkite-agent annotate --style "error" --context "test-failures" < test-output.txt
-        buildkite-agent meta-data set "tests-passed" "false"
-        exit 1
-      fi
-      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"
-      buildkite-agent artifact upload "coverage/**/*"
-      buildkite-agent meta-data set "tests-passed" "true"
-```
-
-A downstream step reading that state:
-
-```yaml
-  - label: ":rocket: Deploy"
-    command: |
-      PASSED=$(buildkite-agent meta-data get "tests-passed")
-      if [[ "$PASSED" != "true" ]]; then
-        echo "Tests did not pass, skipping deploy"
-        exit 0
-      fi
-      scripts/deploy.sh
-    depends_on: "test-step"
-```
-
-## Annotations
-
-Surface build results directly on the build page. Annotations support Markdown and HTML.
-
-### Creating annotations
-
-```bash
-# Simple text annotation
-buildkite-agent annotate "Deploy completed successfully" --style "success" --context "deploy"
-
-# Pipe from a file
-buildkite-agent annotate --style "error" --context "test-failures" < test-output.md
-```
-
-### Key flags
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--style` | `-s` | `default` | Visual style: `default`, `info`, `warning`, `error`, `success` |
-| `--context` | `-c` | random UUID | Unique ID — reusing a context replaces the annotation |
-| `--append` | — | `false` | Append to existing annotation with same context instead of replacing |
-| `--priority` | — | `3` | Display priority (1-10). Higher numbers appear first |
-| `--job` | — | current job | Job ID to annotate (rarely needed) |
-
-### Replacing vs appending
-
-- **Same `--context` without `--append`** replaces the annotation; **with `--append`** appends below existing content.
-- Always use a stable `--context` value so reruns update the same annotation instead of creating duplicates.
-
-> For pipeline-level `notify:` configuration, see the **buildkite-pipelines** skill.
-
-## Artifacts
-
-Upload files as build artifacts, download them in later steps or other builds, and search by glob.
-
-### Upload
-
-```bash
-# Upload a single file
-buildkite-agent artifact upload "pkg/release.tar.gz"
-
-# Upload with glob pattern
-buildkite-agent artifact upload "dist/**/*"
-```
-
-### Download
-
-```bash
-# Download to current directory
-buildkite-agent artifact download "pkg/release.tar.gz" .
-
-# Download from a specific step
-buildkite-agent artifact download "dist/*" . --step "build-step"
-```
-
-### Search
-
-```bash
-# List matching artifacts
-buildkite-agent artifact search "pkg/*.tar.gz" --build "$BUILDKITE_BUILD_ID"
-```
-
-For complete flag tables, see `references/flag-reference.md`.
-
-> For the declarative `artifact_paths:` YAML key, see the **buildkite-pipelines** skill. For `bk artifact` CLI commands, see the **buildkite-cli** skill.
-
-## Meta-data
-
-A build-wide key-value store for sharing state between jobs. Set a value in one job, read it in any other job in the same build.
-
-### Set
-
-```bash
-buildkite-agent meta-data set "release-version" "1.4.2"
-```
-
-### Get
-
-```bash
-VERSION=$(buildkite-agent meta-data get "release-version")
-```
-
-Use `--default` to return a fallback value instead of a non-zero exit when the key is missing: `buildkite-agent meta-data get "deploy-env" --default "staging"`.
-
-### Check existence
-
-```bash
-# Returns exit code 0 if exists, 100 if not
-if buildkite-agent meta-data exists "release-version"; then
-  echo "Version already set"
-fi
-```
-
-### Common patterns
-
-**Block step field values** are stored automatically as meta-data. Retrieve them by field key:
-
-```bash
-# After a block step with fields: [{key: "release-name", text: "Release Name"}]
-RELEASE_NAME=$(buildkite-agent meta-data get "release-name")
-```
-
-## Pipeline Upload
-
-Dynamically add steps to a running build. The core mechanism behind dynamic pipelines — generate YAML at runtime and upload it.
-
-### Basic usage
-
-```bash
-# Upload a specific file
-buildkite-agent pipeline upload .buildkite/deploy-steps.yml
-
-# Pipe generated YAML from stdin
-./scripts/generate-pipeline.sh | buildkite-agent pipeline upload
-```
-
-### Replace mode
-
-By default, uploaded steps are **appended** after the current step. Use `--replace` to replace the entire remaining pipeline:
-
-```bash
-# Replace all remaining steps with the uploaded ones
-buildkite-agent pipeline upload --replace .buildkite/new-pipeline.yml
-```
-
-### Key flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--replace` | `false` | Replace remaining pipeline steps instead of appending |
-| `--no-interpolation` | `false` | Skip environment variable interpolation in the uploaded YAML |
-| `--dry-run` | `false` | Validate and output the pipeline without uploading |
-
-> For pipeline YAML syntax and step types, see the **buildkite-pipelines** skill.
-
-## OIDC Tokens
-
-Request short-lived OpenID Connect tokens from within a job step for authenticating to external services (cloud providers, package registries) without static credentials.
-
-### Basic token request
-
-```bash
-# Request a token for a specific audience
-TOKEN=$(buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-org/my-registry")
-```
-
-### Cloud provider authentication
-
-```bash
-# AWS — request token with STS audience
-TOKEN=$(buildkite-agent oidc request-token --audience "sts.amazonaws.com")
-```
-
-### Key flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--audience` | Buildkite endpoint | Target service URL — must match the OIDC provider audience configuration |
-| `--lifetime` | `600` | Token lifetime in seconds |
-| `--claim` | — | Comma-separated optional claims to include (e.g., `organization_id,pipeline_id`) |
-| `--aws-session-tag` | — | Comma-separated claims to map as AWS session tags |
-
-> For end-to-end OIDC auth flows, cloud provider setup, and token claim details, see the **buildkite-secure-delivery** skill.
-
-## Step Management
-
-Read or modify step attributes at runtime. Useful for conditional logic within steps and build automation.
-
-### Get step attributes
-
-```bash
-# Get current step's label
-LABEL=$(buildkite-agent step get "label")
-
-# Get another step's attribute by key
-STATE=$(buildkite-agent step get "state" --step "deploy-step")
-
-# Get the outcome of a step
-OUTCOME=$(buildkite-agent step get "outcome" --step "test-step")
-```
-
-### Update step attributes
-
-```bash
-# Update current step's label dynamically
-buildkite-agent step update "label" ":rocket: Deploying v${VERSION}"
-
-# Update another step
-buildkite-agent step update "label" ":hourglass: Waiting..." --step "pending-step"
-```
-
-### Cancel a step
-
-```bash
-# Cancel a specific step by key
-buildkite-agent step cancel --step "optional-step"
-```
-
-### Key flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--step` | current step | Step key or UUID to target |
-| `--build` | current build | Build UUID (for cross-build operations) |
-| `--format` | `string` | Output format for `get` |
-
-### Available step attributes
-
-| Attribute | Readable | Writable | Description |
-|-----------|----------|----------|-------------|
-| `label` | yes | yes | Step label displayed in UI |
-| `state` | yes | no | Current state (`running`, `passed`, `failed`, etc.) |
-| `outcome` | yes | no | Final outcome of the step |
-| `key` | yes | no | Step key identifier |
-
-## Distributed Locks
-
-Coordinate parallel jobs within a build using distributed mutex locks. Prevents race conditions when multiple jobs access shared resources.
-
-### Acquire / release pattern
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-# Acquire lock — blocks until available, returns a token
-token=$(buildkite-agent lock acquire "database-migration")
-trap 'buildkite-agent lock release "database-migration" "${token}"' EXIT
-
-# Critical section — only one job runs this at a time
-bundle exec rails db:migrate
-```
-
-### Do / done pattern (one-time setup)
-
-Run a setup task exactly once across all parallel jobs:
-
-```bash
-#!/bin/bash
-echo "+++ Setting up shared test environment"
-
-if [[ $(buildkite-agent lock do "test-env-setup") == "do" ]]; then
-  echo "Downloading test assets..."
-  curl -o /tmp/test-data.zip https://releases.example.com/data.zip
-  unzip /tmp/test-data.zip -d /tmp/shared-test-files/
-  buildkite-agent lock done "test-env-setup"
-else
-  echo "Assets already prepared by another job"
-fi
-
-# All jobs continue here
-run-tests.sh
-```
-
-### Key flags
-
-| Subcommand | Flags | Description |
-|------------|-------|-------------|
-| `lock acquire <name>` | `--timeout` | Maximum wait time in seconds (0 = wait forever) |
-| `lock release <name> <token>` | — | Release with the token from `acquire` |
-| `lock do <name>` | — | Returns `do` if lock acquired, `done` if already completed |
-| `lock done <name>` | — | Mark a `do` lock as completed |
-
-## Environment
-
-Inspect and modify the job's environment variables. Primarily useful for debugging lifecycle hooks and understanding what environment changes hooks made.
-
-```bash
-# Dump all environment variables as JSON
-buildkite-agent env dump | jq .
-
-# Get a specific variable
-buildkite-agent env get "BUILDKITE_BRANCH"
-
-# Set a variable for subsequent hooks and the command
-buildkite-agent env set "DEPLOY_TARGET" "production"
-```
-
-### Key flags
-
-| Subcommand | Default | Description |
-|------------|---------|-------------|
-| `env dump` | JSON to stdout | Dump all environment variables |
-| `env get <keys...>` | — | Get one or more specific variables |
-| `env set <key> <value>` | — | Set a variable for subsequent phases |
-| `env unset <key>` | — | Remove a variable from subsequent phases |
-
-### Debugging hooks
-
-The `env dump` command is particularly useful in lifecycle hooks to see what prior hooks changed:
-
-```bash
-#!/bin/bash
-# .buildkite/hooks/pre-command
-echo "--- Environment after environment hook:"
-buildkite-agent env dump | jq 'keys'
-```
-
-> For agent lifecycle hooks and `buildkite-agent.cfg` configuration, see the **buildkite-agent-infrastructure** skill.
-
-## Secrets
-
-Retrieve cluster secrets at runtime from within job steps. Secrets retrieved this way are automatically added to the log redactor.
-
-### Basic usage
-
-```bash
-# Get a secret value
-SECRET_VAR=$(buildkite-agent secret get "deploy-key")
-
-# Pass directly to a tool
-cli-tool --token "$(buildkite-agent secret get "api-token")"
-```
-
-### Key flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--format` | `string` | Output format: `string` (single secret) or `env` (multiple, KEY="value" pairs) |
-| `--skip-redaction` | `false` | Do not add the secret value to the log redactor |
-| `--job` | current job | Job ID context |
-
-By default, `secret get` automatically registers retrieved values with the log redactor, masking them as `[REDACTED]` in subsequent output.
-
-> For setting up cluster secrets, see the **buildkite-agent-infrastructure** skill. For the declarative `secrets:` pipeline YAML key, see the **buildkite-pipelines** skill.
-
-## Log Redaction
-
-Add values to the build log redactor at runtime so they are masked in all subsequent output. Use this for dynamically-retrieved secrets that were not declared via `secrets:` or `buildkite-agent secret get`.
-
-### Basic usage
-
-```bash
-# Fetch a token from an external source
-DYNAMIC_TOKEN=$(curl -s https://vault.example.com/token)
-
-# Register it with the redactor before using it
-echo "$DYNAMIC_TOKEN" | buildkite-agent redactor add
-
-# Now any log output containing the token value shows [REDACTED]
-echo "Using token: $DYNAMIC_TOKEN"
-# Output: Using token: [REDACTED]
-```
-
-### Multiple values
-
-```bash
-# Redact multiple values
-echo "$SECRET1" | buildkite-agent redactor add
-echo "$SECRET2" | buildkite-agent redactor add
-```
-
-### When to use redactor vs secret get
-
-| Scenario | Use |
-|----------|-----|
-| Secret stored in Buildkite cluster secrets | `buildkite-agent secret get` (auto-redacts) |
-| Secret from external vault (HashiCorp Vault, AWS SSM, etc.) | Fetch externally, then `buildkite-agent redactor add` |
-| Computed sensitive value (temporary token, derived key) | `buildkite-agent redactor add` |
-
-## Tool Signing
-
-Sign and verify pipeline step definitions for integrity checking. Ensures steps have not been tampered with between definition and execution.
-
-### Sign a pipeline
-
-```bash
-# Sign step configuration using a JWKS key
-buildkite-agent tool sign --jwks-file /etc/buildkite-agent/signing-key.json \
-  --step "command=make test" \
-  --step "plugins=docker#v5.12.0"
-```
-
-### Verify a signature
-
-```bash
-# Verify step signature
-buildkite-agent tool verify --jwks-file /etc/buildkite-agent/verification-key.json \
-  --step "command=make test"
-```
-
-### Key flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--jwks-file` | — | Path to JWKS key file for signing or verification |
-| `--jwks-key-id` | — | Key ID to use from the JWKS file |
-| `--step` | — | Step attributes to sign/verify (repeatable) |
-
-> For pipeline signing configuration and rollout strategy, see the **buildkite-secure-delivery** skill.
-
-## Common Mistakes
-
-| Mistake | What happens | Fix |
-|---------|-------------|-----|
-| Missing `--context` on `annotate` | Each call creates a new annotation instead of updating | Always pass `--context` with a stable identifier |
-| Using `--append` without matching `--context` | Append has no effect — creates a new annotation | Ensure `--context` matches the annotation to append to |
-| Forgetting to quote artifact glob patterns | Shell expands globs before `buildkite-agent` sees them | Always quote: `"dist/**/*"` not `dist/**/*` |
-| Reading `meta-data get` before the writing job completes | Key does not exist, command fails with non-zero exit | Use `depends_on` or `wait` to enforce ordering, or use `--default` |
-| Using `pipeline upload --replace` unintentionally | Removes all remaining steps in the build | Only use `--replace` when intentionally rebuilding the entire pipeline |
-| Not releasing locks on script failure | Lock held indefinitely, blocking other jobs | Use `trap ... EXIT` to release locks on any exit |
-| Passing `--audience` that doesn't match OIDC provider config | Token rejected by the target service | Audience must exactly match the provider's configured audience URL |
-| Using `--skip-redaction` with actual secrets | Secret values appear in plain text in build logs | Only use `--skip-redaction` for non-sensitive configuration values |
-| Calling `env set` expecting it to affect the current shell | Variable is set for subsequent hooks/phases, not the current script | Use `export VAR=value` for current-script variables; `env set` for cross-phase |
-| Passing large values via environment variables | OS-level env size limits cause silent truncation or job failure | Switch to file-based approaches (artifacts, meta-data with files) for payloads larger than a few KB |
-| Uploading pipeline YAML with unescaped `$` in `--no-interpolation` mode off | Variables interpolated unexpectedly, producing malformed YAML | Use `--no-interpolation` when YAML contains literal `$` characters |
-
-## Additional Resources
-
-### Reference Files
-- **`references/flag-reference.md`** — Complete flag tables for all subcommands including upload, download, search, shasum, annotate, meta-data, pipeline upload, oidc, step, lock, env, secret, redactor, and tool
-- **`references/patterns-and-recipes.md`** — Advanced multi-subcommand patterns: test failure annotation pipelines, cross-job state machines, OIDC-authenticated Docker push, parallel job coordination with locks, environment debugging
-
-## Further Reading
-
-- [Buildkite Docs for LLMs](https://buildkite.com/docs/llms.txt)
-- [Agent CLI — annotate](https://buildkite.com/docs/agent/v3/cli-annotate.md)
-- [Agent CLI — artifact](https://buildkite.com/docs/agent/v3/cli-artifact.md)
-- [Agent CLI — meta-data](https://buildkite.com/docs/agent/v3/cli-meta-data.md)
-- [Agent CLI — pipeline](https://buildkite.com/docs/agent/v3/cli-pipeline.md)
-- [Agent CLI — OIDC](https://buildkite.com/docs/agent/v3/cli-oidc.md)
-- [Agent CLI — lock](https://buildkite.com/docs/agent/v3/cli-lock.md)
-- [Managing secrets with Buildkite secrets](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets.md)
-- [Dynamic pipelines](https://buildkite.com/docs/pipelines/configure/dynamic-pipelines.md)

package/skills/buildkite-agent-runtime/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Buildkite Agent Runtime"
-  short_description: "In-job agent subcommands for annotations, artifacts, meta-data, and more"
-  icon_small: "./assets/buildkite-icon-small.png"
-  icon_large: "./assets/buildkite-icon-large.png"
-  brand_color: "#00D974"