Linear lifecycle

Purpose: How issues move through Linear from creation to done. Covers statuses, labels, comment protocol, transition rules, and session recovery.

Quick reference:

• 10 issue statuses — Triage → Icebox → Backlog → To-Do → In Design → In Process → In Review → Preview Testing → Done / Cancelled
• 5 project statuses — Lifecycle phases: Discovery, Foundation, Hardening, Launch, Operate
• awaiting-input — A label, not a status — stays in current status while waiting for human
• Done — Merged to main + main preview verified (not assumed)
• Session recovery — Read issue status + labels + last 3-5 comments to determine state
• Comment templates — See linear-formatting.md § Comment Templates

Issue statuses (10)

Every issue flows through these statuses regardless of which lifecycle phase the project is in.

#	Status	Category	What's Happening	UUID
1	Triage	Unstarted	New issue, not yet evaluated	19843fa8-c929-4d67-aa76-66bc30329c23
2	Icebox	Unstarted	Valid ideas, not currently planned	bf42b835-4581-4ad8-af36-6fb984bcf390
3	Backlog	Unstarted	Evaluated, ready to work	ceac866a-c1d0-4126-a59f-06cad402ffb2
4	To-Do	Unstarted	Actively queued for next /go session	d5eedcf2-8448-4225-b58b-504019ffe0b8
5	In Design	Active	All spec work: brief, prototype, tech spec, and issue creation	1577fe48-d3b6-4f54-bc57-14521fac2aec
6	In Process	Active	Building code and running verification	cfbdf201-c256-4641-ae81-aa263cdffca2
7	In Review	Active	Pull request is being reviewed	d4e9a6bd-c07f-4ba5-a0c1-dce24e5843a2
8	Preview Testing	Active	Push, test preview, PR, merge, verify main preview	7f39070c-a823-4cc7-9cda-f63471c45fdb
9	Done	Terminal	Merged to main, main preview verified	97d1346d-38ab-41cb-a27c-bc9c0097a0ed
10	Cancelled	Terminal	Won't do	0fce101c-c701-4235-8fc0-ec0c78db61d1

In Design scope note: "In Design" covers all spec work — brief, prototype, tech spec, and issue creation. It maps to the SDLC DESIGN phase. It is not limited to visual design.

Status colors

Visual colors for diagrams, dashboards, and any visual that references Linear statuses. Pastel variants are for diagram fill backgrounds; hex values are the icon/accent colors.

Status	Icon	Hex	Pastel (fill)
Triage	Orange-red filled arrows	#E8470A	#FDCFBF
Icebox	Dotted gray circle	#95A1B3	#E2E6EB
Backlog	Dotted gray circle	#95A1B3	#E2E6EB
To-Do	Lighter dotted circle	#C5CAD4	#EAECEE
In Design	Empty white circle	#FFFFFF	#F5F5F5
In Process	Orange/amber clock	#F0A500	#FFF0C2
In Review	Green half-fill	#26C244	#C8F5D0
Preview Testing	Green 3/4-fill	#22A849	#C8F5D0
Done	Indigo checkmark	#5E6AD2	#D8DBF5
Cancelled	Gray strikethrough	#95A1B3	#E2E6EB

Project statuses (5 planned)

Lifecycle phases are tracked as Linear Project statuses, not issue statuses. A project in the "Discovery" phase still has individual issues flowing through the 10 issue statuses above. Project statuses describe where the product is in its lifecycle, not where an issue is in the pipeline.

#	Project Status	SDLC Phase	When	UUID
1	Discovery	Phase 1	Market validation in progress	9876d0d6-3a83-4e89-b5f5-73fabb6071b5
2	Foundation	Phase 3	Infrastructure setup in progress	1db5746b-e948-484c-9f24-987bc68b9077
3	Hardening	Phase 5	Security/perf/a11y audit in progress	fa6dd93d-1190-4844-8d67-3c656f10492a
4	Launch	Phase 7	Go-to-market execution in progress	68a3f286-e9ce-495f-b557-e9d696e809e1
5	Operate	Phase 8	Live product monitoring	6984dee2-b9c0-470d-bc91-11bf6426508a

Managed in Settings → Projects → Statuses. When a phase activates for a project, set the project's status accordingly.

Pipeline flow

Triage -> Icebox -> Backlog -> [To-Do] -> In Design -> In Process -> In Review -> Preview Testing -> Done
                             \____________/
                             (To-Do is optional)

                     [awaiting-input label at any checkpoint]                                 Cancelled

All issues follow this pipeline regardless of which lifecycle phase the project is in. Design depth scales with complexity, but no statuses are skipped.

Phase → status mapping

Issues use the same 10 statuses in every phase. The project's lifecycle phase (tracked via Linear Project status) determines which departments are active and what kind of work is being done — but the issue workflow is always the same.

SDLC Phase	Project Status	Issues Use
Discovery	Discovery	Triage → In Design → Done (research issues)
Strategy & Design	—	Triage → In Design → Done (spec issues)
Foundation	Foundation	Full pipeline (infra issues)
Build	—	Full pipeline
Harden	Hardening	Full pipeline (audit issues)
Ship	—	Full pipeline
Launch	Launch	Full pipeline (marketing issues)
Operate	Operate	Full pipeline (support/ops issues)

Complexity Label	Design Depth	Pipeline Behavior
trivial	No design — proceed to BUILD	Skip DESIGN, skip BUILD review agents
standard	Brief in issue comment, 1 reviewer	Standard pipeline
complex	Brief + prototype (if UI) + tech spec + issues, 3-reviewer convergence	Full agent workflow

Design-only issues: Done when speccing is complete (Triage → Backlog → To-Do → In Design → Done). To-Do is optional — issues may skip from Backlog directly to In Design. No forced linkage to spawned implementation issues. Linear Projects serve as the optional organizational container when work is large.

Planning issues (Type: planning): Simplified flow: Triage → In Design → Done. No In Process, no In Review, no Preview Testing — these issues produce decisions, specs, or research but no code. Always auto-derives to trivial complexity.

Spike issues (Type: spike): A time-boxed investigation to reduce uncertainty. Always has a fixed time cap. Output is a recommendation, decision, or "go/no-go" — not a shipped artifact. If the spike's conclusion requires implementation, a separate feature/chore issue is created. Spikes follow the same simplified flow as planning (Triage → In Design → Done) when they produce no code, or the standard pipeline when the spike itself includes framework changes. Always auto-derives to trivial complexity. Distinct from planning: planning produces deliverables (plans, specs, decks), spikes produce decisions.

Labels

Labels are organized into three MECE groups plus one ungrouped flag. Each group covers a distinct dimension — no overlap between groups.

Type group (workspace-scoped)

Classifies the nature of the work. Used for filtering, reporting, and complexity auto-derivation.

Label	Color	UUID	Description
bug	#EB5757	67bd55d9-3b79-41ca-9416-32ce70b4c4c6	Something is broken
feature	#27AE60	b0b46018-d526-48c0-9966-4af042e09fb1	New capability
chore	#06B6D4	048b00fb-b0db-423d-ba07-cd3b658ccea2	Maintenance, refactoring, config
docs	#2F80ED	3f56eed9-6d34-4c84-84c8-16a3acb1ecd9	Documentation only
planning	#BB87FC	b8124ae5-af34-447d-b78b-a028d2a1182f	Research, specs, and design decisions -- no code produced
spike	#F97316	953fe180-5bd0-49b8-843b-9f90e40459fc	Time-boxed investigation to reduce uncertainty -- produces decisions, not deliverables

Group parent: Type (7ef6c112-2a62-4fd3-9891-15b8b9e5e958, workspace-scoped, #95A1B3)

Complexity group (team-scoped)

Drives pipeline depth — how much design, review, and verification an issue gets.

Label	Color	UUID	Pipeline Behavior
trivial	#10B981	6cd67fe2-ed76-4798-95a4-6788347f00b6	No design, skip BUILD review agents
standard	#FBBF24	f788a210-b16d-4691-9285-d4328c27b9f9	Brief in issue comment, 1 reviewer
complex	#EC4899	59033a4a-10a9-4ee8-82a1-ef9aa133fdd9	Brief + prototype (if UI) + tech spec + issues, 3-reviewer convergence

Group parent: Complexity (81a27696-de04-49aa-8b2e-15f13c524bcc, team-scoped, #F2C94C)

Auto-derivation heuristic: When an issue has no Complexity label, the /go pipeline derives one from the Type label + estimate:

Type	Estimate	Derived Complexity
docs	any	trivial
planning	any	trivial
spike	any	trivial
chore	XS, S	trivial
bug	XS, S	trivial
bug	M, L	standard
feature	XS, S	standard
feature	M, L, XL	complex
chore	M, L, XL	standard

A manually applied Complexity label always overrides auto-derivation.

Mode group (team-scoped)

Pre-selects the pipeline trust level for /go.

Label	Color	UUID	Description
autonomous	#84CC16	7a104efa-52b0-4c67-8226-886b96c0c087	Issue runs through full pipeline without human gates
interactive	#6366F1	0da34012-6254-4351-a84f-d0e912f0c64d	Issue pauses at gates for human approval

Group parent: Mode (a9fa01bd-3e4a-44dc-b587-76a4b4c5e969, team-scoped, #6366F1)

Workflow: Apply the label in the backlog or To-Do column. The /go pipeline reads the issue's labels and derives trust level from the type × complexity matrix. The autonomous and interactive labels no longer drive mode selection — they are retained for historical context only.

awaiting-input flag (ungrouped)

awaiting-input (#F43F5E, UUID: 64f7b4d9-d746-479e-b37a-76088dc1640f) is a label, not a status.

• Applied — When human input is needed at any checkpoint
• Issue stays in current status — While the label is present
• Removed — When the human responds
• Kanban best practice — Labels carry meta-state without disrupting flow columns (David Anderson)

When applied:

• Any checkpoint requiring human decision — Brief approval, prototype approval, tech approval, execution plan approval
• New Findings remain after disposition — Human must approve issue creation or skip
• Escalation — A Critical finding that cannot be resolved (immediately or within 3 iterations)

Session recovery with label present: Read the last @Ameet comment and its thread replies. If the human has replied, remove the label and resume. If no reply, wait.

Custom view: The "Awaiting Input" view (e3ad8440-ae11-4227-bdce-afcc1d506029) is filtered by the awaiting-input label and pinned to the sidebar for quick access to all blocked issues.

Estimates

T-shirt sizing (XS, S, M, L, XL) is enabled for capacity planning and complexity auto-derivation. Estimates are set during triage or backlog grooming and feed the auto-derivation heuristic above.

Custom views

View	UUID	Filter	Purpose
Awaiting Input	e3ad8440-ae11-4227-bdce-afcc1d506029	awaiting-input label	Quick access to all blocked issues, pinned to sidebar

Transition rules

What triggers each status change. Pre-conditions are mandatory — the orchestrator must verify all pre-conditions are met before changing status.

Transition	Trigger	Pre-conditions
Triage -> Icebox	Weekly triage: valid idea, not currently planned	Type label applied
Triage -> Backlog	Weekly triage: issue evaluated and promoted	Priority set, type label applied
Icebox -> Backlog	Decision to actively plan the issue	Priority set
Backlog -> To-Do	Issue pulled for next /go session	Priority set
Backlog -> In Design	Work started; plan agent invoked (To-Do is optional — issues may skip it)	Issue assigned, branch created
To-Do -> In Design	Work started; /go command invoked	Issue assigned, branch created
In Design -> In Process	Human approves final design artifact (tech spec, execution plan, or brief for simpler work)	Brief posted to issue (comment or docs/specs/ if >200 lines), human approval comment on Linear, tech spec posted (if required by complexity), all design checkpoints passed
In Design -> Done	Design-only issue: speccing complete	All spec artifacts written, human approval comment on Linear
In Process -> In Review	Implementation complete, verification passed, review agents invoked	All code committed, pnpm type-check && pnpm lint && pnpm build pass, implementation summary posted to Linear
In Review -> Preview Testing	All review findings fixed	All Critical findings fixed, all Advisory findings fixed, review synthesis posted to Linear, no unresolved awaiting-input label
Preview Testing -> Done	Merged to main, main preview verified	PR created and merged, merge commit verified on main (git log origin/main --oneline -1), main preview deployment verified (not assumed)
Any -> Cancelled	Explicitly decided: won't do	Reason documented in Linear comment

Status transitions are visible in Linear's activity timeline — no comment echo needed.

Phase checklists

When the orchestrator starts work on an issue (or resumes), the appropriate checklist is posted to the Linear issue description. Agents check items off as they complete them. All items must be checked before requesting the next status transition. As the pipeline progresses and execution steps become clear, the orchestrator updates the checklist to include remaining steps (review, ship, etc.) — the issue description is the single source of truth for progress, not just the CLI task list.

Checklists use @{project-owner} as a placeholder — replace with the actual project owner's name in each project.

Conditional checklist items: Some items apply only to certain work types. Individual items are annotated in italics (e.g., bug fixes only); conditional sections use bold headings (e.g., **Tech Spec (features only — skip for bug fixes)**). When the condition doesn't apply, check the item off as - [x] Item — N/A.

In Design checklist:

#### Phase Checklist: In Design

> **Brief**
> - [ ] Plan agent invoked (Pass 1: questions)
> - [ ] Human answered questions (or "no questions")
> - [ ] Plan agent invoked (Pass 2: brief)
> - [ ] Brief posted as Linear issue comment (or `docs/specs/[id]-brief.md` if >200 lines)
> - [ ] **CHECKPOINT: @{project-owner} approved brief**
>
> **Prototype (UI work only)**
> - [ ] Prototype agent invoked
> - [ ] Prototype running at localhost:3000
> - [ ] UX decision log posted as Linear comment
> - [ ] Mockup images uploaded to Supabase storage (see `project-management.md` § "Image Assets in Linear")
> - [ ] **CHECKPOINT: @{project-owner} approved prototype**
>
> **Diagrams (standard/complex only — skip for trivial)**
> - [ ] Solution diagram included *(architecture, data flow, state machine, or component hierarchy — choose the type that best illustrates the solution)*
>
> **Tech Spec (features only — skip for bug fixes)**
> - [ ] Tech agent invoked
> - [ ] Tech spec posted as Linear issue comment (or `docs/specs/[id]-tech.md` if >200 lines)
> - [ ] **CHECKPOINT: @{project-owner} approved tech spec**
>
> **Issue Breakdown (features only — skip for bug fixes)**
> - [ ] Issue agent invoked
> - [ ] Issues created with dependency graph
> - [ ] **CHECKPOINT: @{project-owner} approved execution plan**

In Process checklist:

#### Phase Checklist: In Process

> - [ ] Branch created: `type/issue-id-slug`
> - [ ] Implementation complete (all files changed)
> - [ ] Regression test written *(bug fixes only — see standards/core/testing.md § Regression Testing Requirements)*
> - [ ] Verification passed: `pnpm type-check && pnpm lint && pnpm test:run && pnpm build`
> - [ ] Implementation summary posted to Linear
> - [ ] All changes committed

In Review checklist:

#### Phase Checklist: In Review

> - [ ] Review agents invoked (synchronous team if needed)
> - [ ] All Critical findings fixed
> - [ ] All Advisory findings fixed
> - [ ] Review synthesis posted to Linear
> - [ ] New Findings resolved (Fix Now items committed, or @{project-owner} responded, or none)

Preview Testing checklist:

#### Phase Checklist: Preview Testing

> - [ ] Code pushed to remote branch
> - [ ] PR created with summary
> - [ ] Vercel preview deployed and tested
> - [ ] PR merged to main
> - [ ] Main preview verified (not just "assumed working")
> - [ ] Done summary posted to Linear

Comment protocol

Milestone comments only — approximately 8-10 per UI feature. Each comment is a synthesis, not a status echo. All comments follow the format in standards/reference/linear-formatting.md.

[!NOTE] Description vs Comment: Structured findings (video analysis, root cause, steps to recreate) belong in the issue description, not in comments. See standards/reference/project-management.md § "Description vs Comment" for the full rule.

When to post a comment

Milestone	Comment Content
In Design started	Plan summary: what's being designed, key decisions, unknowns
Each @Ameet checkpoint	Context + options + what's needed from human
Implementation complete	What was done, decisions made, data migrated, files changed
Review complete	Synthesis: findings fixed, new findings dispositioned
Done	Summary: files changed, tests added, PR#, preview URLs

Do not post comments that merely restate the current status (e.g., "Moving to In Process"). Linear's timeline handles that.

Comment templates for each milestone type are defined in standards/reference/linear-formatting.md § "Comment Templates".

Escalation

If a Critical finding cannot be resolved after 3 iterations, or verification fails 3 times:

1. Add awaiting-input label — To the issue
2. Post an @Ameet comment — With the following:
   • What failed (specific error or finding)
   • What was tried (each attempt and why it didn't work)
   • Recommended next step (pick one from the list below)
3. Wait — Do not proceed, do not revert

Resolution options to offer the human:

Option	When to Use
Reassign	Different agent type has better domain expertise for this problem
Decompose	Issue is too large; break into smaller, independently verifiable pieces
Revise approach	Current technical approach is fundamentally wrong; need a different strategy
Accept with limitations	Document known issues, ship anyway with a tracked follow-up
Defer	Move to Backlog; problem not worth solving right now

Human responds via: Linear comment thread reply on the checkpoint comment.

Done definition

Done = merged to main + main preview verified.

Definition of Done criteria

All work must meet these DoD criteria before being marked Done:

1. Code merged to main — All commits landed on main branch
2. Main preview verified — Main preview deployment confirmed working (not assumed)
3. User-reachable pages have sidebar nav entry — Any page reachable by users must have a corresponding entry in sidebar navigation (see standards/core/milestone-planning.md § The Horizontal Slice Rule)

Production promotion

Production promotion is a separate concern tracked via:

• deployed:production label — Applied after production release
• Future "Ship" status — When production deployment is automated

Done does not mean "in production." It means the work is complete, merged, and verified on the main preview environment.

Automation chain

Three systems work together to automate status transitions end-to-end:

PR opened           → In Review        (Linear GitHub integration)
PR merged to main   → Preview Testing  (Linear GitHub integration)
Vercel deploys main → Done             (linear-auto-done.yml GitHub Action)
Vercel deploy fails → In Review        (linear-auto-done.yml GitHub Action)

Linear GitHub integration (2 transitions)

GitHub Event	Linear Transition	Status
Branch created with issue ID	→ In Process	Disabled — conflicts with In Design → In Process manual gate
PR opened	→ In Review	Enabled
PR merged	→ Preview Testing	Enabled

Configuration: Linear Settings → Team → GitHub Integration → Status Automations. Map "PR opened" to In Review status and "PR merged" to Preview Testing status.

Vercel → GitHub Action → Linear (1 transition)

The linear-auto-done.yml GitHub Action completes the automation chain:

• Triggers on Vercel's deployment_status webhook event
• Filters: only Production environment (main branch), only success/failure states
• Extracts Linear issue IDs from branch name, commit message, PR title
• On success: transitions to Done
• On failure: transitions back to In Review

Setup: Requires LINEAR_API_KEY as a GitHub repository secret. Each repo's Vercel project must use main as the Production branch (Vercel → Project → Settings → Git → Production Branch).

What stays manual

• Triage → Icebox — Human triage decision (park for later)
• Triage → Backlog — Human triage decision (promote to active)
• Icebox → Backlog — Human decides to actively plan the issue
• Backlog → To-Do — Human queues issue for next session
• Backlog / To-Do → In Design — /go command moves immediately on start
• In Design → In Process — Requires design approval (human gate in interactive mode)

Why this split

Automate the mechanical, gate the meaningful. PR and deploy events are reliable signals — no human judgment needed. The critical gates (triage, design approval, work start) stay manual because they require decisions.

Branch naming

Use Linear's "Copy git branch name" shortcut (Cmd+Shift+. on Mac) as the source of truth. This generates a branch name with the issue ID baked in, ensuring auto-linking works every time. Configure the format in Linear Settings → Team → Git to match:

<type>/<issue-id>-<slug>

PR title format

Include the Linear issue ID for belt-and-suspenders linking:

<type>: <issue-title> (<PROJ-id>)

Examples: feat: user auth flow (RAJ-123), fix: payment timeout (RAJ-456)

Session recovery

If a session crashes mid-pipeline:

1. Read the Linear issue's current status and labels — Determine where in the pipeline
2. Read the last 3-5 comments — Determine what phase completed
3. If awaiting-input label is present:
   • Read the last @Ameet comment and its thread replies
   • If human replied: remove label, resume from current status
   • If no reply: wait
4. If crash during review phase — Re-run all reviewers from scratch (cheap, under 1 minute each)
5. Read any spec artifacts — docs/specs/[id]-brief.md, -tech.md, -prototype.md for context
6. Resume from current status

Multi-issue parallel recovery

When multiple issues are being executed in parallel (e.g., batch framework improvements):

1. List all issues in the current phase/batch
2. Check each issue's status independently
3. Issues that completed before the crash — Retain their status
4. Resume only the incomplete issues
5. If a partial commit exists — Check git log for which issues were included

Stale awaiting-input detection

If an issue has had the awaiting-input label for more than 48 hours with no human response:

1. Post a reminder comment — "@Ameet — This issue has been waiting for input since [date]. Still need a decision on: [summary]"
2. If no response after a second 48-hour period — Move the issue to Backlog with a note

Principle: Linear is the source of truth for issue state. The combination of current status + labels + last comments fully describes where the pipeline is.

Related standards

• standards/core/sdlc.md — Development lifecycle and eight phases
• standards/core/review-protocol.md — Review protocol, finding severity, Linear comment format
• standards/reference/project-management.md — Linear setup, issue formatting, branch naming
• standards/reference/environments.md — Preview environments, deployment, Vercel integration

---

Linear Lifecycle v3.0 -- March 2026