Research: Ralph Loop pattern implementation in gh-aw

[Copilot]

Research how Ralph Loop (autonomous AI agent loop pattern) maps to gh-aw's security-first architecture.

Design Document: docs/examples/ralph-loop.md

Core Finding: gh-aw implements a "Guided Ralph" - Ralph's autonomous iteration pattern with safety guardrails via safe-outputs and PR-based workflows.

Ralph → gh-aw Mapping

Ralph	gh-aw
Bash while loop	GitHub Actions scheduled triggers
Fresh context per iteration	New workflow run = fresh agent instance
prd.json task list	GitHub Discussion with JSON body
progress.txt learnings	Discussion comments
Direct git commits	safe-outputs: create-pull-request
Quality checks (tests/lint)	tools: bash with allowlist

Proposed Implementation

3-phase workflow structure:

1. PRD Initialization - JSON task list in GitHub Discussion
2. Ralph Loop Workflow - Autonomous story implementation with 6-step process (load PRD → select task → implement → quality checks → create PR → update status)
3. Orchestration - Optional controller for iteration management

Example workflow excerpt:

on:
  workflow_dispatch:
    inputs:
      prd_discussion_number:
        required: true
  schedule:
    - cron: "0 */2 * * *"

safe-outputs:
  create-pull-request:
    title-prefix: "[ralph] "
    draft: true
  update-discussion:
    allowed-discussion-numbers: [${{ inputs.prd_discussion_number }}]

Key Trade-offs

Autonomy vs Safety: Ralph commits directly; gh-aw creates draft PRs requiring human review
Iteration Speed: GitHub Actions 2-5min startup vs instant bash loop
State Management: API-based (Discussions) vs local files

Gaps Identified

7 limitations with mitigation strategies:

• Autonomy constraints (safe-outputs required)
• Iteration latency (Actions startup)
• State complexity (API vs files)
• Context window limits
• Local testing challenges
• Error recovery mechanisms
• Scheduling frequency caps

Best Fit: Incremental migrations, doc maintenance, dependency updates, phased rollouts
Poor Fit: Rapid local iteration, unattended overnight runs, direct commits

Future Enhancements

Native Ralph Loop support could include:

• First-class ralph-loop: configuration
• Built-in PRD status tracking via safe-outputs: update-prd-status
• Smart story selection and dependency analysis
• Continuous mode with auto-retriggering
• Multi-agent parallelism

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Research and document Ralph Loop pattern for agentic workflows</issue_title>
<issue_description>## Objective

Research the Ralph Loop pattern and document how it can be implemented using gh-aw agentic workflows.

Context

Ralph is an autonomous AI agent loop that runs AI coding tools repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Reference: https://github.com/snarktank/ralph

Approach

1. Review the Ralph Loop pattern and its key concepts:

   • Fresh context per iteration
   • Memory via git history + progress.txt + prd.json
   • Small, atomic tasks
   • Feedback loops (typecheck, tests)
   • AGENTS.md updates for learnings

2. Identify mapping between Ralph concepts and gh-aw features:

   • How to structure PRD as workflow frontmatter
   • How to track task completion state
   • How to persist learnings between iterations
   • How to implement quality checks

3. Create a design document in docs/examples/ralph-loop.md covering:

   • Overview of Ralph Loop pattern
   • Mapping to gh-aw agentic workflows
   • Proposed workflow structure
   • Key differences from bash-based Ralph

Files to Create

• docs/examples/ralph-loop.md - Design document

Acceptance Criteria

• Design document explains Ralph Loop pattern clearly
• Document maps Ralph concepts to gh-aw features
• Document outlines proposed workflow structure
• Document identifies any gaps or limitations
  Related to Add Ralph Loop examples for agentic workflows #11132

AI generated by Plan Command for #11132

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Research and document Ralph Loop pattern for agentic workflows #11133

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.