Add agent instructions for managing worktrees

Author: markmur

.gitignore

@@ -12,6 +12,9 @@
 .dev.env
 .mint
 
+# Worktrees
+**/worktrees/
+
 # Node / pnpm
 node_modules/
 .pnpm-store/

AGENTS.md

@@ -39,6 +39,52 @@ For cross-platform changes, use the repo-wide aggregates: `dev lint`,
 `dev <platform> format` for formatting; `fix` remains an alias for existing
 workflows.
 
+## Worktrees
+
+Use git worktrees to isolate feature work. **Auto-create a worktree** when
+starting a self-contained task that benefits from isolation (a new feature or a
+standalone fix) — you don't need to ask first.
+
+- **Location:** create worktrees under a `worktrees/` directory at the repo
+  root. `**/worktrees/` is gitignored, so worktree checkouts never appear as
+  untracked changes.
+- **Branch naming:** name branches `<area>/<topic>`, where `<area>` is the
+  platform or subsystem and `<topic>` is a short kebab-case description.
+  Examples: `web/css-minify`, `swift/deeplink-cancel`,
+  `protocol/full-envelope`, `android/maven-local-fix`, `ci/draft-pr-checks`.
+- **Creating:** mirror the branch in the directory path, e.g.
+  ```bash
+  git worktree add worktrees/web/css-minify -b web/css-minify
+  ```
+
+### Before running `dev up` in a new worktree
+
+A fresh worktree is a clean checkout and does **not** include the gitignored
+root `.env` that sample app setup reads from. From inside the new worktree, run:
+
+```bash
+dev copy-env   # copies the root .env (and other root-level config) from the main checkout
+dev up         # regenerates all nested sample config (Android/Swift/RN) from it
+```
+
+`dev copy-env` copies only the root-level source-of-truth files; `dev up`'s
+`setup_storefront_env` step regenerates the nested sample configuration
+(Android `.env`, Swift `Storefront.xcconfig`, RN sample `.env`) from the root
+`.env`, so those do not need to be copied by hand. Treat all of these as
+sensitive (see **Sensitive configuration**) — never print or commit their
+contents. Remember the `shadowenv exec --dir <worktree_path> --` prefix when
+running these outside an interactive shell.
+
+### Cleanup
+
+When the branch has merged or the work is abandoned, remove the worktree and
+delete the branch:
+
+```bash
+git worktree remove worktrees/<area>/<topic>   # add --force if it has throwaway changes
+git branch -d <area>/<topic>
+```
+
 ## Swift Xcode builds
 
 Prefer the `dev swift ...` commands for Swift package and sample builds. When

dev.yml

@@ -64,6 +64,10 @@ commands:
         *) echo "Usage: dev codegen <kotlin|swift|typescript>"; exit 1 ;;
       esac
 
+  copy-env:
+    desc: Copy the root .env into the current worktree so `dev up` can regenerate sample config
+    run: ./scripts/copy_worktree_env
+
   format:
     desc: Auto-format and apply safe lint autocorrections across supported workspaces
     aliases: [fix]

scripts/copy_worktree_env

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Copies the repo-root .env (and other root-level machine-local config, if
+# present) from the main checkout into the current git worktree, so that a
+# subsequent `dev up` can regenerate all nested sample app configuration from it.
+#
+# This command prints file paths and status only; it never prints configured
+# values.
+
+CURRENT_ROOT="$(git rev-parse --show-toplevel)"
+COMMON_GIT_DIR="$(git rev-parse --path-format=absolute --git-common-dir)"
+MAIN_ROOT="$(dirname "${COMMON_GIT_DIR}")"
+
+if [[ "${CURRENT_ROOT}" == "${MAIN_ROOT}" ]]; then
+  echo "Already in the main checkout (${CURRENT_ROOT}); nothing to copy."
+  exit 0
+fi
+
+# Root-level, gitignored source-of-truth files. Nested sample config
+# (Android/Swift/RN) is intentionally omitted: `dev up` regenerates it from the
+# root .env via scripts/setup_storefront_env.
+ROOT_FILES=(
+  ".env"
+  ".dev.env"
+  "local.properties"
+)
+
+copied_any="false"
+
+for rel in "${ROOT_FILES[@]}"; do
+  src="${MAIN_ROOT}/${rel}"
+  dest="${CURRENT_ROOT}/${rel}"
+
+  if [[ ! -e "${src}" ]]; then
+    continue
+  fi
+
+  if [[ -e "${dest}" ]]; then
+    echo "skip (exists): ${rel}"
+    continue
+  fi
+
+  cp "${src}" "${dest}"
+  echo "copied: ${rel}"
+  copied_any="true"
+done
+
+if [[ "${copied_any}" != "true" ]]; then
+  echo "No new root env files to copy."
+fi
+
+echo "Next: run \`dev up\` in this worktree to regenerate sample app config."