Shared Core

Shared Core

"This is the canonical reference for shared Ralph behavior. Agent-specific docs should reference these rules, not duplicate them."

Single Source of Truth

Workers read lightweight state files, PM syncs with prd.json

State File Architecture

Key Principle: Workers NEVER read prd.json. They read only their own state file.

prd.json Role

prd.json is now PM-ONLY. It serves as:

1. PM's task database - All tasks, dependencies, priorities
2. Session state record - Iteration, max iterations, completion
3. Sync source - PM syncs between agent files and PRD

Workers do NOT read prd.json because:

• 110KB file bloats context windows
• Workers only need their current task info
• PM handles all coordination decisions

PM reads both:

• All agent state files (for worker status)
• prd.json (for task database)

prd.json Schema (PM Reference Only)

prd.json Schema

{
  "session": {
    "sessionId": "string",
    "startedAt": "ISO-8601",
    "maxIterations": 200,
    "iteration": 0,
    "status": "running|completed|terminated|max_iterations_reached",
    "currentTask": { "id": "string", "status": "string" } | null,
    "stats": { "totalTasks": 0, "completed": 0, "failed": 0, "commits": 0 }
  },
  "agents": {
    "pm": { "status": "idle", "lastSeen": "ISO-8601", "currentTaskId": "string|null" },
    "developer": { "status": "idle", "lastSeen": "ISO-8601", "currentTaskId": "string|null" },
    "qa": { "status": "idle", "lastSeen": "ISO-8601", "currentTaskId": "string|null" },
    "techartist": { "status": "idle", "lastSeen": "ISO-8601", "currentTaskId": "string|null" },
    "gamedesigner": { "status": "idle", "lastSeen": "ISO-8601", "currentTaskId": "string|null" }
  },
  "items": [
    {
      "id": "string",
      "title": "string",
      "category": "architectural|integration|functional|visual|shader|polish",
      "priority": "high|medium|low",
      "status": "pending|assigned|in_progress|awaiting_qa|passed|needs_fixes|blocked|in_retrospective|retrospective_synthesized|playtest_phase|playtest_complete|prd_refinement|task_ready|skill_research|completed",
      "passes": false,
      "agent": "developer|qa|techartist|gamedesigner",
      "dependencies": ["taskId1", "taskId2"],
      "acceptanceCriteria": [],
      "verificationSteps": [],
      "retryCount": 0,
      "bugs": []
    }
  ],
  "backlogFile": "prd_backlog.json"
}

Session Directory

.claude/session/
├── current-task-developer.json   # Developer state (read by dev, PM)
├── current-task-qa.json          # QA state (read by qa, PM)
├── current-task-techartist.json  # Tech Artist state (read by ta, PM)
├── current-task-gamedesigner.json # Game Designer state (read by gd, PM)
├── current-task-pm.json          # PM coordinator state
├── handoff-log.json             # Task handoff history
├── continue-loop.flag           # Restart signal
├── work-in-progress.json        # Saved state for resume
├── coordinator-progress.txt     # Human-readable log
└── messages/                    # Message queues (event-driven)
    ├── pm/
    ├── developer/
    ├── qa/
    ├── techartist/
    └── gamedesigner/

Unified Status Values (Single Source of Truth)

This is the authoritative reference for ALL status values in Ralph.

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

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

Status Transition Rules

1. Only PM sets task status (except in_progress - workers self-report)
2. Only QA sets passed (PM then transitions to in_retrospective)
3. Only PM transitions to completed (after skill_research)

Task Status Flow Diagrams

Core Task Flow (Implementation)

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

Post-Validation Phased Workflow

passed
  → prd_refinement (PM reorganizes PRD and PRD Backlog)
  → task_ready
  → skill_research (PM improves skills IF needed)
  → completed (archived)

For PM Coordinator

PM reads both agent state files AND prd.json.

After processing each message:

1. Read all agent state files to update Worker Status Summary
2. Sync changes to prd.json.agents section
3. Update prd.json if task status changes

PM heartbeat pattern:

• Update current-task-pm.md with coordinator status
• Sync to prd.json.agents.pm
• Update lastSeen timestamp

Event-Driven Mode Exit Sequence

In event-driven mode, agents exit after work:

1. Complete your work
2. Determine exit status:
   - "idle" - Done
   - "awaiting_pm" - Sent question to PM
   - "awaiting_gd" - Sent question to Game Designer
3. Send status_update message
4. Exit

The status_update message is critical - tells supervisor your actual state.

Exit Conditions

Workers MUST check coordinator status every poll and exit when:

For PM Coordinator: Read current-task-pm.json for session status, or prd.json.session.

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

Each Agent's Commit Scope