Summary
The §1 (Plan) prompt template tells the worker to read .orchestration/briefs/{TASK}.md and .orchestration/plans/{TASK}.md by relative path, but the worker's cwd is its worktree, where .orchestration/ does not exist. setup-worktrees.sh does not create or link it.
Observed
dev-loop 1.6.0, tmux substrate, orchestrating NEWRTB-2786.
templates/session-prompt.md §(1):
You are the session for {TASK}. Treat .orchestration/briefs/{TASK}.md <task_brief> as authority ... the coordinator has ALREADY run wiki-plan and written the plan to .orchestration/plans/{TASK}.md ...
After setup-worktrees.sh feat/... <root> origin/... wt/2786-t1 wt/2786-t4:
$ ls -ld .worktrees/wt-2786-t1/.orchestration
ls: .worktrees/wt-2786-t1/.orchestration: No such file or directory
$ grep -n "orchestration\|ln -s\|symlink" scripts/setup-worktrees.sh
(no output)
.orchestration/ lives at the main repo root. The worker, whose cwd is .worktrees/wt-2786-t1, cannot resolve either relative path.
I worked around it by substituting absolute paths for the three .orchestration/... references when building the §1 prompt, and adding an explicit rule to the prompt that those are the only absolute paths and every repo file must stay relative.
Why not just symlink it into each worktree
A .orchestration -> ../../.orchestration symlink inside the worktree looks like the obvious fix, but it makes .. traversal through that link escape the worktree and land in the main repo. I have hit that before: a relative path assembled from such a link (.orchestration/../<file>) wrote into the main checkout instead of the worktree, which is the same class of contamination setup-worktrees.sh's isolation is meant to prevent. A symlink would also make it easy for a worker to reach other tasks' briefs.
Suggested fix
Any of these; the first seems cleanest:
- Substitute absolute paths in the template.
{STATUS_DIR} and {SKILL} are already absolute-path tokens in the same prompt, so add {BRIEF_PATH} / {PLAN_PATH} tokens and document them the same way. The template's own token list already establishes the convention.
- Copy
briefs/{TASK}.md and plans/{TASK}.md into the worktree (e.g. .claude/tmp/) at dispatch and reference them relatively. Costs a copy but keeps every path in the worker relative; the reviews/ files for rework rounds would need the same treatment.
- Keep relative paths but have
setup-worktrees.sh create a per-task directory containing only that task's files (not a link to the shared tree), so a worker still cannot read its peers' briefs.
Whichever is chosen, it would help to state the rule explicitly in SKILL.md: external orchestration artifacts are addressed by absolute path; repo files by relative path only. Workers otherwise have no way to tell which is which, and a worker that guesses absolute for repo files will edit the main checkout.
Environment
- dev-loop 1.6.0
- macOS (Darwin 25.5.0)
- substrate: tmux (chosen at Gate 1)
Summary
The §1 (Plan) prompt template tells the worker to read
.orchestration/briefs/{TASK}.mdand.orchestration/plans/{TASK}.mdby relative path, but the worker's cwd is its worktree, where.orchestration/does not exist.setup-worktrees.shdoes not create or link it.Observed
dev-loop 1.6.0, tmux substrate, orchestrating NEWRTB-2786.
templates/session-prompt.md§(1):After
setup-worktrees.sh feat/... <root> origin/... wt/2786-t1 wt/2786-t4:.orchestration/lives at the main repo root. The worker, whose cwd is.worktrees/wt-2786-t1, cannot resolve either relative path.I worked around it by substituting absolute paths for the three
.orchestration/...references when building the §1 prompt, and adding an explicit rule to the prompt that those are the only absolute paths and every repo file must stay relative.Why not just symlink it into each worktree
A
.orchestration -> ../../.orchestrationsymlink inside the worktree looks like the obvious fix, but it makes..traversal through that link escape the worktree and land in the main repo. I have hit that before: a relative path assembled from such a link (.orchestration/../<file>) wrote into the main checkout instead of the worktree, which is the same class of contaminationsetup-worktrees.sh's isolation is meant to prevent. A symlink would also make it easy for a worker to reach other tasks' briefs.Suggested fix
Any of these; the first seems cleanest:
{STATUS_DIR}and{SKILL}are already absolute-path tokens in the same prompt, so add{BRIEF_PATH}/{PLAN_PATH}tokens and document them the same way. The template's own token list already establishes the convention.briefs/{TASK}.mdandplans/{TASK}.mdinto the worktree (e.g..claude/tmp/) at dispatch and reference them relatively. Costs a copy but keeps every path in the worker relative; the reviews/ files for rework rounds would need the same treatment.setup-worktrees.shcreate a per-task directory containing only that task's files (not a link to the shared tree), so a worker still cannot read its peers' briefs.Whichever is chosen, it would help to state the rule explicitly in SKILL.md: external orchestration artifacts are addressed by absolute path; repo files by relative path only. Workers otherwise have no way to tell which is which, and a worker that guesses absolute for repo files will edit the main checkout.
Environment