Set up review workspaces

View as markdown

The multi-workspace loop gets finished branches back to you. But reading a diff isn't the same as running the change. Most real review of an app or a site means booting the dev server, opening a URL, and clicking through it.

The routing that gets a task to a review slot is assembled from generic primitives: a workspace carries a tag and a status requires that tag. On top of that, the workflow's review: block tells the Review agent how to boot the branch, and Shelbi's review interface lets you run the change and accept or reject it. This page wires them together end to end. For the model underneath, see the reference: Review workspaces.

You need a working pool first

This page assumes you already have a project with a workspace pool and can promote a task through the board. The first task and multi-workspace pages get you there. A review workspace is an ordinary slot with a tag, not a new kind of thing.

Set up and use the review flow

Tag a workspace for review

Add a review tag to a slot in your project YAML (~/.shelbi/projects/<name>.yaml in global mode, <repo>/.shelbi/project.yaml in-repo). Tag one workspace directly, or tag the machine so every slot on it inherits the tag:

workspaces:
  - { name: alpha,    machine: hub, runner: claude }
  - { name: bravo,    machine: hub, runner: claude }
  - { name: review-0, machine: hub, runner: claude, tags: [review], slot: 3000 }

tags accepts a bare string as shorthand (tags: review). The slot: 3000 sets the numeric slot the review: recipe below resolves $PORT to — so the dev server binds :3000. Leave slot: out and it defaults to the slot's zero-based index among the machine's workspaces, which is why an explicit, port-shaped value is worth setting on a review slot.

One review slot is plenty to start

Each review slot holds one running server bound to its port, so give a second review slot a different slot: value (3010) to avoid a collision. One is enough for a first pass.

Require the tag and add a review: serve recipe

In your workflow file, require the review tag on the review status so tasks route to the tagged slot, then add a review: block telling the Review agent how to boot the branch:

statuses:
  - { id: in-progress, owner: agent, agent: developer }
  - { id: review,      owner: user,  agent: review, tags: [review] }
  - { id: done,        owner: user }
 
transitions:
  - from: review, to: done, actions: [merge, delete_branch]
 
review:
  setup: npm install --no-audit --no-fund
  serve: npm run dev -- -p $PORT
  ready: curl -sf http://localhost:$PORT
  url: http://localhost:$PORT

Shelbi resolves $PORT (equivalently $SLOT) to the review slot's port — 3000 here — and injects the recipe into the Review agent's prompt. The agent runs setup, launches serve, polls ready until the server answers, and hands back the url. Swap the npm lines for whatever your project needs — cargo run, a Makefile target, a Procfile web: line. For a monorepo, add workdir: site (or app, docs) so each workflow serves its own subdirectory on the slot's port.

The review → done transition is the accept edge: it merges the branch and deletes it. Omit the review: block entirely and the Review agent falls back to a diff-only review, booting nothing.

Reload to pick it up

shelbi reload

The tagged slot does not show up under Workspaces — a review slot's capacity surfaces through the review sections instead, and only once a task is routed to it.

Get a task to the review status

Run a task the way you normally would: promote a card and let a dev workspace pick it up, or dispatch one through the orchestrator. When the dev workspace finishes it writes its review-ready marker; the hub poller rebases the branch onto the base branch and moves the task into the Review status.

Because that status requires tags: [review], the orchestrator routes the task onto a free review-tagged slot (preferring the one it ran on) and the Review agent boots the server from the review: recipe. If every matching slot is busy the task waits under Queued for Review until one frees — nothing is preempted.

The finishing dev workspace closes its own session and returns to idle. Its work is now waiting to be run, not edited.

Open the review interface and click through

The task appears in the sidebar under Ready for Review (✓) with a machine:workspace badge showing the slot it's loaded on. Select it (or press Enter on its row) to open the review interface: a two-column layout with the review panel on the left (its own navigation, with a back button at the top that returns you to the dashboard) and the swappable review content on the right.

you@hub — myapp

 myapp                        
                              
 💬 Chat                       
 📋 Tasks                      
 ⚡ Activity                   
                              
 — Workspaces —               
 ▾ hub                        
   ⏵ alpha          Developer 
   · bravo               idle 
                              
 — Ready for Review —         
 ✓ Polish dark-… hub:review-0 
   jlong/dark-mode-toggle-pol…
                              
 — Queued for Review —        
 · Validate webhook payloads  
   shelbi/validate-webhook-pa…
 · Harden token refresh       
   shelbi/harden-token-refresh
 ^P palette  q quit           
                              
 ZEN MODE ON

 Tasks · myapp   1 total                                                     Workflow: All ▾  Workspace: All ▾ 
                                                                                                               
 BACKLOG (0)           TO DO (0)             IN PROGRESS (0)       REVIEW (1)            DONE (0)              
                                                                   Polish dark-mode                            
                                                                   toggle                                      
                                                                    app  ⎇ shelbi/polish…                      
                                                                                                               
  h/l col   j/k row   ⏎ open   n new   f filter   r refresh

From the review panel you can:

🤓 Chat with Reviewer — talk to the Review agent (the default view).
🔀 View Diff — open your system diff tool over the review branch's changes in the main pane. This uses git's configured diff tool (diff.tool, or diff.guitool for a GUI tool); if none is configured the panel shows a short error instead of launching.
✍️ Edit in <editor> — open the review worktree in your configured editor.
🌐 Open Browser — open the served url in your system browser. This action only appears when the workflow declares a review URL.

The built-in review agent's charter is narrow: load and serve, don't code. It won't modify the branch or move the card. Point agent: at an agent you've authored to change what runs there.

Approve or reject

You own the decision, and you make it from the review panel's Actions:

✅ Approve — moves the card one column forward (review → done), firing that edge's actions: per the workflow above, it merges the branch and deletes it. The interface tears down and focus returns to the dashboard.
❌ Reject — opens a type-the-reason dialog. On submit, the reason is appended to the task body and the card bounces back to the ready status for another pass. An empty reason can't submit.

Either decision frees the review slot for the next task routed for review, if any.

Routing a task to a review workspace is the human path: the whole point is human eyes on the running app. Keeping merge on the accept edge and off the enter-review edge means the orchestrator holds a review task for you rather than auto-merging it. When you're ready to hand the orchestrator the cases it can judge on its own, enable Zen Mode to auto-promote backlog and auto-merge finished branches that clear a confidence bar you define.