Upgrading to the Portable SDLC Template 4.0.0
What changes for existing projects when the Linear SDLC templates become portable: map your statuses first, then the workflow stops naming statuses, cards and models.
Preview. Template 4.0.0 is built and merged but not published yet. The steps and behavior on this page describe what ships with it and can change before release.
Version 4.0.0 of the Linear SDLC templates (the Default SDLC, slug sdlc-v2, and the Linear SDLC, slug linear-sdlc) is the first portable template. It does not name a Linear status, an agent card, a model or a credential. It asks one question when something happens: which stage does this issue belong to? The stage's cards, model, skills and outcomes answer the rest, from configuration.
The result is that the same template, unmodified, runs on a team that uses Icebox, Backlog, Started and Accepted, and on a team that uses Ready, Active, Verify and Done. Adding a card to Icebox, or adding a stage, no longer means editing workflow nodes.
What changes
| Before (3.x) | After (4.0.0) |
|---|---|
| A status list in the trigger, and a switch node per status or mention. | Two entry paths, an issue entered a stage and a mention, both ending in the same stage dispatch step. |
| Per-role dispatch leaves with agent cards pinned in the workflow. | No card in the workflow. The stage and its cards choose. |
| Status names written into the template and matched exactly, case included. | No status names. Your project's status mapping decides. |
| The workflow moves the issue after a run (for example to Started). | The workflow moves nothing. The stage's outcomes say where work goes, and the runner applies them. |
A Triage recovery for blocked work. | Whatever the stage's blocked outcome says. |
A linear.comment.created trigger beside agent sessions. | Removed. It fired twice for every mention. Mentions arrive as agent sessions only. |
| A model node set in the workflow. | The project's model is used, and stage and stage card selections apply. |
What stays the same:
- The GitHub Issues branch is unchanged.
- A dispatch that no worker acknowledges is relaunched once. If the relaunch is not acknowledged either, a message on the issue says so, and the issue is not moved.
- Credentials still come from the project's credential bindings.
- Gates, capabilities and the exit handler still run, but the exit handler's checks follow what the run was, not the name of a work type: a run in an
inflightorreworkstage whose card owes a pull request goes through PR creation, CI and deploy; a run whose success moves work to adonestage gets its checks and merge or landing. Blocked and failed runs post no extra summary comment.
Before you upgrade a project
- Map your tracker's statuses to stages. Without a mapping, an issue starts nothing. The platform replies once per issue, with a "map your statuses" message, and no session starts. Do this in the project's Settings, under Stages. See Stages and Roles and First-Run Setup.
- Choose a write status for every mapped stage. It is the status the platform sets when work moves into that stage.
- Check your hosts. Status moves on 4.0.0 come from stage outcomes that the runner applies. Until your hosts run a runner that applies them, a 4.0.0 run leaves the issue where it is.
- Check the cards and models. Each stage you mapped needs a default card, and each such stage needs a model that resolves. The checklist on the Stages page tells you.
Example mappings
The platform's own SDLC statuses:
| Linear status | Stage | Note |
|---|---|---|
| Icebox | icebox | |
| Triage, Backlog | backlog | Write status: Backlog |
| Started | in-progress | |
| Finished | review | |
| Delivered | acceptance | |
| Rejected | rework | |
| Accepted | done | |
| Canceled, Duplicate | closed |
An ops-style board with Ready, Active, Verify, Waiting and Done:
| Linear status | Stage | Note |
|---|---|---|
| Ready | backlog | |
| Active | in-progress | |
| Verify | review | |
| Waiting | icebox | |
| Done | done |
This board has no acceptance stage. At the project level, override Review's success outcome to done, so a passing review closes the work. See Outcomes and Transitions.
How the upgrade reaches a project
The upgrade is published by your platform operator as new template versions. It is not a toggle per project.
- Projects subscribed to the template move to 4.0.0 together when it is published. The status trigger stops filtering on a status list and now fires on every status change in the project. Each firing is one inexpensive workflow run that checks the mapping and starts nothing if the status is unmapped.
- Projects with their own installed copy are not changed automatically. The marketplace offers the update. If the copy was edited on the canvas, the update is refused until you acknowledge that it overwrites those edits.
- The older status-change fallback that used to react when no workflow dispatched is off for 4.0.0 projects, because the 4.0.0 trigger always dispatches on a status change.
Your operator can roll back by moving the template version back. The 4.0.0 version stays published.
After the upgrade
Everything you did to the old template by editing nodes is now a settings change:
| To do this | Change this |
|---|---|
| Let Icebox run another card | Add the card to the Icebox stage |
| Run a different card by default in Backlog | Change the default on the Backlog stage |
| Use a different model for QA | Set the model on the QA stage card |
| Add a new step to your process | Add a stage, map a status to it |
| Change where failed work goes | Change the stage's failure outcome |