Owlshift Owlshift

Adopt a project on a team

This page is for a developer who joins a project that already runs Owlshift, with colleagues who each run their own. Every developer has a runner on their own machine, signed in with their own accounts and running agents on their own Claude subscription. The runners coordinate through the tracker and the git remote: nothing is hosted, and there is no Owlshift server.

Section 1 is for whoever writes the team's project file, once; as you join, check that it reads as shown there. Some lines below are shortened, marked …; your repository's name, paths and accounts will differ.

Before you start

A team works on Linear or GitHub Issues. The Markdown tracker serves one machine: it has no background service, and nothing it writes reaches another machine.

1. The team's project file

Three settings of owlshift.toml make a project a team's. Each is changed through a pull request to the default branch: the background service reads the project file of the default branch, never your checkout's.

The people table. [people] lists each person once, under a handle, with their accounts:

[people.ann]
tracker = "8d0e7c1a-3f52-4b9e-a6d4-91b2c07e5a18"   # Linear user id; on GitHub Issues, the numeric account id
forge = "ann-dev"                                  # GitHub login; without it, none of their reviews is read

[people.lea]
tracker = "2f9c51d0-6a3e-4b7e-9d41-0c8a7e5b3f12"
forge = "lea-martin"

A handle is 1 to 32 lowercase letters, digits, - or _, starting with a letter. With the table, [tracker].admitters and each [zones."<path>"].owner name handles instead of accounts, and every person with a forge login is a reviewer whose reviews are read: [forge].reviewers beside the table is refused. A person who admits tickets is listed twice, once in [people] and once by handle in the admitters:

[tracker]
admit = { label = "agent" }
admitters = ["ann", "lea"]

A label, not a state, admits a ticket. On a team the admission gesture is personal: each developer puts the label on their own tickets, and a runner takes only the tickets its own operator admitted. A state gesture (admit = "ready") counts the account of whoever moved the ticket to the ready column. On a team that is often the person who grooms the backlog, so their runner takes the ticket, or nobody's if they run none. On GitHub Issues the agent:ready label that init writes as the gesture is such a state too: set admit = { label = "agent" }, and owlshift init creates the label agent once the file names it.

Claims on the remote. Under [policy]:

claims = "remote"

Before its first run on a ticket, a runner claims it with a ref on origin, refs/owlshift/claims/<ticket>, and its service renews the claim every hour. Every runner reads the others' claims, so a ticket is never worked by two machines: two people's, or one person's laptop and desktop. A Build also waits for the files another machine's ticket holds. A claim publishes, on the remote, the ticket's identifier, its operator's handle, the runner's identifier (16 random hexadecimal digits, never a host name), when it was claimed and when it expires, and the paths the ticket holds. It never publishes the ticket's text, a plan or a question. On a public repository with a private tracker that much becomes public, which is why claims are the project's choice. Left at "local", the default, two machines can work one ticket.

[policy].max_in_flight and [policy].max_open_prs count each runner's own tickets, so a project's total grows with its developers.

2. Set up your machine: owlshift init

In your clone, at the repository's root:

cd ~/code/shop
owlshift init

The project file is kept as it is: init never writes to a file that exists, and its values win over any flag.

~/code/shop/owlshift.toml exists: kept as it is. Its values win over --tracker, --team and --gate.

It then asks for your secrets, which go to this machine's keychain. They are yours, not the team's:

On GitHub Issues there is no app credential to ask for: the GitHub sign-in is also the tracker's.

Once the tracker answers, init compares the accounts you signed in as with [people]. When they are not listed, it prints the entry to add, filled in with your tracker account and GitHub login:

`[people]` in ~/code/shop/owlshift.toml does not list the accounts this machine signed in as. Add this entry through a pull request, choosing its handle:

[people.<handle>]
tracker = "5b7e3a90-…"
forge = "eve-dev"

When one of your two accounts is listed and not the other, it says lists one of the accounts this machine signed in as, not the other and prints the entry that replaces it. When your tracker account and your login are listed under two handles, it says One person is one entry: fix the file by hand, through a pull request.

owlshift init --skip-secrets stores nothing and reads no account, so it prints no entry.

3. Add yourself to the team

Open a pull request that adds your [people.<handle>] entry and, so that your label admits tickets, your handle to [tracker].admitters. Until it is merged into the default branch your label admits nothing, and owlshift why says why your tickets wait.

4. Check the machine and the team: owlshift doctor

owlshift doctor

Run it until it ends with Ready. Besides the lines every adoption page describes, three lines tell whether the project is set up for a team. They read the project file of your checkout, so pull the default branch first:

Each warning ends with the change to make through a pull request, and points back to this page. Under remote claims a second claims line may say that a claim on origin does not read; when it was written by a later Owlshift, upgrade yours.

5. Admit and answer your own tickets

From here a ticket is yours as on a project of one person:

What colleagues see of each other's tickets

What a claim does not show, the ticket's plan and questions, stays on the machine that works it and on the ticket.

Hand a ticket over: owlshift release

A ticket stays with the runner that claimed it, waiting and parked included, until its pull request is merged or closed. To give it to someone else:

owlshift release ENG-12

The release deletes the claim and posts a [owlshift] RELEASED comment on the ticket that names who released it, who held it and how to restart it. The ticket's stage is left as it is. Then the person whose runner should take it admits it again: they move it back to the ready column and put their label on it, taking it off first if it is there. If the earlier runner pushed a branch owlshift/<ticket>, a new claim is refused while it is on origin: close its pull request and delete the branch first, or finish that pull request by hand.

What a team does not get yet

Teams are roadmap step P10, built on main and not yet through its exit gate.

Next