### Install and Run Flowchart Locally (Bash)

Source: https://github.com/snarktank/ralph/blob/main/AGENTS.md

Installs project dependencies and starts the development server for the flowchart. This is the primary method for local development and viewing the interactive diagram.

```bash
cd flowchart
npm install
npm run dev
```

--------------------------------

### Run Interactive Flowchart with npm

Source: https://context7.com/snarktank/ralph/llms.txt

Launch the React Flow visualization that explains Ralph's workflow with animated step-through. This involves navigating to the directory, installing dependencies, and running the development server or building for production.

```bash
# Navigate to flowchart directory
cd flowchart

# Install dependencies
npm install

# Run development server
npm run dev

# Output:
# VITE v7.2.4  ready in 450 ms
# ➜  Local:   http://localhost:5173/
# ➜  Network: use --host to expose

# Build for production
npm run build

# Output:
# vite v7.2.4 building for production...
# ✓ 245 modules transformed.
# dist/index.html                  0.46 kB │ gzip:  0.30 kB
# dist/assets/index-abc123.css     2.14 kB │ gzip:  0.89 kB
# dist/assets/index-def456.js    142.67 kB │ gzip: 45.82 kB
# ✓ built in 1.23s

# The flowchart displays:
# - 10 workflow steps from PRD creation to completion
# - Color-coded phases: setup (blue), loop (gray), decision (yellow), done (green)
# - Interactive navigation with Previous/Next/Reset buttons
# - Animated edge connections revealing flow
# - Example JSON snippets and learning notes
# - Draggable nodes for custom layout
```

--------------------------------

### Install Ralph Skills Globally (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

Copies the `prd` and `ralph` skills from the Ralph project to your global Amp configuration directory. This makes these skills available across all your projects.

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

--------------------------------

### Configure ESLint for Type-Aware Linting in TypeScript

Source: https://github.com/snarktank/ralph/blob/main/flowchart/README.md

This configuration snippet demonstrates how to expand the ESLint setup for React and TypeScript projects to include type-aware linting rules. It requires installing the `typescript-eslint` plugin and configuring `project` paths in `tsconfig.json` files.

```javascript
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...
    },
  },
])
```

--------------------------------

### Run Flowchart Dev Server (Bash)

Source: https://github.com/snarktank/ralph/blob/main/AGENTS.md

Navigates to the flowchart directory and starts the development server for the interactive React Flow diagram. This command is used for local development and visualization of the Ralph agent's workflow.

```bash
cd flowchart && npm run dev
```

--------------------------------

### Integrate ESLint for React and React DOM Rules

Source: https://github.com/snarktank/ralph/blob/main/flowchart/README.md

This configuration snippet shows how to add `eslint-plugin-react-x` and `eslint-plugin-react-dom` to your ESLint setup for React-specific linting rules. Ensure these plugins are installed as development dependencies.

```javascript
// 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...
    },
  },
])
```

--------------------------------

### Update AGENTS.md with Learnings

Source: https://context7.com/snarktank/ralph/llms.txt

Document reusable patterns discovered during implementation for future iterations. This markdown example shows where to record learnings when editing a specific file.

```markdown
# Example: When editing src/components/TaskCard.tsx

```

--------------------------------

### Autonomous Agent Instructions

Source: https://context7.com/snarktank/ralph/llms.txt

The core prompt template guiding each Ralph iteration. It defines the workflow, quality requirements, and progress reporting format.

```markdown
# Ralph Agent Instructions

You are an autonomous coding agent working on a software project.

## Your Task

1. Read the PRD at `prd.json`
2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
3. Check you're on the correct branch from PRD `branchName`
4. Pick the **highest priority** user story where `passes: false`
5. Implement that single user story
6. Run quality checks (typecheck, lint, test)
7. Update AGENTS.md files if you discover reusable patterns
8. If checks pass, commit with: `feat: [Story ID] - [Story Title]`
9. Update PRD to set `passes: true` for completed story
10. Append progress to `progress.txt`

## Progress Report Format

APPEND to progress.txt:
```
## [Date/Time] - [Story ID]
Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
  - Useful context
---
```

## Stop Condition

If ALL stories have `passes: true`, reply with:
<promise>COMPLETE</promise>
```

--------------------------------

### Acceptance Criteria Examples for Ralph Stories

Source: https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md

Provides examples of verifiable acceptance criteria for user stories within the Ralph system. It distinguishes between good, measurable criteria and vague ones, and specifies essential criteria like 'Typecheck passes' and optional ones like 'Tests pass' or UI verification steps.

```json
"Typecheck passes"
```

```json
"Tests pass"
```

```json
"Verify in browser using dev-browser skill"
```

--------------------------------

### Run Ralph Autonomous Agent (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

Executes the Ralph bash script to start the autonomous AI agent loop. It takes an optional `max_iterations` argument, defaulting to 10. Ralph will iterate through PRD items, implement them, run checks, and commit changes.

```bash
./scripts/ralph/ralph.sh [max_iterations]
```

--------------------------------

### Archive Previous Ralph Run with Bash

Source: https://context7.com/snarktank/ralph/llms.txt

Automatically archives previous PRD and progress files when starting a new feature with a different branch name. This bash script shows manual archiving structure, resetting progress, and tracking the new branch.

```bash
# Archive happens automatically in ralph.sh when:
# - prd.json exists
# - Current branchName differs from .last-branch file
# - progress.txt has content beyond header

# Manual archive structure:
mkdir -p archive/2025-01-12-task-priority
cp prd.json archive/2025-01-12-task-priority/
cp progress.txt archive/2025-01-12-task-priority/

# Reset progress for new feature
echo "# Ralph Progress Log" > progress.txt
echo "Started: $(date)" >> progress.txt
echo "---" >> progress.txt

# Track new branch
echo "ralph/new-feature" > .last-branch

# Archives preserve:
# - Complete prd.json with all story statuses
# - Full progress.txt with learnings and thread URLs
# - Organized by date and feature name
```

--------------------------------

### Component Testing with Mock Context

Source: https://context7.com/snarktank/ralph/llms.txt

Demonstrates how to render a TaskCard component for testing, including the necessary mock authentication context.

```javascript
import { render } from "@testing-library/react";
import TaskCard from "./TaskCard";
import { TestProviders } from "../utils/TestProviders"; // Assuming TestProviders setup mock context

// ... inside a test block ...
render(<TaskCard priority="high" />, { wrapper: TestProviders });
```

--------------------------------

### Build Flowchart (Bash)

Source: https://github.com/snarktank/ralph/blob/main/AGENTS.md

Navigates to the flowchart directory and executes the build script. This command is used to create a production-ready build of the interactive React Flow diagram.

```bash
cd flowchart && npm run build
```

--------------------------------

### Copy Ralph Scripts to Project (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

Copies the `ralph.sh` and `prompt.md` scripts from the Ralph project into a local `scripts/ralph` directory within your project and makes the script executable. This is one method for setting up Ralph.

```bash
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh
```

--------------------------------

### Debug: View Previous Learnings (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

This command displays the content of the 'progress.txt' file, which is used to review learnings from previous iterations of the Ralph project. It helps in understanding historical context and decision-making.

```bash
cat progress.txt
```

--------------------------------

### Configure Amp Auto-Handoff (JSON)

Source: https://github.com/snarktank/ralph/blob/main/README.md

Adds a configuration to `~/.config/amp/settings.json` to enable experimental auto-handoff for Amp. This allows Ralph to handle larger stories that might exceed a single context window by automatically handing off when context fills up.

```json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}
```

--------------------------------

### Generate Product Requirements Document (PRD) with Amp CLI

Source: https://context7.com/snarktank/ralph/llms.txt

Creates a detailed Product Requirements Document (PRD) including clarifying questions, user stories, and acceptance criteria. This is done interactively within an Amp CLI session by loading the 'prd' skill.

```bash
# In Amp CLI session
amp
> Load the prd skill and create a PRD for task priority system

# The skill will ask 3-5 clarifying questions:
# 1. What is the primary goal of this feature?
#    A. Improve user task management
#    B. Enable team prioritization
#    C. Add visual indicators
#    D. Other: [specify]
#
# 2. Who is the target user?
#    A. Individual users only
#    B. Teams with shared tasks
#    C. All users
#
# 3. What is the scope?
#    A. Minimal viable version
#    B. Full-featured implementation

# Respond: 1A, 2C, 3A

# Output saved to tasks/prd-task-priority.md:
# # PRD: Task Priority System
# 
# ## Introduction
# Add priority levels to tasks so users can focus on what matters most...
# 
# ## User Stories
# 
# ### US-001: Add priority field to database
# **Description:** As a developer, I need to store task priority...
# **Acceptance Criteria:**
# - [ ] Add priority column: 'high' | 'medium' | 'low'
# - [ ] Generate and run migration successfully
# - [ ] Typecheck passes

```

--------------------------------

### Run Ralph Agent (Bash)

Source: https://github.com/snarktank/ralph/blob/main/AGENTS.md

Executes the main Ralph agent script. It takes an optional maximum number of iterations as an argument. This script initiates the autonomous AI agent loop.

```bash
./ralph.sh [max_iterations]
```

--------------------------------

### Configure Amp Auto-Handoff with JSON

Source: https://context7.com/snarktank/ralph/llms.txt

Enable automatic context handoff for large stories that exceed a single context window. This JSON configuration sets the experimental autoHandoff context limit.

```json
// ~/.config/amp/settings.json
{
  "amp.experimental.autoHandoff": {
    "context": 90
  }
}

// When context usage reaches 90%, Amp will:
// - Save current state and progress
// - Spawn new Amp instance with context summary
// - Continue working on same story
// - Preserve git history and file changes

// This allows Ralph to handle stories that need:
// - Large codebase exploration
// - Multiple file edits across directories
// - Extensive testing and debugging
// - Complex refactoring
```

--------------------------------

### Query PRD Status with jq

Source: https://context7.com/snarktank/ralph/llms.txt

Check user story completion status from prd.json using jq. This includes viewing all stories, filtering for incomplete ones, and a sample output format. It also shows how to view progress learnings from progress.txt.

```bash
# View story completion status
cat prd.json | jq '.userStories[] | {id, title, passes}'

# Output:
# {
#   "id": "US-001",
#   "title": "Add priority field to database",
#   "passes": true
# }
# {
#   "id": "US-002",
#   "title": "Display priority indicator on task cards",
#   "passes": false
# }

# View only incomplete stories
cat prd.json | jq '.userStories[] | select(.passes == false) | {id, title}'

# View progress learnings
cat progress.txt
```

--------------------------------

### Debug: View Git History (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

This command shows the last 10 commits in the git log, summarized with one line per commit. It's helpful for understanding recent changes and the project's commit history.

```bash
git log --oneline -10
```

--------------------------------

### Run Ralph Autonomous Agent Loop with Bash

Source: https://context7.com/snarktank/ralph/llms.txt

Executes the autonomous agent loop using a bash script. It can run with a default of 10 iterations or a custom limit. The script handles archiving, progress logging, and iterating through Amp CLI commands until tasks are complete or the iteration limit is reached.

```bash
# Run Ralph with default 10 iterations
./ralph.sh

# Run Ralph with custom iteration limit
./ralph.sh 25

# Ralph will:
# - Archive previous run if different branchName
# - Initialize or append to progress.txt
# - Loop through iterations running: cat prompt.md | amp --dangerously-allow-all
# - Check for <promise>COMPLETE</promise> signal
# - Exit with code 0 if complete, code 1 if max iterations reached

# Example output:
# Starting Ralph - Max iterations: 10
# 
# ═══════════════════════════════════════════════════════════
#   Ralph Iteration 1 of 10
# ═══════════════════════════════════════════════════════════
# [Amp output...]
# Iteration 1 complete. Continuing...
# [...]
# Ralph completed all tasks!
# Completed at iteration 3 of 10

```

--------------------------------

### Ralph PRD JSON Output Format

Source: https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md

Defines the structure for prd.json, including project details, branch name, description, and a list of user stories. Each user story has an ID, title, description, acceptance criteria, priority, and status.

```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": ""
    }
  ]
}
```

--------------------------------

### Convert Markdown PRD to Ralph JSON Format with Amp CLI

Source: https://context7.com/snarktank/ralph/llms.txt

Transforms a markdown PRD into the structured JSON format required by Ralph for autonomous execution. The 'ralph' skill in the Amp CLI parses the markdown, extracts stories, orders them by dependency, adds common acceptance criteria, and sets initial pass status.

```bash
# In Amp CLI session
amp
> Load the ralph skill and convert tasks/prd-task-priority.md to prd.json

# The skill will:
# - Parse the markdown PRD
# - Extract user stories with acceptance criteria
# - Order stories by dependencies (schema → backend → UI)
# - Add "Typecheck passes" to all stories
# - Add "Verify in browser using dev-browser skill" to UI stories
# - Set all passes: false
# - Archive previous prd.json if different branchName

# Output: prd.json
{
  "project": "TaskApp",
  "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": ""
    }
  ]
}

```

--------------------------------

### Debug: Check Story Status (Bash)

Source: https://github.com/snarktank/ralph/blob/main/README.md

This snippet uses `jq` to filter and display the 'id', 'title', and 'passes' status of user stories from a 'prd.json' file. It's useful for quickly assessing which stories are marked as completed.

```bash
cat prd.json | jq '.userStories[] | {id, title, passes}'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.