Merging Workstreams and Work Packages
How to fold several draft work packages into one, or several workstreams into one, when an intent has come out in more pieces than the work needs: what moves, what stays behind, who can do it, and why it cannot be undone.
When to use it
Use Merge… to tidy the structure of an intent before the work starts. The usual cases:
- Overlapping work packages. A Generate or an Auto Pilot run proposed two or three packages that change the same thing, and you want one package that a developer or a coding agent can build as one pull request.
- A workstream with nothing of its own. A workstream turned out to be part of another one (its look, its layout on a small screen, the same outcome in other words), and its packages belong under that one.
- Packages you split too finely by hand and now want back together.
Merging is for drafts. Work that has started review is never changed by a merge. If you only want something out of the way, use Archive or Delete instead: see Archiving, Rejecting and Deleting Work.
Merging work packages
- On the intent’s page (the Work tab or the tree) or on the Work Packages board, open the ⋯ menu of a draft work package and choose Merge….
- Tick the other draft work packages of the same intent that you want folded in. A package that cannot take part stays in the list and says why in words.
- Under Keep, choose which package is kept. It starts as the one you opened the menu on. You can give the kept package a new title.
- Read the summary: what moves, what is added to the checklists, what is archived and what is not carried.
- Choose Merge. The page then says what was merged, with a link to the kept package, until you dismiss it.
The packages can sit under different workstreams of the intent; the kept package stays under its own workstream. Packages of different intents cannot be merged.
What the kept package takes, and what stays behind
| From each merged-away package | What happens to it |
|---|---|
| Work items | Moved to the kept package, each with its accepted mark as it was. Nothing is duplicated or renamed. |
| Acceptance criteria and risks of its scope, and of any scope that was accepted | Added to the kept package’s scope, each once. If that scope was already accepted it stays accepted, and the dialog tells you it is gaining criteria. |
| Checklist items (Definition of Ready and Definition of Done) the kept package does not have | Added. A merge can make the gates stricter and never looser. Two items that differ only in their description are both kept, because the description is what the reviewing agent checks against. |
| Policies, context entries and reviewer agents | United with the kept package’s. |
| “Implement after” links | United. A package elsewhere that waited on a merged-away package now waits on the kept one, everywhere the order is shown. |
| Scopes nobody accepted | Not carried. They stay on the merged-away package’s record. |
| Its release phase, when it differs from the kept package’s | Not carried. The kept package keeps its own phase. |
| Plan pages | Not carried. They stay with the merged-away package. |
| Its copy of an organisation’s guardrail checklist item, when the two copies ask different things | Not carried. The kept package’s copy stands, and the dialog counts the difference. |
| A link to an issue in your tracker | Stays with the package it was made for. |
The kept package keeps its own reference (WP-12), its policy version, its phase and its place on the board.
Merging workstreams
- On the intent’s page, open the ⋯ menu of a workstream and choose Merge….
- Tick the other workstreams to fold in, and choose which one is kept. You can retitle the kept workstream.
- Read the summary and choose Merge.
Every work package under a merged-away workstream moves to the kept workstream, in every status: drafts, rejected and archived packages alike. Nothing else about a package changes. The merged-away workstreams leave the intent.
What “has started review” means
A merge only ever changes work that nobody has begun to review. A work package has started review, and cannot be merged or moved by a merge, when any of these is true:
- it is not a draft (it is in review, approved, dispatched, in progress or completed), or it was put away from one of those states;
- it was approved at any time, or has a coding run, even if it has since gone back to draft;
- it was rejected while in review;
- a readiness or done review has been opened for it, even with nothing ticked yet;
- an Artefact Passport has been issued for it.
Three more things stop a merge although they are not review: a legal hold on any package the merge would change; Auto Pilot running, or paused part-way, on the intent (wait for the run to finish, or stop it); and a read-only studio. A spike is never merged: two research questions are not one.
The dialog greys out a package it can see is in the way and says why. Some of these only the server can see (a passport, a legal hold, a review opened a moment ago); if it refuses, the dialog shows its reason and keeps what you ticked.
Where a merged-away package goes
A merged-away work package is not deleted. It is archived exactly as it stood, as a record that says which package it was merged into.
A merged-away workstream leaves nothing behind on the page: its packages are under the kept workstream, and the intent keeps a record of the merge.
Who can merge
| Action | Who |
|---|---|
| Merge work packages | The studio owner or a reviewer. A member can also merge work packages they created themselves — every one of them — as long as nothing the owner or a reviewer set differs between them: checklist items, policies, reviewer agents and the phase. |
| Merge the work packages an Auto Pilot run made | The owner, a reviewer, or the member who started that run (the run’s packages are theirs). |
| Merge workstreams | The studio owner or a reviewer only. |
If you work alone you are the studio’s owner and can do all of it. Nothing here needs a second person.
This is about merging work packages and workstreams into one. Who may approve and merge a pull request is a separate studio setting (Trust Settings → Who may approve and merge), and changing it changes nothing here.
Limits
- Up to five into one. One merge folds at most five work packages into a sixth, or five workstreams into a sixth. Merge again to fold in more.
- Up to 22 work packages move with a workstream merge, counting every status. A workstream that holds more than that can only be the one you keep.
- Up to 40 work items on the kept package, and up to 20 “implement after” links. A merge that would pass either is refused, and nothing is dropped for you.
- Same kind, same policy version. Work packages created under different versions of an organisation’s guardrail policy are not merged; re-baseline them to one version first.
- No loops. A merge that would make a package wait on itself through others is refused, and the dialog names the loop.
- A package that took in more than 32 others cannot later be deleted on its own; delete its intent or its workstream instead.
If something changes, or no answer comes back
A merge is all or nothing. If a colleague changes one of the packages, or the intent, while the dialog is open, nothing is merged: the dialog reloads what it shows, keeps your choices and asks you to check and merge again.
If no answer comes back after you press Merge (the connection dropped, say), the dialog does not guess. It reads the records again. When they show the merge was made it says so; otherwise it says it could not tell, and pressing Merge again sends the same request, never a second merge.
Generate and Auto Pilot afterwards
When you merge two things you are telling the Studio they were one piece of work. Generate and Auto Pilot are told what was merged into what, and do not propose a merged-away work package or workstream again while the one it was merged into is still there. If you do want it back as a separate item, add it by hand.
Good to know
- Merge is on rows and cards, not on a work package’s own page. The packages it can be merged with are on a list.
- Every change a merge makes is in the audit trail, marked as a merge, for the kept package and for each merged-away one.
- Favourites and recent pages are left as they are. A starred merged-away package still opens its record.
- It works in local mode by the same rules. Local mode has no legal holds and no issued passports, so those two never refuse there.
- The dialog works from the keyboard and has not yet been tested with a screen reader.