todo-add

Add work to the TODO.md task tree. Use for /todo-add [--priority P0|P1|P2] [--ref ] [--type feat|fix|task] [--from ] [--parent ] [--lane ] [--clarify]. Splits the request into a tree until every leaf fits one context window, rates each node's complexity (low, mid, high), writes each node as a 2-4 line task with an exact Done when command, and inserts it. Never starts work.

/todo-add

First load the todo core skill (tree format, scope rule and complexity, IDs, invariants, guardrails) and read reference/verification.md from its folder ("Writing a Done when"). If the core is not available as a skill, read ../todo/SKILL.md and ../todo/reference/verification.md.

Defaults: priority P1. Unless --type is given, the type is the first rule that matches the description: (1) its first word, or the word after a leading "add", starts with test, doc, refactor, rename or chore → TASK; (2) fix as the first word, or bug, crash, crashes, regression or broken anywhere → FIX; (3) add, implement or support as the first word, or new anywhere → FEAT; (4) otherwise TASK. With --parent, the type is the parent's prefix, and --priority, --lane and --type are refused (children inherit them). Show the chosen prefix in the result.

Steps

  1. Git mode and invariants. Check git; in a non-git folder print the one-time warning (core, "Git mode") and continue. Run the invariant check.
  2. Resolve --ref. If the path does not exist, say so and ask. Anchors (#section) are allowed. If none is given and a doc in docs/ clearly governs the work, propose it. Otherwise omit Ref. Never invent a path. 2b. RTM (optional). Only if an RTM exists (../todo/reference/rtm.md: docs/RTM.md wins, else README ## RTM): when the work implements a listed requirement, link the root Ref: <rtm path>#<Req> (unless --ref is given) and propose the row change (new task IDs appended to Tasks; status is never copied). Written only on confirmation. With no RTM, do nothing and never create one.
  3. Resolve --from <ID>. It must exist in TODO.md or CHANGELOG.md, otherwise ask. It becomes From: (provenance only).
  4. Resolve --parent <ID>. It must be a [ ] node in TODO.md with at most one dot in its ID (a child of a level-2 node would exceed 3 levels), in a tree that is not claimed by another branch (core lifecycle table). The new node becomes its last child; ancestors that carry a size get it updated. Without --parent the new task is a root. --lane <name> (roots only; lowercase, digits, dashes) adds Lane: <name> to its Links:; children inherit their root's lane.
  5. Clarify. Ask one message of at most 3 short questions when the behavior, the target module or the verification command cannot be derived from the description and the repo. With --clarify, always run one such round first. When the request is unclear, read ../todo/reference/clarify.md and apply its checklist and stop triggers. Wait for the answers. Never guess to avoid asking.
  6. Check it is not already done. Search the code and tests for the behavior (names, a quick grep; run the targeted test if one exists, under "Command safety" in reference/verification.md). If it appears to exist already, say so and ask before adding anything.
  7. Split and rate.
    • Apply the core scope rule: a leaf is one change that fits one context window and touches at most 5 files. Anything bigger is a parent.
    • Break a parent into children until every leaf fits, with at most 3 levels. Order the children as the work will run; add Depends: between siblings only when the order is not obvious.
    • No size by default: add one (core table) only when a node already in TODO.md carries a size or the user asks; an empty tree has none.
    • Rate each node's complexity with the core table (low, mid, high; mid when unsure); a parent is rated by its integration step. Rate the reasoning, not the size: a one-file race condition is high, a five-file rename is low.
    • Each node gets a one-sentence "what to do" and a Done when: written by the rules in reference/verification.md, "Writing a Done when": criteria, ; , then a runnable command that targets a test id or path, not a name filter. If the test does not exist yet, name the file or id the node will create. Add regression: \cmd`only when the project's full suite is not the right guard. Never writemanual, n/a`, a vacuous command, or code or prose in backticks: write identifiers and calls bare (calc.power(2, 3) returns 8) and put only the runnable command in backticks.
    • Containers get their own Done when: the integration test or, when the children's tests already cover it, the regression command. A parent's Done when may pass at baseline; only leaves must start red.
    • If an existing test already covers the criterion, the task is not new work: ask instead of naming that test (except a FIX for a test that exists and fails now: name that test).
    • Definition of Ready. Do not write a node that fails the ready check you can already do: the Ref exists, Depends IDs exist, the scope fits, and the command's test target is named.
    • Optional Depends: only for prerequisites the user named or that the breakdown requires. Each ID must exist.
    • If the request needs long design, requirements or a plan (more than 6 nodes, or detail that does not fit in 4 lines), offer to write it to docs/plans/<ROOT-ID>-<slug>.md (compute the root ID now by the core ID rules) and link it with Ref:. Create that file only if the user agrees.
  8. Fit. The result must stay within 120 lines in total. If it would not fit, add only the root and its first level: a first-level node that still needs children gets State: next: decompose (core), and /todo-continue breaks it down when it becomes workable. Say so in your reply and offer the plan file. If even that does not fit, refuse and suggest finishing or dropping something. Do not trim existing tasks.
  9. Confirm. For more than one node, show the proposed tree (IDs, complexity, one-line titles) and wait for confirmation before writing. Add only what the user confirms. A single new leaf needs no confirmation.
  10. Assign IDs (core ID rules: one global sequence across FEAT, FIX and TASK, never reused) and insert. Do not commit; the next claim commit carries the backlog edit. Place a new root where the order puts it, not at the end: P0 → P1 → P2, then by ascending ID within a priority (a P0 root goes above every P1 root); children go at the end of their parent's children. New roots are added only on the base branch: on a todo/ branch, refuse any new root (a --from follow-up without --parent is one) and any --parent in an unclaimed tree, and tell the user to switch to the base. Re-run the invariant check.
  11. Reply with the inserted tree and its position. Do not start work.

Nothing enters TODO.md unless this command created it from the user's request.