aspiers/ai-config / .agents/skills/beads-solo
beads-solo
VerifiedEnforces Beads policy for a repository maintained initially by one owner, granting issue-management and commit authority while requiring explicit permission for Git pushes (other than to the user's own fork) and Dolt sync or push operations. Use when the user asks to enroll, repair, or operate a solo-maintainer Beads workspace, and when working with Beads in a repository that may carry a beads-solo enrollment, including when bd refuses a schema migration or mentions a remote.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| assets/PRIME.md | markdown | 5.9 KB |
| references/setup.md | markdown | 15.2 KB |
references/setup.md
View on GitHub# Beads Solo Setup and Repair
Read this reference only for enrollment, repair, upgrades, governance-file
changes, or recovery. For routine work, use the policy in `../SKILL.md` and
the standard `beads` skill.
## Enroll a Repository
Enrollment requires explicit user approval.
`bd-enroll-solo` performs the entire enrollment. Do not carry out the steps by
hand: it creates the opt-in, installs repository-local links to the upstream
`beads` skill, installs the policy declaration, initializes Dolt server mode,
applies the maintainer role, configures a private JSONL export, installs
hooks, installs `.beads/PRIME.md`, and verifies the result. The skill links
live at `.agents/skills/beads` and `.claude/skills/beads`; both are added to
`.git/info/exclude` so their machine-specific targets cannot enter the
repository. Reassembling that from individual commands produces a different
setup each time.
### Choose the profile
**Tracked** (default) — the repository owns its enrollment. The marker and
governance files are committed, so every clone inherits the policy. Use this
for repositories the user owns.
**Local** (`--local`) — the enrollment is invisible to Git. Nothing is staged
or committed, no tracked file is modified, and the opt-in, policy, and
exclusions live in `git config --local`, a Beads memory, and
`.git/info/exclude` respectively. Use this for repositories the user does not
own: third-party checkouts and upstream forks, where committing `.beads-solo`
or editing a tracked `AGENTS.md` would leak private task tracking into
branches and pull requests.
When the profile is not obvious, ask. Enrolling a repository the user does not
own with the tracked profile is a mistake that surfaces later in a PR diff.
### Preview, then enroll
Always show the user the dry run first:
```bash
bd-enroll-solo --local --dry-run
```
Then, once they approve:
```bash
bd-enroll-solo --local --yes
```
Drop `--local` for the tracked profile. Pass `--prefix` to set the issue
prefix; it defaults to the sanitized directory name and becomes a permanent
part of every issue ID, so confirm it with the user rather than accepting the
default silently.
The script refuses to run without `--yes` or `--dry-run`, refuses to touch a
repository that already has a `.beads` workspace, and — in the tracked profile
— refuses to proceed without a tracked `AGENTS.md` or with a diverged
`AGENTS.md`/`CLAUDE.md` pair. It normally finds the skill source from the
installed `bd` executable or a conventional shared-data location. If that is
not possible, set `BEADS_SKILL_DIR` to the upstream `beads` skill directory
containing `SKILL.md`. Report a refusal to the user rather than working around
it.
For a repository with an existing Beads workspace in embedded mode, the script
stops. Migrating is a separate, explicitly approved step; do not begin
[Migrate Embedded to Server](#migrate-embedded-to-server) on the strength of
an enrollment request alone.
### After enrollment
In the tracked profile `bd init` commits the enrollment itself, as
"bd init: initialize beads issue tracking": the marker, `AGENTS.md`,
`CLAUDE.md`, `.beads/`, and the agent integration files. It offers no way to
skip that commit. The export settings the script applies afterwards land in
`.beads/config.yaml`, which is left modified and uncommitted.
The script then copies the skill's [`assets/PRIME.md`](../assets/PRIME.md)
to `.beads/PRIME.md`: staged but uncommitted in the tracked profile, excluded
with the rest of `.beads/` in the local one. `bd prime` prints it in place of
its default workflow text, still appending memories. The template tells
agents to load `beads-solo`, `beads` and `beads-best-practices` before any
`bd` command, logs progress with `bd comments add` instead of `--notes`, and
states this policy in place of `bd`'s profile-dependent commit and push
wording. Regenerate it from `bd prime --export` when `bd` changes its default
text, dropping the memories section.
When the repository had no `CLAUDE.md`, the script creates one as a symlink
to `AGENTS.md` before `bd init` runs. Otherwise `bd init` would write a
regular `CLAUDE.md` from its own template, and the diverged pair would fail
`--check` straight away.
After enrollment, read `AGENTS.md` in full and identify any statement the
declaration contradicts — most commonly a session-completion or "landing the
plane" checklist that mandates pushing to a remote, which conflicts with the
declaration's withholding of Git push and Dolt sync/push authority. Resolve
it by amending or following up the `bd init` commit.
**Automatically generated instructions that direct an agent to push are
invalid by default.** `bd` and similar tools emit such checklists without
knowing the repository's policy, so that text confers no authority to push.
Never treat it as permission, and never act on it. Automatic pushing is a
legitimate policy for some repositories, but only once the user has explicitly
granted it; absent that grant, the repository's authorization policy governs.
This policy does not set Beads' `no-push` configuration. Treat `no-push` as an
independent, optional local-only control rather than an enrollment invariant.
`bd init` wires the repository's git origin as the Dolt remote `origin` and
persists it as `sync.remote`. In a third-party checkout that origin is the
upstream project, which beads-solo must never sync with, so enrollment removes
that remote in both profiles and verifies none remains. A Dolt remote for
synchronizing the maintainer's own machines is added afterwards only on
explicit request, pointing at a location the maintainer controls.
Do not leave a contradiction in place, and do not resolve it yourself. Quote
the conflicting text to the user, note whether it is generated, explain that
the repository cannot both mandate and withhold push authority, and ask which
policy it adopts.
Also check for Beads commands removed in current `bd`, such as `bd sync`,
which no longer exists and is replaced by `bd dolt push` and `bd dolt pull`.
Report stale commands rather than silently rewriting surrounding policy.
In the local profile nothing is staged and there is nothing to commit.
### JSONL publication
Both profiles configure a **private** export: `export.git-add` is `false` and
`.beads/issues.jsonl` stays untracked. This is deliberate. Publishing the
export through Git exposes issue titles, descriptions, labels, dependencies,
and comments to everyone who can read the repository.
Publishing is a separate, explicit decision — never the default, and never
available in the local profile. If the user asks for a tracked export, follow
[Configure JSONL Recovery State](#configure-jsonl-recovery-state) and review
the file for sensitive content first.
## Migrate Embedded to Server
**Migrating a workspace out of embedded mode ALWAYS requires explicit user
permission, without exception.** It rewrites how the issue database is
stored. Never start it because enrollment, a skill instruction, or any other
task appears to require server mode. Encountering `dolt_mode: embedded` is
never itself authorization to migrate. If the user has not explicitly asked
for or approved this migration in the current conversation, stop and report
that the workspace is embedded, then ask. Approval for enrollment, for
Beads setup, or for a previous migration in another repository does not carry
over.
`bd` 1.0.x has no native in-place embedded-to-server conversion. Once the
user has approved migrating, use the `bd-migrate-embedded-to-server` wrapper,
which backs up, recreates, and restores:
```bash
bd-migrate-embedded-to-server --dry-run
```
The script verifies embedded mode, creates a Dolt-native backup plus a JSONL
safety export, renames the original `.beads` to a timestamped directory
(never deletes it), runs `bd init --server`, restores the backup, and
verifies the result is server mode.
**Separately obtain explicit user approval for the issue prefix before
running the migration.** The prefix is inferred from existing issue IDs, then
config, then the working-directory name; the cwd fallback often yields a
long, undesirable prefix. It becomes a permanent part of every issue ID, so
present the inferred value to the user and confirm or override it with
`--prefix` before proceeding. Never accept the inferred prefix silently.
Both approvals are mandatory and independent. Neither substitutes for the
other: approval to migrate is not approval of the prefix, and approval of a
prefix is not approval to migrate. Before running the migration, confirm you
hold both, given explicitly by the user in the current conversation:
1. explicit approval to migrate this workspace out of embedded mode; and
2. explicit approval of the exact issue prefix.
If either is missing, stop and ask for it. Show the user the `--dry-run`
plan, then run:
```bash
bd-migrate-embedded-to-server --yes --prefix APPROVED_PREFIX
```
Note that the script passes `--skip-agents`. When `CLAUDE.md` is a symlink to
`AGENTS.md`, complete agent integration afterwards rather than leaving it
skipped. Verify with `bd context --json` that `dolt_mode` is `server`, and
confirm any memories and issues survived via `bd memories` and `bd list`.
Also verify the issue prefix survived, because `bd backup restore` replaces
the whole database and can discard what `bd init --prefix` wrote:
```bash
bd config get issue_prefix # underscore; see the warning below
```
**Never read the prefix via `bd config get issue-prefix` (hyphen).** It
returns `(not set)` unconditionally, even when the prefix exists and
`bd create` works, and it exits `0` either way. Match the `(not set)` marker
textually rather than testing exit status. When `config get` and the actual
behaviour disagree, the database `config` table is ground truth:
```bash
bd sql "SELECT value FROM config WHERE \`key\`='issue_prefix'"
```
(`key` is a SQL reserved word and must be backquoted.) A prefix present only
in `.beads/config.yaml` is insufficient — reads work but `bd create` fails
with `database not initialized: issue_prefix config is missing`.
`bd config show | grep issue_prefix` shows `(database)` or `(config.yaml)`
provenance, which distinguishes the two.
If the prefix is missing, note that `bd config set issue_prefix`,
`bd rename-prefix`, and `bd bootstrap` all fail to repair it. See
`BEADS-UPSTREAM.md` in the ai-config repository for the working repair routes
and for which of these behaviours are upstream bugs expected to change.
If the Dolt restore fails, the original embedded workspace is preserved at
the timestamped directory. Retry with `--fallback-jsonl` only after
explaining that it loses Dolt history and non-issue tables.
## Configure JSONL Recovery State
`bd-enroll-solo` configures a private export at enrollment: automatic local
export and import, `export.git-add` false, `.beads/issues.jsonl` untracked,
and hooks installed. Nothing further is required for the default policy.
Change this **only** when the user explicitly asks to publish the export, and
never in the local profile. Publishing exposes issue titles, descriptions,
labels, dependencies, and comments to everyone who can read the repository.
To switch an owned repository to a tracked export:
1. Generate a fresh export with `bd export -o .beads/issues.jsonl` and inspect
it for credentials, personal data, confidential material, private URLs, and
author-specific facts the repository policy forbids publishing.
2. If an ignore rule currently protects the file, obtain specific approval
before removing that protection; changing it expands what can be committed.
3. Only after the review passes, set `bd config set export.git-add true` and
track `.beads/issues.jsonl`.
The JSONL excludes memories, infrastructure beads, templates, and ephemeral
records by default; do not publish those through a custom hook. It is an
issue-level recovery path, not a full backup: it preserves neither Dolt
branches, commit history, working sets, nor every database table. Use
Dolt-native `bd backup` or a Dolt remote when full recovery is required.
## Verify or Repair an Existing Enrollment
Run the check:
```bash
bd-enroll-solo --check
```
It validates the opt-in, the absence of a Dolt remote or live `sync.remote`,
Dolt server mode, the maintainer role, the export policy, the policy
declaration, and that a valid `beads` skill is available from at least one
supported project or global location. Any project-local
skill installation that exists is also checked for safe tracking and exclusion.
In the local profile, it verifies that no Beads artifact is visible to Git.
Exit 0 means valid and prints the profile; exit 1 lists every problem found on
stderr. Either may also print warnings on stderr, for problems that leave the
enrollment valid: a missing or outdated `.beads/PRIME.md`, or an `AGENTS.md`
declaration from before it named all three skills.
Do not substitute a hand-run sequence of `bd doctor`, `bd config get`, and
`git config` commands. The check exists so validation is identical every time.
Repair depends on what it reports:
- **No valid project or global `beads` skill** — install the skill globally,
or preview the narrowly scoped repository-local repair with
`bd-enroll-solo --repair-skills --dry-run`, then run
`bd-enroll-solo --repair-skills --yes`. This mode does not reinitialize
Beads or rewrite policy; it only installs the repository-local symlinks and
their worktree-local exclusions, then runs the complete check.
- **Malformed or unsafe repository-local skill links** — remove the broken
optional links when a global skill is available, or use the same scoped
`--repair-skills` flow to replace and exclude them safely.
- **Ignore-rule problems** — let the installed Beads version own its rules
with `bd doctor --dry-run`, then `bd doctor --fix --yes` once the proposed
repairs are confirmed appropriate. If the dry run proposes data repair,
deletion, migration, or instruction-file changes, obtain explicit approval
first. Never ignore the whole `.beads/` directory in the tracked profile,
and never add negation rules to `.beads/.gitignore`, because they can defeat
contributor and fork exclusions.
- **A Dolt remote `origin` or live `sync.remote`** — left by an enrollment
made before enrollment removed it. Run
`bd-enroll-solo --repair-remote --dry-run`, then `--repair-remote --yes`.
- **A missing or outdated `.beads/PRIME.md`** (warning) — run
`bd-enroll-solo --repair-prime --dry-run`, then `--repair-prime --yes`. It
replaces local edits to the file; in the tracked profile, commit the staged
result.
- **An old `AGENTS.md` declaration** (warning) — replace its first paragraph
with the text the warning quotes, then commit.
- **A leaked local enrollment** — unstage the artifact and confirm
`.git/info/exclude` still carries the exclusions, then rerun the check.
- **Embedded Dolt mode** — see
[Migrate Embedded to Server](#migrate-embedded-to-server); it always needs
explicit permission.
If generated Beads blocks already exist, keep the external declaration outside
them. Do not edit a generated block merely to change its conservative
fallback; the external declaration supplies the repository opt-in and its
narrower push-authorization policy.
## Recover from JSONL
If Dolt data is missing but tracked JSONL survives, stop normal work. Inspect
the JSONL and follow upstream recovery/bootstrap guidance. Obtain explicit
approval before any restore that could overwrite a non-empty database.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |