Repository navigation
How to reference sibling files from a workflow's source directory? #3445
Description
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?
Activity
mnriem commentedon Jul 10, 2026
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_pathis captured when a workflow is loaded from a file (engine.py), but it's never propagated intoStepContext, so steps can't see it.expressions.py) only exposesinputs,steps,item,fan_in, andcontext.run_id— no source path (and not evenproject_root).cwd = project_rootand receive noSPECKIT_WORKFLOW_DIR-style env var.So your
SPEX_SOURCE=... specify workflow run ~/.../setup.ymlworkaround is genuinely the most reliable option today for the local-file case, and yourlocate-sourcefallback 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:
{{ context.workflow_dir }}and/or aSPECKIT_WORKFLOW_DIRenv var for shell steps..specify/workflows/runs/<run_id>/workflow.yml, so the path there differs from the original; andsource_pathisNonefor 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 commentedon Jul 11, 2026
Thanks! Created the feature issue and started working on a PR.