Example: Using Urist to Build a Feature

This guide walks through a typical workflow for using urist to automate feature development.

Step 1: Define a Plan with Claude

Start by working with Claude (via Claude CLI or claude.ai) to define what you want to build. Discuss requirements, architecture decisions, and break the work into discrete tasks.

Example conversation:

You: I want to add a dark mode toggle to my React app. Help me plan this.

Claude: Here's a plan for adding dark mode:

1. Create a ThemeContext to manage theme state
2. Add a ThemeProvider wrapper component
3. Create a DarkModeToggle button component
4. Update CSS variables for light/dark themes
5. Persist theme preference to localStorage
6. Add theme toggle to the settings page

Step 2: Convert the Plan to a PRD

Ask Claude to convert your plan into urist's PRD format. Use urist get-schema to show Claude the expected structure:

urist get-schema

This outputs the JSON schema. Share it with Claude:

You: Convert our dark mode plan to this PRD format:

<paste schema here>

Claude: Here's your prd.json:

[
  {
    "category": "feature",
    "description": "Create ThemeContext to manage theme state globally",
    "steps": [
      "Create src/contexts/ThemeContext.tsx",
      "Define ThemeContext with light/dark values",
      "Export useTheme hook for consuming components"
    ],
    "successCriteria": [
      "ThemeContext exports provider and hook",
      "TypeScript compiles without errors"
    ],
    "passes": false
  },
  {
    "category": "feature",
    "description": "Add ThemeProvider wrapper to app root",
    "steps": [
      "Import ThemeProvider in App.tsx",
      "Wrap app content with ThemeProvider",
      "Verify context is accessible in child components"
    ],
    "successCriteria": [
      "App renders without errors",
      "useTheme hook returns current theme"
    ],
    "passes": false
  },
  {
    "category": "feature",
    "description": "Create DarkModeToggle button component",
    "steps": [
      "Create src/components/DarkModeToggle.tsx",
      "Use useTheme hook to get/set theme",
      "Add sun/moon icons for visual feedback"
    ],
    "successCriteria": [
      "Toggle switches between light and dark",
      "Component is accessible (has aria-label)"
    ],
    "passes": false
  },
  {
    "category": "feature",
    "description": "Implement CSS variables for theming",
    "steps": [
      "Define CSS variables in :root for light theme",
      "Add [data-theme='dark'] selector with dark values",
      "Update existing styles to use CSS variables"
    ],
    "successCriteria": [
      "Colors change when data-theme attribute changes",
      "No hardcoded colors remain in components"
    ],
    "passes": false
  },
  {
    "category": "feature",
    "description": "Persist theme preference to localStorage",
    "steps": [
      "Save theme to localStorage on change",
      "Read theme from localStorage on app load",
      "Respect system preference as default"
    ],
    "successCriteria": [
      "Theme persists across page refreshes",
      "System preference is used when no saved preference"
    ],
    "passes": false
  },
  {
    "category": "feature",
    "description": "Add theme toggle to settings page",
    "steps": [
      "Import DarkModeToggle in SettingsPage",
      "Add toggle with appropriate label",
      "Style consistently with other settings"
    ],
    "successCriteria": [
      "Toggle appears in settings",
      "Settings page tests pass"
    ],
    "passes": false
  }
]

Save this as prd.json in your project root.

Step 3: Run Urist

Create an empty progress file and run urist:

touch progress.txt
urist run 6

Urist will:

• Pick the first incomplete task
• Invoke Claude to implement it
• Run validation (typecheck, lint, tests)
• Mark the task as complete in prd.json
• Append notes to progress.txt
• Commit the changes
• Move to the next task

Watch the progress:

[model: claude-sonnet-4-20250514]
[thinking...]
[tool: Read]
[tool: Write]
[tool: Bash]
[done: $0.0312, 62.1s]

Tips

• Start small: Break work into tasks that can be completed in a single iteration
• Be specific: Include file paths and concrete success criteria
• Use --debug: If something goes wrong, run with --debug to see full output
• Check progress.txt: Contains notes from each iteration for context
• Preview prompts: Use urist get-next-prompt to see what Claude will receive