Lines, stations and tasks
Spotlight organises a team's work as lines. A line is the series of steps a unit of work goes through, such as triage, writing a spec, building it and reviewing the code. Each step is a station, and each unit of work is a task. A task is always at exactly one station.
At most stations an AI coding agent does the work. The station says which coding tool the agent uses, such as Claude Code (Spotlight calls this the station's harness), what the agent is told to do (its prompt), and which tools and skills it may use. When a task arrives at one of these stations, an agent works on it. One session of an agent working on a task at a station is a run.
The shape of a line
Every line starts with a backlog and ends with a completed station, and no agent works at either. The backlog is where tasks wait until someone starts them. Completed is where tasks go when the line is done with them. Between the two are the work stations, where agents work, and each one lists the stations it may pass a task on to.
A workspace created in the web app starts its first team with two lines (see
Built-in lines). Delivery takes a
request from Triage, through Spec and Implementation, to Code Review, which
opens a pull request. Review looks over a pull request someone else opened. Both are
ordinary lines: a team can change them, or define new lines the same way (see
the spotlight_line reference).
Those lists of which station may pass to which give a line its shape. Delivery's Code Review may send a task back to Implementation or to Spec, and Implementation may send it back to Spec, so a line can loop back on itself instead of running in a straight row. Spotlight also uses this shape to decide which run goes first.
The agent decides where the task goes next
When an agent finishes its work, it says what should happen to the task next.
It does this with one command, spotlight handover, run from inside its
sandbox, the container the agent works in. It has three choices:
- Pass the task on to one of the stations this station may pass to. The task moves there, and a new run is queued right away. Only a station with an agent can take a task this way.
- Ask a person. The task stays where it is and waits in the inbox of the person it is assigned to, or of the person who raised it if nobody is assigned.
- At a station allowed to finish tasks, such as Code Review, finish the task where it stands.
Spotlight checks the choice while the agent can still correct it. If the agent names a station it can't pass to, the command refuses and lists the ones it can. Why agents talk back through a command line explains why this is a command.
If an agent says nothing, fails, or is stopped, Spotlight treats that as a question for a person, with a note saying what happened.
So one task can travel the whole of Delivery without anyone touching it. Triage passes it to Spec, Spec to Implementation, Implementation to Code Review, and Code Review opens a pull request and finishes. People come in where an agent asks for them, or where they choose to step in.
What travels with the task
Each station's agent starts with no memory of the stations before it, so something has to carry the work forward. That something is the note each agent leaves when it hands the task on. Every note is kept on the task, and the next station's agent is given all of them, station by station, as what has already been done.
Spotlight passes on these notes, not everything the earlier agents said and did. That record is long, and by the third station the part that matters would be buried. A note is the previous agent's own summary of what the next one needs to know.
Code travels with the task too. A task keeps one set of working files from its first station to its last: the line's repositories with the task's own branch checked out. Each station's agent finds them as the last agent left them, including changes that were never committed. The branch is how the code reaches GitHub. On Delivery, Implementation pushes the branch before it hands on. On Review, the files are the pull request under review, not a branch of the task's own.
The conversation stays behind. A station's agent carries on its own earlier conversation only when the station takes the task up again while the task is still there, for example after a person answers its question. How a conversation survives between runs covers the files and the conversation.
People and events move tasks too
A person can start or park a task from the board, or start, park or close it from the task's page, and the move happens at once. Moving a task between work stations is left to its runs, because a move by hand drops the station's conversation and says nothing about why, while a run passes the task on with a note the next agent works from. A person who wants work redone says so in the run's chat, and the station's agent passes the task on. When a person does move a task, any run on it ends: a run still waiting for a host, one of the team's computers, to take it up is withdrawn, and a run already working is asked to stop. If the new station has an agent, a new run is queued there.
Events from outside Spotlight move tasks too. On Delivery, a failed check on the pull request sends the task back to Implementation, a comment or a request for changes on the pull request brings it back to Code Review, and a merged pull request moves it to Completed. These rules are part of the line's definition, and Spotlight calls them reactions. Unlike a person's move, a reaction waits while a run holds the task and applies when the run ends, unless the run passes the task on first. A move to Completed, such as a merged pull request, is the exception: it stops the run and asks a person whether to close the task, or, if the task already waits on an answer to the run's question, adds itself to that question. How outside events reach a task explains how Spotlight works out which task an event is about, and what happens when a run holds it.
When two moves happen at once
With agents, people and outside events all able to move a task, two of them will sometimes act at the same moment. Spotlight makes sure neither undoes a decision it never saw.
An agent's handover only counts while its run still has the task. If the task has been moved elsewhere or put to a person in the meantime, whatever the run says when it ends is ignored, and a run that ends in failure is recorded as superseded rather than failed.
A person's move is refused if the task has moved or finished since their board last showed it. So moving a task on a board that hasn't caught up can't undo a move the person never saw.
Finishing a task and moving it are separate
A task keeps no single status. Its station says where it is, and whether it is running, waiting or finished comes from other facts: a run holding it, a question on it that has no answer, and the moment a station finished it or it reached Completed.
So a task can be finished and still stand at a station. When Delivery's Code Review finishes a task, the task stays at Code Review with its pull request open. It moves to Completed later, when the pull request is merged. The board shows where the work is, and the pull request shows what is left to do.
The inbox and the board also show the same task from two sides. A task waiting for a person still stands at its station on the board, marked as awaiting review, and the question it is waiting on is in the inbox. Asking a person covers that side.