Family workstation layout: a plain <Family>/ folder holding the holder and the members' working clones — family.py init lands there, the scaffold learns --family, the holder gains a siblings utility that warns and never moves #76

Lane: xfactory-2 (xFactory-2)

Governing record for a workflow change: the family's WORKSTATION LAYOUT — a plain parent folder named after the family, holding the holder clone and the members' working clones as siblings — becomes something the tooling places and checks, never something it moves. Design only at this stage; nothing here is claimed for authoring yet.

Where this comes from

The ruling that created families (Brett Heap, 2026-09-04): "InkRouter is only something that can download all the others easily? like a holder FOLDER and some utilities for the family of services." The implementation made the holder a REPOSITORY that pins member assembly roots as submodules under members/. The plain folder in the ruling's words was never written down — and it exists anyway, arranged by hand:

~/projects/InkRouter/                 a plain folder, not a git repository
  InkRouter/                          the holder (InkRouter/InkRouter): family.yaml, members/IRRS, members/IRSS pinned + detached
  IRRS/                               working clone of InkRouter/IRRS, on main — where the lanes work
  IRSS/                               working clone of InkRouter/IRSS, on main
  IRRS-worktrees/…                    a linked worktree of IRRS
  session-handoff-2026-09-08-lane-*.md   lane handoffs (lane-collision-protocol Rule 4's estate folder)

Two copies of each member on disk is correct and intended: the holder's members/<Project> is a pinned, detached checkout for make bootstrap and make validate; development happens in the sibling clone on its tracking branch, and the family is bumped to follow. Nothing documents this, and the first question a reader asks — "is InkRouter/InkRouter the family, and what is the parent folder?" — was asked today (2026-09-09).

What the tooling does today

• scripts/family.py init materializes the holder in a TEMP directory unless --work-dir is passed (work_root / family), so the person arranges the folder afterwards by hand.
• setup.sh / setup-project.py land a new project beside where the person stands (--into = invocation directory, setup.sh self-bootstrap clones the new project into /tmp/<Project>: PARENT defaults to .. of the TEMPORARY checkout #39). No family awareness: grep -i family setup-project.py finds nothing.
• The holder template (templates/family-root/) has bootstrap.py and validate-family.py. There is no utility that produces the working clones beside the holder — the "download all the others easily" of the ruling is answered only by submodules inside the holder.

The proposal

Place at clone time; check afterwards; never move.

1. family.py init gets a real landing spot. Default: create <into>/<Family>/ where the person stands and clone the holder INSIDE it, at <Family>/<Family> — the same "lands where you were standing" rule setup.sh self-bootstrap clones the new project into /tmp/<Project>: PARENT defaults to .. of the TEMPORARY checkout #39 gave projects. --work-dir stays as the override. Refuse (no --force) if <Family>/<Family> exists and is non-empty, as today.
2. The scaffold learns --family <Name>. openRepoShape IRTS --org InkRouter --family InkRouter lands the new project at <Family>/IRTS, creating <Family>/ if absent, and the "next commands" block ends with the family.py add line. Detection, advisory only: when the invocation directory is <X>/ and <X>/<X>/family.yaml exists with name: <X>, the plan says "you are standing in the family folder; the project lands beside the holder" — no flag needed, nothing else changes.
3. The holder gains the missing family utility. A Makefile target in templates/family-root/ (name to decide — make siblings? make workstation?) that, for each row in family.yaml, clones the member as a standalone working copy at ../<Project> on its tracking branch, idempotently (an existing clone is fetched, never reset), and prints the layout. Creates nothing on GitHub; needs the same read credential make bootstrap needs. When the holder's parent folder is NOT named <Family>, it WARNS and prints the mv for the human to run — the doctor pattern, not a mover. It never moves anything itself.
4. The layout is documented in the family-root README (and the openRepoShape README's Families section): the plain folder, the two copies and which one you work in, the doubled <Family>/<Family> name and why it is kept, and where handoff files live.

Deliberately NOT proposed

A setup.sh in the holder that checks whether it is under a same-named folder and, if not, creates that folder and MOVES the checkout there. It relocates the directory out from under the shell, editors and every agent lane standing in it; it breaks linked worktrees, whose .git files carry absolute paths (~/.agents/AGENTS.md calls stale worktree pointers the canonical symptom); and it is the one thing this standard refuses everywhere else — an act done by surprise, where every refusal today names what to run instead. The warning-plus-mv in (3) gives the same outcome with the human's hand on it.

Open decisions

• The target's name in (3), and whether it also belongs in scripts/family.py (run from a checkout of the standard) so it works before the holder is cloned.
• Whether --family in (2) should also be honoured by native-Windows setup-project.py (it should; same flag, same landing rule).
• Keep the doubled <Family>/<Family> clone name (recommended: the repository keeps its name and family.yaml disambiguates) or clone the holder under another local name.

Reach

Changes land in openRepoShape: scripts/family.py, setup-project.py (+ setup.sh/openRepoShape pass-through), templates/family-root/{Makefile,README.md,scripts/}, README, AGENTS.md, tests. Existing holders — InkRouter/InkRouter today — take the template additions through update-shape.py check / apply --add <path>, per file, on the human's word. Nothing changes for a project in no family.

🤖 Generated with Claude Code