From nexus
List pending items from TODO.md, pick one, mark it In progress, and propose a hand-off to /review-plan or /implement.
npx claudepluginhub nexus-a1/claude-skills --plugin nexusThis skill is limited to using the following tools:
Companion to `/todo`. Surfaces pending items from `TODO.md`, lets the user pick one, optionally marks it as `In progress`, and proposes a hand-off to the downstream skill (`/review-plan` or `/implement`) by printing the exact command to run next.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Companion to /todo. Surfaces pending items from TODO.md, lets the user pick one, optionally marks it as In progress, and proposes a hand-off to the downstream skill (/review-plan or /implement) by printing the exact command to run next.
/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 hand-off block that shows the user the exact command to run next. Do not invoke another skill — slash commands are user-invoked; /todo-work stops after printing.
For Validate plan first → /review-plan:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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})
Run next:
/review-plan {title}
{if description present:}
{description}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
For Implement directly → /implement:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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})
Run next:
/implement {title}
{if description present:}
Context from TODO.md:
{description}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If the worktree step was skipped (already exists or failed), drop the Worktree: line from the handoff block.
For Just show details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{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 and prints the hand-off block with /review-plan Add webhook support (plus the description) as the suggested next command.
/todo-work 1
Jumps straight to item #1 ("Fix broken link in README"). User chooses "Implement directly". Status flips to In progress; the skill prints /implement Fix broken link in README as the next command to run.
/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 change(missing metadata) marker, not dropped