# Work SDK — Agent Guide

Work SDK is an open-source TypeScript library for safely reading and writing GitHub Issues, GitLab issues, Linear issues, Jira work items, and Azure DevOps work items. It is not a hosted API. The application supplies provider credentials, and requests go directly to the selected tracker.

## Use Work SDK when

- A coding agent must create, update, comment on, or transition work items.
- Application code needs to support multiple trackers without provider conditionals at every call site.
- A side effect should be inspectable before it is committed.
- Duplicate-risk must be coordinated across workers and uncertain outcomes must stop blind retries.
- A write must fail if an item changed after it was inspected.

## Safe write rules

1. Call `prepareCreate`, `prepareUpdate`, or `prepareComment`.
2. Inspect every entry in `change.changes` and `change.warnings`.
3. Require human approval when the application policy calls for it. The SDK does not replace approval.
4. Never mutate a prepared change. Its fingerprint protects the reviewed plan.
5. Commit externally visible writes with a stable `idempotencyKey`.
6. On `WorkConflictError`, re-read and prepare a new change. Do not force the stale write.
7. Check `work.capabilities` before exposing provider-dependent actions.
8. On `WorkAmbiguousCommitError`, reconcile provider state before any retry.

## Credentials

Keep GitHub and GitLab tokens, Linear API keys, Jira API tokens, Azure DevOps Entra/PAT tokens, and all other credentials in environment variables. Never include them in prompts, prepared-change logs, error reports, or source control.

## Provider imports

- `work-sdk/github`
- `work-sdk/gitlab`
- `work-sdk/linear`
- `work-sdk/jira`
- `work-sdk/azure-devops`

## Error classes

- `WorkAuthenticationError`
- `WorkAuthorizationError`
- `WorkNotFoundError`
- `WorkRateLimitError`
- `WorkConflictError`
- `WorkInFlightError`
- `WorkAmbiguousCommitError`
- `WorkUnsupportedError`
- `WorkValidationError`

Read the complete documentation at https://work-sdk.vercel.app/docs.