What it is for
Some goals do not fit in one repository. A feature your product needs may start with a change in weblabor-base, continue in weblabor-teams and end on your product's screens. Carried by hand, that means writing a plan upstream, waiting for it to be built, bringing the change down, writing the next plan, and so on until somebody checks that the goal works — while questions wait unanswered and finished work sits upstream.
/coordinate takes the goal and sees it through. Type it in your product, the one whose screens show whether the goal was reached, followed by what you want:
/coordinate members can invite a guest to a single project
It builds nothing itself and pushes nothing. /next builds what it plans, and /test checks it, as with any other plan.
The interview
It starts the way planning before building does: it asks whether this is urgent, and it needs your product's vision — without one, and if nothing is on fire, it sends you to /vision first.
Then it asks until nothing is left in doubt: what functionality you need, on which screens and flows, in which states, what must not change, and how you will know the goal is reached. Meanwhile it reads every repository the goal reaches, to work out which part belongs to each. It closes the interview by showing you the goal, the points that prove it and what each repository will build, and asks whether anything is missing.
From then on it asks nothing more about the work, except a product question it cannot draw from the goal, in plain text. It answers on its own, with everything you told it, and takes every technical decision itself.
The branch your repositories have to be on
Every repository the goal reaches has to be on the feature/update branch on your computer: your product, and every repository between it and the highest one the goal changes. That is where the plans are saved and where the changes are brought together.
Every one of them below the highest also needs a base-update branch, the one that follows the feature/update of the repository above it. That is where each change from above arrives before it is merged into feature/update, the same way you bring one down by hand.
If one of them is on another branch, lacks the base-update branch it needs, or its folder cannot be found, it stops before writing anything and tells you which one and what is missing. It never switches or creates a branch for you.
If every change the goal needs is in your product itself, it plans there and follows that queue; there is nothing to bring down.
What it writes, and where
- A coordination document, in your product's project in the toolkit, in the
coordination/folder: the goal, the points that prove it, the repositories and their branch, every plan written, the changes already brought down and the conversations it watches. Every review reads it first. Once the goal is achieved and your product's plans for it are gone,/finishrun from your main branch deletes it. - A plan in each repository the goal needs a change in, saved in that repository's project in the toolkit and marked Ready to run. Each plan holds only what that repository builds. A plan below one upstream waits for the behavior it needs from above, and
/nextpasses over it until that behavior has arrived. - A last plan that checks the goal, in your product. It waits for all the others, and its only work is to open your product in the browser and walk every point of the goal in the states that matter. When it leaves no commit of its own,
/finishdeletes it once everything it checks has reached your main branch.
Each plan it saves or changes is announced to the conversation where /next runs for that repository, by default the one named Next steps.
What it watches, and when it stops
Every 10 minutes, in a conversation of its own, it checks each repository's Next steps conversation: that the queue is moving, that none of its plans is stuck on a question — which it answers in the plan itself, with the reason — and that no new plan was missed. If there is no conversation with that name, it asks you which one to watch.
When a plan upstream is implemented, it brings that change down to the repository below: first onto that repository's base-update, straight from the feature/update of the repository above, in its folder on your computer (not from the remote), and from there with a merge into its feature/update. It only ever moves base-update forward: if that branch has commits the repository above does not have, or is missing, it tells you which repository and waits until you sort it out. Because it takes the same path you do, its merges and yours can alternate without getting in each other's way. Then it tells that repository's conversation that what it was waiting for has arrived. It does not wait for the plans a queue is still building in their own worktrees, in that repository or the one above, since they are not built on the branch the merge reads from or lands on. It does wait while a queue builds directly on the branch, one plan at a time, until that build ends, and while the queue of the repository it merges into is checking a plan in the browser, so the screens do not change while they are being checked. When the change it brought down is also what the next repository down is waiting for, it keeps bringing it down in the same check, through that repository's own base-update, instead of waiting 10 minutes for each step. Where the code came from the repository above, the version from above wins; where your repository changed it itself, it keeps what both sides meant, and a conflict it cannot resolve with certainty it leaves undone, telling you the file and why. It never pushes: pushing is yours.
Before it marks the goal as reached it makes a closing sweep: whatever the work on the goal turned up on its own screens and flows — a view that breaks, a message that never shows, a finding the plans left behind — it does not ask you about. It writes a plan that corrects it, in the repository that owns the code, and checks the goal again afterwards. A finding on screens the goal never touched stays where it is and is named in one line, and a product decision it cannot draw from your answers is the only thing it still asks. After three rounds of corrections it stops writing more and names what is left.
It stops once the last plan passes its check and the sweep finds nothing left to correct — and then marks the goal as reached — or once nothing else is on its way. A plan that gets stuck where only you can move it does not stop it: it carries on with the rest and names that plan in its last message. If your assistant cannot schedule the check, it tells you and asks you to write to it every so often so it can look.
/design-catalog follows its own plans with this same coordinator; see Design a product catalogue.
Next
- Run the queue with /next — how each repository's plans are built and checked.
- Send a defect to its repository — how a part of a change is told to belong to weblabor-base or weblabor-teams.
- Verify a plan with /test — how the last plan checks the goal.