▋
docs/adr/0002-monorepo-native-contract.md

ADR 0002: Monorepo-Native Wire Contract

  • Status: Accepted
  • Date: 2026-07-05
  • Amended: 2026-07-08 — the contract now also publishes to the public npm registry as @volpestyle/clankie-contract (dist builds; see clankie-contract/README.md). In-repo consumers still take raw workspace:* source as decided here.

Context

The monorepo migration makes the Clankie checkout the canonical source for the agent, private iOS app, ClankVox, and the shared TypeScript wire contract. The iOS app consumed @volpestyle/clankie-contract through a pinned public git dependency on the old Volpestyle/clankie-contract repo, and the agent carried a duplicate contract package under clankie-agent/packages/.

That kept release builds working, but it preserved a second source of truth and blocked archiving the old contract repo.

Decision

clankie-contract/ at the top level of the monorepo is the only contract source. Both package-local pnpm workspaces include it as an external workspace package:

packages:
  - ../clankie-contract

The agent and iOS app both depend on it as:

"@volpestyle/clankie-contract": "workspace:*"

The agent-local duplicate package is removed. The public Volpestyle/clankie-contract git dependency is no longer part of the mobile release path.

Since the iOS app moved to its own private repo (Volpestyle/clankies, ADR 0004), it reaches this same source by carrying the public monorepo as a git submodule and globbing clankie-contract from inside it — still raw source, still workspace:*. The agent keeps globbing ../clankie-contract directly within this monorepo.

Consequences

  • Wire-shape changes land atomically with the agent and iOS code that consumes them.
  • EAS runs from the app root in the Volpestyle/clankies repo, with eas.json in the app root. The monorepo submodule makes clankie-contract/ available to pnpm during cloud installs; because the submodule is public, EAS needs no extra credentials to fetch it.
  • The old public contract repo can be archived once a fresh TestFlight build verifies the workspace dependency in EAS.
  • Package-local lockfiles remain in place; this does not consolidate every JavaScript package into one root workspace yet.