Awesome Ralphy

Universal templates and workflow for Ralphy projects.

What is This?

A unified workflow and template collection for working with Ralphy - an autonomous AI coding automation tool. These templates provide a consistent way of working across all project types, from web apps to CLIs to infrastructure.

Philosophy: The way you document decisions, capture learnings, and structure work should be the same regardless of what you're building.

Quick Start

Setup a New Project

Linux/macOS:

cd /path/to/your/project
~/awesome-ralphy/scripts/setup-project.sh

Windows (PowerShell):

cd C:\path\to\your\project
~\awesome-ralphy\scripts\setup-project.ps1

That's it! No need to specify project type. The workflow is universal.

What Gets Created

your-project/
├── PRD.md                          # Product Requirements Document
├── .ralphy/
│   └── config.yaml                 # Ralphy configuration
├── docs/
│   ├── adr/                        # Architecture Decision Records
│   │   ├── adr-template.md
│   │   └── README.md
│   └── learnings/                  # Project learnings & gotchas
│       ├── learning-template.md
│       └── README.md
├── .claude/
│   └── commands/                   # Claude Code commands
│       ├── deploy-test.md
│       ├── review-pr.md
│       └── README.md
└── tasks/                          # Task templates
    ├── feature-development.yaml
    ├── bug-fix.yaml
    ├── infrastructure-deployment.yaml
    └── refactoring.yaml

Repository Structure

awesome-ralphy/
├── templates/
│   ├── prd/
│   │   └── PRD.md              # Universal PRD template
│   ├── config/
│   │   └── base-config.yaml    # Base Ralphy configuration
│   ├── docs/                   # Documentation templates
│   │   ├── adr/               # Architecture Decision Records
│   │   └── learnings/         # Learnings documentation
│   ├── claude-commands/        # Claude Code command templates
│   └── tasks/                  # Task list templates
└── scripts/
    ├── setup-project.sh        # Linux/macOS setup script
    └── setup-project.ps1       # Windows setup script

Core Concepts

1. Universal PRD Template

One template that works for all project types. Simply fill in what's relevant for your project:

• Web apps focus on UI/UX sections
• Backend APIs focus on endpoints and data models
• CLI tools focus on commands and options
• Infrastructure focuses on architecture and components

2. Unified Documentation Workflow

ADRs (Architecture Decision Records)

• Document significant decisions
• Same format whether deciding on a database, frontend framework, or deployment strategy
• Located in docs/adr/

Learnings

• Capture debugging sessions and gotchas
• Same format for frontend bugs, backend issues, or infrastructure problems
• Located in docs/learnings/

3. Common Task Templates

All projects benefit from structured workflows:

• Feature Development - Building new functionality
• Bug Fix - Investigating and fixing issues
• Infrastructure Deployment - IaC and deployment changes
• Refactoring - Safe code improvement

4. Claude Commands

Reusable automation for common tasks:

• /deploy-test - Test infrastructure from scratch
• /review-pr - Comprehensive PR review
• Extensible for project-specific needs

5. Claude Code Skills (Auto-Installed!)

Plugins are automatically installed when you run setup!

What happens:

~/awesome-ralphy/scripts/setup-project.sh

# Setup automatically runs:
# ✓ claude plugin marketplace add JohanSpannare/awesome-claude-extensions
# ✓ claude plugin install prd-interview@awesome-claude-extensions
# ✓ claude plugin install pragmatic-tdd@awesome-claude-extensions

Then just use:

/prd-interview
/pragmatic-tdd

Available skills:

• prd-interview - Problem-first PRD creation with User Stories, Use Cases, and 14-step comprehensive interview
• pragmatic-tdd - Test-Driven Development guide following hexagonal architecture and domain-driven design

How it works:

• Setup script uses Claude CLI to install plugins
• Uses --scope project (safe, won't affect your user settings)
• Gracefully falls back if Claude CLI not available
• Instructions in .claude/README-plugins.md for manual install

Why this approach is best:

• ✅ Idiot-proof - Just works automatically
• ✅ Safe - Uses official Claude CLI (handles settings merging correctly)
• ✅ Future-proof - Works even if Claude changes settings format
• ✅ No overwrites - Never touches your existing settings
• ✅ Automatic Updates - Update all projects: /plugin marketplace update

This separation allows awesome-ralphy to focus on templates and project structure, while awesome-claude-extensions provides enhanced interactive workflows through skills.

Usage Examples

Starting a New Web App

# Create Next.js project
npx create-next-app@latest my-app
cd my-app

# Setup Ralphy templates
~/awesome-ralphy/scripts/setup-project.sh

# Fill out PRD
vim PRD.md  # Focus on UI/UX and features sections

# Customize config for Node.js
vim .ralphy/config.yaml  # Set test: "npm test", lint: "npm run lint"

# Start building
ralphy start

Starting a New API Project

# Create project directory
mkdir my-api && cd my-api
python -m venv venv

# Setup Ralphy templates
~/awesome-ralphy/scripts/setup-project.sh

# Fill out PRD
vim PRD.md  # Focus on API endpoints and data models

# Customize config for Python
vim .ralphy/config.yaml  # Set test: "pytest", lint: "pylint ."

# Start building
ralphy start

Starting Infrastructure Project

# Create project directory
mkdir my-infrastructure && cd my-infrastructure

# Setup Ralphy templates
~/awesome-ralphy/scripts/setup-project.sh

# Fill out PRD
vim PRD.md  # Focus on architecture and components

# Customize config for IaC
vim .ralphy/config.yaml  # Set validation commands

# Create first ADR
cp docs/adr/adr-template.md docs/adr/adr-001-cloud-provider.md

# Start building
ralphy start

Workflow

1. Define Requirements (PRD.md)

• Fill in relevant sections
• Skip sections that don't apply
• Use as source of truth for Ralphy

2. Document Decisions (docs/adr/)

cp docs/adr/adr-template.md docs/adr/adr-001-use-postgresql.md
# Document why PostgreSQL over MongoDB

3. Structure Work (tasks/)

cp ~/awesome-ralphy/templates/tasks/feature-development.yaml tasks/add-authentication.yaml
# Customize task list
ralphy run tasks/add-authentication.yaml

4. Capture Learnings (docs/learnings/)

cp docs/learnings/learning-template.md docs/learnings/2024-01-24-cors-issue-fix.md
# Document what you learned from debugging

5. Automate with Commands (.claude/commands/)

/deploy-test pr-123
/review-pr 456

Configuration

The base-config.yaml is a starting point. Customize for your stack:

# For Node.js project
quality:
  commands:
    test: "npm test"
    lint: "eslint ."
    build: "npm run build"

# For Python project
quality:
  commands:
    test: "pytest"
    lint: "pylint ."
    type_check: "mypy ."

# For Go project
quality:
  commands:
    test: "go test ./..."
    lint: "golangci-lint run"
    build: "go build"

Best Practices

Documentation

• ADRs for decisions - Why did we choose X over Y?
• Learnings for gotchas - What surprised us? What should future developers know?
• Keep PRD updated - As requirements change, update the PRD
• Link documents - Reference ADRs in learnings, PRD in ADRs, etc.

Task Management

• Use task templates for complex work
• Break down features into discrete tasks
• Track dependencies between tasks
• Update status as you progress

Configuration

• Start with base-config.yaml
• Customize for your tech stack
• Define clear project boundaries
• Set appropriate quality gates

Consistency

• Same workflow across all projects
• Same documentation structure
• Same way of capturing decisions
• Easier to context-switch between projects

Why Universal?

Before (project-type specific):

• Different templates for web vs backend vs CLI
• Different documentation approaches
• Hard to remember which template to use
• Inconsistent between projects

After (universal):

• One way to work, regardless of project type
• Consistent documentation across all projects
• Easy to switch between projects
• Focus on content, not structure

The way you work shouldn't change based on what you're building.

Customization

Adding Your Own Templates

# Add new task template
cp ~/awesome-ralphy/templates/tasks/feature-development.yaml \
   ~/awesome-ralphy/templates/tasks/security-audit.yaml
# Edit for security audit workflow

# Add new Claude command
cp ~/awesome-ralphy/templates/claude-commands/deploy-test.md \
   ~/awesome-ralphy/templates/claude-commands/security-scan.md
# Edit for security scanning

Project-Specific Commands

Add commands to .claude/commands/ in your project:

# .claude/commands/deploy-production.md

Deploy to production environment with safety checks.

## Steps
1. Verify all tests pass
2. Check staging environment
3. Create backup
4. Deploy to production
5. Monitor health checks

Examples

All examples use the same templates and workflow:

• Example Web App (future)
• Example API (future)
• Example CLI Tool (future)

Resources

• Ralphy Repository
• Claude Code
• ADR Documentation

Contributing

Improvements welcome! This is a living template system.

1. Templates should be project-agnostic
2. Documentation should follow the same structure
3. Workflows should be reusable
4. Keep it simple and focused

License

MIT

---

One workflow. All projects.