Philosophy
Why Kanbus works the way it does
A few principles explain most of the decisions in Kanbus, from one file per issue to the words it uses for work.
Put the plates on a shelf
Kanbus started from a simple need: somewhere to put open loops without switching applications. When you are juggling chat sessions, pending tasks and decisions you have not written down, you need a place for them that does not ask you to log in or run anything. Kanbus lets you and your agents write that context into the repository the moment it comes up. It is the difference between keeping fifteen plates spinning in your head and putting them on a shelf.
Files are the database
There is no hidden database, no background service you have to keep alive and no remote API between you and your issues. The state of the project is the set of JSON files in the repository, and every command reads those files directly. When a cache or a live channel helps, it stays a cache: delete it and nothing is lost.
One file per issue
Trackers that keep every issue in one file guarantee merge conflicts as soon as two people, or two agents, work at once. Kanbus gives every issue its own file, so parallel work on different issues merges cleanly and git does what it is good at.
A small model of work
A tracker should take load off your mind, not add to it. Kanbus keeps a deliberately small set of fields: type, status, priority, parent, dependencies, labels, assignee and comments. A small model is easier for people to keep in their heads and leaves less noise in an agent's context.
Use the words models already know
Epics, tasks, sub-tasks, bugs, status and priority are the vocabulary of decades of project management, and models have read a great deal of it. Kanbus uses those words on purpose, so an agent knows what to do with the board before it has read a line of instructions.
Lean on git
Scope and privacy come from tools you already use. Ignore a folder and its issues stay on your machine; keep a private board next to the shared one with kbs init --local; branch the board along with the code. Kanbus adds as little as it can on top.
Standing on the shoulders of Beads
Kanbus is a spiritual successor to Beads, which proved that a tracker inside the repository is a natural home for agent work. Kanbus keeps that idea and changes the parts that hurt in practice: it drops the secondary database and the sync step, splits issues into separate files, trims the model down and uses standard names. It can still read a Beads repository while you move over.