What the agent does
The agent reads the monorepo's own rules before writing a line, because a Medusa project has a fixed shape and a linter that enforces it. In a store like medusajs/dtc-starter, the root package.json pins pnpm@10.11.1, Turbo runs build, lint and test, and AGENTS.md says what goes where: routes under apps/backend/src/api/{store,admin}/<path>/route.ts, business logic in apps/backend/src/workflows/, a custom data model under apps/backend/src/modules/<name>/, links under src/links/, and admin pages under src/admin/. The backend depends on @medusajs/medusa 2.22.2, @medusajs/admin-sdk, @medusajs/ui 4.2.9 and zod 4.2.0, medusa-config.ts registers no custom modules yet, and src/api/middlewares.ts already calls defineMiddlewares with one entry that applies configureStoreSearch to POST /store/search. The jest.config.js selects suites by TEST_TYPE, integration:http matching integration-tests/http/*.spec.ts, and AGENTS.md warns those suites need a reachable PostgreSQL. The storefront is Next.js 16 with React 19; its product page is apps/storefront/src/modules/products/templates/index.tsx, which lays out ProductInfo, ProductTabs, VariantImageGallery, ProductActions and RelatedProducts, and its server calls live in apps/storefront/src/lib/data/, where products.ts wraps sdk with getAuthHeaders and getCacheOptions.
The backend follows the shape Medusa's own product-reviews tutorial lays out, which the agent reads alongside the installed package's AGENTS.md. A new module at src/modules/product-review/ defines a review model with model.define: title nullable text, content text, rating as a float with a rating_range check between 1 and 5, first_name and last_name, a status enum of pending, approved and rejected defaulting to pending, an indexed product_id and a nullable customer_id. service.ts extends MedusaService({ Review }) and adds a getAverageRating query, index.ts exports PRODUCT_REVIEW_MODULE as productReview, and medusa-config.ts gains modules: [{ resolve: "./src/modules/product-review" }]. A read-only link in src/links/review-product.ts joins review.product_id to the Product Module's product, so query.graph can load a product's reviews. pnpm exec medusa db:generate productReview writes the migration, the one step AGENTS.md says people forget.
Then the workflows and routes. createReviewWorkflow confirms the product exists with useQueryGraphStep, then runs a createReviewStep whose compensation deletes the review; updateReviewWorkflow changes status with a step that restores the old statuses on failure. POST /store/reviews runs the first and GET /store/products/[id]/reviews returns approved reviews with the average; GET /admin/reviews lists with createFindParams() and POST /admin/reviews/status takes ids and a status. In middlewares.ts the agent adds entries beside the existing search one: authenticate("customer", ["session", "bearer"]) and validateAndTransformBody with a Zod schema whose rating is min(1).max(5) on the store POST, validateAndTransformBody on the admin POST and validateAndTransformQuery on the two GETs. A UI route at src/admin/routes/reviews/page.tsx, registered with defineRouteConfig, shows a DataTable from @medusajs/ui with row selection and Approve and Reject commands calling the status route. The code keeps the repository's style: no semicolons, double quotes, kebab-case files, and nothing imported from @medusajs/utils directly.
The storefront gets getProductReviews and addProductReview in lib/data/products.ts, a product-reviews component with the average, the list and a load-more button, a form shown only to a logged-in customer, and one line in the product template rendering the component under the related products. For proof the agent writes apps/backend/integration-tests/http/reviews.spec.ts with medusaIntegrationTestRunner from @medusajs/test-utils: a customer posts a review and reads it back as pending, the store list hides it, the admin approves it, the store list shows it with the average. It installs PostgreSQL in its sandbox, points DATABASE_URL at it, runs pnpm run test:integration:http from apps/backend, then pnpm run lint there, which runs medusa lint with the @medusajs/eslint-plugin rules, pnpm run build for both apps, and opens the product page in its browser against the running backend.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add product reviews to this Medusa store. Read the root package.json and AGENTS.md, apps/backend/medusa-config.ts, apps/backend/src/api/middlewares.ts, the READMEs under apps/backend/src, apps/backend/jest.config.js, the AGENTS.md shipped in node_modules/@medusajs/framework after pnpm install, and the storefront's product template and lib/data/products.ts first. Add a product-review module with a review model (nullable title, content, rating 1 to 5, first and last name, status pending/approved/rejected, indexed product_id, nullable customer_id), register it in medusa-config.ts, add a read-only link to the product, and generate its migration. Add create and update-status workflows with compensation, the routes POST /store/reviews, GET /store/products/:id/reviews (approved only, with the average rating), GET /admin/reviews and POST /admin/reviews/status, with Zod validation and customer authentication in middlewares.ts. Add an admin UI route listing reviews with approve and reject actions, and a storefront reviews section with a form for logged-in customers on the product page. Write an HTTP integration test covering post, moderation and listing, run it against a local PostgreSQL, run lint and build for both apps, and open a pull request with the output.",
"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 the module directory with its generated migration, the link file, two workflows with their steps, four route files, the admin page, the storefront component, form and data functions, and the integration spec, and changes medusa-config.ts, middlewares.ts and the product template. Its description quotes the Jest output for the new spec, the medusa lint result and both builds, and shows the product page with a review and the admin table from the run's record.
A reviewer reads the model and the migration together, since a column is the one thing that is hard to change after deploy, then the middleware entries, which decide who may post and what a payload must contain. Running pnpm exec medusa db:migrate on a staging database and posting one review through the storefront is the last check before merge; the test already did the same against a fresh database.
Run it on every Linear issue labelled storefront
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the storefront label. When an issue such as "customers should be able to rate products" gets the label, the trigger puts the issue after the prompt, and the run reads what fields and moderation the issue asks for before it defines the model. Only label changes by a person in your Rush org fire it, and the automation starts at most max_runs_per_hour runs in an hour.
An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to POST /o/{org}/sessions with the issue URL in resources and a request_id that is a UUID v5 of the issue id, so a redelivered event returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A review feature crosses every layer of a Medusa project: a model and migration, a link, workflows, routes with validation, an admin page and a storefront section, and the framework's linter rejects code that skips its conventions. The agent reads the project's AGENTS.md and the installed package's own notes, follows them, and runs the integration suite against a real PostgreSQL in its own sandbox, with every command and its output kept in the run's record.
The part a laptop rarely finishes is the proof: a database, a migration, a running backend, a test that posts and moderates a review, and a browser on the product page. The agent does all of it before opening the pull request, so the reviewer reads a change that has already been exercised end to end.
Frequently asked questions
Can anyone post a review?
No. middlewares.ts applies authenticate("customer", ["session", "bearer"]) to POST /store/reviews, so only a logged-in customer can post, and the route takes customer_id from the authenticated actor rather than the body. The storefront shows the form only when a customer is signed in.
Do reviews appear immediately?
No. A new review is pending, the store listing returns only approved ones, and an admin approves or rejects from the Reviews page or POST /admin/reviews/status. Change the model's default to approved if you want no moderation; the migration and the tests follow.
Does the test need a database?
Yes. medusaIntegrationTestRunner creates a fresh database per suite on a PostgreSQL it reaches through DATABASE_URL, which is why the agent installs one in its sandbox. The pull request names the environment variables the suite reads so CI can do the same.
Why workflows instead of calling the service from the route?
The project's AGENTS.md puts business logic in workflows, and the framework's lint rules expect it. A workflow step carries a compensation, so a failed create leaves no half-written review, and the same workflow can later be run from a subscriber or a scheduled job.
What if the storefront directory does not exist?
The starter's storefront is optional, and the project's AGENTS.md says to check before assuming it. The agent then ships the backend, the admin page and the test, and the pull request says the store routes are ready for whichever storefront you run.