developer-os Install

Skills / Engineering

implement-backlog

Implements evidence-backed backlog items in small batches, validates every item and the whole batch, gets an independent review, updates the backlog and plan, and commits only green work.

Group
Engineering
Kind
Action
Writes
Code, the backlog (Owner lines, checked items), the plan, the state card, local commits
Asks before
Auth and security items and unscreened Check commands, once up front
Needs
A backlog in the audit-to-backlog format

When it runs

When you invoke it by name or ask it to execute an audit backlog. It takes an optional category, task ID or --batch N.

What it does

  1. Starts from a green baseline. It finds the backlog from the Backlog: line (otherwise TODO.md and TODO-done.md), reads it with the active plan and recent history, and runs the repository's real validation commands. A red baseline stops the run with the failures and a question.
  2. Picks the batch. By default, the ready items of the first unfinished implementation session that has any; without sessions, the highest-priority related items, five by default and ten at most. A category prefix, a task ID or --batch N overrides that. Ready means open, every Blocked by item done, and no other Owner. Only items in the backlog format are taken; other open lines are listed as unformatted.
  3. Asks once, up front, whether to include items that touch authentication or security boundaries, and about any Check that needs a question.
  4. Screens every Check. It never runs one that pipes into a shell, fetches from the network or writes outside the repository; that item is blocked for you to resolve. The project's own test, lint, type-check or build commands run without a question. A script in the repository is read first, and its result is always the command's actual output, never a verdict inferred from the source.
  5. Claims the batch. Before any brief it writes an Owner: <worktree> (<date>) line under each item and commits them as one commit, so parallel worktrees see the claim. When the backlog is git-ignored, the lines, their release and the checked-off items stay uncommitted, and the batch runs one item after another. An Owner older than 7 days is orphaned and is cleared only after you confirm.
  6. Delegates. Independent tasks with disjoint files run in parallel, each in its own git worktree; otherwise they run one after another. Everything is integrated on a local batch branch, and the base branch gets it only by a fast-forward after the review passes; if the base moved, both branches are left for you. The brief grows with the item's size: S gets the objective, location and Check; M also the Done when and files not to touch; L only writes a plan and stops for approval. Every report opens with DONE, REVIEW, BLOCKED or CONTINUING; transient failures are retried at most twice. While delegates run, it only orchestrates.
  7. Reads the reports. On DONE it runs the Check itself in the delegate's worktree, then again after integrating (a sequential item once, in the current checkout); a Manual: item is committed but stays open without its Owner, with steps for you to confirm; REVIEW means approving or rejecting a plan; BLOCKED on you goes under Needs you; CONTINUING is dispatched again. A report without a status goes back once.
  8. Validates. The item's Check after every item, then the full build, type check, tests and lint for the batch, showing only failures. Test failures are classified before editing; assertions change only for a contract that changed. A wrong Done when gets a proposed Amended line, never an edit. Three failed repair cycles stop the run in a deployable state. A short state card in docs/plans/.devos-state.md survives a context compaction.
  9. Reviews and records. The batch diff goes through code-review and the independent reviewer agent. It fixes confirmed P0/P1 and docs findings itself, for at most two review rounds. The review passes on APPROVE, or on a COMMENT whose question you answered; without a pass the base branch gets nothing and the batch branch is left for you. Other findings are proposed as backlog items for your approval; done items move to the done file with their Check result. It stages only batch files and commits only when everything passes, then reports one line per item and the next batch.

Example output

docs/plans/.devos-state.md
Plan: docs/plans/2026-10-15-checkout-retry.md
Item: CART-12 (in progress)
Agents: .worktrees/cart-13 → CART-13, .worktrees/cart-14 → CART-14
Unverified: <claims without evidence yet>
Next: <one line>

Boundaries

Stops when

The batch is committed locally, or earlier at a red baseline, after three failed repair cycles, or after two review rounds without a pass. It deletes the state card and returns the validation evidence, the review additions and the next batch. Claimed items still open lose their Owner line, so the next run can take them.

Never

  • Push or force-push, merge or rebase a shared branch, or open a PR.
  • Include authentication or security items you did not approve up front.
  • Delete or skip tests, or change assertions for a contract that did not change.
  • Commit red work or files outside the batch, other than the docs a docs finding named and the Owner claim and release commits, which touch only the backlog file.
  • Edit or delete a Done when, or take an item another worktree owns.
  • Implement a backlog item itself while a delegate is running.
  • Dispatch or start an item before its Owner line is committed (only written, when the backlog is git-ignored), or force-add an ignored backlog file.