▋
docs/adr/0008-herdr-fork-as-submodule.md

ADR 0008: clankie-herdr fork as a submodule (supersedes 0003)

  • Status: Accepted
  • Date: 2026-07-07

Context

ADR-0003 vendored the Clankie-owned Herdr fork inside the monorepo at herdr/. In practice Volpestyle/clankie-herdr is a patch-stack fork of ogulcancelik/herdr: master tracks upstream, the specializations live as a stack of patch/10…90/* branches (the pane/session-attach API and friends), a fork branch is the assembled result, and a .codex/skills/herdr-fork-rebase skill (rebase-stack.sh) rebases the stack onto new upstream.

Vendoring a copy into the monorepo produced two sources of truth that drifted: the monorepo's herdr/ ran ahead of the fork repo (newer pane API work, plus a monorepo-only clankie-herdr binary and the rebase skill). The rename (ADR-0006) made clankie-herdr a clearly-branded GitHub fork, which removes the original reason to vendor.

Decision

Convert herdr/ from a vendored copy into a git submodule of Volpestyle/clankie-herdr — one source of truth. Before pinning, reconcile the monorepo's drifted-ahead herdr state back into the fork's patch stack (via the rebase-stack workflow) so nothing is lost, and move the monorepo-only bundled clankie-herdr binary + rebase skill into the fork so the submodule is self-contained. This reverses ADR-0003's vendoring while keeping its intent (a clanky-specialized, upstream-rebaseable fork). This is the second submodule in the source-first consumption model alongside @volpestyle/clankie-contract (ADR-0002; the contract has since also published to npm, but in-repo consumers stay on raw source).

Consequences

  • Single source of truth for the fork; drift eliminated. Upstream rebasing is owned by the patch-stack workflow (rebase-stack.sh) in clankie-herdr.
  • Fresh monorepo clones and CI must git submodule update --init before building the bundled stage.
  • The submodule pins a specific fork commit, re-pinned after each stack rebase.
  • Reconciliation + the submodule swap are landed via a worker on its own PR (delicate patch-stack work); the worker preserves the monorepo's newer herdr source and blocks rather than guessing on stack structure.