Plan a Linear Issue Against a Next.js Codebase

A plan run reads and does not write. The agent clones the repository into its own sandbox, reads the issue, then reads the code it touches. Take a feature request against the cart of a storefront like vercel/commerce: a quantity limit per line, a note on a line item, a discount code field. The agent starts at package.json, which pins next 15.6.0-canary.60 and react 19.0.0, uses pnpm with a pnpm-lock.yaml, and has no test runner: the test script runs prettier:check and nothing else. next.config.ts turns on the experimental ppr, inlineCss and useCache flags, so caching is explicit in the code rather than implied by fetch.

Then it follows the data. components/cart/actions.ts is a 'use server' module with five actions: addItem, removeItem, updateItemQuantity, redirectToCheckout and createCartAndSetCookie. Each one calls the Shopify client in lib/shopify, then calls updateTag with TAGS.cart from lib/constants so the cached cart is refetched. The client functions addToCart, removeFromCart and updateCart read the cartId cookie through cookies() from next/headers, and getCart is marked 'use cache: private' with cacheTag on the cart tag and a cacheLife of seconds. The GraphQL behind them lives in lib/shopify/mutations/cart.ts (addToCart, createCart, editCartItems, removeFromCart) and lib/shopify/queries/cart.ts. On the client, components/cart/cart-context.tsx keeps an optimistic copy with useOptimistic and a reducer that handles ADD_ITEM and UPDATE_ITEM with plus, minus and delete, and components/cart/modal.tsx creates the cart cookie on first open. A cart change therefore has four places to touch: the action, the client function and its mutation, the optimistic reducer, and the modal that renders the line.

It checks what verification exists before suggesting tests. There is no vitest, jest or playwright in the dependencies, and the repository has no workflow directory, so nothing runs on a pull request beyond what a reviewer runs by hand. The plan says so, and proposes the smallest check that would catch a regression: a unit test for the reducer in cart-context.tsx, which is pure and takes no network, and a type check with tsc, since typescript 5.8.2 is already present. Adding a runner is a decision for the author, so the plan lists it as an open question with the cost of each option rather than deciding it.

The plan it posts names each file with the reason it changes, the tests to add and the file each belongs in, the risks, and the questions only the issue's author can answer. Risks the code makes plain: getCart is cached per request with a seconds lifetime, so a change that reads the cart right after a mutation has to call updateTag or it shows stale lines; the optimistic reducer recomputes line and cart totals itself, so a new pricing rule has to be mirrored there or the modal flickers; and the Shopify Storefront API decides what a line can carry, so a note or attribute needs the matching GraphQL field.

What comes back is the plan as the run's answer: the session read returns it as result, and a run started by the Linear state trigger posts it as a comment on the issue. It is organised as the prompt asks. A file list with one reason per file, for a cart change typically components/cart/actions.ts, lib/shopify/index.ts, one file under lib/shopify/mutations or queries, lib/shopify/types.ts, components/cart/cart-context.tsx and components/cart/modal.tsx. A test list that says what can be tested without a network and what needs a Shopify store. Then risks and open questions.

The questions are where a plan earns its keep. For a cart change they include whether the rule is enforced in the action or only in the UI, whether the optimistic state should refuse the change or show it and roll back, whether to add a test runner to a repository that has none, and whether the Storefront API version in lib/constants, which the code pins to 2023-01, supports the field the issue needs. The issue's author answers those on the issue before anyone writes code.

Nothing is pushed and no branch is created. The session's record keeps every file the agent opened and every command it ran, so a reader can check a claim like 'getCart is cached with a seconds lifetime' against the line the agent actually read.

Add an automation to the Project with a linear trigger on linear.issue.state_changed and map a state, such as Planning, to plan in its states. Moving an issue into that state starts a read-only run that posts its plan as a comment on the issue through the runner's Linear connection. Map a later state, such as Ready, to exec, and moving the issue on starts an ordinary run that builds it.

From your own server, the same plan comes from this request with the issue's URL in resources; read it from the session's result when the run.completed webhook arrives.

A plan is only as good as the code read behind it. On Rush the agent reads the real repository in its own sandbox, can run pnpm install and tsc to see what the types allow today, and every file and command is kept on the session, so the plan's claims can be checked rather than trusted.

Planning stops waiting on whoever last touched the cart. Every issue moved into the planning state gets its own run at the same time, the plans land on the issues where the team already discusses work, and the people who know the store answer the open questions before the build starts.

Can a plan run change my code?

The repository has no tests. What does the plan say about testing?

Does it need my Shopify store to plan?

What if the issue is too vague to plan?