---
name: oat-worktree-bootstrap
version: 1.2.1
description: Use when creating or resuming a git worktree for OAT implementation. Creates or validates a worktree and runs OAT bootstrap checks.
argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--existing]'
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
---

# Worktree Bootstrap

Create or resume a git worktree and prepare it for OAT development.

## Prerequisites

- Git repository is clean enough to create/switch worktrees.
- The toolchain required by the repository is available in the target
  environment.
- OAT project files exist (`.oat/`, `.agents/`).

## Mode Assertion

**OAT MODE: Worktree Bootstrap**

**Purpose:** Establish an isolated workspace and run standard OAT readiness checks before implementation work.

**BLOCKED Activities:**

- No implementation code changes unrelated to worktree setup.
- No destructive rewrite of existing project artifacts.

**ALLOWED Activities:**

- Create/reuse worktree paths.
- Run bootstrap and readiness checks.
- Update related state/docs for workspace readiness.

## Progress Indicators (User-Facing)

- Print a phase banner once at start:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OAT ▸ WORKTREE BOOTSTRAP
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- Before multi-step operations, print step indicators, e.g.:
  - `[1/4] Resolving worktree target…`
  - `[2/4] Creating/validating worktree…`
  - `[3/4] Running OAT bootstrap checks…`
  - `[4/4] Reporting ready state…`

## Inputs

- Required for creation mode: `<branch-name>`
- Optional:
  - `--base <ref>` (default: `origin/main`)
  - `--path <root>` (explicit worktree root override)
  - `--existing` (bootstrap/validate existing worktree instead of creating one)

## Process

### Step 0: Resolve Repository Context

```bash
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")
```

### Step 0.5: Validate Active Project Config

Resolve active project from local config:

```bash
ACTIVE_PROJECT=$(oat config get activeProject 2>/dev/null || true)
```

If `ACTIVE_PROJECT` is set:

- verify the pointed path exists and contains `state.md`
- if invalid, do **not** silently rewrite it
- prompt user to run one of:
  - `oat-project-clear-active`
  - `oat-project-open`
- require explicit confirmation before continuing with worktree bootstrap

If `ACTIVE_PROJECT` is missing:

- continue (active project is optional for worktree bootstrap)
- use console-only baseline-failure logging in Step 3 if needed

### Step 1: Resolve Target Worktree Context

If `--existing`:

- validate the current directory appears in `git worktree list --porcelain`
- set `TARGET_WORKTREE` to the current directory
- set `WORKTREE_ROOT` to the parent directory of `TARGET_WORKTREE` (informational)
- skip root-path convention checks; externally managed paths are allowed (for example Codex-managed worktrees under `~/.codex/worktrees/...`)

Otherwise, resolve `WORKTREE_ROOT` using this strict precedence (stop at the **first match**):

1. Explicit `--path <root>` (CLI flag — highest priority)
2. `OAT_WORKTREES_ROOT` (environment variable)
3. `.oat/config.json` -> `worktrees.root` (persisted project config)
4. First existing directory in this order (check each, use the first that exists):
   a. `${REPO_ROOT}/.worktrees`
   b. `${REPO_ROOT}/worktrees`
   c. `../${REPO_NAME}-worktrees`
5. Fallback default (nothing matched above): `../${REPO_NAME}-worktrees`

**IMPORTANT:** Precedence level 4 is an ordered list, not a set. Check `.worktrees` first. If it exists, use it — do NOT continue scanning for `../<repo>-worktrees` even if that also exists. Only fall through to the next candidate if the current one does not exist.

For repo-relative values (levels 3–4a–4b), resolve from `REPO_ROOT`.
Treat `.oat/config.json` as phase-A non-sync settings ownership (do not mix with `.oat/sync/config.json`).

If the resolved root is project-local (`.worktrees` or `worktrees`), verify it is ignored by git before creating a new worktree.
Set `TARGET_WORKTREE` to `{WORKTREE_ROOT}/{branch-name}`.

### Step 2: Create or Reuse Worktree

- If `--existing`, validate the current directory is a git worktree and continue.
- Otherwise:
  - validate branch name format (`^[a-zA-Z0-9._/-]+$`)
  - resolve target path as `TARGET_WORKTREE`
  - if branch already exists locally:
    - `git worktree add "{TARGET_WORKTREE}" "{branch-name}"`
  - if branch does not exist:
    - `git worktree add "{TARGET_WORKTREE}" -b "{branch-name}" "{base-ref}"`

`{base-ref}` defaults to `origin/main` unless `--base` is provided.

If worktree creation fails, stop and report the exact git error with remediation guidance.

### Step 2.5: Propagate Local-Only Config + Local Paths

After the worktree is created (or validated with `--existing`), copy gitignored local-only context files from the source repo into the new worktree so downstream skills (e.g., `oat-project-implement`) can resolve context without re-prompting.

**Config propagation:**

Copy `.oat/config.local.json` if it exists in the source repo:

```bash
SRC="$REPO_ROOT/.oat/config.local.json"
DST="{target-path}/.oat/config.local.json"
if [[ -f "$SRC" && ! -f "$DST" ]]; then
  cp "$SRC" "$DST"
fi
```

Rules:

- Only copy if the source file exists **and** the destination does not (never overwrite).
- `config.local.json` uses repo-relative paths, so copied values remain valid across sibling worktrees.
- `activeIdea` is stored in `config.local.json`, so it propagates automatically with the config copy.
- After copying, validate `activeProject` (if present in `config.local.json`) resolves to a real project path in the worktree. If not, print a warning but do not block bootstrap.

**Local paths sync:**

After config propagation, sync configured `localPaths` into the worktree:

```bash
oat local sync "{target-path}" 2>/dev/null || true
```

- Uses the `localPaths` array from `.oat/config.json` to copy local-only directories (e.g., `.oat/ideas/`, `.oat/projects/local/`) into the worktree.
- Non-blocking: if sync fails or no `localPaths` are configured, bootstrap continues.
- Does not overwrite existing paths in the target (use `--force` to override).

### Step 3: Resolve and Run the Repository Bootstrap

Resolve setup from repository context; do not assume Node.js, pnpm, or any
other ecosystem:

1. Read the applicable agent instructions and contributing/setup guidance.
2. Inspect repository task definitions, manifests, and lockfiles.
3. Prefer an explicit worktree bootstrap command when the repository declares
   one. For example, this repository documents a `worktree:init` script and its
   package-manager invocation in `AGENTS.md` and `package.json`.
4. If no command exists, derive the minimum safe setup needed for a fresh
   worktree from repository context: dependency setup, generated files, build,
   and any required local configuration.
5. State the exact selected commands and evidence before executing them.

Run the selected bootstrap command, then the repository's documented readiness
check and a proportionate baseline verification. Run `oat status --scope
project` when the initialized repository contains an OAT project. Finish with
`git status --porcelain`.

Required behavior:

- Stop immediately if the selected bootstrap or required status check fails.
- If the selected baseline verification fails:
  - show a concise failure summary
  - ask the user whether to `abort` or `proceed anyway`
  - if user proceeds:
    - when a valid active project with `implementation.md` exists, append a timestamped baseline-failure note there
    - otherwise print the same note to console output only (do not create a fallback file)
- If `git status --porcelain` is not clean after bootstrap/tests, stop and require cleanup before reporting ready.

### Step 4: Output Ready State

Report:

- resolved worktree path
- active branch
- bootstrap/verification status
- next command: `oat-project-implement`

## References

- `references/worktree-conventions.md`

## Success Criteria

- ✅ Worktree exists (or existing worktree validated).
- ✅ OAT bootstrap completed without blocking errors.
- ✅ User receives a clear next action for implementation.
