How to reference sibling files from a workflow's source directory?

[rhuss]

Context

Following the discussion in #3308, I moved away from the __PROJECT_ROOT__ approach and switched to a workflow-based setup, which @mnriem pointed me toward. That was good advice, thanks. The workflow approach fits my use case much better.

I did run into a limitation while developing the workflow itself that I wanted to ask about.

Use case

I'm building a setup workflow for cc-spex that handles extension installation and command adaptation in one specify workflow run call. The workflow needs to reference files that live alongside it in the same repository (extension manifests, adapter scripts, etc.).

During development, I want to test it against other repos:

cd ~/some-other-repo
specify workflow run ~/dev/cc-spex/spex/setup.yml -i "integration=claude"

The workflow file is at ~/dev/cc-spex/spex/setup.yml, and the files it needs are in ~/dev/cc-spex/spex/extensions/, ~/dev/cc-spex/spex/scripts/, etc. But inside the workflow's shell steps, there's no way to discover that path.

What I've tried

I built a locate-source step with fallbacks (env var, cwd detection, git clone), but the simplest case doesn't work: the workflow can't find its own directory. I noticed WorkflowDefinition.source_path is stored in engine.py but not exposed to steps.

The workaround is passing the path twice:

SPEX_SOURCE=~/dev/cc-spex/spex specify workflow run ~/dev/cc-spex/spex/setup.yml -i "integration=claude"

This works but feels redundant since the path is already in the command.

Question

Is there an existing way for a workflow to discover where its own YAML file lives? If not, is there a recommended pattern for workflows that need to reference sibling files?

[mnriem]

Thanks for the detailed writeup, @rhuss — and glad the workflow approach is fitting your use case better.

To answer your question directly: no, there's currently no supported way for a workflow to discover its own source directory. I traced it to confirm:

• WorkflowDefinition.source_path is captured when a workflow is loaded from a file (engine.py), but it's never propagated into StepContext, so steps can't see it.
• The template namespace (expressions.py) only exposes inputs, steps, item, fan_in, and context.run_id — no source path (and not even project_root).
• Shell steps run with cwd = project_root and receive no SPECKIT_WORKFLOW_DIR-style env var.

So your SPEX_SOURCE=... specify workflow run ~/.../setup.yml workaround is genuinely the most reliable option today for the local-file case, and your locate-source fallback step is a reasonable pattern given the gap.

This feels like a legitimate feature request rather than a bug, so it'd be great if you could file it as a dedicated feature-request issue so it can be triaged and tracked on its own. If you have the bandwidth, a PR would be very welcome too. 🙂 A likely shape:

• Expose the resolved source directory to steps, e.g. {{ context.workflow_dir }} and/or a SPECKIT_WORKFLOW_DIR env var for shell steps.
• Watch a couple of edge cases: on resume the definition is reloaded from the persisted copy under .specify/workflows/runs/<run_id>/workflow.yml, so the path there differs from the original; and source_path is None for string-loaded workflows while installed-by-ID workflows resolve to .specify/workflows/<id>/.

Happy to help review a design or PR if you go for it.

[rhuss]

Thanks! Created the feature issue and started working on a PR.