What the agent does
The agent reads the app and its conventions before it adds a route. In the hypermedia starter kit from adonisjs/starter-kits, package.json depends on @adonisjs/core ^7.5.2, @adonisjs/lucid ^22.4.2 with better-sqlite3, @adonisjs/auth, @adonisjs/session, @adonisjs/shield, @adonisjs/static, @adonisjs/vite, @vinejs/vine and edge.js, and its imports map #controllers/*, #validators/*, #models/* and #generated/* to their directories. adonisrc.ts registers an indexEntities() hook, which is why start/routes.ts points at controllers through the generated #generated/controllers registry, and declares unit, functional and browser test suites, though tests/ holds only bootstrap.ts. app/models/user.ts extends the generated UserSchema in database/schema.ts, a file written by node ace migration:run from the single migration that creates users with full_name, email and password. config/bodyparser.ts already processes multipart/form-data automatically with a 20mb limit. resources/views/components/avatar.edge renders an img when given src and initials otherwise, resources/views/components/layouts/settings.edge has an empty items list with a comment showing how to add a page, and .gitignore ignores tmp/*.
Storage goes through @adonisjs/drive, whose current release lists @adonisjs/core ^7.0.0 as a peer. node ace add @adonisjs/drive installs it, registers its provider in adonisrc.ts, writes config/drive.ts and adds DRIVE_DISK=fs to .env and .env.example; the agent sets the fs service to location: app.makePath('storage'), serveFiles: true, routeBasePath: '/uploads' and visibility: 'public', adds storage to .gitignore, and validates the new variable in start/env.ts. A migration adds a nullable avatar_key string column to users, and running it regenerates database/schema.ts so UserSchema gains the column without a hand edit.
The feature is a profile page in the settings area. app/validators/profile.ts defines avatarValidator with vine.file({ size: '2mb', extnames: ['jpg', 'jpeg', 'png', 'webp'] }), below the body parser's own limit so the validator's message is what a user sees. A ProfileController with show and updateAvatar is created with node ace make:controller so the registry picks it up; updateAvatar validates the request, builds a key from cuid() in @adonisjs/core/helpers and the file's extname, calls avatar.moveToDisk(key), deletes the previous key from the disk when there was one, saves the key on the user and redirects back with a flash message. start/routes.ts gets GET /settings/profile and POST /settings/profile/avatar inside the existing middleware.auth() group, the settings layout's items gets { label: 'Profile', route: 'settings.profile', icon: 'lucide:user' } as its comment suggests, and pages/settings/profile.edge renders the avatar component with src set through the driveUrl helper when a key exists and initials from the model's getter otherwise, above a form with enctype="multipart/form-data" and the kit's field, input and button components.
Tests use the functional suite. The agent adds @japa/api-client with the authApiClient and sessionApiClient plugins beside the browser client in tests/bootstrap.ts, writes tests/functional/profile.spec.ts that signs a user in with loginAs, posts a small PNG from tests/fixtures with the client's file helper, and asserts the redirect, the avatar_key on the reloaded user and that the key exists on the disk; a second test posts a text file and asserts the validation error, and a third posts without a session and asserts the guest redirect. Every test runs under using fakeDisk = drive.fake() so nothing touches storage/. It runs node ace migration:run, npm run lint, npm run typecheck and node ace test functional in its sandbox, and opens the pull request when all three pass.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add file uploads to this AdonisJS app as an avatar on a profile settings page and open a pull request. Read package.json, adonisrc.ts, start/routes.ts, start/kernel.ts, start/env.ts, config/bodyparser.ts, app/models/user.ts, database/schema.ts, database/migrations, app/validators/user.ts, app/controllers, resources/views/components/avatar.edge, resources/views/components/layouts/settings.edge, tests/bootstrap.ts and .gitignore first. Install @adonisjs/drive with node ace add, configure the fs disk under storage with serveFiles and an /uploads base path, validate DRIVE_DISK in start/env.ts and ignore storage in git. Add a migration for a nullable avatar_key on users and run it so the generated schema updates. Add a profile validator with vine.file limited to 2mb and image extensions, a ProfileController made with node ace make:controller whose updateAvatar validates, moves the file to the disk under a cuid key, deletes the old key, saves the user and redirects with a flash message, and routes under the auth group. Add the Profile entry to the settings layout and a profile page using the avatar component and driveUrl. Add @japa/api-client to tests/bootstrap.ts and functional tests on drive.fake() for a valid image, a rejected text file and a guest. Run node ace migration:run, npm run lint, npm run typecheck and node ace test until they pass, then open a pull request listing the routes, the config and what each test proves.",
"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 adds config/drive.ts, the migration, app/controllers/profile_controller.ts, app/validators/profile.ts, resources/views/pages/settings/profile.edge, tests/functional/profile.spec.ts and a small fixture image, and changes adonisrc.ts, package.json, pnpm-lock.yaml, .env.example, start/env.ts, start/routes.ts, database/schema.ts, .gitignore and the settings layout. Its description lists the two routes, shows the fs disk configuration, and quotes the lint, typecheck and test output from the sandbox.
It explains the choices a reviewer will ask about: the key is a cuid with the original extension rather than the client's file name, so a name is never a path; the old file is deleted after the new one is saved, so a failed upload leaves the previous avatar in place; and the public fs disk serves files from /uploads through the app, which the description says to swap for s3 or gcs in config/drive.ts when the app runs on more than one host.
Before merging, a reviewer decides whether a bucket disk should be configured now, whether the 2mb limit and the extension list match the product, and whether the avatar component should get a loading="lazy" attribute or a fixed size now that it renders real images.
Run it on every Linear issue labelled uploads
An automation on the Project with a linear trigger on linear.issue.labeled, uploads in config.labels, and the prompt "this issue names a form or model that should accept a file; add a validated upload field on the existing disk, store the key on the model, extend the functional tests on a fake disk, and open a pull request" starts one run per labelled issue once Drive is configured. The trigger adds the issue after the prompt and fills in nothing else, so an issue about attachments on a support ticket gets a key column on that model and a field on that form.
A team with several AdonisJS apps sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own kit: the api kit gets a JSON route and an api-client test instead of a page, and an app that already has Drive gets only the migration, the controller and the tests.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
An upload touches the body parser, a disk, a migration, a generated schema file, a validator, a view and the test harness, and each has a convention in this kit: controllers are registered through a generated index, the schema file is written by the migration command, settings pages are listed in a layout. The agent follows each one and proves the whole path with functional tests that post a real file in its sandbox, where it can run the migration against the kit's SQLite database and a fake disk without touching anyone's storage.
The migration output, the lint and typecheck runs and the test results stay with the run, so a reviewer sees the form accept an image and refuse a text file without starting the app. A team with several AdonisJS services sends the same request to all of them at once and reads one pull request per app.
Frequently asked questions
Where do the files go?
On the fs disk under storage/, which is ignored by git and served by the app at /uploads/<key> because serveFiles is on. config/drive.ts is where that becomes s3 or gcs; the controller calls moveToDisk and driveUrl and does not care which.
Why is the limit in the validator when the body parser has one?
The body parser's 20mb limit protects the server and answers with a bare error. The validator's 2mb limit is checked per field and reports through the same flash messages the signup form uses, so the user sees which file was too large and why. The validator limit must stay below the parser's or it never gets to run.
Does it edit the generated schema file by hand?
No. database/schema.ts says it is regenerated by node ace migration:run, so the agent writes a migration for avatar_key and runs it; the UserSchema class gains the column from the migration, and the User model needs no change.
How do the tests avoid writing to storage?
Each test runs under using fakeDisk = drive.fake(), which points the disk at a temporary directory for the test's lifetime and restores it after. The assertions check the key on the user and fakeDisk.assertExists for the file, so they prove the write happened without leaving a file behind.
More AdonisJS jobs
The same job on other stacks
- Add File Uploads to a CodeIgniter 4 App (CodeIgniter)
- Add File Uploads to a Livewire Component (Livewire)
- Add File Uploads to a React Router App (React Router)