flurdy/agent-skills / skills/next
next
VerifiedRank ready beads across validated workspace stores or one local store. List read-only, or claim one selected bead, show its details, and continue into its work.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 50.1 KB |
| pi/index.ts | script | 2.5 KB |
| pi/lease-selection.ts | script | 16.9 KB |
| references/dolt-recovery.md | markdown | 7.7 KB |
| references/source-scope.md | markdown | 12.5 KB |
| scripts/bd-showexecutable | script | 1.1 KB |
| scripts/collect.pyexecutable | script | 25.5 KB |
| scripts/next-bdexecutable | script | 16.5 KB |
| scripts/next-selectexecutable | script | 21.3 KB |
| tests/lease-extension.test.mjs | script | 7.4 KB |
| tests/lease-kernel.test.mjs | script | 3.7 KB |
| tests/lease-selection.test.mjs | script | 20.1 KB |
| tests/test_defer_dates.py | script | 6.8 KB |
| tests/test_dolt_recovery_contract.py | script | 3.3 KB |
| tests/test_machine_routing.py | script | 10.1 KB |
| tests/test_next_bd.py | script | 43.8 KB |
| tests/test_next_select.py | script | 36.2 KB |
| tests/test_ownership_contract.py | script | 2.8 KB |
| tests/test_read_deadlines.py | script | 8.2 KB |
| tests/test_related.py | script | 11.4 KB |
| tests/test_source_scope.py | script | 10.1 KB |
| tests/workspace_fixture.py | script | 10.8 KB |
scripts/next-bd
View on GitHub#!/usr/bin/env bash
# next-bd: Show ready beads ranked by priority, with labels, filtered against blocked.
# Usage: next-bd [OPTIONS]
set -euo pipefail
usage() {
cat <<'EOF'
Usage: next-bd [OPTIONS]
Options:
--list Include complete non-selectable in-progress, blocked, deferred tables,
plus a P4 backlog table when fewer than 3 beads are ready
--backlog Always include the P4 backlog table with --list
--status Show only the in-progress, blocked and deferred tables (overrides --list)
--related[=BEAD]
Show beads one hop from BEAD (ID or repo:id), or from the in-progress
beads this harness session claimed: parent progress, blockers, unblocked
work, siblings, children and links. Overrides --list/--status
--in-progress Include a compact in-progress summary (ignored with --list)
--avoid-busy Exclude ready beads whose labels are busy in their store (tracker-only)
--safe Show scope/occupancy-unavailable queues without certifying safety
--safe-json Read-only candidate/scope packet for the optional in-process Pi helper
--json Print ranked candidates as JSON
--type=TYPE Include only candidates of the given issue type
--help Show this help and exit
EOF
}
FULL_LIST=false
SHOW_BACKLOG=false
STATUS_ONLY=false
RELATED=false
RELATED_SELECTOR=""
BACKLOG_THRESHOLD=3
SHOW_IN_PROGRESS=false
AVOID_BUSY=false
JSON_OUTPUT=false
SAFE_OUTPUT=false
SAFE_JSON=false
TYPE_FILTER=""
for arg in "$@"; do
case "$arg" in
--list) FULL_LIST=true ;;
--backlog) SHOW_BACKLOG=true ;;
--status) STATUS_ONLY=true ;;
--related) RELATED=true ;;
--related=*) RELATED=true; RELATED_SELECTOR=${arg#--related=} ;;
--in-progress) SHOW_IN_PROGRESS=true ;;
--avoid-busy) AVOID_BUSY=true ;;
--json) JSON_OUTPUT=true ;;
--safe) SAFE_OUTPUT=true ;;
--safe-json) SAFE_OUTPUT=true; SAFE_JSON=true ;;
--type=*) TYPE_FILTER=${arg#--type=} ;;
--help) usage; exit 0 ;;
esac
done
SCRIPT_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
collector_args=()
if "$SAFE_OUTPUT"; then
collector_args+=(--source-scope)
AVOID_BUSY=false
fi
exit_status=0
if "$JSON_OUTPUT"; then
RELATED=false
fi
if "$RELATED"; then
payload=$("$SCRIPT_DIR/next-select" related ${RELATED_SELECTOR:+"$RELATED_SELECTOR"}) || exit_status=$?
[[ -n $payload ]] || exit "$exit_status"
else
payload=$("$SCRIPT_DIR/collect.py" "${collector_args[@]}")
fi
if "$JSON_OUTPUT"; then
jq -r '.diagnostics[] | "next-bd: \(.)"' <<< "$payload" >&2
jq -r '.machine | "Machine: \(.id // "unknown") (\(.state): \(.reason)); source: \(.source)"' <<< "$payload" >&2
fi
jq -r \
--arg full_list "$FULL_LIST" \
--arg show_ip "$SHOW_IN_PROGRESS" \
--arg show_backlog "$SHOW_BACKLOG" \
--arg status_only "$STATUS_ONLY" \
--arg related "$RELATED" \
--argjson backlog_threshold "$BACKLOG_THRESHOLD" \
--arg avoid_busy "$AVOID_BUSY" \
--arg json_output "$JSON_OUTPUT" \
--arg safe_output "$SAFE_OUTPUT" \
--arg safe_json "$SAFE_JSON" \
--arg type_filter "$TYPE_FILTER" '
def text: (. // "—") | tostring | gsub("[\u0000-\u001f\u007f-\u009f]+"; " ");
def cell: text | gsub("\\|"; "|");
def row: "| " + (map(cell) | join(" | ")) + " |";
def overlap_ids($claims):
. as $candidate |
[$claims[] | select((.repository // "") == ($candidate.repository // "")) |
select(any(.labels[]?; . as $label | ($candidate.labels // []) | index($label))) | .id];
def service_overlap($claims):
. as $candidate |
[$claims[] | select((.repository // "") == ($candidate.repository // "")) |
{id, services: [(.services // [])[] | select(. as $service | ($candidate.services // []) | index($service))]} |
select(.services | length > 0)];
def parent_cell: if .parent == null or .parent == "" then "—" else .parent end;
def issue_headers($workspace):
(if $workspace then ["Repo"] else [] end) + ["ID", "Pri", "Type", "Labels", "Title", "Parent"];
def issue_fields($workspace):
(if $workspace then [.repository] else [] end) +
[.id, (if .priority == null then "—" else "P\(.priority)" end), .issue_type,
(.labels // [] | if length == 0 then "-" else join(", ") end), .title, parent_cell];
def safe_table($title; $rows; $workspace; $numbered; $overlap):
((if $numbered then ["#"] else [] end) + issue_headers($workspace) + ["Lease check"] +
(if $overlap then ["Shared service"] else [] end)) as $headers |
"## \($title) (\($rows | length) beads)\n\n" +
(if $overlap then "May collide with claimed work; labels only, not lease evidence.\n\n" else "" end) +
(if ($rows | length) == 0 then "_No candidates without a shared in-progress service._" else
($headers | row) + "\n" + ($headers | map("---") | row) + "\n" +
($rows | to_entries | map(
(if $numbered then [.key + 1] else [] end) + (.value | issue_fields($workspace)) +
[.value.lease_check] +
(if $overlap then ["\(.value.shared_services | join(", ")) (\(.value.tracker_overlap | join(", ")))"] else [] end) | row
) | join("\n")) end);
def machine_notice($machine):
"Machine: \($machine.id // "unknown" | cell) (\($machine.state | cell): \($machine.reason | cell)); source: \($machine.source | cell)";
def other_table($rows; $workspace):
if ($rows | length) == 0 then "" else
"\n\n## Other machines (\($rows | length) beads; not selectable here)\n\n" +
((issue_headers($workspace) + ["Run on / reason"]) | row) + "\n" +
((issue_headers($workspace) + ["Run on / reason"]) | map("---") | row) + "\n" +
($rows | sort_by(.priority, .created_at, (.repository // ""), .id) | map(
issue_fields($workspace) + [.machine_eligibility.reason] | row) | join("\n"))
end;
def unavailable_notice($stores):
if ($stores | length) == 0 then "" else
"## ⚠️ Beads store unavailable (\($stores | length))\n\n" +
"Work from these stores is not listed below; this is not an empty backlog.\n\n" +
($stores | map("- **\(.repository | text)** — \((.hint // .reason) | text)") | join("\n")) + "\n\n"
end;
def blocker_context:
if (.blocked_by // [] | length) > 0 then .blocked_by | join(", ")
elif (.blocked_by_count // 0) > 0 then "\(.blocked_by_count) blockers"
else "—" end;
def elapsed_note($rows):
($rows | map(select(.defer_elapsed == true)) | length) as $count |
if $count == 0 then "" else
"\n⏰ \($count) elapsed wake \(if $count == 1 then "date" else "dates" end): still stored deferred, not ready. Read-only listing never wakes work; review the awaited event before undeferring.\n"
end;
def defer_cell:
if .defer_elapsed == true then "\(.defer_until | text) ⏰ elapsed" else .defer_until end;
def non_ready_table($title; $status; $rows; $workspace; $extra):
(issue_headers($workspace) + (if $extra == "" then [] else [$extra] end)) as $headers |
"\n\n## \($title) (\($rows | length) \($status))\n" +
(if $title | ascii_downcase | contains("in progress") then "\nTracker claims; session activity unverified.\n" else "" end) +
(if $extra == "Defer until" then elapsed_note($rows) else "" end) +
(if ($rows | length) == 0 then "\n_None._" else
"\n" + ($headers | row) + "\n" + ($headers | map("---") | row) + "\n" +
($rows | sort_by(.priority, .created_at, (.repository // ""), .id) | map(
(issue_fields($workspace) +
(if $extra == "Blocked by" then [blocker_context]
elif $extra == "Defer until" then [defer_cell]
elif $extra == "Updated" then [(.updated_at // .created_at // "—")[0:10]]
else [] end)) | row
) | join("\n"))
end);
def related_status:
if .state == "blocked" then "blocked by " + (.blocked_by // [] | if length == 0 then "—" else join(", ") end)
elif .state == "deferred" then "deferred" + (if .defer_until then " until \(.defer_until)" else "" end) +
(if .defer_elapsed == true then " ⏰ elapsed" else "" end)
else .state // "—" end;
def relation_cell($progress):
.relations | map(if . == "parent" and $progress != null
then "parent (\($progress.closed)/\($progress.total) children closed)" else . end) | join(", ");
def related_section($workspace):
.parent_progress as $progress |
(["Relation"] + issue_headers($workspace) + ["Status"]) as $headers |
"\n\n## Related to \((if $workspace then .selector else .id end) | cell) (\(.related | length) beads)\n\n" +
"Focus: \(if .priority == null then "—" else "P\(.priority)" end) \(.issue_type | cell) · " +
"\(related_status | cell) · \(.title | cell)\n" +
elapsed_note(.related) +
(if (.related | length) == 0 then "\n_None._" else
"\n" + ($headers | row) + "\n" + ($headers | map("---") | row) + "\n" +
(.related | map([relation_cell($progress)] + issue_fields($workspace) + [related_status] | row) | join("\n"))
end);
def name_one: " Name one: `/next related <bead>` or `/next related <repo>:<id>`.";
def related_failure:
"## Related work unknown\n\n" +
if .status == "no-session" then
"No harness session ID is available, so this session\u0027s claimed beads cannot be identified." + name_one
elif .status == "none" then
"No in-progress bead carries this session\u0027s claim attribution (session `\(.session_id | cell)`)." + name_one
elif .status == "ambiguous" then
"`\(.id | cell)` exists in several stores; name one: " + (.matches | map("`\(.selector | cell)`") | join(", ")) + "."
elif .status == "not-found" then
"No queried store owns `\(.selector | cell)`." +
(if .owner_selector then " Its repository is workspace-owned; try `\(.owner_selector | cell)` (owner hint, not proof)." else "" end)
else
"Ownership or session claims could not be checked" + (if .selector then " for `\(.selector | cell)`" else "" end) +
"; nothing was assumed." + ((.failures // []) | map("\n- **\(.repository | text)** — \((.hint // .error) | text)") | join(""))
end;
def related_view:
.workspace as $workspace |
unavailable_notice(.unavailable_stores // []) +
(if .status == "ok" then
(if .focus_source == "session"
then "Focus: in-progress beads claimed by this session (claim attribution, not liveness)."
else "Focus: explicit selector." end) +
(.focus | map(related_section($workspace)) | join("")) +
"\n\nRead-only context, one hop; not selectable work. Closed beads are omitted except the parent. " +
"Start work with `/next` or a named bead."
else related_failure end) +
(if (.diagnostics // [] | length) > 0 then "\n\nSource diagnostics:\n" + (.diagnostics | map("- " + cell) | join("\n")) else "" end);
if $related == "true" then related_view else
. as $payload |
($payload.workspace) as $workspace |
($payload.blocked | map("\(.repository // "")\u0000\(.id)")) as $blocked_keys |
($payload.in_progress) as $in_progress |
($payload.diagnostics) as $diagnostics |
($payload.unavailable_stores // []) as $unavailable |
($payload.ready |
map(select(
. as $candidate |
"\($candidate.repository // "")\u0000\($candidate.id)" as $candidate_key |
$blocked_keys | index($candidate_key) | not
))
) as $unblocked |
($unblocked | map(select(.machine_eligibility.eligible | not))) as $other_machines |
($unblocked | map(select(.machine_eligibility.eligible))) as $eligible |
($eligible | map(select(.priority == 4))) as $backlog |
($eligible |
map(select(.priority >= 0 and .priority <= 3)) |
if $type_filter != "" then
map(select(.issue_type == $type_filter))
else . end |
if $avoid_busy == "true" then
map(select((overlap_ids($in_progress) | length) == 0))
else . end |
map(. + {
rank: (
.priority * 4 +
(if .issue_type == "bug" then 1
elif .issue_type == "feature" or .issue_type == "task" then 2
elif .issue_type == "epic" then 4
else 3
end)
)
}) |
sort_by(.rank, .created_at, (.repository // ""), .id)
) as $ranked |
if $safe_json == "true" then
{version: 1, workspace: $workspace, machine: $payload.machine,
candidates: $ranked, other_machines: $other_machines,
in_progress: $in_progress, blocked: $payload.blocked, deferred: $payload.deferred,
diagnostics: $diagnostics, unavailable_stores: $unavailable}
elif $safe_output == "true" then
($ranked | map(service_overlap($in_progress) as $overlap | . + {
tracker_overlap: ($overlap | map(.id)),
shared_services: ($overlap | map(.services[]) | unique),
lease_check: (if .source_scope.state == "unknown" then "unknown"
elif .source_scope.state == "partial" then "partial"
elif .source_scope.state == "invalid" then "invalid"
else "n/a" end)
})) as $safe_rows |
($safe_rows | map(select(.tracker_overlap | length == 0))) as $review |
($safe_rows | map(select(.tracker_overlap | length > 0))) as $overlaps |
unavailable_notice($unavailable) + machine_notice($payload.machine) +
(if ($in_progress | length) > 0 then non_ready_table("Claimed — in progress"; "beads; not selectable"; $in_progress; $workspace; "") else "" end) +
(if ($payload.blocked | length) > 0 then non_ready_table("Waiting — blocked"; "beads; not selectable"; $payload.blocked; $workspace; "Blocked by") else "" end) +
(if ($payload.deferred | length) > 0 then non_ready_table("Later — deferred"; "beads; not selectable"; $payload.deferred; $workspace; "Defer until") else "" end) +
(if ($diagnostics | length) > 0 then "\n\nSource diagnostics:\n" + ($diagnostics | map("- " + cell) | join("\n")) else "" end) +
other_table($other_machines; $workspace) +
(if ($overlaps | length) > 0 then
"\n\n" + safe_table("Held back — same service as in-progress work"; $overlaps; $workspace; false; true)
else "" end) +
"\n\n" +
(if ($review | length) == 0 and ($unavailable | length) > 0 then
"## Ready to review (0 beads)\n\n_Ready work unknown: the unavailable stores above were not read._"
else
safe_table("Ready to review"; $review; $workspace; true; false) +
"\n\nLease check: 0 free, \($review | length) not checked; no in-process Pi observer. unknown = no source_scope declaration; partial = incomplete scope; n/a = observer unavailable. Not checked does not mean occupied. No lease was acquired."
end) +
"\n\nNumbers are for review, not safe claims. Selector = \(if $workspace then "Repo:ID" else "local:ID" end). Only a fresh eligible recheck permits a safe claim; picking a not-checked row starts ordinary, not lease-checked, work."
elif $json_output == "true" then
$ranked
else
(["#"] + issue_headers($workspace)) as $headers |
("## Ready to Work (\($ranked | length) beads)\n" +
($headers | row) + "\n" + ($headers | map("---") | row) + "\n" +
($ranked | to_entries | map(
[.key + 1] + (.value | issue_fields($workspace)) | row
) | join("\n"))) as $ready_table |
(if ($diagnostics | length) > 0 then
"\n\nSource diagnostics:\n" + ($diagnostics | map("- " + .) | join("\n"))
else "" end) as $diagnostics_block |
(non_ready_table("In Progress"; "beads; not selectable"; $in_progress; $workspace; "") +
non_ready_table("Blocked"; "beads; not selectable"; $payload.blocked; $workspace; "Blocked by") +
non_ready_table("Deferred"; "beads; not selectable"; $payload.deferred; $workspace; "Defer until")) as $non_ready |
unavailable_notice($unavailable) + machine_notice($payload.machine) +
if $status_only == "true" then
$non_ready + $diagnostics_block
elif $full_list == "true" then
$non_ready +
(if $show_backlog == "true" or
(($ranked | length) < $backlog_threshold and ($backlog | length) > 0) then
non_ready_table("Backlog"; "P4 beads; not auto-pickable, start by ID"; $backlog; $workspace; "Updated")
else "" end) +
$diagnostics_block + other_table($other_machines; $workspace) + "\n\n" + $ready_table
elif $show_ip == "true" and ($in_progress | length) > 0 then
"\n\n" + $ready_table +
"\n\nTracker status: in progress (session activity unverified):\n" +
($in_progress | map(
if $workspace then
"- [\(.repository)] `\(.id)` (P\(.priority) \(.issue_type)) \"\(.title)\" (Parent: \(parent_cell | cell))"
else
"- `\(.id)` (P\(.priority) \(.issue_type)) \"\(.title)\" (Parent: \(parent_cell | cell))"
end
) | join("\n")) +
$diagnostics_block + other_table($other_machines; $workspace)
else "\n\n" + $ready_table + $diagnostics_block + other_table($other_machines; $workspace) end
end
end
' <<< "$payload"
exit "$exit_status"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |