Refactor setup-process: canonical setup-worktree.sh + thin delegators#3
Refactor setup-process: canonical setup-worktree.sh + thin delegators#3robinebers wants to merge 1 commit into
Conversation
… + thin delegators Each agent config (Cursor, Codex, Conductor, Grok) now invokes the same scripts/setup-worktree.sh via a SOURCE_ROOT / WORKTREE_ROOT contract, replacing the per-agent inline copy/install logic. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit b173bf9. Configure here.
| "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done", | ||
| "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true" | ||
| ] | ||
| "setup-worktree-unix": "../scripts/setup-worktree.sh" |
There was a problem hiding this comment.
Cursor delegator never sets required env vars
High Severity
The Cursor delegator uses the string-filepath form ("../scripts/setup-worktree.sh") which provides no mechanism to set SOURCE_ROOT and WORKTREE_ROOT. The canonical script enforces these via ${SOURCE_ROOT:?...} and ${WORKTREE_ROOT:?...}, so it will immediately abort when invoked by Cursor. Cursor only exposes $ROOT_WORKTREE_PATH and cwd — neither of which is mapped to the required contract vars. The Codex and Conductor delegators correctly perform this mapping inline, but the Cursor delegator does not and cannot in the string-filepath form.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit b173bf9. Configure here.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/setup-process/SKILL.md">
<violation number="1" location="skills/setup-process/SKILL.md:21">
P2: The PR description states Grok worktree integration is "not verified in this PR," but the doc presents Grok-specific paths (`~/.grok/worktrees.db`, `GROK_WORKSPACE_ROOT`) and auto-detection behavior as established fact. This can mislead users into expecting a working Grok integration that may not exist in the claimed form. Either mark as unverified or remove until confirmed.</violation>
<violation number="2" location="skills/setup-process/SKILL.md:84">
P1: The Cursor delegator uses the string-filepath form which cannot set `SOURCE_ROOT` and `WORKTREE_ROOT` before invoking the script. The canonical `setup-worktree.sh` enforces these via `${SOURCE_ROOT:?...}` / `${WORKTREE_ROOT:?...}` and will immediately abort.
Cursor provides `$ROOT_WORKTREE_PATH` (source) and sets cwd to the new worktree, but the string-filepath form just executes the script directly — there's no way to map those into the contract vars inline.
Either switch to the array form with an inline wrapper (e.g., `["SOURCE_ROOT=$ROOT_WORKTREE_PATH WORKTREE_ROOT=$(pwd) ../scripts/setup-worktree.sh"]`) or have the script detect the Cursor environment and fall back to `ROOT_WORKTREE_PATH`/cwd when `SOURCE_ROOT`/`WORKTREE_ROOT` are unset.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done", | ||
| "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true" | ||
| ] | ||
| "setup-worktree-unix": "../scripts/setup-worktree.sh" |
There was a problem hiding this comment.
P1: The Cursor delegator uses the string-filepath form which cannot set SOURCE_ROOT and WORKTREE_ROOT before invoking the script. The canonical setup-worktree.sh enforces these via ${SOURCE_ROOT:?...} / ${WORKTREE_ROOT:?...} and will immediately abort.
Cursor provides $ROOT_WORKTREE_PATH (source) and sets cwd to the new worktree, but the string-filepath form just executes the script directly — there's no way to map those into the contract vars inline.
Either switch to the array form with an inline wrapper (e.g., ["SOURCE_ROOT=$ROOT_WORKTREE_PATH WORKTREE_ROOT=$(pwd) ../scripts/setup-worktree.sh"]) or have the script detect the Cursor environment and fall back to ROOT_WORKTREE_PATH/cwd when SOURCE_ROOT/WORKTREE_ROOT are unset.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/setup-process/SKILL.md, line 84:
<comment>The Cursor delegator uses the string-filepath form which cannot set `SOURCE_ROOT` and `WORKTREE_ROOT` before invoking the script. The canonical `setup-worktree.sh` enforces these via `${SOURCE_ROOT:?...}` / `${WORKTREE_ROOT:?...}` and will immediately abort.
Cursor provides `$ROOT_WORKTREE_PATH` (source) and sets cwd to the new worktree, but the string-filepath form just executes the script directly — there's no way to map those into the contract vars inline.
Either switch to the array form with an inline wrapper (e.g., `["SOURCE_ROOT=$ROOT_WORKTREE_PATH WORKTREE_ROOT=$(pwd) ../scripts/setup-worktree.sh"]`) or have the script detect the Cursor environment and fall back to `ROOT_WORKTREE_PATH`/cwd when `SOURCE_ROOT`/`WORKTREE_ROOT` are unset.</comment>
<file context>
@@ -15,54 +15,81 @@ Generate the right config so AI agents start in their isolated worktrees / envir
- "for d in .agents .claude .codex .cursor; do [ -d \"$ROOT_WORKTREE_PATH/$d\" ] && mkdir -p \"$d\" && rsync -a \"$ROOT_WORKTREE_PATH/$d/.\" \"$d/\"; done",
- "[ -f \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" ] && cp \"$ROOT_WORKTREE_PATH/{ENV_FILE}\" \"{ENV_FILE}\" || true"
- ]
+ "setup-worktree-unix": "../scripts/setup-worktree.sh"
}
</file context>
</details>
<a href="https://www.cubic.dev/action/fix/violation/7c0d464f-6dd4-49d9-82f9-8e40cee00c18" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://cubic.dev/buttons/fix-with-cubic-light.svg">
<img alt="Fix with Cubic" src="https://cubic.dev/buttons/fix-with-cubic-dark.svg">
</picture>
</a>
| - **Cursor:** `.cursor/worktrees.json` (string path to `scripts/setup-worktree.sh`). | ||
| - **Codex:** `.codex/environments/environment.toml` ([setup].script delegates to the sh). | ||
| - **Conductor:** `conductor.json` at root (setup script invokes the sh). | ||
| - **Grok:** `~/.grok/worktrees.db` + auto-detection of the same sh. |
There was a problem hiding this comment.
P2: The PR description states Grok worktree integration is "not verified in this PR," but the doc presents Grok-specific paths (~/.grok/worktrees.db, GROK_WORKSPACE_ROOT) and auto-detection behavior as established fact. This can mislead users into expecting a working Grok integration that may not exist in the claimed form. Either mark as unverified or remove until confirmed.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/setup-process/SKILL.md, line 21:
<comment>The PR description states Grok worktree integration is "not verified in this PR," but the doc presents Grok-specific paths (`~/.grok/worktrees.db`, `GROK_WORKSPACE_ROOT`) and auto-detection behavior as established fact. This can mislead users into expecting a working Grok integration that may not exist in the claimed form. Either mark as unverified or remove until confirmed.</comment>
<file context>
@@ -15,54 +15,81 @@ Generate the right config so AI agents start in their isolated worktrees / envir
+- **Cursor:** `.cursor/worktrees.json` (string path to `scripts/setup-worktree.sh`).
+- **Codex:** `.codex/environments/environment.toml` ([setup].script delegates to the sh).
+- **Conductor:** `conductor.json` at root (setup script invokes the sh).
+- **Grok:** `~/.grok/worktrees.db` + auto-detection of the same sh.
## The shared pattern
</file context>
| - **Grok:** `~/.grok/worktrees.db` + auto-detection of the same sh. | |
| - **Grok:** `~/.grok/worktrees.db` + auto-detection of the same sh (unverified — confirm before using). |
1 participant
Summary
setup-processskill with a single canonicalscripts/setup-worktree.sh.SOURCE_ROOT/WORKTREE_ROOTenv-var contract..grok, copy env files) and documents the contract explicitly so a delegator that forgets to set the vars fails loudly.version,name, bothDev ServerandBuild[[actions]]blocks, common icons list).Caveats / things to verify before relying on this
.cursor/worktrees.jsonaccepts a string path forsetup-worktree-unix. Not verified against official Cursor docs in this PR — confirm before using.~/.grok/worktrees.db+GROK_WORKSPACE_ROOTauto-detection. Not verified in this PR.Test plan
setup-worktree-unixagainst current Cursor docsscripts/setup-worktree.shin a real project and confirm Codex + Conductor delegators run it end-to-end🤖 Generated with Claude Code
Note
Low Risk
Documentation-only refactor that changes recommended setup patterns but no runtime code in this repo. Risk is mainly that the Cursor/Grok delegation details may be incorrect and could mislead users when configuring worktrees.
Overview
Refactors the
setup-processskill docs to standardize all agent worktree setup on a single canonicalscripts/setup-worktree.sh, with Cursor/Codex/Conductor (and Grok) reduced to thin delegators that passSOURCE_ROOT/WORKTREE_ROOT.Updates templates to remove per-agent inline copy/install snippets, adds the canonical bash script template (including
.grokconfig dir + multiple env files), and expands the Codex TOML example to include full metadata and action shortcuts.Reviewed by Cursor Bugbot for commit b173bf9. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by cubic
Replaced per-agent setup logic with a single canonical
scripts/setup-worktree.shand thin delegators soCursor,Codex,Conductor, andGrokshare identical worktree setup. Adds an explicitSOURCE_ROOT/WORKTREE_ROOTcontract and DRY examples; restores full Codex template details.Refactors
scripts/setup-worktree.sh(install deps, copy.agents/.claude/.codex/.cursor/.grok, copy env files) with fail-fastSOURCE_ROOT/WORKTREE_ROOT.Cursor(string filepath),Codex([setup].script), andConductor(scripts.setup) to invoke the script; notesGrokauto-detection.version,name, both Dev Server and Build[[actions]], common icons).Migration
scripts/setup-worktree.sh(set{INSTALL_CMD}and env-file list), thenchmod +x..cursor/worktrees.json,.codex/environments/environment.toml, andconductor.jsonto the script usingSOURCE_ROOT/WORKTREE_ROOT(see examples in the docs).Written for commit b173bf9. Summary will update on new commits.