skills/todo-work/SKILL.md
List pending items from TODO.md, pick one, mark it In progress, and hand off directly to /review-plan or /implement.
npx skillsauth add nexus-a1/claude-skills todo-workInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Companion to /todo. Surfaces pending items from TODO.md, lets the user pick one, optionally marks it as In progress, and hands off directly to the chosen downstream skill (/review-plan or /implement) via the Skill tool — no manual re-invocation required.
/todo is append-only — it captures items but never surfaces them back out. This skill closes the loop: read TODO.md, filter to pending items, pick one, and kick off work with a single interactive flow.
TODO.md/todo/resume-work/work-status/todo-work [item number]
item number (optional): 1-indexed position in the sorted pending list. If provided, skip the pick question and jump to the next-action question.
TODO_FILE="TODO.md"
If TODO.md does not exist in the project root, stop with:
No TODO.md found in the project root. Use /todo to add your first item.
Otherwise, read the full file with the Read tool.
Extract every ### {title} block. For each block, pull these fields (match case-insensitively, accept the value on the same line):
**Status:** {status}**Priority:** {priority} (strip leading emoji)**Category:** {category}**Scope:** {scope}Plus the free-text description (everything between the metadata block and the next --- or ### heading or end-of-file).
Keep only pending items. An item is pending if its status matches (case-insensitive): Proposed, Not started, Needs discussion. Skip anything else (In progress, Done, Completed, Archived, etc.).
If the item is missing any of the four metadata fields, treat the missing field as unknown — do not drop the item. Record which field was missing so the list display can flag it with (missing metadata).
Sort pending items by priority (emergency → high → medium → low → unknown), with document order as tiebreaker. Number them 1..N in the sorted order; this number is what the optional [item number] argument selects and what the user sees in the list.
Priority sort key (higher wins):
emergency = 4high = 3medium = 2low = 1If zero pending items, stop with:
No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.
If $ARGUMENTS contains a positive integer N and 1 ≤ N ≤ count(pending): Use item N. Skip the inline list and AskUserQuestion entirely.
Otherwise (no numeric argument):
Print the full pending list inline, using the 1..N sorted index from Step 3.
Header: Pending TODO items ({N} total):
Format, one line per item:
{N}. [{priority}] {title}{ (missing metadata) if any of the four fields was unknown}
Example:
Pending TODO items (7 total):
1. [medium] Integrate playwright-engineer into /implement QA phase
2. [medium] Knowledge Sync workflow implementation
3. [medium] Consider changing todo list to JSON
4. [medium] Update 'todo-work' skill to list existing items
5. [low] Evaluate Garry Tan's plan mode prompt
6. [low] Expand agent test coverage
7. [low] Implement true action-based audit trail
Titles only — no descriptions, categories, or scope in the inline list (those stay in the AskUserQuestion option descriptions for the top 3).
Then use AskUserQuestion to pick from the top 3 as quick-select shortcuts:
"Pick item""Which TODO item should we work on?"Cancel; each item label is short, description shows priority + category + scope):
{title} / priority · category · scopeCancel / Don't start any item — exitfalseThe AskUserQuestion tool enforces a maximum of 4 options, so the pick list must stay at 3 items + Cancel. If more than 3 pending items exist, include this note above the question: "Showing top 3 as quick-select options. Use /todo-work {N} to jump to any item from the list above."
If the user picks Cancel, stop with: No item selected.
Display the selected item:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Selected: {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Priority: {priority}
Category: {category}
Scope: {scope}
Status: {status}
{description — if present}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Then use AskUserQuestion:
"Next action""How do you want to start on this item?""Validate plan first (Recommended for non-trivial)" / "Hand off to /review-plan — architect and quality-guard review the plan before implementation""Implement directly" / "Hand off to /implement — skip plan review, go straight to coding""Just show details" / "Print the item and stop — no handoff, no status change"falseIf the user chose Just show details: Skip to Step 9. Do not modify TODO.md.
Otherwise: Update the selected item's status line in TODO.md from its current value to In progress using the Edit tool.
Find the exact line by matching the heading + the Status line belonging to this item. Use this Edit pattern:
old_string:
### {title}
**Status:** {current_status}
new_string:
### {title}
**Status:** In progress
If the Edit fails (e.g., because {title} or {current_status} is not unique in the file), surface a warning and continue without updating — do not abort the handoff:
⚠️ Could not mark item as In progress (status line not unique in TODO.md).
Handoff will proceed; update the status manually if needed.
If the user chose Just show details: Skip to Step 9. No worktree.
Otherwise: Create a git worktree off the remote default branch with a new feature branch so downstream code changes happen in isolation from the current working tree.
Derive a slug from the selected item's title:
the, a, an, to, for, of, add, update, fix).-.[a-z0-9-].[A-Z]+-[0-9]+), keep it as {TICKET}-{slug}. Otherwise use the slug alone (no prefix).Detect the default remote branch and create the worktree:
DEFAULT_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|^origin/||')
if [ -z "$DEFAULT_BRANCH" ] || [ "$DEFAULT_BRANCH" = "HEAD" ]; then
DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | awk '/HEAD branch/{print $NF}')
fi
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
REPO_ROOT=$(git rev-parse --show-toplevel)
if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
source "$HOME/.claude/shared/resolve-config.sh"
fi
WT_ROOT=$(resolve_worktree_root 2>/dev/null || echo ".worktrees")
WORKTREE_PATH="$REPO_ROOT/$WT_ROOT/{branch-suffix}"
git fetch -q origin "$DEFAULT_BRANCH"
git worktree add -b feature/{branch-suffix} "$WORKTREE_PATH" "origin/$DEFAULT_BRANCH"
resolve_worktree_root reads worktree.root from .claude/configuration.yml when present, falling back to .worktrees/ — matching the pattern used by /refactor, /update-documentation, and /implement.
Where {branch-suffix} is the value derived in step 1 (e.g., JIRA-123-webhook-support or broken-readme-link).
Enter the worktree using the EnterWorktree tool with path: {WORKTREE_PATH} (the absolute path from step 2). EnterWorktree with path: enters an already-registered worktree; git worktree add above registers it, so git worktree list will include this path. From this point the session is isolated.
If the worktree already exists (branch name collision), surface a warning and continue without creating one — the user can run the handoff command in the existing worktree manually:
⚠️ Worktree feature/{branch-suffix} already exists. Continuing in current tree.
Switch manually with: cd $WT_ROOT/{branch-suffix}
If git fetch or worktree creation fails for any other reason, surface the error and continue with the handoff in the current tree — do not abort.
Print a one-block launch notice, then invoke the chosen skill via the Skill tool. The session is already inside the new worktree from Step 8 (when one was created), so the chained skill runs in that isolated context. If EnterWorktree was skipped or failed, the chained skill runs in the current tree — drop the Worktree: line from the notice in that case.
For Validate plan first → /review-plan:
Print:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Handing off to /review-plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Item: {title}
Status: {Proposed|Not started|Needs discussion} → In progress
Worktree: .worktrees/{branch-suffix} (branch feature/{branch-suffix}, from origin/{default-branch})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Then invoke (use the plain skill name — no nexus: prefix):
Skill(skill: "review-plan", args: "{title}\n\n{description}")
If the description is empty, pass just {title}.
For Implement directly → /implement:
Print:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Handing off to /implement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Item: {title}
Status: {Proposed|Not started|Needs discussion} → In progress
Worktree: .worktrees/{branch-suffix} (branch feature/{branch-suffix}, from origin/{default-branch})
Note: /implement requires prior requirements from /create-requirements.
If no state.json exists for this item, /implement will surface that
and prompt you to run /create-requirements first.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Then invoke (plain name, title-only — /implement looks up state.json by identifier):
Skill(skill: "implement", args: "{title}")
For Just show details:
No invocation. Print and stop:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Priority: {priority}
Category: {category}
Scope: {scope}
Status: {status} (unchanged)
{description — if present}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/todo-work
Prints the full pending list inline (all N items, one per line with priority + title), then shows the AskUserQuestion with the top 3 as quick-select. User picks item #2 ("Add webhook support"). Chooses "Validate plan first". Skill updates status to In progress, creates the worktree, prints the hand-off notice, and directly invokes /review-plan with the item title and description.
/todo-work 1
Jumps straight to item #1 ("Fix broken link in README"). User chooses "Implement directly". Status flips to In progress, the worktree is created, and the skill directly invokes /implement Fix broken link in README (which will surface a missing-state.json error and prompt the user to run /create-requirements first if no prior requirements exist).
/todo-work
User picks item #3, chooses "Just show details". No Edit to TODO.md, no hand-off — just prints the item details and stops.
/todo-work
Output:
No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.
No TODO.md found in the project root. Use /todo to add your first item.
No pending TODO items. Use /todo to add one, or /work-status to see active work sessions.
/todo-work 99 when 5 items pending)No item #99 — only 5 pending items. Re-run /todo-work to pick interactively.
Warn and continue with the handoff (see Step 7).
.claude/work/ files; optionally reads worktree.root from .claude/configuration.yml (falls back to .worktrees/).worktrees/{branch-suffix}/ on a new feature/{branch-suffix} branch off the remote default branch before handoff (skipped for Just show details); failures fall back to the current treeTODO.md via one Status: line changeSkill tool (plain skill names, no nexus: prefix). The hand-off notice is printed as a record of what was launched and as a fallback display if the Skill call fails(missing metadata) marker, not droppeddevelopment
Add a new entry to the product knowledge base. Wizard-guided — prompts for category, title, and content, then writes a structured markdown file and rebuilds the manifest.
data-ai
Show all active work sessions across brainstorms, requirements, proposals, and epics. Supports --update to advance lifecycle on one session and --sync to sweep them all.
documentation
Review and update project documentation using an agent team. Inventories docs, identifies gaps and drift, updates technical and API docs in parallel.
tools
Annotate an active work session with a note, scope change, or new finding. Auto-detects the active session, synthesizes the salient points of the current conversation, and appends a timestamped entry to state.json after a single target confirmation. Use mid-session when you learn something that should be preserved.