todo-update

Manually change a task node in the TODO.md tree. Use for /todo-update [--status in-progress|blocked|ready|drop|revert] [--note ""], where ID may be dotted like FEAT-002.1. Changes markers, drops a node with its subtree after confirmation, and edits Title, Done when, Ref, Depends, From, State, Complexity, Priority or Lane in place using only text the user supplied.

/todo-update

First load the todo core skill (tree format, complexity, invariants, guardrails). For --status in-progress also read ../todo-continue/SKILL.md (steps 3-5), and reference/git-flow.md and reference/verification.md from the core's folder; for --status ready on a claimed root, reference/git-flow.md. If the core is not available as a skill, read them under ../todo/.

Check git (core, "Git mode"); in a non-git folder print the core's warning and continue. Run the invariant check first. With neither --status nor --note, show the node's lines and change nothing. If the ID is in CHANGELOG.md, refuse to reopen it and suggest /todo-add "<description>" --type fix --from <ID> on the base. Otherwise, if <ID> is not in TODO.md, list the IDs that are and change nothing.

Status changes

  • --status in-progress: refuse if another task is [/] and suggest ready for that one first. Refuse if the node is not workable (open children, unmet Depends:, blocked ancestor, tree claimed by another branch) or its State: says next: decompose (suggest /todo-continue, which breaks it down), and say why. Otherwise do /todo-continue steps 3-5 for it (ready check, branches with the tree claim, [/], State:, start commit). It builds nothing; /todo-continue resumes from there.
  • ready, blocked and revert act where the node's state lives: [/], [!] and [x] live on the tree's branches, while the base shows the node as [ ]. Except for a claim release (below), which runs from any branch: for a node in a claimed tree, if you are not on the branch that shows its state (its own todo/<ID>-… branch when one exists, else its parent's), name that branch and stop; do not switch. A node of an unclaimed tree is changed only on the base. Judge the marker in the checked-out TODO.md.
  • --status ready, by the node's marker:
    • [ ] root whose State: in git show <base>:TODO.md names a branch (a tree claim): release it. Check whether it is stale: does the branch still exist in this clone (local, or remote-tracking refs already fetched)? If it is live, say so with the branch's last commit date, require an explicit yes, and warn that the owner's branch keeps its [/] and State: and will conflict if merged later. Require a clean tree; on a todo/ branch with uncommitted backlog edits, first commit them there as chore(backlog): pending edits <IDs> (backlog files only, by path). Switch to the base (in the main checkout, core "Git mode"), delete the root's whole State: line (it holds only the claim), commit TODO.md alone as chore(backlog): release <ID> (a direct base commit, like the tree claim; other uncommitted backlog edits on the base: ask the user to commit them with a claim or stash them first, and stop), and switch back. The branch is kept unless the user asks to delete it. Nothing else changes.
    • [/] or [!]: set [ ] (a [/] abandons the attempt; its branch is kept) and delete Blocked: (its gist goes in your reply, not the file). Write State: attempts 0/3; branch <the node's own todo/ branch> from <its parent's branch, or the base for a root>; next: resume (no branch item when it has none; no git: attempts 0/3; no git; next: resume, plus a root's files:/docs: kept in its Blocked: action part). On a todo/ branch commit TODO.md as chore(backlog): ready <ID>; on the base leave it uncommitted (a backlog edit). /todo-continue then reuses that branch (git-flow "Start commit").
    • Any other [ ] node: say it is already ready and change nothing.
  • --status blocked: set [!], replace State: (or add as the last field line) with Blocked: in the core format, built from --note and the last failing command. For a manual block with no failing command, write n/a (manual) as the middle part. If --note gives only a reason, the action is resolve this, then run /todo-update <ID> --status ready (written without quotes); ask only when even the reason is missing. In no-git mode a root's rolled-up files:/docs: go into the action part as (files: …; docs: …). On a todo/ branch commit it as chore(backlog): block <ID> (on a [/] node, together with its changed files by explicit path, as /todo-continue "Test failures" does); on the base leave it uncommitted (a backlog edit); on any other branch, name the base and stop. Then stop autonomous execution and do not pick up another node.
  • --status drop: refuse on [/] (set it ready first), on [x] (use revert), on a claimed root (release the claim first), and when any descendant is not [ ] (name them and what must happen first); a node inside a claimed tree is dropped on its parent's branch (its nearest ancestor branch that exists; from elsewhere, name that branch and stop); if the node has its own todo/ branch, list its commits and print git branch -D <branch> for the user (the skill does not run it). Require a reason in --note, otherwise ask. List the node, its whole subtree, and every task that names any dropped ID in Depends: or From: with your proposal to remove or re-point each reference, and ask for confirmation. Then delete the node and its subtree, apply the reference changes, update any ancestor sizes given, and lint (a parent left without children becomes a leaf: check its complexity and any size still fit, and ask if not). So the ID is never reused (core "IDs"): when docs/plans/PROJECT.md exists, append - <date +%F> · <reason> · dropped <IDs> to its ## Revisions; otherwise offer to create docs/plans/PROJECT.md holding only ## Revisions and that line (a backlog file; ask first when docs/ is missing), telling the user that without it the ID could be reused. In git mode on a todo/ branch, commit the change as chore(backlog): drop <ID> - <reason> (backlog files only); on the base leave it uncommitted (a backlog edit). With an RTM (../todo/reference/rtm.md) remove each dropped ID from its Tasks cell in the same change. Never write dropped tasks to CHANGELOG.
  • --status revert: only for an [x] node whose parent is [ ] (roots never are [x]); if the parent is [/], refuse and suggest /todo-update <PARENT-ID> --status ready first. Set the node and every descendant back to [ ], each with State: attempts 0/3; next: redo after revert, so the work is redone from the leaves up; on a todo/ branch commit it as chore(backlog): revert <ID>. In git mode, to undo the code too, print for the user (the skill does not run it): git revert --no-commit -m 1 <merge commit>, git checkout HEAD -- TODO.md CHANGELOG.md (keep the backlog as it is now), git commit -m "Revert <ID>".

Field edits

--note with ready, in-progress or revert is refused. --note without a status: if the note starts with Title:, Done when:, Ref:, Depends:, From:, State:, Complexity:, Size:, Priority: or Lane:, replace that part with the user's text verbatim. Otherwise tell the user the note was not applied; notes have no field of their own.

  • Done when: must keep at least one backticked non-vacuous command and must not contain a forbidden command (I3, I10).
  • Lane: only on roots (name: lowercase letters, digits, dashes).
  • Complexity: is low, mid or high. Size: (optional, - removes it) must match the tree (core). Priority: only on roots.
  • A new Ref: path must exist, and Depends: / From: IDs must exist, otherwise ask. A Depends: that would create a cycle is refused.
  • A user edit of State: is one way to reset the attempt counter (--status ready is the other).

Field edits are refused on [x] nodes and, from outside the tree's branch, on nodes of a claimed tree. Only text the user supplied may change a field. Never rewrite Done when on your own. Re-run lint after any edit and reply with the updated task lines (or a one-line confirmation for a drop). Do not start work.