docs: document context placeholders for name, iteration, and max_iterations

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

Author: 2 people

docs/changelog.md

@@ -8,6 +8,14 @@ keywords: ralphify changelog, release history, new features, version updates, br
 
 All notable changes to ralphify are documented here.
 
+## 0.2.5 — 2026-03-22
+
+### 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.
+
+---
+
 ## 0.2.4 — 2026-03-22
 
 ### Fixed

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.* }})
+├── _resolver.py        # Template placeholder resolution ({{ commands.* }}, {{ args.* }}, {{ context.* }})
 ├── _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,13 +107,24 @@ 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
+
+```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
+```
+
+- Automatically available — no frontmatter configuration needed
+- Useful for progress tracking, naming logs, or adjusting behavior near the end of a run
+
 ## The loop
 
 Each iteration:
 
 1. Re-read `RALPH.md` from disk
 2. Run all commands in order, capture output
-3. Resolve `{{ commands.* }}` and `{{ args.* }}` placeholders
+3. Resolve `{{ commands.* }}`, `{{ args.* }}`, and `{{ context.* }}` placeholders
 4. Pipe assembled prompt to agent via stdin
 5. Wait for agent to exit
 6. Repeat

docs/writing-prompts.md

@@ -341,6 +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.
 - **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/skills/new-ralph/SKILL.md

@@ -86,9 +86,10 @@ If any tests are failing above, fix them before continuing.
 
 #### Body
 
-The body is the prompt. It supports two placeholder types:
+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`)
 
 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.