# Autospec Worktree Setup

> Generate project-specific worktree setup script based on project analysis. Use when this capability is needed.

- Skill: `tomevault-io/autospec-worktree-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/autospec-worktree-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/autospec-worktree-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/autospec-worktree-setup

---


# autospec-worktree-setup

This Agent Skill is generated from autospec.worktree-setup. When the user invokes "$autospec-worktree-setup" or "/autospec.worktree-setup",
load and follow these instructions directly. Treat the text after the skill or
command name as "$ARGUMENTS". Do not route back through "autospec worktree-setup"; this skill
is the prompt for the stage.

Project specs directory: ./specs

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

You are generating a project-specific setup script that will be run when creating new git worktrees. This script handles copying essential configuration files and running package manager install commands instead of copying large dependency directories.

Follow this execution flow:

1. **Analyze project structure**:
   - Identify package managers by checking for lockfiles:
     - `package-lock.json` -> npm
     - `yarn.lock` -> yarn
     - `pnpm-lock.yaml` -> pnpm
     - `bun.lockb` -> bun
     - `go.sum` or `go.mod` -> go
     - `requirements.txt` or `Pipfile.lock` -> pip/pipenv
     - `poetry.lock` or `pyproject.toml` with `[tool.poetry]` -> poetry
     - `Cargo.lock` -> cargo
     - `Gemfile.lock` -> bundler
     - `composer.lock` -> composer
   - Identify essential directories/files to copy:

     **Autospec-related (REQUIRED for autospec workflows):**
     - `.autospec/` - Contains constitution, config, memory, and generated scripts. The `constitution.yaml` is REQUIRED for all workflow stages (specify, plan, tasks, implement).
     - `.agents/skills/` (if exists) - Shared autospec skills for Codex and OpenCode skill-aware sessions.
     - `.claude/skills/` (if exists) - Claude Code project skills. Required if using `agent_preset: claude`.
     - `opencode.json` (if exists) - OpenCode configuration file with permissions and model settings. Located at project root, not inside `.opencode/`.

     **IDE/Editor configuration:**
     - `.vscode/` (if exists)
     - `.idea/` (if exists)
     - Other gitignored config directories needed for development
   - Identify files/directories to EXCLUDE:
     - Dependency directories: `node_modules/`, `vendor/`, `__pycache__/`, `.venv/`, `venv/`, `target/`, `dist/`, `build/`, `.bundle/`
     - Generated files: `*.log`, `*.tmp`, `.cache/`, `coverage/`

2. **Handle secrets**:
   - By default, EXCLUDE these secret patterns:
     - `.env*` (`.env`, `.env.local`, `.env.production`, etc.)
     - `credentials.*`
     - `secrets.*`
     - `*.pem`
     - `*.key`
     - `*.p12`
     - `*token*` files
     - `.ssh/`
   - If `--include-env` was specified in the user input, include `.env*` files but still exclude other secret patterns

3. **Generate the setup script**:

   Create a POSIX-compatible bash script at `.autospec/scripts/setup-worktree.sh` with the following structure:

   ```bash
   #!/bin/bash
   # setup-worktree.sh - Project-specific worktree setup script
   # Generated by autospec worktree gen-script
   #
   # Usage: Called automatically by 'autospec worktree create' or run manually:
   #   ./setup-worktree.sh <worktree_path>
   #
   # Environment variables (set by worktree create command):
   #   WORKTREE_PATH   - Path to the new worktree
   #   WORKTREE_NAME   - Name of the worktree
   #   WORKTREE_BRANCH - Branch checked out in worktree
   #   SOURCE_REPO     - Path to source repository

   set -euo pipefail

   # Get worktree path from argument or environment
   WORKTREE_PATH="${1:-${WORKTREE_PATH:-}}"
   SOURCE_REPO="${SOURCE_REPO:-$(git rev-parse --show-toplevel)}"

   if [ -z "$WORKTREE_PATH" ]; then
       echo "Error: Worktree path required. Usage: $0 <worktree_path>"
       exit 1
   fi

   echo "Setting up worktree at: $WORKTREE_PATH"
   echo "Source repository: $SOURCE_REPO"

   # Function to copy directory if it exists
   copy_if_exists() {
       local src="$SOURCE_REPO/$1"
       local dst="$WORKTREE_PATH/$1"
       if [ -d "$src" ]; then
           echo "Copying $1..."
           mkdir -p "$(dirname "$dst")"
           cp -r "$src" "$dst"
       fi
   }

   # Copy essential configuration directories
   # Autospec-related (REQUIRED for autospec workflows)
   copy_if_exists ".autospec"       # Constitution, config, memory, scripts
   copy_if_exists ".agents/skills"  # Shared Codex/OpenCode skills
   copy_if_exists ".claude/skills"  # Claude Code project skills

   # Copy OpenCode config file if it exists
   if [ -f "$SOURCE_REPO/opencode.json" ]; then
       echo "Copying opencode.json..."
       cp "$SOURCE_REPO/opencode.json" "$WORKTREE_PATH/opencode.json"
   fi

   # IDE/Editor configuration (if detected)
   # copy_if_exists ".vscode"
   # copy_if_exists ".idea"

   # Run package manager install commands
   cd "$WORKTREE_PATH"
   # (Include detected package manager commands)

   echo "Worktree setup complete!"
   ```

4. **Ensure the script**:
   - Uses POSIX-compatible bash (no bashisms)
   - Is idempotent (safe to run multiple times)
   - Handles missing directories gracefully
   - Provides clear output about what it's doing
   - Exits with appropriate error codes

5. **Create output directory**:
   - Ensure `.autospec/scripts/` directory exists
   - Write the script to `.autospec/scripts/setup-worktree.sh`
   - Make it executable (the CLI will set permissions)

6. **Report results**:
   - List directories that will be copied
   - List package manager commands that will be run
   - Note any secrets that are being excluded
   - If `--include-env` was used, warn about security implications

## Output Location

The generated script MUST be written to: `.autospec/scripts/setup-worktree.sh`

## Important Constraints

- The script must work with the existing `autospec worktree create` command
- Secrets are NEVER copied by default - this is a security requirement
- Dependency directories are NEVER copied - install commands are run instead
- The script must be readable and well-commented for user customization

---
> Source: [ariel-frischer/autospec](https://github.com/ariel-frischer/autospec) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-27 -->