How to Turn a Linear Issue Into an Agent Session

A Linear issue is rarely a complete implementation plan. It may have a title, a few acceptance criteria, a Figma link, and a comment from the person who found the bug. To turn a Linear issue into an agent session without creating a bad branch or a long cleanup task, the agent needs that context preserved, scoped, and connected to the right repository before it writes code.

This is not about replacing engineering judgment with a one-click prompt. It is about creating a governed execution path from ticket to diff, test result, pull request, and status update. The agent can move quickly. The team still decides what ships.

Turn a Linear issue into an agent session with real context

The first failure mode is deceptively simple: treating the issue body as the entire task. A ticket such as ENG-482: Add account lockout messaging sounds actionable, but it leaves important questions unanswered. Which service owns the lockout state? Is the copy defined in Figma? Does the API already expose the remaining retry count? Are there existing tests for the authentication flow? Is the intended change a hotfix or part of a broader security release?

A useful agent session starts by assembling the working context around the issue. That includes the issue title, description, labels, priority, acceptance criteria, comments, and linked artifacts. It should also identify the repository, default branch, relevant directory, and the coding agent that will do the work.

For ENG-482, the session might resolve to github.com/acme/auth-web, branch from main, pull a linked Figma frame, and include a Sentry event showing users receiving a generic 429 response after repeated failed logins. The resulting task is no longer "fix the login message." It is specific:

Update the lockout state in the React login flow. Display approved copy from the linked design when the API returns ACCOUNT_TEMPORARILY_LOCKED. Preserve generic handling for other 429 responses. Add coverage for both states.

That distinction matters. An agent with grounded context can investigate and implement. An agent with a vague ticket will make assumptions, and assumptions are where expensive review cycles begin.

Resolve the repository before starting work

Repository selection should be a system decision with a visible rationale, not a guess hidden inside an agent prompt. Linear teams often use one workspace for frontend, backend, infrastructure, documentation, and mobile repositories. The project name alone may not be enough.

Use the strongest signals first: an explicitly linked repository, a project-to-repository mapping, recent issue history, component labels, and referenced paths or services. If the issue is labeled web-auth, the target is likely the web repository. If it references a GraphQL mutation or a Go package, that is stronger evidence than a generic project label.

When the match is uncertain, stop for confirmation. Starting an agent in the wrong repository is not a minor inconvenience. It produces noisy commits, wastes review time, and can create false confidence because checks still pass in a codebase unrelated to the requested change.

Convert acceptance criteria into an execution brief

Acceptance criteria should become explicit agent instructions, not background text the agent may or may not prioritize. Separate the work into desired behavior, non-goals, constraints, and proof.

For example, ENG-482 might require the lockout message to appear only for the named API error, use product-approved language, remain accessible to screen readers, and include unit coverage. It might explicitly exclude changing the lockout duration or adding rate limiting. The proof is a passing test suite, a visual review against the linked design, and a pull request that identifies the error-state behavior.

This structure constrains the task without prescribing every edit. That is the useful division of labor: people define intent and boundaries; the agent performs the investigation and implementation work within them.

Start the agent with a bounded first move

The first agent instruction should not be "implement this." Ask it to inspect the codebase, locate the likely implementation surface, identify relevant tests, and report its plan before making broad changes. For a contained bug fix, that planning stage may take only a few minutes. For a cross-service issue, it can prevent hours of work in the wrong layer.

A strong initial request might read:

Investigate ENG-482 in auth-web. Find where login API errors are mapped to UI states, inspect existing authentication tests, and propose the smallest change that meets the acceptance criteria. Do not modify API contracts or lockout policy.

The agent's response should reference actual files and behavior, such as src/features/auth/LoginForm.tsx, src/features/auth/errorMap.ts, and LoginForm.test.tsx. If it cannot identify the relevant path, that is useful signal. Redirect it before it writes a patch.

This is where a continuous control layer changes the workflow. CodeAgent Mobile can create a context-rich session from the Linear issue, retain the source artifacts and execution history, and keep the task available after you leave the desktop. Nothing needs to be re-explained when a staff engineer reviews the plan from a phone or a teammate resumes the work later.

Review diffs while the task is still cheap to change

Once the agent begins implementation, the session should expose progress as real engineering evidence: files changed, commands run, test output, commits created, and unresolved questions. Status text such as "working on it" is not enough.

Suppose the agent reports that the API does not emit ACCOUNT_TEMPORARILY_LOCKED consistently. It found a legacy 429 response in one path and the named error in another. That is a decision point, not a prompt to keep coding blindly. You can redirect the session: support only the named error in this pull request, document the inconsistency in the Linear issue, and create a follow-up for API normalization.

That is what supervision looks like in practice. Approve a narrow change. Reject a scope expansion. Ask for one more test. Redirect the agent to a different approach before it has rewritten a shared component.

The trade-off is deliberate. More checkpoints add a small amount of latency. They also reduce the probability that an autonomous agent turns a two-file ticket into a 30-file refactor that reviewers cannot safely evaluate. For routine, well-tested changes, teams can allow more autonomy. For authentication, billing, authorization, migrations, or customer data, keep the approval gates tight.

Use checks as the handoff contract

A passing diff is not automatically a shippable change. The agent session should run the checks appropriate to the repository: targeted unit tests, type checks, linting, formatting, integration tests, and build validation where the change warrants it.

Require the session to surface failures plainly. If pnpm test LoginForm passes but the full type check fails because a response union changed, the failure belongs in the review record. The next person should not need to reconstruct what happened from terminal scrollback or an incomplete agent summary.

The pull request should also preserve the connection to ENG-482. A reviewer needs to see the original requirement, the implementation rationale, files changed, checks run, and any intentional limitation. The ticket needs the inverse: a clear status update with the PR number, current check state, and the decision that remains pending.

Keep control when you are away from the desk

Long-running agent work has an awkward timing problem. An agent may finish its plan during a meeting, hit a test failure while you are commuting, or ask a legitimate question after the original developer has signed off. If the workflow lives only inside one terminal session, work stalls or context disappears.

A persistent session lets the team approve, redirect, pause, resume, or end work from whichever device is available. That does not mean approving production code from a lock screen. It means keeping the operational thread intact: the Linear issue, repository, branch, agent transcript, diffs, checks, and review decisions remain attached to the job.

This matters most at handoff. A developer can start investigation in the afternoon, an engineering lead can approve the narrowed plan after dinner, and another developer can review the completed PR the next morning without asking, "What did the agent already try?" The answer is in the session history.

Close the loop back to Linear

The final update should be useful to the person who opened the issue and to the engineer who will touch the code next quarter. Avoid vague status changes like "done" or "agent completed task." Record what changed and what proved it.

For ENG-482, the update could state that the login UI now renders the approved temporary-lockout message for ACCOUNT_TEMPORARILY_LOCKED, generic 429 handling remains unchanged, targeted tests and type checks passed, and PR #1842 is ready for review. If API response inconsistency was discovered, record the follow-up issue rather than burying it in a comment.

That closed loop is the point. A Linear issue becomes an accountable agent session, not a detached prompt. The work keeps its context, the team keeps control, and every handoff leaves proof behind for the next decision.