Module projects 

Projects: work that keeps its tasks next to its code, in one or more repositories. Each repository has its own .brain/ (its own tasks, numbered from 1) and belongs to a project; several services of one project are several repositories with the same project name. init registers each in the central brain’s projects.md, so the kanban app can show every project and filter by one, or by one of its repositories.

What every repository of a project shares is its card, projects/<name>.md in the central brain: the application’s horizontal context (what it is, its services and how they connect, conventions they share). A repository adds its role among them (what it owns, exposes and consumes) in its .brain/project.md, whose title also says which project it belongs to. How to work on one repository’s code (build, test, style) is its CLAUDE.md / AGENTS.md’s, which agents already read, so none of it is repeated here.

Entries outside any project live in the central brain: $KANBRAIN_DIR, else the platform data folder.

Structs

ProjectInfo

A repository’s view of its project: the shared card, and its own notes.

Repo

A registered repository of a project.

Constants

CENTRAL

What the central brain is called where projects are listed; no project can take the name.

PROJECT_FILE

In a repository’s .brain/: the project it belongs to (the # title) and notes about it.

REGISTRY_FILE

In the central brain: every registered repository, - project: path of its .brain.

Functions

central_dir

The central brain’s folder: $KANBRAIN_DIR, else the platform data folder.

ensure_description

Creates the project’s shared card with a placeholder if it has none yet; returns whether it did.

find

The repository label names (shop, or shop/api when the project has several); the error lists the labels there are.

info

What the repository in dir knows of its project: None outside a project. Without central, only what its own card says.

load

The registered repositories, in the order they were registered. No registry means none yet.

read_description

The project’s shared description; empty if it has no card, or only the placeholder init wrote, so nobody reads the placeholder as a description (an agent pays for it in every context).

read_repo_card

The project a .brain/ folder says it belongs to, and its notes about itself.

register

Registers the repository in dir as part of project, moving it if it was registered under another project. Two live repositories with the same name in one project are refused, since --project and the app’s filter tell them apart by name; a registration whose folder is gone gives way.

remove_description

Deletes the project’s shared card; returns whether there was one.

same_dir

Whether two paths are the same folder, however they’re written: a registered path may go through a symlink (/var is /private/var on macOS) or be typed by hand, and still name the folder opened.

unregister

Takes the repository whose .brain/ is dir out of the registry, and returns it; None if it wasn’t registered. Its folder may be gone: a deleted repository can still be taken out.

write_description

Writes the project’s shared card.

write_repo_card

Writes a .brain/ folder’s card: the project it belongs to, and its notes.