Custom Workflows

Ralph is designed to be customized for your specific project needs. This guide shows how to adapt Ralph for different tech stacks, quality checks, and team workflows.

Customizing the Prompt

Ralph uses prompt.md (for Amp) or CLAUDE.md (for Claude Code) as the instruction template for each iteration. This is where you encode your project’s conventions.

Location

scripts/ralph/
├── ralph.sh          # The loop script
├── prompt.md         # Amp instructions (copy and customize)
└── CLAUDE.md         # Claude Code instructions (copy and customize)

What to Customize

Quality Checks
Project Conventions
Tech Stack Details
Common Patterns

Add your project’s specific commands:

## Quality Checks

Before marking a story complete, run:
- npm run typecheck
- npm run lint
- npm run test
- npm run build

ALL checks must pass before committing.

Document your codebase patterns:

prompt.md

## Project Conventions

### Database
- Use Prisma for schema and migrations
- Migration naming: YYYY-MM-DD-description.ts
- Always add indexes for foreign keys

### Components
- Place in `components/` (not `app/components/`)
- Use `"use client"` directive for interactive components
- Export types from same file as component

### Server Actions
- Place in `app/actions/` directory
- Always revalidate relevant paths after mutations
- Return `{success: boolean, error?: string}` format

### Styling
- Use Tailwind utility classes
- Component variants with class-variance-authority
- No inline styles or CSS modules

### State Management
- Server state: React Query
- Client state: Zustand stores in `lib/stores/`
- URL state: searchParams for filters/pagination

Add framework-specific guidance:

prompt.md

## Tech Stack

- **Framework:** Next.js 14 (App Router)
- **Database:** PostgreSQL with Prisma ORM
- **Auth:** NextAuth.js v5
- **UI:** Tailwind CSS + shadcn/ui components
- **Validation:** Zod schemas
- **Testing:** Vitest + Testing Library

## Important Gotchas

- Server Components are default - add "use client" when needed
- Dynamic routes must export generateStaticParams for static export
- Prisma client is singleton - import from lib/prisma
- Auth session available via await auth() in Server Components
- Use server actions for mutations, not route handlers

Document frequently used patterns:

prompt.md

## Common Patterns

### Adding a New Page
Create `app/[route]/page.tsx`
Add metadata export for SEO
Update navigation in `components/Nav.tsx`
Add to sitemap.ts if public

### Adding a Database Table
Update `prisma/schema.prisma`
Run `npx prisma migrate dev --name description`
Regenerate types: `npx prisma generate`
Update AGENTS.md with new table info

### Adding a Form
Create Zod schema in `lib/schemas/`
Create server action in `app/actions/`
Use useFormState hook for client form
Add loading state and error handling

### Adding a Protected Route
Check session at top of page: `const session = await auth()`
Redirect if not authenticated
Add role check if needed
Add to middleware matcher if entire route is protected

Example: E-commerce Project

Here’s a complete example of a customized prompt.md for an e-commerce site:

# Ralph Iteration Prompt - ShopApp

You are Ralph, an autonomous coding agent working on ShopApp, an e-commerce platform.

## Your Job

1. Read `prd.json` and find the highest priority story where `passes: false`
2. Read `progress.txt` for context from previous iterations
3. Implement that ONE story completely
4. Run quality checks (below)
5. Commit if checks pass
6. Update `prd.json` to mark story as `passes: true`
7. Append learnings to `progress.txt`
8. Output `<promise>CONTINUE</promise>` or `<promise>COMPLETE</promise>`

## Tech Stack

- **Framework:** Next.js 14 (App Router)
- **Database:** PostgreSQL + Prisma
- **Payments:** Stripe
- **Images:** Cloudinary
- **Search:** Algolia
- **Email:** Resend
- **UI:** Tailwind + Custom components

## Quality Checks

Before marking complete, run ALL of these:
- npm run typecheck (Must pass)
- npm run lint (Must pass)
- npm run test (Must pass)
- npm run build (Must succeed)

## Project Conventions

### Products
- Product data in `products` table with `product_variants` relationship
- Always eager-load images (avoid N+1 queries)
- Use `formatPrice()` helper for displaying prices
- Inventory tracked in `inventory` table with SKU

### Orders
- Orders are immutable after creation (create audit records for changes)
- Order status enum: pending | processing | shipped | delivered | cancelled
- Always create Stripe PaymentIntent before order creation
- Send email confirmation via Resend after successful order

### Images
- Upload to Cloudinary via server action
- Store cloudinary_id and optimized URL in database
- Use Next.js Image component with Cloudinary loader
- Product images: 800x800px, webp format

### Search
- Product search powered by Algolia
- Index updates via webhook after product mutations
- Search component: `components/ProductSearch.tsx`
- Facets: category, price range, rating, in_stock

### Cart
- Stored in localStorage for guests (max 30 days)
- Stored in database for authenticated users
- Merge guest cart to user cart on login
- Use `useCart()` hook for cart operations

## Common Gotchas

- **Prices:** Store in cents (integer), never floats
- **Stripe:** Use metadata field to link PaymentIntent to order
- **Inventory:** Check stock before allowing add to cart
- **Images:** Always provide alt text for accessibility
- **Emails:** Use email templates from `emails/` directory

## AGENTS.md Updates

After completing a story, update relevant AGENTS.md files with:
- New patterns discovered
- Important gotchas encountered
- Useful context for future iterations

## Output Format

After completing the story:

Project-Specific Examples

SaaS Application

Key customizations:

Multi-tenancy patterns (tenant isolation)
Subscription/billing checks before operations
Feature flags for different plan tiers
Audit logging for compliance

### Multi-Tenancy
- Every query MUST filter by tenantId
- Use middleware to inject tenantId from session
- Tenant data isolated at database level
- Admin routes check isSuperAdmin flag

Mobile Backend API

Key customizations:

API versioning strategy
Rate limiting per endpoint
Response pagination standards
Authentication token refresh flow

### API Conventions
- Version in URL: /api/v1/
- Paginate with limit/offset params
- Return meta: {total, page, hasMore}
- Rate limit: 100 req/min per user

Data Pipeline

Key customizations:

ETL job patterns
Error handling and retry logic
Data validation schemas
Monitoring and alerting

### Pipeline Patterns
- Jobs in jobs/ directory with .job.ts suffix
- Use BullMQ for job queue
- Retry failed jobs 3x with exponential backoff
- Log to Datadog with job_name tag

Component Library

Key customizations:

Component API consistency
Storybook stories for each component
Accessibility requirements
Visual regression tests

### Component Standards
- Export types alongside component
- Props use ComponentProps pattern
- Write Storybook story with variants
- Test keyboard navigation
- ARIA labels required for interactive elements

Quality Check Variations

Strict (Enterprise)

Maximum safety for production systems:

## Quality Checks (STRICT)

ALL must pass before commit:

**Type checking:** `npm run typecheck`
**Linting:** `npm run lint` (no warnings)
**Unit tests:** `npm run test` (100% of existing tests)
**Integration tests:** `npm run test:integration`
**E2E tests:** `npm run test:e2e` (for UI changes)
**Security audit:** `npm audit` (no high/critical)
**Build:** `npm run build` (must succeed)
**Bundle size:** Check bundle doesn't grow >5%

If ANY check fails, fix it before marking story complete.

Balanced (Startup)

Essential checks without slowing down:

## Quality Checks (BALANCED)

Required before commit:

1. **Type checking:** `npm run typecheck`
2. **Linting:** `npm run lint`
3. **Tests:** `npm run test` (for changed files)
4. **Build:** `npm run build`

If checks fail, fix before marking complete.

Minimal (Prototype)

Fast iteration for proof-of-concept:

## Quality Checks (MINIMAL)

Before commit:

1. **Type checking:** `npm run typecheck`
2. **Build:** `npm run build`

Fix type errors before committing. Other issues can be addressed later.

Browser Verification Patterns

For UI-heavy projects, customize dev-browser usage:

## Browser Verification

For stories with UI changes, use dev-browser skill to:

1. Start dev server: `npm run dev`
2. Navigate to changed page
3. Interact with new UI elements
4. Verify visual appearance matches requirements
5. Test responsive behavior (mobile/desktop)
6. Screenshot before marking complete

Include verification steps in commit message.

Team Workflow Integration

PR Workflow
Ticket Integration
Slack Notifications

Have Ralph create PRs instead of direct commits:

## Completion Process

After all stories pass:

1. Push branch: `git push -u origin $(git branch --show-current)`
2. Create PR: `gh pr create --title "[Feature name]" --body "Completes: [list story IDs]"`
3. Add reviewers: `gh pr edit --add-reviewer @team-dev`
4. Link issues: Reference in PR description

Output PR URL and mark as COMPLETE.

Connect Ralph to your issue tracker:

## Story Completion

After marking story as passes:

1. Update Linear ticket status to "In Review"
2. Comment with commit SHA
3. Add "ralph" label to ticket

Use Linear API command:
linear-cli issue update [TICKET_ID] --status "In Review"

Send progress updates:

## Progress Reporting

After each story completion, send Slack notification:

curl -X POST $SLACK_WEBHOOK with:
- Story ID and title
- Commit link
- Branch name

Only send if SLACK_WEBHOOK env var is set.

Testing Your Customizations

After customizing, test with a small PRD:

{
  "project": "Test",
  "branchName": "ralph/test-customization",
  "description": "Test custom Ralph setup",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add test endpoint",
      "description": "As a developer, I want to verify Ralph runs correctly.",
      "acceptanceCriteria": [
        "Add /api/test route that returns {status: 'ok'}",
        "Typecheck passes",
        "Tests pass"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Run Ralph and verify:

Custom quality checks run
Project conventions are followed
Completion process works as expected

Start with small customizations and iterate. Add conventions as you discover patterns that should be encoded.

CLI

File Formats

Examples

Custom Workflows

Custom Workflows

Customizing the Prompt

Location

What to Customize

Example: E-commerce Project

Project-Specific Examples

Quality Check Variations

Browser Verification Patterns

Team Workflow Integration

Testing Your Customizations

Build docs developers (and LLMs) love

CLI

File Formats

Examples

Documentation Index

​Custom Workflows

​Customizing the Prompt

​Location

​What to Customize

​Example: E-commerce Project

​Project-Specific Examples

​Quality Check Variations

​Browser Verification Patterns

​Team Workflow Integration

​Testing Your Customizations

Build docs developers (and LLMs) love

Custom Workflows

Customizing the Prompt

Location

What to Customize

Example: E-commerce Project

Project-Specific Examples

Quality Check Variations

Browser Verification Patterns

Team Workflow Integration

Testing Your Customizations