Ralph Autonomous AI Agent Loop

To ensure Ralph succeeds, follow these guidelines for task sizing and verification:

Task Sizing

Each story in prd.json must be small enough to fit within a single LLM context window.

• Good (Small): Adding a single database column, creating one UI component, or updating one server action.
• Bad (Too Large): "Build the entire dashboard" or "Add authentication". These should be split into multiple smaller stories.

Verification

• Feedback Loops: Ensure your project has automated typechecking and tests. Ralph relies on these to verify work.
• UI Stories: For frontend tasks, include "Verify in browser using dev-browser skill" in the acceptance criteria so Ralph can interactively confirm changes.

Ralph operates on the principle that each iteration is a fresh instance. To prevent context bloat and ensure reliability, every iteration starts with a clean context window.

Memory is preserved across these fresh instances via three specific mechanisms:

1. Git History: Commits from previous iterations provide context on what was changed.
2. progress.txt: An append-only file containing learnings and context discovered during previous runs.
3. prd.json: Tracks the status of user stories (the passes field).

To prevent future iterations from repeating mistakes, maintain a ## Codebase Patterns section at the TOP of progress.txt.

Only add patterns that are general and reusable. Do not include story-specific implementation details or temporary debugging notes.

Examples of patterns to include:

• Specific template usages (e.g., sql<number> for aggregations).
• Migration requirements (e.g., IF NOT EXISTS).
• Export conventions (e.g., exporting types from actions.ts for UI components).

## Codebase Patterns
- Example: Use `sql<number>` template for aggregations
- Example: Always use `IF NOT EXISTS` for migrations
- Example: Export types from actions.ts for UI components

For production applications, it is recommended to enable type-aware lint rules by replacing standard tseslint configurations with type-checked versions. You must also configure parserOptions to point to your tsconfig files so the linter can access type information.

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Replace tseslint.configs.recommended with one of these:
      tseslint.configs.recommendedTypeChecked,
      // Or for stricter rules:
      tseslint.configs.strictTypeChecked,
      // Or for stylistic rules:
      tseslint.configs.stylisticTypeChecked,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
])

Use the ralph skill to convert existing Product Requirement Documents (PRDs) in markdown or text format into the prd.json format required for Ralph's autonomous execution.

Trigger phrases:

• convert this prd
• turn this into ralph format
• create prd.json from this
• ralph json

The prd skill is used to generate a detailed Product Requirements Document (PRD) for new features or projects. It is designed to create clear, actionable documentation suitable for implementation by developers or AI agents.

Trigger Phrases:

• create a prd
• write prd for [feature]
• plan this feature
• requirements for [feature]
• spec out [feature]

Workflow:

1. Input: Provide a description of the feature.
2. Clarification: The tool will ask 3-5 essential clarifying questions (using lettered options like A, B, C) to resolve ambiguities regarding goals, functionality, scope, or success criteria.
3. Generation: Once questions are answered, a structured PRD is generated.
4. Output: The final document is saved as a Markdown file in the tasks/ directory using the naming convention prd-[feature-name].md (kebab-case).

You can add Ralph as a plugin to Claude Code using the marketplace commands. This provides two specific skills:

• /prd: Generates Product Requirements Documents.
• /ralph: Converts PRDs to the prd.json format required for autonomous execution.

These skills are automatically triggered by natural language prompts like "create a prd" or "turn into ralph format".

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Acceptance criteria must be specific and checkable by an agent. Avoid vague language like "Good UX" or "Works correctly".

Required Criteria:

• Every story: Must include "Typecheck passes" as the final criterion.
• Testable logic: Include "Tests pass".
• UI changes: Must include "Verify in browser using dev-browser skill". Frontend stories are not considered complete until visually verified via the dev-browser skill.

Examples:

• Good: "Add status column to tasks table with default 'pending'"
• Bad: "Handles edge cases"

To enforce React-specific best practices, install and configure eslint-plugin-react-x and eslint-plugin-react-dom. These plugins provide recommended configurations for both React logic and React DOM usage.

// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
])

You can install Ralph's skills globally so they are available to Amp across all your projects by copying the skill directories to your Amp configuration folder.

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/