Attio Contract Gate for CI

Overview

This skill turns an Attio integration change into deterministic pull-request evidence. It separates offline contract tests from an explicitly enabled read-only API smoke test.

Prerequisites

• A named repository and existing test runner
• Sanitized Attio response fixtures or generated contract fixtures
• A separately scoped CI credential only if a live smoke test is approved
• The endpoint's current required scopes and pagination contract

Tool Discipline

Use Read, Glob, and Grep to inspect workflows, fixtures, client code, and secret names. Use WebFetch only for current official Attio documentation. Use Write or Edit only after identifying the target files, constraints, and verification plan.

Current Contract

• Test the https://api.attio.com/v2 response envelope and application-owned normalization separately.
• Treat pagination as endpoint-specific: some endpoints use limit and offset; others return pagination.next_cursor.
• Keep mutation tests offline unless a dedicated disposable workspace and cleanup plan are approved.
• Never expose an access token in logs, snapshots, test names, or artifacts.

Authentication

Use a single-workspace access token for one controlled workspace or OAuth for a multi-workspace app. Grant only the endpoint scopes required by the smoke test and pass the token through the CI secret store as a Bearer credential.

Instructions

1. Inspect the changed endpoints, request methods, scopes, and response shapes.
2. Add fixture tests for success, structured Attio errors, pagination termination, and retry classification.
3. Validate that snapshots redact tokens, record values, webhook secrets, and personal data.
4. Add a disabled-by-default live job that performs only an approved read request such as listing objects.
5. Require explicit environment configuration before that job runs; skip it cleanly on forks.
6. Record the exact test command, fixture revision, and live-smoke disposition in the PR evidence.

Approval Boundaries

Do not create, update, or delete records from ordinary PR CI. A mutation smoke test requires a named disposable workspace, bounded fixtures, cleanup verification, and repository-owner approval.

Output

Return the endpoint contract matrix, fixture coverage, redaction result, workflow change, local command result, and live-smoke status.

Error Handling

Attio Error Triage

Overview

This skill classifies an Attio failure before changing code or credentials. It preserves the response's structured fields while keeping tokens and CRM values out of diagnostics.

Prerequisites

• The HTTP method, path template, status, and redacted response body
• The endpoint's documented required scopes
• The request's pagination mode and mutation semantics
• A correlation or application request identifier when available

Tool Discipline

Use Read, Glob, and Grep to locate the caller, response parser, retry policy, and logs. Use WebFetch only for current official Attio documentation. Use Write or Edit only after the failing contract and safe verification path are known.

Current Contract

Attio error responses can include status_code, type, code, and message. Diagnose from observed fields instead of inventing a fixed code list; endpoint references remain authoritative for request shape and scopes.

Authentication

Confirm that a Bearer token exists at runtime and belongs to the intended workspace. For 401, rotate or replace the invalid credential; for 403, compare granted scopes with the endpoint's required scopes before requesting any change.

Instructions

1. Capture method, path template, status, response content type, and redacted structured error fields.
2. Reconcile the request with the exact endpoint reference, including path slug versus UUID and body envelope.
3. Classify authentication, authorization, validation, uniqueness, not-found, throttling, or provider failure.
4. For 429, parse Retry-After as an HTTP date and retry only after the indicated time.
5. For ambiguous 5xx failures, preserve a minimal reproduction and check Attio status before changing business logic.
6. Apply the smallest correction and repeat the same bounded request.

Approval Boundaries

Do not broaden scopes, rotate a shared production credential, replay an ambiguous mutation, or expose customer payloads while troubleshooting without the responsible owner and a recovery plan.

Decision Table

Attio Record Lifecycle

Overview

This skill builds a record workflow from the workspace's actual object and attribute schema. It favors deterministic identity and reversible updates over blind create calls.

Prerequisites

• A named object slug or UUID and the target workspace
• Current attribute definitions for that object
• A stable matching attribute for assert or deduplication
• An approved write and deletion boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the local data model, mapping code, tests, and request wrapper. Use WebFetch only for current official Attio documentation. Use Write or Edit after the object contract and approval boundary are explicit.

Current Contract

• Objects define attributes; records are instances of an object.
• Record values are shaped by each attribute type, not by one universal scalar rule.
• Query records with POST /v2/objects/:object/records/query; this endpoint uses limit and offset.
• Choose create versus assert deliberately. Assert is appropriate only when a documented matching attribute supplies stable identity.
• PUT and PATCH have different multiselect behavior; confirm the endpoint reference before updating.

Authentication

Send a single-workspace or OAuth access token as Authorization: Bearer <access_token>. Confirm the endpoint's object-configuration and record-permission scopes before any write.

Instructions

1. Resolve the object and fetch its current attribute definitions.
2. Map source fields to exact attribute slugs and value shapes; reject unknown mappings.
3. Choose query, create, or assert based on the integration's identity policy.
4. For updates, state whether multiselect values must be overwritten or appended and select the documented method.
5. Persist the Attio record ID and source identity mapping after a successful write.
6. Read the record back and compare only the fields owned by this integration.
7. Require explicit approval before deletion and verify the exact record identity afterward.

Approval Boundaries

Never infer a destructive target from a display name. Record deletion, bulk writes, schema changes, and overwrite updates require the exact workspace, object, record IDs, and owner approval.

Output

Return the schema snapshot, identity rule, request plan, redacted response evidence, read-after-write comparison, and rollback or cleanup status.

Error Handling

Attio Lists and Entries Workflow

Overview

This skill models a business process without confusing an Attio record with its membership in a list. It makes ownership of record attributes and entry attributes explicit.

Prerequisites

• A named list slug or UUID and its permitted parent object
• Current list attribute definitions
• Stable parent record IDs
• Required list-entry, note, or task scopes for the selected workflow

Tool Discipline

Use Read, Glob, and Grep to inspect process rules, identifiers, mappings, and tests. Use WebFetch only for current official Attio documentation. Use Write or Edit after the list contract and mutation boundary are confirmed.

Current Contract

• A list entry points to one parent record and carries list-specific values.
• Removing an entry from a list is not the same as deleting its parent record.
• Entry query and pagination rules come from the exact endpoint reference.
• Notes and tasks are separate resources; do not store their content in list attributes as a shortcut.

Authentication

Use Bearer authentication with only the read or read-write scopes needed for list configuration, entries, notes, tasks, and parent records. Resolve 403 responses from endpoint scope documentation.

Instructions

1. Resolve the list and confirm its parent object and attribute definitions.
2. Query existing entries to determine whether the parent record is already present.
3. Add the parent record only when membership does not exist; persist the returned entry ID.
4. Update only integration-owned entry attributes using the endpoint's documented update semantics.
5. Create notes or tasks only when they are part of the approved workflow and link them to exact records.
6. Read the entry back and verify parent identity, owned values, and process state.
7. For removal, delete only the entry unless parent-record deletion is separately approved.

Approval Boundaries

Bulk entry changes, task assignment, destructive removal, and any parent-record deletion require a preview of exact IDs and impact. Never treat a list slug as sufficient proof of record identity.

Output

Return the list schema, parent-object check, membership decision, changed values, linked-resource IDs, verification result, and cleanup disposition.

Error Handling

Attio Workload Cost Review

Overview

This skill optimizes application-controlled workload rather than guessing at plan prices. It converts observed traffic and synchronization behavior into a ranked change proposal.

Prerequisites

• A representative measurement window and environment
• Request counts grouped by endpoint, method, status, and caller
• Query shapes, pagination behavior, and retry counts
• Current account terms for any commercial decision

Tool Discipline

Use Read, Glob, and Grep to locate polling loops, duplicate writes, query construction, caches, and telemetry. Use WebFetch only for current official Attio documentation. Use Write or Edit after a measured baseline and rollback plan exist.

Current Contract

• Do not encode fixed prices, entitlements, or savings claims in code or durable guidance.
• Read and write requests have different published rate-limit tiers; record and entry queries can also incur score-based limits.
• A lower request count is not automatically better if it increases query complexity or stale-data risk.
• Webhooks can replace some polling, but delivery is at least once and requires deduplication.

Authentication

Use the existing least-privilege Bearer credential for observation. Cost analysis never requires broader scopes than the workload already uses.

Instructions

1. Establish request volume, retry amplification, polling frequency, and duplicate-write baseline.
2. Identify calls that fetch unused fields, repeat stable discovery, or write unchanged values.
3. Separate offset/cursor traversal costs by endpoint and inspect expensive record or entry filters.
4. Model candidate changes: cached schema discovery, change detection, bounded concurrency, webhook-assisted sync, or shorter retention.
5. Quantify impact with ranges and state freshness, reliability, and complexity tradeoffs.
6. Implement one reversible change and compare it with the same measurement window.

Approval Boundaries

Do not change commercial plans, delete retained data, reduce audit history, or replace polling with webhooks without owner review of reliability and recovery behavior.

Output

Return baseline metrics, top cost or load drivers, ranked proposals, assumptions, selected change, rollback trigger, and post-change comparison.

Error Handling

Redacted Attio Diagnostic Bundle

Overview

This skill collects the smallest evidence needed to reproduce or escalate an Attio API problem. Redaction and content review happen before a bundle is written or shared.

Prerequisites

• A named incident, repository, and failing operation
• Redaction rules for tokens, webhook secrets, IDs, and personal data
• The exact endpoint reference and expected request shape
• An approved destination for the final bundle

Tool Discipline

Use Read, Glob, and Grep to inspect configuration names, client code, existing logs, and tests without opening secret files unnecessarily. Use WebFetch only for current official Attio documentation. Use Write or Edit only for a reviewed redacted artifact in the approved path.

Current Contract

• Collect path templates, not customer-bearing URLs.
• Preserve status, content type, documented error fields, retry timing, and pagination mode.
• Record scope names but never token values.
• Do not dump entire records, attribute values, environment variables, headers, or webhook payloads.

Authentication

If a bounded reproduction is approved, use the existing Bearer credential in process memory. The bundle may state credential type, workspace alias, and granted scopes; it must not contain the credential or reusable signature material.

Instructions

1. Define the incident question and minimum evidence fields before collection.
2. Inventory the local caller, endpoint path template, method, timeout, retry policy, and pagination mode.
3. Capture one redacted failure fingerprint and one bounded control request if safe.
4. Add object or list schema identifiers only when needed to explain validation behavior.
5. Scan the candidate bundle for token patterns, authorization headers, webhook secrets, record values, emails, phone numbers, and full IDs.
6. Review the redacted output manually, then write the approved bundle and checksum.

Approval Boundaries

Do not run broad workspace enumeration for diagnostics, collect raw CRM responses, or transmit a bundle until its exact contents and destination are reviewed.

Output

Return a bundle manifest, redaction report, request fingerprint, observed-versus-expected contract, reproduction result, checksum, and sharing disposition.

Error Handling

Attio Integration Rollout

Overview

This skill releases application code that calls Attio's REST API. It uses progressive evidence so a bad schema mapping, scope, or retry policy is caught before broad CRM mutation.

Prerequisites

• A versioned application artifact and tested configuration
• Environment-specific Attio workspace and secret references
• A disposable canary record or approved read-only smoke path
• Defined rollback owner, trigger, and previous artifact

Tool Discipline

Use Read, Glob, and Grep to inspect deployment manifests, secret names, health checks, migrations, and rollback commands. Use WebFetch only for current official Attio documentation. Use Write or Edit after the rollout target and approval boundary are confirmed.

Current Contract

• Inject tokens from the deployment platform; never bake them into images or manifests.
• Validate object and list schemas in the target workspace before enabling writes.
• Keep read and write traffic controls separate because Attio publishes different limit tiers.
• A successful process health check is not proof that CRM mutations are correct.

Authentication

Use the target environment's least-privilege single-workspace token or tenant-specific OAuth token. Confirm workspace identity and required endpoint scopes before canary traffic.

Instructions

1. Compare artifact, configuration, secret references, workspace alias, and endpoint set with the approved release record.
2. Run offline contract and redaction tests on the exact artifact.
3. Deploy with Attio writes disabled and perform a bounded read-only smoke request.
4. Confirm current object/list attributes and pagination behavior in the target workspace.
5. Enable one idempotent or reversible canary write, then read it back.
6. Expand traffic gradually while watching 4xx, 429, 5xx, latency, duplicate writes, and queue age.
7. Roll back on a declared trigger and verify both application and CRM state.

Approval Boundaries

Production writes, token rotation, schema changes, and cleanup of canary data require exact target display and owner approval. Do not roll forward through unexplained validation or authorization failures.

Output

Return artifact identity, environment checks, read smoke, canary evidence, traffic stage, observed metrics, rollback status, and residual risks.

Error Handling

Attio Verified First Read

Overview

This skill proves authentication, workspace reachability, JSON parsing, and object discovery with one read-only request. It does not create a demonstration contact in a real CRM.

Prerequisites

• A named repository and non-production or approved workspace
• A single-workspace access token or OAuth access token
• The object_configuration:read scope required by the object-list endpoint
• A runtime with HTTPS and JSON support

Tool Discipline

Use Read, Glob, and Grep to inspect the local client, environment-variable names, and tests. Use WebFetch only for current official Attio documentation. Use Write or Edit after confirming the repository and intended implementation file.

Current Contract

• Base URL: https://api.attio.com/v2.
• Send Authorization: Bearer <access_token>; Bearer authentication is the recommended form.
• Start with GET /v2/objects and validate a { data: [...] } response.
• Keep the credential out of source, output, exceptions, and request logging.

Authentication

Use a workspace API key for a single workspace or OAuth for an app serving multiple workspaces. Do not request write scopes for this proof.

Instructions

1. Confirm the repository, runtime, workspace alias, secret source, and granted scope.
2. Add or inspect a tiny request wrapper with explicit base URL and Bearer header injection.
3. Request /objects with a bounded timeout and capture status plus content type.
4. On success, parse data and record only object slugs or counts that are safe to expose.
5. Assert that at least one expected object is visible to the workspace.
6. Add a fixture test for success plus 401, 403, and non-JSON failure handling.

Approval Boundaries

Do not add create, update, assert, or delete calls to the first-read proof. Never print the access token or persist a raw workspace response.

Output

Return the redacted configuration, status, response-envelope assertion, safe object summary, fixture-test result, and next integration boundary.

Error Handling

Examples

Input:

workspa…

Attio Authentication Setup

Overview

This skill selects the correct Attio access-token path, maps endpoint scopes, and proves the credential with a non-mutating request.

Prerequisites

• The integration's workspace and tenancy model
• Exact endpoints and operations the application will use
• An approved secret store and rotation owner
• Registered redirect URIs when OAuth is required

Tool Discipline

Use Read, Glob, and Grep to inspect the local auth wrapper, secret names, redirect configuration, and endpoint use. Use WebFetch only for current official Attio documentation. Use Write or Edit after the auth model and target files are confirmed.

Current Contract

• Prefer OAuth 2.0 for an app that serves multiple Attio workspaces.
• Use a manually generated workspace API key for one controlled workspace.
• Both credential types can be sent as Authorization: Bearer <access_token>.
• Required scopes are documented per endpoint and should be granted operation by operation.
• Attio also supports Basic authentication with the token as username and an empty password, but Bearer is recommended.

Authentication

For OAuth, validate state, use the registered redirect URI exactly, exchange the code server-side, and encrypt the resulting token at rest. For a workspace key, create it in developer settings with the minimum scopes and store it only in the approved secret manager.

Instructions

1. Classify the integration as single-workspace or multi-workspace.
2. Inventory methods and endpoints, then derive scopes from their current reference pages.
3. Define secret storage, tenant-to-token mapping, rotation, revocation, and audit ownership.
4. Implement server-side credential injection without token logging.
5. For OAuth, bind and verify state; never expose the client secret to browser code.
6. Verify with one read-only endpoint and record only status, workspace alias, and granted scope names.

Approval Boundaries

Do not generate or broaden production credentials, modify redirect URIs, or migrate tenant tokens without the owning administrator's approval and a rollback plan.

Output

Return the chosen auth model, endpoint-to-scope map, secret reference, OAuth control evidence if applicable, read-only verification, and rotation owner.

Error Handling

Attio Local Development Loop

Overview

This skill makes local iteration fast without turning a shared CRM into a test fixture. Offline contracts are the default; live writes are explicit and disposable.

Prerequisites

• A named repository and test runner
• Sanitized success and error fixtures
• A development Attio workspace or approved test boundary
• A cleanup ledger for any live records or entries

Tool Discipline

Use Read, Glob, and Grep to inspect environment loading, client boundaries, fixtures, and tests. Use WebFetch only for current official Attio documentation. Use Write or Edit after confirming the repository path and test-data policy.

Current Contract

• Keep offline request/response contracts separate from live integration tests.
• Never copy production CRM payloads into fixtures.
• Guard live mutation behind an explicit switch and exact workspace allowlist.
• Pagination fixtures must match the selected endpoint's offset or cursor contract.

Authentication

Use a least-privilege development workspace token from local secret injection. Do not place the token in a committed environment file, fixture, command transcript, or snapshot.

Instructions

1. Locate the Attio client boundary, mappings, retry policy, and existing fixture conventions.
2. Define sanitized fixtures for success, validation failure, authorization failure, throttling, and pagination termination.
3. Add a local configuration guard that identifies the workspace and disables writes by default.
4. Run the smallest offline test while editing mappings or response normalization.
5. When live behavior is necessary, display the workspace and disposable target before enabling one bounded operation.
6. Record created resource IDs in the cleanup ledger, clean them up after review, and verify absence.

Approval Boundaries

Live writes, schema changes, bulk operations, and cleanup deletes require an approved non-production target. If workspace identity cannot be proved, remain offline.

Output

Return the fixture matrix, local commands, workspace guard, offline results, live-test disposition, created-resource ledger, and cleanup evidence.

Error Handling

Examples

Input:

Attio Query and Sync Performance

Overview

This skill tunes observed bottlenecks without promising a universal latency target. It keeps query complexity, rate limits, freshness, and mutation safety visible.

Prerequisites

• Latency distributions by endpoint and operation
• Queue depth, concurrency, retry, and 429 metrics
• Representative query filters, sorts, and object or list sizes
• A correctness baseline for synchronized fields

Tool Discipline

Use Read, Glob, and Grep to inspect query construction, pagination, concurrency, caches, and telemetry. Use WebFetch only for current official Attio documentation. Use Write or Edit after a measured hypothesis and rollback threshold are stated.

Current Contract

• Attio publishes separate global limits for reads and writes and score-based limits for record and entry queries.
• Complex filters and sorts can increase query score; raw request concurrency is not the only load variable.
• Pagination may be offset-based or cursor-based depending on the endpoint.
• Cache object and attribute discovery only with an explicit freshness and invalidation policy.

Authentication

Use the workload's existing least-privilege Bearer token. Performance measurement does not justify additional scopes or access to broader CRM data.

Instructions

1. Measure p50, p95, failure rate, 429 rate, queue age, and retry amplification for a representative window.
2. Segment by endpoint, method, filter/sort shape, page size, and workspace.
3. Verify that each paginator terminates according to its endpoint contract and does not refetch pages.
4. Rank hypotheses such as simpler filters, lower concurrency, bounded caching, change detection, or webhook-assisted work.
5. Change one variable, retain correctness assertions, and compare with the same workload.
6. Roll back when error rate, stale-data risk, or queue age crosses the declared threshold.

Approval Boundaries

Do not trade away correctness, auditability, or data freshness for latency without owner approval. Do not raise concurrency merely because the published global ceiling is higher.

Output

Return baseline metrics, segmented bottleneck evidence, the selected hypothesis and change, correctness checks, comparable after-metrics, and the explicit rollback decision.

Error Handling

Attio Production Readiness Review

Overview

This skill produces a release decision from repository and operational evidence. A checked box without a receipt is unresolved, not complete.

Prerequisites

• Exact artifact, environment, workspace, and release owner
• Endpoint inventory with methods and required scopes
• Data ownership, retention, and deletion policy
• Monitoring, incident, rollback, and support paths

Tool Discipline

Use Read, Glob, and Grep to inspect auth, mappings, tests, workflows, observability, and rollback code. Use WebFetch only for current official Attio documentation. Use Write or Edit only to remediate a named gap with verification.

Current Contract

• Authentication must match the tenancy model and use endpoint-derived least privilege.
• Record and entry identity, owned fields, and destructive boundaries must be explicit.
• Retries must honor Retry-After and exclude permanent request failures.
• Webhook receivers need raw-body HMAC verification and idempotent processing.
• Pagination mode must be confirmed endpoint by endpoint.

Authentication

Verify secret location, workspace or tenant binding, scopes, rotation owner, revocation procedure, and absence from logs and artifacts. Use Bearer authentication for REST requests.

Instructions

1. Bind the review to the exact artifact, environment, workspace, and endpoint inventory.
2. Verify contract tests, schema discovery, field ownership, identity, and pagination termination.
3. Verify credential storage, endpoint scopes, tenant isolation, rotation, and redaction.
4. Verify timeouts, bounded retries, read/write traffic controls, and 429 handling.
5. For webhooks, verify HTTPS, raw-body signature checks, idempotency keys, quick acknowledgement, and replay-safe workers.
6. Exercise read-only smoke, approved canary, alert path, rollback, and recovery evidence.
7. Record PASS, FAIL, or explicitly accepted risk for every item and name the approver.

Approval Boundaries

Only the release owner may accept unresolved data-loss, authorization, privacy, or rollback risk. Do not convert missing evidence into PASS.

Output

Return the bound release identity, control matrix with receipts, failed gates, accepted risks, approvers, and final GO or NO-GO decision.

Error Handling

Attio Rate-Limit Governor

Overview

This skill turns Attio's current published limits into a conservative client policy without treating the documented ceilings as reserved capacity.

Prerequisites

• Request metrics split by workspace, method, and endpoint
• Queue depth, retry count, and 429 response samples
• The endpoint-specific pagination and query contract
• An agreed maximum retry age and failure budget

Tool Discipline

Use Read, Glob, and Grep to inspect concurrency, queues, retries, and pagination. Use WebFetch only to recheck current official Attio limits and response semantics. Use Write or Edit after the governor policy and rollback threshold are explicit.

Current Contract

• Attio currently publishes global ceilings of 100 read requests per second and 25 write requests per second.
• Record and entry query endpoints also use a score budget over a 10-second window; complex filters and sorts consume more score.
• A 429 response can include Retry-After as an HTTP date, so do not assume an integer delay.
• Limits can change and are shared with other workspace traffic; reverify the official guide before rollout.

Authentication

Keep the existing least-privilege Bearer token and partition governor state by workspace credential. Never expose tokens in rate-limit telemetry.

Instructions

1. Inventory calls by read, write, workspace, endpoint, and query shape.
2. Reverify the official limits and endpoint-specific query scoring.
3. Implement separate conservative read and write token buckets below the published ceilings.
4. Add per-workspace queues, bounded concurrency, jitter, and backpressure.
5. On 429, parse Retry-After as an HTTP date when present; otherwise use capped exponential backoff.
6. Retry only idempotent or explicitly idempotency-protected work and only for 429 or eligible transient 5xx responses.
7. Load-test below production limits and record throughput, tail latency, queue age, and retry amplification.

Approval Boundaries

Do not increase concurrency, replay non-idempotent writes, or drop queued work without the service owner's approval and a rollback plan.

Output

Return verified limits, queue partitions, bucket settings, retry eligibility, maximum retry age, load-test evidence, and rollback thresholds.

Error Handling

Attio Integration Reference Architecture

Overview

This skill produces a repo-grounded architecture for reliable Attio reads, writes, and events. It treats tenant isolation, duplicate delivery, schema evolution, and reconciliation as first-class controls.

Prerequisites

• Workspace and tenancy model
• Required objects, lists, attributes, records, entries, and events
• Availability, freshness, recovery, and retention objectives
• Owners for credentials, queues, data mapping, and incident response

Tool Discipline

Use Read, Glob, and Grep to map components, trust boundaries, state, and existing clients. Use WebFetch only for current official Attio contracts. Use Write or Edit after the architecture, ownership, and approval boundaries are agreed.

Current Contract

• Use OAuth for multi-workspace applications and a workspace key only for a controlled single-workspace integration.
• Discover object and attribute identifiers rather than hard-coding display labels.
• Pagination differs by endpoint, and record or entry queries can carry score-based rate cost.
• Webhooks are at-least-once signals; durable processing needs signature verification, idempotency, a queue, and reconciliation.

Authentication

Place a tenant credential resolver behind a server-side interface. Bind each encrypted token to one workspace identity and exact scopes; never accept a workspace identifier from a caller without authorization.

Instructions

1. Map ingress, egress, data stores, trust boundaries, tenant context, and failure domains from the repository.
2. Define a credential resolver and auditable endpoint-to-scope map.
3. Add a bounded schema registry or cache with explicit refresh and invalidation.
4. Route outbound mutations through idempotent jobs with separate read and write governors.
5. Terminate webhooks at an HTTPS receiver that verifies the raw body, deduplicates by idempotency key, acknowledges quickly, and queues work.
6. Add replay, dead-letter handling, periodic reconciliation, and operator-visible lag metrics.
7. Specify deployment order, canary cohort, rollback, recovery exercise, and component owners.

Approval Boundaries

Do not broaden data collection, scopes, retention, tenant access, or mutation authority without approval from the relevant data and service owners.

Output

Return a component-and-data-flow design, trust boundaries, endpoint contracts, failure controls, ownership matrix, rollout sequence, and rollback plan.

Error Handling

Attio Typed Client Patterns

Overview

This skill designs a small REST client around the endpoints an application actually uses. It does not conflate a server-side REST wrapper with Attio's attio App SDK for in-product apps.

Prerequisites

• Runtime, package manager, and existing HTTP conventions
• Exact endpoints, methods, scopes, and response shapes
• Tenancy and credential model
• Existing tests and error-handling policy

Tool Discipline

Use Read, Glob, and Grep to inspect clients, types, dependency policy, and tests. Use WebFetch only for official Attio REST, OpenAPI, and App SDK documentation. Use Write or Edit after the target abstraction and endpoint contracts are confirmed.

Current Contract

• Attio REST requests use the https://api.attio.com/v2 base URL and endpoint-specific scopes.
• Pagination is endpoint-specific: some operations use limit and offset, while others return a cursor such as pagination.next_cursor.
• The Attio App SDK package attio serves apps running inside Attio and is not a universal REST client replacement.
• Generated types can start from the official OpenAPI document, but application-level validation and tests still own runtime safety.

Authentication

Inject a token provider that resolves the authorized workspace at request time. Do not place a global production token in source, client constructors, snapshots, fixtures, or logs.

Instructions

1. Inventory call sites and group the smallest useful endpoint surface.
2. Reverify each method, path, scope, body, response, and paginator in official documentation.
3. Define typed request and response boundaries with runtime validation for external data.
4. Centralize base URL, authorization, timeouts, redaction, request IDs, and structured error translation.
5. Implement separate offset and cursor iterators; bind each endpoint explicitly to the correct strategy.
6. Retry only eligible transient failures, respecting rate limits and mutation idempotency.
7. Add fixture, pagination-termination, error, redaction, and tenant-isolation tests.

Approval Boundaries

Do not replace an established client, add a generated dependency, or migrate production call sites without owner approval and compatibility evidence.

Output

Return the endpoint inventory, client interface, pagination mapping, error taxonomy, auth boundary, test evidence, migration plan, and rollback point.

Error Handling

Attio Integration Security Baseline

Overview

This skill audits and hardens Attio authentication, data handling, webhook verification, tenant boundaries, and operational response without exposing secrets or customer records.

Prerequisites

• Data-flow and trust-boundary inventory
• Endpoint-to-scope map and tenant model
• Secret-store, logging, retention, and incident-response owners
• Webhook receiver code when events are enabled

Tool Discipline

Use Read, Glob, and Grep to inspect credential flow, authorization, logs, storage, and webhook handling. Use WebFetch only for current official Attio security contracts. Use Write or Edit after findings, target controls, and rollback conditions are approved.

Current Contract

• Tokens should be least-privilege, stored server-side, tenant-bound, redacted, and rotatable.
• Verify Attio-Signature by computing SHA-256 HMAC over the exact raw UTF-8 request body with the webhook secret and comparing equal-length hexadecimal values in constant time.
• The signature input is the raw body only; do not invent a timestamp concatenation protocol.
• Delivery is at least once. Use Idempotency-Key and durable state to control duplicates; signature verification alone is not deduplication.

Authentication

Prefer OAuth for multi-workspace applications and a workspace key for a controlled single workspace. Enforce server-side workspace authorization before resolving the encrypted token.

Instructions

1. Map secrets, tenant context, Attio data, logs, queues, backups, and administrative paths.
2. Compare used endpoints with granted scopes and remove unjustified privilege through an approved rotation.
3. Enforce tenant authorization before credential resolution and storage access.
4. Redact authorization headers, secrets, raw customer payloads, and sensitive attribute values from telemetry.
5. Preserve the raw webhook body, verify its HMAC before parsing, compare equal-length buffers safely, and reject failures.
6. Deduplicate accepted events by Idempotency-Key, queue work, and reconcile downstream state.
7. Exercise token revocation, webhook-secret rotation, audit review, and incident rollback.

Approval Boundaries

Do not rotate production secrets, reduce retention, change access scopes, or replay customer mutations without the responsible security and service owners.

Output

Return the threat boundaries, scope gaps, secret lifecycle, webhook verification evidence, redaction tests, tenant-isolation tests, and remediation owners.

Error Handling

Attio Contract Migration

Overview

This skill migrates the integration that actually exists. It does not assume a generic historical version jump; it proves every affected endpoint and data shape against current Attio contracts.

Prerequisites

• Current integration commit, dependencies, and deployment topology
• Endpoint, scope, pagination, data-shape, and webhook inventory
• Representative redacted fixtures and reconciliation queries
• Canary cohort, rollback owner, and recovery objective

Tool Discipline

Use Read, Glob, and Grep to inventory current assumptions and tests. Use WebFetch only for current official Attio documentation and OpenAPI. Use Write or Edit after the contract diff, rollout boundary, and rollback point are documented.

Current Contract

• Validate method, path, scopes, request fields, response fields, value shapes, and pagination per endpoint.
• Treat official OpenAPI as an input to the diff, not a substitute for behavioral fixtures and endpoint documentation.
• Record and entry queries may use offset pagination and score-based rate accounting; other endpoints can expose cursors.
• Webhook changes must preserve raw-body signature verification and at-least-once idempotency.

Authentication

Preserve tenant-to-token binding and least privilege throughout the migration. Any new scope requires explicit justification, administrator approval, and a reversible credential plan.

Instructions

1. Freeze a baseline of call sites, dependencies, contracts, fixtures, metrics, and current production behavior.
2. Diff each affected endpoint against official documentation and OpenAPI.
3. Classify changes as compatible, additive, behavior-sensitive, or breaking.
4. Add compatibility adapters and tests for pagination, value shapes, errors, idempotency, and redaction.
5. Run shadow reads or dry-run comparisons and reconcile mismatches without customer-facing mutations.
6. Canary one bounded workspace or workload with explicit health and rollback thresholds.
7. Expand in stages, retain rollback until reconciliation passes, then remove obsolete paths deliberately.

Approval Boundaries

Do not add scopes, alter destructive mutations, switch all tenants, or remove the rollback path without owner approval and recorded evidence.

Output

Return the before-and-after contract matrix, risk classification, adapter plan, test evidence, shadow or canary results, reconciliation status, and rollback decision.

Error Handling

Attio Webhook Receiver

Overview

This skill implements the complete event-delivery boundary: authenticate the exact payload, acknowledge within Attio's delivery window, process at least once safely, and reconcile missed or delayed effects.

Prerequisites

• Public HTTPS receiver and approved webhook secret storage
• Required event types and downstream ownership
• Durable queue and idempotency store
• Replay, dead-letter, and reconciliation procedures

Tool Discipline

Use Read, Glob, and Grep to inspect raw-body middleware, route handling, queues, and deduplication. Use WebFetch only for current official Attio webhook documentation. Use Write or Edit after the event contract and failure policy are confirmed.

Current Contract

• Read Attio-Signature; legacy deliveries may also expose X-Attio-Signature.
• Compute SHA-256 HMAC over the exact raw UTF-8 request body using the webhook secret and compare hexadecimal signatures safely.
• Return a 2xx quickly after validation and durable acceptance; Attio documents a 5-second timeout.
• Delivery is at least once. Use Idempotency-Key for deduplication.
• Attio documents up to 10 retries over roughly three days and a delivery limit of 25 requests per second per target URL; reverify before rollout.

Authentication

Store the webhook secret server-side. Verify the signature before JSON parsing, logging, queueing, or any state change, and support controlled secret rotation.

Instructions

1. Capture the raw request bytes before body-parsing middleware transforms them.
2. Read the supported signature header, decode the expected hex, and reject malformed or unequal-length values.
3. Compute raw-body HMAC and use a timing-safe equal-length comparison.
4. Validate the event envelope and reserve Idempotency-Key transactionally.
5. Persist the event to a durable queue, then return 2xx within the timeout.
6. Process idempotently with bounded concurrency, explicit dead-letter handling, and redacted telemetry.
7. Test valid, invalid, duplicate, reordered, delayed, burst, queue-failure, and secret-rotation cases.
8. Reconcile authoritative Attio state so a missed event cannot create permanent drift.

Approval Boundaries

Do not create production subscriptions, rotate secrets, replay events, or mutate downstream customer state without the responsible owner and rollback controls.

Output

Return the subscription scope, signature evidence, acknowledgement path, idempotency design, queue behavior, failure tests, reconciliation procedure, and owners.

Error Handling