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.

RepoCard

What a repository’s .brain/project.md says about it, travelling with its code (and its git):

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

cards_dir

The folder of the projects’ shared cards in the central brain.

central_dir

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

check_name

Names are written as - name: path lines and typed after --project, where / separates the repository, so they’re one line without : or /, and not the central brain’s name.

check_repo_name

Repository names are typed after --project NAME/ and written in links as REPO#ID, which a space, , or # would split, so they’re one word without those or : and /.

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), in any case when that names only one; 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

A .brain/ folder’s card; None if it has none (not a project’s repository).

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. Only its own: one a name slugging alike wrote over it before 0.4.0 is that project’s.

rename

Renames project old to new in the registry and its shared card (the file and its title). Its repositories’ own cards are the caller’s: their folders may be elsewhere, or gone.

repo_name

The name the repository whose .brain/ is dir takes in project: wanted if given, refused when another of the project’s repositories has it; else the one its card gives if it stays in that project, else its folder’s. When another repository has that one (two folders named app in different places), the folder above goes before it (backend-app), then a number: two repositories of a project can’t share a name, as --project and links (app#3) tell them apart by it.

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. Another project’s card where it goes, one whose name slugs alike from before 0.4.0, moves to its own place first rather than be overwritten; the project’s own card from then goes.

write_repo_card

Writes a .brain/ folder’s card.