dff2d358f6
New users were confused about which files they write vs. which Ralph manages, and how PROMPT.md, specs/, and fix_plan.md relate to each other. Added: - docs/user-guide/ with quick start tutorial, file reference, and requirements writing guide - examples/simple-cli-tool/ showing minimal Ralph configuration - examples/rest-api/ demonstrating when to use specs/ - README section explaining Ralph files and their relationships Also documents specs/stdlib/ purpose for reusable patterns.
68 lines
1.7 KiB
Markdown
68 lines
1.7 KiB
Markdown
# Example: Simple CLI Tool
|
|
|
|
This example shows a minimal Ralph configuration for a command-line todo application built with Node.js.
|
|
|
|
## What This Example Demonstrates
|
|
|
|
- **Minimal PROMPT.md** - Just enough context for a focused project
|
|
- **Specific fix_plan.md** - Concrete, actionable tasks
|
|
- **No specs/ needed** - Simple enough that PROMPT.md covers everything
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
simple-cli-tool/
|
|
├── .ralph/
|
|
│ ├── PROMPT.md # Project goals and principles
|
|
│ └── fix_plan.md # Task list
|
|
├── .ralphrc # Configuration (auto-generated)
|
|
└── README.md # This file
|
|
```
|
|
|
|
## How to Use This Example
|
|
|
|
1. Copy this directory to a new location:
|
|
```bash
|
|
cp -r examples/simple-cli-tool ~/my-todo-app
|
|
cd ~/my-todo-app
|
|
```
|
|
|
|
2. Initialize git and npm:
|
|
```bash
|
|
git init
|
|
npm init -y
|
|
```
|
|
|
|
3. Run Ralph:
|
|
```bash
|
|
ralph --monitor
|
|
```
|
|
|
|
## Key Points
|
|
|
|
### PROMPT.md is Focused
|
|
|
|
Notice how PROMPT.md:
|
|
- States exactly what the tool should do
|
|
- Specifies the technology (Node.js, commander.js)
|
|
- Defines key behaviors (where data is stored, error handling)
|
|
|
|
### fix_plan.md Uses Priorities
|
|
|
|
Tasks are grouped by priority:
|
|
- Priority 1: Foundation (must work before anything else)
|
|
- Priority 2: Core features (the main functionality)
|
|
- Priority 3: Polish (nice-to-have improvements)
|
|
|
|
### No specs/ Directory
|
|
|
|
This project is simple enough that PROMPT.md provides all necessary context. specs/ would be overkill here.
|
|
|
|
## When to Add More Files
|
|
|
|
Consider adding specs/ if you need:
|
|
- Complex command behavior documentation
|
|
- Data format specifications
|
|
- External service integration details
|
|
|
|
For this simple example, PROMPT.md is sufficient.
|