fix(dsl): Enable shorthand template syntax with workflow directory resolution #582

mathiusj · 2025-11-18T17:32:52Z

TL;DR

Fixed template resolution in workflows by making it aware of the workflow directory.

What changed?

Moved the template method from CogInputContext to CogInputManager to access workflow directory information
Added workflow_dir parameter to CogInputManager, ExecutionManager, and system cogs
Enhanced template path resolution to first check relative to the workflow directory before falling back to the current working directory
Added comprehensive tests for the template method to verify different resolution scenarios

How to test?

Create a workflow with templates in the prompts directory
Use the shorthand syntax to reference templates (e.g., template("my_template", { name: "Test" }))
Run the workflow from a different directory and verify templates are correctly resolved
Try with both relative and absolute paths to ensure both work as expected

Why make this change?

Previously, the template method could only resolve templates relative to the current working directory, causing issues when workflows were run from a different directory than where they were defined. This change ensures templates are properly resolved relative to the workflow's location, making workflows more portable and robust.

mathiusj · 2025-11-18T17:33:08Z

fix(dsl): Enable shorthand template syntax with workflow directory resolution #582 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

nfgrep

LGTM, would await @juniper-shopify's input though.

Maybe update/add a little DSL example that leverages this?

juniper-shopify

thanks for doing this!

A more robust priority list of search locations will be helpful, and adding the workflow dir to the WorkflowContext will reduce the size of these method signatures that are already kind of too big

juniper-shopify · 2025-12-09T21:33:24Z

lib/roast/dsl/cog_input_manager.rb

+
+      #: (String, ?Hash) -> String
+      def template(path, args = {})
+        unless File.exist?(path)


small nit: I'd prefer to use Pathname objects instead of doing manipulation on strings that represent paths. The template method itself should ideally have Pathname | String as the type of its path argument, and it should coerce both to a pathname. this just makes it easier to reason about any code in the codebase (dsl part of it at least) that deals with file paths

juniper-shopify · 2025-12-09T21:35:47Z

lib/roast/dsl/cog_input_manager.rb

      end
+
+      #: (String, ?Hash) -> String
+      def template(path, args = {})


you should actually remove this method definition from cog_input_context when you add it here. it's getting overwritten by the binding, so it works, but it will be very confusing to have a defunct implementation lying around

juniper-shopify · 2025-12-09T21:44:15Z

lib/roast/dsl/cog_input_manager.rb

+          if @workflow_dir
+            # Try relative to workflow directory
+            relative_path = @workflow_dir.join("prompts/#{path}.md.erb")
+            path = relative_path.to_s if relative_path.exist?
+          else
+            # Fallback to current working directory
+            path = "prompts/#{path}.md.erb"
+          end


this has a regression from the existing logic in that it only considers paths inside a prompts/ directory, and only paths ending with .md.erb.

I think we should implement a priority stack of places to look for a matching file, roughly like this (assume path is a Pathname that is whatever the user provided):

path if path.absolute?

@workflow_dir / path if that .exist?

@workflow_dir / "#{path}.erb" if that .exist?

@workflow_dir / "#{path}.md.erb" if that .exist?

repeat 2 - 4 for @workflow_dir / prompts

repeat 2 - 4 for Pathname.pwd

repeat 2 - 4 for Pathname.pwd / prompts

and then just use the first one that exists

juniper-shopify · 2025-12-09T21:46:37Z

lib/roast/dsl/cog_input_manager.rb

+        end
+
+        unless File.exist?(path)
+          raise CogInputContext::ContextNotFoundError, "The prompt #{path} could not be found"


template will generally be used for prompts, but not exclusively. For example, I have a workflow where I'm using template to generate some JSON files containing filter expressions for a system I want an agent to search, and then telling the agent how to run searches with those files, instead of putting the filter expressions into the prompt itself.

Suggested change

raise CogInputContext::ContextNotFoundError, "The prompt #{path} could not be found"

raise CogInputContext::ContextNotFoundError, "The file '#{path}' could not be found"

juniper-shopify · 2025-12-09T21:48:05Z

lib/roast/dsl/execution_manager.rb

      #|  WorkflowContext,
      #|  ?scope: Symbol?,
      #|  ?scope_value: untyped?,
-      #|  ?scope_index: Integer
+      #|  ?scope_index: Integer,
+      #|  ?workflow_dir: Pathname?
      #| ) -> void
      def initialize(


[Re: lines +31 to +41]

add the workflow dir to the WorkflowContext, instead of passing it through explicitly. it should also be non-nilable

See this comment inline on Graphite.

juniper-shopify · 2025-12-09T21:48:53Z

lib/roast/dsl/cog_input_manager.rb

        @cog_registry = cog_registry
        @cogs = cogs
        @workflow_context = workflow_context
+        @workflow_dir = workflow_dir


add the workflow dir to the WorkflowContext, instead of passing it through explicitly. it should also be non-nilable

juniper-shopify · 2025-12-09T21:52:45Z

sorbet/rbi/shims/lib/roast/dsl/cog_input_context.rbi

+      #: (String, ?Hash) -> String
+      def template(path, args = {}); end
+


this is a good opportunity to add some method doc for this while we're at it!

you can use the /docs:write-comments custom claude command to automatically write these for you; then you'll just have the edit them and make sure they make sense. do something like this:

add a comment on this method with some rough notes about what it does, how it works, and things you want to include in the doc. super rough. (sometimes you don't even need this, but this method has no analogue that claude can use to figure out what it does, so some explanation would be helpful)

in an interactive claude, do /docs:write-comments sorbet/rbi/shims/lib/roast/dsl/cog_input_context.rbi and it will do its thing

read what it wrote and tweak it.

check that it didn't mess up any other comments, and revert anything if it did

juniper-shopify · 2025-12-09T21:54:00Z

test/roast/dsl/cog_input_context_test.rb

+        workflow_dir = Pathname.new(@workflow_dir)
+        manager = CogInputManager.new(@cog_registry, @cogs, @workflow_context, workflow_dir)
+
+        # Change to different directory to test the fix


nit: test comments should not refer to "fixes". they should simply describe the objective behaviour being tested

juniper-shopify · 2025-12-09T21:56:10Z

test/roast/dsl/cog_input_context_test.rb

+      test "template method fails with shorthand syntax when not in correct directory and no workflow_dir" do
+        manager = CogInputManager.new(@cog_registry, @cogs, @workflow_context, nil)
+
+        # This test demonstrates the bug when workflow_dir is not provided


nit: same as above -- test comment shouldn't refer to a bug that no longer exists, just describe the expected behaviour it is testing.

(okay, to be fair, there are cases where I think it's useful to have some comments in a test case explaining the particulars of a bug. But, I'd reserve that explicitly for when the bug is very complicated and counterintuitive, and non-obvious to understand what could go wrong to someone with even medium familiarity with the component)

wip: fix bug in shorthand syntax

05372cf

mathiusj force-pushed the mathiusj/gh-545-fix-bug-shorthand-syntax branch from 4011fa5 to 05372cf Compare November 29, 2025 01:19

mathiusj marked this pull request as ready for review November 29, 2025 01:34

mathiusj requested review from dersam, juniper-shopify and nfgrep as code owners November 29, 2025 01:34

mathiusj changed the title ~~wip: fix bug in shorthand syntax~~ fix(dsl): Enable shorthand template syntax with workflow directory resolution Nov 29, 2025

nfgrep reviewed Dec 5, 2025

View reviewed changes

juniper-shopify requested changes Dec 9, 2025

View reviewed changes

	raise CogInputContext::ContextNotFoundError, "The prompt #{path} could not be found"
	raise CogInputContext::ContextNotFoundError, "The file '#{path}' could not be found"

		#: (String, ?Hash) -> String
		def template(path, args = {}); end

fix(dsl): Enable shorthand template syntax with workflow directory resolution #582

Are you sure you want to change the base?

fix(dsl): Enable shorthand template syntax with workflow directory resolution #582

Uh oh!

Conversation

mathiusj commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

What changed?

How to test?

Why make this change?

Uh oh!

mathiusj commented Nov 18, 2025

Uh oh!

nfgrep left a comment

Choose a reason for hiding this comment

Uh oh!

juniper-shopify left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mathiusj commented Nov 18, 2025 •

edited

Loading