Skip to content

Conversation

@fuahyo
Copy link

@fuahyo fuahyo commented Jan 12, 2026

Summary

This PR adds optional, additive documentation and examples that demonstrate one way to
structure work for Ralph, while fully preserving its minimal philosophy.

The goal is to help users define clearer, more focused tasks for each iteration,
without changing how Ralph executes or introducing any new abstractions.

What’s included

New files

  • examples/structured-workflow/README.md
    Overview of the approach and its guiding principles.

  • examples/structured-workflow/TASK-BREAKDOWN-GUIDE.md
    A practical guide for breaking work into focused stages
    (foundation → logic → interface → integration → polish).

  • examples/structured-workflow/prd.json.example
    Example PRD using optional, backwards-compatible metadata fields
    (stage, focus, responsibility) that Ralph safely ignores.

  • examples/structured-workflow/prompt-templates/
    Optional prompt snippets aligned with different task types:

    • foundation.md – schema, migrations, setup
    • logic.md – business rules, APIs
    • interface.md – UI components
    • integration.md – connecting pieces
    • polish.md – edge cases, error handling
  • examples/structured-workflow/example-feature/
    An end-to-end example showing a structured vs unstructured approach:

    • README.md
    • prd.json for a sample “task comments” feature

Updates

  • Main README.md updated to reference the new structured workflow examples.

Design principles preserved

  • No changes to ralph.sh or the core execution loop
  • No multi-agent orchestration
  • No runtime dependencies
  • No external methodology references
  • Everything is opt-in and easy to remove
  • Fully backwards-compatible (metadata fields are optional)
  • Focuses on task clarity, not orchestration logic

Why this exists

Ralph works best when each iteration has a narrow, well-defined goal.
These examples show one way to achieve that through task definition alone,
without adding process or complexity to the tool itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant