Skip to content

reactive/data-client / .agents/skills/data-client-rest-setup

data-client-rest-setup

Verified

Set up and migrate to @data-client/rest for REST APIs. Detects existing HTTP patterns (axios, fetch, ky, superagent, got) and migrates them. Creates custom RestEndpoint base class with common behaviors. Use when adopting @data-client/rest in a new or existing project.

references/axios-migration.md

View on GitHub
<!-- Generated by `yarn build:skills` from docs/rest/guides/axios-migration.md (react). Edit the source doc, not this file. -->

# Migrating from Axios

[`@data-client/rest`](https://dataclient.io/rest) replaces axios calls with typed endpoint definitions. Components still call them directly,
so how the app loads and stores data doesn't change; only the call shape does. A [codemod](#codemod) converts the calls; the
[steps](#steps) below cover the rest.

## Why migrate?

The URL is declared once: path parameters are typed and encoded from the `path` template, and the rest become the query string. Calls don't change.

```ts title="Before"
const getComments = ({
  userId,
  postId,
  sort,
}: {
  userId: string;
  postId: string;
  sort?: 'newest' | 'top';
}) =>
  // callout: Each parameter is typed, encoded and placed by hand, and nothing checks the template against the type.
  axios.get(
    `/users/${encodeURIComponent(userId)}/posts/${encodeURIComponent(postId)}/comments`,
    { params: { sort } },
  );

getComments({ userId: user.id, postId: post.id, sort: 'newest' });
```

```ts title="After"
const getComments = new RestEndpoint({
  // callout: `userId` and `postId` are typed and encoded from the template, so a missing or misspelled one is a compile error.
  path: '/users/:userId/posts/:postId/comments',
  searchParams: {} as { sort?: 'newest' | 'top' },
});

getComments({ userId: user.id, postId: post.id, sort: 'newest' });
```

- **Typed end to end**: path parameters, bodies and responses are typed from each definition.
- **Less code**: [`resource()`](./resource.md) makes a full CRUD API from a `path` and a `schema`.
- **One place for request behavior**: a base endpoint's methods replace interceptors and per-call config.
- **Ready for the store**: the same endpoints and schemas work with [`useSuspense()`](https://dataclient.io/docs/api/useSuspense) and the
  normalized cache, whenever you adopt them.

## Migrate step by step {#steps}

### 1. Install {#install}

```bash
npm install @data-client/rest
```

### 2. Run the codemod {#codemod}

A [jscodeshift](https://github.com/facebook/jscodeshift) codemod does the mechanical part. Commit first, then run it on
your source folders, never the repo root:

```bash
npx @data-client/codemods axios-to-rest src/
```

The codemod doesn't format what it writes. Afterward, run the formatter or lint fixer your project uses on the changed
files, such as `prettier --write`, `eslint --fix` or `biome check --write`.

Each axios call becomes a call to an endpoint, built once at module level. Path params, `params` and the body become its arguments, and it resolves to the body, so `.data` goes away.

```ts title="Before"
import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });

export async function getPost(id: string) {
  const res = await api.get(`/posts/${id}`);
  return res.data;
}

export async function createPost(body: { title: string }) {
  const { data } = await api.post('/posts', body);
  return data;
}
```

```ts title="After"
import { RestEndpoint, RestGenerics } from '@data-client/rest';

class ApiEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
  urlPrefix = 'https://api.example.com';
}

const getPostEndpoint = new ApiEndpoint({ path: '/posts/:id' });

const createPostEndpoint = new ApiEndpoint({
  path: '/posts',
  method: 'POST',
});

export async function getPost(id: string) {
  const res = await getPostEndpoint({ id });
  return res;
}

export async function createPost(body: { title: string }) {
  const data = await createPostEndpoint(body);
  return data;
}
```

What it can't convert, such as interceptors, `timeout`, `isAxiosError()` or a function that returns the axios
response to its callers, gets a `// TODO(data-client):` comment linking the section below that covers it. Search for
`TODO(data-client)` and resolve each one as you go through the next steps.

Endpoints the codemod moves to module level are built when their module loads. It keeps them in their function when
the module that defines the base class imports their file, but it can't see a longer import cycle. If one exists, that
import runs first and fails with `Cannot access 'ApiEndpoint' before initialization`. Break the import cycle, or move
those endpoints into the module that defines the base class.

If the project wraps axios in its own class or function and never calls `axios.get()` or `.post()` directly, or only
calls `axios(config)`, the codemod has little to do. Skip it and start at [step 3](#base-endpoint).

### 3. Move interceptors into a base endpoint {#base-endpoint}

Axios interceptors and instance config become methods on one `RestEndpoint` subclass that every endpoint extends. The
codemod creates this class from `axios.create()`. It comments out the module's `api.interceptors` and `api.defaults`
setup, since `api` no longer exists, and marks each with a `TODO(data-client)`; move each into the class.

`RestEndpoint` parses JSON itself, so an interceptor that only unwraps `response.data` has nothing left to do.

```ts title="Before"
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com',
  headers: { 'X-API-Key': 'my-key' },
});

api.interceptors.request.use(config => {
  config.headers.Authorization = `Bearer ${getToken()}`;
  return config;
});

api.interceptors.response.use(response => response.data);

export default api;
```

```ts title="After"
import { RestEndpoint, RestGenerics } from '@data-client/rest';

export default class ApiEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  urlPrefix = 'https://api.example.com';

  // callout: Runs before every request, like a request interceptor. It can be `async`, to refresh a token first.
  getHeaders(headers: HeadersInit) {
    return {
      ...headers,
      'X-API-Key': 'my-key',
      Authorization: `Bearer ${getToken()}`,
    };
  }
}
```

Response interceptors that change the body, such as unwrapping `{ data }` or converting `snake_case` keys, go in
[`process()`](./RestEndpoint.md#process); see [snakes to camels](https://dataclient.io/rest/guides/network-transform#snakes-to-camels).

When a response interceptor returned `response.data`, a caller's `.data` read a field of the body, not axios's response,
so keep it. The codemod marks these calls when the interceptor is in the same file; if a global
`axios.interceptors.response` lives in another file, check the `.data` it removed from calls there.

#### Server error messages

Axios codebases often show the user `error.response.data.error` or `.message`. Read it from the `Response` body once,
in the base class's [`fetchResponse()`](./RestEndpoint.md#fetchResponse), so call sites get it from
`error.message`:

```ts title="ApiEndpoint.ts"
import {
  NetworkError,
  RestEndpoint,
  RestGenerics,
} from '@data-client/rest';

export default class ApiEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  async fetchResponse(input: RequestInfo, init: RequestInit) {
    try {
      return await super.fetchResponse(input, init);
    } catch (error) {
      if (error instanceof NetworkError) {
        const body = await error.response
          .clone()
          .json()
          .catch(() => null);
        // keep the NetworkError so `status` and `errorPolicy()` still work
        error.message = body?.error ?? body?.message ?? error.message;
      }
      throw error;
    }
  }
}
```

#### Existing endpoint abstractions

A custom endpoint class that wraps axios (say, one with `path`, `method` and a `toDynamicUrl()` helper) can extend
`RestEndpoint` instead of being replaced. It keeps its backward-compatible methods and gains
[`url()`](./RestEndpoint.md#url), [`getRequestInit()`](./RestEndpoint.md#getRequestInit),
[`fetchResponse()`](./RestEndpoint.md#fetchResponse) and [`parseResponse()`](./RestEndpoint.md#parseResponse):

```ts
import { RestEndpoint, RestGenerics } from '@data-client/rest';

export class LegacyEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  urlPrefix = API_ROOT;
  declare queryKey?: string;

  /** @deprecated use url() */
  toDynamicUrl = this.url;
}

const getUser = new LegacyEndpoint({
  path: '/users/:id',
  queryKey: 'user',
  schema: User,
});
```

Pass extra members like `queryKey` as options rather than through a custom constructor, so
[`extend()`](./RestEndpoint.md#extend) (used by `resource()`, `hookifyResource()` and `useCancelling()`) keeps
working.

#### Context-based auth

When tokens come from React context (Okta, Auth0) rather than storage, `getHeaders()` can't
read them. Use [`hookifyResource()`](./hookifyResource.md) to add the headers through a
hook. See the
[authentication guide](./auth.md) for this and other patterns.

### 4. Define entities and resources {#entities}

The codemod makes endpoints without a `schema`. Define an [Entity](https://dataclient.io/rest/api/Entity) for each type the API returns: its
fields, their types and its primary key. Replace each module's CRUD functions on one path with a
[`resource()`](./resource.md):

One `resource()` replaces a module of CRUD functions, and `schema` types every response.

```ts title="Before"
import api from './api';

export interface Post {
  id: string;
  title: string;
  body: string;
}

export const getPosts = () => api.get<Post[]>('/posts');
export const getPost = (id: string) => api.get<Post>(`/posts/${id}`);
export const createPost = (data: Omit<Post, 'id'>) =>
  api.post<Post>('/posts', data);
export const updatePost = (id: string, data: Partial<Post>) =>
  api.patch<Post>(`/posts/${id}`, data);
export const deletePost = (id: string) => api.delete(`/posts/${id}`);
```

```ts title="After"
import { Entity, resource } from '@data-client/rest';
import ApiEndpoint from './ApiEndpoint';

export class Post extends Entity {
  id = '';
  title = '';
  body = '';
  static key = 'Post';
}

// callout: Gives `getList`, `get`, `getList.push`, `update`, `partialUpdate` and `delete`, all typed.
export const PostResource = resource({
  path: '/posts/:id',
  schema: Post,
  Endpoint: ApiEndpoint,
});
```

Try the result against a mock API:

```ts title="Post"
import { Entity } from '@data-client/rest';

export default class Post extends Entity {
  id = '';
  title = '';
  body = '';
  static key = 'Post';
}
```

```ts title="ApiEndpoint"
import { RestEndpoint, RestGenerics } from '@data-client/rest';

export default class ApiEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  urlPrefix = 'https://api.example.com';

  getHeaders(headers: HeadersInit) {
    return {
      ...headers,
      'X-API-Key': 'my-key',
    };
  }
}
```

```ts title="PostResource"
import { resource } from '@data-client/rest';
import ApiEndpoint from './ApiEndpoint';
import Post from './Post';

export const PostResource = resource({
  path: '/posts/:id',
  schema: Post,
  Endpoint: ApiEndpoint,
});
```

```ts title="Usage" column
import { PostResource } from './PostResource';
PostResource.get({ id: '1' });
```

Nested paths like `/projects/:projectId/tasks/:taskId` get their own resource. Keep standalone `new ApiEndpoint()` for
operations that aren't CRUD, like search, custom actions and auth.

> **Warning**
>
> Don't define Entity classes and then leave `schema` unset on the endpoints: without `schema`, responses lose their
> types, and the store can't normalize them when you adopt it.

#### Non-standard primary keys

Many APIs (MongoDB, for example) use `_id` instead of `id`. Override [`pk()`](https://dataclient.io/rest/api/Entity#pk):

```ts
import { Entity } from '@data-client/rest';

export class User extends Entity {
  _id = '';
  name = '';
  email = '';
  static key = 'User';

  pk() {
    return this._id;
  }
}
```

#### Body typing

Type the body of standalone `POST`, `PUT` and `PATCH` endpoints with `body: {} as BodyType`. Don't use
`undefined as unknown as BodyType`: `RestEndpoint` treats [`body`](./RestEndpoint.md#body)`: undefined` as having
no body argument. [`resource()`](./resource.md) types its endpoints' bodies itself.

```ts
const createUser = new ApiEndpoint({
  path: '/users',
  method: 'POST',
  body: {} as { name: string; email: string },
  schema: User,
});
```

#### Coexisting with Zod or Yup

If the codebase already validates responses with Zod or Yup, choose one approach per type:

- **Zod in `process()`** (recommended): keep runtime validation by parsing in
  [`process()`](./RestEndpoint.md#process), and let the Entity handle normalization:

  ```ts
  const getUser = new ApiEndpoint({
    path: '/users/:id',
    schema: User,
    process(value: any) {
      return userSchema.parse(value);
    },
  });
  ```

- **Entity replaces Zod**: move the field shape into the Entity class and remove the Zod schema. Entity fields give
  types, not runtime checks, so add [`static validate()`](https://dataclient.io/rest/api/Entity#validate) for any fields the server might
  send malformed.

- **Zod only, no Entity**: leave `schema` unset and parse manually. Only do this for endpoints that don't gain from
  normalization (auth tokens, one-off responses).

### 5. Update call sites {#call-sites}

Components and services keep their own loading and state; only the call changes.

Endpoints resolve to the parsed body, so `.data` goes away, and parameters become one object.

```ts title="Before"
import { createPost, getPost, getPosts } from './api/posts';

const { data: posts } = await getPosts();
const { data: post } = await getPost('1');
const { data: created } = await createPost({ title: 'Hello', body: '' });
```

```ts title="After"
import { PostResource } from './api/posts';

const posts = await PostResource.getList();
const post = await PostResource.get({ id: '1' });
const created = await PostResource.getList.push({
  title: 'Hello',
  body: '',
});
```

Reading these endpoints through the store, with [`useSuspense()`](https://dataclient.io/docs/api/useSuspense) and the normalized cache, is a
separate step you can take later; see [data dependencies](https://dataclient.io/docs/getting-started/data-dependency).

### 6. Migrate error handling {#error-handling}

`NetworkError` has the `status` and the raw `Response`, in place of axios's `error.response`.

```ts title="Before"
import axios from 'axios';
import { getPost } from './api/posts';

try {
  const { data } = await getPost('1');
} catch (err) {
  if (axios.isAxiosError(err)) {
    console.log(err.response?.status);
    console.log(err.response?.data);
  }
}
```

```ts title="After"
import { NetworkError } from '@data-client/rest';
import { PostResource } from './api/posts';

try {
  const post = await PostResource.get({ id: '1' });
} catch (err) {
  if (err instanceof NetworkError) {
    console.log(err.status);
    console.log(err.response);
  }
}
```

Read a server's error message from the body once, in the base endpoint; see
[server error messages](#server-error-messages).

### 7. Remove axios {#remove-axios}

Search for what still uses axios:

| Pattern                                    | Finds                     |
| ------------------------------------------ | ------------------------- |
| `TODO\(data-client\)`                      | what the codemod left     |
| `import.*from ['"]axios['"]`               | import statements         |
| `axios\.create`                            | instance creation         |
| `axios\.(get\|post\|put\|patch\|delete)`   | direct calls              |
| `\.interceptors\.(request\|response)\.use` | interceptors              |
| `isAxiosError`                             | error handling            |
| `cancelToken\|CancelToken`                 | cancellation (deprecated) |
| `onUploadProgress\|onDownloadProgress`     | progress callbacks        |

Migrate each match with the [reference](#quick-reference) below. When none are left, uninstall axios, then run the
type checker and tests:

```bash
npm uninstall axios
```

## Axios options reference {#quick-reference}

| Axios                                    | @data-client/rest                                                                                           |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `baseURL`                                | [`urlPrefix`](./RestEndpoint.md#urlPrefix)                                                                  |
| `headers` config                         | [`getHeaders()`](./RestEndpoint.md#getHeaders)                                                              |
| `interceptors.request`                   | [`getHeaders()`](./RestEndpoint.md#getHeaders) / [`getRequestInit()`](./RestEndpoint.md#getRequestInit)     |
| `interceptors.response`                  | [`parseResponse()`](./RestEndpoint.md#parseResponse) / [`process()`](./RestEndpoint.md#process)             |
| `transformRequest`                       | [`getRequestInit()`](./RestEndpoint.md#getRequestInit)                                                      |
| `transformResponse`                      | [`process()`](./RestEndpoint.md#process)                                                                    |
| `isAxiosError` / `error.response`        | [`NetworkError`](#error-handling) with `.status` and `.response`                                            |
| `cancelToken` / `signal`                 | [`signal`](#cancellation)                                                                                   |
| `timeout`                                | [`AbortSignal.timeout()`](#timeout) in `getRequestInit()`                                                   |
| `withCredentials: true`                  | [`credentials: 'include'`](./auth.md#cookie-auth-credentials) in `getRequestInit()`                         |
| `responseType: 'blob'` / `'arraybuffer'` | [`content: 'blob'`](#binary-responses) / `'arrayBuffer'`                                                    |
| `params` / `paramsSerializer`            | [`searchParams`](./RestEndpoint.md#searchParams) / [`searchToString()`](#query-serialization)               |
| `data` in a `delete()` config            | [`body`](./RestEndpoint.md#body) on the endpoint: a `DELETE` sends a body only when it has one (rest 0.19+) |
| `auth: { username, password }`           | [`getHeaders()` with `btoa()`](#basic-auth)                                                                 |
| `validateStatus`                         | [Custom `fetchResponse()`](#accepting-error-statuses)                                                       |
| `xsrfCookieName` / `xsrfHeaderName`      | [`getHeaders()`](#csrf-headers)                                                                             |
| `onUploadProgress`                       | [Custom `fetchResponse()` with XMLHttpRequest](#upload-progress)                                            |

### Cancellation

Both axios's `signal` and the deprecated `CancelToken` map to an
[AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) `signal`:

```ts title="Before"
const source = axios.CancelToken.source();
axios.get('/users/1', { cancelToken: source.token });
source.cancel();
```

```ts title="After"
const getUser = new ApiEndpoint({ path: '/users/:id' });
const controller = new AbortController();
// callout: `extend()` gives this one request its own signal; a `signal` set when the endpoint is created would abort all of its requests.
getUser.extend({ signal: controller.signal })({ id: '1' });
controller.abort();
```

See the [abort guide](https://dataclient.io/rest/guides/abort) for more patterns.

### Timeout

```ts title="Before"
axios.get('/users', { timeout: 5000 });
```

```ts title="After"
export default class ApiEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  // callout: Runs for each request, so each one gets its own 5 seconds. `AbortSignal.timeout()` passed to the constructor would start counting once, when the endpoint is created.
  async getRequestInit(
    body?: RequestInit['body'] | Record<string, unknown>,
  ) {
    const init = await super.getRequestInit(body);
    const timeout = AbortSignal.timeout(5000);
    // callout: Keeps `extend({ signal })` cancellation working: either signal aborts the request.
    const signal = init.signal
      ? AbortSignal.any([init.signal, timeout])
      : timeout;
    return { ...init, signal };
  }
}
```

### Binary responses

```ts title="Before"
axios.get('/files/1', { responseType: 'blob' });
```

```ts title="After"
const downloadFile = new RestEndpoint({
  path: '/files/:id',
  content: 'blob',
});
```

[`content`](./RestEndpoint.md#content) also takes `'arrayBuffer'` and `'text'`. See
[file download](https://dataclient.io/rest/guides/network-transform#file-download) to trigger a browser download.

### Query serialization

```ts title="Before"
axios.get('/users', {
  params: { ids: [1, 2, 3] },
  paramsSerializer: params =>
    qs.stringify(params, { arrayFormat: 'repeat' }),
});
```

```ts title="After"
export default class ApiEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  searchToString(searchParams: Record<string, any>) {
    return qs.stringify(searchParams, {
      arrayFormat: 'repeat',
      skipNulls: true,
    });
  }
}
```

axios leaves out `null` and `undefined` params, but the default `searchToString()` uses
[URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams), which sends them as the strings
`"null"` and `"undefined"`; `skipNulls` above drops them. See [`searchToString()`](./RestEndpoint.md#searchToString).

### Basic auth

```ts title="Before"
axios.get('/api', { auth: { username: 'user', password: 'pass' } });
```

```ts title="After"
export default class BasicAuthEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  getHeaders(headers: HeadersInit) {
    return {
      ...headers,
      Authorization: `Basic ${btoa('user:pass')}`,
    };
  }
}
```

### Accepting error statuses

[`fetchResponse()`](./RestEndpoint.md#fetchResponse) throws [`NetworkError`](#error-handling) for any status that
isn't `ok`. Override it to change what counts as an error:

```ts title="Before"
axios.get('/api', { validateStatus: status => status < 500 });
```

```ts title="After"
import {
  NetworkError,
  RestEndpoint,
  RestGenerics,
} from '@data-client/rest';

export default class LenientEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  async fetchResponse(input: RequestInfo, init: RequestInit) {
    const response = await fetch(input, init);
    if (response.status >= 500) throw new NetworkError(response);
    return response;
  }
}
```

### CSRF headers

```ts title="Before"
axios.create({
  xsrfCookieName: 'csrftoken',
  xsrfHeaderName: 'X-CSRFToken',
});
```

Read the cookie in [`getHeaders()`](./RestEndpoint.md#getHeaders) for requests that aren't `GET`. See
[Django Integration](./django.md) for the complete endpoint class.

### Upload progress

`fetch` can't report upload progress, so use
[XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) inside
[`fetchResponse()`](./RestEndpoint.md#fetchResponse). The `onProgress` field is passed as an endpoint option, like
any other member.

```ts title="Before"
axios.post('/upload', formData, {
  onUploadProgress: e => console.log(e.loaded / e.total),
});
```

```ts title="UploadEndpoint.ts"
import {
  NetworkError,
  RestEndpoint,
  RestGenerics,
} from '@data-client/rest';

export default class UploadEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  declare onProgress?: (progress: number) => void;

  fetchResponse(input: RequestInfo, init: RequestInit) {
    return new Promise<Response>((resolve, reject) => {
      const xhr = new XMLHttpRequest();
      const abort = () => xhr.abort();
      const abortError = () =>
        new DOMException('The operation was aborted.', 'AbortError');
      if (init.signal?.aborted) return reject(abortError());
      init.signal?.addEventListener('abort', abort, { once: true });

      xhr.open(
        init.method ?? 'POST',
        typeof input === 'string' ? input : input.url,
      );
      new Headers(init.headers).forEach((value, key) =>
        xhr.setRequestHeader(key, value),
      );
      xhr.onloadend = () =>
        init.signal?.removeEventListener('abort', abort);
      xhr.upload.onprogress = e => {
        if (e.lengthComputable) this.onProgress?.(e.loaded / e.total);
      };
      xhr.onload = () => {
        const headers = new Headers();
        for (const line of xhr
          .getAllResponseHeaders()
          .trim()
          .split(/\r?\n/)) {
          const [key, ...rest] = line.split(': ');
          if (key) headers.append(key, rest.join(': '));
        }
        // 204, 205 and 304 responses can't have a body
        const body = [204, 205, 304].includes(xhr.status)
          ? null
          : xhr.response;
        const response = new Response(body, {
          status: xhr.status,
          statusText: xhr.statusText,
          headers,
        });
        if (response.ok) resolve(response);
        else reject(new NetworkError(response));
      };
      xhr.onerror = () => reject(new TypeError('Network request failed'));
      xhr.onabort = () => reject(abortError());
      xhr.send(init.body as XMLHttpRequestBodyInit | null);
    });
  }
}

const uploadFile = new UploadEndpoint({
  path: '/upload',
  method: 'POST',
  body: {} as FormData,
  onProgress: (progress: number) => console.log(progress),
});
```

## Related guides

- [Authentication](./auth.md): token and cookie auth patterns
- [Aborting Fetch](https://dataclient.io/rest/guides/abort): cancellation and debouncing
- [Transforming data on fetch](https://dataclient.io/rest/guides/network-transform): response transforms, field renaming, file downloads
- [Django Integration](./django.md): CSRF and cookie auth for Django
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall