Arch

---
name: arch
description: Design a system or feature with the user on bird's architecture Workbench, a browser board, before building it. Use when the user wants to design, architect, sketch, or plan a system, service, feature, pipeline, or data flow, or types /bird:arch. Not for changes whose shape is already obvious.
---

# Design on the board, then build

The Workbench is bird's arch harness on a browser page: boxes and wires,
rival approaches side by side, decisions recorded with the reason the losers
lost, and a picker for the questions the architect needs the user to settle.
The user designs there **with** an architect, which is a separate Claude Code
session that bird spawns. Your job is to dispatch it, wait, and build from
what comes back. Do not design the system yourself in the terminal; that is
what the board is for.

## 1. Compose the task

One paragraph, in plain words: what is being designed, and every constraint
you already know from this conversation: scale, stack, what already exists in
the repo, what the user has ruled out, what they care about. The architect
starts from this text plus the repository itself. It has no other memory of
this conversation, so anything you leave out it will have to ask again.

## 2. Launch it

From the repository root, run this **in the background** (it runs until the
user is done designing, which can be many minutes), quoting the task:

```
bird arch --engine claude --linger 90 --close-when-empty 120 "<task>"
```

The flags matter. `--linger 90` keeps the finished board readable for a
minute and a half after the handoff and then exits, which is what wakes you.
`--close-when-empty 120` ends the run if the user closes the tab without
handing off, so you are never left waiting on a page nobody will reopen.

It prints `page: http://127.0.0.1:<port>/` and opens the browser. Tell the
user the board is open, give them the URL in case no tab appeared (a run
whose page is never opened waits indefinitely), that they should hand off
from the conversation there when they are done (the architect records it
with its `handoff` tool), and that you will pick up from the bundle. Then
wait for the process to exit. Do not poll it, and do not start work that
assumes a design.

If `bird` is not found, it is installed from https://github.com/srujan375/bird.
If it says `claude` is not logged in, the user runs `claude auth login`.

## 3. Read the result

The command's last lines are the contract:

- `handoff: <path>/architecture.md` means the user handed off. Read that
  file. It opens with the problem, then the decisions with their rationale,
  the approaches not taken and why, one sheet per component, the testing
  seams, what is out of scope, and whatever is still open. Summarize the
  settled decisions and the testing seam in a few lines.
- `no handoff: ...` means the page closed before the design was finished.
  Say so, and offer the `--resume` command it printed.

After a handoff, ask the user where to build. Here works from the document.
The `next: claude --resume <id> --system-prompt-snapshot off` line it printed
continues the architect's own conversation instead, which holds everything
that was said and not only what was recorded; offer it for a build that will
lean on the reasoning. It is the user's to run, in a new terminal, from the
same directory, and the flag stays: without it the resumed session keeps the
architect's instructions, which say it never writes code. The board page
shows a "Build it in a terminal" prompt they can copy and paste into that
session to start the build.

The same design is also at `.bird/sessions/<run_id>/bundle/architecture.json`
if you need it as structure rather than prose.

## 4. Build from it

The document's last section, "Building from this", is how to treat each
part of it: settled decisions, approaches not taken, the testing seams, what
is out of scope, and the questions to ask before touching what they gate.
Follow it. It is the same set of rules bird's own code session builds from,
so it is kept in the document rather than here.