vinta-ai-workflows 0.7.0-alpha8 → 0.7.0

package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/README.md

@@ -0,0 +1,85 @@
+# Generating the project's worktree command
+
+How [vinta-bootstrap-ai-tools](../../SKILL.md) writes a `prepare.sh` / `teardown.sh` pair into a target project. Once written, the pair is the project's `commands.worktree_prepare` / `commands.worktree_teardown`, and `implement-plan` runs it instead of the `prepare-worktree` skill. It runs only when the user answered **`Yes — generate a provisioning script for this project`** to the bootstrap's `prepare-worktree` question.
+
+The point is that provisioning becomes deterministic. The decisions the `prepare-worktree` skill makes on every run (what to copy, what to fork, how to isolate compose) are made **once**, here, with the user, and frozen into a script the team owns, reviews and edits.
+
+## What ships
+
+| Template | Becomes | Contents |
+|---|---|---|
+| [lib-template.sh](lib-template.sh) | `<dir>/lib.sh` | Resolves the worktree from the `VINTA_WORKTREE_*` environment (or a name given on the command line), plus helpers: `run` (honors `--dry-run`), `clone_dir`, `copy_file`, `set_env`, `forked_db_name`, `require_local_url`, `require_forked_name`, and YAML quoting. |
+| [prepare-template.sh](prepare-template.sh) | `<dir>/prepare.sh` | Sanity checks, `git worktree add`, the **PROJECT STEPS** regions, generic compose isolation, the summary YAML, and the report. On failure it removes the half-made worktree. |
+| [teardown-template.sh](teardown-template.sh) | `<dir>/teardown.sh` | Refuses a dirty worktree without `--force`, runs the **PROJECT STEPS** regions in reverse, stops compose (never `down -v`), removes the worktree, its branch when that branch holds no commits of its own, and the summary. |
+| [gen-compose-worktree-override.sh](../../../vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-compose-worktree-override.sh) | `<dir>/gen-compose-worktree-override.sh` | Copied **only when the project uses docker compose**. `prepare.sh` calls it to fork leaky volumes and strip fixed host ports. |
+
+Everything outside the PROJECT STEPS regions is contract plumbing. It is tested in this repo (`tests/worktree-command.test.mjs`), so leave it alone. The regions are where the project lives.
+
+## Steps
+
+### 1. Location
+
+The directory was chosen in the bootstrap interview (the `prepare-worktree` generate follow-up) and is already in `.vinta-ai-workflows.yaml` as the parent of `commands.worktree_prepare`. When this step runs standalone and that key is unset, ask now (header `Script dir`): `scripts/worktree (Recommended)`, `bin/worktree`, plus any existing scripts directory the inventory found. Free text covers other paths.
+
+**Read before write.** If `prepare.sh`, `teardown.sh` or `lib.sh` already exists there, show the first lines of each and ask (header `Overwrite?`): `Pick another directory (Recommended)`, `Overwrite them`, `Stop — keep my scripts and use them as the command`. The last option records the existing files as `commands.worktree_prepare` / `commands.worktree_teardown` and skips generation.
+
+### 2. Render
+
+Copy the three templates (and the compose generator, when compose is in use) and substitute:
+
+| Placeholder | Value |
+|---|---|
+| `{{WORKTREE_ROOT}}` | `skills.prepare-worktree.worktree_root` (`.claude/worktrees` or `../<repo>-wt-`) |
+| `{{DEFAULT_BRANCH}}` | `project.default_branch` |
+| `{{SUMMARY_DIR}}` | `skills.prepare-worktree.summary_dir` (default `.vinta-ai-workflows/worktrees`) |
+| `{{PROJECT_NAME}}` | `project.name` |
+| `{{SCRIPT_DIR}}` | the chosen directory, repo-relative |
+
+Then `chmod +x` all of them. No `{{…}}` may survive in the written files.
+
+### 3. Fill the PROJECT STEPS regions
+
+Each region in `prepare.sh` sits between `# >>> <region>` and `# <<< <region>`, with commented examples. Replace the examples with this project's real commands, and set the state variables at the top of `prepare.sh` that the summary reads. Then write the **matching** inverse region in `teardown.sh`. A prepare step whose teardown is missing leaks state on every lane recycle.
+
+The decisions are the same ones the `prepare-worktree` skill makes. Read [its body](../../../vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) for the reasoning; the short version for each region:
+
+| Region | Decide from | Rules that stay non-negotiable |
+|---|---|---|
+| `deps` | inventory package managers + lockfiles | Every dependency dir is the worktree's own: `clone_dir` it, or reinstall. **Never symlink.** Virtualenvs and yarn PnP always reinstall, because they store absolute paths into main. In a workspace, clone every member's `node_modules`, not only the root's. Set `DEPS_STRATEGY` / `DEPS_PATHS`. |
+| `env` | inventory env model (`.env*`, `.envrc`) | `copy_file`, never symlink, because later regions and compose isolation append to it. Set `ENV_FILES`. Never print an env file's contents. |
+| `dev_db` | inventory DB engine + how it is delivered | Fork with `forked_db_name`, and call `require_local_url` first, every time. A compose-delivered DB is forked by compose isolation (its volume), so the region only points the env at it. Set `DEV_DB_*`, including `DEV_DB_RESET`: a lane with no reset command cannot be reused across a migration. Add compose DB service names to `LOCAL_DB_HOSTS` in `lib.sh`. |
+| `test_db` | inventory test runner | Give the runner its own DB name through the env channel it already reads. Never edit tracked test config. Set `TEST_DB_*` and `TEST_DB_RESET`. |
+| `compose` | a compose file in the repo | `USES_COMPOSE=1`. List in `SHARED_VOLUMES` only read-only caches the user confirms, **never** a data volume. Step 4 of `prepare.sh` does the rest generically. |
+| `other` | Redis / S3 / queues / search / cron / tunnels in the env model | Per-worktree Redis index or key prefix, `S3_PREFIX=wt-$NAME/`, queue and index suffixes, cron off. Run migrations against the forked DB last. |
+
+Ask the user only about what the inventory cannot settle, through `AskUserQuestion` with the candidates found: which DBs to fork vs stub, which compose volumes are safe to share, whether cron must stay on. Don't ask about anything the table above already decides.
+
+Teardown regions drop only what `prepare.sh` created: call `require_forked_name` before every `dropdb` / `DROP DATABASE`, and make every step tolerate state that is already gone.
+
+### 4. Verify
+
+1. `bash -n` on all three files. Also run `shellcheck` when it is installed.
+2. Dry run, and show the user the output:
+
+   ```bash
+   <dir>/prepare.sh vinta-smoke --dry-run
+   ```
+
+3. Ask (header `Smoke test`): `Dry run is enough (Recommended)`, `Run a real smoke test now`, `Skip`. The real smoke test creates a worktree named `vinta-smoke-<yyyymmdd>`, really forking the local databases the script forks. It then runs the project's lint command inside the worktree and tears it down. When it runs:
+   - `prepare.sh` exits 0, and the three conductor checks from the `commands.worktree_prepare` contract hold: the branch, the registered worktree, and main's `git status` unchanged.
+   - The summary YAML parses.
+   - `teardown.sh` exits 0, and `git worktree list` no longer shows it.
+
+   On failure, show the failing step's output, run `teardown.sh` with the same name, and ask (header `Fix`): `Let me fix the region and retry (Recommended)`, `Keep the scripts as they are — I'll fix them later`, `Drop the scripts — use the prepare-worktree skill instead`. The last option deletes the generated files, and flips `foundation_skills.prepare-worktree` to `enabled` and the two `commands.worktree_*` keys off.
+
+### 5. Record
+
+Set `commands.worktree_prepare: <dir>/prepare.sh` and `commands.worktree_teardown: <dir>/teardown.sh` in `.vinta-ai-workflows.yaml` (Step 0.5 already wrote them from the chosen directory; confirm they match). Tell the user the scripts are theirs to commit and edit, and that `teardown.sh <name>` is also how a human removes a worktree they made by hand with `prepare.sh <name>`.
+
+## Pitfalls
+
+- **Hard-coding the main checkout's path, a branch or a DB name.** Everything per-worktree derives from `$NAME` through `forked_db_name` / `COMPOSE_PROJECT`, so lanes never collide.
+- **Writing outside `$WT_PATH`.** The conductor fails provisioning when main's `git status` changes. The only out-of-tree writes allowed are forked databases, compose volumes, and files under the summary dir.
+- **Forgetting `run`.** A bare command executes under `--dry-run` too. Wrap pipes and redirections as `run sh -c '…'`.
+- **A partial summary.** `prepare.sh` writes every key. When you add state, add it to the variables at the top rather than appending keys to the heredoc.
+- **Logging secrets.** Connection strings carry passwords. `require_local_url` never prints the URL; keep it that way in any message you add.

package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/lib-template.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# Shared plumbing for prepare.sh and teardown.sh: resolves the worktree's
+# identity from the VINTA_WORKTREE_* environment (or from a name given on the
+# command line), and provides the small helpers both scripts use. Sourced, never
+# run. Generated by the vinta-ai-workflows bootstrap; owned by this project now.
+#
+# Bash 3.2 compatible (the macOS system bash): no associative arrays, no
+# ${var,,}, no mapfile.
+
+DRY_RUN="${VINTA_WORKTREE_DRY_RUN:-0}"
+FORCE="${VINTA_WORKTREE_FORCE:-0}"
+name_arg=""
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --force) FORCE=1 ;;
+    -h|--help) sed -n '2,/^set -euo/p' "$0" | sed '$d'; exit 0 ;;
+    -*) echo "unknown option: $arg" >&2; exit 2 ;;
+    *) name_arg="$arg" ;;
+  esac
+done
+
+# Resolves symlinks in the deepest part of a path that exists. `git worktree
+# list` prints resolved paths, so every comparison against it needs this (on
+# macOS /var and /tmp are symlinks into /private).
+canon_path() {
+  local p="$1" rest=""
+  while [ ! -d "$p" ]; do rest="/$(basename "$p")$rest"; p="$(dirname "$p")"; done
+  printf '%s%s' "$(cd "$p" && pwd -P)" "$rest"
+}
+
+MAIN="$(canon_path "${VINTA_MAIN_CHECKOUT:-$(git rev-parse --show-toplevel)}")"
+NAME="${VINTA_WORKTREE_NAME:-$name_arg}"
+if [ -z "$NAME" ]; then
+  echo "usage: $0 <worktree-name> [--dry-run]  (or set VINTA_WORKTREE_NAME)" >&2
+  exit 2
+fi
+case "$NAME" in
+  *[!A-Za-z0-9._-]*) echo "worktree name may only use [A-Za-z0-9._-]: $NAME" >&2; exit 2 ;;
+esac
+
+# Project defaults, baked in at generation time. implement-plan always passes
+# the VINTA_WORKTREE_* values explicitly; these only serve a human running the
+# script by hand.
+WORKTREE_ROOT="{{WORKTREE_ROOT}}"
+DEFAULT_BASE_REF="origin/{{DEFAULT_BRANCH}}"
+SUMMARY_DIR="{{SUMMARY_DIR}}"
+
+case "$WORKTREE_ROOT" in /*) root="$WORKTREE_ROOT" ;; *) root="$MAIN/$WORKTREE_ROOT" ;; esac
+# A root ending in "-" is the `../<repo>-wt-` sibling convention: no slash.
+case "$root" in *-) default_path="$root$NAME" ;; *) default_path="$root/$NAME" ;; esac
+
+WT_PATH="$(canon_path "${VINTA_WORKTREE_PATH:-$default_path}")"
+BRANCH="${VINTA_WORKTREE_BRANCH:-$NAME}"
+BASE_REF="${VINTA_WORKTREE_BASE_REF:-$DEFAULT_BASE_REF}"
+KIND="${VINTA_WORKTREE_KIND:-single}"
+PLAN_PATH="${VINTA_PLAN_PATH:-}"
+SUMMARY="${VINTA_WORKTREE_SUMMARY:-$MAIN/$SUMMARY_DIR/$NAME.yaml}"
+
+# Names derived from the worktree name. Every forked database, compose project,
+# volume and cache key comes from these, so prepare.sh and teardown.sh always
+# agree on what belongs to this worktree.
+REPO_SLUG="$(basename "$MAIN" | tr -c 'A-Za-z0-9_\n' '_' | tr 'A-Z' 'a-z')"
+WT_SLUG="$(printf '%s' "$NAME" | tr -c 'A-Za-z0-9_' '_' | tr 'A-Z' 'a-z')"
+COMPOSE_PROJECT="${REPO_SLUG}_wt_${WT_SLUG}"
+COMPOSE_OVERRIDE="$(dirname "$SUMMARY")/$NAME.docker-compose.override.yml"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+log() { printf '[%s %s] %s\n' "$(basename "$0" .sh)" "$NAME" "$*" >&2; }
+
+# Runs a command, or prints it under --dry-run. For pipes or redirections, wrap
+# them: run sh -c '...'.
+run() {
+  if [ "$DRY_RUN" = 1 ]; then
+    printf '+ %s\n' "$*" >&2
+  else
+    "$@"
+  fi
+}
+
+# The forked name for one of main's databases, e.g. app_dev -> app_dev_wt_lane_1.
+forked_db_name() { printf '%s_wt_%s' "$1" "$WT_SLUG"; }
+
+# Hosts a database URL may point at for this script to fork or drop it. Add the
+# project's compose service names (e.g. "db") when the DB runs in compose.
+LOCAL_DB_HOSTS="localhost 127.0.0.1 ::1"
+
+# Refuses anything but a local database. Forking or dropping is only ever done
+# against a developer's own server, never a shared or remote one. Never prints
+# the URL: it can carry a password.
+require_local_url() {
+  local rest host allowed
+  case "$1" in sqlite:*|file:*) return 0 ;; esac
+  rest="${1#*://}"
+  rest="${rest##*@}"
+  case "$rest" in
+    \[*) host="${rest#\[}"; host="${host%%\]*}" ;;
+    *) host="${rest%%[:/?]*}" ;;
+  esac
+  for allowed in $LOCAL_DB_HOSTS; do
+    [ "$host" = "$allowed" ] && return 0
+  done
+  echo "refusing to fork or drop a database on non-local host '$host' (allowed: $LOCAL_DB_HOSTS)" >&2
+  exit 1
+}
+
+# Refuses to drop a database this worktree did not create.
+require_forked_name() {
+  case "$1" in
+    *_wt_"$WT_SLUG") return 0 ;;
+  esac
+  echo "refusing to drop '$1': it is not a '*_wt_$WT_SLUG' database" >&2
+  exit 1
+}
+
+# Copy-on-write clone of a directory from main into the worktree: APFS clonefile
+# on macOS, reflink on btrfs / XFS, plain copy elsewhere. Links inside the tree
+# stay links, which keeps pnpm's relative-link store valid.
+clone_dir() {
+  [ -e "$MAIN/$1" ] || { log "skip $1 (absent in main)"; return 0; }
+  run mkdir -p "$(dirname "$WT_PATH/$1")"
+  if [ "$(uname)" = Darwin ]; then
+    run cp -ac "$MAIN/$1" "$WT_PATH/$1"
+  else
+    run cp -a --reflink=auto "$MAIN/$1" "$WT_PATH/$1"
+  fi
+}
+
+copy_file() {
+  [ -e "$MAIN/$1" ] || { log "skip $1 (absent in main)"; return 0; }
+  run mkdir -p "$(dirname "$WT_PATH/$1")"
+  run cp -p "$MAIN/$1" "$WT_PATH/$1"
+}
+
+# Sets KEY=VALUE in a worktree env file, replacing an existing line for KEY.
+set_env() {
+  local file="$WT_PATH/$1" key="$2" value="$3"
+  if [ "$DRY_RUN" = 1 ]; then printf '+ set %s in %s\n' "$key" "$1" >&2; return 0; fi
+  touch "$file"
+  grep -v "^$key=" "$file" > "$file.tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$file.tmp"
+  mv "$file.tmp" "$file"
+}
+
+# YAML scalar: null for empty, single-quoted otherwise.
+yaml_str() {
+  if [ -z "$1" ] || [ "$1" = null ]; then
+    printf 'null'
+  else
+    printf "'%s'" "$(printf '%s' "$1" | sed "s/'/''/g")"
+  fi
+}
+
+# YAML flow list from space-separated words.
+yaml_list() {
+  local out="" sep="" item
+  for item in $1; do out="$out$sep$(yaml_str "$item")"; sep=", "; done
+  printf '[%s]' "$out"
+}

package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/prepare-template.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# Provision a runnable git worktree for {{PROJECT_NAME}}.
+#
+# implement-plan runs this as `commands.worktree_prepare`, with the
+# VINTA_WORKTREE_* environment set. You can also run it by hand:
+#
+#   {{SCRIPT_DIR}}/prepare.sh <worktree-name> [--dry-run]
+#
+# --dry-run (or VINTA_WORKTREE_DRY_RUN=1) prints every command instead of
+# running it, and writes nothing.
+#
+# What it guarantees (the commands.worktree_prepare contract):
+#   - a worktree at $VINTA_WORKTREE_PATH, on the new branch
+#     $VINTA_WORKTREE_BRANCH, based on $VINTA_WORKTREE_BASE_REF;
+#   - runnable on its own: dependencies, env files, databases and compose
+#     project are the worktree's, never shared writable state with main;
+#   - a non-zero exit on any failure, and never a write to main's tracked files;
+#   - running again for the same name works once teardown.sh has run.
+#
+# Generated by the vinta-ai-workflows bootstrap. This project owns it now: edit
+# the PROJECT STEPS regions freely, and keep teardown.sh in step with them.
+set -euo pipefail
+. "$(cd "$(dirname "$0")" && pwd)/lib.sh" "$@"
+
+# ---------------------------------------------------------------------------
+# What this worktree got. The PROJECT STEPS below set these; the summary at the
+# end records them so teardown and implement-plan's lane reset can read them.
+# ---------------------------------------------------------------------------
+DEPS_STRATEGY=copy        # copy | reinstall
+DEPS_PATHS=""             # space-separated, relative to the worktree
+ENV_STRATEGY=copy         # copy | symlink
+ENV_FILES=""
+DEV_DB_ENGINE=""          # postgres | mysql | sqlite | mongo | redis; empty = no dev DB
+DEV_DB_STRATEGY=fork      # fork | share | stub
+DEV_DB_FORKED=""
+DEV_DB_URL_VAR=""
+DEV_DB_RESET=""           # command that returns the dev DB to a fresh state
+TEST_DB_ENGINE=""         # empty = no test DB
+TEST_DB_STRATEGY=fork     # fork | share
+TEST_DB_FORKED=""
+TEST_DB_URL_VAR=""
+TEST_DB_RESET=""
+USES_COMPOSE=0            # 1 when the project runs services through docker compose
+COMPOSE_NETWORK=per-worktree
+SHARED_VOLUMES=""         # compose volume keys safe to share: read-only caches, never data
+REDIS_DB_INDEX=""
+S3_PREFIX=""
+CRON_DISABLED=false
+NOTES=""
+
+created_worktree=0
+on_exit() {
+  local status=$?
+  [ "$status" -eq 0 ] && return 0
+  [ "$DRY_RUN" = 1 ] && return 0
+  log "provisioning failed (exit $status)"
+  if [ "$created_worktree" = 1 ]; then
+    log "removing the half-made worktree at $WT_PATH"
+    git -C "$MAIN" worktree remove --force "$WT_PATH" >/dev/null 2>&1 || true
+    git -C "$MAIN" branch -D "$BRANCH" >/dev/null 2>&1 || true
+  fi
+  log "databases or volumes created before the failure are removed by teardown.sh, run with the same VINTA_WORKTREE_* environment"
+}
+trap on_exit EXIT
+
+# ---------------------------------------------------------------------------
+# 1. Sanity
+# ---------------------------------------------------------------------------
+if git -C "$MAIN" worktree list --porcelain | grep -Fxq "worktree $WT_PATH"; then
+  echo "a worktree is already registered at $WT_PATH; run teardown.sh first" >&2
+  exit 1
+fi
+if [ -e "$WT_PATH" ]; then
+  echo "$WT_PATH already exists and is not a registered worktree; move it aside first" >&2
+  exit 1
+fi
+if git -C "$MAIN" show-ref --verify --quiet "refs/heads/$BRANCH"; then
+  echo "branch $BRANCH already exists; pick another name or delete it" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Create the worktree
+# ---------------------------------------------------------------------------
+log "creating $WT_PATH on $BRANCH from $BASE_REF"
+case "$BASE_REF" in
+  origin/*) run git -C "$MAIN" fetch --quiet origin || log "fetch failed; using the local $BASE_REF" ;;
+esac
+run mkdir -p "$(dirname "$WT_PATH")"
+run git -C "$MAIN" worktree add --quiet -b "$BRANCH" "$WT_PATH" "$BASE_REF"
+created_worktree=1
+
+# ---------------------------------------------------------------------------
+# 3. PROJECT STEPS. Each region is filled in for this project at generation
+#    time. Write only inside "$WT_PATH", to databases named by
+#    `forked_db_name`, or under the summary dir. Use `run` for every command so
+#    --dry-run stays honest.
+# ---------------------------------------------------------------------------
+
+# >>> deps: every dependency dir is the worktree's own; never a symlink to main.
+#   clone_dir node_modules            # copy-on-write; also each workspace member's
+#   (cd "$WT_PATH" && run uv sync)    # virtualenvs always reinstall
+#   DEPS_PATHS="node_modules"
+# <<< deps
+
+# >>> env: copy env files (compose isolation below appends to .env, so it must
+#   be a copy), then point their connection strings at this worktree's state.
+#   copy_file .env
+#   ENV_FILES=".env"
+# <<< env
+
+# >>> dev_db: fork the local dev database (or leave DEV_DB_ENGINE empty).
+#   require_local_url "$main_database_url"
+#   DEV_DB_FORKED="$(forked_db_name app_dev)"
+#   run createdb -T app_dev "$DEV_DB_FORKED"
+#   set_env .env DATABASE_URL "postgres://localhost:5432/$DEV_DB_FORKED"
+#   DEV_DB_ENGINE=postgres DEV_DB_URL_VAR=DATABASE_URL
+#   DEV_DB_RESET="dropdb --if-exists $DEV_DB_FORKED && createdb -T app_dev $DEV_DB_FORKED"
+# <<< dev_db
+
+# >>> test_db: give the test runner its own database name.
+#   TEST_DB_FORKED="$(forked_db_name app_test)"
+#   set_env .env TEST_DATABASE_URL "postgres://localhost:5432/$TEST_DB_FORKED"
+#   TEST_DB_ENGINE=postgres TEST_DB_URL_VAR=TEST_DATABASE_URL
+#   TEST_DB_RESET="dropdb --if-exists $TEST_DB_FORKED"
+# <<< test_db
+
+# >>> compose: set USES_COMPOSE=1 when the project runs services through
+#   docker compose. Step 4 then isolates the stack generically.
+#   USES_COMPOSE=1
+#   SHARED_VOLUMES=""
+# <<< compose
+
+# >>> other: Redis index / key prefix, S3 prefix, queue and index suffixes,
+#   cron off, migrations against the forked DB.
+#   S3_PREFIX="wt-$NAME/"; set_env .env S3_PREFIX "$S3_PREFIX"
+#   (cd "$WT_PATH" && run python manage.py migrate)
+# <<< other
+
+# ---------------------------------------------------------------------------
+# 4. Compose isolation. COMPOSE_PROJECT_NAME alone does not isolate external or
+#    fixed-name volumes, or fixed host ports; the generated out-of-tree override
+#    does. Never edit the project's tracked compose files.
+# ---------------------------------------------------------------------------
+FORKED_VOLUMES_YAML="[]"
+PORTS_STRIPPED=""
+BASE_COMPOSE_FILE=""
+if [ "$USES_COMPOSE" = 1 ]; then
+  run mkdir -p "$(dirname "$COMPOSE_OVERRIDE")"
+  share_args=""
+  for vol in $SHARED_VOLUMES; do share_args="$share_args --share-volume $vol"; done
+  report="$(mktemp)"
+  # shellcheck disable=SC2086  # share_args is a deliberate word list
+  run "$SCRIPT_DIR/gen-compose-worktree-override.sh" --main "$MAIN" --worktree "$WT_PATH" \
+    --name "$NAME" --out "$COMPOSE_OVERRIDE" $share_args 2> "$report" >/dev/null
+  cat "$report" >&2
+  for f in compose.yaml compose.yml docker-compose.yaml docker-compose.yml; do
+    if [ -f "$MAIN/$f" ]; then BASE_COMPOSE_FILE="$f"; break; fi
+  done
+  set_env .env COMPOSE_PROJECT_NAME "$COMPOSE_PROJECT"
+  set_env .env COMPOSE_FILE "$BASE_COMPOSE_FILE:$COMPOSE_OVERRIDE"
+  case " $ENV_FILES " in *" .env "*) ;; *) ENV_FILES="$ENV_FILES .env" ;; esac
+  # The generator reports "- <key> (<reason>) -> <volume>" per forked volume.
+  FORKED_VOLUMES_YAML="$(sed -n 's/^    - \([^ ]*\) (\(.*\)) -> \(.*\)$/\1|\2|\3/p' "$report" | {
+    out="" sep=""
+    while IFS='|' read -r key reason pinned; do
+      case "$reason" in external*) reason=external ;; *) reason=fixed-name ;; esac
+      out="$out$sep{volume_key: $(yaml_str "$key"), reason: $reason, forked_name: $(yaml_str "$pinned")}"
+      sep=", "
+    done
+    printf '[%s]' "$out"
+  })"
+  PORTS_STRIPPED="$(sed -n 's/^  stripped host-port publishing from: //p' "$report" | sed 's/^none$//; s/,//g')"
+  rm -f "$report"
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Summary: read by teardown, by implement-plan's lane reset, and by
+#    vinta-ai-maestro. Every key is present; null means none.
+# ---------------------------------------------------------------------------
+db_yaml() { # engine strategy forked url_var reset
+  if [ -z "$1" ]; then printf 'null'; return 0; fi
+  printf '\n    engine: %s\n    strategy: %s\n    forked_name: %s\n    connection_url_var: %s\n    reset_cmd: %s' \
+    "$1" "$2" "$(yaml_str "$3")" "$(yaml_str "$4")" "$(yaml_str "$5")"
+}
+
+if [ "$USES_COMPOSE" = 1 ]; then
+  compose_yaml="$(printf '\n    project_name: %s\n    network_strategy: %s\n    override_path: %s\n    base_compose_file: %s\n    forked_volumes: %s\n    shared_volumes: %s\n    ports_stripped_from: %s' \
+    "$(yaml_str "$COMPOSE_PROJECT")" "$COMPOSE_NETWORK" "$(yaml_str "$COMPOSE_OVERRIDE")" \
+    "$(yaml_str "$BASE_COMPOSE_FILE")" "$FORKED_VOLUMES_YAML" "$(yaml_list "$SHARED_VOLUMES")" \
+    "$(yaml_list "$PORTS_STRIPPED")")"
+else
+  compose_yaml=null
+fi
+
+if [ "$DRY_RUN" = 1 ]; then
+  log "dry run: would write the summary to $SUMMARY"
+else
+  mkdir -p "$(dirname "$SUMMARY")"
+  cat > "$SUMMARY" <<EOF
+# Written by $(basename "$0"); read by teardown.sh and implement-plan.
+name: $(yaml_str "$NAME")
+path: $(yaml_str "$WT_PATH")
+branch: $(yaml_str "$BRANCH")
+base_ref: $(yaml_str "$BASE_REF")
+created_at: $(yaml_str "$(date -u +%Y-%m-%dT%H:%M:%SZ)")
+plan_path: $(yaml_str "$PLAN_PATH")
+flags:
+  deps_change: true
+  schema_change: true
+  env_change: true
+  test_infra_change: true
+  compose_change: $([ "$USES_COMPOSE" = 1 ] && echo true || echo false)
+state:
+  deps:
+    strategy: $DEPS_STRATEGY
+    paths: $(yaml_list "$DEPS_PATHS")
+  env:
+    strategy: $ENV_STRATEGY
+    files: $(yaml_list "$ENV_FILES")
+  dev_db: $(db_yaml "$DEV_DB_ENGINE" "$DEV_DB_STRATEGY" "$DEV_DB_FORKED" "$DEV_DB_URL_VAR" "$DEV_DB_RESET")
+  test_db: $(db_yaml "$TEST_DB_ENGINE" "$TEST_DB_STRATEGY" "$TEST_DB_FORKED" "$TEST_DB_URL_VAR" "$TEST_DB_RESET")
+  compose: $compose_yaml
+  other:
+    redis_db_index: $(yaml_str "$REDIS_DB_INDEX")
+    s3_prefix: $(yaml_str "$S3_PREFIX")
+    cron_disabled: $CRON_DISABLED
+  sandbox:
+    tier: none
+    launcher: null
+    deny: []
+    allow: []
+notes: $(yaml_str "Provisioned by $(basename "$0") (kind: $KIND). $NOTES")
+EOF
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Report (implement-plan quotes the tail of this)
+# ---------------------------------------------------------------------------
+cat <<EOF
+worktree: $WT_PATH
+branch:   $BRANCH (from $BASE_REF)
+deps:     $DEPS_STRATEGY ${DEPS_PATHS:-(none)}
+env:      $ENV_STRATEGY ${ENV_FILES:-(none)}
+dev db:   ${DEV_DB_FORKED:-(none)}
+test db:  ${TEST_DB_FORKED:-(none)}
+compose:  $([ "$USES_COMPOSE" = 1 ] && echo "$COMPOSE_PROJECT" || echo "(not used)")
+summary:  $SUMMARY
+teardown: $SCRIPT_DIR/teardown.sh $NAME
+EOF

package/skills/vinta-bootstrap-ai-tools/resources/worktree-command/teardown-template.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Remove a worktree prepare.sh made for {{PROJECT_NAME}}, and everything it
+# created outside git.
+#
+# implement-plan runs this as `commands.worktree_teardown`, with the same
+# VINTA_WORKTREE_* environment the worktree was provisioned with. You can also
+# run it by hand:
+#
+#   {{SCRIPT_DIR}}/teardown.sh <worktree-name> [--dry-run] [--force]
+#
+# Safe to run more than once: every step skips what is already gone. It refuses
+# a worktree with uncommitted changes unless --force (or VINTA_WORKTREE_FORCE=1)
+# is given, and only drops databases named `*_wt_<worktree>`. It never runs
+# `docker compose down -v`, which would also delete volumes shared with main.
+#
+# Generated by the vinta-ai-workflows bootstrap. Keep the PROJECT STEPS regions
+# in step with prepare.sh's.
+set -euo pipefail
+. "$(cd "$(dirname "$0")" && pwd)/lib.sh" "$@"
+
+registered=0
+if git -C "$MAIN" worktree list --porcelain | grep -Fxq "worktree $WT_PATH"; then
+  registered=1
+fi
+
+# ---------------------------------------------------------------------------
+# 1. Refuse to lose work
+# ---------------------------------------------------------------------------
+if [ "$registered" = 1 ] && [ "$FORCE" != 1 ]; then
+  if [ -n "$(git -C "$WT_PATH" status --porcelain)" ]; then
+    echo "$WT_PATH has uncommitted changes; commit or stash them, or pass --force to discard them" >&2
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 2. PROJECT STEPS, in reverse order of prepare.sh. Each must tolerate state
+#    that is already gone.
+# ---------------------------------------------------------------------------
+
+# >>> other: undo what prepare.sh's "other" region created outside the worktree.
+# <<< other
+
+# >>> test_db: drop the forked test database.
+#   db="$(forked_db_name app_test)"; require_forked_name "$db"
+#   run dropdb --if-exists "$db"
+# <<< test_db
+
+# >>> dev_db: drop the forked dev database.
+#   db="$(forked_db_name app_dev)"; require_forked_name "$db"
+#   run dropdb --if-exists "$db"
+# <<< dev_db
+
+# ---------------------------------------------------------------------------
+# 3. Compose: stop the stack, then remove only the volumes the override pinned
+#    for this worktree. Shared volumes stay.
+# ---------------------------------------------------------------------------
+if [ -f "$COMPOSE_OVERRIDE" ]; then
+  if [ "$registered" = 1 ] && command -v docker >/dev/null 2>&1; then
+    (cd "$WT_PATH" && run docker compose -p "$COMPOSE_PROJECT" down) || log "compose down failed; continuing"
+  fi
+  # The override's volumes: block lists each pinned name; that is the manifest.
+  for vol in $(sed -n '/^volumes:/,/^[^ ]/s/^    name: "\(.*\)"$/\1/p' "$COMPOSE_OVERRIDE"); do
+    case "$vol" in
+      *_wt_"$NAME"_*) run docker volume rm "$vol" >/dev/null 2>&1 || log "volume $vol already gone" ;;
+      *) log "skip volume $vol: not named for this worktree" ;;
+    esac
+  done
+  run rm -f "$COMPOSE_OVERRIDE"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. The worktree and its branch
+# ---------------------------------------------------------------------------
+if [ "$registered" = 1 ]; then
+  if [ "$FORCE" = 1 ]; then
+    run git -C "$MAIN" worktree remove --force "$WT_PATH"
+  else
+    run git -C "$MAIN" worktree remove "$WT_PATH"
+  fi
+else
+  log "no worktree registered at $WT_PATH"
+fi
+# The branch goes only when it holds no commits of its own (its tip is already
+# in the base ref, or merged into main's HEAD). Anything else is kept.
+if git -C "$MAIN" show-ref --verify --quiet "refs/heads/$BRANCH"; then
+  if git -C "$MAIN" merge-base --is-ancestor "$BRANCH" "$BASE_REF" 2>/dev/null \
+    || git -C "$MAIN" merge-base --is-ancestor "$BRANCH" HEAD 2>/dev/null; then
+    run git -C "$MAIN" branch -D "$BRANCH" >/dev/null
+  else
+    log "kept branch $BRANCH: it has commits not in $BASE_REF (delete it with git branch -D once you are sure)"
+  fi
+fi
+
+run rm -f "$SUMMARY"
+log "done"