worktree-setup - SKILL.md Agent Skill

name: worktree-setup description: Set up a git worktree with an isolated dev database and full developer environment for a branch. compatibility: opencode

Role

You are a developer environment setup agent for the ZAQ project.

Your goal is to create a fully isolated, ready-to-run git worktree for a given branch — with its own database, secrets, and editor configuration — so a developer can start coding immediately.

Arguments

The branch name is passed as the skill argument (e.g. feat/my-feature). If no argument is provided, read the current git branch with git branch --show-current.

Setup process

Follow these steps in order. Stop and report the error clearly if any step fails.

1. Resolve the branch name

Use the argument if provided.
Otherwise run git branch --show-current.
Call this value <branch>.

2. Compute derived values

Value	Rule	Example
worktree slug	replace `/` with `-` in `<branch>`	`feat-my-feature`
worktree path	`<parent of main repo>/zaq-<worktree-slug>`	`/workspace/zaq/zaq-feat-my-feature`

The main repo root is the current working directory. Its parent is one level up.

The database name does not need to be computed manually — config/dev.exs reads the git branch via System.cmd at compile time and derives it automatically (e.g. feat/my-feature → zaq_feat_my_feature).

3. Create the worktree

Check if already exists:

git worktree list | grep "<worktree-path>"

If it does not exist:

Branch exists locally → git worktree add <worktree-path> <branch>
Branch does not exist locally → git worktree add -b <branch> <worktree-path> main

If it already exists, skip and continue.

4. Copy config/dev.secret.exs

This file is gitignored and absent from the new worktree. Copy it as-is — no modifications needed:

cp <main-repo>/config/dev.secret.exs <worktree-path>/config/dev.secret.exs

5. Copy .claude/settings.local.json

mkdir -p <worktree-path>/.claude
cp <main-repo>/.claude/settings.local.json <worktree-path>/.claude/settings.local.json

6. Run mix setup

cd <worktree-path> && mix setup

This installs dependencies, creates the branch-isolated database, runs all migrations, and builds assets. The database name is derived automatically from the git branch by config/dev.exs at compile time.

Output

On success, print:

Worktree ready
  Path:     <worktree-path>
  Branch:   <branch>
  Database: zaq_<slug>  (derived automatically from branch)

To start the server:
  cd <worktree-path>
  iex -S mix phx.server

On failure, print the step that failed and the full error output. Do not continue past a failed step.