DEV Community: Sam Novak

Put your particle effects in CI: the silent-skip bug nobody catches by eye

Sam Novak — Mon, 14 Sep 2026 11:23:20 +0000

Most particle editors are GUI-first, which is correct: authoring a visual effect by typing numbers is a miserable way to work. But once the effect exists, it is a file, and files belong in the same machinery as the rest of your project.

I spent an afternoon wiring our VFX into CI and it caught a class of bug we had been shipping for months.

The bug class

A portable effect format usually means one description consumed by multiple renderer backends. That is the whole point. What it does not mean is that every module is implemented on every backend.

We moved an effect from the Three.js path to a 2D Pixi path. It rendered. It just rendered wrong, in a way nobody could name, and it took an embarrassing amount of squinting to work out that a velocity-over-lifetime module had been silently dropped because that backend does not implement it.

It was not an error. It was reported, correctly, in an unsupported-modules list on the stats object. Nobody was reading the stats object.

Making the machine read it

The useful realisation is that this is a test, not a debugging technique. If the runtime will tell you which modules it skipped, you can assert on that in CI:

Load every effect file in the repo
Instantiate it against each backend the game actually ships
Fail the build if the unsupported-module list is non-empty for a backend that effect is used on

That is maybe thirty lines. It turns a silent visual regression into a red X on a pull request, which is the entire difference between a bug you fix in a minute and one you ship.

Validation and generation, while you are there

Two more things fall out once effects are scriptable from the command line.

Validate on commit. A malformed effect file should not reach a build. A validate step in a pre-commit hook or CI job is cheap and stops the "works on my branch" version of VFX bugs.

Generate variants. We had five near-identical pickup effects differing only in tint. Those are now generated from one source plus a colour table, which means a change to the shape of the effect does not require an artist to open five files and remember what the other four looked like.

A caution on that last one: generation is great for mechanical variants and terrible for anything where an artist is making a judgement call. If someone would want to nudge it by eye, it should not be generated.

Getting started

You need two things from your tool: a documented project-file schema, and a CLI that can create, validate and export without a display. If your tool has both, the CI work above is an afternoon. If it has neither, that is worth knowing before the format becomes load-bearing in your pipeline.

The NixieFX CLI reference documents the project schema and the create, validate and export commands, which is what I used for the above. Disclosure: I work with that team. The CI idea is tool-agnostic, and the unsupported-module assertion is the part I would steal first.

Rework is an outcome your tracker probably cannot express

Sam Novak — Mon, 14 Sep 2026 11:20:46 +0000

Your tracker has states for work that has not started, work in progress, and work that is finished. Ask it to express "this was delivered, reviewed, and sent back because it solved the wrong problem" and most of them quietly collapse that into moving the ticket back to In Progress.

That collapse throws away the most useful signal you have.

What gets lost

When a rejected delivery is represented as a state change rather than an event, you lose:

That a delivery happened at all. The cycle-time number now says the task took nine days, with no indication that it was done on day three and redone twice.
Why it came back. "Requirements changed" and "the brief was ambiguous" and "the implementation was wrong" are three completely different problems with three different fixes, and they all look identical from the board.
First-pass rate. Which is the single number that tells you whether your briefs are getting better or worse.

This matters for human work. It matters much more once agents are doing some of the work, because the agent cannot tell you it was confused, and the rework reason is the only place that confusion becomes visible.

The cheap version

You do not need a new tool. You need rework to be an event with a reason, not a state transition.

Add one required field on send-back, with a short closed list. Ours is roughly:

brief was ambiguous
brief was wrong
requirements changed after the brief
implementation did not match a clear brief
out of scope work included

Closed list, not free text. Free text gives you a thousand unique sentences and no aggregate. Five buckets give you a monthly number you can act on.

What we found when we started counting

The honest result: most of our send-backs were not the implementation being wrong. They were the brief being ambiguous in a way that was obvious in hindsight and invisible at writing time. We had been treating a specification problem as an execution problem, which is why none of the things we tried had been helping.

That is not a profound insight. It is just one that was unavailable to us until rework had a reason code.

One design note

If you are building or choosing tooling here, look at whether rework feedback is carried back into the task context that the next run of the work actually reads. A reason code that only lands in a report is an analytics feature. One that reaches whoever, or whatever, picks the task up next is a correctness feature. The Wagglet workflow docs treat rework feedback as part of the task context for exactly this reason.

Disclosure: I work with the team that builds Wagglet. The reason-code idea costs nothing and works in whatever you already have.

Attachment URLs are bearer links, and revoking the token does not revoke them

Sam Novak — Mon, 14 Sep 2026 11:18:28 +0000

When we started handing real tasks to coding agents, we did the obvious safety work first. The agent gets a read-only credential, scoped to one task, that stops working when the claim ends.

Then a colleague asked a question I did not have a good answer to.

The question

If the task context includes attachments, a spec PDF, a screenshot of the bug, a CSV of the failing rows, how does the agent actually fetch them?

The usual answer is a signed URL. The context payload contains a link, the agent GETs it, done.

Here is the part that took me a while to properly absorb: that URL is its own credential. It is a bearer token wearing a URL costume. Which means:

Revoking the task credential does not revoke it. The read token can be completely dead and the attachment link still works.
It does not care who presents it. Anything that can read the URL can read the file.
It leaks the way URLs leak, which is to say constantly. Logs, error reports, a screenshot of a terminal, a model provider request history, a traceback pasted into a group chat.

None of that is exotic. It is the ordinary lifecycle of a string in a distributed system.

Why agents make this sharper

A human opens an attachment in a browser and the URL dies quietly in their history. An agent puts it in a context window, which may be logged, retried, cached, or forwarded to a subagent. The number of places that string comes to rest goes up by an order of magnitude, and most of them are not places you thought about when you designed the expiry.

What to actually do

Treat attachment URLs as secrets in your logging policy. If you redact tokens from logs, redact these too. They are the same class of thing.
Give them a shorter life than the session. The agent needs the file for one run, not for the seven days the claim might last.
Do not log whole context payloads at info level. This is where most accidental exposure actually comes from, not from anything clever.
Scope them to the resource, not the account. A leaked link that exposes one PDF is an incident. One that exposes a bucket is a very different afternoon.

The documentation point

The thing I have come to care about more than the mechanism is whether the vendor says it out loud. A system can handle this correctly and still leave you guessing about whether revocation covers attachment links, and you will guess wrong in the optimistic direction.

The handoff skill docs for Wagglet state it flatly: attachment URLs returned in context are independent bearer links, keep them private, and revoking the task read credential does not revoke a URL already returned. That sentence saved me an experiment, which is what good documentation is for.

Disclosure: I work with the team that builds Wagglet. The advice above applies to any signed-URL scheme you happen to be using.

If you are designing this layer right now, the question worth writing on the wall is simple: when the credential dies, what is still alive?

Seat-based AI tooling has an idle capacity problem nobody budgets for

Sam Novak — Thu, 10 Sep 2026 10:00:18 +0000

If your company buys per-seat AI coding subscriptions, you are almost certainly paying for a lot of capacity that expires unused every week, while some of your engineers hit their limit on Tuesday.

Both things are true at once, and that combination is what makes it a distribution problem rather than a spending problem.

Why the distribution is so uneven

Usage is bursty and it correlates with role in a way that seat allocation does not.

Someone mid-migration will saturate a subscription for two weeks and then barely touch it for a month. Someone in meetings four days a week has a seat that is nearly untouched. A designer or a QA engineer who was given a seat during a rollout may never have opened it.

Meanwhile the allowance does not roll over. Unused capacity is not banked, it just stops existing, and it stops existing quietly. There is no line item for it and no alert.

The wrong fix, which everyone tries first

Share a login. One account, shared credentials, anyone can run anything.

This is worth naming explicitly because it is the natural first idea and it is bad in four separate ways. It breaks attribution, so you cannot tell who ran what. It makes the rate limit collective, so one person's big job blocks everyone. It makes revocation all-or-nothing. And it generally violates the terms you agreed to when you bought the seats.

The second wrong fix is buying more seats to relieve the pressure, which increases the amount of idle capacity you are paying for. You will feel like you solved it, because the person who was blocked stops complaining.

Move the task instead of the account

The version that works is unglamorous: when someone is out of capacity and someone else has plenty, move the work item, not the credentials. The second person runs it on their own subscription, under their own identity, and the attribution stays intact.

That requires the task to be portable, which is the actual cost. A task that only its author can run - because the brief lives in their head - cannot be moved no matter how much capacity is idle elsewhere. So the prerequisite for using spare capacity is writing tasks down properly, which is annoyingly the same prerequisite as everything else in this area.

Be honest about the two kinds of value

This is where I would push back on most write-ups of the idea, including some enthusiastic internal ones.

Recovered output is real: work got done that otherwise would have waited. Worth having.

Cash saved is usually not real. You only save money if you would otherwise have bought more seats. If you were not going to, then using idle capacity costs the same as not using it, and reporting a saving is fiction. It is a throughput gain, not a cost reduction, and the two get conflated constantly because one of them sounds better in a board update.

There is a third thing, harder to measure and possibly the most valuable: someone who was blocked stops being blocked, which changes what they attempt next.

This write-up models the whole thing with the assumptions visible, including a ten-seat worked example and an explicit separation of recovered output from genuine cash savings. I would read the section on why an allowance percentage is not enough before quoting a utilisation number to anybody, because a percentage hides exactly the burstiness that makes the problem interesting.

And if you do try it: run it as a pilot designed so it can come out negative. The failure mode of this idea is not that it does not work - it is that it is impossible to disprove once someone has announced it.

An AI task contains five decisions, and one person usually makes all of them

Sam Novak — Thu, 10 Sep 2026 09:58:16 +0000

Watch a piece of AI-assisted work go through a small team and you can pull out five distinct decisions:

Is this worth doing at all?
Is it prepared well enough to hand to somebody else?
Who runs it, and on whose subscription?
Did the outcome actually meet the bar?
Did it land?

On most teams I have seen, one person makes all five. Usually the person who had the idea. That is the whole problem, and it does not look like a problem while it is happening - it looks like being efficient.

What each collapse costs

1 and 2 collapsing means an idea goes straight to a work item without anyone deciding it is worth preparing. You end up with a board that is a list of thoughts, and nobody can tell which entries are real.

2 and 3 collapsing is the common one. The person who prepared the task is the person who runs it, so preparation never actually has to be legible to anyone else. The brief lives in their head, the task looks tiny in the tracker, and it cannot be reassigned. You discover the brief was never written the day that person is on holiday.

3 and 4 collapsing is the expensive one. The person who ran the task judges whether the result is good. With a human doing the work that is merely optimistic. With an agent it is close to meaningless: the agent reports success, the runner reads the report, the report becomes the verdict. Nobody lied and nothing was checked.

4 and 5 collapsing is subtler. Accepting the work and the work actually landing are different facts, and only one of them is verifiable by a machine. If "accepted" also means "merged", then either you are blocking acceptance on CI, or you are letting a human assertion stand in for git. Both are worse than keeping two fields.

The one I would fix first

Split 3 from 4. Whoever ran it does not judge it.

This is cheap. It does not need tooling, a process document, or anyone's permission - it needs a second name on the item. And it converts an agent's self-report from a verdict into a claim, which is the single highest-leverage change available in this whole area.

The objection is always throughput: we are two people, we do not have a spare reviewer. Fair. Then swap - you review mine, I review yours - and accept that the review is shallow. A shallow review by someone who did not do the work still catches the confident-wrong-answer failure mode, which is the one you actually have.

The account question is its own decision

Decision 3 has a part people skip: whose subscription does the run consume?

The tempting answer is to share a login so anyone can run anything. Do not. It destroys attribution, makes usage limits collective, and generally violates the terms you agreed to. The alternative that works is moving the task to whoever has capacity, and letting them run it on their own account under their own identity. Same flexibility, no shared credentials.

Wagglet's how-it-works page lays this out as five decisions with one owner each, which is where I got the framing, and it is blunt about the account rule - move the prepared task, keep every account with its owner. It also has a short section on work that should not be handed off at all, which I appreciated, because most tools in this space write as though everything should be.

You do not need five people. You need the five decisions to be visibly separate, so that when one of them is being skipped, somebody notices.

Chat is a bad medium for handing off work

Sam Novak — Thu, 10 Sep 2026 09:57:10 +0000

Most work handed between people right now travels as a chat message. "Can you look at the flaky checkout test? I think it is the timezone thing, there is context in the thread from Tuesday."

That message is fine as a nudge and terrible as a handoff, and the reasons are structural rather than a matter of writing it better.

Four things chat cannot do

It is not addressable. There is no id. You cannot refer to "that handoff" in a standup, a commit message, or a follow-up two weeks later. The best you get is a permalink to one message, which loses everything said after it.

It does not accumulate. The scope gets amended four messages later, a constraint arrives from someone else in a side thread, and the original message still says the original thing. There is no single current version - there is a history you have to replay, in order, correctly.

It cannot be reviewed before it is sent. A handoff is a thing you should be able to prepare, reread, and fix. Chat is send-then-clarify by design. You find out it was under-specified by watching someone work on the wrong thing.

It has no completion state. "Done" arrives as another message. Nothing distinguishes "I pushed something" from "someone checked it" from "it actually landed". Those are three separate facts and chat flattens all of them into a thumbs up.

None of this is an argument against chat. It is an argument that chat is the transport, not the artifact.

It gets sharper when an agent is involved

Everything above is an old problem. Handing work to a coding agent makes it acute, for one specific reason: the agent needs the brief to be complete at the moment it starts, because it will not come back and ask.

A human receiving a vague handoff does the single most valuable thing in the whole exchange - they notice it is vague and ask. That check disappears. An agent given an ambiguous brief produces a confident, plausible, wrong answer, and the ambiguity is only discovered at review, if there is a review.

So the artifact has to carry, at start time, all of:

the actual goal, not the symptom that prompted it
the acceptance check, written before the work
the context that is not in the repo, which is the part that lives in someone's head or in Tuesday's thread
the boundary of what the run is allowed to touch
and separately, instructions for the human supervising it, which are not the same as instructions for the agent

That last one took me a while. The person running the task needs to know how to judge progress and when to stop. The agent needs the task. Writing one blob addressed to both produces something that reads as neither.

The credential is part of the artifact

The piece most often left out: what the run is allowed to reach. If handing off a task means handing over your session, the handoff has no boundary and cannot be audited. A bounded, read-only, expiring credential scoped to the one task is not a security nicety bolted on afterwards - it is what makes the handoff a discrete thing with edges rather than a temporary transfer of your whole identity.

And the delivery step wants to be separate from the working step, so that reporting an outcome is a deliberate act with evidence attached rather than the run trailing off.

Wagglet's task handoff documentation is a compact description of that shape in practice: one claimed task, a bounded agent context, a named human supervising the run, a separate delivery prompt, and review by somebody who did not do the work. The part I would point at even if you build your own is the explicit statement of what the copied credential can and cannot reach.

Keep using chat to say "have you got a minute". Just do not let it be the only record of what you agreed.

tools/list is an API contract, and you are versioning it by accident

Sam Novak — Thu, 10 Sep 2026 09:56:02 +0000

If you run an MCP server, your tool catalog is a public API. I do not think most of us are treating it like one.

Here is the shape of the problem. A client connects, calls tools/list, gets your catalog, and starts using it. Then you rename a tool for clarity. Or you tighten a parameter schema because someone was passing nonsense. Or you split one tool into two better ones.

Every one of those is a breaking change shipped with no version number, no deprecation window, and no changelog.

Why it is worse than a normal API break

With an HTTP API, a break produces a 404 or a 400 and somebody's error tracker lights up. The failure is loud and it points at you.

With a tool catalog, the consumer is a language model. It does not throw. It adapts. Give it a tool that no longer exists and it will try a plausible neighbour, or invent arguments that match the old schema, or quietly do something adjacent and report success. The failure surfaces as a weird outcome three steps later, in someone else's log, attributed to the model being unreliable.

That is a genuinely bad debugging situation, and the person who has to debug it is not you.

Rules I would follow

Tool names are permanent. Pick badly and live with it. A slightly awkward name that has been stable for six months is worth more than a clean rename. If you must rename, keep the old name working and have it do the same thing.

Additive changes only, on parameters. New optional parameters are fine. Making an optional parameter required is a break. Narrowing an enum is a break. Renaming a field is a break. Tightening validation on a field that previously accepted sloppy input is a break, and it is the one people do not notice they are doing.

A removed tool should fail loudly, not vanish. If something has to go, leaving it in the catalog with a description that says it is removed and an error that says what to use instead is far kinder than deleting it. The model will read the error. It cannot read your absence.

Say so if your catalog is dynamic. This is the one I would most want documented. If the tools a client sees depend on its permissions, its connection, or the team it is pinned to, then no client can safely cache the catalog once and reuse it. That is a legitimate design - it is how you keep a connection from becoming a second, broader authority than the person who created it - but it has to be stated, because the default client assumption is that a catalog is stable.

Make the catalog itself authoritative. Documentation drifts. If your docs list tool names and your server also lists them, one of the two will be wrong within a quarter. Say plainly which one wins.

The read-before-write pattern

The corollary on the client side, which I have come round to: for anything with an effect, read current state immediately before acting, in the same run. Not at the start of the session - immediately before.

This is not paranoia about your server. It is that the gap between "agent decided to do X" and "agent does X" can contain a human doing something else entirely, and a stale read makes the agent confidently overwrite it. A revision or version check on write is the cheap version of the same protection.

Wagglet's MCP documentation is a decent worked example of these constraints being written down rather than left implied - a connection that is named and revocable and pinned to one person and one team, an explicit statement that the connection never becomes a second authority, and reading current state before an explicit action. Whether or not you use it, the doc is a reasonable checklist of the things a server author should be deciding on purpose.

The short version: your tool names are your API surface, your clients cannot see your git history, and your consumers do not raise exceptions. Version accordingly.

Your tracker has no private draft state, and it shows

Sam Novak — Thu, 10 Sep 2026 09:09:53 +0000

Every issue tracker I have used has some version of Backlog, In Progress, Done. Not one of them ships a place to prepare a task in private before other people can see it.

That missing state causes a specific, recognisable mess, and once you notice it you see it everywhere.

The mess

Somebody has an idea. The only way to record it is to create a ticket. Creating a ticket puts it on the board. Being on the board means it is now a thing the team can see, comment on, estimate, and start.

So a half-formed thought becomes a work item in one step, and then the work item becomes the argument. You have all had the ticket with eleven comments where the first four are people asking what it means, the next four are scope negotiation, and the last three are somebody who already started building the wrong version.

None of that is a communication problem. It is a missing lifecycle stage.

Two jobs that are not the same job

Capturing an idea and preparing a task are different activities with different requirements.

Capturing wants to be as cheap as possible. Any friction here and people stop recording things, which is strictly worse. One line, no fields, no estimate, no owner.

Preparing is the expensive part. It means deciding the scope, writing down what would make the result acceptable, attaching the context somebody would otherwise have to come and ask you for, and - most importantly - deciding whether the thing is worth doing at all.

If those share one state, capturing inherits preparation's friction, or preparation gets skipped. Usually both.

Preparation is cheap in private and expensive in public

This is the bit that convinced me. The same edit costs radically different amounts depending on whether anyone is watching.

Rewriting the scope of a private draft costs nothing. Rewriting the scope of a published ticket means notifying whoever commented, correcting whoever started, and re-litigating whatever was already negotiated. Same keystrokes, ten times the cost.

So the natural consequence of having no private stage is that tasks get published under-prepared and then never properly fixed, because fixing them in public is too expensive.

Publishing as an actual gate

The other thing you get from a real draft state is that publishing becomes a signal.

When someone deliberately moves a task from draft to the board, they are asserting something: this is ready to put in front of another person. That assertion is genuinely useful information. On a board where everything is published by default, no item carries it, and every item has to be independently assessed for whether it is real.

I would go further: nothing should be able to leave the draft state without a written acceptance check. Not as a process ritual - as the definition of prepared.

If your tracker cannot do this

Most cannot, so approximate it:

Add a Draft or Not Ready label and treat items carrying it as invisible. No estimating, no starting, no commenting beyond the author.
Default new items to it. The gate only works if passing through it is deliberate.
Make the exit criterion explicit and boring: scope, acceptance check, context attached.
Keep capture separate and frictionless. A one-line note that becomes a draft later is fine. A one-line note that becomes a ticket immediately is the problem.

The convention is weaker than a real state because nothing enforces it, but it recovers most of the value.

Wagglet's walkthrough of its full workflow is the most explicit version of this I have seen implemented rather than described - a rough request, a private Draft used as a preparation room, then a deliberate publish onto the board, and separate stages after that for claiming, delivering evidence, and a reviewer choosing among genuinely different verdicts. It looks longer on paper. That is rather the point: the stages were always there, they were just happening implicitly inside one column and one comment thread.

The delegation test is whether you can write the check first

Sam Novak — Thu, 10 Sep 2026 09:08:05 +0000

Every discussion I see about what to hand off to a coding agent sorts tasks by difficulty. Easy things to the agent, hard things to the human. It sounds obvious and it has been wrong in practice for me almost every time.

The axis that actually predicts a good handoff is not difficulty. It is this: can you write down, before any work starts, what would make you accept the result?

If you can write the check, hand it off. If you cannot, the task is not ready to hand to anybody.

Why difficulty is the wrong axis

I have handed off genuinely hard work that went fine, because the definition of done was mechanical: migrate this to the new API, all existing tests keep passing, add coverage for the two error paths. Hard, bounded, checkable.

I have also handed off something trivial that came back four times, because what I actually wanted was "make this error message less alarming", and I had no way to say what less alarming meant. That is not a hard task. It is an unspecified one, and the agent did nothing wrong - it produced four defensible answers to a question I had not asked properly.

The failure was mine, and difficulty had nothing to do with it.

Write the check, then write the prompt

The useful discipline is to write the acceptance check first, as a separate artifact, before writing a single line of instruction.

Checkable:

Cursor-based pagination on this endpoint. Existing tests pass. One new test for the empty-page case.
Upgrade this dependency across the monorepo. Build is green. No new lint warnings.
This function allocates in a hot loop. Same output for the existing fixtures, zero allocations in the steady state.

Not checkable, as written:

Make the onboarding feel less intimidating.
Clean up this module.
Improve performance.

The trick with the second list is that it is usually not one task. It is a decision wearing a task costume. "Make onboarding less intimidating" contains a judgement call - what counts as intimidating, and what are we willing to lose - and that part is yours. Once you have made it, what remains is checkable: cut the signup form to three fields, defer the rest to first use, keep the existing validation behaviour.

So the sequence is decide, write the check, then delegate. Skipping to delegate is what produces four rounds of nearly-right work.

The part that surprised me

Two things I did not expect from working this way.

First, if you rigorously delegate everything checkable, what remains on your own plate is pure judgement. That is more tiring, not less. The mechanical tasks were also the ones you could do while half awake, and they let you warm up into a day. Losing all of them at once is a real cost and nobody warns you about it.

Second, and more useful: the check is not agent infrastructure, it is people infrastructure. A bounded task with a written acceptance criterion is something you can hand to a teammate who has never touched that part of the system. Without the check they need the context you have. With it, they need the check and a couple of hours.

That reframing changed how I think about the whole exercise. I started writing acceptance criteria to make agents behave and ended up with a backlog that more of the team could pick up. Wagglet has a good piece on that specific side effect - handoffs as a way for more people to contribute rather than purely a throughput trick, including the caveat that the same mechanism can hollow out a role if you only ever hand out the mechanical half.

That caveat is real, and it is the reason I would not automate the decision step even when I could. The check is the part you write. It is also the part that is actually your job.

Bounties for AI work have the same failure mode as game economies

Sam Novak — Thu, 10 Sep 2026 09:05:18 +0000

I spent a few years designing game economies before I spent any time on AI tooling, and the transition has been strange, because I keep watching people rediscover failure modes that mobile games documented years ago.

The current one: bounties for AI-assisted work. Pay people for tasks completed by their agent. Put a leaderboard on it. Watch throughput go up.

Throughput does go up. That is the problem.

The rule from game economies

Every reward loop has a currency, a source, and a sink. The loop stays healthy while the effort to satisfy the metric is higher than the effort to game it. The moment that inverts, the economy does not slow down - it accelerates in the wrong direction, and it looks like success on the dashboard the whole time.

This is why a "1% drop rate" feels broken to players, why battle passes get abandoned mid-season, and why currency sinks are the least glamorous and most load-bearing part of an economy. Sources are easy. Sinks are the design.

Now apply it to agent work

Ask what a submission actually costs.

Before agents, submitting a completed task cost hours. The metric was expensive to satisfy and roughly impossible to game, so nobody bothered building anti-gaming controls. That cost is now close to zero. One prompt produces something task-shaped. It compiles. It has a plausible commit message.

So if you pay per submitted task, you have built a source with no sink. You will get volume, immediately, and it will be indistinguishable from productivity in every chart you have.

The three specific patterns I would expect, all of them rational:

Task splitting. One real change submitted as four tasks, because the unit of payment is the task and nothing checks that a task is a meaningful unit of work.
Cheap-task farming. People sort the backlog by effort ascending, which is exactly what you asked for, and the hard tickets rot.
Confident non-delivery. An agent reports success. Nobody checks. The reward pays out on the claim, not the outcome.

None of that requires bad actors. Design for the employee who understands your metric perfectly and is not trying to cheat, because that person will find the cheapest honest path and take it.

What the sink looks like here

In a game the sink removes currency. In a work system the sink is a decision that can say no, placed between the claim and the reward, and made by somebody who is not the claimant.

Concretely, the parts I would not skip:

Pay on accepted, not submitted. The reward event is a reviewer's verdict, not a state transition somebody performed on themselves.
Require evidence in the submission. Not "done" - the actual output, the test result, the URL. An unverifiable claim should be structurally impossible to submit, not merely frowned upon.
Separate acceptance from merge truth. A reviewer accepting the work and a branch actually landing are two different facts. Collapsing them means "done" quietly stops meaning anything.
Make the review load visible. This is the one people miss. Reviewing is now the bottleneck and it is unpaid, so it will be done badly unless it is counted as work.

Point 4 is where I think most of these systems will actually fail. You can move the bottleneck from doing to reviewing and call it a productivity win, and the reviewers will absorb it silently for about two months.

The honest uncertainty

I do not know what the right payout ratio is, and I am suspicious of anyone who says they do. Games get curve numbers by shipping and watching, and most of them get it wrong twice first.

What I am fairly confident about is the shape: verified outcome, independent decision, evidence attached, review counted. Wagglet's write-up on bounties and rewards for AI work is the most careful version of that argument I have read, including the anti-gaming controls, which is the part usually left as an exercise for the reader.

Run it on one team for a month before announcing it as a revolution. If your throughput triples in week one, that is not the good outcome - that is your economy telling you the metric is cheaper to game than to satisfy.

Call whoami first: your agent should not trust a cached tool catalog

Sam Novak — Thu, 27 Aug 2026 08:13:54 +0000

There is a failure I have now watched three separate teams hit, and it always looks like a bug in the agent.

An agent connects to a tool server, does useful work for a week, and then one day starts producing confidently wrong actions. It calls a tool that no longer exists. It tries to transition something it is not allowed to transition. It reports success on a mutation that silently did nothing. Everyone goes looking for the regression in the model, or in the prompt, and the actual cause is that the agent was working from a catalog of tools and permissions it had cached at some point in the past.

The fix is one boring call at the start of every session, and it is worth understanding why it is not optional.

A token is a connection, not a role

Here is the thing people get wrong about tokens on a permissioned tool server. The token identifies which named connection is talking. It does not carry the caller's authority.

That sounds like a distinction without a difference until something changes on the other side. The person the connection belongs to gets moved to a different team. Their role changes. An admin turns off tool access at the workspace level. A permission that used to be granted is revoked.

In a system built correctly, the token keeps working as an identifier and the authority is resolved fresh on every call from the person's current membership, roles, and permissions. Which means the answer to "can I do this?" can be yes on Monday and no on Tuesday with nothing about the token having changed. Wagglet's MCP server is explicit about this: a token identifies a named connection, and it never overrides the same person's current membership, roles, or permissions. Team-level access is off by default, and disabling it later rejects every connection request immediately without deleting the connections.

If your agent cached a permission list at connection time, it is now confidently wrong about what it can do, and the only symptom you will see is a failed action it did not expect to fail.

Tool schemas move under you

The second half is the tool catalog. Any actively developed tool server adds tools, renames arguments, tightens validation, and deprecates things. That is normal and healthy.

What is not healthy is an agent whose idea of the available tools came from documentation, a blog post, or a previous session's transcript. A copied old catalog is not a source of truth. The live tools/list response is. This is the same discipline as not hardcoding an API response shape you saw once in a tutorial, except the failure is quieter, because a model will happily improvise a plausible call for a tool that no longer accepts that argument.

So: whoami first, then read, then act

The sequence that holds up:

1. Establish identity and authority. Call the server's whoami (or equivalent) and treat its team, identity, roles, and permissions as the authority for this session. Not your prompt's belief about who you are. Not last week's.

2. Fetch the live tool schemas. Use them, not a remembered list. If a tool you were planning to call is gone, that is information, not an error to work around.

3. Discover ids with bounded search, and page properly. Cursors exist because the population can be bigger than one response. An agent that reads the first page and reports a total is producing a confident number that is wrong.

4. Read the complete authorized record before you change it. Fetch the ticket or document, keep the returned record and its item revisions, and use those in the mutation. This is what makes concurrent edits safe instead of last-write-wins.

5. Use the matching lifecycle command, and give each intended mutation a fresh operation id. Reuse an operation id only when you are deliberately retrying the same intended change. This is the difference between a retry and a duplicate.

The full sequence with the actual tool names is in the Wagglet MCP workspace guide.

Why this is more than hygiene

There is a design point buried in this that is worth pulling out.

A permissioned tool interface is not a database with a chat wrapper. It keeps the product's own language and its own lifecycle rules, and it refuses actions that do not fit them. That refusal is the feature. An agent that could freely write any field would produce records that are structurally valid and semantically nonsense - a task marked delivered with no evidence, a review verdict with no reviewer.

Which is why "read current state, then use the explicit action for what you actually mean" is not ceremony. It is the thing that keeps an agent's output reviewable by a human afterwards. If you want the reasoning behind treating delivery, acceptance, merge, and deploy as four separate facts rather than one status field, that is the argument in the Wagglet workflow.

The one-line version

Do not let an agent start from what it remembers. Make it ask who it is, what it may do, and what tools exist - every session, out loud, before the first action. It costs one call. It saves the class of bug that looks like the model got worse and is actually your permissions changing underneath a cached answer.

Background on the surrounding handoff model: how Wagglet works.

Your coding agent needs a read-only, task-scoped, expiring credential

Sam Novak — Thu, 27 Aug 2026 08:07:58 +0000

Every team that starts handing work to coding agents hits the same wall in about week three. Someone prepares a task, someone else is going to run it, and the agent needs context. Not vague context - the ticket, the acceptance criteria, the linked spec, the three comments that changed the scope. So one of two things happens.

Either the person who prepared the task pastes a wall of text into a chat window and hopes it is still accurate by the time the agent reads it, or somebody shares a credential. A personal access token. An API key with read/write on the whole workspace. In the worst version I have seen, a shared login to the tracker itself.

Both are bad, and they are bad in ways that do not look like security problems at first. They look like reliability problems.

The snapshot goes stale, quietly

A pasted brief is a snapshot. It was true when it was copied. Ten minutes later somebody narrows the scope in a comment, or attaches the design that answers the open question, and the agent has no way to know. It will complete the task it was given, confidently, and you will find out at review that it was the previous version of the task.

The failure mode is not that the agent is wrong. It is that nothing in the system can tell you the agent was reading a stale copy. There is no version, no timestamp, no way to ask "is this still current?".

The credential is too big, always

So the obvious fix is to give the agent live access. And the moment you do that with a normal token, you have handed a process that generates text the ability to change your workspace.

Think about what a standard workspace token can usually do: read any ticket, comment anywhere, transition anything, sometimes delete. You needed exactly one of those powers - read this one task and the things it points at. You granted all of them, for as long as the token lives, which is usually forever.

And you granted them to the wrong identity. A shared token is not "the agent" or "the runner", it is whoever created the token. Every action lands in the audit log under their name. Six weeks later, when you are trying to work out who moved the ticket, the log says a person who was on holiday.

What a bounded credential looks like

The version that actually works is narrower on four separate axes, and it is worth being explicit about all four, because most homegrown solutions get two right and forget the others.

Read-only. Not "read-mostly". The capability the agent starts with should have no ability to deliver, transition, comment, or edit anything. If the agent's report is going to move the task forward, that should be a separate, later, deliberately authorized action - not something the same credential could do at any moment.

Rooted at one resource. Scoped to this claim, on this task. Not to the project, not to the team. If the agent follows a link out of the task to something it was not granted, the answer should be a refusal, not a helpful response. This is the axis people skip, because project-wide scoping is so much easier to build.

Expiring. Days, not months. The task will be done or abandoned long before then. A credential that outlives the work it was minted for is just a key under the doormat.

Revocable independently. Turning off agent access for the team should reject connections immediately, without deleting them and without anybody having to hunt down individual tokens.

Wagglet's handoff is built on exactly this shape: when a teammate claims a task, the copied prompt carries a read-only, claim-rooted context capability plus a fallback snapshot. The agent can refresh the permitted current context - so the staleness problem goes away - but that starting capability cannot deliver or change anything. The details are in the MCP workspace guide, and the surrounding flow is on how it works.

Identity stays with the person

The other half of this, which is easy to miss: the runner uses their own agent subscription. Their own Claude Code or Codex account, their own token balance. Nobody shares an agent login to move a task, which is the practice this whole pattern exists to kill.

That matters for a boring reason and an interesting one. The boring reason is terms of service. The interesting one is that "who ran this" and "who prepared this" are genuinely different facts, and a shared login collapses them into one name. Once collapsed, you cannot answer basic questions about your own process.

The cheap version, if you are not adopting anything

You do not need a product to get most of this. If you are rolling your own handoff today:

Mint a token per task, not per person, and give it read scope only.
Set an expiry you would be comfortable defending, then halve it.
Put the resource id in the token's scope and enforce it server-side, not in the prompt. A prompt instruction to "only read ticket 412" is a suggestion.
Log the human runner as the actor for anything the agent causes, and keep the agent's own report as evidence rather than as a state change.
Make the delivery step a separate call with a separate authorization, so "the agent said it is done" and "the task is done" stay different facts.

The pattern is not complicated. It is just narrower than the credential you already have lying around, which is why almost everybody reaches for the wrong one first.

More on the task-design side of this: the dual prompt.