Lesson 3: Your First AI Task

Video Walkthrough

Watch the full walkthrough of creating your first task:

Note: Replace the video URL above with your own walkthrough recording. The embed is fully responsive and supports any YouTube or Vimeo URL.

Step 1: Describe the Task

Create a task using the CLI:

rearch task create \
  --description "Add a 404 page that matches the existing design system" \
  --pipeline feature

You can also write the description in a file for longer tasks:

rearch task create --file tasks/add-404-page.md

Example task file (tasks/add-404-page.md):

# Add a 404 Page

Create a custom 404 page for the application.

## Requirements

- Use the existing layout component
- Include a friendly message and illustration
- Add a "Go Home" button that navigates to /
- Match the current design tokens (colors, spacing, typography)
- Page should be accessible (proper heading structure, alt text)

## Files to reference

- src/layouts/MainLayout.astro
- src/styles/tokens/
- src/pages/index.astro (for design reference)

Step 2: Monitor Progress

Once the task is created, the agent begins working. Monitor it in real time:

rearch task watch

You will see output similar to:

Task: Add a 404 page that matches the existing design system
Status: in_progress
Pipeline: feature

[Step 1/5] Reading project context...
  ✓ Scanned 42 files in src/
  ✓ Identified layout: MainLayout.astro
  ✓ Detected design tokens

[Step 2/5] Planning implementation...
  → Creating src/pages/404.astro
  → Modifying src/styles/global.css (adding 404 styles)

[Step 3/5] Writing code...
  ✓ Created src/pages/404.astro (47 lines)
  ✓ Modified src/styles/global.css (+12 lines)

[Step 4/5] Running tests...
  ✓ Build passed
  ✓ Accessibility audit passed

[Step 5/5] Creating pull request...
  ✓ PR #23 created: feat: add custom 404 page

Step 3: Review the Pull Request

The agent creates a pull request with:

A clear title and description
A summary of changes with reasoning
File diffs for each modified/created file
Test results

Open the PR on GitHub and review it like you would any other contribution. You can:

Approve if it looks good
Request changes with comments — the agent will read them and iterate
Close if the approach is wrong and create a new task with different instructions

# Request changes via CLI
rearch task feedback --pr 23 --message "Use the existing ErrorLayout instead of MainLayout"

The agent reads your feedback, updates the code, and pushes a new commit.

Step 4: Merge

Once satisfied, merge the PR as usual:

gh pr merge 23 --squash

Or click “Merge” in the GitHub UI. That is it — your first AI-powered task is complete.

Common Task Patterns

Here are some effective ways to describe tasks:

Bug Fixes

rearch task create --description "Fix: login form submits twice when user double-clicks the submit button. The fix should debounce the submission."

Refactoring

rearch task create --description "Refactor the UserService class to use dependency injection instead of direct imports. Keep all existing tests passing."

Documentation

rearch task create --description "Add JSDoc comments to all exported functions in src/utils/. Follow the existing style in src/utils/format.ts."

Test Coverage

rearch task create --description "Write unit tests for src/services/billing.ts. Cover all public methods, including edge cases for zero amounts and currency conversion."

What’s Next

You have successfully created, monitored, reviewed, and merged your first AI task. In the next lesson, you will learn best practices for getting the most out of ReArch.