BenchBox: Skill for Claude Code

Todo — Idea to Done

The tracker is driven through MCP tool calls on the todo-db server, not shell commands. Task state is JSON (index.json plus one items/<id>.json per item) published on a dedicated Git state branch, one commit per operation. The todo-db CLI keeps bootstrap, validation, migration, and recovery for humans and CI (listed at the end of this page). Never hand-edit state-branch files; every change goes through a tool so publication stays atomic.

This is the only tracker skill. There is no separate todo-db skill: todo-db is the product this skill drives — the MCP server named todo-db and the CLI of the same name. Do not author a second skill for it, in this catalog or in the product repository.

Critical rules

• Call get_instructions first in a session. It returns the live protocol and, on clients that supply no explicit actor, pins your worker identity.
• Drive through MCP tools, never the shell. Do not invoke tracker verbs through the todo-db floor CLI, hand-edit state, or invent a second store. Use Bash strictly for repo test suites, linters, and builds.
• Fail-closed preflight. If the todo-db MCP tools are absent from your tool registry, stop and tell the operator to register todo-db-mcp (references/bootstrap.md). Do not reconstruct the backlog from files or chat history — the state branch is the only source.
• One server instance is one worker identity. Run separate servers with different --actor values for concurrent workers.
• One live claim per worker. Taking a second item without releasing or finishing the first is refused with E_MULTIPLE_CLAIMS.
• Only the claim holder may renew, finish, or release an item. Keep the generation returned by take; after a restart, take the same item again to re-adopt it (fresh generation, refreshed lease — any earlier process image holding the old generation goes stale).
• Take over a foreign live claim only when its session cannot resume. takeover(item_id, expected_holder, reason) transfers a live claim held by another worker: name the exact holder you inspected with show_item and say why that session is dead. It is refused when the task has no live claim (use take), when you already hold it (use take to re-adopt), when the holder changed under you (re-read, then decide), or when you hold another live claim (E_MULTIPLE_CLAIMS). Batch ownership held by the displaced worker transfers with the item. Requires todo-db 0.8.1 or later.
• Prepared work is not completion. The prepared lifecycle is fail-closed and capability-versioned: register_batch must first persist one project / repository identity, owner generation, integration branch/worktree and immutable start head, ordered members, frozen scope, delivery boundary, terminal outcome, and (later) one final PR identity. Register each member's explicit implementation edge, then take and prepare it with a clean exact checkout, actual member base, accepted head, current integration head, scope hash, and passed bounded-suite evidence. prepare releases the claim while leaving the item open; it does not mark work done. The integrator verifies the cumulative current tree and binds the final PR before re-taking and finishing members. If the server does not advertise the registered-batch contract and compatible schema version, stop and use serial mode; never treat legacy per-item receipts as valid. Ordinary dependencies remain done-only; prepared receipts never unlock review, approval, merge, deployment, or soak gates.
• Skill-only actions — ideate, spec, prioritize, batch, handoff, closeout — are workflows, not tools. Follow their reference guides.
• Close-out authorization. closeout is write-shaped under shared-review-protocol/SKILL.md §1 ([REVIEW-AUTH-001]). A message that explicitly invokes closeout — alone or paired with review or validation — authorizes it that turn. A message asking only to review or validate stays review-only: report findings and stop until a later message authorizes closeout.