docs(worktree-isolation): multi-repo feature-group pattern + adoption reference#124
Merged
Merged
Conversation
… reference Extend the worktree-isolation skill from single-repo isolation to binding parallel worktrees of one feature across separate repos (backend / worker / FE). - Multi-Repo Feature Groups: explicit registry over branch-name heuristics, membership lifecycle (add/remove), running the set (port slots, OAuth redirect pinning, config-not-carried-by-worktree, one grouped session). - New references/multi-repo-feature-groups.md: tool-agnostic adoption recipe with the registry schema, port-slot formula, run-script generation, the OAuth-claim mechanism, and reusable bash snippets so anyone can port it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 adds
Extends the
worktree-isolationskill from single-repo isolation to a fullmulti-repo feature-group pattern, and ships a standalone adoption reference so
anyone can port the logic into their own stack.
The problem it documents
A feature often spans several repos - a backend, a worker/AI service, a frontend -
each its own git repo with its own branch. Worktrees isolate one repo; nothing
binds worktrees across repos, so creating, running, tracking, and tearing down
the set is manual and easy to get wrong.
The lifecycle the docs cover
Key decision: explicit registry, not branch-name matching
The load-bearing choice a reviewer cannot reconstruct from the diff:
feat/x-integrationvsfeat/x-attribution-ui)Real feature branches drift per repo, so any name-based inference is unreliable.
A
group / role / worktree-path / slotregistry is the single source of truth.What changed
SKILL.md: new "Multi-Repo Feature Groups" section - registry overheuristics, membership lifecycle (add/remove), and running the set (port
slots, OAuth redirect pinning, config-not-carried-by-worktree, one grouped
session). Plus matching Quick-Reference and Red-Flag rows.
references/multi-repo-feature-groups.md(new): tool-agnostic recipe - theregistry schema, the
port = base + 10*slotformula, run-script generation(env-prefix vs
--port), the OAuth-claim mechanism, a config block to fillin, and reusable bash snippets (no-subprocess branch read, OAuth port-swap).
Verifying
Docs-only; nothing in the plugin runtime changed. The pattern is backed by a
working reference implementation (shell tooling) that was exercised end-to-end -
create, seed, run, status, OAuth-claim, teardown - against throwaway repos.