ralph-config

name	ralph-config
description	Generate ralph.yml and PROMPT.md configuration files for Ralph Orchestrator workflows from plans, tickets, or ideas. Use when setting up Ralph Orchestrator, creating hat-based workflows, or adapting Linear/Jira/markdown plans into ralph.yml + PROMPT.md files.

Ralph Orchestrator Configuration Generator

Generate ralph.yml and PROMPT.md files for Ralph Orchestrator hat-based agent workflows. Adapts plans from Linear, Jira, markdown files, or raw ideas into ready-to-run configurations.

Parameters

• --from <source>: Plan source - Linear ID, Jira ID, file path, URL, or inline description
• --preset <name>: Start from a built-in preset (see reference.md for full list)
• --pattern <name>: Coordination pattern (pipeline, contract-first, cyclic, adversarial, hypothesis-driven, coordinator-specialist, adaptive-entry)
• --backend <name>: Agent backend (claude, kiro, gemini, codex, amp, copilot, opencode). Default: claude
• --traditional: Hatless configuration (simple loop, no hat orchestration)
• --epic: Generate epic-level multi-phase execution workflow (PM orchestration, spec-driven development, phase gates)

Phase 0: Fetch Latest Documentation

Mandatory. Ralph Orchestrator changes frequently. Before generating any config:

1. Fetch latest config reference: https://mikeyobrien.github.io/ralph-orchestrator/guide/configuration/
2. Fetch hats & events: https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/
3. If using a preset, fetch it: https://raw.githubusercontent.com/mikeyobrien/ralph-orchestrator/main/presets/{preset-name}.yml
4. Compare against this skill's reference.md. Prefer fetched docs when they differ.
5. If fetches fail, warn the user and proceed with built-in reference:

   WARNING: Could not fetch latest Ralph docs. Using built-in reference
   which may be outdated. Verify at: https://mikeyobrien.github.io/ralph-orchestrator/
   

Phase 1: Progressive Source Discovery

Use progressive disclosure. Start simple, only ask deeper questions when genuinely needed.

Level 1 (always - skip if --from provided):

What are you trying to build or accomplish?

Level 2 (only if workflow type isn't obvious):

What type of workflow fits this? Feature / Bug fix / Refactor / Research / Docs / Deploy

Level 3 (only if using hats and pattern isn't clear):

How complex is the coordination? Simple (traditional, no hats) / Standard (2-3 hats, pipeline) / Advanced (4+ hats, use preset)

Do NOT front-load all questions. Extract what you can from the source first.

Phase 2: Source Adaptation

Extract plan content based on source type:

Linear ticket (--from CHR-123):

linctl issue get <ticket-id> --json
# Title → PROMPT.md objective
# Description → requirements and context
# Subtasks → task breakdown
# Labels → infer workflow type
# Comments → additional context

Jira ticket (--from PROJ-789): If no Jira MCP available, ask user to paste content. Extract same fields as Linear.

Markdown file (--from ./plan.md): Read the file. First heading = objective, content = requirements, task lists = acceptance criteria, code blocks = technical context.

Inline description (--from "Add validation..."): Use directly. Ask clarifying questions only if too vague for acceptance criteria.

No source: Interactive discovery starting from Level 1.

Phase 3: Generate PROMPT.md

PROMPT.md carries ALL workstream-specific context. Write it for an agent with zero prior context.

Use the template at templates/prompt-template.md.

Principles:

• Specific and concrete - vague prompts produce vague results
• Minimum 3 measurable acceptance criteria
• One objective per PROMPT.md
• Include file paths when referencing existing code
• Explicitly state what's out of scope

Phase 4: Generate ralph.yml

Key principle: ralph.yml stays generic and reusable. It defines orchestration mechanics (HOW), not workstream specifics (WHAT). Context lives in PROMPT.md and referenced files.

Decision Tree

Simple one-shot task?  →  Traditional mode (no hats)
                          ↓ no
Built-in preset fits?  →  Use preset, customize guardrails/backend only
                          ↓ no
Standard pattern fits? →  Use coordination pattern as template
                          ↓ no
Build custom hats         (rare - truly unique workflows only)

Design Principles

1. Start with a preset - Don't hand-craft hats when a preset works
2. Fewer hats is better - 2-hat workflow that works > 6-hat workflow that's fragile
3. Hat instructions are role-focused - Describe HOW to work, not WHAT to build
4. Events are routing signals - Brief payloads; detailed output goes in files
5. KISS always - Simplest config that achieves the goal

For the complete ralph.yml field reference and hat configuration schema, see reference.md.

For full worked examples, see examples/.

Phase 5: Output and Guidance

1. Write ralph.yml and PROMPT.md to the current directory
2. Show execution instructions:

   Files created:
     ./ralph.yml
     ./PROMPT.md
   
   To run:
     ralph run
   
   To run with a different backend:
     ralph run --backend gemini
   

3. If using hats, show the event flow:

   Workflow: task.start → Builder → build.done → Reviewer → review.approved → LOOP_COMPLETE
   

4. Remind user to review:
   • Does PROMPT.md capture the full intent?
   • Are guardrails appropriate for this project?
   • Is max_iterations sized right for the task?

---

Epic-Level Execution (--epic flag)

For epics/initiatives with multiple phases, stories, and dependencies, use the --epic flag to generate a full PM-orchestrated workflow.

When to Use Epic Mode

• Multi-phase projects with phase gates
• Epics with 5+ stories and dependencies
• Work requiring spec-driven development
• Projects needing audit trails in your tracker (Linear, Jira, GitHub)

Epic Directory Structure

project/
├── epic.ralph.yml                    # Ralph config
└── specs/epic-id/
    ├── epic.PROMPT.md               # Epic overview, success criteria
    ├── backlog.md                   # Phase structure, story ordering, dependencies
    ├── env.md                       # Environment setup, test commands (optional)
    └── phase-N/                     # Phase-specific generated artifacts

Epic Templates

• Epic PROMPT: templates/epic-prompt-template.md
• Backlog structure: templates/backlog-template.md

Epic Workflow

The epic workflow adds these hats on top of the standard pattern:

1. Project Manager - Orchestrates phases, creates tasks, handles transitions
2. Spec Writer - Creates detailed specs from tracker stories
3. Spec Reviewer - Reviews specs before implementation
4. Engineer - Implements approved specs using TDD
5. Verifier - Validates implementations ruthlessly
6. Phase Tester - Integration tests for each phase
7. Completion Tester - Final epic validation

Tracker Integration

Epic mode integrates with your project management tool. Adapt commands:

Tool	Fetch Issue	Comment
Linear	linctl issue get KEY --json	linctl issue comment KEY "message"
Jira	jira issue view KEY --plain	jira issue comment KEY "message"
GitHub	gh issue view NUM	gh issue comment NUM -b "message"

All hats comment on tracker tickets to maintain an audit trail.

Key Design Patterns

1. PM as Central Orchestrator - Only PM can emit LOOP_COMPLETE
2. Spec-Driven Development - No implementation without approved spec
3. Phase Gates - Each phase has explicit criteria before proceeding
4. Feedback Loops - Failed verifications trigger rework cycles
5. Task Dependencies - Ralph's task system manages story ordering

See examples/epic-multiagent-pipeline.md for a complete worked example.