Sonensei
TFP
Task Flow Protocol. A git-native protocol for teams of humans and AI coding agents. Instead of an orchestrator that hands out work, agents pull the next ready task from a board that lives in the repo. Git is the referee: a claim is a commit, and only one push can win. It needs only Python 3 and git.
Three parts
No server, no orchestrator, no database. Any agent that can run a shell command can join, and people use the same commands as the agents.
The protocol
AGENTS.md: one page of rules that every agent reads first. How to take a task,
finish it, hand it back, and what to do when something is unclear or a merge conflicts.
The board
tasks/*.md: one Markdown file per task, next to the code. The front matter holds
status, owner and dependencies; the body holds the goal and checkable acceptance criteria.
The tools
tasks.py for the verbs, agents.py to run several Claude Code agents
(each in its own clone), and a local dashboard that gives people the same actions as buttons.
How it works
Five verbs carry the protocol. The rest is for edge cases.
| Verb | What it does | Guarantee |
|---|---|---|
| next | Lists ready tasks, the ones that unblock the most first | Dependencies are respected |
| claim | Takes a task: a commit that is pushed to main | Exactly one owner; the loser is told who won |
| done | Merges the latest main, runs the project check, then pushes | Main only ever holds finished, checked work |
| release | Hands the task back with a note | Work in progress survives on wip/<id> |
| assume | Records a decision a person may want to revisit | Agents never wait for an answer |
When an agent dies
A claim is a lease that the runner renews while the agent is alive. If a laptop closes or a session
ends, the lease expires and another agent takes the task over, starting from the
wip/ backup of the previous owner's commits, not from zero.
When people are asleep
Agents pick the most reasonable option and record it as an assumption. People review the assumptions later, answer questions on held tasks, freeze the board while they replan, or drop work that is no longer wanted.
When the plan is wrong
Agents may split a task that is too big, add a missing one, or put one on hold with a question. Limits keep this in check: subtasks can't be split again, and after two sessions a task goes to review.
Across several repos
Existing repos, for example a backend and a frontend, are imported as folders of one working repo. A sync publishes each folder back to its original repo.
Dashboard
A local web app for the people on the team. Each person runs it on their own laptop, in their own clone.
Every button runs the real command, so a claim from the dashboard can lose a race just like one
from the shell. It listens on 127.0.0.1 only.
Get started
A board in your repo
git clone https://github.com/OldPeasant/tfp ../tfp
cp ../tfp/{tasks.py,agents.py,board.py,repos.py,AGENTS.md} .
python tasks.py new api "Define the API" --deps spec
echo "make check" > .taskcheck
python tasks.py next # ready tasks
python tasks.py claim api
python tasks.py done api # check, pushAgents and dashboard
python agents.py start 4 # 4 agents here
python agents.py status
python dashboard/server.py # dashboard
python tasks.py assumptions # their decisionsIt comes with a 22-task starter board for a typical full-stack app with an AI feature. The README on GitHub has the full setup, including several repos.