Skip to content

Extension API

Ralph’s prompts follow a built-in-first architecture. All methodology content, prompt templates, and role definitions live in ralph’s package code. Users extend this content through optional files in docs/prompts/.

  1. Always optional — Extension files are never required. Ralph works with zero extension files.
  2. Never overwritten — No ralph command (init, loop, or otherwise) modifies files in docs/prompts/ (except creating rules.md during ralph init).
  3. Appended, not replaced — Extension content is appended after built-in content, separated by a --- Project Extensions --- marker. User content never replaces built-in content (except role overrides via the explicit ## Override: directive).
FileMerge BehaviorFormat
docs/prompts/system.mdAppended to built-in system promptFree-form Markdown. Template variables supported.
docs/prompts/boot.mdAppended to built-in boot promptFree-form Markdown. Template variables supported.
docs/prompts/methodology.mdAppended to built-in methodologyFree-form Markdown.
docs/prompts/rules.mdInjected as {{project.rules}}Free-form Markdown.
docs/prompts/roles.mdMerged with built-in rolesDirective headings: ## Override:, ## Add:, ## Disable:
docs/prompts/task-template.mdReplaces built-in task scaffoldMarkdown task template for ralph task. Must include {{task.number}} and {{task.title}} placeholders.

Template variables use {{variable}} syntax and are interpolated in both built-in templates and user extension files:

VariableValue
{{task.id}}Task ID (e.g., T-005)
{{task.title}}Task title
{{task.description}}Task description body
{{task.prdReference}}PRD section reference (e.g., §3.2)
{{task.prdContent}}Extracted PRD section content
{{task.touches}}Comma-separated file paths from Touches field (blank if unset)
{{task.hints}}Content of the task’s Hints section (blank if no Hints)
{{config.language}}Project language (e.g., TypeScript)
{{config.packageManager}}Package manager (e.g., pnpm)
{{config.testingFramework}}Testing framework (e.g., Vitest)
{{config.qualityCheck}}Quality check command (e.g., pnpm check)
{{config.testCommand}}Test command (e.g., pnpm test)
{{config.fileNaming}}File naming convention (e.g., kebab-case, blank if unset)
{{project.rules}}Contents of docs/prompts/rules.md
{{codebaseIndex}}Auto-generated file/export index
{{retryContext}}Context from a previous failed attempt (empty on first attempt)

The docs/prompts/roles.md file uses Markdown headings with specific directives to customize the 9 built-in roles.

Replace a built-in role’s description:

## Override: SDET
In this project, the SDET focuses on integration testing with real database connections.
All tests must hit the actual PostgreSQL instance, not mocks.

The role keeps its name, focus, and participation phases but gets the new description.

Define a new role:

## Add: Compliance Officer
- **Focus**: Regulatory compliance
- **Responsibility**: Reviews all data handling for GDPR/HIPAA compliance. Validates that PII is encrypted at rest and in transit.
- **Participates**: Boot, Verify

Required fields for added roles: Focus, Responsibility, Participates (comma-separated phase names).

Remove a built-in role from the project:

## Disable: UX/UI Designer
This is a headless API project with no user-facing surface.

The description text after the heading is informational — it documents why the role is disabled.

Task files may include an optional Roles field to restrict which roles participate:

- **Roles**: DBA, Compliance Officer

When Roles is present, only the listed roles participate (plus Frontend & Backend Engineers, which always participate). When absent, all applicable roles participate.

Use ralph show to inspect the effective merged content:

Terminal window
ralph show system-prompt # Built-in system prompt + docs/prompts/system.md
ralph show boot-prompt # Built-in boot prompt + docs/prompts/boot.md
ralph show roles # Built-in roles + docs/prompts/roles.md customizations
ralph show methodology # Built-in methodology + docs/prompts/methodology.md
ralph show rules # Contents of docs/prompts/rules.md
# See only built-in content (without extensions)
ralph show system-prompt --built-in-only
# Machine-readable output
ralph show roles --json