ADR 0001: Clankie Monorepo

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

Context

Clankie is one product with several tightly coupled surfaces:

• clankie-agent owns the canonical runtime behavior and API.
• clankvox is the native realtime media plane used by the agent.
• clankie-contract defines the TypeScript wire vocabulary shared by the agent and its clients.
• herdr/ contains clankie-herdr, the Clankie-owned Herdr fork that provides the persistent terminal stage and pane/session runtime for local orchestration.

Separate repositories make cross-surface changes harder to land atomically and force contract bumps or documentation updates to move independently from the code that needs them.

Decision

Clankie uses one GitHub monorepo with package directories at the root:

clankie-agent/
clankvox/
clankie-contract/
herdr/

Each package keeps its package-local toolchain, lockfile, and instructions. The root repository provides the cross-package map and GitHub Actions orchestration. The private iOS app lives in its own repository (Volpestyle/clankies) and is not part of this monorepo; see docs/adr/0004-public-real-history-private-ios.md.

Consequences

• Cross-surface changes can land in one commit or pull request.
• Package boundaries stay explicit; developers still run package commands from package roots.
• GitHub Actions live at the repository root and call each public package from its own working directory.
• The first migration preserves the existing package-local pnpm workspaces instead of consolidating all JavaScript packages into one root lockfile.