Skip to content

README.md

Latest commit

 

History

History
376 lines (284 loc) · 10.1 KB

README.md

File metadata and controls

376 lines (284 loc) · 10.1 KB

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:

Resources

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.