From 6af4aa6e62eb123fab7993e1e9d229902f5a8e0e Mon Sep 17 00:00:00 2001
From: fuahyo <fuah566@gmail>
Date: Mon, 12 Jan 2026 11:14:43 +0700
Subject: [PATCH] add optional structured workflow examples for task clarity

---
 README.md                                     |  11 +
 examples/structured-workflow/README.md        |  52 ++++
 .../TASK-BREAKDOWN-GUIDE.md                   | 222 ++++++++++++++++++
 .../example-feature/README.md                 | 117 +++++++++
 examples/structured-workflow/prd.json.example | 155 ++++++++++++
 .../prompt-templates/README.md                |  32 +++
 .../prompt-templates/foundation.md            |  38 +++
 .../prompt-templates/integration.md           |  44 ++++
 .../prompt-templates/interface.md             |  43 ++++
 .../prompt-templates/logic.md                 |  40 ++++
 .../prompt-templates/polish.md                |  43 ++++
 11 files changed, 797 insertions(+)
 create mode 100644 examples/structured-workflow/README.md
 create mode 100644 examples/structured-workflow/TASK-BREAKDOWN-GUIDE.md
 create mode 100644 examples/structured-workflow/example-feature/README.md
 create mode 100644 examples/structured-workflow/prd.json.example
 create mode 100644 examples/structured-workflow/prompt-templates/README.md
 create mode 100644 examples/structured-workflow/prompt-templates/foundation.md
 create mode 100644 examples/structured-workflow/prompt-templates/integration.md
 create mode 100644 examples/structured-workflow/prompt-templates/interface.md
 create mode 100644 examples/structured-workflow/prompt-templates/logic.md
 create mode 100644 examples/structured-workflow/prompt-templates/polish.md

diff --git a/README.md b/README.md
index 67d98d16..12f58af9 100644
--- a/README.md
+++ b/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/`.
diff --git a/examples/structured-workflow/README.md b/examples/structured-workflow/README.md
new file mode 100644
index 00000000..6f51a8f0
--- /dev/null
+++ b/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.
+
diff --git a/examples/structured-workflow/TASK-BREAKDOWN-GUIDE.md b/examples/structured-workflow/TASK-BREAKDOWN-GUIDE.md
new file mode 100644
index 00000000..a9423824
--- /dev/null
+++ b/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.
+
diff --git a/examples/structured-workflow/example-feature/README.md b/examples/structured-workflow/example-feature/README.md
new file mode 100644
index 00000000..8571e7e6
--- /dev/null
+++ b/examples/structured-workflow/example-feature/README.md
@@ -0,0 +1,117 @@
+# Example Feature: Task Comments
+
+This is a complete example showing how structured tasks improve clarity and execution consistency in Ralph.
+
+## The Feature
+
+Add the ability for users to add comments to tasks. Users should be able to:
+- View comments on a task
+- Add new comments
+- See who wrote each comment and when
+- Delete their own comments
+
+## Comparison: Unstructured vs Structured
+
+### Unstructured Approach (Common Mistakes)
+
+A poorly structured PRD might have tasks like:
+
+```json
+{
+  "id": "US-001",
+  "title": "Add comments to tasks",
+  "description": "Users should be able to comment on tasks",
+  "acceptanceCriteria": [
+    "Comments work correctly",
+    "Users can add and view comments"
+  ]
+}
+```
+
+**Problems:**
+- Too vague - what does "work correctly" mean?
+- Too big - database, backend, and UI all in one task
+- No clear verification steps
+- Agent doesn't know where to start
+
+### Structured Approach (This Example)
+
+The structured PRD breaks this into clear phases:
+
+1. **Foundation** - Database schema for comments
+2. **Logic** - Server functions to create/read/delete comments
+3. **Interface** - UI components to display and add comments
+4. **Integration** - Connect UI to backend, handle real-time updates
+5. **Polish** - Error handling, edge cases, permissions
+
+Each task is:
+- **Small** - Completable in one iteration
+- **Specific** - Clear acceptance criteria
+- **Verifiable** - Can check if it's done
+- **Ordered** - Dependencies are obvious
+
+## The Structured PRD
+
+See `prd.json` for the complete structured PRD with:
+- Clear task breakdown by phase
+- Specific acceptance criteria
+- Optional metadata (`stage`, `focus`, `responsibility`)
+- Proper ordering by dependencies
+
+## Key Improvements
+
+### 1. Clear Scope Per Task
+
+Each task has a single, clear responsibility:
+- US-001: Just the database schema
+- US-002: Just the server functions
+- US-003: Just the UI component
+- etc.
+
+The agent knows exactly what to work on.
+
+### 2. Verifiable Acceptance Criteria
+
+Instead of "works correctly", we have:
+- "Create comments table with: id, taskId, userId, content, createdAt"
+- "Component displays list of comments with author name and timestamp"
+- "Clicking delete calls deleteComment service and removes comment from UI"
+
+The agent can verify each step.
+
+### 3. Natural Dependencies
+
+Tasks are ordered so dependencies are obvious:
+- Schema before server functions
+- Server functions before UI
+- UI before integration
+- Integration before polish
+
+Ralph picks tasks by priority, so this ordering ensures correct execution.
+
+### 4. Metadata for Clarity (Optional)
+
+The `stage`, `focus`, and `responsibility` fields help humans understand the task structure. Ralph ignores these fields - they're purely for documentation.
+
+## Running This Example
+
+1. Copy `prd.json` to your project's ralph directory
+2. Run `./scripts/ralph/ralph.sh`
+3. Watch how each iteration picks the next task and completes it
+
+Notice how:
+- Each iteration has clear focus
+- Progress is easy to track
+- Dependencies are handled naturally
+- The agent knows exactly what "done" means
+
+## Takeaways
+
+Structuring tasks well means:
+- **Smaller tasks** - Each fits in one context window
+- **Clear criteria** - Easy to verify completion
+- **Natural order** - Dependencies are obvious
+- **Better outcomes** - Agent stays focused and completes work
+
+You don't need the metadata fields (`stage`, `focus`, `responsibility`) - they're optional. The real value is in breaking work into small, verifiable, ordered tasks.
+
diff --git a/examples/structured-workflow/prd.json.example b/examples/structured-workflow/prd.json.example
new file mode 100644
index 00000000..0fd135f3
--- /dev/null
+++ b/examples/structured-workflow/prd.json.example
@@ -0,0 +1,155 @@
+{
+  "project": "MyApp",
+  "branchName": "ralph/user-notifications",
+  "description": "User Notification System - Allow users to receive and manage notifications",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add notifications table to database",
+      "description": "As a developer, I need to store notifications in the database so they persist across sessions.",
+      "acceptanceCriteria": [
+        "Create notifications table with: id, userId, type, title, message, read, createdAt",
+        "Add foreign key constraint to users table",
+        "Generate and run migration successfully",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "",
+      "stage": "foundation",
+      "focus": "data-model",
+      "responsibility": "schema"
+    },
+    {
+      "id": "US-002",
+      "title": "Create notification service functions",
+      "description": "As a developer, I need functions to create, read, and mark notifications as read.",
+      "acceptanceCriteria": [
+        "Create notification service with: createNotification, getUserNotifications, markAsRead",
+        "All functions properly typed",
+        "Service handles database errors gracefully",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": "",
+      "stage": "logic",
+      "focus": "business-rules",
+      "responsibility": "backend"
+    },
+    {
+      "id": "US-003",
+      "title": "Add notification bell icon to header",
+      "description": "As a user, I want to see a notification indicator in the header so I know when I have new notifications.",
+      "acceptanceCriteria": [
+        "Notification bell icon appears in header next to user menu",
+        "Badge shows unread count when > 0",
+        "Icon is clickable and opens dropdown (placeholder for now)",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": false,
+      "notes": "",
+      "stage": "interface",
+      "focus": "ui-component",
+      "responsibility": "frontend"
+    },
+    {
+      "id": "US-004",
+      "title": "Create notification dropdown panel",
+      "description": "As a user, I want to see my notifications in a dropdown when I click the bell icon.",
+      "acceptanceCriteria": [
+        "Dropdown panel opens when bell is clicked",
+        "Shows list of notifications (title and message)",
+        "Unread notifications visually distinct (bold or background color)",
+        "Empty state message when no notifications",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": false,
+      "notes": "",
+      "stage": "interface",
+      "focus": "ui-component",
+      "responsibility": "frontend"
+    },
+    {
+      "id": "US-005",
+      "title": "Connect notification dropdown to backend",
+      "description": "As a user, I want to see my actual notifications from the database in the dropdown.",
+      "acceptanceCriteria": [
+        "Dropdown fetches notifications from getUserNotifications service",
+        "Notifications display in reverse chronological order (newest first)",
+        "Loading state while fetching",
+        "Error state if fetch fails",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 5,
+      "passes": false,
+      "notes": "",
+      "stage": "integration",
+      "focus": "data-fetching",
+      "responsibility": "frontend"
+    },
+    {
+      "id": "US-006",
+      "title": "Add mark-as-read functionality",
+      "description": "As a user, I want to mark notifications as read when I click on them.",
+      "acceptanceCriteria": [
+        "Clicking a notification calls markAsRead service",
+        "Notification updates to read state immediately (optimistic update)",
+        "Unread count badge updates",
+        "Read notifications no longer show as unread",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 6,
+      "passes": false,
+      "notes": "",
+      "stage": "integration",
+      "focus": "user-interaction",
+      "responsibility": "frontend"
+    },
+    {
+      "id": "US-007",
+      "title": "Handle notification creation events",
+      "description": "As a developer, I need the system to create notifications when relevant events occur.",
+      "acceptanceCriteria": [
+        "Create notification when user receives a message",
+        "Create notification when task is assigned to user",
+        "Notifications created with correct type and content",
+        "Typecheck passes",
+        "Tests pass"
+      ],
+      "priority": 7,
+      "passes": false,
+      "notes": "",
+      "stage": "integration",
+      "focus": "event-handling",
+      "responsibility": "backend"
+    },
+    {
+      "id": "US-008",
+      "title": "Add error handling and edge cases",
+      "description": "As a user, I want the notification system to handle errors gracefully.",
+      "acceptanceCriteria": [
+        "Handle case where user has 100+ notifications (pagination or truncation)",
+        "Handle network errors when fetching notifications",
+        "Handle case where notification is deleted while viewing",
+        "All error states have user-friendly messages",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 8,
+      "passes": false,
+      "notes": "",
+      "stage": "polish",
+      "focus": "error-handling",
+      "responsibility": "full-stack"
+    }
+  ]
+}
+
diff --git a/examples/structured-workflow/prompt-templates/README.md b/examples/structured-workflow/prompt-templates/README.md
new file mode 100644
index 00000000..f3b5fac7
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/README.md
@@ -0,0 +1,32 @@
+# Prompt Templates
+
+Optional prompt snippets you can reference when customizing `prompt.md` for different task types.
+
+**These are suggestions, not requirements.** Ralph works fine with the default `prompt.md`. Use these if you want to add task-type-specific guidance.
+
+## How to Use
+
+1. Read the template that matches your task's `stage` or `focus` (if you're using those metadata fields)
+2. Copy relevant sections into your `prompt.md`
+3. Adapt to your project's conventions
+
+Or ignore these entirely and stick with the default prompt.
+
+## Templates
+
+- **`foundation.md`** - For schema, migrations, data model tasks
+- **`logic.md`** - For business rules, server actions, API endpoints
+- **`interface.md`** - For UI components, forms, displays
+- **`integration.md`** - For connecting pieces, data fetching, event handling
+- **`polish.md`** - For error handling, edge cases, refinement
+
+## Philosophy
+
+These templates emphasize:
+- **Clear scope** - What exactly needs to be done
+- **Verification** - How to know it's complete
+- **Context** - What the agent should read first
+- **Patterns** - What to preserve from existing code
+
+They don't change Ralph's execution model - they just help the agent understand the task better.
+
diff --git a/examples/structured-workflow/prompt-templates/foundation.md b/examples/structured-workflow/prompt-templates/foundation.md
new file mode 100644
index 00000000..304cc3d1
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/foundation.md
@@ -0,0 +1,38 @@
+# Foundation Stage Tasks
+
+Use this guidance for tasks focused on schema, migrations, data models, and core types.
+
+## Before Starting
+
+1. Read existing schema files to understand naming conventions
+2. Check migration history to see the pattern used
+3. Review type definitions to match existing patterns
+
+## Focus Areas
+
+- **Consistency** - Follow existing naming conventions exactly
+- **Types** - Ensure types are properly exported and reusable
+- **Migrations** - Use the same migration pattern as existing ones
+- **Constraints** - Add appropriate foreign keys, indexes, defaults
+
+## Common Patterns to Preserve
+
+- Migration file naming: `YYYYMMDDHHMMSS-description.sql`
+- Type exports: Export types from schema files for reuse
+- Default values: Match existing patterns (e.g., timestamps, enums)
+- Nullability: Follow existing patterns for optional vs required fields
+
+## Verification
+
+- Migration runs without errors
+- Types compile correctly
+- No breaking changes to existing queries (unless intentional)
+- Typecheck passes
+
+## Notes for progress.txt
+
+Document:
+- Any new patterns established
+- Naming conventions discovered
+- Gotchas about the schema (e.g., "field X must be set before Y")
+
diff --git a/examples/structured-workflow/prompt-templates/integration.md b/examples/structured-workflow/prompt-templates/integration.md
new file mode 100644
index 00000000..d31d8546
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/integration.md
@@ -0,0 +1,44 @@
+# Integration Stage Tasks
+
+Use this guidance for tasks focused on connecting pieces, data fetching, event handling, and end-to-end flows.
+
+## Before Starting
+
+1. Read how data fetching is done elsewhere in the codebase
+2. Check existing event handling patterns
+3. Review how different layers connect (UI → API → Database)
+4. Understand state management approach
+
+## Focus Areas
+
+- **Data Flow** - Ensure data flows correctly through layers
+- **State Synchronization** - Keep UI and backend in sync
+- **Error Propagation** - Errors surface correctly to users
+- **Performance** - Avoid unnecessary re-renders or requests
+
+## Common Patterns to Preserve
+
+- Data fetching: Use existing fetch/cache patterns
+- State updates: Follow existing state update patterns
+- Optimistic updates: Match existing optimistic update approach
+- Error handling: Use existing error handling in UI
+- Loading states: Match existing loading patterns
+
+## Verification
+
+- Data appears correctly in UI
+- Updates persist correctly
+- Errors are handled and displayed
+- Loading states work properly
+- No unnecessary network requests
+- Typecheck passes
+- **Verify in browser using dev-browser skill** (required for UI integration)
+
+## Notes for progress.txt
+
+Document:
+- Data flow patterns discovered
+- Gotchas about state synchronization
+- Performance considerations
+- Dependencies between layers
+
diff --git a/examples/structured-workflow/prompt-templates/interface.md b/examples/structured-workflow/prompt-templates/interface.md
new file mode 100644
index 00000000..767bd030
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/interface.md
@@ -0,0 +1,43 @@
+# Interface Stage Tasks
+
+Use this guidance for tasks focused on UI components, forms, displays, and user-facing elements.
+
+## Before Starting
+
+1. Read existing components to understand styling patterns
+2. Check component library or design system being used
+3. Review form patterns if building forms
+4. Look at similar UI elements for consistency
+
+## Focus Areas
+
+- **Visual Consistency** - Match existing UI patterns
+- **Accessibility** - Follow existing a11y patterns
+- **Responsiveness** - Match existing responsive behavior
+- **State Management** - Use existing state management patterns
+
+## Common Patterns to Preserve
+
+- Component structure: Match existing component organization
+- Styling: Use existing CSS/styling approach
+- Form handling: Follow existing form patterns
+- Loading states: Match existing loading indicator patterns
+- Error display: Use existing error message components
+
+## Verification
+
+- Component renders correctly
+- Styling matches existing patterns
+- Interactive elements work (clicks, hovers, etc.)
+- Responsive behavior works on different screen sizes
+- Typecheck passes
+- **Verify in browser using dev-browser skill** (required for all UI tasks)
+
+## Notes for progress.txt
+
+Document:
+- Component patterns discovered
+- Styling conventions
+- Gotchas about the UI framework
+- Dependencies between components
+
diff --git a/examples/structured-workflow/prompt-templates/logic.md b/examples/structured-workflow/prompt-templates/logic.md
new file mode 100644
index 00000000..8ed0e3d4
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/logic.md
@@ -0,0 +1,40 @@
+# Logic Stage Tasks
+
+Use this guidance for tasks focused on business rules, server actions, API endpoints, and backend logic.
+
+## Before Starting
+
+1. Read existing server actions or API routes to understand patterns
+2. Check error handling patterns used elsewhere
+3. Review validation logic to match existing approach
+
+## Focus Areas
+
+- **Business Rules** - Implement logic correctly, handle edge cases
+- **Error Handling** - Use consistent error patterns
+- **Validation** - Validate inputs using existing patterns
+- **Types** - Ensure all inputs/outputs are properly typed
+
+## Common Patterns to Preserve
+
+- Error responses: Match existing error format
+- Validation: Use same validation library/pattern
+- Database queries: Follow existing query patterns
+- Logging: Use existing logging approach (if any)
+
+## Verification
+
+- Logic handles all cases described in acceptance criteria
+- Errors are handled gracefully
+- Input validation works correctly
+- Typecheck passes
+- Tests pass (if tests exist)
+
+## Notes for progress.txt
+
+Document:
+- Business rule gotchas discovered
+- Error handling patterns used
+- Dependencies between functions
+- Performance considerations
+
diff --git a/examples/structured-workflow/prompt-templates/polish.md b/examples/structured-workflow/prompt-templates/polish.md
new file mode 100644
index 00000000..3f0d6151
--- /dev/null
+++ b/examples/structured-workflow/prompt-templates/polish.md
@@ -0,0 +1,43 @@
+# Polish Stage Tasks
+
+Use this guidance for tasks focused on error handling, edge cases, refinement, and final touches.
+
+## Before Starting
+
+1. Review the feature as implemented so far
+2. Check existing error handling patterns
+3. Look for similar edge case handling elsewhere
+4. Review user feedback or requirements for edge cases
+
+## Focus Areas
+
+- **Edge Cases** - Handle boundary conditions and unusual inputs
+- **Error States** - Provide clear error messages and recovery paths
+- **User Experience** - Ensure smooth experience even when things go wrong
+- **Performance** - Optimize for large datasets or slow networks
+
+## Common Patterns to Preserve
+
+- Error messages: Match existing error message style
+- Empty states: Use existing empty state components
+- Loading states: Match existing loading patterns
+- Validation: Use existing validation error display
+- Retry logic: Follow existing retry patterns (if any)
+
+## Verification
+
+- All edge cases from acceptance criteria are handled
+- Error states are user-friendly
+- Performance is acceptable (no obvious slowdowns)
+- No regressions in existing functionality
+- Typecheck passes
+- **Verify in browser using dev-browser skill** (required for UI polish)
+
+## Notes for progress.txt
+
+Document:
+- Edge cases discovered during implementation
+- Error handling patterns used
+- Performance optimizations made
+- Gotchas about edge case handling
+