Extension scripts need an absolute project root for reliable path resolution

[rhuss]

Problem

Extension commands that invoke helper scripts need a reliable absolute path to those scripts at runtime. The project-relative paths that rewrite_project_relative_paths() produces (e.g., .specify/extensions/spex/scripts/foo.sh) only work when the agent's working directory is the project root. In practice, CWD shifts during a session and the relative paths break.

The most common scenario where this happens is git worktrees. When an agent creates a worktree for isolated feature development, the working directory changes to the worktree root, which is a different filesystem location from the main repo. Subagent spawning can also reset CWD, as can explicit cd commands in multi-step workflows. Any of these cause a relative script path to resolve against the wrong directory.

What we're doing today

In our extension (cc-spex), we currently work around this by using the Claude Code plugin system. Our scripts live in the plugin cache directory (~/.claude/plugins/cache/spex-plugin/spex/5.8.0/scripts/), and a context hook injects the absolute plugin root path into every prompt. Commands reference scripts as <PLUGIN_ROOT>/scripts/foo.sh, which always resolves correctly regardless of CWD.

This works, but it's entirely Claude Code-specific. The plugin cache, the context hook, the <plugin-root> injection are all Claude Code infrastructure. None of it exists on other agents, so the approach doesn't generalize.

The git rev-parse workaround

The agent-agnostic fallback is:

REPO_ROOT=$(git rev-parse --show-toplevel)
"$REPO_ROOT/.specify/extensions/spex/scripts/foo.sh"

This works from any CWD within the repo, including worktrees (--show-toplevel returns the worktree root, not the main repo root). But it requires a git invocation every time a command references a script, and it assumes the project is a git repository.

Proposal

A __PROJECT_ROOT__ template variable, resolved at install time to the absolute project path, would solve this cleanly. It fits the existing pattern of __AGENT__ and __SPECKIT_COMMAND_*__ substitutions in the template pipeline, and it would give extension authors a reliable way to reference their own scripts from any working directory.

Commands would reference scripts as:

__PROJECT_ROOT__/.specify/extensions/spex/scripts/foo.sh

This stays materialized (the absolute path is baked into the installed command file), project-local, and agent-agnostic.

One tradeoff: the resolved path becomes stale if the project directory moves. But that's the same tradeoff __AGENT__ already makes (agent name is baked in at install time), and specify init --refresh would re-resolve it.

Related: #3303 (extension portability discussion, where the maintainer suggested using extension-local paths for script discovery).

[mnriem]

I have triggered a bug-assess agentic workflow for it to asses it. Note I did this so it can surface affected code paths and changes that have gone in against what your problem statement is

[github-actions]

Bug assessment — extension-scripts-absolute-path: Valid · severity medium

---

Bug Assessment: Extension Scripts Need Absolute Project Root for Reliable Path Resolution

• Slug: extension-scripts-absolute-path
• Created: 2026-07-02T15:26:15Z
• Source: issue Extension scripts need an absolute project root for reliable path resolution #3308
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @rhuss. Extension commands that invoke helper scripts are installed with project-relative paths (e.g. .specify/extensions/spex/scripts/foo.sh). These paths only resolve correctly when the agent's CWD is the project root. In practice, CWD shifts during a session in three common scenarios: git worktrees (agent creates an isolated branch worktree at a different filesystem path), subagent spawning (some agents reset CWD when spawning child agents), and explicit cd commands in multi-step workflows. When any of these occur the relative script path resolves against the wrong directory and the script invocation fails.

The reporter notes a Claude Code–specific workaround (plugin cache + injected __PLUGIN_ROOT__ context) and a general-purpose workaround (git rev-parse --show-toplevel), but neither is built into Spec Kit and neither is agent-agnostic. The proposed fix is a __PROJECT_ROOT__ template variable resolved to an absolute path at install time, following the existing __AGENT__ substitution pattern.

Symptom

Extension commands that invoke scripts (e.g. .specify/extensions/spex/scripts/foo.sh) fail with a "file not found" or "no such file or directory" error when the agent's working directory is not the project root. The expected behaviour is that script references in installed command files resolve correctly regardless of CWD.

Reproduction

1. Install Spec Kit in a project at /home/user/myproject/.
2. Install an extension that references a helper script (e.g. .specify/extensions/spex/scripts/foo.sh in the installed command body).
3. From the project root, run the command → succeeds.
4. Create a git worktree: git worktree add ../myproject-feature feature-branch → worktree root is /home/user/myproject-feature/.
5. Run the same command from the worktree root → fails because .specify/extensions/spex/scripts/foo.sh resolves to /home/user/myproject-feature/.specify/extensions/spex/scripts/foo.sh which does not exist.

[NEEDS CLARIFICATION: exact error message and agent name under which the reporter tested; the above steps are reconstructed from the report.]

Suspected Code Paths

• src/specify_cli/agents.py:174–197 — CommandRegistrar.rewrite_project_relative_paths(). This static method rewrites scripts/, memory/, and templates/ references to .specify/scripts/, .specify/memory/, .specify/templates/ etc. but deliberately leaves extension-local paths (".specify/extensions/<ext>/scripts/...") intact (see comment at line 187). The result is always a relative path — there is no mechanism to emit absolute paths.
• src/specify_cli/integrations/base.py:583–682 — IntegrationBase.process_template(). The template pipeline has 8 steps. Step 5 (line 670) substitutes __AGENT__ with the agent name (baked in at install time). Step 6 (line 677) calls rewrite_project_relative_paths(). There is no step that substitutes a __PROJECT_ROOT__ variable despite project_root: Path | None being a parameter of the function (used only for Python interpreter resolution, lines 628–634).
• src/specify_cli/integrations/base.py:837–842 — MarkdownIntegration.setup() calls process_template() passing project_root=project_root, so the absolute path is available at call time but never used to expand a placeholder.
• src/specify_cli/integrations/copilot/__init__.py:371 — Copilot's process_template call follows the same pattern.
• extensions/git/commands/speckit.git.feature.md:47–50 — The bundled Git extension already uses the relative pattern (.specify/extensions/git/scripts/bash/...) confirming this is the established installed form.

Root Cause Hypothesis

The template pipeline in process_template() provides install-time substitution for agent identity (__AGENT__) and command invocations (__SPECKIT_COMMAND_*__), but has no install-time substitution for the project root. The project_root value is present at template-processing time (passed as a parameter) but is never injected into the command content as an absolute-path literal. Without this, extension authors have no standard way to produce CWD-independent script references. Confidence: high — the gap is directly visible in the code; the claim requires no speculation about runtime behaviour.

Proposed Remediation

Preferred: Add __PROJECT_ROOT__ as a recognized install-time template variable. In process_template() (src/specify_cli/integrations/base.py), insert a new substitution step immediately after the __AGENT__ replacement (current step 5):

# 5b. Replace __PROJECT_ROOT__
if project_root is not None:
    content = content.replace("__PROJECT_ROOT__", str(project_root.resolve()))

When project_root is None (unusual; only used in unit tests that exercise the function without a project) the placeholder is left untouched so template authors get a visible signal rather than a silent empty string.

Extension command templates can then write:

__PROJECT_ROOT__/.specify/extensions/spex/scripts/foo.sh

which is baked into the installed command file as an absolute path at specify init / specify extension install time, working from any CWD.

This is the same pattern as __AGENT__: the value is resolved once at install time and embedded literally. The known trade-off — stale paths if the project directory moves — already applies to __AGENT__ and is mitigated by specify init --refresh.

Alternatives:

• git rev-parse instruction in docs only: Document the workaround. Zero code change. Does not help extension authors building agent-agnostic extensions; leaves the gap open indefinitely.
• Runtime resolution via injected context: Have the CLI inject an environment variable or frontmatter field that the agent reads at runtime. More complex (requires agent cooperation), not universally supported.

Files likely to change:

• src/specify_cli/integrations/base.py — process_template(): add the __PROJECT_ROOT__ substitution step.
• tests/integrations/test_base.py — add test cases for __PROJECT_ROOT__ substitution (with and without project_root=None).
• AGENTS.md (docs) — add __PROJECT_ROOT__ to the "Argument Patterns / Special Processing" section.

Tests to add or update:

• test_process_template_resolves_project_root — verify __PROJECT_ROOT__ is replaced with the absolute resolved path when project_root is supplied.
• test_process_template_leaves_project_root_when_no_root — verify __PROJECT_ROOT__ is left intact when project_root=None.
• Check that existing rewrite_project_relative_paths tests remain unaffected (no interaction).

Risks & Considerations

• Absolute paths baked in: Installed command files will contain the absolute path of the project at install time. If the project directory is renamed or moved, references break until specify init --refresh is run. This is the same risk accepted for __AGENT__. Document clearly.
• No impact on existing commands: The change is additive. Templates that do not use __PROJECT_ROOT__ are unaffected. rewrite_project_relative_paths() is not modified.
• Windows paths: Path.resolve() returns backslash-separated paths on Windows. Extension authors should be aware; shell scripts may need quoting. The Python interpreter resolution code in process_template already deals with the same concern (line 632–633: quotes interpreter path if it contains whitespace).
• No security concern: The value injected is str(project_root.resolve()), derived from the CLI's own working directory at install time, not from user-supplied input in the template body.

Open Questions

• [NEEDS CLARIFICATION: Should __PROJECT_ROOT__ be left as-is or replaced with empty string / raise a warning when project_root is None? The "leave as-is" approach is safest for test coverage visibility.]
• [NEEDS CLARIFICATION: Should the bundled Git extension's commands be updated to use __PROJECT_ROOT__ as an example, or is that a separate follow-up?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🐛 Assess Bug from Labeled Issue for issue #3308 · 223.7 AIC · ⌖ 24.9 AIC · ⊞ 31.8K · ◷

[rhuss]

Thanks! If this all make sense, I can give it also a try. I wouldn't update the existing extensions, just adding the feature itself. As assessed, its fully additive and backwards compatible, so its low risk.

[mnriem]

Assessment follow-up — re-scoping against current main

Having traced this against main (HEAD bba473c), I'd like to refine the assessment. Two premises in the problem statement no longer match how Spec Kit works, and there's an existing mechanism the original write-up didn't account for.

1. Feature creation and git are already decoupled. Since #2873 (git extension made opt-in, v0.10.0), core scripts/bash/create-new-feature.sh is git-free: it resolves the repo root, creates specs/<name>/spec.md, and persists .specify/feature.json — no branch, no worktree. The opt-in git extension's speckit.git.feature.md is explicit that it does branch creation only, and its script uses git checkout -b — a branch switch, not git worktree add. So the issue's "most common scenario … the agent creates a worktree" isn't produced by any Spec Kit flow; it comes from the surrounding agent harness. In a real worktree, .specify/ is checked out at the worktree root too, so project-relative extension paths still resolve there.

2. The CWD-independence problem is already solved for in-tree scripts — without baking absolute paths. common.sh provides find_specify_root (walks upward for .specify/) and SPECIFY_INIT_DIR (explicit project-root override, #2892). Both resolve to the same value an install-time absolute path would — the absolute project root — but at runtime, so they survive a project move/rename. An extension script that sources common.sh can already do:

REPO_ROOT="$(find_specify_root)"   # or honor $SPECIFY_INIT_DIR
"$REPO_ROOT/.specify/extensions/<ext>/scripts/bash/foo.sh"

which is exactly the pattern the bundled git extension already uses.

Proposed re-scope. Keep valid, but retarget from "worktrees break relative paths" → "extension authors lack a documented CWD-independent invocation pattern; the mechanism already exists." The fix is documentation (AGENTS.md + extensions/git/README.md): the find_specify_root / SPECIFY_INIT_DIR recipe above, agent-agnostic and git-free.

Suggested severity: low–medium (documentation/DX gap, not a runtime breakage in Spec Kit's own flows).

If you have any further questions, let us know.

[rhuss]

Thanks for the thorough assessment, @mnriem. The re-scoping to "documentation/DX gap rather than runtime breakage" is fair, and the find_specify_root / SPECIFY_INIT_DIR pointer is helpful context.

One gap the documentation approach wouldn't cover: extension command templates embed script paths directly in the agent's prompt (e.g., .specify/extensions/git/scripts/bash/foo.sh in speckit.git.feature.md). The agent reads that relative path and tries to execute it from its current working directory. If CWD has shifted, the script is never found, so find_specify_root inside the script never gets a chance to run.

CWD shifts aren't limited to worktrees. Agent harnesses routinely change working directories in ways extension authors can't control or predict, for example when spawning subagents. These are implementation details of the harness, not something an extension can guard against with a runtime lookup.

There's also the worktree case to consider: when .specify/ is gitignored (which is common for brownfield projects where upstream maintainers don't want tool-specific files committed to their repo), the directory simply won't exist in a worktree. Relative paths to extension scripts break there too, and find_specify_root can't help because there's nothing to find.

find_specify_root solves path resolution for scripts that are already executing. The template path problem is one layer up: how does the agent locate the script entry point in the first place?

That's the use case where a resolved __PROJECT_ROOT__ (or equivalent) would help extension authors. Happy to discuss alternative approaches if baking an absolute path at install time feels too rigid.

[mnriem]

Thanks @rhuss — your "one layer up" framing is correct, and I want to concede it cleanly while flagging why __PROJECT_ROOT__ specifically is the wrong lever.

Where you're right. The failure is at the entry point: the agent is handed a repo-root-relative script path in the prompt and executes it against its CWD. If CWD has shifted, the shell errors before the script runs, so nothing inside it (find_specify_root, SPECIFY_INIT_DIR) ever gets a chance. That's real.

One correction: this isn't extension-specific. Core commands emit the same relative form — {SCRIPT} in the scripts: frontmatter expands to .specify/scripts/bash/…, equally relative to repo root. The scripts: frontmatter only selects the sh/ps variant and strips the block; it does not produce an absolute path. Core "works" for exactly one reason: the harness starts the primary agent at repo root, so the relative path resolves. Once any Spec Kit script launches — core or extension — it's already CWD-independent, because it anchors off ${BASH_SOURCE[0]} (the git extension even walks up from its own SCRIPT_DIR). So the unprotected layer is shared; core /speckit.plan breaks the same way under a CWD shift. Any fix should target that shared entry-point layer, not extensions alone.

Why an install-time absolute __PROJECT_ROOT__ is the wrong fix. Three concrete problems:

1. It's incompatible with our multi-root model. A Spec Kit project is directory-scoped (nearest .specify/); a monorepo holds several, selected at runtime via SPECIFY_INIT_DIR (the project axis, feat(scripts): add SPECIFY_INIT_DIR to target a member project from the repo root #2892). An absolute path baked once at init time hard-pins a command to a single member and can't be redirected — it collapses the runtime project axis into a compile-time constant, reintroducing the single-root assumption find_specify_root/SPECIFY_INIT_DIR were built to remove.

2. It resolves the wrong tree in the very worktree case that motivates this. Baked at install, __PROJECT_ROOT__ points at the original checkout. In a worktree the launched script's get_repo_root/cd would then operate on the original tree, not the worktree the agent is in — silent, and worse than a "file not found".

3. It breaks the naming convention. Project-root resolution already lives in the runtime SPECIFY_* namespace (it is SPECIFY_INIT_DIR). Introducing a bare, install-time __PROJECT_ROOT__ mints a new, differently-timed token for a concept the project already resolves at runtime — the opposite direction from where our naming should be consolidating.

Suggested direction. Keep the fix runtime-resolved and multi-root-aware in the SPECIFY_* family rather than baking an absolute path. If the gap worth closing is "help the agent locate the entry-point script before any script runs," let's scope that explicitly — e.g. a documented, agent-agnostic launcher/resolution step that honors SPECIFY_INIT_DIR + nearest-.specify/ — so it survives monorepos, worktrees, and project moves. Happy to spec that out.

[rhuss]

Ok, let me try to get this back on the human level :-). I think your biggest pushback is based on the assumption that skills generated via specify init are committed to the repository and hence should not contain any absolute pathes (fully agreed). But what if those files are treated are as emphereal artifacts and neved comitted ?

Like with my standard .gitignore like

# spex: generated/local files (only constitution is committed)
**/.claude/
**/.specify/**
!**/.specify/memory/
!**/.specify/memory/constitution.md

In this case, absolute path names are fully working, as those files are specific to their installation anyway.

Maybe back to my use case and the trouble that I had with relative paths (quoting an agent summary):

My extension (cc-spex) has commands that invoke helper scripts at runtime. For example, ship calls spex-flow-state.sh, triage calls sanitize-gh-json.py, detach calls spex-detach.sh. Currently, these commands resolve script paths via a $PLUGIN_ROOT variable extracted from a <plugin-root> tag that Claude Code injects into the system prompt, pointing to the plugin cache (e.g., /Users/rhuss/.claude/plugins/cache/spex-plugin-development/spex/5.8.0/scripts/). This gives me absolute paths but is entirely Claude Code-specific.

When I try to replace $PLUGIN_ROOT with relative .specify/extensions/spex/scripts/... paths to become harness-agnostic, I expect breakage in two scenarios:

1. Monorepo member projects: If cc-spex is installed into apps/web/.specify/, but the agent's CWD is the git root, the relative path .specify/extensions/spex/scripts/foo.sh resolves against the git root where no .specify/ exists.

2. Subagent CWD inheritance: Different harnesses handle working directories differently when spawning subagents. If a subagent's CWD doesn't match the project root, relative script paths fail before the script has a chance to self-resolve.

I will try to find out what very concretely broke with my use case when I switch from a $PLUGIN_ROOT concept (that is Claude Code specific) to using relative paths with my workflow and monorepo setups.

I will try to find out what very concretely broke with my use case when I switch from a $PLUGIN_ROOT concept (that is Claude Code specific) to using relatives path with my workflow and monorepo setups.

In the meantime I will close this issue, but maybe something like this compromise would make sense:

That said, if committed skill files are a hard requirement, a possible compromise: a specify project root subcommand (trivially wrapping the existing find_project_root() with SPECIFY_INIT_DIR support) that process_template() / rewrite_project_relative_paths() uses as a prefix when emitting script paths. The installed command would contain:

$(specify project root)/.specify/extensions/spex/scripts/foo.sh

This is runtime-resolved (not baked), multi-root aware (honors SPECIFY_INIT_DIR and .specify/ walk-up), safe to commit (evaluates on each developer's machine), worktree-safe (resolves to the current tree), and stays in the specify namespace. Two small changes that compose: the subcommand + the path rewriting in process_template().

This would not include absolute paths during installation time, but always resolve the project root during runtime, on expense of an extra shell call.