Skip to content

ADR: Git Worktrees & Agent Operations

Status: DRAFT Date: 2026-01-23 Context: Context switching between "Platform", "Marketing", and "Architecture" incurs high friction (branch switching, rebuilding). We also need to define how AI Agents interact with the Monorepo without hallucinating cross-dependencies.

1. The Decision

We will adopt Git Worktrees to maintain persistent, isolated working environments ("Context Nodes") on the local machine. We will pair this with a Hybrid Agent Strategy to enforce strict boundaries where possible.

2. Operational Model

A. The "Context Nodes"

We will create sibling directories to the main repo. These serve as "Permanent Windows" into specific parts of the system.

Worktree Path Focus Area Checkout Strategy (Sparse)
../sd-platform The App apps/platform/, packages/, config/
../sd-marketing The Site apps/marketing/ (Island Mode)
../sd-library The Docs documentation/, development/

B. The "Hybrid" Agent Strategy

We define the AI Agent's scope based on the Workspace it is initialized in.

  1. Marketing Agent (../sd-marketing):

    • Type: ISOLATED.
    • Scope: Can ONLY see apps/marketing.
    • Safety: Guaranteed not to import packages/ (which are physically missing).
    • Use Case: CSS tweaks, Content updates, Landing page features.

  2. Platform/Arch Agent (../sd-platform or ../singular-dream):

    • Type: NETWORKED.
    • Scope: Sees the Monorepo root.
    • Safety: Relies on linting/discipline.
    • Use Case: Core logic, Shared libraries, API development.

3. Change Control & Procedures

The "Branch Lock" Constraint

Git does not allow the same branch to be checked out in two worktrees simultaneously.

New Operating Procedure: * Main Repo: Sits on main (Read-only reference). * Platform Node: Sits on dev-platform or feature branches. * Marketing Node: Sits on dev-marketing or feature branches.

The "Shared Code" Protocol

When the Platform Agent changes a shared package (e.g., @sd/foundation-auth): 1. Platform Node: Commits the change to feature/auth-update. 2. Marketing Node: MUST git pull or git checkout feature/auth-update to see that change. * Note: Since Marketing is "Isolated" in our strategy, it shouldn't care about shared code, reducing this friction significantly. This validates the "Hybrid" model.

4. CI/CD Implications

  • No Change: CI/CD pipelines always checkout a fresh clone.
  • Verification: The "Island" nature of Marketing must be enforced by CI (e.g., specific turbo scopes) to ensure we don't accidentally rely on implicit local state.