πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
docs(agents): remove linear-planning and keep Linear writes short (#17276)
Nikita Kabardin1acfa5d94db3
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.mdindex 150719ce80..c5667dd244 100644--- a/.agents/AGENTS.md+++ b/.agents/AGENTS.md@@ -115,6 +115,9 @@ than two sentences they read.code that no longer exists.- Never commit secrets or credentials. Keep `.env*.example` files insync with required env vars.+- Tracker writes default to short. "Create a subticket", "file this", or+ "add a ticket" get a title and a few sentences a human would write.+ Expand with research only when they ask.- Human handoff: assume the reader does not remember the ticket. Lead witha one-sentence TL;DR. Prefer one or two human actions per message; ifyou need more, keep every point simple and super readable. Do not dump@@ -149,10 +152,9 @@ Two moments in every task, both easy to skip and both expensive:one session otherwise. Do it before the PR, not after the merge: there is nolater.-The practice, its template and its tooling are the `linear-context-handover` and-`linear-planning` skills, alongside `linear-agent-writes`, which is the policy for-what an agent may write to the tracker and how it must be marked. Read those-rather than improvise. If this environment cannot reach the tracker, say so in your reply and+The practice, its template and its tooling are `linear-context-handover` and+`linear-agent-writes`. Read those rather than improvise. If this environment+cannot reach the tracker, say so in your reply andhand back the text that should have gone on the work item β never skip eitherstep silently, because silent non-compliance looks exactly like compliance.diff --git a/.agents/skills/langfuse-codebase-navigator/SKILL.md b/.agents/skills/langfuse-codebase-navigator/SKILL.mdindex b5e7f9bb07..0845d94917 100644--- a/.agents/skills/langfuse-codebase-navigator/SKILL.md+++ b/.agents/skills/langfuse-codebase-navigator/SKILL.md@@ -30,8 +30,7 @@ Use this as the first stop for Langfuse org navigation. Your job is to choose th- Someone new, or you do not know whether you are talking to an outside contributor or a maintainer: use `langfuse-onboarding`.- "What should I do today", or preparing a weekly project update: use `linear-work-rhythm`.- Reconstructing why a surface is the way it is before changing it, or writing the reasoning behind finished work onto its Linear ticket: use `linear-context-handover`.-- Turning a feature into Linear subtickets that map onto an intended PR stack: use `linear-planning`.-- Before any agent write to Linear β a comment, a description edit, a ticket: use `linear-agent-writes`, the write policy.+- Before any agent write to Linear β a comment, a description edit, a ticket: use `linear-agent-writes`, the write policy. Ordinary writes stay a title and a few sentences.- Frontend work under `langfuse/langfuse/web`: also check `web/.agents/skills/vercel-react-best-practices` and `web/.agents/skills/vercel-composition-patterns`.- Infrastructure autoscaling or cloud capacity: use `infra-scaling`.- Public Langfuse usage, docs lookup, API access, instrumentation, prompt migration, SDK upgrade, trace analysis, or CLI work: use the public `langfuse` skill from `langfuse/skills`.diff --git a/.agents/skills/linear-agent-writes/SKILL.md b/.agents/skills/linear-agent-writes/SKILL.mdindex b44c1d0e76..76fb535b8e 100644--- a/.agents/skills/linear-agent-writes/SKILL.md+++ b/.agents/skills/linear-agent-writes/SKILL.md@@ -4,8 +4,9 @@ description: |The org policy for what an agent may write to Linear, and how it must bemarked. Read this before creating a ticket, editing a description, orcommenting on a ticket as an agent β "file this in Linear", "comment on the- ticket", "create subtickets for this plan", "write the handover". Also covers- the required Linear connection and what to do when there isn't one.+ ticket", "create a subticket", "write the handover". Default those writes+ to a short human description; expand with research only when asked. Also+ covers the required Linear connection and what to do when there isn't one.---# Linear agent writes@@ -28,6 +29,21 @@ tracker, and it has nothing to ask of an outside contributor.*Provenance: the "Agentic Coding and Linear" RFC (LFE-15914), which replaced theearlier "Linear is read-only for agents" posture.*+## Default length++Ordinary Linear writes are short. A new ticket or subticket is a title and+two to four sentences: what to do, and why in one line if it is not obvious.+Comments stay to the thing the watcher needs today.++Expand β research, file lists β only when they ask ("expand this", "add+context"). Do not invent an implementation-ready brief.++Wrong (they said "create a subticket"): six fields, entry-point files, a+stack position, a research essay.++Right: "Warn sunset event types on POST /ingestion request body. Fern still+lists trace-create as if it works; say those event types stop on Nov 16."+## Why the taboo went awayLinear used to be human-only for agents, and every skill that touched it had to@@ -73,18 +89,15 @@ description, and why an attachment is not optional are### 3. Create a ticket β a subticket freely, a top-level one after a yesLabel `AI created`. Say in the description that an agent created it and who it is-for.+for. Default length is the short human ticket in *Default length* above.-**A subticket of an existing ticket needs no permission.** The intended use is-planning: one subticket per PR in an intended stack, created up front so the plan-is visible before any branch exists, with enough context in each that an agent-could implement it from the ticket alone β-[`linear-planning`](../linear-planning/SKILL.md) is how.+**A subticket of an existing ticket needs no permission.** File the short+ticket. "Create a subticket" / "file this" / "add a ticket" is this shape.**A ticket with no parent needs the human's yes first** β a top-level issue, or-one filed straight into a project. Show the title and the description you intend-to file, get an explicit go-ahead, then **create it yourself**; do not hand the-text back for them to paste, which is the cost you were meant to remove.+one filed straight into a project. Show the title and the short description you+intend to file, get an explicit go-ahead, then **create it yourself**; do not+hand the text back for them to paste, which is the cost you were meant to remove.This is the only gate in this policy, and it exists because a parentless ticketlands in somebody's triage queue. It is the one shape whose cost falls on peoplediff --git a/.agents/skills/linear-context-handover/SKILL.md b/.agents/skills/linear-context-handover/SKILL.mdindex 5f5c1134ff..ccc0ca61eb 100644--- a/.agents/skills/linear-context-handover/SKILL.md+++ b/.agents/skills/linear-context-handover/SKILL.md@@ -4,7 +4,7 @@ description: |Use Linear as the org's memory: reconstruct a feature's history beforetouching it, and leave the reasoning behind finished work in the ticketdescription so the next agent inherits it. Use when starting work on an- existing feature, when planning multi-PR work, and always when wrapping up β+ existing feature, when splitting a large change, and always when wrapping up β"what happened to this screen before", "write the handover", "why is thiscode like this".---@@ -28,8 +28,10 @@ it before your first write. This file is the *craft* β where post-context goeswhat earns a place in it, and the two mechanics that stop it being destroyed onthe way in.-How to slice a big change into PRs, and what a planning subticket must contain,-are the sibling skill: [`linear-planning`](../linear-planning/SKILL.md).+How to slice a big change into PRs is+[`pr-stack-workflow`](../pr-stack-workflow/SKILL.md). That is git/PR+mechanics. Reconstructing history is not a reason to file a stack of+subtickets.## Before you touch a feature: reconstruct its historydiff --git a/.agents/skills/linear-context-handover/scripts/lf-context.sh b/.agents/skills/linear-context-handover/scripts/lf-context.shindex c2914af987..144c541f73 100755--- a/.agents/skills/linear-context-handover/scripts/lf-context.sh+++ b/.agents/skills/linear-context-handover/scripts/lf-context.sh@@ -8,7 +8,7 @@# -> ticket, parent, subtickets, relations, project, AI handover## Shipped with the `linear-context-handover` skill, which is the reading and-# writing practice around it; the planning practice is `linear-planning`.+# writing practice around it.# Provenance: LFE-15914 ("Agentic Coding and Linear: an RFC").## Run it from inside the checkout you are about to change, or point it at one@@ -384,8 +384,7 @@ elsenote ""note "then read each description's 'π€ AI post-context' block before designing anything:"note "a reversal already litigated once does not need re-litigating."- note "practice: the linear-context-handover skill (reconstruct + handover),"- note " the linear-planning skill (slicing a feature into a PR stack)."+ note "practice: the linear-context-handover skill (reconstruct + handover)."fiprintf '\n'diff --git a/.agents/skills/linear-planning/SKILL.md b/.agents/skills/linear-planning/SKILL.mddeleted file mode 100644index 9aaf815715..0000000000--- a/.agents/skills/linear-planning/SKILL.md+++ /dev/null@@ -1,117 +0,0 @@-----name: linear-planning-description: |- Plan a feature in Linear as subtickets that map 1:1 to a chained PR stack,- with enough context in each ticket that an agent could implement it from the- ticket alone. Use before writing code for anything bigger than a one-commit- fix β "plan this feature", "split this branch into reviewable PRs", "turn this- RFC into tickets", "open a PR stack".------# Planning a feature as Linear subtickets--**One idea:** the planning session is where the expensive thinking happens, and-it evaporates when the session ends. Write it into subtickets *while* you plan,-one subticket per PR you intend to open, so the implementation can be handed to-any agent β a cloud agent, a colleague, a session next month β and nothing is-lost.--This skill owns the Linear half: whether to plan at all, and what a subticket-must contain. It does not own the PR mechanics.--- **Where to cut the slices, the stack rules, and how to verify each branch** are- [`pr-stack-workflow`](../pr-stack-workflow/SKILL.md). Read it for the slicing;- this file does not restate it.-- **What an agent may write to Linear and how it must be marked** is- [`linear-agent-writes`](../linear-agent-writes/SKILL.md). Read it before your- first write.-- **Reconstructing history before you plan, and the handover after you ship**,- are [`linear-context-handover`](../linear-context-handover/SKILL.md).--## Step 0 β reconstruct before you slice--Run the context CLI on the files you are about to change, then read what it finds:-[`linear-context-handover`](../linear-context-handover/SKILL.md) β *reconstruct-its history*. Half the design questions have already been answered somewhere in-that chain, and a decision that was already reversed once does not need-proposing again.--## Does it need a plan at all?--The discriminator is in [`pr-stack-workflow`](../pr-stack-workflow/SKILL.md) β-*Decide whether it needs a stack*:-one sentence without an "and", a default or persisted shape that needs a-migration decision, a shared component, a click-path verification. Use that-table; it is the same question.--Two consequences for the tracker specifically:--- **If the fix is one commit, the ticket already is the plan.** Do not manufacture- subtickets for it. Hand the ticket to an agent as the whole brief.-- **If you cannot yet write the acceptance check, you are researching, not- planning.** Do the research and put *it* on the parent ticket β the numbers, the- screenshots, an attached `.md`. The plan is the second document, not the first.--## One subticket per slice, created up front--Create the whole set before any branch exists, so the plan is reviewable as a-plan. Each is a **subticket of the existing ticket**, which needs no permission.-If the work has no parent ticket yet, that parent is a top-level ticket β show it-and get a yes before filing it, then plan underneath it.--The worked example is the experiments-UI rebuild: 54 commits on one branch became-eight subtickets under LFE-15711 and eight chained PRs (#16912β#16919), one to-one, in landing order. PR #1 merged while #2β#8 were still in review, which is the-whole point of planning it as a stack rather than discovering the split at review-time.--## What a subticket must contain--The bar is not "a human can follow this". It is: **hand it to an agent with no-session history and it can implement it.** Six fields, every time β paste-ready-shape in [`references/subticket-template.md`](references/subticket-template.md):--1. **The change**, in one imperative sentence. "Show the 24 populated score- columns by default." If it needs an "and", it is two subtickets.-2. **The evidence that justifies it** β the number, the quote, the screenshot.- `98% of column-picker use on this table ends with a score column added (440 of- 449 users, 90d)`. Without this, review re-litigates the design.-3. **Entry-point files** β two to five paths, with the line where the behavior- lives, and the mechanism if it is not obvious from the file.-4. **The acceptance check** β a click path with a URL and an observable outcome,- plus the seeded data it needs. *Expect 24 score columns, all populated, 0- blank*, not "looks better".-5. **Position in the stack** β `4/8, branches off #16914, base retargets to main- when #16914 lands`.-6. **Deliberately not in scope**, with where it went instead. This is the field- that stops an implementer helpfully widening the slice and breaking the union- check.--An empty field is usually a sign the slice is not understood yet, not a sign the-field is optional. *Not in scope* is the exception β it is empty only when nothing-was tempting.--## Labels and boundaries--Planning this way uses two of the three permitted write shapes: creating-subtickets, and writing into descriptions. **The policy is not restated here** β-[`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority for-which shapes are allowed, which label stamps each, and what still belongs to a-human.--The two rules you will hit immediately while planning:--- **Subtickets are free; the top of the tree needs a yes.** Planning under an- existing ticket needs no permission. Creating the parent itself does.-- **Stamp every shape you used.** A subticket you created *and* wrote the plan- into carries both `AI created` and `AI edited`.--Estimates, priorities, assignees and cycle stay unset. Suggest them in your reply-instead.--## When the stack lands--Wrap up with [`linear-context-handover`](../linear-context-handover/SKILL.md): the-substantial handover on the parent, short pointers on the leaves, `AI edited` on-each. The parent's subticket list plus those blocks are exactly what the context-CLI hands the next agent.diff --git a/.agents/skills/linear-planning/agents/openai.yaml b/.agents/skills/linear-planning/agents/openai.yamldeleted file mode 100644index d293db5e90..0000000000--- a/.agents/skills/linear-planning/agents/openai.yaml+++ /dev/null@@ -1,4 +0,0 @@-interface:- display_name: "Linear Planning"- short_description: "Plan a feature as subtickets mapped to a PR stack"- default_prompt: "Use $linear-planning to turn a feature into Linear subtickets that map one-to-one onto a chained PR stack, each carrying enough context to be implemented from the ticket alone."diff --git a/.agents/skills/linear-planning/references/subticket-template.md b/.agents/skills/linear-planning/references/subticket-template.mddeleted file mode 100644index 736a2f6305..0000000000--- a/.agents/skills/linear-planning/references/subticket-template.md+++ /dev/null@@ -1,77 +0,0 @@-# Planning subticket template--One subticket per PR in the intended stack, created as a **child of the existing-ticket** β which needs no permission β and labelled `AI created`. Filing the-parent itself is a top-level ticket and needs a yes first.--The bar is not "a human can follow this". It is: **an agent with no session-history can implement it from the ticket alone.** If a field would be empty, that-is usually a sign the slice is not understood yet β not a sign the field is-optional. The exception is *Not in scope*, which is empty only when nothing was-tempting.--Title: imperative, names the surface, no ticket-speak.-`Show the populated score columns by default on the experiments list`--```markdown-*Created by <agent> on <date> while planning <PARENT-ID>, for whoever implements-slice N of the stack. Everything here is agent-written.*--## The change--<One imperative sentence. If it needs an "and", it is two subtickets.>--## Why β the evidence--<The number, the quote, or the screenshot that justifies it. Name the source and-the window: "440 of 449 users (98%), 90 days, users not pageviews". A design-opinion with no evidence line is fine β say so explicitly, so review argues about-the right thing.>--## Where it lives--- `web/src/.../ThisFile.tsx:757` β <what is there today>-- `packages/shared/src/.../thatQuery.ts` β <the projection that has to change>--<2β5 entry points. Not a file list of the diff β the places an implementer starts-reading. Include the mechanism if it is not obvious from the file:-"both families are discovered with the same filter, so each level produces an-always-empty twin".>--## Acceptance check--1. `http://localhost:3025/project/<id>/experiments`-2. <click path>-3. Expect: <observable outcome with a number β "24 score columns, all populated,- 0 blank" β not "looks better">--<Plus the seeded data or scenario the check needs, and the command that produces-it.>--## Position in the stack--`N/M` Β· branches off #<parent PR> Β· base retargets to `main` when that lands Β·-must pass the repo's verification bar on its own branch, not only on the stack-tip.--## Not in scope--- <The tempting adjacent change> β stays in <TICKET-ID> / on the parent, because- <reason>.-```--## After the PR merges--Do not rewrite this block. Append the leaf handover pointer below it and add-`AI edited` alongside `AI created` β see-[`linear-context-handover`](../../linear-context-handover/references/handover-template.md).--## What not to put in a planning subticket--- The whole design doc. Link the parent, or attach an `.md`; eight copies of one- essay is noise.-- A status narrative ("first we tried X"). That belongs in the handover, after.-- Estimates, priorities, assignees, cycle β human-only fields. Leave them unset- and mention the suggestion in chat.-- Anything confidential: no customer names, no support-ticket ids, no vendor- references. Same rule as the public PR artifacts.diff --git a/.agents/skills/linear-work-rhythm/SKILL.md b/.agents/skills/linear-work-rhythm/SKILL.mdindex 9a613892bd..ab5d5f3c1e 100644--- a/.agents/skills/linear-work-rhythm/SKILL.md+++ b/.agents/skills/linear-work-rhythm/SKILL.md@@ -256,9 +256,8 @@ A ticket, a pull request, a Slack permalink, a screenshot. Read it, work out whait is asking for, and propose the next step β do not ask which skill applies.- **A tracker ticket** β reconstruct its history first- ([`linear-context-handover`](../linear-context-handover/SKILL.md)), then say- whether it is one commit or needs planning- ([`linear-planning`](../linear-planning/SKILL.md)).+ ([`linear-context-handover`](../linear-context-handover/SKILL.md)), then+ propose the next step.- **A Slack permalink** β read the thread if a Slack tool is connected. If it isnot, say so in one line and ask them to paste it; do not guess from the URL.What usually follows is a ticket, so offer to draft one β and remember adiff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.mdindex 0babbe54dc..9fc8f13ebe 100644--- a/.agents/skills/skill-creator/SKILL.md+++ b/.agents/skills/skill-creator/SKILL.md@@ -61,7 +61,7 @@ keep correct. In summary, a skill may:rewrites the human's prose. This is where durable context belongs.3. **Create a ticket** β a subticket of an existing ticket needs no permission; aticket with no parent needs the human's yes first, and then the skill files it- itself.+ itself. Default the body to a short human description.Assigning, moving state, closing, estimating, re-prioritising, deleting,projects, and new labels still belong to a human. A skill that wants one of those