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 |
references/integration-cleanup.md
View on GitHub# Explicit repository integration cleanup
Use `/beads cleanup /absolute/repository` (Pi: `/skill:beads cleanup /absolute/repository`) only
when the user explicitly selects post-init integration cleanup. `/beads cleanup --inspect ...`
ends after the read-only preview. Loading the baseline, initializing Beads, or finishing migration
never selects cleanup. This procedure owns standalone integration cleanup, not migration, data
retention, tracker changes, installation or publication. Global client setup is limited to the
Claude hook removal in [Global Claude hooks](#global-claude-hooks).
Requires Python 3.10+, Git and, for native removal proposals, any installed bd exposing the
removal commands. There is no version allowlist: before a native action is authorized, the helper
runs that exact remover against a disposable sandbox fixture (isolated repository and HOME,
metrics/push/Git ops disabled) and refuses when any assumption below no longer holds. Generated
Codex ownership hashes are likewise produced by the installed bd in a sandbox, not stored.
## Prevent new redundancy
Check the installed `bd init --help`. For a separately authorized new initialization, the checked
version supports `--skip-agents --skip-hooks`: suppress AGENTS.md plus Claude/Codex setup and Git
hook installation. Never rerun init as cleanup. These flags neither remove existing integrations
nor promise an empty Git diff, no configuration changes, no commit, or no other init side effects.
The shared workflow does not require automatic prime injection.
## 1. Inspect one explicit root
Read the target's repository instructions first. Establish its canonical Git worktree and preserve
its before-state, including unrelated changes. Follow workspace Git wrappers when configured.
A source target is not a tracking-store claim: this inspector never reads or changes issue data.
```bash
python3 ~/.agents/skills/beads/scripts/integration_cleanup.py --repo /absolute/repository
```
The helper reads only bounded known integration surfaces and Git configuration needed for path
identity. It probes bd version/help with metrics and event flushing disabled. It never invokes bd
against the target or the real HOME; bd runs only inside a temporary sandbox (to generate Codex
templates when Codex files are present, and for the `--action` self-test). Do not run hooks as an
inspection test.
The `beads-integration-cleanup/v1` report includes:
- canonical repository and executable identities, content hashes, modes, marker line ranges and
deduplicated instruction aliases; file contents and arbitrary hook commands are not printed;
- fixed `agents-blocks`, `claude`, `codex-native`, `codex-generated`, `hooks`, and
`interactions-ignore` actions, exact mechanisms/argv/affected paths/effects, and `ready`,
`blocked` or `clean` status;
- unsupported residuals, including custom client surfaces and nonstandard hook commands;
- a fingerprint binding the inspected files, topology, helper, bd binary and proposed effects.
Per-file input is limited to 256 KiB and each inspected hook directory to 128 entries. Malformed
or duplicate markers/JSON, unreadable/special/hardlinked files, linked mutation paths, out-of-root
aliases, shared Git administration, local Git includes and ambiguous hooks configuration block
relevant actions. An external symlink target is not read. Known instruction aliases are grouped
once for inventory; native mutations through either linked name remain refused. Other client
surfaces are presence diagnostics, not exhaustive detection or a deletion allowlist.
The only permitted ambient command-config overrides are noninteractive credential suppression;
location or arbitrary Git/Beads overrides fail closed. Do not unset them merely to bypass a refusal.
Return to the correct ordinary repository environment. The helper is a cooperative preflight,
not a filesystem sandbox or authority to modify any path.
## 2. Review the fixed action table
Characterized on bd 1.2.2 and 1.3.0; the self-test re-proves the load-bearing effects for the
installed binary. Plus the explicitly reviewed cleanup-only exceptions:
| Action | Effects | When to refuse |
|---|---|---|
| `agents-blocks` | A native exact edit removes one uniquely paired general block and/or one exact checked Codex block from regular `AGENTS.md`; the preview includes at most one immediately adjacent separator blank line, preserving every other byte outside selected spans | Linked/hardlinked/ambiguous path, malformed/duplicate markers, missing replacement guidance, recovery evidence or exact old/new preview |
| `claude` | `setup claude --remove --global=false` removes the general managed block only from `CLAUDE.md`; removes the four exact `bd prime` variants from SessionStart/PreCompact in both project settings files; serializes hook JSON while preserving sibling commands and unrelated properties | Linked/ambiguous paths, malformed input, missing recovery evidence; native warnings are partial failure even with exit 0 |
| `codex-native` | `setup codex --remove --global=false` removes the Codex block from `AGENTS.md`, generated skill files, feature flag and managed hook entries | Any `.codex/config.toml` exists; also refuse mixed entries, linked paths or unproven generated bytes. Prefer `codex-generated` when its stricter proof passes |
| `codex-generated` | Separately confirmed exact-file deletion of the four project files whose hashes and directory shape match sandbox output of the installed bd; native `rmdir` only for resulting empty known directories | Any hash/entry/topology mismatch; project skill aliases global `~/.agents`; the exact Codex block is neither selected through `agents-blocks` nor already absent |
| `hooks` | `hooks uninstall` removes the five managed hook sections or pure files; may unset local `core.hooksPath` and reactivate default `.git/hooks` | Chains/backups, legacy/malformed sections, shared/out-of-root/custom paths, a fallback hook that could become active, or authored content/checks that would become unreachable |
| `interactions-ignore` | Native edit adds anchored `/.beads/interactions.jsonl` to root `.gitignore`; separately confirmed `git rm --cached -- .beads/interactions.jsonl` retains the local file while removing it from the index | Linked/hardlinked/malformed paths, deeper negation rules, absent tracked working file, missing backup, or inability to prove the anchored rule wins with `check-ignore --no-index` |
The native Codex remover deletes an **entire entry** when any child command starts with
`bd codex-hook `; this can remove unrelated siblings. Its feature-flag removal is not scoped to
Beads. The conservative config-file refusal is intentional; do not delete a config temporarily,
remove just the blocker, or disable checks to make native removal pass.
The native Claude remover preserves symlinks by refusing the write, but may already have changed
settings before reporting a warning with exit 0. It leaves template scaffolding outside the
managed block. This cleanup procedure's `agents-blocks` action is the sole reviewed exception to
the ordinary no-manual-edit rule: it uses Pi's native exact edit after unique full-line markers,
regular single-link identity, an old/new preview, recovery evidence and a fresh confirmation. It
is not permission to alter generated content, repair malformed blocks, or edit any other managed
region.
`codex-generated` is likewise a fixed exact-output exception, not a generic directory cleanup.
The four file hashes and the Codex-block hash come from running the installed bd's `setup codex`
in a sandbox, so an upgrade that changes templates simply changes what counts as generated.
Missing known files are a no-op; any unexpected entry refuses deletion. Confirmed removal uses
exact file paths and non-recursive `rmdir`, never `rm -r`. The global skill identity must differ.
`interactions-ignore` prefers untrack-and-retain over deletion because Beads may recreate the file.
Adding an ignore rule without untracking a tracked file is incomplete. Editing bd-owned
`.beads/.gitignore` is not allowed; root `/.beads/interactions.jsonl` must win over deeper rules.
When the untracking commit reaches another checkout Git may remove its tracked copy, so review
non-empty contents and recovery needs before publication.
Sources: bd tag `v1.2.2`,
[hooks.go](https://github.com/gastownhall/beads/blob/v1.2.2/cmd/bd/hooks.go),
[claude.go](https://github.com/gastownhall/beads/blob/v1.2.2/cmd/bd/setup/claude.go),
[agents.go](https://github.com/gastownhall/beads/blob/v1.2.2/cmd/bd/setup/agents.go),
[codex.go](https://github.com/gastownhall/beads/blob/v1.2.2/cmd/bd/setup/codex.go), and
[agent_skill.go](https://github.com/gastownhall/beads/blob/v1.2.2/cmd/bd/setup/agent_skill.go).
The per-action self-test and native fixture suite verify these claims against the installed
binary; source review alone is not compatibility proof. Generated hashes identify templates, not
arbitrary files whose names happen to match.
## 3. Select, retain recovery evidence, and confirm
Show a compact table of the actual target's proposed paths, marker ranges/counts, native effects,
refusal reasons and recovery sources. Include **None — keep existing state**. Do not present blocked
actions as executable options, and never send settings secrets or raw configuration diffs to chat.
Selection is not execution authority. Before a ready action:
1. Require the applicable source scope. In guarded Pi, shell effects cannot acquire leases: the
user must select the target worktree for implementation before a removal command. Tracking
comments and the inspector itself grant no source authority. Shared Git administration is
refused rather than implicitly leasing another worktree.
2. Retain a mode-private backup of every affected file and relevant local Git configuration,
including ignored and untracked settings, under an approved ignored `.artifacts/` directory.
Record canonical paths, hashes, modes, the planned command and before-state. Do not rely on
Git recovery for untracked/ignored files or discard existing changes. No backups outside the
authorized scope and no copying a linked target. If a safe recovery copy cannot be retained,
stop for a user decision rather than accepting silent loss.
3. Recheck effective Beads backup/export/synchronization settings and command side effects under
the shared baseline. Integration removal must not mutate tracking data or publish anything.
4. Re-run the inspector with the displayed fingerprint and action. For `claude`, `codex-native`
and `hooks` this also runs the sandbox self-test of the installed bd; the target is not touched:
```bash
python3 ~/.agents/skills/beads/scripts/integration_cleanup.py \
--repo /absolute/repository --expect FINGERPRINT --action agents-blocks
```
Nonzero exit (including a failed self-test, reported with each broken assumption) blocks the action. Refresh the preview and selection after any drift; a fingerprint
is not an approval token or a lock. The preflight-to-command race is a cooperative limitation.
5. Ask for fresh explicit confirmation **immediately before each destructive command or native
edit**, showing one exact operation. Execute it once, separately, with no command chains or
retries. Native bd actions keep both the helper's process-cwd binding
(`env --chdir=/absolute/repository`) and bd `-C`, plus `--sandbox`, `--global=false` and metrics
suppression. bd setup resolves project files from process cwd despite accepting `-C`;
omitting either binding is unsupported. Never select `--global`, an unlisted recipe, or a
different executable.
`agents-blocks` uses one exact native Edit, then re-inventory. `codex-generated` deletes each
proven file by exact path in one visible command and prunes only empty known directories with
non-recursive `rmdir`. `interactions-ignore` performs the `.gitignore` native edit first,
verifies ignore precedence, then asks again immediately before the visible `git rm --cached`.
## 4. Verify every action before continuing
Treat any stderr warning, nonzero exit, unexpected path/mode/content change or surviving expected
removal as a partial failure. Stop, preserve output and the current diff privately, and report
exactly what changed and remains. No automatic rollback, retry, hook repair or next action.
After each successful command:
- Re-inventory and compare all affected aliases, hashes, modes and marker/hook counts with the
backup. Confirm authored text outside removed spans, unrelated JSON properties and sibling
commands survived. JSON formatting changes must match the preview; inspect ignored settings
too, not just `git diff`.
- Verify Git's effective hooks path and all preserved check/chain reachability without executing
a hook. Use source inspection and syntax checks, not commits or pushes as a test harness.
- Inspect the resulting diff, index and repository status. For interactions cleanup,
`git check-ignore -v --no-index .beads/interactions.jsonl` must cite the anchored root rule,
`git ls-files -- .beads/interactions.jsonl` must be empty and the local file must still exist.
Required checks must remain enabled; no global integration, database, backup, registry, branch
or history cleanup is implied.
- Refresh the preview for the next selected action and obtain its own confirmation. Once an
action is `clean`, skip it rather than rerunning a native command merely to normalize files.
Report removed versus retained/unsupported integrations separately. Successful partial cleanup is
not a claim that every integration disappeared. Commit, tracker updates and publication follow
their normal separately authorized workflows; this procedure does not automatically perform them.
Migration aftercare may reuse this inventory only **after its own selection and migration-evidence
gates**; standalone inspection never supplies or satisfies migration evidence.
## Global Claude hooks
`bd setup claude --global` adds `bd prime` to `SessionStart` and `PreCompact` in
`~/.claude/settings.json`. The shared workflow needs no prime injection, and every compaction then
injects the full CLI reference twice. Use `/beads cleanup --global` only when the user explicitly
selects it.
```bash
python3 ~/.agents/skills/beads/scripts/integration_cleanup.py --global
```
Do not use `bd setup claude --remove --global`: besides the hooks it strips the managed block from
`CLAUDE.md` in its process cwd and re-sorts every settings key. The helper removes the hooks itself,
without bd. The `claude-global` action counts only the four exact `bd prime` variants in
`SessionStart`/`PreCompact` and is `blocked` for linked/hardlinked/malformed settings. Global Codex,
Gemini and Cursor hooks are residuals only: no verified removal action.
After showing the effects and getting fresh confirmation, apply once with the displayed
fingerprint and an existing mode-0700 directory:
```bash
python3 ~/.agents/skills/beads/scripts/integration_cleanup.py \
--global --expect FINGERPRINT --apply claude-global --backup-dir PRIVATE_DIR
```
This is the helper's only write. It copies the original to `PRIVATE_DIR` (0600, never overwritten),
removes only matching commands, drops entries and events left empty, keeps key order and file
mode, replaces the file atomically and reports the re-inspected status, which must be `clean`.
Then show `diff` against the backup: it must contain only the removed `bd prime` entries.
## Verification commands
From the agent-skills repository:
```bash
make test-beads
BEADS_NATIVE_CLEANUP_TESTS=1 make test-beads
```
The first runs the always-available read-only inspector/contract fixtures; native characterization
is explicitly skipped without opt-in. The second additionally runs the installed bd against
disposable local fixture repositories and isolated homes, with metrics/event flushing disabled,
including every action self-test. It does not initialize a real store or run project hooks. A
missing native executable is not passing native evidence. On a bd upgrade, run it to see which
characterized behaviour changed; the runtime self-test already fails closed on load-bearing drift.
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 |