Skip to content

flurdy/agent-skills / skills/next

Rank 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.

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("\\|"; "&#124;");
  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"
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall