--- name: bamboohr-upgrade-migration-2d121d2b0dcb description: >- Migrate a BambooHR integration across SDK, OpenAPI, auth, dataset, or endpoint changes with pinned evidence, dual-read comparison, and rollback. Use when replacing legacy report/dataset calls or upgrading an official SDK. Trigger with "upgrade BambooHR", "BambooHR migration", or "BambooHR deprecated API". allowed-tools: Read,Glob,Grep,Write,Edit argument-hint: " " version: 1.5.0 license: MIT author: Jeremy Longshore tags: [saas, hr, bamboohr, migration, upgrade] model: inherit effort: high compatibility: Designed for Claude Code --- # 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, access a tenant, deploy, or delete legacy code. ## Approval Boundaries Require approval for dependency/source pins, auth changes, production dual-read, write canary, checkpoint conversion, cutover, rollback, and legacy removal. ## Output Return source/target evidence, contract diff, package provenance, compatibility matrix, dual-read reconciliation, canary metrics, checkpoint/rollback plan, cutover decision, and deprecated code remaining. ## Error Handling - Target package cannot be reproduced: stop and use a reviewed source pin or direct HTTP. - Semantic mismatch: quarantine the field/operation; do not normalize silently. - Ambiguous write during canary: read current state and halt further writes. ## Examples - "Upgrade to the Python SDK" first verifies the distribution or pins source. - "Move custom reports to datasets" produces a field-by-field dual-read migration. ## Resources Read [official evidence](references/official-docs.md) for migration authority. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/bamboohr-pack/skills/bamboohr-upgrade-migration/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/bamboohr-pack/skills/bamboohr-upgrade-migration/SKILL.md Attribution basis: Source repository record Fields of work: Human Resources, Operations Roles: Business Process Analyst, HR Analyst, HR Generalist Specialties: API Tools: Bamboohr Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 8a93a378e41ed2920a1eb84bf7cbeda5daed2514cc3123f2077a80e9c2663f49