Own tool, MIT licence
Agentic dev workflow: tiller
tiller is a set of procedures (skills) for AI agents in software delivery. The procedures are shared by every project, a project’s facts live in its profile, and its decisions in a register that the later steps read.
Problem
An AI agent in a repository writes code quickly. Without a process around it, though, a team gets changes nobody planned, tests written after the fact, and reviews that check style rather than whether the change does what it was meant to do.
The gaps are usually four. No specification for the agent to start from. No review that keeps conformance to conventions apart from conformance to the ticket. No boundaries: what the agent does not do alone, such as merging, sending a message or touching someone else’s PR. No memory of decisions, so every session starts from zero and reviews report deviations agreed earlier as defects.
On top of that, agent instructions that grow inside one project absorb its facts: merge rules, test commands, environment hosts. A second project means copying and hand-editing them, and an agent can apply one project’s rules to another.
Solution
tiller keeps the procedure apart from the facts. The procedure is how a ticket is opened, planned, tested, reviewed and merged. The facts are everything that differs between projects: the tracker, the branch convention, test commands, CI gates, who may merge. Every skill that works on a ticket starts by resolving the project’s profile (step −1) and stops if it finds none.
The steps that hold quality stand on that frame. The plan checks the ticket’s premise against the code. TDD starts from a test that fails for the reason the ticket describes. Review runs on two independent axes. The verdict comes from a fresh session that did not write the code.
- flow-* skills: from opening a ticket, planning and TDD through review, commit and PR to the verdict, bug diagnosis and manual QA; none of them carries the facts of a particular project
- a project profile: a local file of facts (tracker, branches, test commands, gates, merge rules, boundaries), checked by a script before an unattended run
- brains: private knowledge repositories for a project, with a register of decisions D-nnn and questions Q-nnn; a decision becomes “agreed” only once a person confirms it
- the branch’s decision ledger: a deliberate deviation recorded the moment it is taken, read by the reviews and the verdict
- two-axis review: Standards (the repository’s conventions) and Spec (the ticket plus later agreements), reported side by side and never merged into one score
- confidence check: a high-confidence or needs-review verdict computed from conditions, including proof that the tests pass at one specific SHA (CI or a local re-run)
- unattended runs: a ticket in fourteen phases with checkpoints and caps; a decision that touches a boundary on the inviolables list stops the run and waits for a person
- helm: a private overview of every project (stage, deadlines, promises); it advises and never starts work by itself
- a leak guard and an access hook: a commit naming a project, a person or a credential is refused, and one project’s session reads neither another project’s profile nor a brain it was not granted
How a ticket moves
Profile
The skill resolves the project from an environment variable, a .tiller-profile file or the repository path. No profile means stop, not a guess.
Start
The ticket is checked (status, blockers, acceptance criteria), a branch is cut from a fresh main, and a short plan is agreed before code.
Plan
The ticket’s premise is checked against the repository; a seam table names the test level and what is deliberately not tested. Decisions go into the register.
TDD
The test fails first for the reason the ticket describes, then passes. Green means the repository’s gates pass at a specific SHA, not just the assertion.
Review
Two axes in parallel, in separate subagents: Standards and Spec. Every finding carries a file location and gets a ruling.
Commit and PR
A commit in the profile’s format and a PR that always opens as a draft, with the test results and screenshots when the change touches the interface.
Verdict
A confidence check in a fresh session: high-confidence or needs-review. The profile says who merges, the agent or a person.
A sample run
Illustrative example
A fictional mini-project, bookshelf-api (a REST API in TypeScript), and ticket SHELF-12: filter the list of books by author. The log shows what each skill does according to its description in the repository; names, numbers and results are made up for the example.
/flow-start-ticket SHELF-12- profile: bookshelf (a .tiller-profile file in the repository)
- SHELF-12 · Filter books by author · Backlog, unblocked, 2 acceptance criteria
- branch SHELF-12-filter-by-author from origin/main · status: In Progress
- a 3-step plan agreed before any code
/flow-plan-ticket SHELF-12- premise confirmed: GET /books exists (src/routes/books.ts), no author parameter yet
- kind: code · seam: filterBooks(books, query) · unit · cases written up front
- deliberately not tested here: the HTTP layer beyond one request test
- decision (self, overridable): an empty ?author= returns the whole list → ledger
/flow-tdd- ✗ filterBooks › filters by author, ignoring case: expected 2 books, received 5
- red for the ticket’s reason, not a harness failure
- ✓ 6 passed · lint ok · typecheck ok
- pin: without the parameter the list is unchanged (green by design)
- with the implementation reverted, the test fails again for the same reason
/flow-code-review- Standards · 1 finding · src/routes/books.ts:18 · parameter name breaks the README convention
- Spec · 0 findings · AC1 and AC2 covered, the ledger decision honoured
- finding accepted and fixed · ✓ 6 passed
/flow-create-commit- feat(books): filter the list by author
/flow-create-pull-request- draft PR #7 · body: scope, test results, ticket link
/flow-confidence-check SHELF-12- a new session; the ticket is its only input
- CI at the head SHA: green
- AC1 covered · AC2 covered · 0 blocker / high / medium
- verdict: high-confidence
- merging follows the profile’s merge authority: here, a human signature
Results and lessons
Numbers from the tiller repository, with no claims about deployments. Each one gives the path it comes from.
- 23 flow-* skills
skills/flow-*/SKILL.md - 1011 tests declared across 89 Node test files
lines starting with test( (indented too) in *.test.mjs - 168 commits on main since the first one, 12 October 2026
git rev-list --count d536250 - 14 phases of an unattended run, each with a checkpoint
lib/driver/phases.mjs - 6 mandates within which the owner-proxy role may act for the owner
README.md - MIT licence
LICENSE
As of 22 October 2026, the main branch of the tiller repository (commit d536250).
Lessons
- Procedure and facts apart. A skill with no project facts moves to the next repository by writing a profile, not by copying instructions. A ticket skill that resolves no profile stops instead of guessing.
- Two review axes, not one score. Code can follow every convention and do the wrong thing, or the reverse. In a merged report one axis hides the other, so Standards and Spec run in separate subagents.
- Decisions written down at once. A deviation missing from the ledger is reported by review as a defect or scope creep. Recorded the moment it is taken, it becomes something the review grades rather than rediscovers.
- Green is a measurement. A test is green when the gates pass at a specific SHA; without that the verdict cannot be high-confidence. The session that wrote the code does not give it a verdict.
- Boundaries as code. Merge rules, gates and the inviolables list live in the profile, and a script checks them. A decision that touches a boundary stops the run and waits for a person. No agent role takes over a signature.
Stack
Repository
The repository is private for now; the code is available on request.
A similar problem on your side?
Tell us about it in a few clicks. You do not need a finished specification.
We usually reply within one business day. Prefer e-mail? Write to joanna@kokot.it.