Repository: snarktank/ralph Branch: main Commit: 6c53cb0b831e Files: 26 Total size: 60.8 KB Directory structure: gitextract_o5r2ey0r/ ├── .claude-plugin/ │ ├── marketplace.json │ └── plugin.json ├── .github/ │ └── workflows/ │ └── deploy.yml ├── .gitignore ├── AGENTS.md ├── CLAUDE.md ├── LICENSE ├── README.md ├── flowchart/ │ ├── .gitignore │ ├── README.md │ ├── eslint.config.js │ ├── index.html │ ├── package.json │ ├── src/ │ │ ├── App.css │ │ ├── App.tsx │ │ ├── index.css │ │ └── main.tsx │ ├── tsconfig.app.json │ ├── tsconfig.json │ ├── tsconfig.node.json │ └── vite.config.ts ├── prd.json.example ├── prompt.md ├── ralph.sh └── skills/ ├── prd/ │ └── SKILL.md └── ralph/ └── SKILL.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .claude-plugin/marketplace.json ================================================ { "name": "ralph-marketplace", "owner": { "name": "snarktank" }, "metadata": { "description": "Skills for the Ralph autonomous agent system - Generate PRDs and convert them to prd.json format for autonomous execution", "version": "1.0.0" }, "plugins": [ { "name": "ralph-skills", "source": "./", "description": "PRD generation and conversion skills for the Ralph autonomous agent loop", "version": "1.0.0", "keywords": ["ralph", "prd", "automation", "agent", "planning"], "category": "productivity", "skills": "./skills/" } ] } ================================================ FILE: .claude-plugin/plugin.json ================================================ { "name": "ralph-skills", "version": "1.0.0", "description": "Skills for the Ralph autonomous agent system - Generate PRDs and convert them to prd.json format for autonomous execution", "author": { "name": "snarktank" }, "skills": "./skills/", "keywords": ["ralph", "prd", "automation", "agent", "planning", "requirements"] } ================================================ FILE: .github/workflows/deploy.yml ================================================ name: Deploy Flowchart to GitHub Pages on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: 20 cache: npm cache-dependency-path: flowchart/package-lock.json - name: Install dependencies run: npm ci working-directory: flowchart - name: Build run: npm run build working-directory: flowchart - name: Setup Pages uses: actions/configure-pages@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: flowchart/dist deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 ================================================ FILE: .gitignore ================================================ # Ralph working files (generated during runs) prd.json progress.txt .last-branch # Archive is optional to commit # archive/ # OS files .DS_Store #Claude .claude/ ================================================ FILE: AGENTS.md ================================================ # Ralph Agent Instructions ## Overview Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. ## Commands ```bash # Run the flowchart dev server cd flowchart && npm run dev # Build the flowchart cd flowchart && npm run build # Run Ralph with Amp (default) ./ralph.sh [max_iterations] # Run Ralph with Claude Code ./ralph.sh --tool claude [max_iterations] ``` ## Key Files - `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) - `prompt.md` - Instructions given to each AMP instance - `CLAUDE.md` - Instructions given to each Claude Code instance - `prd.json.example` - Example PRD format - `flowchart/` - Interactive React Flow diagram explaining how Ralph works ## Flowchart The `flowchart/` directory contains an interactive visualization built with React Flow. It's designed for presentations - click through to reveal each step with animations. To run locally: ```bash cd flowchart npm install npm run dev ``` ## Patterns - Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context - Memory persists via git history, `progress.txt`, and `prd.json` - Stories should be small enough to complete in one context window - Always update AGENTS.md with discovered patterns for future iterations ================================================ FILE: CLAUDE.md ================================================ # Ralph Agent Instructions You are an autonomous coding agent working on a software project. ## Your Task 1. Read the PRD at `prd.json` (in the same directory as this file) 2. Read the progress log at `progress.txt` (check Codebase Patterns section first) 3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main. 4. Pick the **highest priority** user story where `passes: false` 5. Implement that single user story 6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires) 7. Update CLAUDE.md files if you discover reusable patterns (see below) 8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]` 9. Update the PRD to set `passes: true` for the completed story 10. Append your progress to `progress.txt` ## Progress Report Format APPEND to progress.txt (never replace, always append): ``` ## [Date/Time] - [Story ID] - What was implemented - Files changed - **Learnings for future iterations:** - Patterns discovered (e.g., "this codebase uses X for Y") - Gotchas encountered (e.g., "don't forget to update Z when changing W") - Useful context (e.g., "the evaluation panel is in component X") --- ``` The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better. ## Consolidate Patterns If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings: ``` ## Codebase Patterns - Example: Use `sql` template for aggregations - Example: Always use `IF NOT EXISTS` for migrations - Example: Export types from actions.ts for UI components ``` Only add patterns that are **general and reusable**, not story-specific details. ## Update CLAUDE.md Files Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files: 1. **Identify directories with edited files** - Look at which directories you modified 2. **Check for existing CLAUDE.md** - Look for CLAUDE.md in those directories or parent directories 3. **Add valuable learnings** - If you discovered something future developers/agents should know: - API patterns or conventions specific to that module - Gotchas or non-obvious requirements - Dependencies between files - Testing approaches for that area - Configuration or environment requirements **Examples of good CLAUDE.md additions:** - "When modifying X, also update Y to keep them in sync" - "This module uses pattern Z for all API calls" - "Tests require the dev server running on PORT 3000" - "Field names must match the template exactly" **Do NOT add:** - Story-specific implementation details - Temporary debugging notes - Information already in progress.txt Only update CLAUDE.md if you have **genuinely reusable knowledge** that would help future work in that directory. ## Quality Requirements - ALL commits must pass your project's quality checks (typecheck, lint, test) - Do NOT commit broken code - Keep changes focused and minimal - Follow existing code patterns ## Browser Testing (If Available) For any story that changes UI, verify it works in the browser if you have browser testing tools configured (e.g., via MCP): 1. Navigate to the relevant page 2. Verify the UI changes work as expected 3. Take a screenshot if helpful for the progress log If no browser tools are available, note in your progress report that manual browser verification is needed. ## Stop Condition After completing a user story, check if ALL stories have `passes: true`. If ALL stories are complete and passing, reply with: COMPLETE If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). ## Important - Work on ONE story per iteration - Commit frequently - Keep CI green - Read the Codebase Patterns section in progress.txt before starting ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2026 snarktank Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # Ralph ![Ralph](ralph.webp) Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`. Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). [Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632) ## Prerequisites - One of the following AI coding tools installed and authenticated: - [Amp CLI](https://ampcode.com) (default) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`) - `jq` installed (`brew install jq` on macOS) - A git repository for your project ## Setup ### Option 1: Copy to your project Copy the ralph files into your project: ```bash # From your project root mkdir -p scripts/ralph cp /path/to/ralph/ralph.sh scripts/ralph/ # Copy the prompt template for your AI tool of choice: cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp # OR cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code chmod +x scripts/ralph/ralph.sh ``` ### Option 2: Install skills globally (Amp) Copy the skills to your Amp or Claude config for use across all projects: For AMP ```bash cp -r skills/prd ~/.config/amp/skills/ cp -r skills/ralph ~/.config/amp/skills/ ``` For Claude Code (manual) ```bash cp -r skills/prd ~/.claude/skills/ cp -r skills/ralph ~/.claude/skills/ ``` ### Option 3: Use as Claude Code Marketplace Add the Ralph marketplace to Claude Code: ```bash /plugin marketplace add snarktank/ralph ``` Then install the skills: ```bash /plugin install ralph-skills@ralph-marketplace ``` Available skills after installation: - `/prd` - Generate Product Requirements Documents - `/ralph` - Convert PRDs to prd.json format Skills are automatically invoked when you ask Claude to: - "create a prd", "write prd for", "plan this feature" - "convert this prd", "turn into ralph format", "create prd.json" ### Configure Amp auto-handoff (recommended) Add to `~/.config/amp/settings.json`: ```json { "amp.experimental.autoHandoff": { "context": 90 } } ``` This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window. ## Workflow ### 1. Create a PRD Use the PRD skill to generate a detailed requirements document: ``` Load the prd skill and create a PRD for [your feature description] ``` Answer the clarifying questions. The skill saves output to `tasks/prd-[feature-name].md`. ### 2. Convert PRD to Ralph format Use the Ralph skill to convert the markdown PRD to JSON: ``` Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json ``` This creates `prd.json` with user stories structured for autonomous execution. ### 3. Run Ralph ```bash # Using Amp (default) ./scripts/ralph/ralph.sh [max_iterations] # Using Claude Code ./scripts/ralph/ralph.sh --tool claude [max_iterations] ``` Default is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool. Ralph will: 1. Create a feature branch (from PRD `branchName`) 2. Pick the highest priority story where `passes: false` 3. Implement that single story 4. Run quality checks (typecheck, tests) 5. Commit if checks pass 6. Update `prd.json` to mark story as `passes: true` 7. Append learnings to `progress.txt` 8. Repeat until all stories pass or max iterations reached ## Key Files | File | Purpose | |------|---------| | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) | | `prompt.md` | Prompt template for Amp | | `CLAUDE.md` | Prompt template for Claude Code | | `prd.json` | User stories with `passes` status (the task list) | | `prd.json.example` | Example PRD format for reference | | `progress.txt` | Append-only learnings for future iterations | | `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) | | `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) | | `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery | | `flowchart/` | Interactive visualization of how Ralph works | ## Flowchart [![Ralph Flowchart](ralph-flowchart.png)](https://snarktank.github.io/ralph/) **[View Interactive Flowchart](https://snarktank.github.io/ralph/)** - Click through to see each step with animations. The `flowchart/` directory contains the source code. To run locally: ```bash cd flowchart npm install npm run dev ``` ## Critical Concepts ### Each Iteration = Fresh Context Each iteration spawns a **new AI instance** (Amp or Claude Code) with clean context. The only memory between iterations is: - Git history (commits from previous iterations) - `progress.txt` (learnings and context) - `prd.json` (which stories are done) ### Small Tasks Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code. Right-sized stories: - Add a database column and migration - Add a UI component to an existing page - Update a server action with new logic - Add a filter dropdown to a list Too big (split these): - "Build the entire dashboard" - "Add authentication" - "Refactor the API" ### AGENTS.md Updates Are Critical After each iteration, Ralph updates the relevant `AGENTS.md` files with learnings. This is key because AI coding tools automatically read these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions. Examples of what to add to AGENTS.md: - Patterns discovered ("this codebase uses X for Y") - Gotchas ("do not forget to update Z when changing W") - Useful context ("the settings panel is in component X") ### Feedback Loops Ralph only works if there are feedback loops: - Typecheck catches type errors - Tests verify behavior - CI must stay green (broken code compounds across iterations) ### Browser Verification for UI Stories Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work. ### Stop Condition When all stories have `passes: true`, Ralph outputs `COMPLETE` and the loop exits. ## Debugging Check current state: ```bash # See which stories are done cat prd.json | jq '.userStories[] | {id, title, passes}' # See learnings from previous iterations cat progress.txt # Check git history git log --oneline -10 ``` ## Customizing the Prompt After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project: - Add project-specific quality check commands - Include codebase conventions - Add common gotchas for your stack ## Archiving Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`. ## References - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/) - [Amp documentation](https://ampcode.com/manual) - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) ================================================ FILE: flowchart/.gitignore ================================================ # Logs logs *.log npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* lerna-debug.log* node_modules dist dist-ssr *.local # Editor directories and files .vscode/* !.vscode/extensions.json .idea .DS_Store *.suo *.ntvs* *.njsproj *.sln *.sw? ================================================ FILE: flowchart/README.md ================================================ # React + TypeScript + Vite This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available: - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh ## React Compiler The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). ## Expanding the ESLint configuration If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: ```js export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ // Other configs... // Remove tseslint.configs.recommended and replace with this tseslint.configs.recommendedTypeChecked, // Alternatively, use this for stricter rules tseslint.configs.strictTypeChecked, // Optionally, add this for stylistic rules tseslint.configs.stylisticTypeChecked, // Other configs... ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ]) ``` You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: ```js // 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: [ // Other configs... // 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, }, // other options... }, }, ]) ``` ================================================ FILE: flowchart/eslint.config.js ================================================ import js from '@eslint/js' import globals from 'globals' import reactHooks from 'eslint-plugin-react-hooks' import reactRefresh from 'eslint-plugin-react-refresh' import tseslint from 'typescript-eslint' import { defineConfig, globalIgnores } from 'eslint/config' export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ js.configs.recommended, tseslint.configs.recommended, reactHooks.configs.flat.recommended, reactRefresh.configs.vite, ], languageOptions: { ecmaVersion: 2020, globals: globals.browser, }, }, ]) ================================================ FILE: flowchart/index.html ================================================ How Ralph Works
================================================ FILE: flowchart/package.json ================================================ { "name": "flowchart", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@xyflow/react": "^12.10.0", "react": "^19.2.0", "react-dom": "^19.2.0" }, "devDependencies": { "@eslint/js": "^9.39.1", "@types/node": "^24.10.1", "@types/react": "^19.2.5", "@types/react-dom": "^19.2.3", "@vitejs/plugin-react": "^5.1.1", "eslint": "^9.39.1", "eslint-plugin-react-hooks": "^7.0.1", "eslint-plugin-react-refresh": "^0.4.24", "globals": "^16.5.0", "typescript": "~5.9.3", "typescript-eslint": "^8.46.4", "vite": "^7.2.4" } } ================================================ FILE: flowchart/src/App.css ================================================ * { margin: 0; padding: 0; box-sizing: border-box; } .app-container { width: 100vw; height: 100vh; display: flex; flex-direction: column; background: #ffffff; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; } .header { text-align: center; padding: 24px 20px 16px; border-bottom: 1px solid #eee; } .header h1 { font-size: 32px; font-weight: 600; color: #111; margin-bottom: 6px; } .header p { font-size: 16px; color: #666; } .flow-container { flex: 1; width: 100%; } .controls { display: flex; justify-content: center; align-items: center; gap: 16px; padding: 20px; border-top: 1px solid #eee; } .controls button { padding: 12px 28px; font-size: 16px; font-weight: 500; border: 2px solid #222; background: #fff; color: #222; border-radius: 6px; cursor: pointer; transition: all 0.2s; } .controls button:hover:not(:disabled) { background: #222; color: #fff; } .controls button:disabled { opacity: 0.3; cursor: not-allowed; } .controls .reset-btn { border-color: #888; color: #888; } .controls .reset-btn:hover:not(:disabled) { background: #888; color: #fff; } .step-counter { font-size: 16px; color: #666; min-width: 120px; text-align: center; } .instructions { text-align: center; padding: 12px; font-size: 14px; color: #999; } .node-content { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; padding: 8px; } .node-title { font-weight: 600; font-size: 15px; color: #111; margin-bottom: 4px; text-align: center; } .node-description { font-size: 12px; color: #666; text-align: center; } .react-flow__node-default { padding: 0; } .custom-node { width: 240px; height: 70px; background: #ffffff; border: 2px solid #222; border-radius: 8px; display: flex; align-items: center; justify-content: center; } .react-flow__handle { width: 10px; height: 10px; background: #888; border: 2px solid #222; } .react-flow__handle:hover { background: #222; } .note-node { border: 2px dashed #888; border-radius: 6px; padding: 12px 16px; font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Fira Code', monospace; font-size: 11px; line-height: 1.4; color: #333; max-width: 360px; } .note-node pre { margin: 0; white-space: pre-wrap; word-break: break-word; } .react-flow__controls { box-shadow: none; border: 1px solid #ddd; } .react-flow__controls-button { border-bottom: 1px solid #ddd; } .react-flow__controls-button:last-child { border-bottom: none; } ================================================ FILE: flowchart/src/App.tsx ================================================ import { useCallback, useState, useRef } from 'react'; import type { Node, Edge, NodeChange, EdgeChange, Connection } from '@xyflow/react'; import { ReactFlow, useNodesState, useEdgesState, Controls, Background, BackgroundVariant, MarkerType, applyNodeChanges, applyEdgeChanges, addEdge, Handle, Position, reconnectEdge, } from '@xyflow/react'; import '@xyflow/react/dist/style.css'; import './App.css'; const nodeWidth = 240; const nodeHeight = 70; // Setup phase - horizontal at top // Loop phase - circular arrangement below // Exit - at bottom center type Phase = 'setup' | 'loop' | 'decision' | 'done'; const phaseColors: Record = { setup: { bg: '#f0f7ff', border: '#4a90d9' }, loop: { bg: '#f5f5f5', border: '#666666' }, decision: { bg: '#fff8e6', border: '#c9a227' }, done: { bg: '#f0fff4', border: '#38a169' }, }; const allSteps: { id: string; label: string; description: string; phase: Phase }[] = [ // Setup phase (vertical) { id: '1', label: 'You write a PRD', description: 'Define what you want to build', phase: 'setup' }, { id: '2', label: 'Convert to prd.json', description: 'Break into small user stories', phase: 'setup' }, { id: '3', label: 'Run ralph.sh', description: 'Starts the autonomous loop', phase: 'setup' }, // Loop phase { id: '4', label: 'AI picks a story', description: 'Finds next passes: false', phase: 'loop' }, { id: '5', label: 'Implements it', description: 'Writes code, runs tests', phase: 'loop' }, { id: '6', label: 'Commits changes', description: 'If tests pass', phase: 'loop' }, { id: '7', label: 'Updates prd.json', description: 'Sets passes: true', phase: 'loop' }, { id: '8', label: 'Logs to progress.txt', description: 'Saves learnings', phase: 'loop' }, { id: '9', label: 'More stories?', description: '', phase: 'decision' }, // Exit { id: '10', label: 'Done!', description: 'All stories complete', phase: 'done' }, ]; const notes = [ { id: 'note-1', appearsWithStep: 2, position: { x: 340, y: 100 }, color: { bg: '#f5f0ff', border: '#8b5cf6' }, content: `{ "id": "US-001", "title": "Add priority field to database", "acceptanceCriteria": [ "Add priority column to tasks table", "Generate and run migration", "Typecheck passes" ], "passes": false }`, }, { id: 'note-2', appearsWithStep: 8, position: { x: 480, y: 620 }, color: { bg: '#fdf4f0', border: '#c97a50' }, content: `Also updates AGENTS.md with patterns discovered, so future iterations learn from this one.`, }, ]; function CustomNode({ data }: { data: { title: string; description: string; phase: Phase } }) { const colors = phaseColors[data.phase]; return (
{data.title}
{data.description &&
{data.description}
}
); } function NoteNode({ data }: { data: { content: string; color: { bg: string; border: string } } }) { return ( 
{data.content}
); } const nodeTypes = { custom: CustomNode, note: NoteNode }; const positions: { [key: string]: { x: number; y: number } } = { // Vertical setup flow on the left '1': { x: 20, y: 20 }, '2': { x: 80, y: 130 }, '3': { x: 60, y: 250 }, // Loop '4': { x: 40, y: 420 }, '5': { x: 450, y: 300 }, '6': { x: 750, y: 450 }, '7': { x: 470, y: 520 }, '8': { x: 200, y: 620 }, '9': { x: 40, y: 720 }, // Exit '10': { x: 350, y: 880 }, // Notes ...Object.fromEntries(notes.map(n => [n.id, n.position])), }; const edgeConnections: { source: string; target: string; sourceHandle?: string; targetHandle?: string; label?: string }[] = [ // Setup phase (vertical) - bottom to top connections { source: '1', target: '2', sourceHandle: 'bottom', targetHandle: 'top' }, { source: '2', target: '3', sourceHandle: 'bottom', targetHandle: 'top' }, { source: '3', target: '4', sourceHandle: 'bottom', targetHandle: 'top' }, // Loop phase { source: '4', target: '5', sourceHandle: 'right', targetHandle: 'left' }, { source: '5', target: '6', sourceHandle: 'right', targetHandle: 'top' }, { source: '6', target: '7', sourceHandle: 'left-source', targetHandle: 'right-target' }, { source: '7', target: '8', sourceHandle: 'left-source', targetHandle: 'right-target' }, { source: '8', target: '9', sourceHandle: 'left-source', targetHandle: 'right-target' }, { source: '9', target: '4', sourceHandle: 'top-source', targetHandle: 'bottom-target', label: 'Yes' }, // Exit { source: '9', target: '10', sourceHandle: 'bottom', targetHandle: 'top', label: 'No' }, ]; function createNode(step: typeof allSteps[0], visible: boolean, position?: { x: number; y: number }): Node { return { id: step.id, type: 'custom', position: position || positions[step.id], data: { title: step.label, description: step.description, phase: step.phase, }, style: { width: nodeWidth, height: nodeHeight, opacity: visible ? 1 : 0, transition: 'opacity 0.5s ease-in-out', pointerEvents: visible ? 'auto' : 'none', }, }; } function createEdge(conn: typeof edgeConnections[0], visible: boolean): Edge { return { id: `e${conn.source}-${conn.target}`, source: conn.source, target: conn.target, sourceHandle: conn.sourceHandle, targetHandle: conn.targetHandle, label: visible ? conn.label : undefined, animated: visible, style: { stroke: '#222', strokeWidth: 2, opacity: visible ? 1 : 0, transition: 'opacity 0.5s ease-in-out', }, labelStyle: { fill: '#222', fontWeight: 600, fontSize: 14, }, labelShowBg: true, labelBgPadding: [8, 4] as [number, number], labelBgStyle: { fill: '#fff', stroke: '#222', strokeWidth: 1, }, markerEnd: { type: MarkerType.ArrowClosed, color: '#222', }, }; } function createNoteNode(note: typeof notes[0], visible: boolean, position?: { x: number; y: number }): Node { return { id: note.id, type: 'note', position: position || positions[note.id], data: { content: note.content, color: note.color }, style: { opacity: visible ? 1 : 0, transition: 'opacity 0.5s ease-in-out', pointerEvents: visible ? 'auto' : 'none', }, draggable: true, selectable: false, connectable: false, }; } function App() { const [visibleCount, setVisibleCount] = useState(1); const nodePositions = useRef<{ [key: string]: { x: number; y: number } }>({ ...positions }); const getNodes = (count: number) => { const stepNodes = allSteps.map((step, index) => createNode(step, index < count, nodePositions.current[step.id]) ); const noteNodes = notes.map(note => { const noteVisible = count >= note.appearsWithStep; return createNoteNode(note, noteVisible, nodePositions.current[note.id]); }); return [...stepNodes, ...noteNodes]; }; const initialNodes = getNodes(1); const initialEdges = edgeConnections.map((conn, index) => createEdge(conn, index < 0) ); const [nodes, setNodes] = useNodesState(initialNodes); const [edges, setEdges] = useEdgesState(initialEdges); const onNodesChange = useCallback( (changes: NodeChange[]) => { changes.forEach((change) => { if (change.type === 'position' && change.position) { nodePositions.current[change.id] = change.position; } }); setNodes((nds) => applyNodeChanges(changes, nds)); }, [setNodes] ); const onEdgesChange = useCallback( (changes: EdgeChange[]) => { setEdges((eds) => applyEdgeChanges(changes, eds)); }, [setEdges] ); const onConnect = useCallback( (connection: Connection) => { setEdges((eds) => addEdge({ ...connection, animated: true, style: { stroke: '#222', strokeWidth: 2 }, markerEnd: { type: MarkerType.ArrowClosed, color: '#222' } }, eds)); }, [setEdges] ); const onReconnect = useCallback( (oldEdge: Edge, newConnection: Connection) => { setEdges((eds) => reconnectEdge(oldEdge, newConnection, eds)); }, [setEdges] ); const getEdgeVisibility = (conn: typeof edgeConnections[0], visibleStepCount: number) => { const sourceIndex = allSteps.findIndex(s => s.id === conn.source); const targetIndex = allSteps.findIndex(s => s.id === conn.target); return sourceIndex < visibleStepCount && targetIndex < visibleStepCount; }; const handleNext = useCallback(() => { if (visibleCount < allSteps.length) { const newCount = visibleCount + 1; setVisibleCount(newCount); setNodes(getNodes(newCount)); setEdges( edgeConnections.map((conn) => createEdge(conn, getEdgeVisibility(conn, newCount)) ) ); } }, [visibleCount, setNodes, setEdges]); const handlePrev = useCallback(() => { if (visibleCount > 1) { const newCount = visibleCount - 1; setVisibleCount(newCount); setNodes(getNodes(newCount)); setEdges( edgeConnections.map((conn) => createEdge(conn, getEdgeVisibility(conn, newCount)) ) ); } }, [visibleCount, setNodes, setEdges]); const handleReset = useCallback(() => { setVisibleCount(1); nodePositions.current = { ...positions }; setNodes(getNodes(1)); setEdges(edgeConnections.map((conn, index) => createEdge(conn, index < 0))); }, [setNodes, setEdges]); return (

How Ralph Works

Autonomous AI agent loop for completing PRDs

Step {visibleCount} of {allSteps.length}
Click Next to reveal each step
); } export default App; ================================================ FILE: flowchart/src/index.css ================================================ :root { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-synthesis: none; text-rendering: optimizeLegibility; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } body { margin: 0; padding: 0; background: #ffffff; } ================================================ FILE: flowchart/src/main.tsx ================================================ import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import './index.css' import App from './App.tsx' createRoot(document.getElementById('root')!).render( , ) ================================================ FILE: flowchart/tsconfig.app.json ================================================ { "compilerOptions": { "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo", "target": "ES2022", "useDefineForClassFields": true, "lib": ["ES2022", "DOM", "DOM.Iterable"], "module": "ESNext", "types": ["vite/client"], "skipLibCheck": true, /* Bundler mode */ "moduleResolution": "bundler", "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "moduleDetection": "force", "noEmit": true, "jsx": "react-jsx", /* Linting */ "strict": true, "noUnusedLocals": true, "noUnusedParameters": true, "erasableSyntaxOnly": true, "noFallthroughCasesInSwitch": true, "noUncheckedSideEffectImports": true }, "include": ["src"] } ================================================ FILE: flowchart/tsconfig.json ================================================ { "files": [], "references": [ { "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" } ] } ================================================ FILE: flowchart/tsconfig.node.json ================================================ { "compilerOptions": { "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo", "target": "ES2023", "lib": ["ES2023"], "module": "ESNext", "types": ["node"], "skipLibCheck": true, /* Bundler mode */ "moduleResolution": "bundler", "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "moduleDetection": "force", "noEmit": true, /* Linting */ "strict": true, "noUnusedLocals": true, "noUnusedParameters": true, "erasableSyntaxOnly": true, "noFallthroughCasesInSwitch": true, "noUncheckedSideEffectImports": true }, "include": ["vite.config.ts"] } ================================================ FILE: flowchart/vite.config.ts ================================================ import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' // https://vite.dev/config/ export default defineConfig({ plugins: [react()], base: '/ralph/', }) ================================================ FILE: prd.json.example ================================================ { "project": "MyApp", "branchName": "ralph/task-priority", "description": "Task Priority System - Add priority levels to tasks", "userStories": [ { "id": "US-001", "title": "Add priority field to database", "description": "As a developer, I need to store task priority so it persists across sessions.", "acceptanceCriteria": [ "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')", "Generate and run migration successfully", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" }, { "id": "US-002", "title": "Display priority indicator on task cards", "description": "As a user, I want to see task priority at a glance.", "acceptanceCriteria": [ "Each task card shows colored priority badge (red=high, yellow=medium, gray=low)", "Priority visible without hovering or clicking", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 2, "passes": false, "notes": "" }, { "id": "US-003", "title": "Add priority selector to task edit", "description": "As a user, I want to change a task's priority when editing it.", "acceptanceCriteria": [ "Priority dropdown in task edit modal", "Shows current priority as selected", "Saves immediately on selection change", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 3, "passes": false, "notes": "" }, { "id": "US-004", "title": "Filter tasks by priority", "description": "As a user, I want to filter the task list to see only high-priority items.", "acceptanceCriteria": [ "Filter dropdown with options: All | High | Medium | Low", "Filter persists in URL params", "Empty state message when no tasks match filter", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 4, "passes": false, "notes": "" } ] } ================================================ FILE: prompt.md ================================================ # Ralph Agent Instructions You are an autonomous coding agent working on a software project. ## Your Task 1. Read the PRD at `prd.json` (in the same directory as this file) 2. Read the progress log at `progress.txt` (check Codebase Patterns section first) 3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main. 4. Pick the **highest priority** user story where `passes: false` 5. Implement that single user story 6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires) 7. Update AGENTS.md files if you discover reusable patterns (see below) 8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]` 9. Update the PRD to set `passes: true` for the completed story 10. Append your progress to `progress.txt` ## Progress Report Format APPEND to progress.txt (never replace, always append): ``` ## [Date/Time] - [Story ID] Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID - What was implemented - Files changed - **Learnings for future iterations:** - Patterns discovered (e.g., "this codebase uses X for Y") - Gotchas encountered (e.g., "don't forget to update Z when changing W") - Useful context (e.g., "the evaluation panel is in component X") --- ``` Include the thread URL so future iterations can use the `read_thread` tool to reference previous work if needed. The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better. ## Consolidate Patterns If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings: ``` ## Codebase Patterns - Example: Use `sql` template for aggregations - Example: Always use `IF NOT EXISTS` for migrations - Example: Export types from actions.ts for UI components ``` Only add patterns that are **general and reusable**, not story-specific details. ## Update AGENTS.md Files Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files: 1. **Identify directories with edited files** - Look at which directories you modified 2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories 3. **Add valuable learnings** - If you discovered something future developers/agents should know: - API patterns or conventions specific to that module - Gotchas or non-obvious requirements - Dependencies between files - Testing approaches for that area - Configuration or environment requirements **Examples of good AGENTS.md additions:** - "When modifying X, also update Y to keep them in sync" - "This module uses pattern Z for all API calls" - "Tests require the dev server running on PORT 3000" - "Field names must match the template exactly" **Do NOT add:** - Story-specific implementation details - Temporary debugging notes - Information already in progress.txt Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory. ## Quality Requirements - ALL commits must pass your project's quality checks (typecheck, lint, test) - Do NOT commit broken code - Keep changes focused and minimal - Follow existing code patterns ## Browser Testing (Required for Frontend Stories) For any story that changes UI, you MUST verify it works in the browser: 1. Load the `dev-browser` skill 2. Navigate to the relevant page 3. Verify the UI changes work as expected 4. Take a screenshot if helpful for the progress log A frontend story is NOT complete until browser verification passes. ## Stop Condition After completing a user story, check if ALL stories have `passes: true`. If ALL stories are complete and passing, reply with: COMPLETE If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). ## Important - Work on ONE story per iteration - Commit frequently - Keep CI green - Read the Codebase Patterns section in progress.txt before starting ================================================ FILE: ralph.sh ================================================ #!/bin/bash # Ralph Wiggum - Long-running AI agent loop # Usage: ./ralph.sh [--tool amp|claude] [max_iterations] set -e # Parse arguments TOOL="amp" # Default to amp for backwards compatibility MAX_ITERATIONS=10 while [[ $# -gt 0 ]]; do case $1 in --tool) TOOL="$2" shift 2 ;; --tool=*) TOOL="${1#*=}" shift ;; *) # Assume it's max_iterations if it's a number if [[ "$1" =~ ^[0-9]+$ ]]; then MAX_ITERATIONS="$1" fi shift ;; esac done # Validate tool choice if [[ "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then echo "Error: Invalid tool '$TOOL'. Must be 'amp' or 'claude'." exit 1 fi SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PRD_FILE="$SCRIPT_DIR/prd.json" PROGRESS_FILE="$SCRIPT_DIR/progress.txt" ARCHIVE_DIR="$SCRIPT_DIR/archive" LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch" # Archive previous run if branch changed if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "") LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "") if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then # Archive the previous run DATE=$(date +%Y-%m-%d) # Strip "ralph/" prefix from branch name for folder FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||') ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME" echo "Archiving previous run: $LAST_BRANCH" mkdir -p "$ARCHIVE_FOLDER" [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/" [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/" echo " Archived to: $ARCHIVE_FOLDER" # Reset progress file for new run echo "# Ralph Progress Log" > "$PROGRESS_FILE" echo "Started: $(date)" >> "$PROGRESS_FILE" echo "---" >> "$PROGRESS_FILE" fi fi # Track current branch if [ -f "$PRD_FILE" ]; then CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "") if [ -n "$CURRENT_BRANCH" ]; then echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE" fi fi # Initialize progress file if it doesn't exist if [ ! -f "$PROGRESS_FILE" ]; then echo "# Ralph Progress Log" > "$PROGRESS_FILE" echo "Started: $(date)" >> "$PROGRESS_FILE" echo "---" >> "$PROGRESS_FILE" fi echo "Starting Ralph - Tool: $TOOL - Max iterations: $MAX_ITERATIONS" for i in $(seq 1 $MAX_ITERATIONS); do echo "" echo "===============================================================" echo " Ralph Iteration $i of $MAX_ITERATIONS ($TOOL)" echo "===============================================================" # Run the selected tool with the ralph prompt if [[ "$TOOL" == "amp" ]]; then OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true else # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true fi # Check for completion signal if echo "$OUTPUT" | grep -q "COMPLETE"; then echo "" echo "Ralph completed all tasks!" echo "Completed at iteration $i of $MAX_ITERATIONS" exit 0 fi echo "Iteration $i complete. Continuing..." sleep 2 done echo "" echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks." echo "Check $PROGRESS_FILE for status." exit 1 ================================================ FILE: skills/prd/SKILL.md ================================================ --- name: prd description: "Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out." user-invocable: true --- # PRD Generator Create detailed Product Requirements Documents that are clear, actionable, and suitable for implementation. --- ## The Job 1. Receive a feature description from the user 2. Ask 3-5 essential clarifying questions (with lettered options) 3. Generate a structured PRD based on answers 4. Save to `tasks/prd-[feature-name].md` **Important:** Do NOT start implementing. Just create the PRD. --- ## Step 1: Clarifying Questions Ask only critical questions where the initial prompt is ambiguous. Focus on: - **Problem/Goal:** What problem does this solve? - **Core Functionality:** What are the key actions? - **Scope/Boundaries:** What should it NOT do? - **Success Criteria:** How do we know it's done? ### Format Questions Like This: ``` 1. What is the primary goal of this feature? A. Improve user onboarding experience B. Increase user retention C. Reduce support burden D. Other: [please specify] 2. Who is the target user? A. New users only B. Existing users only C. All users D. Admin users only 3. What is the scope? A. Minimal viable version B. Full-featured implementation C. Just the backend/API D. Just the UI ``` This lets users respond with "1A, 2C, 3B" for quick iteration. Remember to indent the options. --- ## Step 2: PRD Structure Generate the PRD with these sections: ### 1. Introduction/Overview Brief description of the feature and the problem it solves. ### 2. Goals Specific, measurable objectives (bullet list). ### 3. User Stories Each story needs: - **Title:** Short descriptive name - **Description:** "As a [user], I want [feature] so that [benefit]" - **Acceptance Criteria:** Verifiable checklist of what "done" means Each story should be small enough to implement in one focused session. **Format:** ```markdown ### US-001: [Title] **Description:** As a [user], I want [feature] so that [benefit]. **Acceptance Criteria:** - [ ] Specific verifiable criterion - [ ] Another criterion - [ ] Typecheck/lint passes - [ ] **[UI stories only]** Verify in browser using dev-browser skill ``` **Important:** - Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good. - **For any story with UI changes:** Always include "Verify in browser using dev-browser skill" as acceptance criteria. This ensures visual verification of frontend work. ### 4. Functional Requirements Numbered list of specific functionalities: - "FR-1: The system must allow users to..." - "FR-2: When a user clicks X, the system must..." Be explicit and unambiguous. ### 5. Non-Goals (Out of Scope) What this feature will NOT include. Critical for managing scope. ### 6. Design Considerations (Optional) - UI/UX requirements - Link to mockups if available - Relevant existing components to reuse ### 7. Technical Considerations (Optional) - Known constraints or dependencies - Integration points with existing systems - Performance requirements ### 8. Success Metrics How will success be measured? - "Reduce time to complete X by 50%" - "Increase conversion rate by 10%" ### 9. Open Questions Remaining questions or areas needing clarification. --- ## Writing for Junior Developers The PRD reader may be a junior developer or AI agent. Therefore: - Be explicit and unambiguous - Avoid jargon or explain it - Provide enough detail to understand purpose and core logic - Number requirements for easy reference - Use concrete examples where helpful --- ## Output - **Format:** Markdown (`.md`) - **Location:** `tasks/` - **Filename:** `prd-[feature-name].md` (kebab-case) --- ## Example PRD ```markdown # PRD: Task Priority System ## Introduction Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering to help users manage their workload effectively. ## Goals - Allow assigning priority (high/medium/low) to any task - Provide clear visual differentiation between priority levels - Enable filtering and sorting by priority - Default new tasks to medium priority ## User Stories ### US-001: Add priority field to database **Description:** As a developer, I need to store task priority so it persists across sessions. **Acceptance Criteria:** - [ ] Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium') - [ ] Generate and run migration successfully - [ ] Typecheck passes ### US-002: Display priority indicator on task cards **Description:** As a user, I want to see task priority at a glance so I know what needs attention first. **Acceptance Criteria:** - [ ] Each task card shows colored priority badge (red=high, yellow=medium, gray=low) - [ ] Priority visible without hovering or clicking - [ ] Typecheck passes - [ ] Verify in browser using dev-browser skill ### US-003: Add priority selector to task edit **Description:** As a user, I want to change a task's priority when editing it. **Acceptance Criteria:** - [ ] Priority dropdown in task edit modal - [ ] Shows current priority as selected - [ ] Saves immediately on selection change - [ ] Typecheck passes - [ ] Verify in browser using dev-browser skill ### US-004: Filter tasks by priority **Description:** As a user, I want to filter the task list to see only high-priority items when I'm focused. **Acceptance Criteria:** - [ ] Filter dropdown with options: All | High | Medium | Low - [ ] Filter persists in URL params - [ ] Empty state message when no tasks match filter - [ ] Typecheck passes - [ ] Verify in browser using dev-browser skill ## Functional Requirements - FR-1: Add `priority` field to tasks table ('high' | 'medium' | 'low', default 'medium') - FR-2: Display colored priority badge on each task card - FR-3: Include priority selector in task edit modal - FR-4: Add priority filter dropdown to task list header - FR-5: Sort by priority within each status column (high to medium to low) ## Non-Goals - No priority-based notifications or reminders - No automatic priority assignment based on due date - No priority inheritance for subtasks ## Technical Considerations - Reuse existing badge component with color variants - Filter state managed via URL search params - Priority stored in database, not computed ## Success Metrics - Users can change priority in under 2 clicks - High-priority tasks immediately visible at top of lists - No regression in task list performance ## Open Questions - Should priority affect task ordering within a column? - Should we add keyboard shortcuts for priority changes? ``` --- ## Checklist Before saving the PRD: - [ ] Asked clarifying questions with lettered options - [ ] Incorporated user's answers - [ ] User stories are small and specific - [ ] Functional requirements are numbered and unambiguous - [ ] Non-goals section defines clear boundaries - [ ] Saved to `tasks/prd-[feature-name].md` ================================================ FILE: skills/ralph/SKILL.md ================================================ --- name: ralph description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json." user-invocable: true --- # Ralph PRD Converter Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution. --- ## The Job Take a PRD (markdown file or text) and convert it to `prd.json` in your ralph directory. --- ## Output Format ```json { "project": "[Project Name]", "branchName": "ralph/[feature-name-kebab-case]", "description": "[Feature description from PRD title/intro]", "userStories": [ { "id": "US-001", "title": "[Story title]", "description": "As a [user], I want [feature] so that [benefit]", "acceptanceCriteria": [ "Criterion 1", "Criterion 2", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" } ] } ``` --- ## Story Size: The Number One Rule **Each story must be completable in ONE Ralph iteration (one context window).** Ralph spawns a fresh Amp instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code. ### Right-sized stories: - Add a database column and migration - Add a UI component to an existing page - Update a server action with new logic - Add a filter dropdown to a list ### Too big (split these): - "Build the entire dashboard" - Split into: schema, queries, UI components, filters - "Add authentication" - Split into: schema, middleware, login UI, session handling - "Refactor the API" - Split into one story per endpoint or pattern **Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big. --- ## Story Ordering: Dependencies First Stories execute in priority order. Earlier stories must not depend on later ones. **Correct order:** 1. Schema/database changes (migrations) 2. Server actions / backend logic 3. UI components that use the backend 4. Dashboard/summary views that aggregate data **Wrong order:** 1. UI component (depends on schema that does not exist yet) 2. Schema change --- ## Acceptance Criteria: Must Be Verifiable Each criterion must be something Ralph can CHECK, not something vague. ### Good criteria (verifiable): - "Add `status` column to tasks table with default 'pending'" - "Filter dropdown has options: All, Active, Completed" - "Clicking delete shows confirmation dialog" - "Typecheck passes" - "Tests pass" ### Bad criteria (vague): - "Works correctly" - "User can do X easily" - "Good UX" - "Handles edge cases" ### Always include as final criterion: ``` "Typecheck passes" ``` For stories with testable logic, also include: ``` "Tests pass" ``` ### For stories that change UI, also include: ``` "Verify in browser using dev-browser skill" ``` Frontend stories are NOT complete until visually verified. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work. --- ## Conversion Rules 1. **Each user story becomes one JSON entry** 2. **IDs**: Sequential (US-001, US-002, etc.) 3. **Priority**: Based on dependency order, then document order 4. **All stories**: `passes: false` and empty `notes` 5. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/` 6. **Always add**: "Typecheck passes" to every story's acceptance criteria --- ## Splitting Large PRDs If a PRD has big features, split them: **Original:** > "Add user notification system" **Split into:** 1. US-001: Add notifications table to database 2. US-002: Create notification service for sending notifications 3. US-003: Add notification bell icon to header 4. US-004: Create notification dropdown panel 5. US-005: Add mark-as-read functionality 6. US-006: Add notification preferences page Each is one focused change that can be completed and verified independently. --- ## Example **Input PRD:** ```markdown # Task Status Feature Add ability to mark tasks with different statuses. ## Requirements - Toggle between pending/in-progress/done on task list - Filter list by status - Show status badge on each task - Persist status in database ``` **Output prd.json:** ```json { "project": "TaskApp", "branchName": "ralph/task-status", "description": "Task Status Feature - Track task progress with status indicators", "userStories": [ { "id": "US-001", "title": "Add status field to tasks table", "description": "As a developer, I need to store task status in the database.", "acceptanceCriteria": [ "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')", "Generate and run migration successfully", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" }, { "id": "US-002", "title": "Display status badge on task cards", "description": "As a user, I want to see task status at a glance.", "acceptanceCriteria": [ "Each task card shows colored status badge", "Badge colors: gray=pending, blue=in_progress, green=done", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 2, "passes": false, "notes": "" }, { "id": "US-003", "title": "Add status toggle to task list rows", "description": "As a user, I want to change task status directly from the list.", "acceptanceCriteria": [ "Each row has status dropdown or toggle", "Changing status saves immediately", "UI updates without page refresh", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 3, "passes": false, "notes": "" }, { "id": "US-004", "title": "Filter tasks by status", "description": "As a user, I want to filter the list to see only certain statuses.", "acceptanceCriteria": [ "Filter dropdown: All | Pending | In Progress | Done", "Filter persists in URL params", "Typecheck passes", "Verify in browser using dev-browser skill" ], "priority": 4, "passes": false, "notes": "" } ] } ``` --- ## Archiving Previous Runs **Before writing a new prd.json, check if there is an existing one from a different feature:** 1. Read the current `prd.json` if it exists 2. Check if `branchName` differs from the new feature's branch name 3. If different AND `progress.txt` has content beyond the header: - Create archive folder: `archive/YYYY-MM-DD-feature-name/` - Copy current `prd.json` and `progress.txt` to archive - Reset `progress.txt` with fresh header **The ralph.sh script handles this automatically** when you run it, but if you are manually updating prd.json between runs, archive first. --- ## Checklist Before Saving Before writing prd.json, verify: - [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first) - [ ] Each story is completable in one iteration (small enough) - [ ] Stories are ordered by dependency (schema to backend to UI) - [ ] Every story has "Typecheck passes" as criterion - [ ] UI stories have "Verify in browser using dev-browser skill" as criterion - [ ] Acceptance criteria are verifiable (not vague) - [ ] No story depends on a later story