Skip to content
ttorta docs

Quick Start

Your first ticket

From the created workspace to a ticket in done, one screen at a time.

1. The workspace exists

Torta wrote a folder at the location you chose, holding torta.json, one home per agent under .agents/, one project folder per agent under .projects/, and the queues each agent works from. The workspace layout page has the map. Every queue is empty: nothing exists until you have asked for it.

If you adopted a folder instead, that folder is the workspace and it holds the same things, plus ADOPTED.md saying what moved. Each project is under .projects/, in the folder its owner keeps work in, with its git history. Everything below is the same from here on.

2. The board

Four tabs across the top:

  • board: to-do, doing and done for every agent. With nothing queued it says so in one line, and names the agent to go and talk to.
  • needs you: decisions waiting on you, as plain questions.
  • settings: one row per account, with a tick or the exact step to fix it.
  • terminal: a pane per agent, to watch it work and talk to it.

The header says engine running, with pause beside it.

3. Say what you want built

The terminal panel is already open on the agent that takes requests, and that agent speaks first: it asks what you want built. Answer in your own words. It interviews you for three things, one at a time:

  1. What it should do, as behaviour you would notice using the product.
  2. Why it matters, in a sentence.
  3. The one number that settles whether it worked.

Rough answers are fine; it sharpens them with you. Then it authors the ticket through ticket.py, the same path every ticket takes, so the ticket is numbered, linted, given a ## History row and published into the gate’s queue by atomic rename. There is no second way to create one.

If the answer is that the product already does it, or that it is not worth doing, it tells you and writes nothing. Keeping noise out of the queues is half of what a front door is for.

4. Approve the ticket

Open needs you. The ticket is there, asking:

Approve this before it gets built?

That question is the prompt on the REVIEW status in the workflow schema; every user-facing status has one. Press approve.

Approving moves the ticket from REVIEW to APPROVED. Rejecting sends it back to its author as REDO.

5. Watch it get built

The engine dispatches approved work. An agent takes the ticket up, its status becomes WIP, and the work appears in that agent’s pane on the terminal tab. The pane is a real Claude Code session in the agent’s own home.

Approving starts nothing if no engine is running. torta start runs one for you; torta board does not.

6. It lands in done

Finished work ends in the agent’s done column. When the agent cannot finish, it asks you back in needs you, in one of four statuses:

  • BLOCKED: a hard constraint, or a budget that ran out mid-build.
  • NOT_FEASIBLE: it cannot be built the way it was described.
  • FOR_DEPLOY: ready to go live, and it wants your yes.
  • SPEC: a slice of a bigger plan wants ruling on before a builder sees it.

7. Stop, and come back

Ctrl-C in the terminal you started torta in stops the board, the engine and every pane.

To open it again, point torta at the folder it made:

torta start ~/Documents/projects/my-project

It picks up where you left off. There is no reattach across restarts: panes close with the board, and the next board opens fresh ones.