refactor: rename prompt_file/prompt_name/prompt_dir to ralph_file/ralph_name/ralph_dir

Kasper Junge · claude · Kasper Junge · commit 7f1e3b2fbcbc · 2026-03-13T06:25:46.000+01:00
Aligns internal terminology with RALPH.md naming convention. The concept
was renamed from "prompt" to "ralph" but these fields still used the old
name. Keeps prompt_text and -p/--prompt unchanged since ad-hoc text is
not a "ralph" (a named, persistent, file-based entity).

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/api.md b/docs/api.md
@@ -16,7 +16,7 @@ from ralphify import run_loop, RunConfig, RunState
 config = RunConfig(
     command="claude",
     args=["-p", "--dangerously-skip-permissions"],
-    prompt_file="RALPH.md",
+    ralph_file="RALPH.md",
     max_iterations=3,
 )
 state = RunState(run_id="my-run")
@@ -43,9 +43,9 @@ Fields match the CLI options:
 config = RunConfig(
     command="claude",
     args=["-p", "--dangerously-skip-permissions"],
-    prompt_file="RALPH.md",
-    prompt_text=None,       # Ad-hoc prompt (overrides prompt_file)
-    prompt_name=None,       # Named ralph from .ralphify/ralphs/
+    ralph_file="RALPH.md",
+    prompt_text=None,       # Ad-hoc prompt (overrides ralph_file)
+    ralph_name=None,        # Named ralph from .ralphify/ralphs/
     max_iterations=10,
     delay=2.0,
     timeout=300,
@@ -98,7 +98,7 @@ class MyEmitter:
             print(f"  Check '{event.data['name']}' failed")
 
 
-config = RunConfig(command="claude", args=["-p"], prompt_file="RALPH.md", max_iterations=3)
+config = RunConfig(command="claude", args=["-p"], ralph_file="RALPH.md", max_iterations=3)
 state = RunState(run_id="observed-run")
 run_loop(config, state, emitter=MyEmitter())
 ```
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -44,7 +44,7 @@ Named ralphs, ralph-scoped primitives, and live agent activity streaming.
 
 - **Named ralphs** — save reusable, task-focused ralphs in `.ralphify/ralphs/<name>/RALPH.md` and switch between them with `ralph run <name>`. Create with `ralph new ralph <name>`. The `ralph` field in `ralph.toml` also accepts a ralph name.
 - **`--ralph` flag on `ralph new`** — scope checks, contexts, and instructions to a named ralph with `ralph new check <name> --ralph <ralph>`. Creates the primitive inside `.ralphify/ralphs/<ralph>/` so it only applies when running that ralph.
-- **`--prompt-file` / `-f` flag** — point `ralph run` at any prompt file by path, overriding `ralph.toml`.
+- **`--ralph-file` / `-f` flag** — point `ralph run` at any prompt file by path, overriding `ralph.toml`.
 - **Live agent activity streaming** — when the agent command is Claude Code, the engine auto-detects it and uses `--output-format stream-json` with `subprocess.Popen` for line-by-line streaming. Other agents continue to use the standard `subprocess.run()` path.
 - **Codebase migration cookbook recipe** — step-by-step guide for automating JavaScript-to-TypeScript migrations, with adaptation tips for Python 2→3, CommonJS→ESM, and more.
 - **Contributor docs** — new `docs/contributing/` section with a codebase map, replacing the old `agent_docs/` directory.
diff --git a/docs/cli.md b/docs/cli.md
@@ -96,7 +96,7 @@ ralph run --log-dir ralph_logs     # Save output to log files
 | `[RALPH_NAME]` | | none | Name of a [named ralph](primitives.md#ralphs) in `.ralphify/ralphs/` |
 | `-n` | | unlimited | Max number of iterations |
 | `--prompt` | `-p` | none | Ad-hoc prompt text. Overrides the ralph file |
-| `--prompt-file` | `-f` | none | Path to a ralph file. Overrides `ralph.toml` |
+| `--ralph-file` | `-f` | none | Path to a ralph file. Overrides `ralph.toml` |
 | `--stop-on-error` | `-s` | off | Stop loop if agent exits non-zero or times out |
 | `--delay` | `-d` | `0` | Seconds to wait between iterations |
 | `--timeout` | `-t` | none | Max seconds per iteration |
diff --git a/docs/contributing/codebase-map.md b/docs/contributing/codebase-map.md
@@ -54,7 +54,7 @@ ralph run
   │
   ├── cli.py:run() — parse options, print banner
   │   ├── Load config from ralph.toml
-  │   ├── Resolve prompt via ralphs.resolve_ralph_source() (--prompt > name > --prompt-file > toml > root)
+  │   ├── Resolve prompt via ralphs.resolve_ralph_source() (--prompt > name > --ralph-file > toml > root)
   │   └── Build RunConfig and call engine.run_loop()
   │
   └── engine.py:run_loop(config, state, emitter)
diff --git a/docs/primitives.md b/docs/primitives.md
@@ -202,7 +202,7 @@ When resolving the prompt (first match wins):
 
 1. `-p` flag — inline ad-hoc prompt text
 2. Positional argument — `ralph run <name>` looks up `.ralphify/ralphs/<name>/RALPH.md`
-3. `--prompt-file` / `-f` flag — explicit path to a prompt file
+3. `--ralph-file` / `-f` flag — explicit path to a prompt file
 4. `ralph.toml` `ralph` field — can be a name or a file path
 5. Fallback — `RALPH.md` in the project root
 
diff --git a/src/ralphify/__init__.py b/src/ralphify/__init__.py
@@ -7,7 +7,7 @@
 
     from ralphify import run_loop, RunConfig, RunState, QueueEmitter
 
-    config = RunConfig(command="claude", args=["-p"], prompt_file="RALPH.md")
+    config = RunConfig(command="claude", args=["-p"], ralph_file="RALPH.md")
     state = RunState(run_id="my-run")
     emitter = QueueEmitter()
     run_loop(config, state, emitter)
diff --git a/src/ralphify/_discovery.py b/src/ralphify/_discovery.py
@@ -118,19 +118,19 @@ def merge_by_name(global_list: list[_P], local_list: list[_P]) -> list[_P]:
 
 def discover_enabled(
     root: Path,
-    prompt_dir: Path | None,
+    ralph_dir: Path | None,
     discover: Callable[[Path], list[_P]],
     discover_local: Callable[[Path], list[_P]],
 ) -> list[_P]:
     """Discover primitives, merge local overrides (if any), and return only enabled ones.
 
     Encapsulates the three-step pattern shared by all primitive types:
-    discover globals → merge with prompt-scoped locals → filter to enabled.
+    discover globals → merge with ralph-scoped locals → filter to enabled.
 
     Used by the engine's ``_discover_enabled_primitives`` to build the
     full set of primitives for a run.
     """
     items = discover(root)
-    if prompt_dir is not None:
-        items = merge_by_name(items, discover_local(prompt_dir))
+    if ralph_dir is not None:
+        items = merge_by_name(items, discover_local(ralph_dir))
     return [item for item in items if item.enabled]
diff --git a/src/ralphify/_events.py b/src/ralphify/_events.py
@@ -48,7 +48,7 @@ class EventType(Enum):
 
     # ── Run lifecycle ───────────────────────────────────────────
     # Data: checks/contexts/instructions (int counts), max_iterations,
-    #       timeout, delay, prompt_name
+    #       timeout, delay, ralph_name
     RUN_STARTED = "run_started"
     # Data: reason ("completed" | "user_requested" | "error"),
     #       total, completed, failed, timed_out
diff --git a/src/ralphify/_run_types.py b/src/ralphify/_run_types.py
@@ -47,9 +47,9 @@ class RunConfig:
 
     command: str
     args: list[str]
-    prompt_file: str
+    ralph_file: str
     prompt_text: str | None = None
-    prompt_name: str | None = None
+    ralph_name: str | None = None
     max_iterations: int | None = None
     delay: float = 0
     timeout: float | None = None
diff --git a/src/ralphify/checks.py b/src/ralphify/checks.py
@@ -100,22 +100,22 @@ def discover_checks(root: Path = Path(".")) -> list[Check]:
     return _checks_from_entries(discover_primitives(root, "checks", CHECK_MARKER))
 
 
-def discover_checks_local(prompt_dir: Path) -> list[Check]:
-    """Scan ``prompt_dir/checks/`` for prompt-scoped checks.
+def discover_checks_local(ralph_dir: Path) -> list[Check]:
+    """Scan ``ralph_dir/checks/`` for ralph-scoped checks.
 
     Same construction logic as :func:`discover_checks` but reads from
-    a prompt directory instead of the global ``.ralphify/checks/``.
+    a ralph directory instead of the global ``.ralphify/checks/``.
     """
-    return _checks_from_entries(discover_local_primitives(prompt_dir, "checks", CHECK_MARKER))
+    return _checks_from_entries(discover_local_primitives(ralph_dir, "checks", CHECK_MARKER))
 
 
-def discover_enabled_checks(root: Path, prompt_dir: Path | None = None) -> list[Check]:
+def discover_enabled_checks(root: Path, ralph_dir: Path | None = None) -> list[Check]:
     """Discover checks, merge local overrides, and return only enabled ones.
 
     Convenience wrapper over :func:`~ralphify._discovery.discover_enabled`
     so callers don't need to wire up the discover/discover_local callables.
     """
-    return discover_enabled(root, prompt_dir, discover_checks, discover_checks_local)
+    return discover_enabled(root, ralph_dir, discover_checks, discover_checks_local)
 
 
 def run_check(check: Check, project_root: Path) -> CheckResult:
diff --git a/src/ralphify/cli.py b/src/ralphify/cli.py
@@ -280,10 +280,10 @@ def status() -> None:
 
 @app.command()
 def run(
-    prompt_name: str | None = typer.Argument(None, help="Name of a ralph in .ralphify/ralphs/."),
+    ralph_name: str | None = typer.Argument(None, help="Name of a ralph in .ralphify/ralphs/."),
     n: int | None = typer.Option(None, "-n", help="Max number of iterations. Infinite if not set."),
     prompt_text: str | None = typer.Option(None, "-p", "--prompt", help="Ad-hoc prompt text. Overrides the prompt file."),
-    prompt_file: str | None = typer.Option(None, "--prompt-file", "-f", help="Path to prompt file. Overrides ralph.toml."),
+    ralph_file: str | None = typer.Option(None, "--ralph-file", "-f", help="Path to prompt file. Overrides ralph.toml."),
     stop_on_error: bool = typer.Option(False, "--stop-on-error", "-s", help="Stop if the agent exits with non-zero."),
     delay: float = typer.Option(0, "--delay", "-d", help="Seconds to wait between iterations."),
     log_dir: str | None = typer.Option(None, "--log-dir", "-l", help="Save iteration output to log files in this directory."),
@@ -304,25 +304,25 @@ def run(
 
     # Inline text (-p/--prompt) bypasses file resolution entirely.
     if prompt_text:
-        prompt_file_path = agent.get("ralph", "RALPH.md")
-        resolved_prompt_name: str | None = None
+        ralph_file_path = agent.get("ralph", "RALPH.md")
+        resolved_ralph_name: str | None = None
     else:
-        if prompt_name and prompt_file:
-            rprint("[red]Cannot use both a ralph name and --prompt-file.[/red]")
+        if ralph_name and ralph_file:
+            rprint("[red]Cannot use both a ralph name and --ralph-file.[/red]")
             raise typer.Exit(1)
 
         try:
-            prompt_file_path, resolved_prompt_name = resolve_ralph_source(
-                prompt_name=prompt_name,
-                prompt_file=prompt_file,
+            ralph_file_path, resolved_ralph_name = resolve_ralph_source(
+                ralph_name=ralph_name,
+                ralph_file=ralph_file,
                 toml_ralph=agent.get("ralph", "RALPH.md"),
             )
         except ValueError as e:
             rprint(f"[red]{e}[/red]")
             raise typer.Exit(1)
 
-        if not Path(prompt_file_path).exists():
-            rprint(f"[red]Prompt file '{prompt_file_path}' not found.[/red]")
+        if not Path(ralph_file_path).exists():
+            rprint(f"[red]Prompt file '{ralph_file_path}' not found.[/red]")
             raise typer.Exit(1)
 
     if log_dir:
@@ -331,9 +331,9 @@ def run(
     config = RunConfig(
         command=command,
         args=args,
-        prompt_file=prompt_file_path,
+        ralph_file=ralph_file_path,
         prompt_text=prompt_text,
-        prompt_name=resolved_prompt_name,
+        ralph_name=resolved_ralph_name,
         max_iterations=n,
         delay=delay,
         timeout=timeout,
diff --git a/src/ralphify/contexts.py b/src/ralphify/contexts.py
@@ -73,22 +73,22 @@ def discover_contexts(root: Path = Path(".")) -> list[Context]:
     return [_context_from_entry(prim) for prim in discover_primitives(root, "contexts", CONTEXT_MARKER)]
 
 
-def discover_contexts_local(prompt_dir: Path) -> list[Context]:
-    """Scan ``prompt_dir/contexts/`` for prompt-scoped contexts.
+def discover_contexts_local(ralph_dir: Path) -> list[Context]:
+    """Scan ``ralph_dir/contexts/`` for ralph-scoped contexts.
 
     Same construction logic as :func:`discover_contexts` but reads from
-    a prompt directory instead of the global ``.ralphify/contexts/``.
+    a ralph directory instead of the global ``.ralphify/contexts/``.
     """
-    return [_context_from_entry(prim) for prim in discover_local_primitives(prompt_dir, "contexts", CONTEXT_MARKER)]
+    return [_context_from_entry(prim) for prim in discover_local_primitives(ralph_dir, "contexts", CONTEXT_MARKER)]
 
 
-def discover_enabled_contexts(root: Path, prompt_dir: Path | None = None) -> list[Context]:
+def discover_enabled_contexts(root: Path, ralph_dir: Path | None = None) -> list[Context]:
     """Discover contexts, merge local overrides, and return only enabled ones.
 
     Convenience wrapper over :func:`~ralphify._discovery.discover_enabled`
     so callers don't need to wire up the discover/discover_local callables.
     """
-    return discover_enabled(root, prompt_dir, discover_contexts, discover_contexts_local)
+    return discover_enabled(root, ralph_dir, discover_contexts, discover_contexts_local)
 
 
 def run_context(context: Context, project_root: Path) -> ContextResult:
diff --git a/src/ralphify/engine.py b/src/ralphify/engine.py
@@ -42,23 +42,23 @@ class EnabledPrimitives(NamedTuple):
     instructions: list[Instruction]
 
 
-def _resolve_prompt_dir(config: RunConfig) -> Path | None:
-    """Return the prompt directory when running a named prompt.
+def _resolve_ralph_dir(config: RunConfig) -> Path | None:
+    """Return the ralph directory when running a named ralph.
 
     Returns ``None`` for ad-hoc prompt text (``-p``), which has no
     directory to scan for local primitives.
     """
-    if config.prompt_name and not config.prompt_text:
-        return Path(config.prompt_file).parent
+    if config.ralph_name and not config.prompt_text:
+        return Path(config.ralph_file).parent
     return None
 
 
 def _discover_enabled_primitives(
-    root: Path, prompt_dir: Path | None = None,
+    root: Path, ralph_dir: Path | None = None,
 ) -> EnabledPrimitives:
     """Discover all primitives and return only the enabled ones.
 
-    When *prompt_dir* is set, prompt-scoped primitives are merged with
+    When *ralph_dir* is set, ralph-scoped primitives are merged with
     globals (local wins on name collisions).  Enabled filtering happens
     **after** the merge so a disabled local primitive can suppress a
     global one with the same name.
@@ -69,9 +69,9 @@ def _discover_enabled_primitives(
     only enabled primitives and do not re-filter.
     """
     return EnabledPrimitives(
-        checks=discover_enabled_checks(root, prompt_dir),
-        contexts=discover_enabled_contexts(root, prompt_dir),
-        instructions=discover_enabled_instructions(root, prompt_dir),
+        checks=discover_enabled_checks(root, ralph_dir),
+        contexts=discover_enabled_contexts(root, ralph_dir),
+        instructions=discover_enabled_instructions(root, ralph_dir),
     )
 
 
@@ -116,7 +116,7 @@ def _handle_loop_transitions(
     config: RunConfig,
     primitives: EnabledPrimitives,
     emit: _BoundEmitter,
-    prompt_dir: Path | None = None,
+    ralph_dir: Path | None = None,
 ) -> tuple[bool, EnabledPrimitives]:
     """Handle stop, pause, and reload transitions at the top of each iteration.
 
@@ -133,7 +133,7 @@ def _handle_loop_transitions(
             return False, primitives
 
     if state.consume_reload_request():
-        primitives = _discover_enabled_primitives(config.project_root, prompt_dir)
+        primitives = _discover_enabled_primitives(config.project_root, ralph_dir)
         emit(EventType.PRIMITIVES_RELOADED, {
             "checks": len(primitives.checks),
             "contexts": len(primitives.contexts),
@@ -159,7 +159,7 @@ def _assemble_prompt(
     if config.prompt_text:
         prompt = config.prompt_text
     else:
-        raw = Path(config.prompt_file).read_text()
+        raw = Path(config.ralph_file).read_text()
         _, prompt = parse_frontmatter(raw)
     if context_results:
         prompt = resolve_contexts(prompt, context_results)
@@ -340,8 +340,8 @@ def run_loop(
         log_path_dir.mkdir(parents=True, exist_ok=True)
 
     check_failures_text = ""
-    prompt_dir = _resolve_prompt_dir(config)
-    primitives = _discover_enabled_primitives(config.project_root, prompt_dir)
+    ralph_dir = _resolve_ralph_dir(config)
+    primitives = _discover_enabled_primitives(config.project_root, ralph_dir)
 
     emit(EventType.RUN_STARTED, {
         "checks": len(primitives.checks),
@@ -350,13 +350,13 @@ def run_loop(
         "max_iterations": config.max_iterations,
         "timeout": config.timeout,
         "delay": config.delay,
-        "prompt_name": config.prompt_name,
+        "ralph_name": config.ralph_name,
     })
 
     try:
         while True:
             should_continue, primitives = _handle_loop_transitions(
-                state, config, primitives, emit, prompt_dir,
+                state, config, primitives, emit, ralph_dir,
             )
             if not should_continue:
                 break
diff --git a/src/ralphify/instructions.py b/src/ralphify/instructions.py
@@ -47,22 +47,22 @@ def discover_instructions(root: Path = Path(".")) -> list[Instruction]:
     return [_instruction_from_entry(prim) for prim in discover_primitives(root, "instructions", INSTRUCTION_MARKER)]
 
 
-def discover_instructions_local(prompt_dir: Path) -> list[Instruction]:
-    """Scan ``prompt_dir/instructions/`` for prompt-scoped instructions.
+def discover_instructions_local(ralph_dir: Path) -> list[Instruction]:
+    """Scan ``ralph_dir/instructions/`` for ralph-scoped instructions.
 
     Same construction logic as :func:`discover_instructions` but reads from
-    a prompt directory instead of the global ``.ralphify/instructions/``.
+    a ralph directory instead of the global ``.ralphify/instructions/``.
     """
-    return [_instruction_from_entry(prim) for prim in discover_local_primitives(prompt_dir, "instructions", INSTRUCTION_MARKER)]
+    return [_instruction_from_entry(prim) for prim in discover_local_primitives(ralph_dir, "instructions", INSTRUCTION_MARKER)]
 
 
-def discover_enabled_instructions(root: Path, prompt_dir: Path | None = None) -> list[Instruction]:
+def discover_enabled_instructions(root: Path, ralph_dir: Path | None = None) -> list[Instruction]:
     """Discover instructions, merge local overrides, and return only enabled ones.
 
     Convenience wrapper over :func:`~ralphify._discovery.discover_enabled`
     so callers don't need to wire up the discover/discover_local callables.
     """
-    return discover_enabled(root, prompt_dir, discover_instructions, discover_instructions_local)
+    return discover_enabled(root, ralph_dir, discover_instructions, discover_instructions_local)
 
 
 def resolve_instructions(prompt: str, instructions: list[Instruction]) -> str:
diff --git a/src/ralphify/ralphs.py b/src/ralphify/ralphs.py
@@ -90,13 +90,13 @@ def is_ralph_name(value: str) -> bool:
 
 def resolve_ralph_source(
     *,
-    prompt_name: str | None,
-    prompt_file: str | None,
+    ralph_name: str | None,
+    ralph_file: str | None,
     toml_ralph: str,
 ) -> tuple[str, str | None]:
     """Resolve which prompt file to use, returning ``(file_path, ralph_name)``.
 
-    Priority chain: positional name > --prompt-file > ralph.toml.
+    Priority chain: positional name > --ralph-file > ralph.toml.
     The ``toml_ralph`` value from ``ralph.toml`` may be either a file path or
     a named ralph — names are tried first, falling back to a literal path.
 
@@ -105,12 +105,12 @@ def resolve_ralph_source(
 
     Raises ``ValueError`` if a named ralph lookup fails.
     """
-    if prompt_name:
-        found = resolve_ralph_name(prompt_name)
+    if ralph_name:
+        found = resolve_ralph_name(ralph_name)
         return str(found.path / RALPH_MARKER), found.name
 
-    if prompt_file:
-        return prompt_file, None
+    if ralph_file:
+        return ralph_file, None
 
     # Fall back to ralph.toml agent.ralph — could be a name or a path
     if is_ralph_name(toml_ralph):
diff --git a/tests/test_checks.py b/tests/test_checks.py
diff --git a/tests/test_cli.py b/tests/test_cli.py
diff --git a/tests/test_contexts.py b/tests/test_contexts.py
diff --git a/tests/test_discovery.py b/tests/test_discovery.py
diff --git a/tests/test_engine.py b/tests/test_engine.py
diff --git a/tests/test_instructions.py b/tests/test_instructions.py
diff --git a/tests/test_manager.py b/tests/test_manager.py
