Linear — Day 1 guide (Brainforge delivery)
Purpose: One place to learn how Brainforge uses Linear for execution truth: core objects, how work flows, which labels and saved views matter, and what to do first by role (IC, CSO, Service Lead, Head of Delivery).
Last updated: 2026-04-06
Who should read what
| Role | Read | Then do |
|---|---|---|
| Everyone | Core components through Flows | Bookmark your persona view kit |
| IC | + IC — Day 1 | Own assignee + project + honest state |
| CSO | + CSO — Day 1 | Per-client views + plan ↔ board alignment |
| Service Lead | + Service Lead — Day 1 | Cross-client roster view from Operating |
| Head of Delivery | + Head of Delivery — Day 1 | Portfolio hygiene views + standards bar |
Deeper catalogs (do not duplicate here):
- Full recommended view list (issues, projects, initiatives, dashboards): linear-views.md
- Naming and labels (taxonomy): linear-cleanup-taxonomy.md
- Minimum discipline (ownership, dates, truth): linear-hygiene-standards.md
Core components
Short definitions and how they stack.
| Object | What it is | Brainforge use |
|---|---|---|
| Team | Workspace area with its own backlog and permissions | Client teams (e.g. LMNT, CTA) vs internal (Platform, Delivery, GTM). Canonical list: linear-cleanup-taxonomy.md §1. |
| Issue | Unit of execution (ticket) | Should have assignee, project, clear title, honest state, and labels when policy applies. |
| Project | Container for related issues; dates and lead | Maps to engagement workstreams; link to initiative. |
| Initiative | Higher-level grouping (roadmap / portfolio) | Client pattern: Client | Workstream. Internal: service line or offering. See taxonomy §2–3. |
| Milestone | Checkpoint inside a project | Use for client-meaningful phases; CSO narrative should match milestone progress. |
| Cycle | Time box (sprint), if your team uses it | Optional; “No cycle” hygiene view exists if you adopt cycles. |
| Assignee | Person responsible for the issue | Exactly one owner for active work; empty assignee = triage debt. |
| Project lead | Accountable for project outcome in Linear | Useful for “Led by …” project views (CSO / PM). |
| State | Workflow status (Backlog, In Progress, Done, …) | Should be comparable across client teams where possible — see linear-status-cleanup.md and apps/platform/scripts/audit-linear-workflow-states.ts. |
| Labels | Tags for filtering and reporting | Service line, phase, offering, routing — Labels below. |
| Views / Spaces / Dashboards | Saved filters on issues, projects, or initiatives | Persona kits below; full catalog in linear-views.md. |
Typical stack: Initiative → Project → Issue. Milestones hang off projects. Labels cut across for reporting.
Brainforge hierarchy (plan → Linear)
- SOW / project plan defines scope and phases.
- Initiatives represent sponsor-level or workstream buckets (client:
Client \| Workstream; internal: service line or platform area). - Projects hold the issues the team executes; align names to offerings where helpful (see taxonomy §3).
- Issues are the day-to-day truth for who is doing what and whether it is blocked or done.
CSO owns that the board tells the same story as the client narrative; Service Lead signs off technical feasibility and dates. See project-ownership-guide.md.
Labels (summary)
Canonical detail: linear-cleanup-taxonomy.md §4. Common sets:
| Category | Examples | When |
|---|---|---|
| Service line | data, ai, strategy-analytics | In-scope engineering work should carry line signal (exact names from workspace — use list_issue_labels before bulk edits). |
| Subservice | data-platform, data-modeling, data-strategy, measurement-kpis, reporting-insights, workflow-automation, knowledge-engineering, copilots-agents | One primary subservice when work maps to a bucket; see linear-cleanup-taxonomy §4. Legacy: data-infrastructure, analytics-bi, metrics-kpis, ai-infrastructure. |
| Phase | phase-0, phase-1, phase-2 | Option B / implementation plans. |
| Offering | omni, edge-to-activation, dbt-audit, … | Scoped to a specific offering or vault slug. |
| Delivery | client-dependency, internal | Waiting on client vs internal-only. |
| Agent routing | ai-assignable, human-only | Per linear-labels-ai-human.md. |
Legacy / proxy: Some teams still use cap-* or other workstream labels. Audits map these to canonical slugs — see .cursor/skills/linear-service-label-audit/references/taxonomy.md in the platform repo.
Roster vs labels (Service Leads): Cross-client visibility is easiest with Operating roster → multi-team saved views; label-only filters add value when labels are audited and maintained. See sl-cross-client-views.md and linear-prereq-hygiene.md.
Flows — how work moves
- Create — Prefer creating issues inside the right project so they inherit initiative context. Triage queues are fine short-term; empty project on active work is debt (see hygiene views).
- Assign — One assignee; reassign explicitly when handing off.
- Blocked / waiting on client — Use blocked state where your workflow supports it and label
client-dependencywhen policy applies so CSO can filter chase lists. - Done — Move to completed only when acceptance criteria are met; add a short comment if the title alone is not enough for history.
- CSO ↔ SL — No client-visible date or scope promise without SL alignment (see CSO project ownership guide).
Accountability recap: linear-hygiene-standards.md §4 (CSO, SL, IC, HoD).
Persona view kits (“start here”)
Spaces or sort-by-name: bulk-created views already use prefixes [HoD], [CSO], [SL], [IC] so kits cluster in the sidebar (see linear-views.md — persona prefixes).
apps/platform/scripts/create-linear-views-bulk.ts syncs those shared issue views plus per-client ([CSO] …) and per-internal-team ([HoD] …) lenses from linear-views-teams.config.json. Project / initiative / dashboard views are still manual per linear-views.md.
IC — Day 1
- Confirm your default team in Linear matches where you file work.
- Use built-in My issues (assignee = you) for daily focus; optional
[IC] AI-assignablefrom the bulk script for agent-eligible work. - Before closing the day: every active issue you own has a project and up-to-date state.
- If blocked on the client: use
client-dependency(and blocked state if used) and ping CSO. - If technical ambiguity: ping Service Lead early — see IC README.
CSO — Day 1
- Bookmark
[CSO] [Your client] — …views from the bulk script (active, no assignee, no project, overdue, due this week, client dependency, stale 4w) — see § C1. - Bookmark
[CSO] Blocked — client dependency(workspace-wide chase list) and[HoD]portfolio views (Overdue, Due this week, global hygiene) as needed. - For projects: use Active projects and Led by [you] if you are project lead — linear-views.md — Project views.
- Read project-ownership-guide.md for initiative/milestone expectations.
Service Lead — Day 1
- Build one cross-client issue view per line:
Team ∈ {Operating roster for your line}+ active states — step-by-step: sl-cross-client-views.md. - Monthly: reconcile Operating roster ↔ teams in that view (same doc).
- Optional: use
[SL]Service - … and[SL]Subservice - … views only if labels are trustworthy — run linear-prereq-hygiene first.
Head of Delivery — Day 1
- Bookmark
[HoD]workspace hygiene views (stale, unowned, no project, overdue, etc.) and[HoD] Platform — …/[HoD] Delivery — …/[HoD] GTM — …internal kits from the bulk script. - Use project and initiative views from linear-views.md for portfolio drift (No initiative, Active initiatives).
- Optional: one Dashboard with overdue + stale + blocked widgets — same catalog.
- Role home: README.md.
Appendix A — Tighter Linear configuration (Brainforge)
Use this as a maturity checklist; several items already have playbooks.
| Area | Why | Reference |
|---|---|---|
| Workflow states | Consistent meaning across client teams | linear-status-cleanup.md; apps/platform/scripts/audit-linear-workflow-states.ts |
| Team hierarchy | Cleaner nav (e.g. Ops, Sales subtrees) | linear-cleanup-taxonomy.md §1 |
| Initiative + project discipline | Fewer orphan issues and invisible work | .cursor/skills/linear-structure-hygiene/SKILL.md |
| Project lead | Clear ownership for portfolio filters | linear-views.md — Project views |
| Milestones | Client checkpoints visible | Taxonomy + CSO standards matrix |
| Issue / project templates | Faster kickoff, fewer orphans | Offering linear-template.md files under knowledge/sales/services/ |
| Cycles | If used, align to planning cadence | linear-views.md — D2 |
| Triage / automations | Reduce unowned queues | Linear native automations (evaluate per team) |
| Integrations | GitHub / Slack context on issues | linear-api-setup.md |
| Archive | Keep active teams readable | ARCHIVE team / archived projects per cleanup discovery practices |
Appendix B — Scripts (platform repo)
| Script | Use |
|---|---|
apps/platform/scripts/create-linear-views-bulk.ts | Sync shared issue views (51 with default JSON) using [HoD] / [CSO] / [SL] / [IC] prefixes; clientTeams + internalTeams in linear-views-teams.config.json; --dry-run to list; --prune-legacy once to drop old unprefixed names |
apps/platform/scripts/dedupe-linear-custom-views.ts | Delete extra custom views when the same name exists more than once (keeps newest) |
apps/platform/scripts/list-and-delete-linear-views.ts | List all custom views (paginated); --delete for blank slate |
apps/platform/scripts/create-linear-view-not-updated-4-weeks.ts | Single “stale” view create/update |
Extend client and internal team kits via apps/platform/scripts/linear-views-teams.config.json (clientTeams, internalTeams).
Appendix C — Service Lead roster cadence (monthly)
- Export current Operating allocation for your line (which client teams have your service).
- Open your cross-client saved view in Linear; confirm Team filter matches that roster.
- If a client onboarded/offboarded, update the view and note the change in service line review.
Full procedure: sl-cross-client-views.md.
Related
- linear-custom-views-audit.md — Audit log and listing commands
- linear-prereq-hygiene.md — When to run structure/label hygiene
- INDEX.md — Delivery navigation