Dotbrain

---
name: dotbrain
description: >
  The dotbrain operating convention — how a Brain, its work graph, and agent
  workspaces fit together, and the rules that bind work in a wired project. Invoke it
  to hand an agent the convention when the session-start hook did not.
disable-model-invocation: true
---

*States the convention; changes nothing.* The document below is the exact text the
session-start hook injects as `.brain/DOTBRAIN.md`. Some harnesses never run that hook
(Cowork, Claude Desktop, an untrusted Codex hook), which is what this skill is for —
same document, delivered by hand.

## Who owns what

The convention describes the model; these skills act on it.

| To do this | Use |
|---|---|
| Create or repair `.brain` / `.beads` links | `wire-brain` |
| Create, claim, or close work items | `manage-work-graph` |
| Do an item or a finite batch of items | `run-execution` |
| Formalize an initiative, or record a decision | `to-design`, `grill-decisions` |
| Edit a project's own rules in `.brain/AGENTS.md` | `curate-project-context` |

# DOTBRAIN.md

Shared operating rules for all dotbrain brains. Owned by dotbrain; synced by
`dotbrain refresh`. Do not edit per project — changes to the packaged dotbrain
Brain template propagate to every brain.

## Wiring

- This Brain lives in the private dotbrain home at
  `~/dotbrain/brainspaces/<name>/.brain`, not in the code repo.
- Repo-root `.brain` and `.beads` are gitignored symlinks into that Brainspace. `.claude` and
  `.codex` are real project directories containing gitignored selected resources. Skills and
  Claude agents are symlinks; Codex agents are generated real TOML files marked
  `# dotbrain-managed-agent: v1`. Customize their private source; delivered copies are disposable.
  These resources are local machine wiring: never commit them to the code repo.
- Brain changes are committed in `~/dotbrain`. The code repo's `git status` never shows them.
- Worktrees reach this same Brain through their own `.brain` and `.beads` symlinks; never copy it
  per worktree.
- Attach a main checkout or Git worktree with `dotbrain wire`; Git metadata connects a worktree
  to its main checkout's existing Brainspace without changing registration or declarations.
- Maintain the current wired checkout with `dotbrain refresh`, `dotbrain skills link`, or
  `dotbrain agents link`. Outside it, select `--project <name>`; asset linking also accepts a wired
  `--repo <checkout>`. Global assets require `--scope global`.
- `dotbrain unwire` detaches the selected checkout while retaining the Brainspace, shared tracker,
  other worktrees, and user-owned workspace content. Retire Brainspaces through filesystem actions.
- Never hand-create links under `.claude` or `.codex`. Their targets are relative paths the CLI
  computes from the checkout's real location; a hand-counted `../` depth dangles without error.

## Rules

- Read `.brain/AGENTS.md` before substantial work. It holds this project's own rules and is
  not injected at session start. If it is missing, note the gap and continue.
- Brain writes are agent-managed (git-tracked in dotbrain, so changes are revertable).
- The work graph lives in beads. Work from `bd ready`; record multi-step plans as epics with
  `blocks` dependencies, not as markdown checklists. `manage-work-graph` maintains the graph;
  `run-execution` carries out an item or finite batch. While delegated workers run, only the
  lead changes the work graph or the active design doc; the lead is the agent running that
  execution.
- Both the HITL and handoff workflows run on a dedicated branch and land through a review
  surface: a PR, or the branch diff where the project hosts no PRs. Parallel workers integrate
  into that branch, never into `main`. In the HITL workflow, propose the branch at the first
  bounded execution; it may span several bounded executions. Ask before pushing or opening a PR.
  Merge stays human-owned. Local HITL landing requires explicit human instruction, recorded
  by the lead; it is never the default.
- Use `CONTEXT.md` vocabulary when naming concepts in issues, plans, tests, and proposals.
  Do not drift to synonyms.
- If a proposed change conflicts with an ADR, call it out before proceeding.
- If `CONTEXT.md` or `adr/` are missing or empty, proceed silently — note the gap, don't
  scaffold them unasked.
- `.brain/docs/` holds project-scoped knowledge (runbooks, references, derived notes) that
  is not auto-injected into context. Before answering how this project builds, runs, deploys,
  integrates, or otherwise works, check and search `.brain/docs/` first — do not infer from
  the public repo or generic conventions when the Brain has a documented answer.
- Search the Brain by targeting `.brain/`: it is hidden and gitignored, so a search from
  the repo root skips it.
- The code repo may be public; the Brain never is. Never mirror Brain content into the code
  repo — for a public need, derive a fresh audience-specific doc instead.
- Public-facing repo docs (README.md, repo-root AGENTS.md) must not expose private Brain
  paths or content. The only `.brain` reference allowed in the repo root is the one-line
  agent pointer to `.brain/AGENTS.md`.
- Never reference private Brain context from code, tests, comments, commit messages, or
  PR text: no ADR numbers, Brain paths, or decision-record identifiers in anything the
  public repo carries. State the rationale in plain terms instead; the ADR linkage stays
  in the Brain.

## Working in loops

These invariants bind any iterative or autonomous execution, whatever skill or loop primitive
drives it:

- Verification, success, and acceptance criteria are human-owned. They can change, but only through
  the human: surface the proposed wording and the reason, get approval, then record what changed.
  Where no human is present to approve — an autonomous loop — that is a stop condition, not a
  licence to decide. What is ruled out in every workflow is an agent weakening or rewriting them on
  its own to match what the build does.
- Autonomous iteration always has a hard stop — a retry cap, budget, or turn limit. When the stop
  is hit, report blocked with the attempt trail; do not keep iterating.
- An explicit automation-handoff contract — scope, branch/base, verification plan, review mode,
  available provider/auth, PR authorization, and an explicit `GO` — authorizes only pushing its
  dedicated branch, a draft PR at the first push, one mention of the human for each blocked stop,
  and, at `FINAL`, a ready-for-review PR with the human's review requested. Merge, deploy,
  publish, dependency changes, and every other outward action end the loop and go to the human.
- A review gate is human-owned at close: a clean agent verdict does not close it. Closing is the
  human's, or `close-design`'s terminal transition. The lead may close a `code` review bead after
  observing the human's merge of its recorded PR, citing that PR and merge commit. A PR closed
  unmerged leaves it open. A `simplify` bead does not close on merge and waits for every finding's
  disposition. Detailed closing rules live in `manage-work-graph/references/review-beads.md`.
- Beads are the state; the active design doc is the spec. State says where you are, the spec says
  where to go. Reread the spec every iteration, not just at loop start.

## Unknowns

The Brain exists to shrink the gap between the map (what the agent has been told — vocabulary,
decisions, rules) and the territory (the codebase and its real constraints). That gap is the
project's unknowns. Name them in four quadrants and use the terms exactly, so skills, issues, and
design docs speak one language:

- **Known knowns** — stated and settled. Live in `CONTEXT.md`, `adr/`, and `AGENTS.md`.
- **Known unknowns** — open questions you can name. Live in a design doc's `Known Unknowns` and in beads.
- **Unknown knowns** — tacit preferences and domain expectations, recognized only when shown.
  Surfaced by grilling and prototypes, then written into canon.
- **Unknown unknowns** — constraints, edge cases, and existing behavior you have not thought to
  consider. Surfaced by a blind-spot pass before implementation; caught mid-build as discoveries.

Cheap moves early — orient, grill, prototype — turn expensive late unknowns into known knowns.

## Brain structure

- `CONTEXT.md` — domain vocabulary for this project
- `project.yaml` — per-project skill selection and engine/tracker config
- `adr/` — Architecture Decision Records, one file per decision
- `designs/` — design docs, one initiative per file. Each design doc carries a `lifecycle:` field:
  `draft`, `active`, `shipped`, `abandoned`, or `superseded`. Agents must update lifecycle when the
  document's mutability changes. While a design is `active`, it is the living design authority for
  the initiative: current design, verification / success criteria, known unknowns, deviations, and
  design-relevant implementation discoveries live here. Authored by `to-design`, decomposed into
  bead epics by `to-issues`.
  Beads still own execution state. Once a design is `shipped`, `abandoned`, or `superseded`, it
  freezes as a point-in-time record; durable residue lands in `adr/` (decisions) and `CONTEXT.md`
  (vocabulary). Driving a design to a terminal state is `close-design`'s job.
  Design frontmatter is one field set across every Brain: `lifecycle:` (required), `started:` and
  `ended:` (dates), `extends:` (a design this one builds on), `residue:` (ADR ids produced). Per-doc
  invented fields drift the vocabulary apart; say anything else in prose
- `docs/` — derived docs, runbooks, reference material. Optional, never authoritative —
  canon wins
- `learning/` — the operator's learning workspace for this project, owned by `teach-me`. Optional,
  never authoritative; learning paths and parked concepts live in `learn:` beads. When the user
  asks to park a concept for later learning, file it per `manage-work-graph`'s learning-beads
  reference
- `site/` — the Brain site's settings (`site.yaml`, whose nav is the sidebar), its home page
  `index.md`, dotbrain's manual `configure.md`, and optional theme extensions. Optional; `dotbrain site` renders every Markdown file
  in the Brain as a page, and `brain-site` maintains it

Skills are cross-project; the Brain only configures them. Skill *selection* lives in
`project.yaml` (`skills:`); project tracker conventions live in `AGENTS.md` under Project.