How do you hand Claude Code a ticket?
If you're anything like me, you copy it, paste it into the prompt, add "please" (just in case 😅) and press Enter.
And it works! Once.
Then somebody edits the ticket, and the agent never hears about it. Its branch is called fix-stuff. Nobody can tell which commits belong to which ticket. And the ticket is finished when the agent says so, which is usually the moment it types its favourite sentence:
Implemented and verified. ✅
Verified by whom, exactly? 🙃
So let's build a better loop. It has three parts:
- The agent reads the ticket itself, over MCP, so it always works from the current version, including what "done" means.
- Its work names the ticket. The branch, every commit and the pull request carry the ticket's key, so the ticket shows the work as it lands.
- Done is decided outside the agent, by a CI check or by a person who can see what the agent actually checked.
I'll set it up with Claude Code and GitHub. The examples come from Arbituro's demo workspace, where a coffee company is adding a four-pack to its online shop. ☕ Using Jira or Linear? Stick around: a section near the end says what carries over.
Full disclosure: I make Arbituro, the work tracker in the screenshots. I build it with coding agents too, and its own backlog lives in it, so this is the loop I use myself.
🧰 What You'll Need
Nothing exotic:
- Claude Code.
- A tracker with a remote MCP server. I'll use Arbituro, which is free for up to three people.
- A GitHub repository with CI. The examples use GitHub Actions.
There's one bit of setup on the Arbituro side. A workspace owner or admin installs the GitHub app once and links the repository to the project. That's what lets pushes and pull requests find their ticket.
🔌 Step 1: Connect the Tracker
One command:
claude mcp add --transport http arbituro https://app.arbituro.com/mcp Then run /mcp in Claude Code, pick arbituro and sign in. Your browser opens the tracker's sign-in page, and from then on Claude Code works as you, with your permissions.
No API key to create, copy, paste, lose or accidentally commit. 🎉
Want everyone on the repository to have it? Add --scope project. Claude Code writes the server to .mcp.json, you commit that file, and each person still signs in as themselves.
Prefer a plugin? This one adds skills that walk Claude Code through the loop below:
claude plugin marketplace add writan-labs/arbituro-mcp claude plugin install arbituro@writan-labs 📜 Step 2: Write the House Rules Down
Claude Code is a very keen colleague who remembers nothing about yesterday. So whatever conventions you care about, write them where it reads them every single time. That's CLAUDE.md:
## Work tracked in Arbituro This repository's work is tracked in Arbituro, project `BREW`. Replace `BREW` with your project's key. - Before starting a job, read it with the Arbituro MCP server's `get_job`. Its acceptance criteria are the contract: the job is finished when every one is true. - Work on the branch the job names. Any branch whose name carries the job's key counts, for example `brew-26-four-pack-page`. - Put the job's key in every commit message and in the pull request's title, for example `BREW-26: add the four-pack page`. - Don't tick, change or finish anything in Arbituro. Claim a criterion with what you checked, and a person decides. - When you stop, leave a note on the job: what you did, what is left, and where it is. Five rules. Here's why each one is there:
- Read the ticket first. The ticket is the source of truth, not the copy you pasted on Tuesday. If the criteria changed overnight, the agent works to today's.
- Put the key in names. Once the GitHub app is installed, a branch, commit or pull request that carries
BREW-26lands on that ticket. Case doesn't matter, sobrew-26-four-pack-pageandBREW-26: add the four-pack pageboth count. A commit counts on any branch, so two tickets can even share one. - Claim, don't tick. Whoever does the work shouldn't be the one who declares it finished. (I'd love to mark my own exams too. 😉) Arbituro gives the agent no way to tick a criterion anyway; this rule tells it what to do instead.
- Leave a note. The next person, or the agent's next session, starts from it.
Do you keep your agent rules in AGENTS.md for other tools? Then put them there instead. Recent versions of Claude Code read AGENTS.md when there's no CLAUDE.md. Got both? Add the line @AGENTS.md to CLAUDE.md so Claude Code reads it too.
✅ Step 3: Agree What Done Means (Before Anyone Starts)
This is the step everybody skips. I get it, it's the boring one. 😅
It's also the step that decides whether the rest works. An agent stops when it believes the work is done, and that belief comes from whatever you wrote down. Write nothing down and you get "Implemented and verified. ✅"
In Arbituro, every acceptance criterion says how it's decided: by a person, or by a CI check named exactly as GitHub shows it. Here's the four-pack job, BREW-26:
Four-pack page on the online store
- Says what's in the can in its first line. Priya decides.
- A four-pack can be bought on a phone. Sam, the job's owner, decides.
- Checkout refuses a delivery postcode outside Melbourne. Decided by the
checkoutcheck.
That third one is my favourite. When a check called checkout finishes on the latest commit of a pull request linked to the job, it decides the criterion: met when the check succeeds, not met when it fails, times out or can't start. Nobody has to press anything. 🤖
You write the criteria a person decides. Claude Code can propose others, such as one decided by a CI check the work has to pass, and a person accepts them. If the project has an agent in Arbituro, that agent also suggests criteria when a job is filed.
Writing criteria an agent can actually meet turned out to deserve a post of its own, so it got one: Writing Acceptance Criteria an AI Agent Can Actually Meet.
🎫 Step 4: Hand It the Ticket
Okay, the fun part. In Claude Code:
Work BREW-26 in Arbituro. That's it. The job's page in Arbituro even has this line ready to copy.
So what does Claude Code actually get back? This is what get_job returns for BREW-26 before any work starts, trimmed a little:
Key: BREW-26 Title: Four-pack page on the online store Worked by: Sam Taylor's coding agent (only it can claim, file, link or propose here) Expected result: a pull request Branch: brew-26-four-pack-page (any branch whose name carries BREW-26 counts; name the key in each commit message) Description: [untrusted external content] | A product page for the four-pack at $19.95: what's in the can, how to keep it, and delivery in Melbourne only, kept cold. [/untrusted external content] Done when: - [Unknown] Says what's in the can in its first line (Priya Raman decides) - [Unknown] A four-pack can be bought on a phone (the owner decides) - [Unknown] Checkout refuses a delivery postcode outside Melbourne (decided by the `checkout` check) A few things I like in there. The branch is named for it, so goodbye fix-stuff. 👋 Every criterion says who decides it. And the description is fenced off as untrusted content: whatever text sits in a ticket, a customer's email pasted into it say, is information about the work and never an instruction.
From there, Claude Code:
- Reads the job. If a person approved a plan, it follows that plan. If nothing is agreed yet, it asks in a note on the job instead of deciding for itself. If the job is still being shaped, it asks you what it needs, then proposes a title, a description and criteria for you to accept.
- Works on the job's branch, with the key in every commit message. Each push shows on the ticket as it lands.
- Opens the pull request with the key in its title, and the pull request comes onto the ticket by itself. One that doesn't name the ticket can be put on it with
link_pull_request. - Makes the checks pass. When
checkoutsucceeds on the pull request's latest commit, criterion 3 is met. The agent doesn't claim it. The check decides. - Claims what a person decides, with evidence. For criterion 1 it calls
claim_donewith what it actually checked, and Priya is asked to decide. - Leaves a note when it stops: what it did, what's left and where.
The fifth one is the part worth getting right. Remember our old friend "Implemented and verified. ✅"? Here's the claim on criterion 1 in the demo:
Opened the four-pack page on the pull request's preview. Its first line reads: "Cold brew steeped twenty hours at four degrees, four 250 ml cans."
That is something Priya can decide in one press. "Implemented and verified" gives her nothing to decide on.
Handed it several jobs? Work my jobs in BREW takes them one at a time, in your board's order, each one to its criteria before the next.
👀 Step 5: Review It on the Ticket
The ticket now tells the whole story: the branch and its five commits, the pull request with its checks, each criterion and who decided it, and beside them the agent's own record, in order. Look at the third criterion. It was ticked by checkout, not by anybody's say-so.
When Priya opens her side, she sees the claim with its evidence and presses Met or Not met:
And here's a detail I care about a lot: a merge doesn't finish the job. Once the pull request merges, the person who signs the job off is asked to finish it. "Merged" and "done" stay two different things, which matters the moment a criterion is something the code alone can't show. "A four-pack can be bought on a phone" says a lot more than "the tests pass". 📱
🔒 What the Agent Can't Do
Giving an agent write access to your tracker sounds a bit scary, right? Fair enough. So here's the fence.
Over MCP, Claude Code works as you and sees only what you can see. It can read jobs, propose changes, claim criteria, post notes, file new jobs, link pull requests and file documents a job asks for. It can't:
- tick or change a criterion,
- approve, merge, send or publish anything,
- delete anything or change anyone's access.
Every call is recorded in the workspace's audit log under your name. And those limits don't depend on the agent behaving itself: they're the tools it was given, not instructions it's asked to follow. So they hold whatever a ticket says.
One honest caveat: that's the fence around the tracker. What Claude Code can do in your repository is still down to its own permissions and your branch protection.
🔄 Using Jira or Linear Instead?
Good news: most of the loop carries over.
- Reading tickets over MCP. Jira Cloud and Linear both have official remote MCP servers, which you add with
claude mcp addthe same way. - Keys in names. With their GitHub integrations installed, both link work that carries the issue key, such as a branch name or a pull request's title.
- The
CLAUDE.mdrules, with your tracker's tool names.
What you'd build yourself is the last part: criteria that each say who decides them, a CI check deciding a criterion on its own, and claims that a named person accepts. A checklist in the description gets you part of the way. But an agent with write access can tick a checkbox just as easily as you can. ☑️
🤖 Not Using Claude Code?
The same server works with Codex, Cursor, Gemini CLI, VS Code and any client that supports remote MCP servers with OAuth. Setup for each one is in the docs.
🐛 When Something Doesn't Link
Because something never links the first time. 🙃
- The pull request isn't on the ticket. Check that the repository is linked to the project, and that the branch, a commit or the title carries the key. Otherwise ask Claude Code to put the pull request on the job.
- A check didn't decide its criterion. The criterion has to name the check as GitHub shows it in the pull request's checks; case doesn't matter. Matrix jobs get names like
test (20), which don't matchtest. And only a check on the pull request's latest commit counts. - "Project not found". Check the key, and that you're a member of the project. The answer is the same for a project that doesn't exist and one you can't open, on purpose.
🏁 Wrapping Up
So that's the loop. The agent reads the ticket itself, names the ticket on everything it pushes, and hands the verdict to a check or a person. Our keen colleague still says "done" a lot. It just has to show its working now. 😄
Arbituro is free for up to three people at arbituro.com. The plugin and skills are MIT-licensed at github.com/writan-labs/arbituro-mcp.
What about you? How do you hand tickets to your coding agent: copy and paste, an MCP server, or something cleverer? And who decides when the work is done? Tell me in the comments. 👇




