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_native_cleanup.py
View on GitHub"""Opt-in characterization of the installed bd's removers; never runs a hook or opens a real store."""
import hashlib
import importlib.util
import json
import os
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[3]
BD = shutil.which("bd")
NATIVE = os.environ.get("BEADS_NATIVE_CLEANUP_TESTS") == "1"
BEGIN = "<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:fixture -->"
END = "<!-- END BEADS INTEGRATION -->"
CODEX_BEGIN = "<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->"
CODEX_END = "<!-- END BEADS CODEX SETUP -->"
@unittest.skipUnless(NATIVE, "opt in with BEADS_NATIVE_CLEANUP_TESTS=1 and an installed bd")
class NativeCleanupTests(unittest.TestCase):
def setUp(self):
self.assertTrue(BD, "native characterization requires an installed bd")
artifacts = ROOT / ".artifacts"
artifacts.mkdir(exist_ok=True)
self.temp = tempfile.TemporaryDirectory(prefix="native-cleanup-", dir=artifacts)
self.addCleanup(self.temp.cleanup)
self.base = Path(self.temp.name)
self.repo = self.base / "repo"
self.home = self.base / "home"
self.repo.mkdir()
self.home.mkdir()
self.env = {
"PATH": os.environ["PATH"], "HOME": str(self.home),
"XDG_CONFIG_HOME": str(self.home / ".config"),
"GIT_CONFIG_NOSYSTEM": "1", "GIT_CONFIG_GLOBAL": os.devnull,
"GIT_TERMINAL_PROMPT": "0", "BD_DISABLE_METRICS": "1", "BD_DISABLE_EVENT_FLUSH": "1",
"BD_BACKUP_ENABLED": "false", "BD_EXPORT_AUTO": "false",
"BD_NO_PUSH": "true", "BD_NO_GIT_OPS": "true",
"BEADS_DIR": str(self.repo / ".beads"),
}
version = self.call(BD, "--version").stdout
self.assertRegex(version, r"^bd version \S+")
self.call("git", "init", "-q", "-b", "main")
(self.repo / ".beads").mkdir(mode=0o700)
self.put(".beads/config.yaml", "metrics:\n disabled: true\nbackup:\n enabled: false\n")
def call(self, *args):
return subprocess.run(args, cwd=self.repo, env=self.env, text=True, capture_output=True, timeout=20, check=True)
def bd(self, *args):
return self.call(BD, "-C", str(self.repo), "--sandbox", *args)
def put(self, name, content):
path = self.repo / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content)
return path
def block(self):
return BEGIN + "\nfixture generated content\n" + END + "\n"
def helper(self):
spec = importlib.util.spec_from_file_location("integration_cleanup", ROOT / "skills/beads/scripts/integration_cleanup.py")
helper = importlib.util.module_from_spec(spec)
spec.loader.exec_module(helper)
return helper
def test_installed_bd_passes_every_self_test_and_generation_matches_setup(self):
helper = self.helper()
tool = helper.bd_probe()
self.assertTrue(tool["supported"])
for action in helper.NATIVE_ACTIONS:
self.assertEqual(helper.self_test(tool, action), [], action)
generated = helper.generated_codex(tool)
self.bd("setup", "codex")
for name, expected in generated["files"].items():
self.assertEqual(hashlib.sha256((self.repo / name).read_bytes()).hexdigest(), expected)
agents = (self.repo / "AGENTS.md").read_text()
start = agents.index(CODEX_BEGIN)
end = agents.index(CODEX_END, start) + len(CODEX_END)
self.assertEqual(hashlib.sha256(agents[start:end].encode()).hexdigest(), generated["block"])
def test_proposed_native_command_binds_cwd_when_launched_elsewhere(self):
helper = self.helper()
self.put("CLAUDE.md", "before\n" + self.block() + "after\n")
self.put(".claude/settings.json", json.dumps({"hooks": {"SessionStart": [{"hooks": [
{"type": "command", "command": "bd prime --hook-json"},
]}]}}))
outside = ROOT / "CLAUDE.md"
outside_before = outside.read_bytes() if outside.exists() else None
report = helper.inspect_repository(str(self.repo))
action = next(item for item in report["actions"] if item["id"] == "claude")
self.assertEqual(action["argv"][1], "--chdir=" + str(self.repo))
subprocess.run(action["argv"], cwd=ROOT, env=self.env, text=True, capture_output=True, timeout=20, check=True)
self.assertEqual((self.repo / "CLAUDE.md").read_text(), "before\nafter\n")
self.assertEqual(json.loads((self.repo / ".claude/settings.json").read_text()), {"hooks": {}})
outside_after = outside.read_bytes() if outside.exists() else None
self.assertEqual(outside_after, outside_before)
def test_claude_removes_only_block_and_exact_hook_commands(self):
self.put("CLAUDE.md", "before\n" + self.block() + "after\n")
authored = {"type": "command", "command": "run-project-check"}
settings = {"permissions": {"deny": ["anything"]}, "hooks": {"SessionStart": [{
"matcher": "", "hooks": [authored, {"type": "command", "command": "bd prime --hook-json"}],
}]}}
for name in ("settings.json", "settings.local.json"):
self.put(".claude/" + name, json.dumps(settings))
global_file = self.home / ".claude/settings.json"
global_file.parent.mkdir()
global_file.write_text("global sentinel")
self.bd("setup", "claude", "--remove", "--global=false")
self.assertEqual((self.repo / "CLAUDE.md").read_text(), "before\nafter\n")
for name in ("settings.json", "settings.local.json"):
result = json.loads((self.repo / ".claude" / name).read_text())
self.assertEqual(result["hooks"]["SessionStart"][0]["hooks"], [authored])
self.assertEqual(result["permissions"], settings["permissions"])
self.assertEqual(global_file.read_text(), "global sentinel")
self.assertFalse((self.repo / ".beads/dolt").exists())
def test_claude_removal_preserves_link_but_reports_zero_exit_partial_failure(self):
target = self.put("AGENTS.md", "authored\n" + self.block())
(self.repo / "CLAUDE.md").symlink_to("AGENTS.md")
result = self.bd("setup", "claude", "--remove", "--global=false")
self.assertTrue((self.repo / "CLAUDE.md").is_symlink())
self.assertIn(BEGIN, target.read_text())
self.assertIn("refusing to write through symlink", result.stderr)
self.assertEqual(result.returncode, 0)
def test_claude_zero_exit_can_leave_a_failed_instruction_removal(self):
(self.repo / "CLAUDE.md").mkdir()
self.put(".claude/settings.json", json.dumps({"hooks": {"SessionStart": [{"hooks": [
{"type": "command", "command": "bd prime --hook-json"},
]}]}}))
result = self.bd("setup", "claude", "--remove", "--global=false")
self.assertIn("Warning", result.stderr)
self.assertEqual(result.returncode, 0)
self.assertEqual(json.loads((self.repo / ".claude/settings.json").read_text()), {"hooks": {}})
def test_codex_removes_sibling_hooks_and_shared_feature_flag(self):
self.put("AGENTS.md", self.block() + CODEX_BEGIN + "\ncodex\n" + CODEX_END + "\nauthored\n")
self.put(".codex/config.toml", "[features]\nhooks = true\nother = true\n")
self.put(".codex/hooks.json", json.dumps({"hooks": {"SessionStart": [{"hooks": [
{"type": "command", "command": "bd codex-hook SessionStart"},
{"type": "command", "command": "run-project-check"},
]}]}}))
self.bd("setup", "codex", "--remove", "--global=false")
self.assertFalse((self.repo / ".codex/hooks.json").exists())
self.assertEqual((self.repo / ".codex/config.toml").read_text(), "[features]\nother = true\n")
self.assertEqual((self.repo / "AGENTS.md").read_text(), self.block() + "authored\n")
def test_hooks_uninstall_unsets_beads_path_and_strands_authored_checks(self):
self.bd("hooks", "install", "--beads")
hook = self.repo / ".beads/hooks/pre-commit"
hook.write_text(hook.read_text() + "\nrun-project-check\n")
self.put(".beads/hooks/pre-push.old", "run-old-check\n")
self.bd("hooks", "uninstall")
self.assertEqual(hook.read_text(), "#!/usr/bin/env sh\n\nrun-project-check\n")
self.assertEqual((self.repo / ".beads/hooks/pre-push.old").read_text(), "run-old-check\n")
result = subprocess.run(["git", "config", "--get", "core.hooksPath"], cwd=self.repo, env=self.env, capture_output=True)
self.assertEqual(result.returncode, 1)
def test_safe_native_removals_repeat_without_content_change(self):
self.bd("setup", "codex")
# Pure generated installation: no unrelated hook consumers in this isolated fixture.
self.bd("setup", "codex", "--remove", "--global=false")
self.bd("setup", "claude", "--remove", "--global=false")
self.bd("hooks", "install", "--beads")
self.bd("hooks", "uninstall")
before = {str(p.relative_to(self.repo)): p.read_bytes() for p in self.repo.rglob("*") if p.is_file()}
self.bd("setup", "codex", "--remove", "--global=false")
self.bd("setup", "claude", "--remove", "--global=false")
self.bd("hooks", "uninstall")
after = {str(p.relative_to(self.repo)): p.read_bytes() for p in self.repo.rglob("*") if p.is_file()}
self.assertEqual(before, after)
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: 471k | 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 |