todo-list

Use when the user invokes /todo-add, says "add a new project", "create a project for X", "start tracking X", or describes a new feature/initiative to track. Scaffolds the project folder + index.md row; the step before /todo-plan.

Use when the user invokes /todo-archive, says "compact tasks.md", "archive this project", "clean up the hub", "tidy the index", "this tasks file is huge", or a SessionStart archive-candidate report appears. Losslessly moves completed revision detail to anchored journal entries, leaves direct tombstones, and moves completed project rows from active index.md to cold archive.md.

Use when a todo-* skill needs the hub's shared contract — resolving paths against $TODO_HUB, looking a project up active-first then archived, validating a value before it reaches a shell, counting real task checkboxes, naming a task by its ID, reading a revision tag, deciding whether code work is shipped, gating a status flip on the project graph, or choosing between an act-now command and a next-session handoff. A reference, not a workflow; nothing here is invoked directly by the user.

Use when the user invokes /todo-execute, says "execute this project", "work through tasks", or names a hub project and wants work done, including concurrently with phrases such as "execute these tasks in parallel", "work multiple features of the same repo at once", or "fan this out with worktrees". Sequential by default; parallel mode fans file-disjoint tasks out to worktree agents.

Use when the user invokes /todo-graph, asks "what can I start?", "what's blocked and why?", "what does finishing X unlock?", how tracked projects depend on each other, requests a dependency path or graph audit/export, or wants to add/remove a typed project relationship. Also lists one project's real tasks with their IDs for other skills. Answers from a deterministic project graph and never guesses dependencies from prose. For "what's left and which model should do it", use todo-triage instead.

Use when the user invokes /todo-infographic, asks to visualize a hub project, or current-session plan/task edits make its infographic stale. Builds or incrementally refreshes artifacts/infographic.html and registers it without rebuilding unchanged visual structure.

Use when the user invokes /todo-learn or wants the agent to behave differently in this repo from now on — says "don't do that again", "next time do Z", "learn from this", "make that a rule for this repo", or "always/never do X here". Records one standing rule in the working repo's skill files (`.agents/skills/`, mirrored to `.claude/skills/`) so Claude Code and Codex both follow it next time. Not for fixing a hub project's delivered work — "the result isn't what I expected" is /todo-revise — and not for the host's own memory of personal facts.

Use when the user invokes /todo-list, asks to list projects, wants the status overview of all projects ("what am I working on", "how far along is everything"), asks to show completed/archived projects, or says "sort the index", "rank projects by progress", or "reorder index.md". Hub-wide overview only — one project's context or where-was-I is todo-refer, and changing or auditing recorded state is todo-state. Default view reads active index.md plus one progress count; archive view reads cold archive.md; sort reorders active rows only.

Use when choosing a Claude Code or Codex model for todo-list work, mapping capability tiers across providers, or balancing model cost, accuracy, and reasoning effort.

Use when the user invokes /todo-plan, says "plan this project", "replan X", "update the plan", "break X into tasks", or names a hub project and wants its plan created or revised. Runs discovery, verifies the target repo exists locally, then writes the hub project's plan.md and tasks.md — not a writer for generic implementation plans outside the hub.

Use when the user invokes /todo-push, says "ship this", "push this up and merge it", "checkout from main, commit, push, create PR, merge to main", or describes the full branch-to-merge git workflow (not a single git step). Works in any repo, not just the hub.

Use when the user invokes /todo-refer or wants one hub project's context — says "refer to project X", "pull in the context for X", "give me the plan for X to review against", or wants a project's plan/tasks loaded before another command — and equally for where-was-I on one project: "where was I", "pick up where we left off", "continue the migration project", "what happened last session", "what's the state of X", or a fresh session on a project with prior work. Also handles "what happened in R4"-style revision history questions. Replaces the former /todo-resume, which is now this skill's `resume` mode — treat that spelling as an invocation of this skill. Read-only, one project, active-or-archived, and cross-repo; the all-projects overview is todo-list, and changing or auditing recorded state is todo-state.

Use when the user invokes /todo-review, says "review this against the plan", "does the diff match the plan", "check this work before verify", "review what the agent built for X", "review what the parallel wave merged", or has changes in a repo that belong to a hub project and wants them reviewed. Reviews a diff against the project's plan.md — scope, constraints, claimed-done tasks — plus a correctness pass.

Use when the user invokes /todo-review-handoff, says "hand this review to someone else", "turn the review into a document her agent can run", "let the PM judge these findings", "make the review checkable", "package this review for another team", or has review findings that a different person — often non-engineer — must rule on before anything is fixed. Converts findings into numbered falsifiable claims plus a ruling sheet, so the recipient's agent proves or refutes each one and the recipient decides which get addressed. Does NOT review code itself (it delegates that) and never applies a fix.

Use when the user invokes /todo-revise, says "fix R7", "fix the verify failures", "this drifted", "give feedback on what's done", "the result isn't what I expected", "revise this", "what's the gap on X", or names a hub project and wants its delivered work fixed against expectation. Fixes this project's delivered work — captures each gap as a Revisions entry, fixes it in a worktree, then hands off to verification and shipping. A correction to how the agent should behave next time belongs to /todo-learn.

Use when the user wants to change or audit a hub project's recorded state — invokes /todo-state, says "mark X as done", "tick off task Y", "uncheck that", "add a task to X", "reword task 2.3", "set this to in-progress", "reopen this archived project", "mark this project done", or wants to record progress without a full execution pass — and equally when they say "is the index accurate", "does the todo match reality", "audit my project statuses", "this says done but it never shipped", or suspect hub state has drifted from what actually happened in the repos. Edits tasks.md and the owning active or archived registry row in sync; `audit` only reports drift against tasks and git evidence, and `audit fix` applies it after one confirmation. Not for looking: the all-projects overview is todo-list, and one project's context or where-was-I is todo-refer. Replaces the former /todo-update-state (now the default mode) and /todo-sync (now `audit`) — treat either of those spellings as an invocation of this skill.

Use when the user invokes /todo-style, says "install the briefing style", "make the agent answer like an executive briefing", "swap my CLAUDE.md", "back up my CLAUDE.md before changing it", "use the todo-list response style", "restore my old CLAUDE.md", "undo the style pack", "uninstall the style pack", or "which style pack version do I have". Backs the current global agent instruction file up into the hub, then installs the bundled response-style pack for Claude Code and Codex. Never runs unprompted and never overwrites without a verified backup.

Use when the user invokes /todo-triage, says "what's left", "tabulate remaining work", "which model should handle this", "triage my tasks", or wants a cross-project table of open tasks with a recommended model per task. Read-only — tabulates and recommends, never edits.

Use when the user invokes /todo-verify, says "verify this project", "did the e2e pass", "run the verification layer", or names a project and wants its verification result reconciled into the todo. Detection only — reads results, ticks tasks, flips status, opens Revisions on failures and records coverage gaps as advisory; never edits code.