dotbrain 0.3.4__tar.gz

dotbrain-0.3.4/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+
+# Python/uv build and test artifacts.
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/

dotbrain-0.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armin Zou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotbrain-0.3.4/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: dotbrain
+Version: 0.3.4
+Summary: Wires project Brainspaces and skills into coding agents.
+Project-URL: Homepage, https://github.com/arminzou/dotbrain
+Project-URL: Repository, https://github.com/arminzou/dotbrain
+Project-URL: Issues, https://github.com/arminzou/dotbrain/issues
+Author: Armin Zou
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12

dotbrain-0.3.4/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="assets/banner.jpg" alt="Dotbrain" width="100%">
+</p>
+
+# Dotbrain
+
+> Dotbrain keeps your project's context private and your code repo clean, and makes that discipline effortless.
+
+As an engineer, almost everything I build outgrows my private workspace. A side project I start
+alone gets shared or open-sourced later; team repos are visible from day one. The code can be
+shared; the thinking behind it doesn't have to be: the half-formed decisions, the roadmap, the
+rationale I would not want published, or leaked into a commit message by an agent.
+
+For a while that thinking had no natural home. It scattered across my head, my Obsidian vault,
+gitignored docs, and agent memory layers. Keeping it coherent was its own maintenance job. Every
+new session meant re-explaining the project, re-wiring tools, and hunting for context that should
+have just been there. So I built Dotbrain.
+
+## What is Dotbrain?
+
+Dotbrain keeps your project's private thinking in a versioned Brainspace under `~/dotbrain/`.
+It plants gitignored symlinks at your repo root pointing into that Brainspace, so agents pick
+up your decisions, vocabulary, and notes automatically at session start. The content never
+touches the code repo; the symlinks make sure it follows the project wherever you work it.
+
+    ~/dotbrain/
+    └── brainspaces/
+        └── my-project/
+            ├── .brain/
+            │   ├── CONTEXT.md  # domain vocabulary
+            │   ├── adr/        # architecture decisions
+            │   ├── designs/    # design docs
+            │   └── docs/       # derived reference material
+            └── .beads/     # execution store (issue tracker)
+
+    ~/repos/my-project/
+    ├── .brain  ──────────────► ~/dotbrain/brainspaces/my-project/.brain
+    ├── .beads  ──────────────► ~/dotbrain/brainspaces/my-project/.beads
+    ├── .claude/               # real directory with gitignored resource links
+    └── .codex/                # real directory with gitignored resource links
+
+## Why not just keep private notes?
+
+A gitignored notes file is the obvious fix, but I wanted those notes versioned, so they became a
+separate private repo. That is what I did for a long time. It kept them private and tracked, but it
+sat off to the side of the project: when I spun up a git worktree to run a second agent in parallel,
+the notes did not come with it; when I cloned the project onto another machine, they were not there
+either. The context I needed most was the context that never followed the work.
+
+Dotbrain keeps the Brain and issue tracker private and versioned under a project's Brainspace, then
+links selected agent resources into the repo's workspaces. A worktree can restore its `.brain` and
+`.beads` links through `wire-brain`'s worktree repair branch. A new machine is one clone and
+bootstrap away from having every project wired. The notes are there wherever you work the project,
+instead of sitting beside it.
+
+## "But my agent already remembers, and I have CLAUDE.md/AGENTS.md"
+
+**Agent session memory** carries context between sessions, but it is person-scoped, not
+project-scoped: it accumulates facts about you, not the decisions and rationale behind a specific
+project. Memory banks have the same shape. Both are also vendor-locked: Claude's memory doesn't
+help Codex, and wiring a new agent into a project means manual setup each time. Dotbrain is owned
+by the project, not the person or the tool: any agent working in the repo picks it up
+automatically.
+
+**CLAUDE.md/AGENTS.md** is great for a handful of standing instructions, but it lives in the public
+repo and should not become the home for every decision and design note. Past a point it just bloats,
+and everything in it is public if the repo is.
+
+Dotbrain is a project's private source of truth: authored by humans, readable by any agent,
+enforced by the wiring. The project brain is not accumulated; it is written, reviewed, and corrected.
+Both the human and the agent work from the same source, and git tracks all of it.
+
+## Is this for you?
+
+**Use Dotbrain if:**
+
+- you work with more than one coding agent or across multiple worktrees on the same project
+- your project has real context worth preserving: decisions, vocabulary, rationale that agents need to work effectively
+- your code is shared or will be, and you want the thinking behind it to stay private
+- you want that context authored and version-controlled, not accumulated in an opaque tool
+
+**Skip it if:**
+
+- your repos are all private and a single agent already covers you
+- you only need a few standing instructions; `CLAUDE.md` is genuinely simpler
+- you are looking for a hosted team knowledge base
+
+## How it works
+
+```mermaid
+flowchart LR
+  agent(["Coding agent: Claude Code, Codex"])
+  subgraph repo["Code repo"]
+    direction TB
+    code["your code"]
+    links["gitignored symlinks"]
+  end
+  subgraph home["Private dotbrain home (~/dotbrain)"]
+    direction TB
+    brain["Brain: vocabulary, decisions, rules"]
+    exec["Execution store: ready-work tracker"]
+    ws["Agent workspaces"]
+  end
+  agent --> repo
+  links --> brain
+  links --> exec
+  links --> ws
+```
+
+`dotbrain wire <repo>` creates the Brainspace, drops gitignored symlinks at the repo root, and
+links project skills and subagents into the agent workspaces. `dotbrain refresh` repairs wiring
+and relinks project skills and subagents if anything drifts. `dotbrain bootstrap` runs once per
+machine to install session-start hooks and link global skills and subagents.
+
+**Skills** are cross-project and live under `~/dotbrain/skills/`. Wiring links the relevant ones
+into each agent workspace (`.claude/`, `.codex/`) so any agent in the repo gets the same skill
+set without manual setup. Per-project skill and subagent selection lives in `project.yaml`; the
+Brain's `AGENTS.md` holds the cross-cutting conventions those skills read at session start.
+
+**Beads** (`.beads/`) is the private execution store. Agents use the `bd` CLI to inspect ready
+work, claim issues, and close them. Because it lives in the Brainspace and is version-controlled,
+any agent across sessions, worktrees, or tools operates from the same issue tracker. Work claimed
+in one session is visible to the next; nothing is re-derived from scratch.
+
+The session-start hook loads Brain context and execution state automatically, so every session
+starts warm: the agent knows the project vocabulary, the standing decisions, and what work is
+ready.
+
+When something needs to go public, you author a fresh, audience-specific doc rather than copying
+from the Brain, a private source that should never be mirrored into the code repo.
+
+## Workflow
+
+Dotbrain ships a set of bundled Brain-coupled skills: the operating manual for a wired project. They load
+automatically at session start and are available as slash commands.
+
+- **`wire-brain`** — provision or repair Brainspace wiring between a repo and its private Brain.
+- **`grill-decisions`** — stress-test a plan against the project's vocabulary and existing
+  decisions, then write clarified choices into `CONTEXT.md` and `adr/`.
+- **`curate-project-context`** — organize and maintain public and private project context as it
+  accumulates.
+- **`operate-execution`** — inspect the ready frontier, claim a work item, and record discoveries
+  back into the execution graph. This is the primary skill for driving daily work.
+- **`to-design`** — formalize a multi-step initiative into a design doc, save it to the Brain, and
+  create an epic bead.
+- **`to-issues`** — decompose a design doc into independently-workable bead tasks with acceptance
+  criteria and dependencies.
+- **`review-architecture`** — review the codebase for deeper architectural opportunities and feed
+  findings back into the Brain.
+- **`triage-public`** — intake public issues (GitHub, Linear, Jira), classify them, and link
+  accepted work to private execution items.
+- **`write-agent-docs`** — write public project docs, private Brain material, and user-owned
+  skills so agents retrieve and follow them predictably.
+
+See [docs/skills.md](docs/skills.md) for the full set.
+
+### Worktree execution
+
+Most work runs in place in the main checkout, reviewed as it happens. When work needs isolation,
+such as genuine parallelism or a long-running loop you want off your interactive tree, run it in a
+git worktree instead. A worktree shares the main checkout's Brain and execution state, with no
+separate Brain.
+
+`operate-execution` recommends when to isolate; the agent runtime creates the worktree. If it has
+no `.brain` or `.beads`, use `wire-brain`'s worktree repair branch to link those two directories
+back to the main checkout.
+
+## Install
+
+Dotbrain installs as a plugin. You do not need to clone this repo: the plugin carries the skills,
+the session-start hook, and an installer for the matching CLI.
+
+Claude Code — send these as two separate prompts:
+
+```
+/plugin marketplace add arminzou/dotbrain
+/plugin install dotbrain@dotbrain
+```
+
+Codex:
+
+```bash
+codex plugin marketplace add arminzou/dotbrain
+codex plugin add dotbrain@dotbrain
+```
+
+Codex holds plugin lifecycle hooks until you approve them: start `codex`, open `/hooks`, trust the
+dotbrain hook, then start a new thread.
+
+Then ask your agent to wire a repo, or invoke the `wire-brain` skill. It installs the `dotbrain`
+CLI (along with `uv` and Beads) if it is missing, runs `dotbrain bootstrap`, and wires the repo.
+
+On **Windows**, enable
+[Developer Mode](https://learn.microsoft.com/windows/apps/get-started/enable-your-device-for-development)
+first so Dotbrain can create directory symlinks without Administrator privileges. The private
+dotbrain home defaults to `%USERPROFILE%\dotbrain` (for example, `C:\Users\you\dotbrain`). Set
+`DOTBRAIN_HOME` only when you want to use a different location.
+
+See [docs/getting-started.md](docs/getting-started.md) for the full walkthrough, including how to
+install the CLI by hand and what to do if `marketplace add` trips over a Windows file lock.
+
+## Use
+
+```bash
+dotbrain wire <repo>      # connect a code repo to a private Brainspace
+dotbrain refresh          # repair wiring, load execution state, link project skills
+dotbrain unwire <repo>    # disconnect a repo from its Brainspace
+```
+
+## Develop
+
+The CLI is a [uv](https://docs.astral.sh/uv/)-managed Python package.
+
+```bash
+git clone https://github.com/arminzou/dotbrain.git
+cd dotbrain
+uv sync                 # provision the env
+uv run dotbrain --help  # inspect the command tree
+uv run pytest           # run the test suite
+```
+
+To install a CLI from your checkout rather than a release tag, run `./scripts/dev-install.sh` (or
+`.\scripts\dev-install.ps1` on Windows) from the repo root, then `dotbrain bootstrap`. That is the
+contributor path; users get the CLI from PyPI or the plugin.
+
+The plugin's `skills/` tree is the source of truth for dotbrain's bundled skills.
+
+Version lives in `pyproject.toml` and is mirrored into `src/dotbrain/__init__.py`, both plugin
+manifests, and both first-run installers; `tests/test_plugin_build.py` enforces that they agree.
+When cutting a release, bump all of them and push a matching `v<version>` tag — the installers pin
+that tag, so a release without one breaks first-run installs.

dotbrain-0.3.4/docs/README.md

@@ -0,0 +1,33 @@
+# Documentation
+
+This directory is the public docs index for dotbrain.
+
+Start here if you want the shape of the material before diving into a specific page.
+
+## Start Here
+
+- [architecture.md](architecture.md)
+  The design narrative: Brainspaces, the Brain/execution split, skills, and the public/private boundary.
+- [getting-started.md](getting-started.md)
+  The first-run path: install, bootstrap, wire a repo, and verify the result.
+
+## Reference
+
+- [cli-reference.md](cli-reference.md)
+  Public CLI command reference.
+- [configuration.md](configuration.md)
+  Annotated `config.yaml` and `project.yaml` examples.
+- [skills.md](skills.md)
+  Catalog of packaged Brain-coupled skills.
+- [glossary.md](glossary.md)
+  Public vocabulary for the dotbrain model.
+
+## Reading Order
+
+If you are new to dotbrain, a reasonable order is:
+
+1. [architecture.md](architecture.md)
+2. [getting-started.md](getting-started.md)
+3. [configuration.md](configuration.md)
+4. [skills.md](skills.md)
+5. [cli-reference.md](cli-reference.md)

dotbrain-0.3.4/docs/architecture.md

@@ -0,0 +1,80 @@
+# Architecture
+
+This document explains dotbrain's design: Brainspaces, the Brain and execution split, skills, and
+the public/private boundary. For the problem dotbrain solves and how to get started, see the
+[README](../README.md).
+
+## Brainspaces
+
+The unit of organization is a **Brainspace** — one directory per project that holds everything an
+agent needs that is not the code itself:
+
+- `.brain/` — the project's knowledge (see below)
+- `.beads/` — the execution store (issues, dependencies, plans)
+
+Brainspaces live together in a single repository. A code repo connects to its Brainspace through
+the gitignored `.brain` and `.beads` symlinks. Its `.claude` and `.codex` agent workspaces are real
+directories; dotbrain contributes individually ignored skill and subagent links without claiming
+project-owned files. The code repo stays clean and the context stays private, while the agent sees
+both as one tree.
+
+## The Brain
+
+A Brain has five elements, each with a single clear purpose:
+
+- **`CONTEXT.md`** — the project's domain vocabulary. Names for concepts that issues, plans, and code
+  use consistently, so language does not drift into synonyms.
+- **`adr/`** — Architecture Decision Records, one file per decision. Each captures a choice that is
+  hard to reverse, surprising without context, and the result of a real trade-off.
+- **`designs/`** — design docs, one initiative per file. While a design is active, it is the
+  living design authority for the initiative: current design, known unknowns, and deviations live
+  there. Authored by `to-design`, decomposed into bead epics by `to-issues`. Beads remain the
+  execution/status source. Once shipped, abandoned, or superseded, the design doc freezes as a
+  point-in-time record.
+- **`AGENTS.md`** — per-project agent operating conventions: linking rules, ADR policy, priority.
+- **`project.yaml`** — per-project runtime selection plus skill and subagent selection.
+- **`docs/`** — derived runbooks and reference material. Never authoritative; the elements above win.
+
+Brain writes are version-controlled, so every change is reviewable and revertable. Each element has
+a single writer rather than every agent editing everything, which keeps the knowledge coherent.
+
+## Execution lives in the tracker
+
+Plans and tasks do not live as markdown checklists that rot. They live in an **execution store** — by
+default [Beads](https://github.com/gastownhall/beads) (`bd`), a dependency-aware issue tracker.
+Multi-step work is modeled as issues with blocking relationships, so "what is ready to work on" is a
+query, not a document. The execution store is treated as machine-local runtime state, hydrated from
+configuration — which lets the same backend run locally (embedded) or as a shared server across
+machines, configured per project. The tracker is pluggable behind a small contract, so a project can
+swap the backend without changing how agents work.
+
+## Skills
+
+Skills are reusable agent capabilities, owned by the tool rather than any one project. The plugin
+delivers dotbrain's brain-coupled skills; dotbrain links only the operator's global and per-project
+selections. Linking is reconciled idempotently — the tool only ever creates or prunes the symlinks it
+owns, and never deletes a real file or a link it did not create. That is what lets the bundled
+product skills coexist safely with an operator's own private skills on the same machine.
+
+## Wiring and session start
+
+Connecting a repo is one command: `dotbrain wire` creates or repairs the Brainspace, writes its two
+links, materializes the agent workspaces, and records per-link ignore rules. A one-time
+`dotbrain bootstrap` links global skills and subagents.
+
+At the start of every agent session, a hook injects the shared operating rules and the project's own
+Brain context into the session, so the agent begins already knowing the project's conventions without
+anyone pasting them in. Project-selected skills and vendor-native subagents are linked into the
+matching workspaces from the same Brainspace declarations. A worktree with no `.brain` or `.beads`
+uses `wire-brain`'s worktree repair branch to link them back to the main checkout.
+
+## Public / private boundary
+
+The decision that shapes everything: **the tool is public; your data is private.** This repository is
+the tool — CLI, bundled skills, templates, scripts. Your Brainspaces and Brains live in a separate,
+private data root that the installed tool operates on. The tool never contains project data, and a
+Brain is never mirrored into a public code repo. When something genuinely needs to be public, you
+*derive* a fresh, audience-specific document instead of exposing the private source.
+
+That boundary is what lets you run dotbrain as an open-source tool while keeping it, unchanged, for
+entirely private work.

dotbrain-0.3.4/docs/beads-backend.md

@@ -0,0 +1,100 @@
+# Beads Backend
+
+This page explains the two beads backend modes dotbrain supports, when to use each one, and how the
+backend lifecycle fits into `load`, `migrate`, and cleanup commands.
+
+## Two Modes
+
+Per project, beads can run in one of two practical modes:
+
+- `embedded`
+  Local beads state lives in the project's private Brainspace.
+- `server`
+  The project uses a shared Dolt sql-server backend.
+
+For most first-time setups, `embedded` is the right default.
+
+## Embedded Mode
+
+Use embedded mode when:
+
+- the project is mostly local to one machine
+- you do not need a shared sql-server backend
+- you want the smallest operational footprint
+
+In embedded mode, the Brainspace carries the local beads state and dotbrain can hydrate it
+locally when needed.
+
+## Server Mode
+
+Use server mode when:
+
+- the project should use a shared backend across machines or sessions
+- you want multiple wired checkouts to connect to the same server-backed beads database
+- the project has moved beyond the local embedded default
+
+Server mode needs shared infrastructure defaults in `config.yaml`, typically under `beads.server`.
+The per-project `project.yaml` then sets `beads.mode: server`.
+
+See [configuration.md](configuration.md) for the concrete
+config examples.
+
+## How dotbrain Decides
+
+There are two layers of configuration:
+
+- `~/dotbrain/config.yaml` for machine-wide server defaults
+- `~/dotbrain/brainspaces/<name>/.brain/project.yaml` for per-project backend choice and overrides
+
+In practice:
+
+- if a project stays on the default path, it is usually `embedded`
+- if a project declares `beads.mode: server`, dotbrain treats it as server-backed
+
+## `dotbrain beads load`
+
+Use `dotbrain beads load` to hydrate local beads state from the tracked declarations.
+
+What it does depends on the backend:
+
+- server-mode projects attach to the declared server tracker
+- embedded projects initialize local beads state and pull it
+
+This is a reconcile step for backend state. It does not touch repo wiring, hooks, or unrelated
+workspace files.
+
+## `dotbrain beads migrate`
+
+Use `dotbrain beads migrate` when a project started as embedded and should move onto a remote
+sql-server backend without losing its existing history.
+
+Typical use case:
+
+- a project began with the local embedded default
+- later it needs a shared server backend
+- you want to preserve existing beads history while moving to server mode
+
+`migrate` is the transition step between those two worlds.
+
+## `dotbrain beads drop-db`
+
+`dotbrain beads drop-db` is a backend cleanup command for server-backed projects.
+
+Use it only when you actually intend to remove the remote beads database. This is separate from
+repo wiring and separate from `dotbrain unwire`.
+
+Rule of thumb:
+
+- `unwire` disconnects a repo from its Brainspace
+- `drop-db` removes a server backend database
+
+Those are different operations on purpose.
+
+## Which One Should You Pick?
+
+Choose `embedded` when you want the simplest default.
+
+Choose `server` when the project genuinely needs shared backend infrastructure.
+
+If you are unsure, start embedded and migrate later only when the project really needs the shared
+server model.