Insist on a Unique Worktree for Every Task and Package It as the repo-worktree Skill

[ptr727]

What this does

One consolidated update covering #711 and #714, per the maintainer's direction that the two land together rather than as scattered rules. It includes the fix-714-branch-verification branch (all of PR #716 plus its unpushed Copilot nit-fix commit), so this PR supersedes #716, which can be closed unmerged.

The worktree mandate (#711)

• GOVERNANCE.md "Repository Boundaries and Write Safety" gains the affirmative task-start rule: every task, a continuation of a prior session's task included, isolates into its own git worktree before its first file edit, based on the branch work starts on per "Branching Model". The primary checkout is the maintainer's own surface.
• New repo-worktree skill (kept-authority shape: GOVERNANCE keeps the law, the skill is the task-start surface) carrying the mandate's trigger moments plus the mechanics as its own content: base-branch choice, the Propose a Repo and Worktree Layout Convention and a repo-worktree Skill #699 layout convention (~/repos/<Repo>, ~/repos/worktrees/<Repo>-<task-slug>), the git worktree add + EnterWorktree path: sequence, listing, and post-merge cleanup. The physical migration of existing checkouts stays tracked in Propose a Repo and Worktree Layout Convention and a repo-worktree Skill #699.
• git-commit-conventions tightened: stage by explicit path, never git add -A or git add ., and the pre-commit git status check generalizes from "the maintainer's own uncommitted edits" to "any change this session did not make", with ask-or-stop as the response, never bundling. The GOVERNANCE "Git and Commit Rules" summary matches.
• Host-wide agent-safety block (host-setup/agent-safety/claude-md-safety.md) gains the same task-start bullet, naming "worktree" in so many words so Claude Code's EnterWorktree tool is armed even in sessions no AGENTS.md reaches. Machines pick it up on their next installer re-run (Roll out global ~/.claude/CLAUDE.md safety rules to all machines #365 cadence).
• AGENTS.md map annotates the boundaries row with the new skill and updates the no-skill-by-decision paragraph and the closing skill inventory.

The base-branch rule (#714, from PR #716)

Carried in unchanged apart from consolidation cross-links: GitHub's default-branch setting reads main but work starts on develop, so a worktree defaulted to "the default branch" silently misses in-flight content, and a "does not exist" claim names the branch it was checked against.

Verification

• build_dist.py --check clean (both skill trees regenerated and committed together)
• prose_lint.py, repo_gate.py, host_gate.py all pass
• test_build_dist.py (19), test_prose_lint.py (244), test_repo_gate.py (70), test_host_gate.py (72), test_skills_install.py (29), host-setup/agent-safety/test_install.py (45), spec/validate.py all pass
• Signed-commit probe run before committing (sig=G, noreply identity on author and committer)

Closes #711. Closes #714. Supersedes #716.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR consolidates governance and skill updates to require that every task (including continuations) isolates into its own git worktree before the first file edit, and it packages the mechanics as a new repo-worktree skill to ensure the rule is surfaced at the right moment.

Changes:

• Adds an explicit “worktree before first edit” mandate to GOVERNANCE/host safety guidance (including continuation re-isolation).
• Introduces the new repo-worktree Skill (source + generated plugin), including base-branch guidance and worktree lifecycle mechanics.
• Tightens git-commit-conventions to forbid blanket staging and strengthens the pre-commit git status stop condition; propagates base-branch/negative-existence guidance to relevant skills.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
host-setup/agent-safety/README.md	Updates kit documentation to reflect the new worktree-before-edit mandate in the host-wide safety block.
host-setup/agent-safety/claude-md-safety.md	Adds the explicit host-wide “isolate into a worktree before first edit” rule so tools like EnterWorktree are “armed” by policy text.
GOVERNANCE.md	Adds the affirmative task-start worktree rule, tightens git staging summary language, and adds base-branch guidance + negative-existence-claim rule.
AGENTS.md	Updates the rules map to annotate that task isolation is surfaced by the new repo-worktree skill.
.claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md	Adds the generated repo-worktree skill content to the Claude plugin distribution.
.claude-plugin/fleet-skills/skills/operational-vs-release-workflow/SKILL.md	Adds “default branch is main but work starts on develop” guidance to the generated workflow skill.
.claude-plugin/fleet-skills/skills/git-commit-conventions/SKILL.md	Updates the generated git skill to forbid blanket staging and strengthen git status checks.
.claude-plugin/fleet-skills/skills/agent-conduct/SKILL.md	Updates the generated conduct skill to include the “does not exist” branch-naming requirement.
.claude-plugin/fleet-skills/.source-digest	Updates the plugin source digest to reflect regenerated skill content.
.claude-plugin/fleet-skills/.claude-plugin/plugin.json	Registers the new repo-worktree skill in the plugin manifest.
.agents/skills/repo-worktree/SKILL.md	Adds the source repo-worktree skill (mandate + mechanics) for fleet skill installation.
.agents/skills/operational-vs-release-workflow/SKILL.md	Adds base-branch/default-branch guidance to the source workflow skill.
.agents/skills/git-commit-conventions/SKILL.md	Tightens staging/commit hygiene rules in the source git skill.
.agents/skills/agent-conduct/SKILL.md	Adds the “does not exist” branch-checking rule to the source conduct skill.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (3)

GOVERNANCE.md:58

• The Branching Model note says the default-branch setting is main but work starts on develop "on both fleet workflow models", yet the last sentence narrows the guidance to only a release-model repo. This is internally inconsistent and could mislead readers working in an operational repo (which also starts on develop).

**GitHub's own "default branch" repository setting reads `main`, but `develop` is where work starts and where in-flight content lives**, so a worktree or clone that defaults to "the default branch" lands on `main` and can silently miss content already merged to `develop` but not yet promoted. Branch from `develop` for a `release`-model repo unless the task is explicitly about `main`-only content.

.agents/skills/repo-worktree/SKILL.md:7

• The skill description says to base work on develop "for a release-model repo", but later in this same skill it states that both workflow models start work on develop. Please make the description match the rule it documents to avoid confusion for operational repos.

  feature branch before its first file edit, based on the branch work starts on (develop for a
  release-model repo, never whichever branch a tool defaulted to). Also wraps the mechanics:

.claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md:7

• Same inconsistency as the source skill file: this generated copy says develop is the base only for a release-model repo, but the skill body states both models start on develop. Align the description so the packaged skill doesn’t give mixed guidance.

  feature branch before its first file edit, based on the branch work starts on (develop for a
  release-model repo, never whichever branch a tool defaulted to). Also wraps the mechanics:

[ptr727]

Answering the three suppressed round-2 findings, which are one inconsistency in three places: the GOVERNANCE.md Branching Model sentence and the repo-worktree skill description (source and generated copy) qualified the develop base as release-model-only while the skill body states both workflow models start work on develop.

Fixed in 8f1fac6: the GOVERNANCE sentence now reads "Branch from develop, on either workflow model, unless the task is explicitly about main-only content", and the skill description reads "develop on both fleet workflow models", matching the body. The generated copy is regenerated in the same commit.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

GOVERNANCE.md:45

• This paragraph is now a single very long line, which is inconsistent with the surrounding hard-wrapped prose and makes future diffs/edits harder. Please wrap it similarly to the rest of this file.

The fleet's mechanical git rules: default to staging rather than committing and stage by explicit path only, never a blanket add, commit means commit and push, every commit is signed and carries the committer's own verified GitHub `noreply` identity, never force push, a history rewrite re-identifies only the commits it touches that aren't yours, and destructive git commands run only on explicit instruction.

.agents/skills/repo-worktree/SKILL.md:72

• The skill mandates that continuations “re-isolate”, but the only concrete command sequence shown here creates a new branch from origin/develop. Consider adding a short example for attaching an existing task branch (local or origin/) to a new worktree so continuations don’t accidentally fork a fresh branch.

Note: the same change likely needs to be mirrored into the generated copy at .claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md to keep them in sync.

```sh
git -C ~/repos/<Repo> fetch origin develop
git -C ~/repos/<Repo> worktree add ~/repos/worktrees/<Repo>-<task-slug> -b <task-branch> origin/develop

</details>

[ptr727]

Answering the two suppressed round-3 findings:

GOVERNANCE.md:45 — "This paragraph is now a single very long line, which is inconsistent with the surrounding hard-wrapped prose... Please wrap it." Declined: the committed style rule is the opposite. The comment-and-doc-style skill states "One logical paragraph per line, no hard-wrap line-length limit", and round 1 of this review flagged this same paragraph for being hard-wrapped, which 2d00c34 fixed. The surrounding wrapped prose is the legacy inconsistency, out of scope here.

.agents/skills/repo-worktree/SKILL.md:72 — "the only concrete command sequence shown here creates a new branch... add a short example for attaching an existing task branch." Fixed in e9a9711: a continuation sequence now attaches the existing task branch (git worktree add <path> <task-branch> after fetching it), and the prose names git's refusal to attach a checked-out branch as the mandate working, with the clean-tree/stop rule for freeing it. The generated copy is regenerated in the same commit.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md:77

• The continuation snippet uses git fetch origin <task-branch> but then calls git worktree add ... <task-branch>, which expects a local branch ref. If the base clone doesn't already have a local <task-branch> (e.g., fresh clone / only remote-tracking exists), the worktree add step can fail.

git -C ~/repos/<Repo> fetch origin <task-branch>

.agents/skills/repo-worktree/SKILL.md:77

• The continuation snippet uses git fetch origin <task-branch> but then calls git worktree add ... <task-branch>, which expects a local branch ref. If the base clone doesn't already have a local <task-branch> (e.g., fresh clone / only remote-tracking exists), the worktree add step can fail.

git -C ~/repos/<Repo> fetch origin <task-branch>

[ptr727]

Answering the round-4 suppressed finding (raised identically against the source and generated copies of repo-worktree/SKILL.md):

"The continuation snippet uses git fetch origin <task-branch> but then calls git worktree add ... <task-branch>, which expects a local branch ref. If the base clone doesn't already have a local <task-branch>... the worktree add step can fail."

Declined as a defect: the failure does not reproduce. git worktree add applies the same DWIM as git checkout when the named branch exists in exactly one remote, creating the local tracking branch. Constructed repro on git 2.47.3:

git init a && git -C a commit --allow-empty -m base && git -C a branch task-x
git clone a b            # b has only remote-tracking origin/task-x
git -C b worktree add ../wt task-x
# Preparing worktree (new branch 'task-x')
# branch 'task-x' set up to track 'origin/task-x'.  -> exit 0

054b42a documents that guessing inline anyway, so the next reader does not have to re-derive why the snippet works on a fresh clone. The generated copy is regenerated in the same commit.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.agents/skills/repo-worktree/SKILL.md:83

• This text implies git worktree add … <task-branch> will “guess” and create a local branch tracking origin/<task-branch> when only the remote-tracking ref exists. In practice git worktree add commonly requires an existing local branch (or an explicit -b … origin/<task-branch>), so this guidance can fail on a fresh clone / remote-only branch. Update the continuation instructions to include an explicit remote-based form (and keep the existing local-branch form as a separate case).

When the base clone holds only the remote-tracking ref, the same command creates the local
branch tracking `origin/<task-branch>` through git's ordinary checkout guessing, so a fresh
clone needs no separate branch setup. Git refuses to attach a branch that is already checked

.agents/skills/repo-worktree/SKILL.md:85

• There’s an awkward hard line break splitting the sentence “and that refusal is the mandate working …” across two lines, which reads like a formatting glitch. Join it into one sentence/paragraph for readability.

clone needs no separate branch setup. Git refuses to attach a branch that is already checked
out somewhere else, and that refusal is
the mandate working, since the branch sitting checked out in a shared tree is the hazard the

[ptr727]

Answering the two suppressed round-5 findings:

.agents/skills/repo-worktree/SKILL.md:83 — "In practice git worktree add commonly requires an existing local branch (or an explicit -b … origin/<task-branch>), so this guidance can fail on a fresh clone / remote-only branch." Declined: this restates the round-4 finding already answered with a runnable reproduction (see the previous comment). git worktree add <path> <branch> applies the checkout DWIM when the branch exists in exactly one remote and creates the local tracking branch, verified on git 2.47.3 with a constructed two-repo case that exits 0 and prints "branch 'task-x' set up to track 'origin/task-x'". Fleet clones carry a single remote, so the exactly-one-remote condition holds.

.agents/skills/repo-worktree/SKILL.md:85 — "awkward hard line break splitting the sentence... reads like a formatting glitch." Fixed in 21aa9ac: the paragraph is rewrapped evenly, no mid-clause short line. The generated copy is regenerated in the same commit.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

GOVERNANCE.md:45

• This sentence reads ambiguously because the conjunction joins two parallel clauses without a separating comma ("default to staging rather than committing and stage..."). Adding a comma after "committing" makes the list of rules parse correctly.

The fleet's mechanical git rules: default to staging rather than committing and stage by explicit path only, never a blanket add, commit means commit and push, every commit is signed and carries the committer's own verified GitHub `noreply` identity, never force push, a history rewrite re-identifies only the commits it touches that aren't yours, and destructive git commands run only on explicit instruction.

[ptr727]

Answering the suppressed round-6 finding:

GOVERNANCE.md:45 — "the conjunction joins two parallel clauses without a separating comma ('default to staging rather than committing and stage...')" Fixed in 6b85350: the two staging rules are now separate list items, "default to staging rather than committing, stage by explicit path only and never with a blanket add, ...".

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.agents/skills/repo-worktree/SKILL.md:7

• The skill description says the worktree should be based on “develop on both fleet workflow models”, but the skill body (and GOVERNANCE.md) includes an explicit exception for tasks that are about main-only content. Consider updating the description to include that exception so the short summary doesn’t encourage always branching from develop.

  feature branch before its first file edit, based on the branch work starts on (develop on both
  fleet workflow models, never whichever branch a tool defaulted to). Also wraps the mechanics:

[ptr727]

Answering the suppressed round-7 finding:

.agents/skills/repo-worktree/SKILL.md:7 — "Consider updating the description to include that exception so the short summary doesn't encourage always branching from develop." Fixed in b271f36: the description now reads "develop on both fleet workflow models unless the task is explicitly about main-only content", matching the body and GOVERNANCE.md. The generated copy is regenerated in the same commit.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.agents/skills/repo-worktree/SKILL.md:72

• The worktree-creation example hardcodes develop, but the skill (and GOVERNANCE) says the base branch is the branch work starts on and can be main for main-only tasks. Using a <base-branch> placeholder here avoids contradicting the rule and reduces the chance of copy/pasting the wrong ref.

git -C ~/repos/<Repo> fetch origin develop
git -C ~/repos/<Repo> worktree add ~/repos/worktrees/<Repo>-<task-slug> -b <task-branch> origin/develop

.claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md:72

• Same issue as the source skill: this example hardcodes develop even though the rule is to base the worktree on the branch work starts on (sometimes main). Consider using a <base-branch> placeholder so the example stays consistent with the mandate.

git -C ~/repos/<Repo> fetch origin develop
git -C ~/repos/<Repo> worktree add ~/repos/worktrees/<Repo>-<task-slug> -b <task-branch> origin/develop

[ptr727]

Answering the suppressed round-8 finding (raised identically against the source and generated copies of repo-worktree/SKILL.md):

"The worktree-creation example hardcodes develop... Using a <base-branch> placeholder here avoids contradicting the rule and reduces the chance of copy/pasting the wrong ref."

Declined: the concrete develop is deliberate. The incident behind the base-branch rule (#714) was a worktree based on the wrong branch because a tool was left to pick, and a <base-branch> placeholder recreates that choice at copy-paste time, which is the failure mode the rule closes. develop is the correct base on both workflow models in every case except the explicitly-named main-only exception, which the surrounding prose states twice, so the example shows the overwhelming default verbatim and the exceptional reader adapts one ref knowingly rather than every reader choosing one.