Skip to content

docs(worktree-isolation): multi-repo feature-group pattern + adoption reference#124

Merged
KailasMahavarkar merged 1 commit into
mainfrom
docs/worktree-feature-groups
Jul 7, 2026
Merged

docs(worktree-isolation): multi-repo feature-group pattern + adoption reference#124
KailasMahavarkar merged 1 commit into
mainfrom
docs/worktree-feature-groups

Conversation

@KailasMahavarkar

Copy link
Copy Markdown
Collaborator

What this adds

Extends the worktree-isolation skill from single-repo isolation to a full
multi-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

 go  ──►  new/add  ──►  env  ──►  up  ──►  st  ──►  claim-oauth  ──►  down  ──►  rm
 pick     create        seed      run      watch    OAuth :8080       stop      unbind
 set      + branch      .env      stack    drift    (singleton)                 (keep code)

Key decision: explicit registry, not branch-name matching

The load-bearing choice a reviewer cannot reconstruct from the diff:

approach binds verdict
exact branch match only byte-identical branch names misses drift (feat/x-integration vs feat/x-attribution-ui)
branch-token heuristic fuzzy prefix/suffix strip false positives, fragile
explicit registry exactly what you declare correct - chosen

Real feature branches drift per repo, so any name-based inference is unreliable.
A group / role / worktree-path / slot registry is the single source of truth.

What changed

  • SKILL.md: new "Multi-Repo Feature Groups" section - registry over
    heuristics, 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 - the
    registry schema, the port = base + 10*slot formula, run-script generation
    (env-prefix vs --port), the OAuth-claim mechanism, a config block to fill
    in, 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.

… 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>
@KailasMahavarkar KailasMahavarkar merged commit c5bd83b into main Jul 7, 2026
4 checks passed
@KailasMahavarkar KailasMahavarkar deleted the docs/worktree-feature-groups branch July 7, 2026 13:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant