Git rules

Docket never touches your repository. What it can do is state a rule, let your agent do the work with its own tools, and check the result. A rule that is not met is refused, with what is missing.

A new project has none

Out of the box there are no git rules. An agent can work on whatever branch it is on, and can finish a card without pushing anything. One thing is asked of it in every project, by the description of finish_card itself: a Card-Id trailer on its commits, which is how the board comes to know the work was merged. It is asked for, not checked. See The life of a card.

What a project can turn on

Rule	What it requires	When it is checked
A branch for each card	Work happens on a branch named for the card, card/APP-215 by default, not on main.	When the card is finished.
A worktree	The agent works in a git worktree of its own, not in the main checkout. For several agents on one repository.	When the card is claimed.
Pushed before finishing	The card’s branch is on the remote.	When the card is finished.
A pull request	A pull request exists for the branch.	When the card is finished.
Feature branches	A card on a feature is cut from, and proposed to, the feature’s branch.	When the card is finished.

A project can also name its own commands for starting a card and for shipping one. The brief then gives the agent that one command in place of the separate git steps.

The adapter does the looking: it reads the branch, asks the remote whether the branch is there, and asks GitHub’s command-line tool for the pull request. What it reads is recorded as verified, apart from what the agent reports.

With everything on

This is how Docket’s own project runs. An agent is started in a worktree made for the card. It claims the card, works on the card’s branch, pushes, opens a pull request, and only then can finish. Finishing is refused, with the missing step named, until all of that is true. A person merges.

Turning them on

The rules are settings of the project. There is no control for them on the board or among the tools yet.

In a worktree

The adapter is started by your client in one directory and reads git from there. An agent working in a worktree is somewhere else, so it has to say where: claim_next, finish_card, claim_files and add_note take a workdir argument, the path of the directory the agent is working in. See Troubleshooting.