Skip to diagrams
dotfilesGitHub

Agent bundles / developer / worktree skill

Worktree workflow

Who coordinates the work, how sessions hand off, when a review is valid, and which records prove completion.

04 diagramsOwnership → handoffs → review gates → recordsFull-width maps · scroll locally on narrow screens
01

Who owns what

Ownership map
Who owns whatYou invoke the worktree playbook. It coordinates shared-context for paths and records, muxer-subagents for fresh sessions, Worktrunk for Git worktrees, and the ticket skill for the issue reference.YouSelect a phaseWorktree playbookCoordinate the phaseshared-contextResolve storage routesmuxer-subagentsCreate fresh sessionsWorktrunkOwn Git lifecycleTicket skillResolve issue referenceRecordsResolved locationsNew agentIndependent contextGit worktreeSource workspaceCoordination is not ownership of storage, sessions, or Git.

The playbook coordinates; shared-context, muxer-subagents, Worktrunk, and the ticket skill retain their own responsibilities.

02

Start and review handoffs

Sequence
Start and review handoffsStart launches an implementation agent. Review launches a different reviewer session in the same source worktree. A signal is transient; the parent verifies persisted receipts after each completion.YOUWORKTREE PLAYBOOKFRESH AGENT SESSIONstart(ticket)Implementation handoffCompletion signal + durable receiptreview(ticket)Different reviewer · same source worktreeVerdict for the frozen commit01 / Request02 / Verify receipts after each signal03 / Never reuse the implementer

The implementation and review use separate agent sessions in the same source worktree. The parent checks receipts after completion signals.

03

Review and finish gates

State machine
Review and finish gatesImplementation becomes reviewable and is reviewed. FAILURE leads to a fix, a new commit, and review again. SUCCESS approves only the frozen commit. An approved source can finish directly or optionally submit a pull request before finishing. A new commit invalidates the approval.ImplementingFresh implementationReviewableFreeze source commitReviewIndependent reviewerApprovedCommit-bound verdictNeeds fixFix → new commitSubmittedOptional pull requestFinishedFinish directly or after PRSUCCESSFAILUREReview againSubmitFinishFinishNew commit invalidates the previous verdict

FAILURE requires a fix and another review. SUCCESS applies to the reviewed commit. Submission is optional before finish; a new commit invalidates the verdict.

04

Where records go

Provenance graph
Where records goPhase-start, phase-result, and phase-complete receipts populate events, the append-only authoritative log. Reviews and snapshots are immutable artifacts; manifests and projections are replaceable views. Evidence paths are resolved separately.Phase-startBefore the child runsPhase-resultPersist the outcomePhase-completeParent verificationevents/ · append-onlyAuthoritative phase receiptsReviews + snapshotsImmutable outputs / referencesManifest + projectionsReplaceable current viewsEvidence referenceResolve its route separatelyImmutableReplaceable

Append-only events are authoritative. Reviews and snapshots remain immutable; manifests and projections are replaceable. Evidence uses its separately resolved route.