orbyn-worktree ยท diff
git:20261031.ed3f1d3 to git:20261101.8be107b
73 added, 186 removed. Audit A to A.
---
name: orbyn-worktree
description: "Manage local task branches, private contribution storage when supported and Git worktree isolation; use sibling <repo>-wt directories, purpose-based names and preservation before cleanup."
---
# Worktree ownership and lifecycle
Use this skill when a task needs checkout isolation, the user requests a worktree,
- or an existing worktree needs reconciliation/cleanup. The owning
- [workflow](../orbyn-workflow/SKILL.md) selects it from the ordinary task request;
- the human does not need a separate invocation. Follow the consuming project's
- instructions, requested checkout and host permissions. A small clear edit can
- stay in its current checkout; a new worktree is not mandatory for every task.
+ or an existing worktree needs reconciliation/cleanup. The
+ [workflow](../orbyn-workflow/SKILL.md) selects it from the ordinary task request,
+ without a separate invocation. Follow the consuming project's instructions,
+ requested checkout and host permissions. A small clear edit can stay in its
+ current checkout.
## Resolve the repository and owner first
Inspect the current checkout, branch, HEAD, tracked/untracked changes and
`git worktree list --porcelain`. Resolve the primary clone and common repository
- from Git registration and the task, rather than assuming the current working
- directory is the primary clone. A linked worktree's `.git` is normally a pointer;
- do not treat it as another independent clone or derive another `-wt` root from it.
- Bare or separately configured Git directories need an explicit project anchor.
+ from Git registration and the task; the current directory may be a linked worktree.
+ A linked worktree's `.git` is normally a pointer: do not treat it as an independent
+ clone or derive another `-wt` root from it.
- Check existing worktrees and any applicable host attachment inventory before
- creating another. Reuse a suitable worktree only when its repository, task owner,
- branch, source and local work fit this task. A clean directory is not evidence
- that another active session has released it. Preserve unrelated changes and
- outputs; do not stash, reset, switch another owner's checkout, copy dirty files
- or move existing worktrees merely to enforce this convention.
+ Preserve unrelated changes and outputs. Do not stash, reset, switch another owner's
+ checkout, copy dirty files or move existing worktrees merely to enforce this convention.
## Reuse before cloning or replacing
- Continue the same task/PR in its owned branch and checkout through review and
- corrections. Inspect canonical repository/remotes, registered trees, host bindings
- and any existing reference cache before creating another. A new independent task
- uses the verified current default branch; a stack uses its exact reviewed dependency.
- Do not use a historical task branch just because it is current, or create a clone
- per agent/day/retry. Keep target nesting and the library's established sibling root.
+ Before creating a checkout, inspect registered trees, canonical repository/remotes,
+ host attachments and bindings, and any existing reference cache. Reuse a worktree
+ only when its repository, task owner, branch, source and local work fit this task.
+ Confirm that no active session still holds a clean directory before reusing it.
- Reclone only for a new repository, proven missing/unrecoverable source store,
- necessary separate trust/credential boundary or demonstrated incompatible need.
- Try suitable supported readiness/repair first; a stale cwd, conflict or old build
- is not itself a reason to reclone. An intentional partial/no-checkout reference
- cache can lack an index or visible source and show deletion-like status. Resolve
- its intended materialization mode, pinned source and owner before interpreting
- that as lost work/corruption; a promisor setting alone proves neither intent nor
- safety. Do not reset, checkout over or reclone it on that symptom alone.
- When replacement is actually authorized,
- preserve local refs/commits, binary-capable staged/unstaged snapshots, untracked
- source and valuable ignored data/configuration in permitted storage. Verify any
- bundle prerequisites and replacement beside the old checkout before deliberately
- rebinding task/host paths and rereading instructions. Do not automatically copy
- credentials, move an active path or delete the old clone. Explicit workdir success
- does not prove the host binding changed. Use [continuation readiness](../orbyn-setup/SKILL.md#resume-after-a-workspace-or-runtime-change).
+ Continue the same task/PR in its owned branch and checkout through review and
+ corrections. Start a new independent task from the verified current default branch
+ and a stack from its exact reviewed dependency. Do not use a historical task branch
+ just because it is current, or create a clone per agent/day/retry.
## Sibling location and names
- Targets use the library-root ignored `repo/` workspace by default; follow the
- [nested repository contract](../orbyn-setup/references/repository-workspaces.md).
- For `orbyn-fullstack-skills/repo/widget`, use sibling `repo/widget-wt/<purpose>/`.
- A target [registered in place](../orbyn-setup/references/repository-workspaces.md#in-place-targets)
- uses the same sibling rule beside its own path.
- Preserve target instructions/skills and inspect its Git state separately. Other existing
- external checkouts remain preservation inputs until a coordinated authorized move;
- never move active work merely to satisfy the layout. The library's own maintenance
- worktrees can use its established external sibling root, keeping library and target
- ownership distinct.
-
For a primary clone `<parent>/<repo>`, the default root is its sibling
`<parent>/<repo-slug>-wt/`. Use a stable lowercase hyphenated repo slug; reuse an
existing established sibling root rather than creating a case-only alternative.
- Each worktree has one direct child directory named for its purpose:
+ Each worktree has one direct child directory named for its purpose slug, not the
+ branch's slash-separated path:
```text
orbyn-fullstack-skills/repo/
orbyn/ primary clone
orbyn-wt/
task-rescheduling/ feat/task-rescheduling
save-retry/ fix/save-retry
worktree-policy/ chore/worktree-policy
```
- Use lowercase letters, digits and hyphens for a short directory slug, normally
- under 64 characters. Use neutral branch prefixes such as `feat/`, `fix/`,
- `chore/`, `docs/` or `refactor/`. Do not use agent, assistant, vendor or model
- branding in a new branch or directory name. Avoid path separators, traversal,
- spaces, Windows device names and case-only distinctions. A directory leaf uses
- the purpose slug, not the branch's slash-separated path.
-
- Inspect collisions before choosing another name. If the existing path/branch is
- unrelated or still owned, choose a distinct purpose or a suffix such as `-2`;
- never overwrite a directory, reuse a foreign branch or use force to bypass Git's
- already-checked-out protection. Keep existing legacy paths/branch names intact.
+ Targets use the library-root ignored `repo/` workspace by default under the
+ [nested repository contract](../orbyn-setup/references/repository-workspaces.md):
+ `orbyn-fullstack-skills/repo/widget` uses sibling `repo/widget-wt/<purpose>/`.
An explicit user location or an established consuming-project policy wins.
- ## Keep task branches local and publish deliberately
-
- A worktree and its branch are local Git state. Creating them does not require a
- branch on the company's remote. Reuse one owned task branch and worktree through
- implementation, correction and review. Do not create another branch for each
- agent, phase or retry. Independent writers may need bounded temporary local
- branches/worktrees; consolidate their changes into the owning task branch and
- retire them only after preserving the work. Never push every delegate branch.
- Serialize operations on shared Git refs, remotes and configuration under one owner.
-
- Keep work local by default. Publish only when pushing/PR delivery is authorized
- and the patch is concrete and reviewable. Inspect existing project contribution
- policy, sanitized remote identities, upstream relationship, repository visibility,
- account permission and fork restrictions before choosing a push destination.
- A remote named `origin` is not evidence that it is a personal fork.
-
- For company upstreams, prefer one existing permitted **private** personal contribution fork
- for the approved account. Create one only within authorized delivery/setup scope
- and when company/host policy allows it. Use a meaningful stable name such as
- `<Repository>-contributions`, retaining the upstream identity:
-
- | Identity | Example |
- | ---------------------------------------------------- | --------------------------------------------- |
- | Company upstream | `company/Orbyn` |
- | Reused personal fork | `approved-account/Orbyn-contributions` |
- | Task branch on that fork, when publication is needed | `feat/task-rescheduling` |
- | Local task checkout | `Documents/GitHub/orbyn-wt/task-rescheduling` |
-
- ### Privacy before publication
-
- Prefer private contribution storage whenever the host, upstream visibility and
- organization policy support it. Inspect the actual API/host result after creation;
- a requested flag or a private-sounding name is not visibility evidence. Verify
- upstream permissions and organization approval before copying restricted code
- into any personal account, including a private repository.
-
- On GitHub, native forks of a public repository are public and cannot independently
- be made private. Private upstream forks stay private where forking is permitted;
- internal-repository behavior also depends on account/enterprise policy. Do not
- attempt to bypass these rules or promise a private public-parent native fork.
-
- If the desired privacy is unavailable, keep task branches/commits local. Within
- explicit backup scope, a permitted private standalone repository can hold work,
- but it is a separate repository, not a native fork or an automatic upstream PR
- source. Verify its actual visibility, access and remotes before any push. Do not
- create it merely because an API token can. Never detach, delete or recreate an
- existing fork, rewrite its history or change upstream visibility to enforce a
- naming/privacy preference.
-
- When a public upstream PR is explicitly authorized, promote only its reviewed
- allowlisted changes through the required public contribution path. Keep unrelated
- branches, company-only material, reports and backups local/private. Explain the
- visibility boundary before a public push when privacy was requested; if public
- publication is not authorized, preserve the patch and report the specific limit.
- A private backup does not retract commits already published to a public network.
+ Use lowercase letters, digits and hyphens for a short directory slug, normally
+ under 64 characters. Use neutral branch prefixes such as `feat/`, `fix/`, `chore/`,
+ `docs/` or `refactor/`. Do not use agent, assistant, vendor or model branding in a
+ new branch or directory name. Avoid path separators, traversal, spaces, Windows
+ device names and case-only distinctions.
- Verified 24 October 2026 against [GitHub fork visibility and permissions](https://docs.github.com/en/pull-requests/reference/forks).
- Other providers require their own current policy check; do not generalize GitHub's
- constraints into a universal claim about forks.
+ Inspect collisions before choosing a name. If the existing path/branch is unrelated
+ or still owned, choose a distinct purpose or a suffix such as `-2`; never overwrite
+ a directory, reuse a foreign branch or use force to bypass Git's already-checked-out
+ protection. Keep existing legacy paths/branch names intact.
- Verify that a candidate fork actually belongs to the intended upstream; matching
- names are insufficient. Preserve an established fork/name rather than renaming it
- or creating one per task. A local worktree stays within the primary clone's Git
- repository and can push its task branch to the permitted fork remote; it is not
- another hosted fork. Keep fetch/base selection tied to the canonical upstream
- and target the contribution PR back to the correct upstream branch.
+ ## Keep task branches local and publish deliberately
- Never copy private/restricted company code into a public or otherwise unauthorized
- fork, standalone mirror or account. An available API token does not establish
- redistribution authority. If forks are disallowed, use an explicitly authorized
- internal contribution path; otherwise preserve the local branch/commits and prepare
- a reviewable patch with the exact publishing blocker. Do not silently fall back
- to pushing a new company branch or stop independent local work. Respect an existing
- explicit company-branch instruction instead of inventing a fork requirement.
+ A worktree and its branch are local Git state; they need no branch on the company's
+ remote. Reuse one owned task branch and worktree through implementation, correction
+ and review instead of creating one per agent, phase or retry. Never push every
+ delegate branch. Serialize operations on shared Git refs, remotes and configuration
+ under one owner.
- Before any push, verify the destination account/repository/visibility, source
- branch and refspec. Add/change a remote or branch tracking only within scope;
- do not rewrite `origin`, alter global Git settings, force-push a foreign branch
- or publish merely because a branch exists. Report where work is local, backed up,
- pushed and proposed for review. A local branch is recoverable only while its
- checkout/Git data remain; preserve valuable unpushed work before cleanup.
+ Keep work local by default. Before any push, follow
+ [contribution storage](references/contribution-storage.md). A local branch is
+ recoverable only while its checkout/Git data remain; preserve valuable unpushed
+ work before cleanup.
## Create and verify the selected checkout
- For unattended execution, verify required host capabilities on a disposable
- checkout with the actual topology before expensive work. A primary-clone commit
- probe does not establish write access to a linked worktree's separate Git index
- or common metadata. Test only effects already authorized by the task.
- If the host denies metadata writes, preserve the patch and report delivery as
- blocked; do not rewrite `.git`, supply an alternate index or bypass the sandbox.
- A separately authorized new workspace must have its own readiness evidence;
- never move or reset existing owned work to manufacture a passing probe.
-
Resolve the requested base revision before writes. Continue an existing task/PR
- from its actual branch or reviewed commit. For new work, use the project's
- verified default branch/ref; do not assume that an unrelated current feature
- branch or a stale local `main` is the desired base. Fetch only when available and
- authorized; label an offline/cached base as such. A clean worktree does not copy
- the primary checkout's uncommitted changes. If those changes are required, plan
- a selective, recoverable transfer with their owner instead of silently omitting
- or copying them.
+ from its actual branch or reviewed commit. For new work, use the project's verified
+ default branch/ref, not an unrelated current feature branch or a stale local `main`.
+ Fetch only when available and authorized; label an offline/cached base as such.
- Use a supported host worktree tool when it meets the requested layout and
- ownership contract. If its storage path is fixed elsewhere, report the limitation
- and use a permitted Git operation when appropriate; do not claim a custom path
- was honored when the tool chose another. Creating a worktree does not create a
- new project chat or authorize messaging another owner.
+ Create a **new** branch from a verified base with
+ `git worktree add -b <branch> <path> <base>`. Reuse an existing branch with
+ `worktree add <path> <branch>` only after ownership/checkout inspection. Avoid `-B`,
+ `--force` and duplicate branch checkouts. Verify the final path, branch, base/HEAD
+ and status before editing.
- For a **new** branch with a verified base, an example operation is:
+ Use the selected worktree as the working directory for every subsequent edit/check.
+ After selecting or switching checkout, reread nested instructions and re-resolve
+ search roots there under [action scope](../orbyn-setup/references/action-scope.md).
- ```sh
- git -C /work/orbyn-fullstack-skills/repo/orbyn worktree add -b feat/task-rescheduling /work/orbyn-fullstack-skills/repo/orbyn-wt/task-rescheduling origin/main
- git -C /work/orbyn-fullstack-skills/repo/orbyn-wt/task-rescheduling status --short --branch
- git -C /work/orbyn-fullstack-skills/repo/orbyn-wt/task-rescheduling rev-parse --show-toplevel HEAD
- ```
+ Preserve project environment files; do not automatically copy secrets or run setup
+ hooks from source. Worktrees share Git objects and may still share databases, ports,
+ fixtures or external services: assign those separately.
- These paths/ref are examples, not values to copy into another project. Reuse an
- existing branch with `worktree add <path> <branch>` only after ownership/checkout
- inspection. Avoid `-B`, `--force` and duplicate branch checkouts. Verify the final
- path, branch, base/HEAD and status before editing. Use the selected worktree as
- the working directory for every subsequent edit/check; reread relevant nested
- instructions there. Preserve project environment files; do not automatically copy
- secrets or run setup hooks from source. Worktrees share Git objects and may still
- share databases, ports, fixtures or external services: assign those separately.
- Use [action scope](../orbyn-setup/references/action-scope.md) after selecting or
- switching checkout: re-resolve applicable instructions and search roots there.
- Shared Git history or project memory does not establish identical rules, source
- or branch-specific applicability; do not reuse another checkout's search results
- as current evidence.
+ If the host denies Git metadata writes, preserve the patch and report delivery as
+ blocked. Never rewrite `.git`, supply an alternate index or bypass the sandbox.
## Designate task verification
Before expensive runs, use the CI owner's [feature-worktree gates](../orbyn-ci-design/references/change-scope.md#designate-gates-for-the-feature-worktree).
- Name focused checks for the affected contracts and consumers, exclusions and
- conditions for widening in the existing task brief. A new worktree does not imply
- an entire-app suite, new hosted CI or deployment. Required repository statuses
- still apply at delivery; isolated files do not establish isolated runtime effects.
+ Name focused checks, exclusions and conditions for widening in the existing task
+ brief. A new worktree adds no entire-app suite, hosted CI or deployment.
## Preserve before cleanup
At a meaningful handoff or terminal delivery result, apply the single
[task closeout method](references/task-closeout.md): reconcile source, commit,
push, PR and resource states, decide retention with a reason/review trigger,
and assess exact-path retirement separately from permission to remove it.
- A squash merge or clean status alone is insufficient. Use supported managed
- archive/Git removal only after ownership, later commits, dependencies, ignored
- artifacts, live previews and recovery are resolved. A refusal has no automatic
- force fallback; local/remote ref deletion and tracking prune remain separate.
- For preview/evidence storage, server/volume ownership and retention classes, use
- [artifact lifecycle](../orbyn-workflow/references/artifact-lifecycle.md).
+ Never delete another owner's work; unknown ownership means hold. A squash merge or
+ clean status alone does not clear a tree for removal. Use supported managed archive/Git removal
+ only after ownership, later commits, dependencies, ignored artifacts, live previews
+ and recovery are resolved. A refusal has no automatic force fallback; local/remote
+ ref deletion and tracking prune remain separate.
+
Return the selected path/base/head, verified delivery state, retained resources,
recovery pointers and actual closeout disposition. A dry run changes nothing.
+
+ ## Read when needed
+
+ - Pushing, forks, private storage, backups or a public PR: [contribution storage](references/contribution-storage.md).
+ - Recloning, replacing a checkout or an empty partial cache: [checkout replacement](references/checkout-replacement.md).
+ - In-place, external or bare layouts, delegate branches, unattended runs, denied metadata writes, required dirty primary changes, host worktree tools, search results from another checkout, required statuses at delivery or a worked command example: [checkout setup](references/checkout-setup.md).
+ - Preview/evidence storage, server/volume ownership or retention classes: [artifact lifecycle](../orbyn-workflow/references/artifact-lifecycle.md).