How it works

From a triggered ticket to a reviewed pull request, and everything the agent does in between.

Sinatra works like a teammate you hand a ticket to. You trigger it, it investigates and writes code, it opens a pull request, and it responds when you leave review feedback. This page walks through that loop.

Triggering the agent

From Linear:

Assign an issue to Sinatra.
@-mention it in a comment on the issue.

From GitHub:

Add the sinatra label to an issue. Sinatra provisions this label on the repos you enable.
Comment on an issue from an account with write access to the repo.

You do not need Linear. Sinatra runs the full loop on a GitHub issue alone, opens a PR that closes the issue on merge, and posts its updates on the issue. Connect Linear if you want the agent to live in your Linear workflow instead.

Once triggered, the agent reacts with 👀 so you know it picked the work up.

The phases

A workstream moves through a series of phases. Most tickets skip straight to implementation; the planning phases are opt-in.

Investigating. Sinatra reads the ticket and decides how to approach it. A classifier sorts the ticket into one of the phases below based on how well-specified it is.
Brainstorming (optional). For vague tickets, the agent drafts a requirements write-up and posts it as a comment for you to refine or approve. Off by default; enable it per repo with brainstorm.enabled in .sinatrarc.
Planning (optional). The agent posts an implementation plan as a comment, again for you to refine or approve. Enable it with planning.enabled. Approving a brainstorm always leads into planning, never straight to code.
Implementing. The agent writes the code, runs your test command if one is configured, and commits.
PR open. Sinatra opens the pull request and links it back on the ticket.

When the agent posts a requirements doc or a plan, you respond in the same comment thread. Reply with changes to refine it, or approve it to move on. The agent edits its comment in place rather than stacking new ones.

Reviewing its own work

Pull requests open as drafts. Before asking for your review, the agent reviews its own diff against the ticket, and only then flips the PR from draft to ready. If you jump in with a comment while it is still reviewing, it holds the PR as a draft and picks up your feedback first.

Watching progress

While the agent works, it streams its progress as it goes: a single rolling comment on a GitHub issue, or Linear activity updates on a Linear issue. It updates one place instead of flooding the thread.

Review and rework

After the PR is ready, the loop keeps going:

Request changes on the PR, or comment with what you want different. The agent reworks on the same branch and pushes new commits.
CI failures send the agent back to fix the PR. It retries up to the ci.max_rework limit in .sinatrarc (two by default), then pauses for a human if it still cannot get green.

The whole loop runs on durable workflows. If a sandbox or the worker crashes mid-run, Sinatra resumes from where it left off rather than starting the ticket over.

Steering a run

You direct Sinatra by replying in the thread it's working in. A few behaviors are worth knowing.

Continue vs. restart

By default a reply is treated as feedback to continue the current run — a new approach, a correction, an extra requirement. Sinatra keeps its sandbox, branch, and any open draft PR.

Ask it to start over — "scrap this and redo", "throw it away and start fresh", "restart from scratch" — and it does a destructive restart: it abandons the sandbox, deletes its branch, closes the draft PR, and begins the ticket again. It only restarts when the request is unambiguous; anything that reads as ordinary feedback is treated as continue, so you won't lose work by accident.

Which comments wake it on a PR

Once a PR is open, leave code feedback on the PR. Sinatra acts on a PR comment only when it both @-mentions @sinatra and actually asks for something — "fix the failing lint", "please re-review", "handle the empty case". Acknowledgements like "thanks" or "lgtm" are ignored. A 👀 reaction confirms it picked the comment up. A formal review that requests changes sends it back to rework; an approval doesn't trigger anything.

Reply in the right place

While a brainstorm or plan is under review, reply in the same comment thread Sinatra posted it in. If you reply about requirements after the plan phase has already started (or about the plan before there is one), Sinatra posts a short note pointing you to the right thread rather than acting on it.

Stopping and resuming

GitHub — remove the sinatra label or close the issue to cancel an in-flight run. Reopen a still-labeled issue and Sinatra resumes where it left off.
Linear — use the agent session's Stop control, or move the issue to Cancelled, Done, or Duplicate. Re-assign or re-mention Sinatra to start again.

What the states mean

You may see these states on a workstream:

State	Meaning
`pending`, `investigating`	Picked up; deciding how to approach it.
`brainstorming`, `brainstorm_review`	Drafting and refining requirements (opt-in).
`planning`, `plan_review`	Drafting and refining a plan (opt-in).
`implementing`	Writing code.
`pr_open`	Pull request is open and awaiting review or CI.
`rework`	Acting on review feedback or a CI failure.
`completed`	Work is done, usually after the PR merges.
`failed`, `cancelled`	Stopped by an error, or by you closing or unlabeling the ticket.
`payment_required`	Paused for a top-up. See billing.

On this page