Agents

Give agents the source: the file that renders, in your repo.

Against a package, an agent sees types and docs. When the API doesn't fit, it adds a wrapper or an override. With Shelf, it reads the file that renders and changes that.

What an agent can read

The implementation: Markup, behavior wiring, and every variant, in one normal React file.
The styles: StyleX next to the markup, using semantic tokens it can look up.
Local changes: shelf check lists which files your team already modified.
The catalog: shelf search finds an existing component before the agent builds a new one.

The loop

the agent loop

┌────────┐   ┌─────┐   ┌──────┐   ┌────────┐   ┌─────────────┐   ┌──────┐
│ search ├──▶│ add ├──▶│ read ├──▶│ change ├──▶│ shelf check ├──▶│ ship │
└────────┘   └─────┘   └──────┘   └────▲───┘   └──────┬──────┘   └──────┘
                                       │              │
                                       └──── fix ─────┘

The agent loop: search, add, read, change, shelf check, and ship. A failing check loops back to change.

Every step is a command with short, stable output and no prompts. A failing check names the file and what to run, so the agent can fix it and check again.

An example

terminal

> Add a confirm step before deleting a project.

$ shelf search dialog
  alert-dialog  component   A modal that asks the user to confirm or cancel; ...
  dialog        component   A modal window composed from Root, Trigger, ...

$ shelf add alert-dialog
  ✓ resolved alert-dialog, foundations, utils
  ✓ added 1 file
  ✓ recorded provenance in .shelf/lock.json

  Alert Dialog is now yours.
    src/components/ui/alert-dialog.tsx

~ edits src/components/ui/alert-dialog.tsx

$ shelf check
  ✓ config       registry ../../registry
  ✓ provenance   6 items, 9 files, 1 modified locally
      ~ src/components/ui/alert-dialog.tsx (alert-dialog, modified locally)
  ✓ dependencies 5 packages declared, Shelf dependencies installed
  ✓ imports      11 local imports resolve

  ✓ All checks passed

An agent adds a confirm step: it searches Shelf, adds Alert Dialog, edits it, and shelf check passes with one file modified locally.

The output above is real. The agent found Alert Dialog instead of building a modal, added it, changed it, and got a passing check that lists the change.

Tell your agent

Add a line to your AGENTS.md or rules file: search Shelf with shelf search before creating UI, add what exists with shelf add, and run shelf check before finishing.

What comes next

Today, when shelf update leaves conflict markers, an agent resolves them with shelf diff --local for context, and shelf check fails until none are left. Planned, not available yet: stories and tests alongside each version, and visual feedback that says what changed.