Skip to content

arminzou/dotbrain / plugin/skills/wire-brain

wire-brain

Unverified

Wires, 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 jobCommand
Attach a main checkout or linked Git worktreedotbrain wire --repo <path>
Repair an existing wired checkoutdotbrain 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 reconciliationdotbrain refresh --all
Config, skills, agents, hooks, or templates changeddotbrain refresh --project <project> / --all
Prepare machine-global resourcesdotbrain bootstrap
Global skills or subagents are staledotbrain skills link --scope global / dotbrain subagents link --scope global
Need a health report before decidingdotbrain doctor
Detach a repo from its Brainspacedotbrain 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, or none.
  • agents: active workspaces, usually claude and/or codex.
  • 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:

  • .brain always points at the Brain.
  • .beads exists unless beads.mode is none.
  • .claude is a real directory when the claude agent workspace is active.
  • .codex is a real directory when the codex agent 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 doctor reports no relevant errors.
  • readlink <repo>/.brain resolves into ~/dotbrain/brainspaces/<name>/.brain.
  • Expected .beads links and materialized .claude / .codex workspaces match .brain/project.yaml.
  • Git's exclusion file contains the dotbrain-managed entries (git rev-parse --git-path info/exclude).
  • git -C <repo> status --short shows no unexpected tracked changes.
  • If beads are enabled, bd -C <repo> ready works or reports a valid empty tracker.
  • Public instructions route changes/review to root RULES.md and remain useful without a Brain.
  • Refresh preserves user-owned notebooks, rules, and instructions.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall