Add optional structured-workflow examples for clearer task execution

README.md

@@ -186,6 +186,17 @@ Edit `prompt.md` to customize Ralph's behavior for your project:
 - Include codebase conventions
 - Add common gotchas for your stack
 
+## Structured Workflow Examples (Optional)
+
+The `examples/structured-workflow/` directory contains optional examples and templates that help structure work more effectively:
+
+- **`TASK-BREAKDOWN-GUIDE.md`** - Practical guide to breaking work into phases that fit Ralph's execution model
+- **`prd.json.example`** - Shows optional metadata fields (`stage`, `focus`, `responsibility`) for organizing tasks
+- **`prompt-templates/`** - Optional snippets for customizing `prompt.md` by task type
+- **`example-feature/`** - Complete end-to-end example demonstrating structured tasks
+
+These are purely additive and optional. Ralph works perfectly without them. Use them if you want guidance on structuring tasks, or ignore them if you prefer a simpler approach.
+
 ## Archiving
 
 Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.

examples/structured-workflow/README.md

@@ -0,0 +1,52 @@
+# Structured Workflow for Ralph
+
+This directory contains optional examples and templates that help structure work more effectively in Ralph, while preserving Ralph's minimal philosophy.
+
+**Everything here is optional and additive.** You can use Ralph perfectly fine without any of this. These examples exist to help you think about how to break work into tasks that fit naturally into Ralph's one-agent, one-task, one-iteration loop.
+
+## Philosophy
+
+Ralph executes tasks. It doesn't orchestrate workflows. The structure comes from how you define tasks, not from complex logic in the execution loop.
+
+When tasks are well-structured:
+- Each iteration has clear focus
+- Dependencies are obvious from task order
+- The agent knows exactly what "done" means
+- Progress is easy to track
+
+When tasks are poorly structured:
+- The agent gets confused about scope
+- Context runs out before completion
+- Dependencies cause failures
+- Progress is unclear
+
+## The Approach
+
+Break work into phases that naturally flow from one to the next:
+
+1. **Foundation** - Schema, data structures, core types
+2. **Logic** - Business rules, server actions, API endpoints
+3. **Interface** - UI components, forms, displays
+4. **Integration** - Connecting pieces, end-to-end flows
+5. **Polish** - Edge cases, error handling, refinement
+
+Each phase contains multiple small tasks. Tasks within a phase can often be done in parallel (Ralph picks by priority), but phases should generally be ordered.
+
+## Files in This Directory
+
+- **`prd.json.example`** - Example PRD with optional metadata fields (`stage`, `focus`, `responsibility`) that help organize tasks without changing how Ralph runs
+- **`prompt-templates/`** - Optional prompt snippets you can reference when customizing `prompt.md` for different task types
+- **`example-feature/`** - A complete end-to-end example showing how structured tasks improve clarity
+
+## Using These Examples
+
+1. **Read the example PRD** to see how metadata can help organize tasks
+2. **Review the prompt templates** if you want to customize behavior by task type
+3. **Study the example feature** to see the pattern in practice
+
+Then adapt these ideas to your own work. The metadata fields are optional - Ralph will work with or without them. The prompt templates are suggestions - use them, modify them, or ignore them.
+
+## Key Principle
+
+**Ralph remains a task executor.** These examples show how to structure tasks better, not how to change Ralph's execution model. If you find yourself wanting to modify `ralph.sh` or add orchestration logic, step back and reconsider your task structure instead.
+

examples/structured-workflow/TASK-BREAKDOWN-GUIDE.md

@@ -0,0 +1,222 @@
+# Task Breakdown Guide
+
+A practical guide to breaking work into tasks that fit naturally into Ralph's execution model.
+
+## The Core Principle
+
+**Each task should be completable in one Ralph iteration (one context window).**
+
+Ralph spawns a fresh agent instance per iteration. If a task is too big, the agent runs out of context before finishing and produces broken code.
+
+## The Phased Approach
+
+Break work into phases that flow naturally:
+
+### Phase 1: Foundation
+**What:** Schema, data structures, core types, migrations
+
+**Examples:**
+- Add a database column and migration
+- Create a new table
+- Define TypeScript types/interfaces
+- Set up configuration files
+
+**Characteristics:**
+- No dependencies on other work
+- Changes are structural, not behavioral
+- Easy to verify (migration runs, types compile)
+
+### Phase 2: Logic
+**What:** Business rules, server actions, API endpoints, core functions
+
+**Examples:**
+- Create a service function to process data
+- Add validation logic
+- Implement a calculation or transformation
+- Create an API endpoint
+
+**Characteristics:**
+- Depends on foundation (uses schema/types)
+- Changes are behavioral, not visual
+- Verifiable with tests or manual testing
+
+### Phase 3: Interface
+**What:** UI components, forms, displays, user-facing elements
+
+**Examples:**
+- Create a component to display data
+- Add a form for user input
+- Build a dropdown or filter
+- Create a modal or dialog
+
+**Characteristics:**
+- May depend on logic (calls services)
+- Changes are visual and interactive
+- Requires browser verification
+
+### Phase 4: Integration
+**What:** Connecting pieces, data fetching, event handling, end-to-end flows
+
+**Examples:**
+- Connect UI component to backend service
+- Add data fetching to a page
+- Handle user interactions (clicks, form submissions)
+- Wire up real-time updates
+
+**Characteristics:**
+- Depends on both logic and interface
+- Makes the feature actually work end-to-end
+- Requires browser verification
+
+### Phase 5: Polish
+**What:** Error handling, edge cases, refinement, final touches
+
+**Examples:**
+- Handle network errors gracefully
+- Add loading states
+- Handle empty states
+- Optimize performance
+- Add accessibility improvements
+
+**Characteristics:**
+- Depends on integration being complete
+- Improves robustness and user experience
+- Often involves testing edge cases
+
+## Task Sizing Rules
+
+### Right-Sized Tasks
+
+A task is right-sized if you can:
+1. Describe what needs to be done in 2-3 sentences
+2. List 3-5 specific acceptance criteria
+3. Complete it in one focused session
+4. Verify it's done without ambiguity
+
+**Examples:**
+- ✅ "Add priority column to tasks table with migration"
+- ✅ "Create service function to get user notifications"
+- ✅ "Add notification bell icon to header with unread count badge"
+- ✅ "Connect notification dropdown to backend service"
+
+### Tasks That Are Too Big
+
+If you find yourself saying "and then" or "also need to", the task is too big.
+
+**Examples:**
+- ❌ "Add authentication system" → Split into: schema, middleware, login UI, session handling
+- ❌ "Build the dashboard" → Split into: data queries, chart components, filters, layout
+- ❌ "Refactor the API" → Split into one task per endpoint or pattern
+
+**How to split:**
+1. Identify the distinct pieces
+2. Order them by dependencies
+3. Make each piece its own task
+4. Ensure each task is independently verifiable
+
+## Dependency Ordering
+
+Tasks should be ordered so that:
+- Earlier tasks don't depend on later ones
+- Dependencies are obvious from the task order
+- Ralph can pick tasks by priority without breaking things
+
+**Correct order:**
+1. Schema changes (foundation)
+2. Server functions (logic)
+3. UI components (interface)
+4. Connecting them (integration)
+5. Error handling (polish)
+
+**Wrong order:**
+1. UI component (needs schema that doesn't exist)
+2. Schema change
+3. Server function
+
+## Acceptance Criteria
+
+Each task needs verifiable acceptance criteria. "Works correctly" is not verifiable. "Button shows confirmation dialog before deleting" is verifiable.
+
+### Good Criteria
+
+- Specific and measurable
+- Can be checked automatically or manually
+- Clear pass/fail condition
+- Includes quality checks (typecheck, tests)
+
+**Examples:**
+- "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"
+- "Verify in browser using dev-browser skill" (for UI tasks)
+
+### Bad Criteria
+
+- Vague or subjective
+- Cannot be verified
+- No clear completion condition
+
+**Examples:**
+- "Works correctly"
+- "User can do X easily"
+- "Good UX"
+- "Handles edge cases" (too vague - which edge cases?)
+
+## Metadata Fields (Optional)
+
+You can add optional metadata to tasks for documentation:
+
+- `stage`: "foundation" | "logic" | "interface" | "integration" | "polish"
+- `focus`: More specific focus area (e.g., "data-model", "ui-component", "error-handling")
+- `responsibility`: "schema" | "backend" | "frontend" | "full-stack"
+
+**Important:** Ralph ignores these fields. They're purely for human understanding. The task will work identically with or without them.
+
+## Example: Breaking Down a Feature
+
+**Feature:** "Add user notifications"
+
+**Unstructured (too big):**
+- "Add notification system"
+
+**Structured (right-sized):**
+
+1. **Foundation:** Add notifications table to database
+2. **Logic:** Create notification service functions
+3. **Interface:** Add notification bell icon to header
+4. **Interface:** Create notification dropdown panel
+5. **Integration:** Connect dropdown to backend service
+6. **Integration:** Add mark-as-read functionality
+7. **Integration:** Handle notification creation events
+8. **Polish:** Add error handling and edge cases
+
+Each task is:
+- Small enough for one iteration
+- Clearly verifiable
+- Properly ordered by dependencies
+- Independently completable
+
+## Checklist
+
+Before adding a task to your PRD, verify:
+
+- [ ] Task can be completed in one context window
+- [ ] Task has 3-5 specific acceptance criteria
+- [ ] All criteria are verifiable (not vague)
+- [ ] Task doesn't depend on later tasks
+- [ ] Task includes quality checks (typecheck, tests if applicable)
+- [ ] UI tasks include browser verification requirement
+
+## Remember
+
+Ralph executes tasks. Structure comes from task definition, not from orchestration. Well-structured tasks lead to better outcomes because:
+
+- The agent has clear focus
+- Progress is easy to track
+- Dependencies are obvious
+- Completion is verifiable
+
+Keep tasks small, specific, and ordered. That's the key to effective Ralph usage.
+