refactor: rename context.* placeholders to ralph.*

{{ ralph.name }}, {{ ralph.iteration }}, and {{ ralph.max_iterations }}
read more naturally in RALPH.md files than the context.* prefix.

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

Author: 2 people

docs/changelog.md

@@ -12,7 +12,7 @@ All notable changes to ralphify are documented here.
 
 ### Added
 
-- **Context placeholders** — ralphs can now access runtime metadata via `{{ context.name }}` (ralph directory name), `{{ context.iteration }}` (current iteration, 1-based), and `{{ context.max_iterations }}` (total iterations if `-n` was set, empty otherwise). No frontmatter configuration needed.
+- **Ralph placeholders** — ralphs can now access runtime metadata via `{{ ralph.name }}` (ralph directory name), `{{ ralph.iteration }}` (current iteration, 1-based), and `{{ ralph.max_iterations }}` (total iterations if `-n` was set, empty otherwise). No frontmatter configuration needed.
 
 ---
 

docs/contributing/codebase-map.md

@@ -22,7 +22,7 @@ src/ralphify/           # All source code
 ├── cli.py              # CLI commands (run, new, init) — delegates to engine for the loop
 ├── engine.py           # Core run loop orchestration with structured event emission
 ├── manager.py          # Multi-run orchestration (concurrent runs via threads)
-├── _resolver.py        # Template placeholder resolution ({{ commands.* }}, {{ args.* }}, {{ context.* }})
+├── _resolver.py        # Template placeholder resolution ({{ commands.* }}, {{ args.* }}, {{ ralph.* }})
 ├── _agent.py           # Run agent subprocesses (streaming + blocking modes, log writing)
 ├── _run_types.py       # RunConfig, RunState, RunStatus, Command — shared data types
 ├── _runner.py          # Execute shell commands with timeout and capture output

docs/quick-reference.md

@@ -107,12 +107,12 @@ Your instructions here. Use {{ args.dir }} for user arguments.
 - `--` ends flag parsing: `ralph run my-ralph -- --verbose ./src` treats `--verbose` as a positional value
 - Missing args resolve to empty string
 
-### Context placeholders
+### Ralph placeholders
 
 ```markdown
-{{ context.name }}               # Ralph directory name (e.g. "my-ralph")
-{{ context.iteration }}          # Current iteration number (1-based)
-{{ context.max_iterations }}     # Total iterations if -n was set, empty otherwise
+{{ ralph.name }}               # Ralph directory name (e.g. "my-ralph")
+{{ ralph.iteration }}          # Current iteration number (1-based)
+{{ ralph.max_iterations }}     # Total iterations if -n was set, empty otherwise
 ```
 
 - Automatically available — no frontmatter configuration needed
@@ -124,7 +124,7 @@ Each iteration:
 
 1. Re-read `RALPH.md` from disk
 2. Run all commands in order, capture output
-3. Resolve `{{ commands.* }}`, `{{ args.* }}`, and `{{ context.* }}` placeholders
+3. Resolve `{{ commands.* }}`, `{{ args.* }}`, and `{{ ralph.* }}` placeholders
 4. Pipe assembled prompt to agent via stdin
 5. Wait for agent to exit
 6. Repeat

docs/writing-prompts.md

@@ -341,7 +341,7 @@ Rules of thumb:
 - **Commands:** Pick the 2-3 most useful signals. Don't add commands whose output the agent doesn't need.
 - **Command output:** Can be long. If your commands produce verbose output, consider using scripts that filter to the relevant lines.
 - **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 }}`).
-- **Context placeholders:** Use `{{ context.name }}`, `{{ context.iteration }}`, and `{{ context.max_iterations }}` to access runtime metadata — the ralph's directory name, which iteration this is, and the total number if `--n` was set.
+- **Ralph placeholders:** Use `{{ ralph.name }}`, `{{ ralph.iteration }}`, and `{{ ralph.max_iterations }}` to access runtime metadata — the ralph's directory name, which iteration this is, and the total number if `--n` was set.
 - **Working directory:** Commands run from the project root by default. Commands starting with `./` run from the ralph directory — handy for bundling helper scripts next to your `RALPH.md`.
 
 ## Next steps

src/ralphify/_frontmatter.py

@@ -25,7 +25,7 @@
 FIELD_COMMANDS = "commands"
 FIELD_ARGS = "args"
 FIELD_CREDIT = "credit"
-FIELD_CONTEXT = "context"
+FIELD_RALPH = "ralph"
 
 # Sub-field names within each command mapping.
 CMD_FIELD_NAME = "name"

src/ralphify/_resolver.py

@@ -12,7 +12,7 @@
 
 import re
 
-from ralphify._frontmatter import CMD_NAME_RE, FIELD_ARGS, FIELD_COMMANDS, FIELD_CONTEXT
+from ralphify._frontmatter import CMD_NAME_RE, FIELD_ARGS, FIELD_COMMANDS, FIELD_RALPH
 
 
 # Pattern matching ``{{ args.<name> }}`` placeholders — used by resolve_args
@@ -37,26 +37,26 @@ def _replace(match: re.Match) -> str:
 
 # Single pattern matching all placeholder kinds for single-pass resolution.
 _ALL_PATTERN = re.compile(
-    rf"\{{\{{\s*({FIELD_COMMANDS}|{FIELD_ARGS}|{FIELD_CONTEXT})\.({CMD_NAME_RE.pattern})\s*\}}\}}"
+    rf"\{{\{{\s*({FIELD_COMMANDS}|{FIELD_ARGS}|{FIELD_RALPH})\.({CMD_NAME_RE.pattern})\s*\}}\}}"
 )
 
 
 def resolve_all(
     prompt: str,
     command_outputs: dict[str, str],
     user_args: dict[str, str],
-    context: dict[str, str] | None = None,
+    ralph_context: dict[str, str] | None = None,
 ) -> str:
     """Resolve all placeholders in a single pass to prevent cross-contamination.
 
     Resolves ``{{ commands.name }}``, ``{{ args.name }}``, and
-    ``{{ context.name }}`` in a single pass so values inserted by one
+    ``{{ ralph.name }}`` in a single pass so values inserted by one
     kind of placeholder are not re-processed as the other kind.
     """
     lookups: dict[str, dict[str, str]] = {
         FIELD_COMMANDS: command_outputs,
         FIELD_ARGS: user_args,
-        FIELD_CONTEXT: context or {},
+        FIELD_RALPH: ralph_context or {},
     }
 
     def _replace(match: re.Match) -> str:

src/ralphify/engine.py

@@ -120,8 +120,8 @@ def _run_commands(
     return results
 
 
-def _build_context(config: RunConfig, state: RunState) -> dict[str, str]:
-    """Build the context dict for ``{{ context.X }}`` placeholders."""
+def _build_ralph_context(config: RunConfig, state: RunState) -> dict[str, str]:
+    """Build the context dict for ``{{ ralph.X }}`` placeholders."""
     ctx: dict[str, str] = {
         "name": config.ralph_dir.name,
         "iteration": str(state.iteration),
@@ -143,8 +143,8 @@ def _assemble_prompt(
     """
     raw = config.ralph_file.read_text(encoding="utf-8")
     _, prompt = parse_frontmatter(raw)
-    context = _build_context(config, state)
-    prompt = resolve_all(prompt, command_outputs, config.args, context)
+    ralph_context = _build_ralph_context(config, state)
+    prompt = resolve_all(prompt, command_outputs, config.args, ralph_context)
     if config.credit:
         prompt += _CREDIT_INSTRUCTION
     return prompt

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

@@ -89,7 +89,7 @@ If any tests are failing above, fix them before continuing.
 The body is the prompt. It supports three placeholder types:
 - `{{ commands.<name> }}` — replaced with command output each iteration
 - `{{ args.<name> }}` — replaced with CLI arguments
-- `{{ context.<name> }}` — replaced with runtime metadata (`name`, `iteration`, `max_iterations`)
+- `{{ ralph.<name> }}` — replaced with runtime metadata (`name`, `iteration`, `max_iterations`)
 
 HTML comments (`<!-- ... -->`) are automatically stripped before the prompt is assembled. They never reach the agent. Use them for notes about why rules exist or TODOs for prompt maintenance.
 

tests/test_engine.py

@@ -891,10 +891,10 @@ def test_arg_values_not_resolved_as_command_placeholders(self, tmp_path):
         assert "Filter: {{ commands.tests }}" in result
         assert "Tests: 5 passed" in result
 
-    def test_resolves_context_placeholders(self, tmp_path):
+    def test_resolves_ralph_placeholders(self, tmp_path):
         config = make_config(
             tmp_path,
-            "Name: {{ context.name }}, Iter: {{ context.iteration }}, Max: {{ context.max_iterations }}",
+            "Name: {{ ralph.name }}, Iter: {{ ralph.iteration }}, Max: {{ ralph.max_iterations }}",
             max_iterations=5,
             credit=False,
         )
@@ -905,10 +905,10 @@ def test_resolves_context_placeholders(self, tmp_path):
 
         assert result == "Name: my-ralph, Iter: 3, Max: 5"
 
-    def test_context_max_iterations_empty_when_unlimited(self, tmp_path):
+    def test_ralph_max_iterations_empty_when_unlimited(self, tmp_path):
         config = make_config(
             tmp_path,
-            "Max: {{ context.max_iterations }}",
+            "Max: {{ ralph.max_iterations }}",
             max_iterations=None,
             credit=False,
         )
@@ -919,10 +919,10 @@ def test_context_max_iterations_empty_when_unlimited(self, tmp_path):
 
         assert result == "Max: "
 
-    def test_context_name_is_ralph_dir_name(self, tmp_path):
+    def test_ralph_name_is_ralph_dir_name(self, tmp_path):
         config = make_config(
             tmp_path,
-            "Name: {{ context.name }}",
+            "Name: {{ ralph.name }}",
             max_iterations=1,
             credit=False,
         )

tests/test_resolver.py

@@ -154,41 +154,41 @@ def test_hyphenated_arg_name(self):
         assert result == "/tmp"
 
 
-class TestResolveContext:
-    """Tests for {{ context.X }} placeholders passed through resolve_all."""
+class TestResolveRalphContext:
+    """Tests for {{ ralph.X }} placeholders passed through resolve_all."""
 
-    def test_resolves_context_name(self):
-        result = resolve_all("Ralph: {{ context.name }}", {}, {}, {"name": "my-ralph"})
+    def test_resolves_ralph_name(self):
+        result = resolve_all("Ralph: {{ ralph.name }}", {}, {}, {"name": "my-ralph"})
         assert result == "Ralph: my-ralph"
 
-    def test_resolves_context_iteration(self):
-        result = resolve_all("Iter: {{ context.iteration }}", {}, {}, {"iteration": "3"})
+    def test_resolves_ralph_iteration(self):
+        result = resolve_all("Iter: {{ ralph.iteration }}", {}, {}, {"iteration": "3"})
         assert result == "Iter: 3"
 
-    def test_resolves_context_max_iterations(self):
+    def test_resolves_ralph_max_iterations(self):
         result = resolve_all(
-            "Max: {{ context.max_iterations }}", {}, {}, {"max_iterations": "10"},
+            "Max: {{ ralph.max_iterations }}", {}, {}, {"max_iterations": "10"},
         )
         assert result == "Max: 10"
 
-    def test_unknown_context_key_resolves_to_empty(self):
-        result = resolve_all("{{ context.unknown }}", {}, {}, {"name": "test"})
+    def test_unknown_ralph_key_resolves_to_empty(self):
+        result = resolve_all("{{ ralph.unknown }}", {}, {}, {"name": "test"})
         assert result == ""
 
-    def test_no_context_clears_placeholders(self):
-        result = resolve_all("{{ context.name }}", {}, {})
+    def test_no_ralph_context_clears_placeholders(self):
+        result = resolve_all("{{ ralph.name }}", {}, {})
         assert result == ""
 
-    def test_context_with_commands_and_args(self):
+    def test_ralph_with_commands_and_args(self):
         result = resolve_all(
-            "{{ commands.tests }} {{ args.dir }} {{ context.iteration }}",
+            "{{ commands.tests }} {{ args.dir }} {{ ralph.iteration }}",
             {"tests": "ok"}, {"dir": "./src"}, {"iteration": "2"},
         )
         assert result == "ok ./src 2"
 
-    def test_context_value_not_resolved_as_command_placeholder(self):
+    def test_ralph_value_not_resolved_as_command_placeholder(self):
         result = resolve_all(
-            "Ctx: {{ context.name }}\nCmd: {{ commands.tests }}",
+            "Ctx: {{ ralph.name }}\nCmd: {{ commands.tests }}",
             {"tests": "5 passed"},
             {},
             {"name": "{{ commands.tests }}"},
@@ -197,5 +197,5 @@ def test_context_value_not_resolved_as_command_placeholder(self):
         assert "Cmd: 5 passed" in result
 
     def test_whitespace_tolerant(self):
-        result = resolve_all("{{  context.name  }}", {}, {}, {"name": "test"})
+        result = resolve_all("{{  ralph.name  }}", {}, {}, {"name": "test"})
         assert result == "test"