← All projects

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.

  • software teams
  • AI agents

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

How a ticket moves through tillerA top-to-bottom diagram. The skill resolves the project profile and stops without one. Then the ticket start, the plan, TDD, review on two parallel axes (Standards and Spec), the commit and a draft PR, and a confidence-check verdict in a fresh session. At the end, either the agent merges, when the profile allows it, or the PR waits for a human signature. Alongside runs the branch’s decision ledger: the plan and TDD write it, the reviews and the verdict read it.branch decision ledger → read by review and verdictProject profilestep −1no profile = stopStartflow-start-ticketticket, branch, short planPlanflow-plan-ticketpremise, seams, decisionsTDDflow-tddred → green, repo gatesStandardsflow-code-reviewrepo conventionsSpecflow-code-reviewticket + agreementsCommit and PRflow-create-pull-requestalways a draft PRVerdictflow-confidence-checkfresh session, tests at the SHAAgent mergesmerge authorityprofile permittingHuman signatureready-to-signthe PR waits open
The interactive path, one skill per step; the last row is the profile’s merge rule. An unattended run takes the same steps through the driver’s fourteen phases.
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. Review

    Two axes in parallel, in separate subagents: Standards and Spec. Every finding carries a file location and gets a ruling.

  6. 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.

  7. 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.

  1. /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
  2. /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
  3. /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
  4. /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
  5. /flow-create-commit

    • feat(books): filter the list by author
  6. /flow-create-pull-request

    • draft PR #7 · body: scope, test results, ticket link
  7. /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
A session on the fictional bookshelf-api project, from opening the ticket to the verdict. This is not a recording of a real project. The steps and their order follow the skill descriptions in the tiller repository; nothing here calls an API.

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

  • Claude Code
  • Codex
  • Bash
  • Node.js
  • GitHub CLI

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.

Tell us what you dream of

We usually reply within one business day. Prefer e-mail? Write to joanna@kokot.it.