clud-extern-repos · diff
git:20260807.dd89e45 to git:20260823.45b0702
16 added, 4 removed. Audit A to A.
---
name: clud-extern-repos
- description: Coordinate dependent cross-repo changes under a repo-local .extern-repos/ checkout convention.
+ description: Coordinate dependent cross-repo changes using a sister checkout directory beside the repo.
triggers:
- When a task needs a dependent change in another repository
- - When the user asks to use .extern-repos for cross-repo work
+ - When the user asks to use extern repos or sister checkouts for cross-repo work
---
<!-- managed-by: clud -->
# clud-extern-repos
Use this workflow when the current repo needs coordinated work in a dependent repository.
## Code Change Rule
If any parent or dependent repository change is a bug fix or feature implementation, use RED -> GREEN in that repository: write or identify the focused failing test/repro first, run it to fail, implement the scoped change, rerun it to pass, then run the broader repo checks before opening linked PRs.
## Convention
- Place each dependent checkout at `<current-repo>/.extern-repos/<repo-name>/`. Only immediate children of `.extern-repos/` are tracked by clud GC.
+ Place each dependent checkout **beside** the repo, not inside it:
- Before cloning, verify `.extern-repos/` is ignored by the current repo. If it is not ignored, ask before adding the ignore entry and refuse to create an unignored clone.
+ ```
+ ~/dev/myrepo <- the repo you are working in
+ ~/dev/myrepo-extern/ <- dependent checkouts go here
+ running-process/
+ ```
+
+ So from `~/dev/myrepo`, clone to `../myrepo-extern/<repo-name>`. Only immediate children of that directory are tracked by clud GC.
+
+ The directory is derived from the repo's own name, and for a worktree it derives from the **main** repo — `~/dev/myrepo-wt-123` also uses `~/dev/myrepo-extern`, so a dependency is cloned once rather than once per worktree.
+
+ You do not need to add an ignore entry for it, and you should not: it is outside the repo, so nothing that walks the repo can reach it. That is the point. A checkout inside the repo has to be excluded by every linter, formatter, test collector, and build script pointed at the root, and a wrong exclusion fails silently — `ci/banned_imports.py` in clud carried one for its whole life without anybody noticing.
+
+ Checkouts still under the older `<repo>/.extern-repos/` location keep working and are still tracked, but put new ones beside the repo.
Create feature branches in the dependent repo using the `feat/<short-name>` convention.
## Coordination
Keep each repo's work scoped to that repo. Do not edit the parent repo from inside the dependent checkout, and do not edit the dependent checkout from the parent repo.
When opening PRs, link both directions:
- Parent PR body: `Depends on <owner>/<repo>#<number>`
- Dependent PR body: `Coordinated with <owner>/<parent-repo>#<number>`
If the dependent PR must land first, make that ordering explicit in the parent PR body.
## Cleanup
The daemon auto-removes `.extern-repos/<name>/` once the directory has been inactive (no descendant `mtime` change) for at least 24 hours and no live clud session is rooted inside it. Anything tracked under `.extern-repos/` is clud-managed by convention, so don't park work there that you want kept indefinitely — copy it elsewhere or commit + push it first.
Override the inactivity window via `CLUD_GC_EXTERN_REPO_MAX_AGE_SECS` (default `86400`).