Add an upstream Segment to the Repo Layout Convention - #733
Merged
Conversation
The layout block in the repo-worktree skill reasoned that no owner segment is needed because every repo on a fleet machine is under one owner. A host that also keeps third-party clones falsifies that, and the failure is a collision rather than an untidy name: a fork is named <upstream-owner>-<upstream-repo>, so a clone of home-assistant/core joined the same way is the fork home-assistant-core, while reduced to a bare core it names no project and collides with the next core cloned from anywhere else. Third-party clones now live at ~/repos/upstream/<owner>-<repo>, flat under one segment that states the relationship rather than the owner. The block also writes down the two naming rules the flat namespace above it depends on: a fork carries the upstream owner in its name at fork time, and a repository adopted as the owner's own work is detached from its parent and keeps a plain name. Closes #725.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repo-worktree skill’s layout convention to explicitly account for third-party (non-fork) upstream clones by introducing an upstream/ segment, preventing name collisions on machines that host both fleet repos/forks and external reference checkouts.
Changes:
- Extend the documented repo layout with
~/repos/upstream/<owner>-<repo>for upstream (non-fork) clones. - Add rationale explaining why forks remain in the flat top-level namespace while upstream clones are placed under
upstream/. - Refresh the generated fleet-skills source digest to reflect the updated skill content.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| .claude-plugin/fleet-skills/skills/repo-worktree/SKILL.md | Document upstream clone placement under ~/repos/upstream/ and explain the naming rationale and contribution workflow implication. |
| .agents/skills/repo-worktree/SKILL.md | Mirror the same layout + rationale updates in the agents skill source. |
| .claude-plugin/fleet-skills/.source-digest | Update digest to reflect regenerated plugin content. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
A hyphen in either half means foo-bar/baz and foo/bar-baz produce one directory name. The join is kept because it is the fork convention's own, so the ambiguity is inherited from the flat namespace rather than introduced by the upstream segment, and the section now says so and says what a second clone does about it.
The section illustrated the fork and clone naming rules with repositories observed on the maintainer's machine. A constructed case demonstrates the same collision and any reader can follow it, so acme/core, initech/widget, and acme-labs/core replace them.
ptr727
added a commit
that referenced
this pull request
Aug 15, 2026
… the Upstream Repo-Layout Segment (#734) Closes #719 Closes #720 Closes #721 Closes #722 Promotes six merged `develop` PRs to `main`: - #732 -- Reconcile the PlexCleaner registry entry and audit report after the 2026-08-15 resync (closes #719). - #731 -- Exempt hub-hosted paths from the prose gate's `dead-path` rule (closes #721). - #730 -- Fix the hub slug and the dead anchor in the canonical `copilot-instructions.md` (closes #720, #722). - #723 -- Refresh the PhotoCleaner audit report after the 0e84805 resync. - #733 -- Add an `upstream/` segment to the repo layout convention (addresses #725, not closed -- the fork-naming variant differs from the issue's proposal). - #724 -- Add the HomeAutomation-Config audit report and reconcile its registry entry. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Addresses #725. The layout block in the
repo-worktreeskill carried a clause from #699 reasoning that no owner segment is needed "since every repo here is under one owner". A machine that also keeps third-party clones falsifies that, and what it produces is a collision rather than an untidy name.The collision is caused by the fork naming rule, which #699 mentioned only in passing and nothing wrote down: a fork is named
<upstream-owner>-<upstream-repo>at fork time, soptr727/home-assistant-corealready occupieshome-assistant-core. A clone ofhome-assistant/corejoined the same way lands on it, and reduced to a barecoreit names no project and collides with the nextcorecloned from any other owner.The layout
upstream/is flat rather than nested by owner, so onelsreads every reference checkout, the same reasoning that already keepsworktrees/flat. Naming a clone by the same<owner>-<repo>join a fork uses means forking it later moves the directory up one level under the name it already has, and a worktree off it needs no new rule:~/repos/worktrees/<owner>-<repo>-<task-slug>.The two naming rules the flat namespace depends on
Both were practice, neither was written down, and the collision is only explicable with them stated:
esphome-esphomeforesphome/esphome. 15 of the 17 existing forks already do this.aiopurpleairrather thanbachya-aiopurpleair, since it tracks nothing upstream. The fleet already has both of those repos side by side, which is what makes this the existing rule rather than a new one.The section also notes that contributing from an
upstream/clone is never a push out of it, routing to theupstream-contribution-workflowskill, which fixes the layout back to the flat namespace once a fork exists.Testing
python3 scripts/build_dist.pyregenerated the plugin tree, and--checkreports it current.python3 scripts/prose_lint.pyclean over the whole tree (195 files).python3 scripts/repo_gate.pyclean (eol, eol-coverage, sha-pin).cspellgate covers README and HISTORY only, so this file is out of its scope and no dictionary entry is needed.Follow-up, not in this PR
Two existing repos are off the convention this PR writes down, and renaming a repository is outward-facing, so the list is the maintainer's to run:
ptr727-jellyfin->jellyfin-jellyfin(parentjellyfin/jellyfin). The live upstream makes this a real future collision.esphome-esphome-docs->esphome-esphome.io(parentesphome/esphome.io). A hand-name for a dotted upstream, where the siblinghome-assistant-home-assistant.iokeeps its dot.Postfix-Relay(parentjuanluisbaptiste/docker-postfix) deliberately keeps its name. It is an adopted product rather than a tracked fork, so under the rule above it is a candidate to detach on GitHub, not to rename.