Skip to content

feat: add context placeholders for ralph name, iteration, and max_iterations#25

Closed
malpou wants to merge 3 commits into
computerlovetech:mainfrom
malpou:pm/ralph-context-placeholders
Closed

feat: add context placeholders for ralph name, iteration, and max_iterations#25
malpou wants to merge 3 commits into
computerlovetech:mainfrom
malpou:pm/ralph-context-placeholders

Conversation

@malpou
Copy link
Copy Markdown
Contributor

@malpou malpou commented Mar 22, 2026

Summary

Closes #14.

  • Adds {{ context.name }}, {{ context.iteration }}, and {{ context.max_iterations }} built-in placeholders so ralphs can access runtime metadata in their prompts
  • No frontmatter configuration needed — these are automatically available
  • context.name resolves to the ralph directory name, context.iteration to the 1-based iteration number, and context.max_iterations to the total if -n was set (empty otherwise)

Changes

  • _frontmatter.py — new FIELD_CONTEXT constant
  • _resolver.py — extended _ALL_PATTERN regex and resolve_all() to handle the context namespace
  • engine.py — new _build_context() helper, updated _assemble_prompt() signature to accept RunState
  • 6 new tests covering context resolution, missing keys, mixed namespaces, and engine integration
  • Docs updated: writing-prompts, quick-reference, codebase-map, SKILL.md, changelog (0.2.5)

Test plan

  • All 442 tests pass (uv run pytest)
  • Manual: create a ralph using {{ context.iteration }} in the prompt body and verify it resolves to the correct iteration number
---
agent: cat
---

Iteration {{ context.iteration }} of {{ context.max_iterations }}.
Ralph name is {{ context.name }}.
image
  • Manual: verify {{ context.max_iterations }} is empty when -n is not set
---
agent: cat
---

Hello from {{ context.name }}!
This is iteration {{ context.iteration }}.
Max iterations: [{{ context.max_iterations }}]
image

malpou and others added 3 commits March 22, 2026 08:40
… max_iterations

Ralphs can now access runtime metadata via {{ context.name }},
{{ context.iteration }}, and {{ context.max_iterations }} placeholders.
These are resolved alongside existing command and arg placeholders in
a single pass to prevent cross-contamination.

Closes computerlovetech#14

Co-authored-by: Ralphify <noreply@ralphify.co>
…ations

Co-authored-by: Ralphify <noreply@ralphify.co>
@malpou malpou marked this pull request as ready for review March 22, 2026 09:15
Copy link
Copy Markdown
Collaborator

@kasperjunge kasperjunge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this one — clean implementation and great test coverage.

One naming change I'd like before merging: rename context.* to ralph.*. So {{ ralph.name }}, {{ ralph.iteration }}, {{ ralph.max_iterations }}.

Reasoning: in a RALPH.md file, {{ ralph.name }} is immediately self-documenting — "this ralph's name." context is an overloaded term that requires a mental lookup ("context of what?"). ralph.* reads naturally and there's zero ambiguity.

If you update the namespace naming + docs, this is good to merge.

@kasperjunge
Copy link
Copy Markdown
Collaborator

Superseded by #37, which renames context.* to ralph.* as discussed. Thanks @malpou for the original implementation — your commits are preserved with authorship in the new PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ralph name and iteration access

2 participants