Skip to content
Surfc Wiki

Linear Setup Guide

Linear Setup Guide

This guide covers the one-time setup of Linear for Surfc project management.

1. Create your workspace and project

  1. Go to linear.app and sign in
  2. Create a new Team called Surfc
  3. Under the team, create a Project called Surfc App

2. Configure issue labels

Create the following labels (these match the GitHub issue templates):

Type labels:

  • feature — green
  • bug — red
  • chore — grey
  • docs — blue
  • refactor — purple

Priority labels (Linear has built-in priority — use that instead of custom labels):

  • Urgent (p0)
  • High (p1)
  • Medium (p2)
  • Low (p3)

3. Set up the kanban board

Linear’s default workflow states work well. Adjust to:

StateMeaning
BacklogCaptured but not yet scheduled
TodoScheduled for current or next milestone
In ProgressClaude Code is actively working on it
In ReviewBranch pushed, PR open, awaiting review
DoneMerged and deployed
CancelledWon’t do

4. Create Milestones (Cycles in Linear)

Create the following Cycles:

  • v1.1 — Foundation
  • v1.2 — Import & Share
  • v1.3 — Platform

5. Connect GitHub

  1. Go to Settings → Integrations → GitHub
  2. Connect your GitHub account
  3. Select the surfc repository
  4. Enable: Sync issue states, Link PRs to issues

Once connected:

  • Opening a PR with an issue ID in the branch name or description auto-links them
  • Merging the PR moves the Linear issue to Done automatically

6. Create the initial issues

Create one issue per roadmap item using the details in docs/product-roadmap.md.

Use this naming convention: SUR-1, SUR-2 etc. (Linear assigns these automatically).

Reference the issue ID in commit messages:

feat(notes): add readwise api token field in settings [SUR-2]

7. Daily workflow

Starting work:

  1. Move the Linear issue to “In Progress”
  2. In Claude Code: create a branch for SUR-1 and start the App.jsx refactor

Finishing work:

  1. Claude Code pushes the branch and opens a PR
  2. Move the Linear issue to “In Review”
  3. Review and merge the PR
  4. Linear auto-moves the issue to Done (if GitHub integration is active)
  5. Update CHANGELOG if user-visible

Linear vs GitHub Issues

Both are in use:

  • Linear — day-to-day task management, kanban board, sprint planning
  • GitHub Issues — the permanent record linked to PRs and commits

When you create an issue in Linear, also create the corresponding GitHub Issue (or use the Linear GitHub integration to sync them automatically). This keeps the git history fully traceable.