BambooHR CI Contract

Overview

Create a fail-closed test lane that proves request construction, schema handling, redaction, retries, and tenant isolation without placing production BambooHR credentials or employee records in routine CI.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

Use the pinned OpenAPI from BambooHR's official SDK repository as the endpoint and schema authority. Record the upstream commit and review diffs before updating the pin. Dataset v1 and legacy report deprecations must be regression assertions, not silently normalized away.

Authentication

Unit and contract tests use synthetic credentials that can never authenticate. An optional live smoke job uses a dedicated least-privilege identity in an approved test tenant, is disabled for forks, and never exposes secrets to pull- request code or artifacts.

Instructions

1. Inspect the repository's runtime, test framework, CI provider, generated-code policy, and secret-scanning rules.
2. Add synthetic unit tests for tenant validation, auth header creation, token-refresh persistence, redaction, error typing, retry boundaries, and idempotency decisions.
3. Pin BambooHR's official OpenAPI commit and add contract tests for only the operations the application uses. Alert on removed operations, auth changes, changed required fields, response/status drift, or new deprecations.
4. Use invented names and values in fixtures. Include adversarial cases for cross-tenant IDs, permission-denied fields, oversized pages, webhook replay, malformed signatures, and PII-like strings that must be redacted.
5. Make formatting, static analysis, tests, contract diff, secret scan, and artifact scan required. Upload only reports proven free of payload data.
6. If a live smoke is justified, make it manually dispatched or protected- environment gated, read-only, body-discarding, time-bounded, and non-forked.
7. Fail the release on any required gate; do not convert schema/security failures to advisory because BambooHR is temporarily unavailable.

Tool Discipline

Use Read, Glob, and Grep to inspect existing CI and tests. Use Write/Edit only for approved workflows, fixtures, and assertions. This skill does not run CI, create secrets, call a tenant, or change repository settings.

Approval Boundaries

Require approval before adding a dependency, enabling a live smoke, changing a required check, uploading artifacts, or granting CI access to a tenant secret.

Output

Return CI stages and triggers, OpenAPI pin, synthetic fixture policy, required checks, live-smoke boundary, secret exp…

BambooHR Error Triage

Overview

Diagnose from evidence, not guessed endpoint behavior. Preserve the request ID and operation while excluding credentials and HR payloads. A 200 with missing fields may still be a permission/schema issue on legacy report paths.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The official Python SDK defines typed exceptions for bad request, authentication, permission, not found, timeout, conflict, payload size, media type, validation, rate limit, and server/network failures. Its request ID may come from any of three documented response headers. Automatic retry is limited to 408, 429, 504, and 598—not every 5xx.

Authentication

Record only auth mode and credential alias/age. For OAuth 401, allow one controlled refresh when configured; persist rotated tokens. For API-key 401, verify owner, tenant, and revocation without printing the key. A 403 usually requires permission analysis, not a retry.

Instructions

1. Capture timestamp, tenant alias, operation, method/path template, status or typed exception, request ID, attempt count, latency, and a redacted summary.
2. Reproduce against a fixture first. If a live retry is needed, obtain approval and ensure the operation is read-only or idempotent.
3. Classify:

• 400/422: validate body, field IDs, filters, pagination, and media type.
• 401: validate credential/refresh lifecycle and tenant.
• 403: compare required endpoint/field permissions with the owning identity.
• 404: distinguish resource, tenant, format, and deprecated-path failures.
• 409/412: refresh current HR state or policy; do not overwrite.
• 413: shrink page, field set, or upload.
• 429: honor Retry-After when supplied and consume the retry budget.
• 500/502/503: record request ID and service condition; retry only when the operation and current client policy explicitly allow it.
• 504/598: bounded backoff for idempotent work, then queue/defer.

1. Compare current OpenAPI and SDK version before changing code. Do not paper over a deprecated endpoint with an unlimited retry.
2. Add a regression test that proves classification, redaction, and behavior.

Tool Discipline

Use Read, Glob, and Grep to inspect the failing code, schema, and bounded logs. Use Write/Edit only for an approved fix and regressi…

BambooHR Employee and Dataset Sync

Overview

Design a resumable read pipeline for employee data. Prefer BambooHR's dataset v2 contract for new bulk data work, minimize fields at the source, and treat missing fields as a possible permission decision rather than automatically as data loss.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Employee endpoints include list, get, create, and update operations.
• POST /api/v2/datasets/{datasetName}/data accepts fields, OData-style filter, orderBy, page, and pageSize and returns data, links, and meta; page size is at most 1000 in the reviewed OpenAPI.
• Dataset v1 data calls are deprecated. Dataset discovery and field discovery use v1.2 endpoints in the current OpenAPI.
• Legacy custom-report endpoints carry deprecation notices. Do not start a new pipeline on them merely because old examples do.

Authentication

Use OAuth scope report where the documented dataset operation requires it, or a dedicated API-key user with access only to selected fields. Bind credentials, checkpoint, and destination namespace to one tenant.

Instructions

1. Define the business purpose, legal basis, tenant, destination, data owner, refresh target, and exact employee fields before making a request.
2. Discover the dataset and its field definitions from current endpoints. Save field IDs and semantic mappings as reviewed configuration, not assumptions.
3. Query dataset v2 with deterministic ordering. Keep every ordered field in the requested fields list and bound pageSize to the documented maximum.
4. Follow returned pagination metadata or links until completion. Persist a checkpoint only after the destination transaction commits.
5. Upsert by a stable tenant-scoped employee identifier. Distinguish absent, null, redacted, future-dated, and inactive values.
6. Reconcile source count, received count, accepted count, rejected count, and destination count. Quarantine schema or permission drift instead of deleting.
7. Encrypt retained HR data and delete raw page bodies after the approved retention window.

Tool Discipline

Use Read, Glob, and Grep to inspect mappings, schemas, and checkpoints. Use Write/Edit only for approved pipeline code, configuration, and tests. Do not use this skill to fetch production employee data or mutate a downstream system.

Approval Boundaries

Require approval for the field set, inactive/future employee inclusion…

BambooHR Time-Off, Benefits, and Files

Overview

Implement sensitive secondary HR workflows without collapsing reads and mutations into one privilege boundary. Each domain has different approvers, retention needs, and consequences; choose exactly one operation class per run.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The official SDK/OpenAPI exposes time-off policy, balance, request, and status operations; company and employee benefit reads; and company/employee file operations. Some operations return an empty body or plain text, so success must be determined from the documented status and follow-up read—not a guessed JSON shape.

Authentication

Use an OAuth client or dedicated API-key user whose permissions match the chosen domain and action. A file reader should not inherit time-off approval rights; a balance reader should not inherit employee-file access.

Instructions

1. Classify the request as time-off, benefits, or files and as read or mutation. Record tenant, employee identifier, purpose, approver, and expected effect.
2. Discover IDs from authorized list operations; never accept an unqualified ID from another tenant or infer a benefit, policy, request, or file identifier.
3. For reads, request only needed date range, fields, and records. Do not retain file bytes or dependent/benefit data in general application logs.
4. For a proposed mutation, generate a before/after preview and idempotency key. Validate policy, effective dates, units, status transition, and employee.
5. Obtain approval from the owning HR role immediately before execution. Re-read the target after approval to detect intervening changes.
6. Verify status and state with a follow-up read. Record request ID and audit metadata, not raw employee data.
7. Define compensation for partial failure; never auto-reverse an approved HR action without a second authorization.

Tool Discipline

Use Read, Glob, and Grep to inspect domain mappings and current safeguards. Use Write/Edit only for approved adapters, previews, and tests. The allowed tools do not authorize a live BambooHR read, download, or mutation.

Approval Boundaries

Require separate approval for any time-off request/status change, balance adjustment, benefit write, file upload/download/delete, or permission expansion. Never expose document contents in a chat transcript or CI artifact.

Output

Return domain, operation, tenant, minimized inputs, before/after preview, approval identity, response status, verification read, request ID, retention handling, and rollback or compensation status.

Er…

BambooHR Operational Cost Tuning

Overview

Optimize costs the team can actually measure: compute, egress, storage, observability, queue backlog, failure recovery, and engineering/support time. Do not quote a per-call BambooHR price or numeric quota unless the customer's current contract or a current official price source explicitly provides it.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

BambooHR's dataset v2 projection and pagination can reduce request fan-out and unnecessary fields. The official SDK exposes bounded retries and redacted logging. These capabilities reduce waste only when the integration measures requests, bytes, attempts, and retained data.

Authentication

Separate usage by tenant and credential alias without embedding keys or tokens in cost logs. Auth failures are operational waste and potential security events; do not solve them by using one broader shared credential.

Instructions

1. Choose a representative window and measure request count by operation, transferred bytes, retries, failed jobs, queue time, compute duration, storage/backup growth, log volume, and human incident time.
2. Assign each call to a business output. Mark duplicates, polling with no state change, N+1 employee calls, deprecated report traffic, and repeated failures.
3. Replace fan-out with minimized dataset v2 projections where semantics match. Use deterministic pagination and retain only approved fields.
4. Cache stable metadata with an owner and TTL. Prefer checkpoints and change- aware workflows to blind full refreshes, but keep periodic reconciliation.
5. Cap retries and dead-letter terminal work. A retry storm converts an outage into cost and rate pressure without producing value.
6. Reduce log payloads to safe operational fields and set retention by purpose. HR response bodies should not be an observability cost center.
7. Model candidate savings from measured infrastructure unit rates and labor assumptions. Label BambooHR contract costs as customer-supplied, not inferred.
8. Canary the change and compare cost, freshness, completeness, error rate, and recovery time before rollout.

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, and existing metrics. Use Write/Edit only for approved measurement, optimization, and tests. Do not access invoices, production HR data, or billing systems under this skill.

Approval Boundaries

Require approval before changing refresh frequency, fields, retention, cache, concurrency, reconciliation cadence, or a customer-contract assumption. Cost reduction may not weaken pri…

BambooHR Privacy-Safe Debug Receipt

Overview

Create evidence sufficient to reproduce and route a BambooHR failure without packaging employee records, credentials, tokens, raw request/response bodies, webhook payloads, or environment dumps.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The official Python SDK surfaces a request ID from x-request-id, x-bamboohr-request-id, or request-id and includes a secure log filter for sensitive headers and URL parameters. These controls do not make arbitrary application logs safe; verify the emitted artifact field by field.

Authentication

Diagnostics may record only auth mode, credential owner alias, token/key age, and last rotation time. Never include Authorization headers, API keys, client secrets, refresh/access tokens, cookie values, or webhook private keys.

Instructions

1. Define incident ID, tenant alias, UTC window, operation, expected result, actual status, impact, and evidence recipient.
2. Locate only bounded logs for the affected request IDs. Do not grep or export an entire environment, home directory, database, or log bucket.
3. Produce a manifest containing application version/commit, SDK or adapter version, endpoint template without IDs/query values, auth mode, timeout, configured retry count, status, latency, request IDs, and safe aggregate counts. Do not retain the response body.
4. Replace tenant, employee, file, benefit, applicant, and webhook identifiers with stable incident-local aliases. Remove bodies and free-text errors that may echo BambooHR's response content.
5. Scan the proposed receipt for secret formats, email addresses, government IDs, dates of birth, addresses, compensation, health/benefit data, and URLs containing query values. Review manually after automated scanning.
6. Write a checksum and explicit inclusion/exclusion list. Keep the artifact local until the data owner approves its recipient and retention.
7. Prefer a directory or JSON/Markdown receipt. Do not create a broad tarball by default; archive only the reviewed manifest if the support channel requires it.

Tool Discipline

Use Read, Glob, and Grep only against the approved paths and time window. Use Write/Edit to create the minimal receipt and redaction tests. Do not use shell archive or network tools under this skill.

Approval Boundaries

Require approval before reading production logs, writing a diagnostic artifact, including any pseudonymized employee fact, or sending evidence to BambooHR or a third party. Creation does not authorize transmission.

Outpu…

BambooHR Controlled Deployment

Overview

Promote an already-tested BambooHR connector without baking one cloud vendor's CLI into the skill. Separate application deployment, secret mutation, OAuth registration, webhook replacement, data migration, and traffic cutover because they have different approvals and rollback behavior.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The application must use the tenant-local BambooHR host. OAuth redirects are exact HTTPS locations and refreshed tokens require application persistence. Webhook destinations require HTTPS and creation yields a one-time verification key. Health checks must not expose employee data or require broad HR permissions.

Authentication

Create distinct identities/secrets per environment and tenant. Bind token records to subject and tenant. Deployment health may verify local configuration and dependencies; a live BambooHR readiness check must be separately approved, read-only, low sensitivity, body-discarding, and rate bounded.

Instructions

1. Record immutable artifact digest, source commit, configuration schema, target environment, tenant set, deployment owner, data migration, and rollback owner.
2. Diff configuration names and secret references without reading secret values. Verify no production credential appears in build args, images, logs, or previews.
3. Validate exact OAuth redirect URIs, trusted tenant mapping, encrypted token persistence, rotation callback, egress policy, TLS, and log redaction.
4. Run offline tests, schema checks, migration dry run, and synthetic webhook verification before deploying the immutable artifact.
5. Deploy dark or to a canary. Run local liveness/readiness first; then, if approved, one body-discarding company-information check with a request ID.
6. Drain or pause schedulers and queues during cutover so two versions do not race. Preserve idempotency and checkpoints across rollback.
7. Observe authentication failures, refresh failures, request errors, queue age, reconciliation, webhook verification, and cross-tenant alarms.
8. Promote or roll back against explicit thresholds. Revoke superseded secrets or webhook keys only after the new path is verified and separately approved.

Tool Discipline

Use Read, Glob, and Grep to inspect deployment files and secret references. Use Write/Edit only for approved manifests, configuration, and tests. This skill does not run provider CLIs, authenticate, provision, deploy, rotate, or cut traffic.

Approval Boundaries

Require separate approval for deployment, database migration, secret write, OAuth red…

BambooHR Minimal Connection Proof

Overview

Verify routing, TLS, authentication, and basic permission with the smallest useful call. Do not begin with the employee directory: it contains personal data and is unnecessary for a connectivity test.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

Use the tenant-local host https://company-subdomain.bamboohr.com. The official OpenAPI operation GET /api/v1/company_information returns basic company profile information and supports OAuth or API-key authentication.

Authentication

Prefer a short-lived OAuth access token for partner integrations. For an internal API key, Basic auth uses the API key as username and x as password. Load secrets from the current process environment or an approved secret manager; never place a token directly in the command, URL, source file, or receipt.

Instructions

1. Confirm the exact tenant subdomain and auth mode. Reject slashes, schemes, ports, and dots in the subdomain input.
2. Inspect the project for an existing BambooHR client and reuse its timeout, user-agent, request-ID, and redaction controls.
3. If an operator approves a direct API-key smoke test, run a body-discarding request:

   curl --fail-with-body --silent --show-error \
     --max-time 20 --output /dev/null --write-out '%{http_code}\n' \
     --user "${BAMBOOHR_API_KEY}:x" \
     "https://${BAMBOOHR_COMPANY_SUBDOMAIN}.bamboohr.com/api/v1/company_information"

1. For OAuth, send Authorization: Bearer … from the application's secret- aware HTTP client rather than echoing a token through shell history.
2. Record timestamp, tenant alias, auth mode, HTTP status, elapsed time, and a server request ID when available. Do not retain the response body.
3. Only after the connection proof succeeds, request approval for an employee- scoped test with an explicitly minimized field list.

Tool Discipline

Use Read, Glob, and Grep to find current client and configuration conventions. Use Write/Edit only to add an approved example or test. Bash is restricted to curl; show the exact host and body-retention behavior before executing it.

Safety Justification

The optional live request can reach sensitive HR infrastructure. It is limited to HTTPS, one read-only company-information endpoint, a finite timeout, no body retention, and operator approval for the tenant and credential.

Approval Boundaries

Do not make a live request, access an employee endpoint, install a pack…

BambooHR Authentication Setup

Overview

Configure the narrowest BambooHR identity that fits the integration. OAuth 2.0 is BambooHR's recommended path for partner integrations. An API key is suitable for an internal tool or prototype when its owning user's permissions and key lifecycle are acceptable.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Tenant API host: https://{company-subdomain}.bamboohr.com.
• Authorization endpoint: https://{company-subdomain}.bamboohr.com/authorize.php.
• Token endpoint: POST https://{company-subdomain}.bamboohr.com/token.php?request=token.
• API-key requests use HTTP Basic authentication with the key as username and x as password.
• BambooHR's official Python source supports OAuth, refresh, API keys, request IDs, retry controls, and redacted logging. As of 2026-09-11 the documented bamboohr-sdk distribution is not discoverable on public PyPI; verify the registry before installing or use an approved commit pin.

Authentication

For OAuth, register an HTTPS redirect URI, generate a high-entropy state, bind it to the initiating session, and reject callbacks whose state does not match. Exchange the code server-side. Store access token, refresh token, expiry, tenant, subject, and granted scope in an encrypted, tenant-scoped record.

For API keys, create a dedicated BambooHR user with only required field and workflow permissions. Store the key in the deployment secret manager. Never put it in .env.example, logs, shell history, test fixtures, or a client bundle.

Instructions

1. Identify whether the integration is partner/multi-tenant or internal/single- tenant, and record the authentication decision.
2. Derive the tenant subdomain from the customer's BambooHR URL; do not accept a full arbitrary host from untrusted input.
3. For OAuth, implement authorization-code exchange, state validation, encrypted token persistence, rotation, and reauthorization after terminal refresh failure. The SDK does not persist refreshed tokens for the application.
4. For API keys, assign a dedicated owner, document field permissions, and set a rotation and revocation procedure before use.
5. Test with a low-sensitivity read such as company information. Capture status and request ID, but discard the response body from evidence.
6. Exercise invalid-state, expired-token, revoked-key, wrong-tenant, and denied- field cases before production approval.

Tool Discipline

Use Read, Glob, and Grep to inspect existin…

BambooHR Local Development Loop

Overview

Make local iteration independent of production HR data and network availability. Use a fake transport whose fixtures are designed from the official schema, not recorded from real employees.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The official OpenAPI and SDK docs define operations, status codes, auth modes, pagination, and typed errors. They are suitable inputs for contract fixtures; they do not authorize copying actual BambooHR payloads into a repository.

Authentication

Default local configuration uses obvious non-secret placeholders and a fake transport. A live test-tenant profile is separate, ignored by version control, loaded from an approved secret store, and never activated by ordinary test or watch commands.

Instructions

1. Inspect runtime, package manager, test framework, local configuration, and current BambooHR adapter.
2. Put a transport interface behind the adapter. Implement an in-memory fake with explicit scripted responses and request assertions.
3. Create synthetic employees and HR objects with impossible domains and values. Cover active/inactive/future states, missing permitted fields, pagination, empty results, and schema drift without realistic government IDs or records.
4. Add scenarios for 401, 403, 409, 412, 413, 422, 429, 503, 504, 598, timeout, redaction, request IDs, and ambiguous mutation outcome.
5. Add a watch command that runs offline unit/contract tests only. Keep any integration test behind an explicit profile and approval gate.
6. For webhook development, generate payloads locally, verify raw-byte HMAC behavior with a synthetic key, and test replay/idempotency. Do not capture a real delivery as a fixture.
7. Document reset, seeded scenarios, schema-pin update, and the exact command that proves the default loop performs no network calls.

Tool Discipline

Use Read, Glob, and Grep to inspect code and ignored paths. Use Write/Edit for approved fake transport, fixtures, tests, and developer docs. Do not install packages or access BambooHR under this skill.

Approval Boundaries

Require approval before adding a dependency, storing any live credential, calling a tenant, capturing traffic, or adding a fixture derived from customer data. Redaction does not automatically make a production payload reusable.

Output

Return transport boundary, scenario inventory, fixture provenance, commands, no-network proof, coverage for auth/…

BambooHR Performance Tuning

Overview

Optimize from a measured request graph while preserving completeness and privacy. The first objective is usually eliminating per-employee fan-out, not raising concurrency against an unknown tenant limit.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

Dataset v2 returns selected fields with links and meta pagination and permits page sizes up to 1000 in the reviewed OpenAPI. Its request uses filter, orderBy, page, and pageSize. Dataset v1 data retrieval and custom-report paths carry deprecation notices and should not anchor new optimizations.

Authentication

Benchmark with the same auth mode and effective field permissions as production, but only in an approved test tenant or sanitized workload. Different identities can produce different shapes, so never compare results without recording the credential alias and permission set.

Instructions

1. Establish baseline p50/p95 latency, request count by operation, page count, records and bytes received, retries, error rate, CPU/memory, destination time, and end-to-end freshness.
2. Draw the request graph. Replace N+1 employee reads with dataset v2 projections where the required fields and semantics are supported.
3. Minimize fields, add deterministic orderBy, and tune pageSize below the documented maximum based on payload, memory, latency, and 413 behavior.
4. Stream or page through data and commit checkpoints only after destination durability. Do not load the complete workforce into memory by default.
5. Cache stable metadata such as dataset/field definitions with a bounded TTL. Do not cache tokens or unrestricted employee payloads in a shared cache.
6. Add per-tenant concurrency control and reuse safe HTTP connections. Increase parallelism only during a measured canary and watch 429 and tail latency.
7. Compare exact record identities and reconciliation counts before and after. Roll back if freshness, completeness, permissions, or memory regresses.

Tool Discipline

Use Read, Glob, and Grep to inspect the request graph and current metrics. Use Write/Edit for approved instrumentation, query changes, and tests. This skill does not authorize a production benchmark or HR-data export.

Approval Boundaries

Require approval before querying production, changing field selection or cache retention, increasing concurrency, or replacing a source endpoint. Performance does not justify silently omitting inactive or future-dated reco…

BambooHR Production Readiness Gate

Overview

Issue a reproducible go/no-go verdict. A checklist item passes only with current evidence tied to the release artifact and environment; "configured" or "tested before" is not a receipt.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The reviewed BambooHR contract includes tenant-local hosts, OAuth/API-key auth, caller-owned refreshed-token persistence, typed request IDs/errors, finite SDK retries, dataset v2, and one-time webhook keys. Legacy dataset/report deprecations and Python package-registry uncertainty must be explicit.

Authentication

Require auth mode, identity owner, tenant binding, field/operation permissions, credential age, rotation/revocation runbook, and OAuth state/token-persistence tests. Verify references, not secret values.

Instructions

1. Freeze release commit and artifact digest. Confirm source, generated files, dependency lock, vulnerability/secret scans, and required CI are green.
2. Verify each tenant and environment has isolated configuration, identity, token/key storage, destination namespace, queues, and checkpoints.
3. Approve the minimum employee fields and workflows; confirm purpose, retention, encryption, deletion, backup, log, and support-evidence controls.
4. Prove offline tests for auth, tenant isolation, permission loss, pagination, reconciliation, retries, ambiguous writes, schema drift, webhook HMAC/replay, and redaction.
5. Prove production topology: timeouts, finite retries, per-tenant concurrency, circuit breaker, dead letter, alerts, dashboards, on-call ownership, and body-free health checks.
6. If using Python SDK source, record exact commit and approval; do not claim a public registry release until reverified. For PHP, record the locked Packagist version.
7. Rehearse rollback without deleting new data or replaying HR mutations. Define scheduler/queue ownership and checkpoint compatibility for both versions.
8. Run an approved canary, compare source/destination counts and identities, and observe through the agreed window.
9. Mark every gate PASS, FAIL, WAIVED with owner/expiry, or NOT APPLICABLE with reason. Any unresolved critical gate yields NO-GO.

Tool Discipline

Use Read, Glob, and Grep to collect exact release evidence. Use Write/Edit only for the approved readiness receipt and missing tests/configuration. This skill does not deploy, rotate secrets, call tenants, or alter production state.

Approval Boundaries

Launch approval must identify engineering, HR/data owner, security/privacy, and operations owners as appli…

BambooHR Rate and Retry Control

Overview

Protect the tenant, worker pool, and downstream systems with a finite retry budget. BambooHR does not publish one universal numeric quota in the reviewed official sources, so do not turn an observed limit into a product guarantee.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

The official Python SDK retries HTTP 408, 429, 504, and 598 with exponential delays beginning at 100 ms. Retry count is configurable from zero through five and defaults to one. It exposes RateLimitExceededException and request IDs. 503 is represented as service unavailable but is not in that documented automatic-retry set.

Authentication

Retries must reuse the same tenant-bound identity without logging or rebuilding its token. If an OAuth token expires, permit one refresh workflow; do not count repeated authentication failures as rate-limit retries.

Instructions

1. Inventory every caller, concurrency source, scheduled sync, webhook replay, and manual job that shares the tenant identity.
2. Classify operations as read-only, idempotent with a key, conditionally safe, or unsafe to retry. Default mutations to no automatic retry.
3. On 429, parse and honor a valid Retry-After value when present; otherwise use capped exponential backoff with jitter. Bound total attempts and elapsed time.
4. For 408, 504, or 598, apply the same budget only to retry-safe work. Treat other failures according to explicit application policy, not by widening the SDK's documented set accidentally.
5. Centralize per-tenant concurrency and queue limits. Add a circuit breaker for sustained failures and spread scheduled full syncs.
6. Emit status class, request ID, attempt, selected delay, queue age, breaker state, and terminal disposition—never response bodies or credentials.
7. Test exact attempt counts, jitter bounds, Retry-After, elapsed-time cap, cancellation, restart persistence, and no-retry mutations.

Tool Discipline

Use Read, Glob, and Grep to find retry loops and worker concurrency. Use Write/Edit only for approved policy, instrumentation, and tests. This skill does not send live requests or tune an account's BambooHR configuration.

Approval Boundaries

Require approval before changing production concurrency, replaying queued HR operations, or enabling retries for a mutation. Never retry an ambiguous write until a read proves its current state.

Output

Return operation classification, retryable statuses, max attempts and…

BambooHR Reference Architecture

Overview

Produce an architecture that keeps control-plane actions, HR data-plane reads, mutations, webhook reception, and downstream delivery independently governable. The connector is not the authority for HR policy; BambooHR and the approved destination each retain explicit ownership.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

Use tenant-local BambooHR hosts and current official OpenAPI operations. Prefer dataset v2 for new bulk reads. Support OAuth token refresh with external persistence, typed request IDs/errors, bounded retries, and webhook one-time key custody. Treat deprecated report/dataset v1 paths as migration boundaries.

Authentication

The control plane stores encrypted, tenant-scoped credential metadata and exact redirect/permission configuration. Workers receive short-lived access to one tenant credential; they cannot choose arbitrary hosts or read another tenant's tokens. API-key mode uses a dedicated BambooHR identity and explicit rotation.

Instructions

1. Define actors, tenants, business outcomes, systems of record, fields, workflows, freshness, scale, residency, retention, and recovery objectives.
2. Draw trust boundaries among consent/callback, token store, scheduler, sync worker, webhook ingress, queue, schema validator, destination adapter, checkpoint store, audit log, monitoring, and support tooling.
3. Separate read and mutation workers and permissions. Route jobs with an immutable tenant ID resolved to trusted credential and destination metadata.
4. For scheduled sync, use minimized dataset v2 reads, deterministic pagination, transactional checkpoints, idempotent destination upsert, and periodic full reconciliation.
5. For webhooks, terminate TLS, retain raw bytes only in memory for verified HMAC, reject replay, enqueue idempotently, acknowledge promptly, and use the event only as a trigger for an authorized source read when appropriate.
6. Enforce field allowlists and schema versions before queues/storage. Encrypt approved HR data and keep bodies out of general logs, traces, and dead letters.
7. Add per-tenant concurrency, finite retries, circuit breaker, dead-letter review, request-ID correlation, and backpressure.
8. Design credential revocation, tenant offboarding, data deletion, webhook replacement, schema migration, regional failure, and rollback before launch.

Tool Discipline

Use Read, Glob, and Grep to ground the design in the existing system. Use Write/Edit only for approved architecture records, diagrams-as-code, and interface contracts. This skill does not provision or m…

BambooHR SDK and Client Patterns

Overview

Build a small application-owned adapter around a verified BambooHR transport. Keep BambooHR models and error details at the adapter boundary so upstream SDK regeneration or endpoint migration does not ripple through business logic.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• BambooHR/bhr-api-python and BambooHR/bhr-api-php are official repositories.
• bamboohr/api 2.0.1 is published on Packagist.
• The Python repository documents bamboohr-sdk 1.0.0, but public PyPI did not expose that distribution on 2026-09-11 and the repository had no tag or release. Treat it as source-visible, not registry-proven.
• No official npm BambooHR SDK was found; a TypeScript integration should use a narrow HTTP adapter rather than claim an official package.

Authentication

Expose constructors for OAuth and API-key identities, not raw headers. Bind each client to one validated tenant subdomain. If OAuth refresh is enabled, persist rotated tokens through the caller-owned callback; the Python SDK does not store them across restarts.

Instructions

1. Inventory language, package lock, existing HTTP client, and supported auth modes with Read, Glob, and Grep.
2. Verify the selected package in its public registry at implementation time. For an approved source install, pin an immutable commit and record its hash, license, provenance, and update owner.
3. Define an adapter with explicit operations such as getCompanyInformation, listEmployees, and queryDatasetV2; do not expose an arbitrary URL method to untrusted callers.
4. Normalize errors into status, operation, retryability, request ID, and a redacted summary. Preserve the original exception only in protected logs.
5. Keep tenant, authentication, timeout, retry budget, and user-agent immutable for the life of a client instance.
6. Test request construction, tenant rejection, secret redaction, typed error mapping, token-refresh persistence, and response-shape drift with fixtures.

Tool Discipline

Use Read, Glob, and Grep to establish the project's language and package state. Use Write/Edit only for the approved adapter and tests. This skill does not authorize package installation, remote registry mutation, or live tenant calls.

Approval Boundaries

Require approval before adding a dependency, using an unreleased commit, making a tenant request, broadening OAuth scopes, or enabling debug logging around HR data. Never silently fall back from OAuth to an…

BambooHR Integration Security

Overview

Treat the connector as a high-sensitivity HR data system. Security is not only secret storage: it includes tenant isolation, field-level authorization, data minimization, webhook authenticity, auditability, and deletion.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

BambooHR permissions affect which employee fields and operations an identity can access. The official SDK supports secure logging and request-ID extraction, but application logs, queues, databases, exports, and support artifacts remain the operator's responsibility. Webhook creation returns a one-time private key.

Authentication

Use OAuth for partner integrations with validated state, exact HTTPS redirect URIs, encrypted per-subject token storage, and persisted token rotation. For API keys, use a dedicated least-privilege user, named owner, expiry review, and tested revocation. Never share one identity across tenants.

Instructions

1. Map trust boundaries: user/browser, callback, token store, connector, BambooHR tenant, queue, destination, logs, backups, support, and analytics.
2. Inventory every requested field and classify sensitivity. Remove fields not tied to an approved purpose; isolate government IDs, compensation, medical, dependent, benefit, and file data.
3. Enforce tenant from trusted credential metadata, not from a request body. Validate identifiers at every queue and storage boundary.
4. Redact authorization, keys, cookies, query strings, webhook secrets, and HR values. Allow request IDs, operation names, status, latency, and safe counts.
5. For webhooks, store the creation-only key atomically, verify HMAC-SHA256 over raw bytes using the currently documented carrier, compare in constant time, and reject before parsing or side effects.
6. Encrypt in transit and at rest, set retention and deletion jobs, restrict backup access, and test subject/customer deletion obligations.
7. Exercise cross-tenant access, denied fields, revoked credentials, replay, log injection, oversized payload, SSRF-like tenant input, and support-bundle exfiltration in tests.

Tool Discipline

Use Read, Glob, and Grep for code and configuration inspection. Use Write/Edit only for explicitly approved hardening and regression tests. Never write sample secrets or real employee records.

Approval Boundaries

Require security/data-owner approval before broadening fields, OAuth scopes, API-key permissions, retention, destinations, webhook events, or support access. Do not rotate or revoke live credentials as part of an audit without approval.

BambooHR Upgrade and Migration

Overview

Move one contract boundary at a time and prove semantic parity on authorized data. A repository default branch is not a released package; a README install line is not registry evidence; and a v1 URL does not mean the operation is free from deprecation.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Dataset v1 data retrieval is deprecated in favor of POST /api/v2/datasets/{datasetName}/data.
• Saved/custom report operations carry replacement notices in the current SDK docs.
• Official Python and PHP SDK repositories were updated 2026-08-31. PHP package bamboohr/api 2.0.1 is on Packagist. Python bamboohr-sdk 1.0.0 is described in source but was absent from public PyPI and had no tag/release on 2026-09-11.

Authentication

Preserve the existing identity during endpoint/SDK migration unless auth change is the explicit workstream. If migrating API key to OAuth, treat registration, state validation, token storage, refresh, permission equivalence, and revocation as a separate staged migration with independent rollback.

Instructions

1. Freeze the current adapter, dependency lock, endpoint inventory, auth mode, fields, filters, pagination, error mapping, retry policy, and production metrics.
2. Pin target OpenAPI/SDK evidence to an immutable commit, tag, or registry artifact. Verify package availability, integrity, license, and runtime support.
3. Diff operations, required parameters, auth scopes, status codes, response shapes, deprecations, pagination, retry behavior, and model return types.
4. Put old and new implementations behind the same application adapter. Keep writes on the old path while dual-reading a minimized approved cohort.
5. Compare record identities, field semantics, null/absent/redacted values, inactive/future cases, ordering, page completion, and error behavior. Do not log differing employee values; report aliases and counts.
6. Canary the new read path, then separately stage any idempotent write path with before/after verification and explicit approval.
7. Maintain checkpoints that both versions understand or define a reversible conversion. Do not let rollback replay completed HR mutations.
8. Remove old code only after the observation window, reconciliation, dependency scan, runbook update, and rollback retirement approval.

Tool Discipline

Use Read, Glob, and Grep to inventory current contracts and versions. Use Write/Edit only for approved adapters, migrations, tests, and docs. This skill does not install packages, …

BambooHR Webhook Operations

Overview

Operate permissioned BambooHR webhooks as a security boundary. The creation response contains a privateKey used for HMAC-SHA256 and returns it only once; losing it requires controlled replacement, not a retrieval call.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Create/list/get/update/delete and log endpoints live under /api/v1/webhooks.
• The destination URL must use HTTPS and format is required (json or form-encoded in the reviewed OpenAPI).
• monitorFields is required when events include employee.updated or employee_with_fields.updated; omitted events default to field-based employee events that also require monitored fields.
• Receiver 4xx responses are not retried. Receiver 5xx responses may be retried up to five times at documented 5, 10, 20, 40, and 80 minute intervals.

Authentication

Webhook management requires OAuth scope webhooks or a permitted API-key user. Store the one-time privateKey immediately in a secret manager scoped to tenant and webhook ID. Keep management credentials separate from receiver verification.

Instructions

1. Choose event-based or field-based delivery and list only the events, monitorFields, and postFields needed by the consumer.
2. Validate an HTTPS destination and use a non-production receiver for creation tests. Prepare secret storage before the create call.
3. Capture id and privateKey from the 201 response atomically; store the key once and ensure it never enters logs, tickets, fixtures, or source control.
4. Implement HMAC-SHA256 over the exact raw request bytes according to BambooHR's current webhook documentation. Do not parse or reserialize before checking. Confirm the documented signature carrier/header from current docs or a controlled sample; this pack does not invent one.
5. Compare signatures in constant time, reject before processing, then enforce tenant routing, payload schema, event allowlist, timestamp/replay window when supplied, and an idempotency key derived from stable delivery facts.
6. Acknowledge only after durable enqueue. Return intentional 4xx for terminal payload rejection and 5xx only when a later retry can succeed.
7. Monitor webhook logs, last-fired time, verification failures, duplicates, queue age, and dead letters. Rotate by creating and validating a replacement before removing the …