--- title: Using Linear description: How we use Linear for task management and product ops. --- # Using Linear We use Linear for all internal ticketing / task management. Linear is the backbone of our [product ops](/handbook/product-engineering/how-we-work/product-ops) that allows us to move fast as a small team while working with a large community of customers and OSS users. Our workspace is `clickhouse`. Engineering work lives in `LFE` (Langfuse Engineering), part of `Langfuse (LF)`. ## Principles - Linear is the source of truth for executing work. Do not keep a parallel status tracker in Slack, spreadsheets, or Figma — the one exception is the long-term [roadmap](/handbook/product-engineering/how-we-work/roadmapping), which stays in Figma. - Everyone maintains their own issues and projects - We do not have someone on the team that manages the backlog centrally → outside the triage queue, there should be no issues that are not assigned to someone. - Every active project and issue has one lead. - Create Linear issues for tasks that are likely to happen within the next 6 months. Everything beyond that can be tracked on the [roadmap](/docs/roadmap) and [GitHub ideas](/ideas). Close, cancel, or backlog anything that is no longer likely within six months. ## How to use Linear - SLA: Clear out the Linear Inbox at least twice per working day. This is the main on-topic discussion channel. Triage for importance, and reply immediately when the reply takes less than two minutes. Use `H` to snooze anything you want to come back to. - Use Linear comments for durable, on-topic discussion and decisions. Link a Slack thread when you need a faster turnaround. - Git: - When making a change, copy the branch name from Linear issue, which leads to automatic linking of PR to Linear issue. - Once PR is merged, issue is moved to the `merged` state. See [definition of done](#definition-of-done) for what happens next. ## Projects and issues [#projects-and-issues] Use the smallest primitive that fits the work. | Primitive | When to use it | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Issue** | One concrete deliverable with one owner. The default. Small improvements and fixes stay issues and never need a project. | | **Project** | Multi-step work that needs several issues, coordination, progress reporting, or delivery stages. Projects need project management, so only open one for real work. | | **Milestone** | Optional, for larger projects: a meaningful delivery phase such as "planning complete" or "minimum viable release" — not a checklist. | | **Initiative** | Rare. A broad, multi-quarter outcome spanning several projects. Projects and issues are usually enough. | Do not create a project just to group loosely related issues — use a label and a saved view for that. A project normally has zero or one RFC; if it needs two, it is probably two projects. Where there is an RFC, it belongs in the project description. ### Project lifecycle | Status | What it needs | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Backlog** | Likely within six months. Owner, priority, pod/function label, a short outcome. | | **Planned** | Owner, priority, a quarter-level target date, pod/function label, a brief and a definition of done, and known dependencies. | | **In Progress** | A specific target date, current health, weekly updates, linked issues — plus milestones if the project is large. | | **Completed** | The intended outcome is delivered, not merely that the issue list is empty. Follow-ups captured; docs, changelog and customer follow-up done where relevant. | | **Canceled** | Intentionally stopped, with a short reason. | Target dates are internal planning signals, not external commitments. The public roadmap stays directional. At quarter-end every remaining backlog project is deliberately re-prioritised, moved to a new quarter, or cancelled. Nothing rolls forward silently. ### Weekly project updates If you lead an active project, post an update before Monday planning. Nothing reminds you, so make it part of your Friday or Monday morning: - Health - Progress since the last update - Next step - Blockers, or decisions you need from someone else - Any change to the target date Separately, look through your own open bugs regularly to catch anything slipping. ## Definition of done [#definition-of-done] An engineering issue moves to `merged` automatically when its pull request merges. It does **not** go straight to `done`. `merged` is deliberately a staging step: it is your chance to capture what you do not want to forget before the issue leaves your view. Once the change is deployed to production, and before moving it to `done` by hand, check whether it needs - a documentation page or edit, - a changelog entry, - a word to any customer whose request is linked to it, - the reasoning behind it written onto the issue, so that whoever picks the surface up next does not have to reconstruct it. If an agent did the work, the `linear-context-handover` skill is how it leaves that behind. Complete a **project** when its intended outcome is delivered — including docs, changelog and customer follow-up where relevant. ## Labels - Every issue carries one label from the `Kind` group: `bug`, `improvement`, or `feature`. - On top of that, use a well-known label for the product area, so filters and shared views work. See the [conventions in how we ship](/handbook/product-engineering/how-we-work/how-we-ship#linear-conventions). - Do not recreate owner, status, priority, dates, initiatives, or customer links as labels — Linear already has fields for those. ## Bugs and feature requests Most work arrives rather than being typed in: GitHub Issues from `langfuse/langfuse` land in the engineering team automatically, customer reports come in through Pylon, and we often create an issue straight from the Slack thread where something came up. A customer request is evidence linking a customer to an issue, not a second issue to execute — when several point at the same thing, keep all of the evidence on it. Feature owners clear triage continuously and normally decide within one working day: merge it with an existing issue, accept it, put it in a backlog project, re-route it, or close it as not planned. ## Agents may write to Linear [#agents] Agents are allowed to write to Linear directly — there is no longer a rule that one must stop and ask a human first. They comment, append their reasoning to an issue description, and create issues. They do have to follow rules, and **the rules are not repeated here.** They live as agent skills in the `langfuse/langfuse` repository, under `.agents/skills/`, together with the tooling that implements them: - `linear-agent-writes` — what an agent may write and how each write must be marked. Read this one before your first agentic write. - `linear-planning` — planning a feature as issues that map onto a stack of pull requests. - `linear-context-handover` — recovering the history behind a piece of work, and leaving your reasoning on the issue when you finish. Keeping them in the repo means an agent loads them where the work happens, and there is one copy to keep correct. The short version: every agent write is labelled and says in its own text that an agent wrote it, so you can always tell at a glance which words on an issue are a person's. Changing state — assigning, moving, closing, prioritising — stays with a human. ## Setup Linear ### Mandatory - Connect to Slack and GitHub - Join the Langfuse teams you need: `Engineering (LF)`, `Langfuse`, and whichever of `Marketing (LF)`, `Sales (LF)`, `Ops (LF)` and `General (LF)` apply to your work - Set "assign to self on creation" so issues you create are owned from the start ### Optional - Connect to Cursor Background Agents to delegate tasks to AI --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/handbook/tools-and-processes/using-linear.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .