feat: add prompts as a first-class primitive so users can save, switch between, and reuse task-focused prompts

- Create src/ralphify/prompts.py with discover_prompts(), resolve_prompt_name(), is_prompt_name()
- Add `ralph new prompt <name>` scaffold command
- Add `ralph prompts list` to show available prompts
- Add positional `prompt_name` arg to `ralph run` with priority chain:
  inline text > positional name > --prompt-file > ralph.toml > root PROMPT.md
- Strip frontmatter when reading prompt files in engine
- Add prompt_name to RunConfig and RUN_STARTED event
- Register prompts in UI primitives API for automatic CRUD
- Add prompt_name to RunCreate model and resolve in create_run()
- Update CLAUDE.md with prompts.py and PROMPT.md marker reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

CLAUDE.md

@@ -25,7 +25,8 @@ Key modules:
 - `cli.py` — CLI commands and the main `run()` loop
 - `_frontmatter.py` — Primitive discovery and YAML frontmatter parsing
 - `resolver.py` — Template placeholder resolution (`{{ contexts.name }}`, `{{ instructions }}`)
-- `checks.py`, `contexts.py`, `instructions.py` — The three primitive types
+- `prompts.py` — Named prompt discovery and resolution
+- `checks.py`, `contexts.py`, `instructions.py` — The other three primitive types
 
 Tests are in `tests/` with one file per module. Docs are in `docs/` using MkDocs with Material theme.
 
@@ -38,7 +39,7 @@ Tests are in `tests/` with one file per module. Docs are in `docs/` using MkDocs
 
 ## Traps
 
-- Primitive marker filenames (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`) are hardcoded in each module's `discover_*()` function AND in scaffold templates in `cli.py`. Change one → update both.
+- Primitive marker filenames (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`, `PROMPT.md`) are hardcoded in each module's `discover_*()` function AND in scaffold templates in `cli.py`. Change one → update both.
 - `timeout` and `enabled` frontmatter fields have special type coercion in `_frontmatter.py:parse_frontmatter()`. New typed fields need coercion logic added there.
 - Both contexts and instructions share `resolver.py:resolve_placeholders()`. Changes affect both.
 - Output is truncated to 5000 chars in `_output.py`. This is intentional.

src/ralphify/cli.py

@@ -20,6 +20,7 @@
 from ralphify.contexts import discover_contexts
 from ralphify.engine import RunConfig, RunState, _format_duration, run_loop
 from ralphify.instructions import discover_instructions
+from ralphify.prompts import discover_prompts, is_prompt_name, resolve_prompt_name
 from ralphify.detector import detect_project
 
 _console = Console(highlight=False)
@@ -30,6 +31,9 @@
 new_app = typer.Typer(help="Scaffold new ralph primitives.", invoke_without_command=True)
 app.add_typer(new_app, name="new")
 
+prompts_app = typer.Typer(help="Manage prompt primitives.", invoke_without_command=True)
+app.add_typer(prompts_app, name="prompts")
+
 
 @new_app.callback()
 def new_callback(ctx: typer.Context) -> None:
@@ -38,6 +42,31 @@ def new_callback(ctx: typer.Context) -> None:
         rprint(ctx.get_help())
         raise typer.Exit()
 
+
+@prompts_app.callback()
+def prompts_callback(ctx: typer.Context) -> None:
+    """Manage prompt primitives."""
+    if ctx.invoked_subcommand is None:
+        rprint(ctx.get_help())
+        raise typer.Exit()
+
+
+@prompts_app.command("list")
+def prompts_list() -> None:
+    """List available prompts."""
+    prompts = discover_prompts()
+    root_prompt = Path("PROMPT.md")
+    if not prompts and not root_prompt.exists():
+        rprint("[dim]No prompts found.[/dim]")
+        return
+    if root_prompt.exists():
+        size = len(root_prompt.read_text())
+        rprint(f"  [cyan]PROMPT.md[/cyan]  (root, {size} chars)")
+    for p in prompts:
+        icon = "[green]✓[/green]" if p.enabled else "[dim]○[/dim]"
+        desc = f"  {p.description}" if p.description else ""
+        rprint(f"  {icon} {p.name:<18}{desc}")
+
 BANNER_LINES = [
     "██████╗░░█████╗░██╗░░░░░██████╗░██╗░░██╗██╗███████╗██╗░░░██╗",
     "██╔══██╗██╔══██╗██║░░░░░██╔══██╗██║░░██║██║██╔════╝╚██╗░██╔╝",
@@ -169,6 +198,15 @@ def _load_config() -> dict:
 -->
 """
 
+PROMPT_MD_TEMPLATE = """\
+---
+description: Describe what this prompt does
+enabled: true
+---
+
+Your prompt content here.
+"""
+
 PROMPT_TEMPLATE = """\
 # Prompt
 
@@ -249,6 +287,14 @@ def context(
     _scaffold_primitive("contexts", name, "CONTEXT.md", CONTEXT_MD_TEMPLATE)
 
 
+@new_app.command()
+def prompt(
+    name: str = typer.Argument(help="Name of the new prompt."),
+) -> None:
+    """Create a new prompt. Prompts are reusable task-focused prompt files you can switch between."""
+    _scaffold_primitive("prompts", name, "PROMPT.md", PROMPT_MD_TEMPLATE)
+
+
 @app.command()
 def status() -> None:
     """Show current configuration and validate setup."""
@@ -290,6 +336,10 @@ def status() -> None:
     _print_primitives_section("Instructions", instructions,
         lambda i: (i.content[:50] + "...") if len(i.content) > 50 else i.content)
 
+    prompts = discover_prompts()
+    _print_primitives_section("Prompts", prompts,
+        lambda p: p.description or "(no description)")
+
     if issues:
         rprint("\n[red]Not ready.[/red] Fix the issues above before running.")
         raise typer.Exit(1)
@@ -381,6 +431,7 @@ def emit(self, event: Event) -> None:
 
 @app.command()
 def run(
+    prompt_name: Optional[str] = typer.Argument(None, help="Name of a prompt in .ralph/prompts/."),
     n: Optional[int] = typer.Option(None, "-n", help="Max number of iterations. Infinite if not set."),
     prompt_text: Optional[str] = typer.Option(None, "-p", "--prompt", help="Ad-hoc prompt text. Overrides the prompt file."),
     prompt_file: Optional[str] = typer.Option(None, "--prompt-file", "-f", help="Path to prompt file. Overrides ralph.toml."),
@@ -401,7 +452,42 @@ def run(
     agent = toml_config["agent"]
     command = agent["command"]
     args = agent.get("args", [])
-    prompt_file_path = prompt_file if prompt_file else agent["prompt"]
+
+    # Conflict: positional name + --prompt-file
+    if prompt_name and prompt_file:
+        rprint("[red]Cannot use both a prompt name and --prompt-file.[/red]")
+        raise typer.Exit(1)
+
+    # Resolve prompt file path using priority chain:
+    # --prompt (inline text) > positional name > --prompt-file > ralph.toml > root PROMPT.md
+    resolved_prompt_name: str | None = None
+    if prompt_text:
+        # Inline text — no file needed
+        prompt_file_path = agent.get("prompt", "PROMPT.md")
+    elif prompt_name:
+        # Positional arg — look up in .ralph/prompts/
+        try:
+            found = resolve_prompt_name(prompt_name)
+        except ValueError as e:
+            rprint(f"[red]{e}[/red]")
+            raise typer.Exit(1)
+        prompt_file_path = str(found.path / "PROMPT.md")
+        resolved_prompt_name = found.name
+    elif prompt_file:
+        prompt_file_path = prompt_file
+    else:
+        # Fall back to ralph.toml agent.prompt — could be a name or a path
+        toml_prompt = agent.get("prompt", "PROMPT.md")
+        if is_prompt_name(toml_prompt):
+            # Try as a prompt name first, fall back to file path
+            try:
+                found = resolve_prompt_name(toml_prompt)
+                prompt_file_path = str(found.path / "PROMPT.md")
+                resolved_prompt_name = found.name
+            except ValueError:
+                prompt_file_path = toml_prompt
+        else:
+            prompt_file_path = toml_prompt
 
     prompt_path = Path(prompt_file_path)
     if not prompt_text and not prompt_path.exists():
@@ -416,6 +502,7 @@ def run(
         args=args,
         prompt_file=prompt_file_path,
         prompt_text=prompt_text,
+        prompt_name=resolved_prompt_name,
         max_iterations=n,
         delay=delay,
         timeout=timeout,

src/ralphify/engine.py

@@ -23,6 +23,7 @@
     run_all_checks,
 )
 from ralphify.contexts import discover_contexts, resolve_contexts, run_all_contexts
+from ralphify._frontmatter import parse_frontmatter
 from ralphify.instructions import discover_instructions, resolve_instructions
 
 
@@ -46,6 +47,7 @@ class RunConfig:
     args: list[str]
     prompt_file: str
     prompt_text: str | None = None
+    prompt_name: str | None = None
     max_iterations: int | None = None
     delay: float = 0
     timeout: float | None = None
@@ -160,6 +162,7 @@ def run_loop(
             "max_iterations": config.max_iterations,
             "timeout": config.timeout,
             "delay": config.delay,
+            "prompt_name": config.prompt_name,
         },
     ))
 
@@ -227,7 +230,11 @@ def run_loop(
             ))
 
             # Assemble prompt
-            prompt = config.prompt_text if config.prompt_text else prompt_path.read_text()
+            if config.prompt_text:
+                prompt = config.prompt_text
+            else:
+                raw = prompt_path.read_text()
+                _, prompt = parse_frontmatter(raw)
             if enabled_contexts:
                 context_results = run_all_contexts(enabled_contexts, config.project_root)
                 prompt = resolve_contexts(prompt, context_results)

src/ralphify/prompts.py

@@ -0,0 +1,59 @@
+"""Discover and resolve named prompts from ``.ralph/prompts/<name>/PROMPT.md``.
+
+Prompts are reusable task-focused prompt files that users can switch between
+(e.g. ``improve-docs``, ``refactor``, ``add-tests``).  They follow the same
+``.ralph/<kind>/<name>/MARKER.md`` convention as other primitives.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ralphify._frontmatter import discover_primitives
+
+
+@dataclass
+class Prompt:
+    """A named prompt discovered from ``.ralph/prompts/<name>/PROMPT.md``.
+
+    The *content* is the body text below the frontmatter.
+    """
+
+    name: str
+    path: Path
+    description: str = ""
+    enabled: bool = True
+    content: str = ""
+
+
+def discover_prompts(root: Path = Path(".")) -> list[Prompt]:
+    """Scan ``.ralph/prompts/`` for subdirectories containing ``PROMPT.md``.
+
+    Returns prompts in alphabetical order by name.
+    """
+    return [
+        Prompt(
+            name=entry.name,
+            path=entry,
+            description=frontmatter.get("description", ""),
+            enabled=frontmatter.get("enabled", True),
+            content=body,
+        )
+        for entry, frontmatter, body in discover_primitives(root, "prompts", "PROMPT.md")
+    ]
+
+
+def resolve_prompt_name(name: str, root: Path = Path(".")) -> Prompt:
+    """Look up a prompt by name.  Raises ``ValueError`` if not found."""
+    for prompt in discover_prompts(root):
+        if prompt.name == name:
+            return prompt
+    available = [p.name for p in discover_prompts(root)]
+    msg = f"Prompt '{name}' not found."
+    if available:
+        msg += f" Available: {', '.join(available)}"
+    raise ValueError(msg)
+
+
+def is_prompt_name(value: str) -> bool:
+    """Return True if *value* looks like a prompt name (no ``/`` or file extension)."""
+    return "/" not in value and "." not in value

src/ralphify/ui/api/primitives.py

@@ -11,6 +11,7 @@
 from ralphify.checks import discover_checks
 from ralphify.contexts import discover_contexts
 from ralphify.instructions import discover_instructions
+from ralphify.prompts import discover_prompts
 from ralphify.ui.models import PrimitiveResponse, PrimitiveUpdate
 
 router = APIRouter()
@@ -20,6 +21,7 @@
     "checks": (discover_checks, "CHECK.md"),
     "contexts": (discover_contexts, "CONTEXT.md"),
     "instructions": (discover_instructions, "INSTRUCTION.md"),
+    "prompts": (discover_prompts, "PROMPT.md"),
 }
 
 

src/ralphify/ui/api/runs.py

@@ -7,6 +7,7 @@
 
 from ralphify.engine import RunConfig
 from ralphify.manager import RunManager
+from ralphify.prompts import resolve_prompt_name
 from ralphify.ui.models import RunCreate, RunResponse, RunSettingsUpdate
 
 router = APIRouter()
@@ -36,11 +37,22 @@ def _run_response(managed) -> RunResponse:
 async def create_run(body: RunCreate) -> RunResponse:
     """Create and start a new run."""
     mgr = _get_manager()
+    prompt_file = body.prompt_file
+    resolved_name: str | None = None
+    if body.prompt_name:
+        root = Path(body.project_dir)
+        try:
+            found = resolve_prompt_name(body.prompt_name, root)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        prompt_file = str(found.path / "PROMPT.md")
+        resolved_name = found.name
     config = RunConfig(
         command=body.command,
         args=body.args,
-        prompt_file=body.prompt_file,
+        prompt_file=prompt_file,
         prompt_text=body.prompt_text,
+        prompt_name=resolved_name,
         max_iterations=body.max_iterations,
         delay=body.delay,
         timeout=body.timeout,

src/ralphify/ui/models.py

@@ -8,6 +8,7 @@ class RunCreate(BaseModel):
     args: list[str] = []
     prompt_file: str = "PROMPT.md"
     prompt_text: str | None = None
+    prompt_name: str | None = None
     max_iterations: int | None = None
     delay: float = 0
     timeout: float | None = None