Surface next N unblocked taskwarrior tasks by urgency, skipping lock-contending tasks. Use when planning a parallel-agent wave or choosing tasks for a dispatch slot.
Surface next N unblocked taskwarrior tasks by urgency, skipping lock-contending tasks. Use when planning a parallel-agent wave or choosing tasks for a dispatch slot.
Next-candidate-agent surfacing for parallel / wave dispatch. Pairs with agent-patterns-plugin:parallel-agent-dispatch and workflow-orchestration-plugin:workflow-wave-dispatch.
When to Use This Skill
Use this skill when...
Use task-status / task-add / task-done instead when...
Picking the top-N unblocked tasks for a parallel-agent wave
Producing a full queue audit (pending + blocked + drift) — use task-status
Filtering candidates that contend on the same exclusive lock (ghidra, migration)
Filing a new task before there is anything to coordinate — use task-add
Emitting a --wave brief for an orchestrator to fan out
Closing a task that already landed via commit — use task-done
git rev-parse --show-toplevel writes to stderr in a no-git cwd, and
stderr from a Context backtick aborts the skill before its body runs.
Project resolution is done in the body (Step 1 below) via the Bash tool
where 2>/dev/null and exit-code handling are tolerated.
Parameters
Parse $ARGUMENTS:
--n=N — number of candidates to surface (default 3)
--lock=<resource> — exclude candidates that need the named lock (e.g. ghidra, migration, task-bulk)
--wave — format output as a wave brief (orchestrator-ready)
--project=<name> — override the auto-detected project filter
--all — opt out of project filtering (cross-project wave; rare — usually wrong for dispatch)
--include-active — include +ACTIVE (already-claimed) tasks in candidate ranking. Default behaviour excludes them so a wave is never dispatched onto work another agent has already started via .
/taskwarrior:task-claim
--stale-after=N — threshold (hours) for flagging a +ACTIVE claim as stale in the report. Default 4. Stale claims are reported only — never auto-stopped.
Project resolution
Default behaviour is project-scoped. A wave dispatch almost always wants
candidates from a single repo, so cross-project candidates are filtered
out by default. Resolve $PROJECT in this order:
--project=<name> if provided.
--all → no project filter (cross-project wave).
Basename of git rev-parse --show-toplevel 2>/dev/null, run via the
Bash tool (where stderr suppression and non-zero exits are tolerated).
If no git repo (Step 3 returned empty), basename of cwd.
Execution
Execute this workflow:
Step 1: Load unblocked pending tasks
Substitute the literal project name into the filter (no $() command
substitution — shell-operator protections will reject it). Use taskwarrior's
native +READY virtual tag, which means pending, unblocked, not waiting, and
either unscheduled or scheduled before now — so it subsumes the old
-BLOCKED clause AND respects scheduled: / wait: dates. Add -ACTIVE to
exclude tasks already claimed via /taskwarrior:task-claim:
With --include-active, drop the -ACTIVE clause so already-claimed
tasks compete for ranking. With --all, drop the project: clause.
+READY automatically hides wait:-deferred and future-scheduled: tasks,
so a task parked with wait: until a PR merges never appears as a candidate.
Never use task next — exits 1 on empty.
Step 1b: Snapshot in-flight claims
In parallel with Step 1 (these are independent reads), collect the set
of currently-claimed tasks for the report:
Stale claims are surfaced in the report only; task-coordinate never
calls task stop on its own. The orchestrator (or the original claimer)
decides whether to release.
Step 2: Detect lock contenders
Classify each task by the locks implied by its tags or bpid:
Tag / ID prefix
Implied lock
+re on decomp work, tmp/decomp/ in description
ghidra
+migration, bpid starts with MIG-
migration
+bulk_task
task-bulk (taskwarrior itself — single-writer)
Matching bpdoc in shared manifest
manifest
Drop any candidate that matches the --lock= filter. Two tasks that
would contend on the same lock cannot share a wave — keep the one with
higher urgency, defer the other to the next wave.
Step 3: Rank and cap
Keep the top N by urgency. If ties, prefer:
Tasks with a pre-existing bpdoc (scope is already written down)
Tasks without exclusive-lock contention
Tasks with earlier entry (older first)
Step 4: Emit candidates
Lead the output with the resolved project scope so the orchestrator
knows the wave is single-repo (default) or cross-project (--all):
If the rank step dropped any lock-contending candidates, report them as
deferred-to-next-wave with the lock name — the orchestrator decides
whether to pre-dump via exclusive-lock-dispatch or serialise.
Step 6: Append in-flight + stale-claim sections
Always emit two trailing sections so the orchestrator sees the full
state of the project queue, not just the dispatchable subset:
## In flight (claimed)
| Task | UUID | Agent | Branch | Host | Started |
|------|------|-------|--------|------|---------|
| #4 (WO-008) | a1b2c3d4 | claude-a1b2c3d4 | feature/parser | host-1 | 2h ago |
| #9 (WO-011) | 9f8e7d6c | claude-9f8e7d6c | feature/api | host-2 | 30m ago |
## Stale claims (>4h)
| Task | UUID | Agent | Started | Action |
|------|------|-------|---------|--------|
| #2 (WO-005) | 44556677 | claude-44556677 | 6h ago | Investigate; release with `/taskwarrior:task-release 2` (or the UUID) if abandoned |
Empty sections render as "(none)". Never auto-stop a stale claim —
report only, per the v1 design. UUID is convenience, not the safety
mechanism (.claude/rules/task-id-stability.md).
