aiblueprint-cli 1.4.59 → 1.4.61

package/agents-config/skills/environments-manager/examples/scripts/claude-worktree-create.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Claude Code WorktreeCreate hook wrapper.
+# Replaces default `git worktree add` behavior, then runs the shared scripts/worktree-up.sh.
+#
+# stdin contract:  JSON with { "name": "<worktree-name>", ... }
+# stdout contract: the absolute worktree path and NOTHING ELSE.
+# Progress goes to <worktree>/.worktree-setup.log AND /dev/tty when available.
+
+set -euo pipefail
+
+INPUT=$(cat)
+NAME=$(echo "$INPUT" | jq -r '.name')
+REPO="$CLAUDE_PROJECT_DIR"
+WORKTREE="${REPO}/.claude/worktrees/${NAME}"
+BRANCH="worktree-${NAME}"
+SETUP_TIMEOUT_SEC="${CLAUDE_WORKTREE_SETUP_TIMEOUT:-900}"
+
+LOG_FILE=""
+
+# Both the /dev/tty redirect AND the log append are guarded so a missing tty or
+# read-only worktree never aborts the hook (the script runs under `set -e`).
+log_to() {
+  { echo "$*" > /dev/tty; } 2>/dev/null || true
+  if [[ -n "$LOG_FILE" ]]; then
+    echo "$(date '+%H:%M:%S') $*" >> "$LOG_FILE" 2>/dev/null || true
+  fi
+}
+
+log_to "[claude-worktree-create] Creating worktree (branch: $BRANCH)..."
+
+mkdir -p "${REPO}/.claude/worktrees"
+if git -C "$REPO" rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
+  git -C "$REPO" worktree add "$WORKTREE" "$BRANCH" >/dev/null 2>&1
+else
+  git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" HEAD >/dev/null 2>&1
+fi
+
+LOG_FILE="$WORKTREE/.worktree-setup.log"
+: > "$LOG_FILE"
+
+# Hooks inherit the shell default Node, NOT the project's .nvmrc. Many CLIs
+# (e.g. Convex) crash on older Node. Source nvm/fnm so `node` resolves to
+# whatever the worktree's .nvmrc demands.
+if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
+  # shellcheck disable=SC1090,SC1091
+  . "$HOME/.nvm/nvm.sh" >/dev/null 2>&1 || true
+  if [[ -f "$WORKTREE/.nvmrc" ]]; then
+    (cd "$WORKTREE" && nvm use >/dev/null 2>&1) || true
+  fi
+elif command -v fnm >/dev/null 2>&1; then
+  eval "$(fnm env --use-on-cd)" || true
+fi
+
+log_to "[claude-worktree-create] Using node: $(node --version 2>&1 || echo unknown)"
+
+run_setup() {
+  cd "$WORKTREE"
+  # CI=1 keeps interactive CLIs (convex, prisma, etc.) from prompting and hanging.
+  ROOT_WORKTREE_PATH="$REPO" \
+  CLAUDE_WORKTREE_NAME="$NAME" \
+  CI=1 \
+    bash "${REPO}/scripts/worktree-up.sh"
+}
+
+# Watchdog: hard-kill setup after SETUP_TIMEOUT_SEC. macOS has no `timeout`
+# command by default, so we background the setup and a sleeper that kills it
+# on timeout. Without this, an interactive prompt would hang the hook forever.
+(
+  run_setup >> "$LOG_FILE" 2>&1
+) &
+SETUP_PID=$!
+
+(
+  sleep "$SETUP_TIMEOUT_SEC"
+  if kill -0 "$SETUP_PID" 2>/dev/null; then
+    echo "[claude-worktree-create] TIMEOUT after ${SETUP_TIMEOUT_SEC}s - killing setup (PID $SETUP_PID)" >> "$LOG_FILE"
+    kill -TERM "$SETUP_PID" 2>/dev/null || true
+    sleep 5
+    kill -KILL "$SETUP_PID" 2>/dev/null || true
+  fi
+) &
+WATCHDOG_PID=$!
+
+SETUP_EXIT=0
+wait "$SETUP_PID" || SETUP_EXIT=$?
+kill "$WATCHDOG_PID" 2>/dev/null || true
+wait "$WATCHDOG_PID" 2>/dev/null || true
+
+if [[ "$SETUP_EXIT" -ne 0 ]]; then
+  log_to "[claude-worktree-create] worktree-up.sh exited $SETUP_EXIT - see $LOG_FILE"
+else
+  log_to "[claude-worktree-create] Worktree ready."
+fi
+
+# THE ONLY THING ON STDOUT - Claude parses this as the cwd.
+echo "$WORKTREE"

package/agents-config/skills/environments-manager/examples/scripts/claude-worktree-remove.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Claude Code WorktreeRemove hook wrapper.
+# Runs scripts/worktree-down.sh for cleanup, then removes the git worktree and branch.
+#
+# stdin contract: JSON with { "worktree_path": "<absolute-path>", ... }
+
+set -euo pipefail
+
+INPUT=$(cat)
+WORKTREE=$(echo "$INPUT" | jq -r '.worktree_path')
+REPO="$CLAUDE_PROJECT_DIR"
+CLEANUP_TIMEOUT_SEC="${CLAUDE_WORKTREE_CLEANUP_TIMEOUT:-300}"
+
+[[ ! -d "$WORKTREE" ]] && exit 0
+
+LOG_FILE="$WORKTREE/.worktree-cleanup.log"
+: > "$LOG_FILE" 2>/dev/null || LOG_FILE=""
+
+log_to() {
+  { echo "$*" > /dev/tty; } 2>/dev/null || true
+  if [[ -n "$LOG_FILE" ]]; then
+    echo "$(date '+%H:%M:%S') $*" >> "$LOG_FILE" 2>/dev/null || true
+  fi
+}
+
+# Cleanup may call CLIs (e.g. convex env remove) that need the project's Node version.
+if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
+  # shellcheck disable=SC1090,SC1091
+  . "$HOME/.nvm/nvm.sh" >/dev/null 2>&1 || true
+  if [[ -f "$WORKTREE/.nvmrc" ]]; then
+    (cd "$WORKTREE" && nvm use >/dev/null 2>&1) || true
+  fi
+elif command -v fnm >/dev/null 2>&1; then
+  eval "$(fnm env --use-on-cd)" || true
+fi
+
+run_cleanup() {
+  cd "$WORKTREE"
+  ROOT_WORKTREE_PATH="$REPO" CI=1 bash "${REPO}/scripts/worktree-down.sh"
+}
+
+if [[ -x "${REPO}/scripts/worktree-down.sh" ]]; then
+  (
+    run_cleanup >> "${LOG_FILE:-/dev/null}" 2>&1
+  ) &
+  CLEANUP_PID=$!
+
+  (
+    sleep "$CLEANUP_TIMEOUT_SEC"
+    if kill -0 "$CLEANUP_PID" 2>/dev/null; then
+      log_to "[claude-worktree-remove] TIMEOUT after ${CLEANUP_TIMEOUT_SEC}s - killing cleanup"
+      kill -TERM "$CLEANUP_PID" 2>/dev/null || true
+      sleep 3
+      kill -KILL "$CLEANUP_PID" 2>/dev/null || true
+    fi
+  ) &
+  WATCHDOG_PID=$!
+
+  wait "$CLEANUP_PID" 2>/dev/null || true
+  kill "$WATCHDOG_PID" 2>/dev/null || true
+  wait "$WATCHDOG_PID" 2>/dev/null || true
+fi
+
+BRANCH=$(git -C "$WORKTREE" rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+git -C "$REPO" worktree remove "$WORKTREE" --force 2>/dev/null || true
+[[ -n "$BRANCH" && "$BRANCH" != "HEAD" ]] && git -C "$REPO" branch -D "$BRANCH" 2>/dev/null || true

package/agents-config/skills/environments-manager/examples/scripts/dev.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Example: dev server on a free port. Generated by environments-manager.
+
+set -euo pipefail
+
+WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
+cd "$WORKTREE_PATH"
+
+port="${DEV_PORT_START:-3910}"
+while lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
+  port=$((port + 1))
+done
+
+echo "Starting app on http://localhost:$port"
+exec pnpm dev -p "$port"

package/agents-config/skills/environments-manager/examples/scripts/worktree-down.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Example: pnpm + Postgres project cleanup. Generated by environments-manager.
+
+set -euo pipefail
+
+WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
+cd "$WORKTREE_PATH"
+
+if [[ ! -f .env ]]; then
+  echo "no .env in worktree, nothing to clean"
+  exit 0
+fi
+
+db_name=$(grep -E '^DATABASE_URL=' .env | sed -E 's|.*/([^/?]+).*|\1|' | head -n1 || true)
+
+if [[ -n "${db_name:-}" ]] && command -v dropdb >/dev/null 2>&1; then
+  dropdb --if-exists -d postgres "$db_name" || true
+  echo "dropped $db_name"
+fi
+
+rm -f .env .env.local .env.development.local
+echo "removed local env files"

package/agents-config/skills/environments-manager/examples/scripts/worktree-up.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Example: pnpm + Postgres project with all four setup steps enabled.
+# Generated by environments-manager. Adapt the project section for your repo.
+
+set -euo pipefail
+
+WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
+SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-$HOME/Developer/saas/myapp}}"
+
+cd "$WORKTREE_PATH"
+
+# 1. Copy ignored env files
+for f in .env .env.local .env.development.local; do
+  if [[ -f "$SOURCE_PATH/$f" && ! -f "$WORKTREE_PATH/$f" ]]; then
+    cp "$SOURCE_PATH/$f" "$WORKTREE_PATH/$f"
+    echo "copied $f"
+  fi
+done
+
+# 2. Install dependencies
+if   [[ -f pnpm-lock.yaml ]]; then pnpm install
+elif [[ -f bun.lock || -f bun.lockb ]]; then bun install
+elif [[ -f yarn.lock ]]; then yarn install
+elif [[ -f package-lock.json ]]; then npm install
+fi
+
+# 3. Worktree-isolated database
+worktree_slug=$(basename "$WORKTREE_PATH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')
+db_name="myapp_${worktree_slug}"
+
+if [[ -f .env ]]; then
+  if grep -qE '^DATABASE_URL=' .env; then
+    if [[ "${MYAPP_RESET_DB:-0}" == "1" ]] && command -v dropdb >/dev/null 2>&1; then
+      dropdb --if-exists -d postgres "$db_name" || true
+    fi
+    if command -v createdb >/dev/null 2>&1; then
+      createdb -d postgres "$db_name" 2>/dev/null || true
+    fi
+    # Rewrite only the DB name in DATABASE_URL
+    sed -i.bak -E "s|(DATABASE_URL=postgres://[^/]+)/[^?\"']+|\1/${db_name}|" .env && rm -f .env.bak
+    echo "DB set to $db_name"
+  fi
+fi
+
+# 4. Codegen
+if [[ -f prisma/schema.prisma ]]; then
+  pnpm prisma generate
+fi
+
+echo "worktree ready"

package/agents-config/skills/environments-manager/references/claude.md

@@ -0,0 +1,156 @@
+# Claude Code Linking
+
+Wire the shared `scripts/worktree-up.sh` and `scripts/worktree-down.sh` into Claude Code's native worktree system.
+
+## What Claude Code Actually Provides
+
+Claude Code DOES have native worktree support. It is fired on real worktree creation, not on every session.
+
+| Mechanism | What it does |
+| :--- | :--- |
+| `claude --worktree <name>` (or `-w`) | Creates worktree at `.claude/worktrees/<name>/` on branch `worktree-<name>` |
+| `.worktreeinclude` file (gitignore syntax) | Auto-copies matching **gitignored** files (e.g. `.env`, `.env.local`) into every new worktree - **no scripting required** |
+| `WorktreeCreate` hook | Runs ONCE when a worktree is created. **Replaces the default `git worktree add` behavior** - the hook script must call `git worktree add` itself and print the worktree path to stdout |
+| `WorktreeRemove` hook | Runs when a worktree is being deleted. Receives `worktree_path` on stdin |
+| `$CLAUDE_PROJECT_DIR` | Path to the source repo root inside hook scripts |
+
+**Do NOT use `SessionStart` for worktree setup.** `SessionStart` fires on every new conversation in any worktree, not on worktree creation. It would rerun setup every time the user opens a session.
+
+The "run once when worktree is created" hook is `WorktreeCreate` - that is the correct mechanism.
+
+There is no separate `PostWorktreeCreate` hook (feature request #27744 is open). Because `WorktreeCreate` replaces the default git logic, the hook script must be responsible for both the `git worktree add` call AND the project setup.
+
+## Files to Generate
+
+```text
+.worktreeinclude                  # gitignore-syntax list of files to auto-copy
+.claude/
+├── settings.json                 # WorktreeCreate + WorktreeRemove hooks
+└── commands/                     # optional: per-action slash commands
+    ├── dev.md
+    ├── typecheck.md
+    ├── test.md
+    └── lint.md
+scripts/
+├── claude-worktree-create.sh     # WorktreeCreate hook wrapper
+├── claude-worktree-remove.sh     # WorktreeRemove hook wrapper
+└── (shared worktree-up.sh / worktree-down.sh / dev.sh)
+```
+
+`.gitignore` must also include `**/.claude/worktrees/`.
+
+## `.worktreeinclude`
+
+If "Copy ignored env files" was selected in Step 1, **prefer `.worktreeinclude` over the bash `cp` loop** - it's native, zero-script, and runs on every worktree path (CLI `--worktree`, subagent worktrees, desktop parallel sessions).
+
+```
+.env
+.env.local
+.env.development.local
+```
+
+Only files matching a pattern **and** gitignored are copied. Tracked files are never duplicated.
+
+## `.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/claude-worktree-create.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/claude-worktree-remove.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If the project already has a `settings.json`, **merge** the `hooks` block. Do not overwrite.
+
+## `scripts/claude-worktree-create.sh` & `claude-worktree-remove.sh`
+
+These wrappers exist because Claude's `WorktreeCreate` hook has Claude-specific responsibilities the shared `scripts/worktree-up.sh` cannot handle:
+
+1. Call `git worktree add` itself (Claude does not do it).
+2. Print the worktree path - and **only** the path - to stdout.
+3. Send progress output to a log file (and to `/dev/tty` only when available).
+
+**Do not inline the wrapper code into this doc.** The full, battle-tested wrappers live in `examples/scripts/claude-worktree-create.sh` and `claude-worktree-remove.sh`. Always start from those — they encode every gotcha listed in "Hook Robustness" below. The wrappers do these things in order:
+
+1. Read `name` from stdin JSON, compute `WORKTREE` and `BRANCH`.
+2. Create the worktree (reusing a matching branch if it exists).
+3. Open a log file at `<worktree>/.worktree-setup.log`.
+4. Source `nvm` or `fnm` and activate the worktree's `.nvmrc` (so child CLIs see the right Node).
+5. Run `scripts/worktree-up.sh` with `ROOT_WORKTREE_PATH`, `CLAUDE_WORKTREE_NAME`, and `CI=1` set, under a watchdog that hard-kills after `CLAUDE_WORKTREE_SETUP_TIMEOUT` (default 900s).
+6. Echo the worktree path on stdout — and absolutely nothing else.
+
+The remove wrapper mirrors steps 3–5 for cleanup, then runs `git worktree remove --force` + `git branch -D`.
+
+`ROOT_WORKTREE_PATH` is set so the shared `scripts/worktree-up.sh` can locate the source checkout via the existing cascade (`CODEX_SOURCE_TREE_PATH` → `ROOT_WORKTREE_PATH`).
+
+## Hook Robustness (lessons from a real project)
+
+These five fixes turn a wrapper that "works on my machine" into one that survives Claude's actual hook execution context. Every one of these came from a real bug.
+
+1. **`set -e` + `> /dev/tty` will abort the hook.** When Claude runs the hook as a child process, `/dev/tty` may exist but be non-writable, and the redirect failure under `set -e` kills the whole script before setup ever runs. Always wrap the redirect: `{ echo "$*" > /dev/tty; } 2>/dev/null || true`. Testing with `[[ -w /dev/tty ]]` is NOT enough — the perm test can pass while the open call still fails.
+
+2. **Hooks inherit the shell default Node, not the worktree's `.nvmrc`.** If the project's CLI tools require a newer Node (Convex needs 24+; older Node crashes on regex `v` flag), the hook will instantly die. Source `~/.nvm/nvm.sh` or run `fnm env` at the top of the wrapper, then `nvm use` inside the worktree.
+
+3. **Always log to a file.** A hook that crashes silently is impossible to debug from the UI. Open `<worktree>/.worktree-setup.log` early, append every step. The user can `tail -f` it during the next attempt.
+
+4. **Add a watchdog timeout — macOS has no `timeout` command.** Background the setup, background a sleep+kill, `wait` on the setup. Without a watchdog, a single interactive CLI prompt (convex, prisma, vercel) can hang the hook forever — which is what users see as "the script is infinite."
+
+5. **Set `CI=1` before calling the setup script.** Many CLIs read `CI` and switch to non-interactive mode (skip prompts, suppress spinners). It's the cheapest insurance against interactive hangs.
+
+## Common Misconception: Agent Worktrees
+
+The `WorktreeCreate` hook **only fires for `claude --worktree` from the CLI**. The Agent tool's `isolation: "worktree"` feature, and parallel-session worktrees created via the desktop app, create worktrees at `~/Developer/worktrees/<repo>/<name>/` on branch `claude/<name>` — those do **not** trigger this hook. If you need setup there, the user must run `scripts/worktree-up.sh` inside the agent worktree manually (or wire a different mechanism).
+
+Also: **`.claude/settings.json` changes only take effect after restarting Claude.** A running session keeps the old hook config. Tell the user to restart before testing.
+
+## Custom Slash Commands as Actions (optional)
+
+Claude Code does not have a top-bar action menu. To expose the standard actions, write one file per action under `.claude/commands/`. Each is a tiny prompt that tells Claude to run the matching shared script or package-manager command.
+
+See `examples/claude/commands/` for the four standard ones (`dev.md`, `typecheck.md`, `test.md`, `lint.md`).
+
+## Guardrails
+
+- **Never use `SessionStart` for one-time worktree setup** - it fires every session. Use `WorktreeCreate`.
+- **Never let `git worktree add` write to stdout** in the `WorktreeCreate` hook - redirect with `>/dev/null 2>&1`. Anything on stdout besides the path breaks Claude's parser.
+- **Read stdin once** with `INPUT=$(cat)` - stdin cannot be re-read.
+- **Always merge** into the existing `.claude/settings.json`, never overwrite.
+- The hook must live in `.claude/settings.json`, not `.claude/settings.local.json` - it must be checked in.
+- Prefer `.worktreeinclude` over a bash `cp` loop for env files. Use the `cp` loop only when you need conditional or non-gitignored copies.
+- Add `**/.claude/worktrees/` to `.gitignore` so worktree contents do not pollute the main repo's `git status`.
+
+## Verification
+
+```bash
+python3 -c "import json; json.load(open('.claude/settings.json'))"
+bash -n scripts/claude-worktree-create.sh scripts/claude-worktree-remove.sh
+test -x scripts/claude-worktree-create.sh scripts/claude-worktree-remove.sh
+grep -q '.claude/worktrees' .gitignore || echo "ADD: **/.claude/worktrees/ to .gitignore"
+```
+
+## Online References
+
+- Run parallel sessions with worktrees: https://code.claude.com/docs/en/worktrees
+- Hooks reference (WorktreeCreate, WorktreeRemove): https://code.claude.com/docs/en/hooks
+- Community reference implementation: https://github.com/tfriedel/claude-worktree-hooks
+- Open feature request for PostWorktreeCreate: https://github.com/anthropics/claude-code/issues/27744

package/agents-config/skills/environments-manager/references/codex.md

@@ -0,0 +1,97 @@
+# Codex Linking
+
+Wire the shared `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh` into Codex App Local Environments.
+
+## What Codex Provides
+
+Codex has the richest native model of the three IDEs:
+
+1. **`.codex/environments/environment.toml`** - shareable config for setup, cleanup, and actions.
+2. **`[setup] script`** - runs when Codex creates a new worktree for a new thread.
+3. **`[cleanup] script`** - runs before Codex cleans up the worktree.
+4. **`[[actions]]`** - top-bar buttons that run in the integrated terminal.
+
+Worktrees only contain checked-in files, so ignored files like `.env` must be copied or recreated by setup.
+
+## Environment Variables
+
+| Variable | Meaning |
+| :--- | :--- |
+| `$CODEX_WORKTREE_PATH` | The new worktree path |
+| `$CODEX_SOURCE_TREE_PATH` | The original project checkout |
+
+## Files to Generate
+
+```text
+.codex/
+└── environments/
+    └── environment.toml
+```
+
+The TOML file is small - it only points at the shared scripts and lists the actions.
+
+## `.codex/environments/environment.toml`
+
+```toml
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY.
+version = 1
+name = "Project Worktree"
+
+[setup]
+script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-up.sh"
+
+[cleanup]
+script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-down.sh"
+
+[[actions]]
+name = "Dev"
+icon = "tool"
+command = "scripts/dev.sh"
+
+[[actions]]
+name = "Typecheck"
+icon = "tool"
+command = "pnpm ts"
+
+[[actions]]
+name = "Unit tests"
+icon = "tool"
+command = "pnpm test:ci"
+
+[[actions]]
+name = "Lint"
+icon = "tool"
+command = "pnpm lint:ci"
+```
+
+Adjust the action commands for the project's package manager (e.g. `bun run typecheck`).
+
+## Guardrails
+
+- Do not put large fragile shell programs directly in the TOML string. The TOML keeps two lines max - `cd` then call the script.
+- Do not read or write `.conductor` directories.
+- Do not create duplicate environments when the user already has one. Update the existing `.codex/environments/environment.toml`.
+- Do not hardcode a dev port in the Dev action - call `scripts/dev.sh`, which finds a free port.
+- Do not commit `.codex` only on a worktree - it must live on the source checkout / main branch so future worktrees pick it up.
+
+## Verification
+
+```bash
+sed -n '1,120p' .codex/environments/environment.toml
+```
+
+If Python 3.11+ is available:
+
+```bash
+python3 - <<'PY'
+import tomllib
+with open(".codex/environments/environment.toml", "rb") as f:
+    tomllib.load(f)
+PY
+```
+
+## Online References
+
+- OpenAI Codex Local Environments: https://developers.openai.com/codex/app/local-environments
+- OpenAI Codex Worktrees: https://developers.openai.com/codex/app/worktrees
+- `CODEX_SOURCE_TREE_PATH` / `CODEX_WORKTREE_PATH` note: https://zenn.dev/route06/articles/c1f686b4479957

package/agents-config/skills/environments-manager/references/cursor.md

@@ -0,0 +1,88 @@
+# Cursor Linking
+
+Wire the shared `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh` into Cursor.
+
+## What Cursor Provides
+
+Cursor has native worktree support via `.cursor/worktrees.json`. The file is searched first in the worktree, then in the project root.
+
+Three setup keys are supported (Cursor picks the first one that matches the host OS):
+
+- `setup-worktree-unix` - macOS/Linux (string filepath or array of commands)
+- `setup-worktree-windows` - Windows (string filepath or array of commands)
+- `setup-worktree` - generic fallback
+
+Cursor does **not** support a cleanup script. Cleanup is timer-based via global settings (`cursor.worktreeCleanupIntervalHours`, `cursor.worktreeMaxCount`). To get a real cleanup hook, expose `scripts/worktree-down.sh` as a project command the user runs manually before `/delete-worktree`.
+
+Built-in worktree slash commands the user already has: `/worktree`, `/best-of-n`, `/apply-worktree`, `/delete-worktree`.
+
+## Environment Variables
+
+Only one variable is documented:
+
+- `$ROOT_WORKTREE_PATH` - absolute path to the root of the original checkout
+- (On Windows: `%ROOT_WORKTREE_PATH%`)
+
+The worktree path itself is just `pwd` inside the worktree.
+
+## Files to Generate
+
+```text
+.cursor/
+└── worktrees.json
+```
+
+That is it. No actions menu, no per-IDE command files - Cursor wires the setup script and stops.
+
+## `.cursor/worktrees.json`
+
+Preferred shape: point Cursor at the script files. Keep arrays only as a last resort.
+
+```json
+{
+  "setup-worktree-unix": "../scripts/worktree-up.sh"
+}
+```
+
+The path is relative to the location of `.cursor/worktrees.json`. From `.cursor/worktrees.json` at the project root, `scripts/worktree-up.sh` is at `../scripts/worktree-up.sh`.
+
+If the project also needs Windows support, add the second key:
+
+```json
+{
+  "setup-worktree-unix": "../scripts/worktree-up.sh",
+  "setup-worktree-windows": "../scripts/worktree-up.ps1"
+}
+```
+
+If the user does not want a separate script and prefers inline commands:
+
+```json
+{
+  "setup-worktree": [
+    "cp $ROOT_WORKTREE_PATH/.env .env",
+    "pnpm install"
+  ]
+}
+```
+
+Inline is fine for two-line setups. For anything more, use a script - the worktree-up logic from the parent skill belongs in `scripts/worktree-up.sh`, not in JSON.
+
+## Guardrails
+
+- Do not put fragile multi-line setup inline. If it does not fit in two clean array entries, call the script.
+- Do not put `.cursor/worktrees.json` only in a worktree - it must be on the source checkout / main branch so future worktrees pick it up.
+- Do not rely on a cleanup hook - Cursor does not have one. Tell the user to run `scripts/worktree-down.sh` before `/delete-worktree`, or document it in the project README.
+- Do not use `$CURSOR_WORKTREE_PATH` - that variable is not documented and not guaranteed. Use `pwd` inside the worktree.
+
+## Verification
+
+```bash
+python3 -c "import json; json.load(open('.cursor/worktrees.json'))"
+test -x scripts/worktree-up.sh
+```
+
+## Online References
+
+- Cursor Worktrees docs: https://cursor.com/docs/configuration/worktrees
+- Cursor 3 worktrees release notes: https://forum.cursor.com/t/cursor-3-worktrees-best-of-n

package/agents-config/skills/fix-pr-comments/SKILL.md

@@ -2,6 +2,8 @@
 name: fix-pr-comments
 description: Fetch PR review comments and implement all requested changes
 allowed-tools: Bash(gh :*), Bash(git :*), Read, Edit, MultiEdit
+disable-model-invocation: true
+allow_implicit_invocation: false
 ---
 
 # Fix PR Comments

package/agents-config/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/agents-config/skills/merge/SKILL.md

@@ -3,6 +3,8 @@ name: merge
 description: Intelligently merge branches with context-aware conflict resolution
 allowed-tools: Bash(git :*), Bash(gh :*), Read, Edit, MultiEdit, Task
 argument-hint: <branch-name>
+disable-model-invocation: true
+allow_implicit_invocation: false
 ---
 
 # Merge