Ralph Core

Ralph Core Instructions

"Single source of truth for all Ralph agents - reference, don't duplicate."

When to Use This Skill

Use when you need to reference:

• Core system behavior or architecture
• Status value definitions
• Exit conditions
• Ralph-specific protocols

Use proactively for:

• Resolving ambiguities about status transitions
• Understanding file ownership rules
• Clarifying commit format requirements

Quick Start

Example 2: Determine commit format

Q: How should I format my commit message?
A: Use Ralph commit format:
   [ralph] [{agent}] {task-id}: Brief description

   - Change 1
   - Change 2

   PRD: {task-id} | Agent: {agent} | Iteration: N

Example 3: Check file permissions

Q: Can I modify prd.json.items?
A: Only PM can modify task items. Workers can only
   modify their own agents.{agent} entry in prd.json.

Ralph Architecture (V2)

Event-Driven with Actor Model + Event Sourcing:

┌─────────────────────────────────────────────────────────────────┐
│                    ACTOR SUPERVISOR (Watchdog)                   │
│                    - Monitors agents via named pipes            │
│                    - Auto-restart on crash ("let-it-crash")      │
│                    - Event log: .claude/session/eventlog.jsonl │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    ┌─────────┐        ┌─────────┐        ┌─────────┐
    │    PM   │        │ Worker  │        │ Worker  │
    │ (pipes) │◄──────►│ (pipes) │◄──────►│ (pipes) │
    └─────────┘        └─────────┘        └─────────┘

Key Concepts

Status Values Reference (Single Source of Truth)

Task Status (prd.json.items[{taskId}].status)

Agent Status (prd.json.agents.{agent}.status)

Status Transition Rules

1. Only PM can set task status (except in_progress by workers)
2. Only QA can set passed status (PM then transitions)
3. Only PM can transition to completed
4. blocked is terminal - requires manual intervention
5. All awaiting_* statuses have 10-minute watchdog timeout

Task Status Flow

Core Flow (Implementation)

pending → assigned → in_progress → awaiting_qa → passed
                                        ↓
                                   needs_fixes
                                        ↓
                                   blocked (after max attempts)

Post-Validation Phases

passed → in_retrospective → retrospective_synthesized → playtest_phase
       → playtest_complete → prd_refinement → task_ready
       → skill_research → completed

File Ownership (Single-Writer Principle)

Concurrency Rules

1. Read-modify-write atomically - Use temp file pattern
2. Only update fields you own - Never overwrite another agent's data
3. Append-only for logs - Never delete or reorder entries
4. Retry on conflict - If write fails, re-read and retry once

Commit Format (Universal)

[ralph] [{AGENT}] {PRD_ID}: Brief description

- Change 1
- Change 2

PRD: {PRD_ID} | Agent: {AGENT} | Iteration: {N}

Universal Commit Rule

CRITICAL: Every agent MUST commit their file changes.

When to Commit:

• After any file modifications (source, configs, PRD, docs, session)
• Before sending completion messages
• After any skill file updates
• After any documentation changes

No Commit Exceptions:

• Heartbeat updates (prd.json.agents.{agent}.lastSeen)
• Temporary/pending message files

Exit Conditions

Only these allow agents to exit:

Workers MUST check and exit when any condition is met.

Heartbeat Protocol

Agents MUST emit heartbeat markers during long operations:

[HEARTBEAT] Agent: {AGENT_TYPE} | Status: working | Task: {TASK_ID}

Emit:

• Every 30 seconds during long-running operations
• When starting a new phase of work
• When waiting for external processes (builds, tests)

Configuration

Configurable via environment variables:

Related Skills