fix: resolve {{ args.* }} placeholders in command run strings

Args placeholders in command `run` fields were never resolved before
execution, causing shlex.split to tokenize them into multiple tokens.
Now resolve_args() is called on each command's run string before
execution, matching the behavior already applied to the prompt body.

Closes #20

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/changelog.md

@@ -7,6 +7,14 @@ keywords: ralphify changelog, release history, new features, version updates, br
 
 All notable changes to ralphify are documented here.
 
+## 0.2.1 — 2026-03-21
+
+### Fixed
+
+- **`{{ args.* }}` placeholders now resolved in command `run` strings** — previously, arg placeholders were only resolved in the prompt body. Commands like `run: gh issue view {{ args.issue }}` would fail because `shlex.split` tokenized the raw placeholder into multiple arguments. Args are now resolved before command execution.
+
+---
+
 ## 0.2.0 — 2026-03-21
 
 The v2 rewrite. Ralphify is now simpler: a ralph is a directory with a `RALPH.md` file. No more `ralph.toml`, no more `.ralphify/` directory, no more `ralph init`. Everything lives in one file.

docs/how-it-works.md

@@ -37,7 +37,7 @@ Command output is captured **regardless of exit code** — a command like `pytes
 
 ### 3. Resolve placeholders
 
-Each `{{ commands.<name> }}` placeholder in the prompt body is replaced with the corresponding command's output. Placeholders for `{{ args.<name> }}` are replaced with user argument values from the CLI.
+Each `{{ commands.<name> }}` placeholder in the prompt body is replaced with the corresponding command's output. Placeholders for `{{ args.<name> }}` are replaced with user argument values from the CLI — both in the prompt body and in command `run` strings.
 
 Unmatched placeholders resolve to an empty string — you won't see raw `{{ }}` text in the assembled prompt.
 

docs/quick-reference.md

@@ -72,7 +72,7 @@ Your instructions here. Use {{ args.dir }} for user arguments.
 | Field | Type | Description |
 |---|---|---|
 | `name` | string | Identifier for `{{ commands.<name> }}` |
-| `run` | string | Shell command to execute |
+| `run` | string | Shell command to execute (supports `{{ args.<name> }}` placeholders) |
 
 ## Placeholders
 

docs/writing-prompts.md

@@ -304,7 +304,7 @@ Rules of thumb:
 
 - **Core prompt:** 20-50 lines is the sweet spot. Enough to be specific, short enough to leave room for work.
 - **Commands:** Pick the 2-3 most useful signals. Don't add commands whose output the agent doesn't need.
-- **User args:** Use `{{ args.name }}` to make ralphs reusable — pass project-specific values from the CLI instead of hardcoding them in the prompt.
+- **User args:** Use `{{ args.name }}` to make ralphs reusable — pass project-specific values from the CLI instead of hardcoding them in the prompt. Args also work in command `run` strings (e.g., `run: gh issue view {{ args.issue }}`).
 - **Command output:** Can be long. If your commands produce verbose output, consider using scripts that filter to the relevant lines.
 
 ## Next steps

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ralphify"
-version = "0.2.0"
+version = "0.2.1"
 description = "Stop stressing over not having an agent running. Ralph is always running"
 readme = "README.md"
 license = "MIT"

src/ralphify/engine.py

@@ -77,6 +77,7 @@ def _run_commands(
     commands: list[Command],
     ralph_dir: Path,
     project_root: Path,
+    user_args: dict[str, str],
 ) -> dict[str, str]:
     """Execute all commands and return a dict of name→output.
 
@@ -85,7 +86,7 @@ def _run_commands(
     """
     results: dict[str, str] = {}
     for cmd in commands:
-        run_str = cmd.run
+        run_str = resolve_args(cmd.run, user_args)
         # Determine working directory: if the command starts with ./ it's
         # relative to the ralph directory, otherwise use project root.
         if run_str.startswith(_RELATIVE_CMD_PREFIX):
@@ -195,7 +196,7 @@ def _run_iteration(
     if config.commands:
         emit(EventType.COMMANDS_STARTED, {"iteration": iteration, "count": len(config.commands)})
         command_outputs = _run_commands(
-            config.commands, config.ralph_dir, config.project_root,
+            config.commands, config.ralph_dir, config.project_root, config.args,
         )
         emit(EventType.COMMANDS_COMPLETED, {
             "iteration": iteration,

src/ralphify/skills/new-ralph/SKILL.md

@@ -96,6 +96,7 @@ A command is a name and something to run. The framework executes it, captures st
 - **Other commands run from the project root.** `run: uv run pytest` runs in the working directory where `ralph run` was invoked.
 - **Output is always captured** regardless of exit code.
 - **No shell features by default.** Commands are parsed with `shlex.split()`. For pipes, redirects, `&&` — use a script.
+- **`{{ args.<name> }}` placeholders work in `run` strings.** Example: `run: gh issue view {{ args.issue }}` resolves before execution.
 
 ### User arguments
 

tests/test_engine.py

@@ -667,7 +667,7 @@ def test_returns_name_to_output_mapping(self, mock_run_cmd, tmp_path):
         mock_run_cmd.return_value = RunResult(success=True, returncode=0, output="test output")
         commands = [Command(name="tests", run="pytest")]
 
-        result = _run_commands(commands, ralph_dir=tmp_path / "ralph", project_root=tmp_path)
+        result = _run_commands(commands, ralph_dir=tmp_path / "ralph", project_root=tmp_path, user_args={})
 
         assert result == {"tests": "test output"}
 
@@ -686,7 +686,7 @@ def per_command(**kwargs):
             Command(name="b", run="cmd-b"),
         ]
 
-        result = _run_commands(commands, ralph_dir=tmp_path / "ralph", project_root=tmp_path)
+        result = _run_commands(commands, ralph_dir=tmp_path / "ralph", project_root=tmp_path, user_args={})
 
         assert len(result) == 2
         assert result["a"] == "out-1"
@@ -698,7 +698,7 @@ def test_dotslash_uses_ralph_dir(self, mock_run_cmd, tmp_path):
         ralph_dir = tmp_path / "my-ralph"
         commands = [Command(name="local", run="./check.sh")]
 
-        _run_commands(commands, ralph_dir=ralph_dir, project_root=tmp_path)
+        _run_commands(commands, ralph_dir=ralph_dir, project_root=tmp_path, user_args={})
 
         assert mock_run_cmd.call_args.kwargs["cwd"] == ralph_dir
 
@@ -708,7 +708,7 @@ def test_regular_command_uses_project_root(self, mock_run_cmd, tmp_path):
         ralph_dir = tmp_path / "my-ralph"
         commands = [Command(name="tests", run="pytest")]
 
-        _run_commands(commands, ralph_dir=ralph_dir, project_root=tmp_path)
+        _run_commands(commands, ralph_dir=ralph_dir, project_root=tmp_path, user_args={})
 
         assert mock_run_cmd.call_args.kwargs["cwd"] == tmp_path
 
@@ -717,15 +717,35 @@ def test_timeout_passed_to_run_command(self, mock_run_cmd, tmp_path):
         mock_run_cmd.return_value = RunResult(success=True, returncode=0, output="ok")
         commands = [Command(name="slow", run="sleep 1", timeout=300)]
 
-        _run_commands(commands, ralph_dir=tmp_path, project_root=tmp_path)
+        _run_commands(commands, ralph_dir=tmp_path, project_root=tmp_path, user_args={})
 
         assert mock_run_cmd.call_args.kwargs["timeout"] == 300
 
     def test_empty_commands_returns_empty_dict(self, tmp_path):
-        result = _run_commands([], ralph_dir=tmp_path, project_root=tmp_path)
+        result = _run_commands([], ralph_dir=tmp_path, project_root=tmp_path, user_args={})
 
         assert result == {}
 
+    @patch(MOCK_RUN_COMMAND)
+    def test_resolves_args_in_command_run_string(self, mock_run_cmd, tmp_path):
+        mock_run_cmd.return_value = RunResult(success=True, returncode=0, output="issue content")
+        commands = [Command(name="issue", run="gh issue view {{ args.issue }} --json title")]
+
+        _run_commands(commands, ralph_dir=tmp_path, project_root=tmp_path, user_args={"issue": "42"})
+
+        assert mock_run_cmd.call_args.kwargs["command"] == "gh issue view 42 --json title"
+
+    @patch(MOCK_RUN_COMMAND)
+    def test_dotslash_detection_after_args_resolution(self, mock_run_cmd, tmp_path):
+        mock_run_cmd.return_value = RunResult(success=True, returncode=0, output="ok")
+        ralph_dir = tmp_path / "my-ralph"
+        commands = [Command(name="check", run="./{{ args.script }}")]
+
+        _run_commands(commands, ralph_dir=ralph_dir, project_root=tmp_path, user_args={"script": "check.sh"})
+
+        assert mock_run_cmd.call_args.kwargs["cwd"] == ralph_dir
+        assert mock_run_cmd.call_args.kwargs["command"] == "./check.sh"
+
 
 class TestAssemblePrompt:
     """Unit tests for _assemble_prompt — reading and resolving the prompt template."""