Update a dependency / migration
One library, one changelog, one diff — not three half-finished upgrades in a trench coat.
Dependency upgrades succeed when the agent can hold one library's breaking changes in its head. They fail when the prompt says 'upgrade everything' and the agent fans out across five changelogs at once. This template restricts the upgrade to one library, names the breaking changes to handle, and forbids opportunistic refactors.
When to reach for this template.
- You're bumping a single library across a major version with documented breaking changes.
- The changelog or release notes are linkable from the prompt.
- You can grep for the removed APIs the agent has to replace.
- You're willing to defer 'while we're at it' bumps to their own tasks.
The template.
Drop this into .watchfire/tasks/<n>.yaml, edit the prompt and acceptance_criteria to match your repo, and let the daemon run it.
task_id: depbump5
task_number: 5
title: "Upgrade pino from 8.x to 9.x"
prompt: |
Upgrade `pino` and `pino-pretty` from 8.x to
the latest 9.x release in `package.json` and
`package-lock.json`. Read the pino 9.0 release
notes (https://github.com/pinojs/pino/releases)
and handle the documented breaking changes —
in particular the changes around
`transport` options and the removal of legacy
level-by-string helpers.
Where the codebase uses removed APIs (search
for `pino.levels` and `pino.symbols`), update
the call sites to the 9.x equivalents. Do not
add a compatibility shim.
Out of scope:
- Upgrading any other dependency.
- Reorganising log structure or fields.
- Switching transports.
acceptance_criteria: |
- `pino` and `pino-pretty` resolve to 9.x in
`package.json` and `package-lock.json`.
- No usage of removed pino 8.x APIs remains
(grep clean).
- `npm run test` passes with no warnings about
deprecated pino APIs.
- `npm run lint` passes with no new warnings.
- The application boots locally with the same
log output shape as before
(`npm run dev` succeeds).
status: ready
Common pitfalls.
The shapes of failure most often seen on this kind of task — and the way this template hedges against each.
- Bundling multiple bumps into one task. When the build breaks, you can't tell which library's breaking change did it — the task becomes an unreadable debug session.
- Not linking the changelog. The agent will rely on its training-cutoff understanding of v9 and miss the breaking change that landed in v9.2.
- Letting the agent add a compatibility shim. Once you have a shim, you also have technical debt; force the rewrite at the call site.
- Skipping the runtime check. 'Tests pass' isn't enough — `npm run dev` boots cleanly and the log output shape is the same.
Related templates.
Refactor / rename
A mechanical move kept mechanical — so the diff stays cheap to review.
Open the template
Add tests for an untested module
Backfill coverage against a named bar — not the agent's idea of 'enough tests'.
Open the template
Investigate and report (no code changes)
Diagnosis only — the artifact is a Markdown report, not a patch.
Open the template
Pair it with a playbook.
These use-case playbooks lean on tasks shaped like this one.
Build your own.
This template is a starting point. Fill in a form to draft your own task in the playground — or read the full task schema to learn every field the daemon understands.
Get started with Watchfire
Install in seconds. Define tasks. Let agents ship code for you.
Download for macOSAvailable for macOS, Linux, and Windows
# Install via Homebrew (macOS)brew tap watchfire-io/tapbrew install --cask watchfire-io/tap/watchfire# Set up your project and gowatchfire initwatchfire task add "Build the login page"watchfire start --allIncludes GUI, CLI, and daemon. Also available via Homebrew.