flurdy/agent-skills / skills/beads
beads
VerifiedShared Beads workflow baseline. Use whenever an agent uses `bd`, manages durable tasks, blockers, or handoffs, resolves work ownership, or decides between an ephemeral checklist and durable tracking. Covers store authority and remote Dolt safety.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.5 KB |
| references/integration-cleanup.md | markdown | 15.9 KB |
| references/sizing.md | markdown | 3.5 KB |
| scripts/integration_cleanup.py | script | 40.3 KB |
| tests/test-consumer-routing.shexecutable | script | 4.5 KB |
| tests/test-skill-contract.shexecutable | script | 7.7 KB |
| tests/test_integration_cleanup.py | script | 20.6 KB |
| tests/test_native_cleanup.py | script | 9.3 KB |
tests/test-consumer-routing.sh
View on GitHub#!/usr/bin/env bash
# Every skill that reads or writes an existing bead must route through the shared
# resolver and qualify its bd calls with the proven owning store.
set -euo pipefail
ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
# shellcheck disable=SC2088 # literal text asserted in SKILL.md, never expanded
RESOLVER='~/.agents/skills/next/scripts/next-select'
fail() {
printf 'FAIL: %s\n' "$1" >&2
exit 1
}
frontmatter() {
awk 'NR == 1 { next } /^---$/ { exit } { print }' "$1"
}
# Fenced code lines only: prose may mention `bd close` when explaining the rule.
code_lines() {
awk '/^ *```/ { fenced = !fenced; next } fenced { print }' "$1"
}
assert_contains() {
grep -Fq -- "$2" "$1" || fail "$1 missing: $2"
}
# Skills that mutate an existing bead: resolver allowed, resolver used, every mutating bd
# call in code qualified with -C, and the four resolver outcomes handled.
for skill in complete-task create-pr; do
file="$ROOT_DIR/skills/$skill/SKILL.md"
frontmatter "$file" | grep -Fq -- "Bash($RESOLVER:*)" || fail "$skill: resolver not in allowed-tools"
assert_contains "$file" "$RESOLVER resolve <bead-id>"
for outcome in '`resolved`' '`ambiguous`' '`unavailable`' '`not-found`'; do
assert_contains "$file" "$outcome"
done
if code_lines "$file" | grep -Eq '^\s*bd (close|update|create|dep|defer) '; then
fail "$skill: unqualified mutating bd call in code; use bd -C <directory>"
fi
code_lines "$file" | grep -Eq '^\s*bd -C <directory> close ' || fail "$skill: close must use bd -C <directory>"
done
# New follow-ups share the original's proven store; no unqualified deferred writes.
complete="$ROOT_DIR/skills/complete-task/SKILL.md"
for command in create defer; do
frontmatter "$complete" | grep -Fq -- "Bash(bd -C * $command:*)" || fail "complete-task: missing scoped $command grant"
code_lines "$complete" | grep -Eq "^\s*bd -C <directory> $command " || fail "complete-task: missing scoped $command call"
done
# Skills that create new work: store listing used and every create/dep in code qualified.
for skill in triage plan-to-backlog; do
file="$ROOT_DIR/skills/$skill/SKILL.md"
permissions=$(frontmatter "$file")
for mode in resolve stores; do
if ! grep -Fq -- "Bash($RESOLVER:*)" <<< "$permissions" &&
! grep -Fq -- "Bash($RESOLVER $mode:*)" <<< "$permissions"; then
fail "$skill: resolver $mode not in allowed-tools"
fi
done
assert_contains "$file" "$RESOLVER stores"
assert_contains "$file" 'usable: false'
if code_lines "$file" | grep -Eq '^\s*bd (close|update|create|dep|list|search) '; then
fail "$skill: unqualified bd call in code; use bd -C <directory>"
fi
done
assert_contains "$ROOT_DIR/skills/triage/SKILL.md" "$RESOLVER resolve <selector>"
assert_contains "$ROOT_DIR/skills/plan-to-backlog/SKILL.md" "$RESOLVER resolve <id>"
# Read-only consumers handed a bead ID: resolver allowed and used, reads qualified.
for skill in delegate-work diagnose-bug; do
file="$ROOT_DIR/skills/$skill/SKILL.md"
frontmatter "$file" | grep -Fq -- "Bash($RESOLVER:*)" || fail "$skill: resolver not in allowed-tools"
assert_contains "$file" "$RESOLVER resolve <id>"
assert_contains "$file" 'bd -C <directory> show <id>'
assert_contains "$file" 'never infer the store from the ID or the cwd'
done
# Portfolio reader: every store enumerated, every read qualified, unusable stores surfaced.
file="$ROOT_DIR/skills/tracking-sweep/SKILL.md"
frontmatter "$file" | grep -Fq -- "Bash($RESOLVER:*)" || fail "tracking-sweep: resolver not in allowed-tools"
assert_contains "$file" "$RESOLVER stores"
assert_contains "$file" 'usable: false'
if code_lines "$file" | grep -Eq '^\s*bd (list|show|memories|ready|stale|orphans)\b'; then
fail "tracking-sweep: unqualified bd read in code; use bd -C <directory>"
fi
# Script-driven consumer: the owning store is proven and every bd call goes through it.
trello="$ROOT_DIR/skills/trello-beads"
assert_contains "$trello/SKILL.md" 'fail closed before any Trello request or `bd` call'
for script in trello-pull.sh trello-sync.sh; do
assert_contains "$trello/scripts/$script" 'source "$SCRIPT_DIR/owning-store.sh"'
assert_contains "$trello/scripts/$script" 'require_owning_store'
if grep -Eq '\$\(bd ' "$trello/scripts/$script"; then
fail "$script: bare bd call; use bd_store"
fi
done
assert_contains "$trello/scripts/owning-store.sh" 'bd -C "$BEADS_STORE_DIR"'
printf '%s\n' 'beads consumer routing tests passed'
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |