Skip to content

Instantly share code, notes, and snippets.

@vishalsachdev

vishalsachdev/SKILL.md

Last active January 10, 2026 21:15
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save vishalsachdev/281d9609d766c1c506c810f69bafa40f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save vishalsachdev/281d9609d766c1c506c810f69bafa40f to your computer and use it in GitHub Desktop.
Download ZIP
Ralph Playbook - Agent Skills Implementation Guide
Raw
SKILL.md
name description license metadata compatibility
ralph-playbook
Implements Ralph workflow - an iterative AI-driven development loop using Jobs-to-be-Done (JTBD) specification, gap analysis, and autonomous building with backpressure validation. Use when building software products with deterministic LLM-based planning and implementation loops.
Apache-2.0
author version source
Clayton Farr
1.0
Requires bash, git, and Claude CLI. Best suited for projects with test suites and build validation.

Ralph Playbook

An autonomous AI-driven development workflow that structures software building into three phases: requirement definition, planning (gap analysis), and iterative building with test-driven backpressure.

Core Concept

Ralph is a loop that runs continuously. It reads a prompt, performs one task, updates plan files on disk, commits, and exits—leaving everything ready for the next iteration. The loop restarts automatically.

Key Philosophy: Context is everything. Allocate first ~5K tokens to specs, run one task per loop iteration with fresh context, and fan out to subagents.

Three Phases

Phase 1: Define Requirements

  • Identify Jobs to Be Done (JTBD)
  • Break JTBDs into topics of concern
  • Create spec files (specs/FILENAME.md) for each topic

Phase 2: Planning (PLANNING mode)

  • Subagents study specs and existing source code
  • Gap analysis: compare specifications against current implementation
  • Create/update IMPLEMENTATION_PLAN.md with prioritized tasks
  • No implementation—planning only

Phase 3: Building (BUILDING mode)

  • Orient: study specs and existing code
  • Select the most important task from the plan
  • Implement the task
  • Run tests/validation (backpressure)
  • Update IMPLEMENTATION_PLAN.md, commit, exit
  • Loop restarts automatically

Key Files

  • loop.sh: Bash script orchestrating the loop
  • PROMPT_build.md: Instructions for the building phase
  • PROMPT_plan.md: Instructions for the planning phase
  • AGENTS.md: Operational guide for how to build/test
  • IMPLEMENTATION_PLAN.md: Persistent task list
  • specs/: Requirement specifications
  • src/: Application source code

Critical Principles

Context Is Everything

  • ~176K usable tokens at 200K context limit
  • Allocate first 5K tokens for specs
  • Fan out to subagents for expensive work
  • One task per loop = maximum smart zone utilization

Steering Ralph: Patterns + Backpressure

Upstream: Add code patterns that guide what Ralph generates Downstream: Create backpressure via tests, lints, builds, type checks

Let Ralph Ralph

  • Ralph self-identifies what to do next
  • Ralph self-corrects through test failures
  • Iterate on prompts based on observed failures
  • Trust eventual consistency through iteration

Plan Is Disposable

  • Regenerate the plan when wrong or stale
  • Better to discard a bad plan than watch Ralph circle

When to Use Ralph

  • Building software with clear specifications
  • Teams wanting autonomous AI-driven development
  • Projects with test suites for backpressure
  • Iterative development with frequent refinement

More Information

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