switchroom 0.5.0

package/skills/buildkite-pipelines/references/advanced-patterns.md

@@ -0,0 +1,286 @@
+# Advanced Pipeline Patterns
+
+Complex patterns for dynamic pipelines, matrix builds, monorepo setups, and multi-stage workflows.
+
+## Dynamic Pipeline Generator (Python)
+
+Generate pipeline YAML based on git diff. Useful for monorepos where only changed services need testing:
+
+```python
+#!/usr/bin/env python3
+"""Generate Buildkite pipeline steps for changed services."""
+import subprocess
+import sys
+import yaml
+
+def changed_files():
+    result = subprocess.run(
+        ["git", "diff", "--name-only", "HEAD~1"],
+        capture_output=True, text=True, check=True
+    )
+    return result.stdout.strip().split("\n")
+
+def affected_services(files):
+    services = set()
+    for f in files:
+        parts = f.split("/")
+        if len(parts) > 1 and parts[0] == "services":
+            services.add(parts[1])
+    return sorted(services)
+
+def generate_pipeline(services):
+    steps = []
+    for svc in services:
+        steps.append({
+            "label": f":test_tube: {svc}",
+            "command": f"cd services/{svc} && make test",
+            "key": f"test-{svc}",
+            "retry": {"automatic": [{"exit_status": -1, "limit": 2}]}
+        })
+
+    if steps:
+        steps.append("wait")
+        steps.append({
+            "label": ":white_check_mark: All services passed",
+            "command": "echo 'All tests passed'"
+        })
+    else:
+        steps.append({
+            "label": ":fast_forward: No services changed",
+            "command": "echo 'No service changes detected, skipping tests'"
+        })
+
+    return yaml.dump({"steps": steps}, default_flow_style=False)
+
+if __name__ == "__main__":
+    files = changed_files()
+    services = affected_services(files)
+    print(generate_pipeline(services))
+```
+
+Use in pipeline:
+
+```yaml
+steps:
+  - label: ":pipeline: Generate"
+    command: ".buildkite/generate-pipeline.py | buildkite-agent pipeline upload"
+```
+
+## Dynamic Pipeline Generator (Bash)
+
+Simpler alternative without Python dependency:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+CHANGED=$(git diff --name-only HEAD~1)
+STEPS=""
+
+for dir in services/*/; do
+  svc=$(basename "$dir")
+  if echo "$CHANGED" | grep -q "^services/$svc/"; then
+    STEPS="${STEPS}
+  - label: ':test_tube: ${svc}'
+    command: 'cd services/${svc} && make test'
+    retry:
+      automatic:
+        - exit_status: -1
+          limit: 2"
+  fi
+done
+
+if [ -z "$STEPS" ]; then
+  echo "steps:
+  - label: ':fast_forward: Skip'
+    command: 'echo No changes detected'"
+else
+  echo "steps:${STEPS}"
+fi
+```
+
+## if_changed Patterns
+
+Skip steps when relevant files haven't changed. Available on Buildkite-hosted agents:
+
+### Basic include pattern
+
+```yaml
+steps:
+  - label: ":nodejs: Frontend tests"
+    command: "npm test"
+    if_changed:
+      - "src/frontend/**"
+      - "package.json"
+      - "package-lock.json"
+```
+
+### Exclude pattern (run unless only docs changed)
+
+```yaml
+steps:
+  - label: ":hammer: Build"
+    command: "make build"
+    if_changed:
+      on_changes_excluding:
+        - "docs/**"
+        - "*.md"
+        - ".github/**"
+```
+
+### Monorepo patterns
+
+```yaml
+steps:
+  - label: ":api: API tests"
+    command: "cd api && make test"
+    if_changed:
+      - "api/**"
+      - "shared/**"       # Shared libraries affect all services
+      - "proto/**"         # Protobuf changes affect API
+
+  - label: ":web: Web tests"
+    command: "cd web && make test"
+    if_changed:
+      - "web/**"
+      - "shared/**"
+```
+
+## Advanced Matrix Builds
+
+### Matrix with adjustments and skips
+
+```yaml
+steps:
+  - label: "Test {{matrix.lang}} {{matrix.version}}"
+    command: "scripts/test-{{matrix.lang}}.sh"
+    matrix:
+      setup:
+        lang:
+          - "ruby"
+          - "python"
+          - "node"
+        version:
+          - "latest"
+          - "previous"
+      adjustments:
+        - with:
+            lang: "ruby"
+            version: "previous"
+          soft_fail: true           # Allow Ruby previous to fail
+        - with:
+            lang: "python"
+            version: "previous"
+          skip: "Python 3.11 EOL"   # Skip entirely with reason
+```
+
+### Matrix with per-combination environment variables
+
+```yaml
+steps:
+  - label: "Build {{matrix.arch}}"
+    command: "make build"
+    matrix:
+      setup:
+        arch:
+          - "amd64"
+          - "arm64"
+      adjustments:
+        - with:
+            arch: "arm64"
+          env:
+            CROSS_COMPILE: "aarch64-linux-gnu-"
+            CGO_ENABLED: "0"
+```
+
+## Multi-Stage Pipeline (Build → Test → Deploy)
+
+Complete pipeline with artifacts passed between stages:
+
+```yaml
+steps:
+  - group: ":hammer: Build"
+    steps:
+      - label: "Compile"
+        command: "make build"
+        artifact_paths: "dist/**/*"
+        key: "build"
+
+  - wait
+
+  - group: ":test_tube: Test"
+    steps:
+      - label: "Unit Tests"
+        command: |
+          buildkite-agent artifact download "dist/*" .
+          make test-unit
+        depends_on: "build"
+        artifact_paths: "coverage/**/*"
+
+      - label: "Integration Tests"
+        command: |
+          buildkite-agent artifact download "dist/*" .
+          make test-integration
+        depends_on: "build"
+
+  - wait
+
+  - block: ":shipit: Deploy to production?"
+    branches: "main"
+
+  - label: ":rocket: Deploy"
+    command: |
+      buildkite-agent artifact download "dist/*" .
+      scripts/deploy.sh
+    branches: "main"
+    concurrency: 1
+    concurrency_group: "deploy/production"
+```
+
+## Plugin Composition
+
+Combine multiple plugins in a single step:
+
+```yaml
+steps:
+  - label: ":docker: Build and Test"
+    plugins:
+      - docker-login#v2.1.0:
+          username: myuser
+          password-env: DOCKER_PASSWORD
+      - docker-compose#v5.5.0:
+          build: app
+          image-repository: index.docker.io/org/repo
+          cache-from:
+            - "app:index.docker.io/org/repo:latest"
+      - test-collector#v2.0.0:
+          files: "tmp/junit-*.xml"
+          format: "junit"
+```
+
+Plugins execute in order: login first, then compose build, then test collection.
+
+## Notification Routing
+
+Route notifications to different channels based on branch or build state:
+
+```yaml
+notify:
+  - slack:
+      channels:
+        - "#deploys"
+      message: ":rocket: Deploy build {{build.number}} {{build.state}}"
+    if: build.branch == "main"
+
+  - slack:
+      channels:
+        - "#ci-alerts"
+      message: ":rotating_light: Build {{build.number}} failed on {{build.branch}}"
+    if: build.state == "failed" && build.branch != "main"
+
+  - email: "oncall@example.com"
+    if: build.state == "failed" && build.branch == "main"
+
+steps:
+  - command: "make test"
+```

package/skills/buildkite-pipelines/references/retry-and-error-codes.md

@@ -0,0 +1,131 @@
+# Retry and Error Codes Reference
+
+Comprehensive guide to Buildkite exit codes, retry strategies, and failure handling.
+
+## Exit Code Table
+
+| Exit code | Meaning | Retryable | Recommendation |
+|-----------|---------|-----------|----------------|
+| `0` | Success | — | No action needed |
+| `1` | General error (test failure, script error) | Usually no | Fix the code; don't auto-retry genuine failures |
+| `-1` | Agent lost connection | Yes | Agent crashed, network drop, or OOM kill. Always retry. |
+| `2` | Misuse of shell command | No | Fix the script syntax |
+| `125` | Docker daemon error | Sometimes | Docker pull failed or daemon unavailable. Retry once. |
+| `126` | Command not executable | No | Fix file permissions: `chmod +x script.sh` |
+| `127` | Command not found | No | Install missing binary or fix PATH |
+| `128` | Invalid exit argument | No | Script called `exit` with invalid value |
+| `137` | SIGKILL (OOM) | Sometimes | Container hit memory limit. Increase memory or optimize. |
+| `143` | SIGTERM | Yes | Spot instance termination, agent shutdown. Always retry. |
+| `255` | SSH failure or timeout | Yes | Network timeout, SSH connection lost. Retry with limit. |
+
+## Retry Strategy Recommendations
+
+### Infrastructure failures (always retry)
+
+```yaml
+retry:
+  automatic:
+    - exit_status: -1    # Agent lost
+      limit: 2
+    - exit_status: 143   # Spot termination
+      limit: 2
+    - exit_status: 255   # SSH/timeout
+      limit: 2
+```
+
+### Network-sensitive steps (retry with backoff)
+
+For steps that fetch external dependencies (npm install, docker pull, apt-get):
+
+```yaml
+retry:
+  automatic:
+    - exit_status: -1
+      limit: 2
+    - exit_status: 125   # Docker daemon
+      limit: 1
+    - exit_status: "*"   # Catch network errors (ECONNRESET, ETIMEDOUT)
+      limit: 1
+```
+
+### Deploy steps (no auto-retry)
+
+Deployment steps should not auto-retry to prevent double-deploys:
+
+```yaml
+retry:
+  automatic: false
+  manual:
+    allowed: true
+    reason: "Review logs before retrying a deployment"
+```
+
+### Test steps (targeted retry)
+
+Retry only infrastructure failures, not test failures:
+
+```yaml
+retry:
+  automatic:
+    - exit_status: -1
+      limit: 2
+    - exit_status: 143
+      limit: 2
+  manual:
+    allowed: true
+```
+
+Do not use `exit_status: "*"` for test steps — it masks real test failures and wastes compute.
+
+## soft_fail vs retry
+
+| Mechanism | Purpose | Build status |
+|-----------|---------|-------------|
+| `retry.automatic` | Re-run the step hoping for a different result | Passes if retry succeeds |
+| `retry.manual` | Allow humans to re-run from the UI | Stays failed until retried |
+| `soft_fail` | Acknowledge failure without blocking the build | Build passes regardless |
+| `soft_fail` with `exit_status` | Treat specific codes as soft failure | Only matched codes are soft |
+
+### soft_fail examples
+
+```yaml
+# Treat any failure as soft (non-blocking)
+- label: "Lint"
+  command: "make lint"
+  soft_fail: true
+
+# Only treat exit code 1 as soft (other codes still hard-fail)
+- label: "Optional integration test"
+  command: "make test-integration"
+  soft_fail:
+    - exit_status: 1
+```
+
+## Retry Limits
+
+| `limit` value | Meaning |
+|---------------|---------|
+| `1` | Retry once (2 total attempts) |
+| `2` | Retry twice (3 total attempts) |
+| `10` | Maximum allowed value |
+
+Keep limits low. High retry counts on genuine failures waste agent time and delay feedback. Recommended: `limit: 2` for infrastructure, `limit: 1` for everything else.
+
+## Combining Retry Rules
+
+Multiple automatic retry rules are evaluated in order. The first matching rule applies:
+
+```yaml
+retry:
+  automatic:
+    - exit_status: -1     # Agent lost → retry 2x
+      limit: 2
+    - exit_status: 143    # Spot termination → retry 2x
+      limit: 2
+    - exit_status: 255    # SSH/timeout → retry 1x
+      limit: 1
+    - exit_status: "*"    # Anything else → retry 1x
+      limit: 1
+```
+
+Place specific codes before the wildcard `"*"`. The wildcard catches all non-zero exits not matched by earlier rules.

package/skills/buildkite-pipelines/references/step-types-reference.md

@@ -0,0 +1,225 @@
+# Step Types Reference
+
+Detailed attribute tables for all Buildkite pipeline step types.
+
+## Command Step
+
+The primary step type. Runs one or more shell commands on an agent.
+
+```yaml
+steps:
+  - label: ":hammer: Build"
+    command: "make build"
+    # OR multiple commands:
+    commands:
+      - "npm ci"
+      - "npm test"
+```
+
+### Command step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `label` | — | Display label in Buildkite UI (supports emoji `:emoji:`) |
+| `command` / `commands` | — | Shell command(s) to execute |
+| `key` | — | Unique identifier for `depends_on` references |
+| `env` | `{}` | Environment variables for this step |
+| `agents` | `{}` | Agent targeting: `queue`, tags |
+| `artifact_paths` | — | Glob pattern(s) for files to upload after step completes |
+| `branches` | all | Branch filter (e.g., `"main"`, `"release/*"`) |
+| `parallelism` | `1` | Number of parallel jobs to create |
+| `timeout_in_minutes` | pipeline default | Max execution time before kill |
+| `retry` | — | Automatic and manual retry rules (see retry reference) |
+| `depends_on` | — | Step key(s) that must pass first |
+| `if` | — | Boolean expression to conditionally run step |
+| `skip` | `false` | Skip reason string, or `true` to skip silently |
+| `soft_fail` | `false` | Treat failure as neutral (build continues green) |
+| `cancel_on_build_failing` | `false` | Cancel this job if another job fails the build |
+| `concurrency` | unlimited | Max parallel jobs in `concurrency_group` |
+| `concurrency_group` | — | Shared concurrency namespace |
+| `concurrency_method` | `ordered` | `ordered` (FIFO) or `eager` |
+| `priority` | `0` | Scheduling priority (higher = sooner) |
+| `plugins` | — | Plugin configurations |
+| `notify` | — | Step-level notifications |
+| `matrix` | — | Matrix build configuration |
+| `cache` | — | Built-in cache (hosted agents only) |
+
+## Wait Step
+
+Blocks execution until all preceding steps complete successfully.
+
+```yaml
+# Simple form
+- wait
+
+# Explicit null form (equivalent)
+- wait: ~
+
+# Continue on failure — downstream steps run even if prior steps failed
+- wait:
+  continue_on_failure: true
+
+# Conditional wait
+- wait:
+  if: build.source == "schedule"
+```
+
+### Wait step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `continue_on_failure` | `false` | Proceed even if prior steps failed |
+| `if` | — | Conditional expression |
+
+## Block Step
+
+Pauses the build for manual approval. The build remains in a "blocked" state until unblocked via UI or API.
+
+```yaml
+# Simple form
+- block: ":shipit: Deploy to production"
+
+# With branch restriction
+- block: ":shipit: Release"
+  branches: "main"
+
+# With select field
+- block: "Release"
+  fields:
+    - select: "Environment"
+      key: "deploy-env"
+      options:
+        - label: "Staging"
+          value: "staging"
+        - label: "Production"
+          value: "production"
+      required: true
+```
+
+### Block step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `block` | — | Label displayed on the block step |
+| `key` | — | Unique identifier for `depends_on` |
+| `prompt` | — | Instructional text shown to the unblocker |
+| `fields` | — | Input fields (text or select) |
+| `branches` | all | Branch filter |
+| `if` | — | Conditional expression |
+| `depends_on` | — | Step key(s) that must pass first |
+| `allow_dependency_failure` | `false` | Show block even if dependencies failed |
+
+## Trigger Step
+
+Creates a build on another pipeline.
+
+```yaml
+steps:
+  - trigger: "deploy-pipeline"
+    label: ":rocket: Trigger deploy"
+    build:
+      branch: "main"
+      commit: "HEAD"
+      message: "Triggered from upstream"
+      env:
+        DEPLOY_VERSION: "1.2.3"
+```
+
+### Trigger step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `trigger` | — | Pipeline slug to trigger |
+| `label` | — | Display label |
+| `build` | `{}` | Build parameters: `branch`, `commit`, `message`, `env`, `meta_data` |
+| `async` | `false` | Don't wait for triggered build to complete |
+| `branches` | all | Branch filter |
+| `if` | — | Conditional expression |
+| `depends_on` | — | Step key(s) that must pass first |
+| `soft_fail` | `false` | Treat triggered build failure as neutral |
+| `skip` | `false` | Skip reason or boolean |
+
+## Group Step
+
+Visually groups steps in the Buildkite UI. Collapsible in the build view.
+
+```yaml
+steps:
+  - group: ":test_tube: Tests"
+    steps:
+      - label: "Unit"
+        command: "make test-unit"
+      - label: "Integration"
+        command: "make test-integration"
+```
+
+### Group step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `group` | — | Group label |
+| `key` | — | Unique identifier for `depends_on` |
+| `steps` | — | Nested steps (any type except group) |
+| `if` | — | Conditional expression (prevents all nested steps + plugins) |
+| `depends_on` | — | Step key(s) that must pass first |
+| `notify` | — | Group-level notifications |
+| `allow_dependency_failure` | `false` | Run group even if dependencies failed |
+
+## Input Step
+
+Collects structured input from a user before the build continues. Similar to block but designed for data collection rather than approval gates.
+
+```yaml
+steps:
+  - input: "Deployment Configuration"
+    fields:
+      - text: "Release tag"
+        key: "release-tag"
+        hint: "The git tag to deploy (e.g., v1.2.3)"
+        required: true
+      - select: "Region"
+        key: "deploy-region"
+        multiple: true
+        options:
+          - label: "US East"
+            value: "us-east-1"
+          - label: "EU West"
+            value: "eu-west-1"
+```
+
+Access collected values in subsequent steps with `build.env("release-tag")` in conditionals or via the Buildkite meta-data API.
+
+### Input step attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `input` | — | Label displayed on the input step |
+| `key` | — | Unique identifier for `depends_on` |
+| `prompt` | — | Instructional text |
+| `fields` | — | Input fields (text or select) |
+| `branches` | all | Branch filter |
+| `if` | — | Conditional expression |
+| `depends_on` | — | Step key(s) that must pass first |
+
+### Field types
+
+**Text field:**
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `text` | — | Field label |
+| `key` | — | Meta-data key to store value |
+| `hint` | — | Helper text below the field |
+| `required` | `true` | Require a value before continuing |
+| `default` | — | Pre-filled value |
+
+**Select field:**
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `select` | — | Field label |
+| `key` | — | Meta-data key to store value |
+| `options` | — | Array of `{label, value}` choices |
+| `multiple` | `false` | Allow selecting multiple options |
+| `required` | `true` | Require a selection before continuing |
+| `default` | — | Pre-selected value |