arminzou/dotbrain / plugin/skills/wire-brain
wire-brain
UnverifiedWires, repairs, refreshes, or inspects a repo's dotbrain Brainspace by driving the dotbrain CLI. Use when starting a project under dotbrain, attaching an existing repo to a Brainspace, repairing wiring in a main checkout or linked Git worktree, reconciling agent workspace resources after an upgrade, or checking bootstrap expectations.
Wire Brain
Connect an adopter repo to its private Brainspace through dotbrain. The CLI owns wiring,
scaffolding, resource reconciliation, hooks, skill links, agent delivery, and beads setup. Agents using
this skill choose the right CLI command, inspect the result, and hand Brain content changes to the
skill that owns that content.
Choose the wiring branch
For every checkout, check installation below, then choose a CLI command. When attaching or
repairing a linked Git worktree, read Worktree attachment for its shared
state and verification rules. dotbrain wire discovers the main checkout through Git metadata;
the CLI creates the worktree's wiring.
First run
Before choosing a CLI command, check whether dotbrain is on PATH. If it is, continue without
installing anything.
If it is absent, this is a machine that has never run dotbrain — so resolve the dotbrain home before installing anything.
Ask before creating a dotbrain home
Check for the dotbrain home: $DOTBRAIN_HOME when set, otherwise ~/dotbrain. If it already
exists, say nothing and move on to the installer.
If it does not exist, stop and ask the operator before creating one:
No dotbrain home on this machine. Do you already have one in git? Give me the remote and I'll clone it. Otherwise I'll create a fresh one.
The home holds every Brainspace — the Brain, the work graph, the whole private history — and it is normally a git repo the operator pushes somewhere. Creating a fresh one on a machine whose operator already has a populated one elsewhere leaves them with an empty, diverged home, and they usually do not find out until they notice their projects are missing. Nothing on the machine distinguishes the two cases, so asking is the only way to tell them apart.
When they name a remote, clone it first, into that exact path:
git clone <remote> ~/dotbrain
Then run the installer. dotbrain bootstrap is idempotent: it seeds only the files the clone is
missing and leaves the existing git checkout alone.
Install the CLI
Run the installer shipped beside this skill:
- On macOS or Linux:
${CLAUDE_PLUGIN_ROOT}/scripts/install.sh. - On Windows:
pwsh -NoProfile -File "$env:CLAUDE_PLUGIN_ROOT/scripts/install.ps1".
The installer provides uv, bd, the CLI version pinned to this plugin release, and runs
dotbrain bootstrap — which creates and git-initializes the dotbrain home when it is absent. Then
resume this skill's normal wiring flow in the current repo. Relay bootstrap's setup list to the user,
including which runtimes were set up and each dotbrain detach --runtime <name> undo command.
Command choice
Use the narrowest command that matches the symptom. dotbrain --help carries the current flags;
this table only carries the routing.
| Symptom or job | Command |
|---|---|
| Attach a main checkout or linked Git worktree | dotbrain wire --repo <path> |
| Repair an existing wired checkout | dotbrain refresh from that checkout |
| Brainspace has no registered checkout (retired Brain-only project) | dotbrain wire --project <project> from its repository, or archive the Brainspace |
| Existing Brainspaces need registered-checkout reconciliation | dotbrain refresh --all |
| Config, skills, agents, hooks, or templates changed | dotbrain refresh --project <project> / --all |
| Prepare machine-global resources | dotbrain bootstrap |
| Global skills or subagents are stale | dotbrain skills link --scope global / dotbrain subagents link --scope global |
| Need a health report before deciding | dotbrain doctor |
| Detach a repo from its Brainspace | dotbrain unwire |
Project operations default to the current wired checkout, including a nested directory or
worktree. Outside it, use --project <name>; named selection respects the project's local checkout
override. --all selects registered projects and conflicts with individual selectors. --home
overrides the private data root. refresh maintains existing projects; it never creates one.
Do not recreate these steps by hand unless the CLI reports a concrete obstruction that must be removed first.
Ownership
~/dotbrain/config.yaml holds global infrastructure defaults, such as a shared beads sql-server.
Per-project identity lives in ~/dotbrain/brainspaces/<name>/.brain/project.yaml:
beads.mode:embedded,server, ornone.agents: active workspaces, usuallyclaudeand/orcodex.skills: project skill selection linked into the active workspaces.subagents: project custom subagent extras.
The CLI seeds missing Brain scaffolding and links runtime assets. Agents maintain Brain knowledge
through maintain-brain; use work-graph for native Beads operations and repo-rules
for adopted repository requirements. Consult the CLI upgrade guidance for obsolete configuration and preserved retired resources.
Wiring contract
A wired adopter repo points at its Brainspace through local, gitignored symlinks and has real agent workspace directories. Expected wiring is derived from project config:
.brainalways points at the Brain..beadsexists unlessbeads.modeisnone..claudeis a real directory when theclaudeagent workspace is active..codexis a real directory when thecodexagent workspace is active.
Skills and custom Claude agents use symlinks. Codex custom-agent TOML definitions are generated real files with the marker # dotbrain-managed-agent: v1; customize their source in the private home. Dotbrain
overwrites or prunes marked copies and preserves unmarked files and foreign links.
The Git exclusion file ignores /.brain, /.beads, and each workspace resource dotbrain creates. The public
repo context routes making or reviewing changes to tracked root RULES.md. Apply the convention's
public/private boundary to public repo files. Wiring preserves existing context pointers
and user instructions; it never authors repository rules.
Wiring one repo
Run dotbrain wire from the adopter repo, or pass --repo <path> from elsewhere.
For initial main-checkout wiring, use --project <project> when the Brainspace name should differ
from the repo directory name. Existing checkouts and worktrees use their established identity.
Use beads options only for the initial tracker setup when project config or global config is not
already sufficient:
dotbrain wire --repo /path/to/repo --server-host db.example.internal
dotbrain wire --repo /path/to/repo --remote https://doltremoteapi.dolthub.com/owner/repo
dotbrain wire --repo /path/to/repo --skip-beads
After wiring, run:
dotbrain doctor
git -C /path/to/repo status --short
Public instructions remain user-owned; wiring preserves their existing context pointers. Symlinks whose targets are outside the repo must remain untracked.
Detachment
Detach through the CLI:
dotbrain unwire --repo /path/to/repo
Detachment removes the selected checkout's managed wiring and context pointer while keeping the
Brainspace, registration, user-owned workspace files, and other wired worktrees. Brainspace
archival or deletion is an operator-owned filesystem action. Remote database deletion remains
separate: use dotbrain beads drop-db <database> --yes only when explicitly requested.
Verification
Before declaring wiring fixed:
dotbrain doctorreports no relevant errors.readlink <repo>/.brainresolves into~/dotbrain/brainspaces/<name>/.brain.- Expected
.beadslinks and materialized.claude/.codexworkspaces match.brain/project.yaml. - Git's exclusion file contains the dotbrain-managed entries (
git rev-parse --git-path info/exclude). git -C <repo> status --shortshows no unexpected tracked changes.- If beads are enabled,
bd -C <repo> readyworks or reports a valid empty tracker. - Public instructions route changes/review to root
RULES.mdand remain useful without a Brain. - Refresh preserves user-owned notebooks, rules, and instructions.
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: 467k | 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: 319k | 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: 319k | 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: 319k | Updated | Claude CodeCodex | Verified | Install |