How thirdshift works

The Day shift is you: settle what should change, what success looks like, and what is out of scope. Put that in a GitHub issue. One session's worth of work can stand alone; a larger Spec is an issue with Tickets as GitHub sub-issues. We'll follow a standalone issue first.

1. Day shiftClarify the behavior and acceptance criteria
2. GitHub issueRecord the agreed work
3. RunGive thirdshift the Issue URL

From a clone of the issue's repository, normally checked out on your intended Base branch, start a Run. In this example, main is the Base branch and the pull request will target it:

cd ~/repos/widgets
thirdshift --no-merge https://github.com/acme/widgets/issues/7

--no-merge explicitly leaves the pull request for review, even if your User config normally requests merging. Before starting, install and authenticate GitHub CLI (gh) and your chosen Harness (the agent CLI, such as Claude Code or Codex), configure Git's commit identity and push access, and install the repository's test toolchain. thirdshift setup chooses machine defaults.

thirdshift checks that the Issue URL matches the clone's origin, that the issue is open, and that the Base branch, Harness and Git identity are usable. It selects an Issue branch, marks the issue in-progress (its Claim), then acquires a sibling Git Worktree. A fresh Issue branch starts from the fetched Base branch on origin.

Launch directory~/repos/widgets/Checked out on mainYou start thirdshift here

Run's Worktree~/repos/widgets-issue-7/Checked out on issue-7The agent edits and tests here

Shared Git history and remotes · separate checked-out files

The work happens in the Worktree rather than switching your Launch directory to the Issue branch. If an existing Issue branch has no pull request or an open one, thirdshift continues it instead of starting over. An open pull request supplies its Base branch. Once a branch's pull request is closed or merged, later work uses a new numbered Issue branch.

thirdshift starts a headless session in the selected Harness, in the Worktree. The Session prompt supplies the issue, Base branch, Issue branch and review instructions. Factory skills are linked where that Harness discovers them. The opening session carries the change from implementation through review to a committed branch and pull request.

1. ImplementRead the issue and repo instructions; test first where possible
2. ReviewIndependent Standards and Spec reviewers inspect the change
3. PublishAddress findings, commit, push and open the pull request

The Standards axis checks repository coding standards and code smells. The Spec axis checks the change against the issue. For findings that say behavior is wrong, the implementing agent must run the reviewer's reproducer before deciding: a demonstrated failure gets fixed with its test kept; a declined finding needs evidence that exercises it. Skipped findings go in the pull request's Unaddressed findings section, and decisions for the Day shift get a linked triage issue.

These are agent reviews, followed by deterministic Git and CI checks in Delivery. They do not guarantee correctness or replace your judgment. You can inspect the exact prompts and Factory skills, including the review procedure.

A pull request existing is not the finish line. Delivery runs the opening session, then keeps the captured pull request mergeable and checks CI. This orchestration is thirdshift's code; a Repair is another agent session started when the branch needs work.

1. Merge in the Base branchBring the latest upstream changes into the Issue branch; never rebase
2. Push and watch CI on this headCheck mergeability and whether the Base branch moved while checks ran
3. Reach a checked pull requestMergeable, with CI green or no CI checks, and no upstream change still to reconcile

Conflict or the branch's own CI failure?Start a Repair to resolve or fix it.Then return to merging the Base branch ↑

Base branch moved during CI?Reconcile the new upstream state.Return to merging the Base branch ↑

Repair and upstream-move budgets keep the loop bounded. If a CI-fix Repair leaves the same failing head, that head gets one Check re-run; if its own checks stay red, the Run fails rather than spending more Repairs on unchanged code.

An Inherited failure is a check that also failed under the same name on the Base branch commit last merged in. thirdshift does not ask a Repair to fix that on this Issue branch. It fails the Run, or, when allowed, starts a separate Base fix and waits before trying again.

An optional Security review runs after the opening session (or after the Spec review for a Spec PR). It fixes reproduced vulnerabilities introduced by this change; an introduced finding left unfixed holds Self-merge. Security review details.

Ordinary cleanup removes the factory-owned Worktree and local Issue branch after work reaches origin; the remote work remains available for review or continuation. Cleanup retains resources when ownership or preservation is uncertain. A successful Self-merge also deletes the remote Issue branch and closes the issue. A merge refused by repository policy can fail the Run while leaving the pull request ready.

You can watch progress without interrupting the agent:

thirdshift status
thirdshift show https://github.com/acme/widgets/issues/7
thirdshift logs https://github.com/acme/widgets/issues/7 --follow

The Command log records the whole command; Session logs record the individual agent sessions, and the Activity log records starts and outcomes per repository. Optional email notifications report how the Run ended. Inspecting logs.

When the Issue URL has Tickets as GitHub sub-issues, thirdshift starts a Spec run. GitHub's “blocked by” links determine when a Ticket can start. Independent Tickets can run in parallel, each in its own Worktree; a blocked Ticket waits for its prerequisites to land.

Ticket A / RunWorktree + Issue branch AMerge its PR into the Spec branch ↓

Ticket B / RunWorktree + Issue branch BMerge its PR into the Spec branch ↓

1. Ticket C / RunStarts after A and B land; merges its PR into the Spec branch ↓
2. Spec review + DeliveryReview the whole Spec branch against the Spec and Base branch
3. Spec PR → Base branchOne combined pull request for you to review, or for a requested Merge run to merge

Each Ticket is a Merge run into the Spec branch, not directly into main. The Spec PR gathers the result into the Base branch. A Ticket closing means its work landed on the Spec branch; the whole Spec has not shipped yet.

A failed Ticket stops only its dependents; other reachable Tickets can still run. Tickets marked for human work or triage also hold their dependents. An incomplete Spec leaves a draft Spec PR with a Tickets checklist. Rerunning continues existing branches. Spec run controls and limits.

A direct Issue URL starts work you have already chosen. Other commands find work, then dispatch the same Run or Spec run you just followed. Each invocation makes one pass; your operating system's scheduler starts the next one.

Pickup runTakes the lowest-numbered eligible Ready issue, labelled ready-for-agent

Architect run / WeedingReviews architecture; a strong recommendation becomes an Architect plan, otherwise an idea waits for triage

Security run / FencingAudits and reproduces findings; records them privately and dispatches fixes only when allowed

Eligible work ↓ Run or Spec run ↓ reviewed pull request

Pickup respects issue readiness, open blockers and the Claim limit. Architect and Security runs yield to ready human-shaped work. Gates can skip a pass without failure, and unresolved plans, ideas or findings can leave the next decision with the Day shift. This is scheduled CLI work on your machine, using your authenticated tools.

Next: inspect every prompt and skill, see a real Run's recorded output, or use the manual for installation, commands and configuration.