What the agent does
The agent reads the endpoint from the route to the repository. In an app laid out like slimphp/Slim-Skeleton, app/routes.php mounts ListUsersAction at GET /users inside a /users group, next to ViewUserAction at /{id}. src/Application/Actions/User/ListUsersAction.php is four lines of work: it calls $this->userRepository->findAll(), logs "Users list was viewed." and returns respondWithData($users), which the base Action class wraps in an ActionPayload of statusCode and data and serialises with JSON_PRETTY_PRINT. src/Domain/User/UserRepository.php is an interface with findAll(): array and findUserOfId(int $id): User, bound in app/repositories.php to InMemoryUserRepository, which holds five users keyed by id and returns array_values of them. The base Action already has resolveArg for route arguments and throws HttpBadRequestException for a missing one, but nothing reads query parameters. tests/Application/Actions/User/ListUserActionTest.php prophesies findAll() once and compares the whole JSON body to an expected ActionPayload.
The change starts at the interface, since the in-memory repository is the stand-in for a database one. UserRepository gains findPage(int $offset, int $limit): array and countAll(): int, with findAll() left in place because nothing else should break. InMemoryUserRepository implements them with array_slice over array_values($this->users) and count. ListUsersAction reads page and per_page from $this->request->getQueryParams(), defaulting to 1 and 20, and refuses anything that is not a positive integer, or a per_page above 100, with the same HttpBadRequestException the base class already uses, which HttpErrorHandler turns into the skeleton's JSON error shape with a 400. The response keeps statusCode and data and adds, inside data, items, page, perPage and total, so a client that read a bare array before has one key to change and a client that wants the next page can compute it.
The agent keeps the skeleton's conventions where they exist. declare(strict_types=1) stays at the top of every file, the new interface methods carry the same docblocks as the old ones, and the action's log line gains the page number. It does not add a pagination library: the skeleton has no database, and a LIMIT/OFFSET pair is the whole contract a database repository will need to implement later.
The check is the existing suite plus the cases the change creates. The agent updates ListUserActionTest to prophesy findPage(0, 20) and countAll(), adds tests for ?page=2&per_page=2 against the five default users, for page=0, per_page=abc and per_page=500 returning 400, and adds findPage cases to InMemoryUserRepositoryTest. It runs vendor/bin/phpunit, vendor/bin/phpcs against the PSR-12 ruleset in phpcs.xml, and vendor/bin/phpstan at the level 4 set in phpstan.neon.dist, the three commands .github/workflows/tests.yml runs, and quotes all three in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add pagination to the GET /users endpoint of this Slim 4 app. Read app/routes.php, src/Application/Actions/Action.php, src/Application/Actions/User/ListUsersAction.php, src/Domain/User/UserRepository.php, src/Infrastructure/Persistence/User/InMemoryUserRepository.php, src/Application/Handlers/HttpErrorHandler.php, the tests under tests/ and .github/workflows/tests.yml first. Add findPage(int $offset, int $limit): array and countAll(): int to the UserRepository interface and implement them in InMemoryUserRepository with array_slice and count, keeping findAll. In ListUsersAction read page and per_page from the query string with defaults 1 and 20, reject non-positive or non-integer values and per_page above 100 with HttpBadRequestException, and respond with data containing items, page, perPage and total. Update ListUserActionTest for the new repository calls, add tests for a second page and for each rejected value, and add findPage tests to InMemoryUserRepositoryTest. Run vendor/bin/phpunit, vendor/bin/phpcs and vendor/bin/phpstan and fix anything they report. Open a pull request that quotes all three outputs and shows the new response shape.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes UserRepository.php, InMemoryUserRepository.php, ListUsersAction.php, ListUserActionTest.php and InMemoryUserRepositoryTest.php, and touches no route, middleware or container wiring. Its description shows one response body for GET /users?page=2&per_page=2 with the items, page, perPage and total keys, one 400 body for per_page=abc, and the phpunit, phpcs and phpstan output.
A reviewer checks the defaults and the cap against what their clients send, confirms the error path returns the skeleton's ActionError shape rather than a bare message, and decides whether the old findAll() should stay on the interface. If the project has a database repository, the reviewer sees the two methods it must implement, with the in-memory version as the reference.
Clients get the same statusCode and data envelope, a bounded page of users under items, and enough in the response to build the next request without a second call.
Run it on every Linear issue labelled api-pagination
An automation on the Project with a linear trigger on linear.issue.labeled and the label api-pagination starts a read-only run that reads the issue and posts a plan as a comment on it: which action, which repository methods, which tests. The change itself starts from the reader's own server, which sends this body to POST /o/{org}/sessions with the issue's URL in resources beside the repository, so the issue text is in the prompt, and a request_id that is a UUID v5 of the issue id, so a retried call returns the run it already started.
Each run reads that app's own list action, so an endpoint backed by PDO gets LIMIT and OFFSET in its query and a COUNT(*) beside it, while one on an in-memory repository gets array_slice, with the same query parameters and the same response shape across the two.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Pagination touches an interface, its implementations, an action and the tests that pin its JSON byte for byte, and the skeleton's CI runs three tools that each reject a different kind of mistake. The agent makes the change and runs PHPUnit, PHP_CodeSniffer and PHPStan in its own sandbox with the project's own configuration, and keeps the output with the pull request, so the review is about the contract and not about whether the build passes.
List endpoints that return whole tables are usually found several at a time. The same request runs across every service at once, each in its own sandbox, each getting parameters and a response shape that match that service's conventions, and each with the proof that its own suite still passes.
Frequently asked questions
Does the response shape change for existing clients?
The envelope of statusCode and data stays. What was a bare array under data becomes an object with items, page, perPage and total, so a client reads data.items where it read data. The pull request shows one full body so the change is visible before merging.
Why extend the interface instead of slicing in the action?
Slicing in the action would work for the in-memory repository and load the whole table from a database one. findPage and countAll give a database implementation a LIMIT, an OFFSET and a COUNT to run, and the action stays the same whichever repository is bound in app/repositories.php.
What happens with page=0 or per_page=500?
Both get a 400 through the HttpBadRequestException the base Action already uses, which HttpErrorHandler renders in the skeleton's JSON error shape. The cap of 100 is a constant in the action and the pull request names it.
Will phpstan and phpcs still pass?
The agent runs both with the project's own phpstan.neon.dist and phpcs.xml, the same way .github/workflows/tests.yml does, and fixes what they report before opening the pull request. The output is quoted in the description.
More Slim jobs
The same job on other stacks
- Add Message History Pagination to a Socket.IO Chat (Socket.IO)
- Add Pagination to a Wagtail Blog Index (Wagtail)
- Add Pagination to an aiohttp App (aiohttp)