πͺ’ 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): propose Linear ticket updates before writing (#17176)
Nikita Kabardina85d3ecd8414
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.mdindex c5667dd244..93fd7cf4a6 100644--- a/.agents/AGENTS.md+++ b/.agents/AGENTS.md@@ -3,69 +3,18 @@Langfuse is an open source LLM engineering platform for developing, monitoring,evaluating, and debugging AI applications.-## Who You Are Working For+## Scope-This repo serves two different people, and they get different halves of it.-Work out which before anything else, and never guess silently.+**Outside contributor** β code and `CONTRIBUTING.md` only (build, checks, PRs).+No tracker, handbook, or working-week context.-It is a configuration question, not an interview. Read the workspace-identity file in `.langfuse/` (`me.md`, gitignored) if it exists. Do-**not** Read or Write `~/.config/langfuse/me.md` β that path is outside-the project, and workspace-scoped harnesses (OpenCode) prompt on it.-Identity there is optional; if the workspace file is missing,-`langfuse-onboarding` step 1 names them. On Cursor Cloud that is the run-owner (`cursor-cloud` `run-info`) plus the team roster β **not**-`gh api β¦permissions`, because Cloud's GitHub token is a read-only-integration and reports `push: false` for maintainers. Desktop still uses-`gh api user` then `.permissions.push`. For anything those cannot tell-you β which areas they work on β **just ask, once**, and write the-answer into `.langfuse/` so nobody asks again. Someone who has worked-here for a year does not need onboarding; they need you to know their-name. `langfuse-onboarding` is for people who are actually new.--**An outside contributor** gets the code and `CONTRIBUTING.md`: how to build it,-what the checks require, how to open a pull request. Nothing about the tracker,-the handbook, or the working week β they cannot open any of it, and offering it-describes a locked door.--**A maintainer** gets all of that plus an assistant that holds the-organisational context they would otherwise carry in their head. Be that-assistant, not a code-completion engine waiting for instructions:--- **Answer "what should I do today."** Not from memory β from the tracker. Which- projects they lead, which owe an update before Monday planning, what shipped- but is not finished. `linear-work-rhythm`.-- **Know what the rest of the team is doing.** Colleagues post project updates- weekly. Before someone designs against a surface, check whether a colleague- touched it recently and say so: *"Trang was reworking that flow last week β- worth asking her to review."* Naming the person is more useful than naming the- ticket.-- **Take a link and run with it.** A tracker ticket, a pull request, a Slack- permalink, a screenshot: read it, work out what it is asking for, and propose- the next step. Do not ask which skill to use β that is your job to know.-- **Volunteer what is organisationally due**, briefly, when it is relevant: an- update nobody has written, an issue sitting in `Merged` with no docs decision,- a project whose target date has quietly passed. Once, in a line, not as a- standing report.-- **Propose the implementation.** Not everyone here works with agents the same- way. When someone describes a problem, offer a route through it rather than- waiting to be told the design.--The handbook is the source for how the team works, and it is not optional-reading: `content/handbook/**` in `langfuse/langfuse-docs`, read from-`origin/main`. When it disagrees with a skill, say so β one of the two is wrong.--Keep it short. A maintainer is mid-task; a paragraph they have to skim is worse-than two sentences they read.+**Maintainer** β that plus a short organisational assist: what the tracker says+they should do today (`linear-work-rhythm`), who else touched a surface recently,+and a concrete next step when handed a link. Keep answers short. Handbook:+`content/handbook/**` in `langfuse/langfuse-docs` on `origin/main`.## How To Work-- Know who you are working for before you assume what they may do. An outside- contributor and a Langfuse maintainer get different halves of this repo, and- the difference is derivable β the workspace identity file in `.langfuse/`- if it exists, else `langfuse-onboarding` step 1 (Cloud run owner, not- Cloud `gh` permissions). Do not Read `~/.config/langfuse/me.md`. Never- guess it silently.- Read the minimal local context required for the task.- Keep changes scoped and avoid unrelated refactors.- Delegate exploratory or noisy work β broad code search, multi-file@@ -138,25 +87,17 @@ than two sentences they read.## Context Handover-Two moments in every task, both easy to skip and both expensive:--- **Before you touch an existing feature, reconstruct its history.** Walk- commits, the PRs that carried them, and the head branch name β which is where- the work-item identifier lives β through to the work item itself and any prior- agent context on it. The commands are in- `.agents/skills/pr-stack-workflow/references/stack-commands.md` β *Recover the- context before you slice*. A decision already reversed once does not need- proposing again.-- **Before you ask for review or merge, leave your reasoning on the work item**- β the decisions, the reversals, how the human steered, the traps. It survives- one session otherwise. Do it before the PR, not after the merge: there is no- later.--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 and-hand back the text that should have gone on the work item β never skip either-step silently, because silent non-compliance looks exactly like compliance.+- **Before changing an existing feature**, reconstruct history (commits β PRs β+ branch β ticket). Prefer `linear-context-handover` over guessing.+- **Before review/merge, or at the end of a productive session**, ask whether to+ preserve results on the ticket(s) β e.g. "Should I update the ticket(s) with+ the results of this session so they are preserved?" Show the block; write only+ after a yes ("write the handover" counts). Policy: `linear-agent-writes`.+ Ordinary Linear writes stay short (title + a few sentences) unless asked to+ expand.+- Large work: prefer small reviewable PRs; create subtickets under an existing+ parent freely when that helps. If the tracker is unreachable, say so and leave+ the text in the reply.## Project Structure@@ -207,12 +148,9 @@ langfuse/### Cursor Cloud specific instructions-- Identity: `cursor-cloud` `run-info` (`owningUserName`, `owningUserEmail`),- then the roster. Repo postinstall and Cloud start normally recover the- workspace identity file in `.langfuse/` from `LINEAR_API_KEY` first (and- a machine-level copy under `~/.config/langfuse` when the harness allows- it). Read the workspace file. Ignore `git config`- (`[email protected]`) and Cloud `gh` `.permissions.push`.+- Ignore `git config` (`[email protected]`) and Cloud `gh`+ `.permissions.push` β Cloud's GitHub token is a read-only integration and+ often reports `push: false` for maintainers.- Linear: MCP if already authorized; else a real read with `LINEAR_API_KEY`(or `LINEAR_TOKEN` / `LINEAR_API_TOKEN`). Interactive `mcp_auth` does notwork in Cloud. If neither works, tell them to add **`LINEAR_API_KEY`** as adiff --git a/.agents/README.md b/.agents/README.mdindex 3bee3d3b44..b88562bf77 100644--- a/.agents/README.md+++ b/.agents/README.md@@ -232,16 +232,6 @@ idempotent setup and then installs Cursor's Playwright system dependencies.Each agent run starts the six-service source stack with`scripts/agents/start-cursor-cloud.sh`.-Identity recovery runs in both repo postinstall and Cursor Cloud start. When-`LINEAR_API_KEY` is available, it verifies the viewer belongs to the Langfuse-team and writes `.langfuse/me.md` (gitignored, inside the checkout) without-exposing the key. A machine-level copy under `~/.config/langfuse` is also-written when the harness allows home-dir access; OpenCode and similar-workspace-scoped tools skip that path so they do not prompt on the user-dir. Neither file is overwritten, so human corrections survive repeated-installs and worktrees. Running it at Cloud start matters because-environment builds do not rerun install for each new agent.-The start script builds and waits for web, worker, PostgreSQL, ClickHouse,Redis, and MinIO, seeds the synthetic demo project, and verifies the web andworker health endpoints. The default Cursor VM is accepted only after threediff --git a/.agents/skills/cursor-agents-workflow/SKILL.md b/.agents/skills/cursor-agents-workflow/SKILL.mdindex 6d53fe67b2..aa2c9c743c 100644--- a/.agents/skills/cursor-agents-workflow/SKILL.md+++ b/.agents/skills/cursor-agents-workflow/SKILL.md@@ -42,9 +42,7 @@ use `LINEAR_API_KEY` (or `LINEAR_TOKEN` / `LINEAR_API_TOKEN`) via GraphQL or`lf-context.sh`. If that env is unset, **say so** and tell them to add**`LINEAR_API_KEY`** at https://cursor.com/dashboard/cloud-agents, then start anew run. Langfuse engineers: the write policy is-[`linear-agent-writes`](../linear-agent-writes/SKILL.md). Identity is-[`langfuse-onboarding`](../langfuse-onboarding/SKILL.md) β Cloud `run-info`, not-Cloud `gh` permissions.+[`linear-agent-writes`](../linear-agent-writes/SKILL.md).If Linear is not reachable, **say so in your handoff message** and hand backthe context that should have gone on the ticket. Do not skip it silently.diff --git a/.agents/skills/git-workflow/SKILL.md b/.agents/skills/git-workflow/SKILL.mdindex 2de6b2d8a0..efa0fb667c 100644--- a/.agents/skills/git-workflow/SKILL.md+++ b/.agents/skills/git-workflow/SKILL.md@@ -54,7 +54,7 @@ operations.- Prefer non-interactive Git and GitHub commands where possible.- Keep PRs narrow enough to review without unrelated refactors.- When a change is too large for one reviewable PR, split it into a chained- stack instead of widening the PR: use `pr-stack-workflow`.+ stack of small PRs instead of widening one.- Open PRs as reviewable, not as drafts, unless a human asks for a draft.- Cursor agents apply the GitHub `cursor` label after opening a PR; see`cursor-agents-workflow`. Do not leave that tag for a human.diff --git a/.agents/skills/housekeeping/SKILL.md b/.agents/skills/housekeeping/SKILL.mdindex 55f2c7e835..1d463420e3 100644--- a/.agents/skills/housekeeping/SKILL.md+++ b/.agents/skills/housekeeping/SKILL.md@@ -40,7 +40,7 @@ Include confidence for each recommendation: `high`, `medium`, `low`, or `unknown3. Inspect comments, latest activity, linked issues, checks, and review threads when status or ownership is ambiguous.4. Cluster duplicates or related items before prioritizing.5. Return recommendations ordered by urgency, then quick wins, then cleanup.-6. Present the recommendations as a decision table for the engineer to act on. Every action this skill recommends is a state change reserved for a human, so do not perform them. If a queue item needs a note left on it for someone else, that is a comment or a description edit, which agents do write β see [`linear-agent-writes`](../linear-agent-writes/SKILL.md) for the shapes and the labels.+6. Present the recommendations as a decision table for the engineer to act on. Every action this skill recommends is a state change reserved for a human, so do not perform them. If a queue item needs a note left on it for someone else, that is a comment or a description edit β propose it, get a yes, then write; see [`linear-agent-writes`](../linear-agent-writes/SKILL.md).## Linear Review@@ -109,13 +109,13 @@ Recommend:- `stale-candidate` for old, conflicting, duplicate, or superseded PRs.- `no-action` when a PR is blocked on the author, failing CLA, merge conflicts, unresolved requested changes, or unrelated team ownership.-Do not approve, request changes, comment, close, merge, or edit a PR without explicit human approval for that PR. This is about **GitHub pull requests**, not the issue tracker β tracker comments and description edits follow `linear-agent-writes` and need nobody's permission.+Do not approve, request changes, comment, close, merge, or edit a PR without explicit human approval for that PR. This is about **GitHub pull requests**, not the issue tracker β tracker comments and description edits follow [`linear-agent-writes`](../linear-agent-writes/SKILL.md) (propose, then write).## Human GatesThese writes require explicit human confirmation by row ID:-- Linear state β status, priority, assignee, labels, cancellation, or customer-need changes. Comments and description edits are **not** gated: they are two of the permitted agent write shapes, so leave them to [`linear-agent-writes`](../linear-agent-writes/SKILL.md), which owns the shapes and the labels.+- Linear state β status, priority, assignee, labels, cancellation, or customer-need changes. Comments and description edits are permitted agent shapes but still need a propose-then-write yes β leave them to [`linear-agent-writes`](../linear-agent-writes/SKILL.md).- Pylon replies, internal notes, status changes, assignment, tags, snoozes, closes, or external-issue links. This is customer-facing, and that gate stays.- GitHub approvals, comments, requested changes, reviewer changes, closes, merges, labels, or branch actions.diff --git a/.agents/skills/incident-alert-tickets/SKILL.md b/.agents/skills/incident-alert-tickets/SKILL.mdindex 25fa8fa113..4a58fc2159 100644--- a/.agents/skills/incident-alert-tickets/SKILL.md+++ b/.agents/skills/incident-alert-tickets/SKILL.md@@ -95,22 +95,25 @@ the proposed ticket so the human can judge the overlap.## Write-Back-Appending a cause section to a ticket that already exists is a description edit,-which agents do autonomously. A monitor with no ticket needs a parentless one,-which is the single write that asks first β see-[`linear-agent-writes`](../linear-agent-writes/SKILL.md) for the policy this-follows, and read it before your first write.--- **Append: do it.** Insert the new `---`-separated dated block after the- existing cause sections, above the `Your cause is not listed?` trailer; leave- everything else untouched. Mark the block as agent-written in its own text and- label the ticket `AI edited`. Never reflow or rewrite the human-written prose- around it.+Appending a cause section to a ticket that already exists is a description edit;+creating a monitor with no ticket is a parentless create. Both need a yes β+see [`linear-agent-writes`](../linear-agent-writes/SKILL.md) and read it before+your first write.++- **Append: show it, then do it.** Prepare the new `---`-separated dated block+ (insert after the existing cause sections, above the `Your cause is not+ listed?` trailer; leave everything else untouched). Mark the block as+ agent-written in its own text. Put it in the go-ahead table; once approved,+ append it and label the ticket `AI edited`. Never reflow or rewrite the+ human-written prose around it.- **Create: show it, then file it.** Prepare the issue β title`[ENV] <Monitor title>`, the `incident-alert` label, description = alert header,the first dated cause section, and the `Your cause is not listed?` trailer βshow it for a go-ahead, and once you have one, create it yourself and label it- `AI created`. One go-ahead covers the whole run's proposed tickets.+ `AI created`.++**One go-ahead covers the whole run** β appends and creates together. Asking+per row is worse than the pasting this replaced.Report what you did either way:diff --git a/.agents/skills/infra-scaling/SKILL.md b/.agents/skills/infra-scaling/SKILL.mdindex 92db0d0eea..a8540b46ad 100644--- a/.agents/skills/infra-scaling/SKILL.md+++ b/.agents/skills/infra-scaling/SKILL.md@@ -211,7 +211,7 @@ Run a full plan only when credentials and workspace setup are available or the u- Trigger this when the recommendation table contains at least one concrete scaling change, or when Terraform scaling settings were edited. Do not create a ticket for an all-`No change` review unless the user explicitly asks.- Ensure there is a GitHub PR for the scaling change. If no PR exists yet, create one. Include the recommendation summary, validation, and rollout risks in the PR body.-- Only three write shapes are permitted and each must be labelled and marked as agent-written. [`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority; read it before your first write. For this skill: **adding evidence to a ticket that already exists is yours to do** (label it `AI commented`, or `AI edited` if you put the evidence in the description); **a new ticket has no parent, so it is the one write that asks first** β show the title and body, take one go-ahead, then create it and label it `AI created`.+- Only three write shapes are permitted and each must be labelled and marked as agent-written. [`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority; read it before your first write. For this skill: **evidence on an existing ticket and a new parentless ticket both need a yes** β show the comment / description block or the new title and body in the table, take one go-ahead for the set (or named rows), then write and label (`AI commented`, `AI edited`, or `AI created`).- Report what you wrote and what still needs a human:| ID | Finding | Evidence | Impact / Scope | Existing Ticket Match | Action | Confidence |diff --git a/.agents/skills/langfuse-codebase-navigator/SKILL.md b/.agents/skills/langfuse-codebase-navigator/SKILL.mdindex 0845d94917..1c5d06d84f 100644--- a/.agents/skills/langfuse-codebase-navigator/SKILL.md+++ b/.agents/skills/langfuse-codebase-navigator/SKILL.md@@ -26,11 +26,10 @@ Use this as the first stop for Langfuse org navigation. Your job is to choose th- Product implementation in `langfuse/langfuse`: choose the matching repo-local skill under `.agents/skills`, such as `backend-dev-guidelines`, `frontend-browser-review`, `clickhouse-best-practices`, `add-model-price`, `turborepo`, `pnpm-upgrade-package`, `code-review`, or production-debug skills as applicable.- Cursor Cloud or Cursor desktop agents implementing a Linear issue, opening a PR, applying the `cursor` GitHub label, asking a human to test, or handling Claude, Greptile, or Codex review comments: use `cursor-agents-workflow`.-- A change too large for one reviewable PR, splitting a long-lived branch into PRs, or propagating and retargeting a stack: use `pr-stack-workflow`.-- Someone new, or you do not know whether you are talking to an outside contributor or a maintainer: use `langfuse-onboarding`.+- A change too large for one reviewable PR: split it into small stacked PRs rather than one wide PR.- "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`.-- 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.+- Reconstructing why a surface is the way it is before changing it, or proposing the reasoning behind finished work onto its Linear ticket: use `linear-context-handover`.+- Before any agent write to Linear β a comment, a description edit, a ticket: use `linear-agent-writes`, the write policy (propose updates; mark every write). Ordinary writes stay a title and a few sentences. Subtickets under an existing parent are free.- 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/langfuse-onboarding/SKILL.md b/.agents/skills/langfuse-onboarding/SKILL.mddeleted file mode 100644index 0f31089185..0000000000--- a/.agents/skills/langfuse-onboarding/SKILL.md+++ /dev/null@@ -1,261 +0,0 @@-----name: langfuse-onboarding-description: |- Configure an agent for whoever is using it β outside contributor or Langfuse- maintainer, which areas they work on, and whether Linear answers. On Cursor- Cloud, identify the run owner (not Cloud gh permissions) and treat missing- Linear as a LINEAR_API_KEY secret to set. Use on "onboard me", "I'm new here",- "what do I need to set up", "am I set up correctly", "why can't you see my- tickets", "what should I do today" when me.md is missing, whenever you- need someone's role and no identity file exists yet, and when a- workspace-scoped harness (OpenCode) prompts on ~/.config or other- user-dir paths.------# Onboarding at Langfuse--Two jobs, and they are separable β most of the time you only want the first.--1. **Configuration** (steps 1, 2 and 4): work out who is using this agent, what- they work on, and what they are connected to. Seconds, not a session. Someone- who has been here a year needs this and nothing else β do not walk a- colleague through a new-joiner path to find out their name.-2. **Onboarding** (steps 3 and 5): the walkthrough, for people who are actually- new.--Everything an agent needs in order to behave differently for a contributor than-for a maintainer comes from the first, so do that before anything else.--## Step 1 β name them, then prove Linear; do not ask what you can find out--Normal path: `scripts/agents/configure-langfuse-identity.sh` already ran from-repo postinstall or Cursor Cloud start and wrote a workspace identity file-at `.langfuse/me.md` (gitignored) from the Linear viewer. Read **that**-file β it is inside the project. Do **not** Read, Write, or bash-`~/.config/langfuse/me.md` or any other path under `$HOME`. Workspace-scoped-harnesses (OpenCode and similar) prompt on every access outside the project;-identity is optional there, so skip it rather than ask the human to approve-the user dir. If a tool call to a home path is denied, treat identity as-absent and continue β do not retry.--Run the local probe first, then stop at the first path that names a person:--```bash-bash .agents/skills/langfuse-onboarding/scripts/whoami.sh-```--The probe does not stat `$HOME` unless `LANGFUSE_ALLOW_HOME_IDENTITY=1`.-It reports whether a workspace (or opted-in) `me.md` exists, whether a-Linear token is in the environment (boolean only β it never prints the-secret), a `linear_viewer` line if that token works, and whether-`gh api user` works. On Cursor Cloud, a working `linear_viewer` is tracker-identity even when Linear MCP is `needsAuth`.--**Who, in this order:**--1. **Workspace `me.md`** β `.langfuse/me.md` in this checkout, as reported- by `whoami.sh`. Already recorded. Skip to Linear.-2. **Cursor Cloud run owner.** If `cursor-cloud` tools exist, call `run-info`.- Use `owningUserName` and `owningUserEmail`. Join the name to the roster- (`components-mdx/team-members.mdx` in a docs checkout, or- `gh api repos/langfuse/langfuse-docs/contents/components-mdx/team-members.mdx`).- **Maintainer needs Langfuse-team evidence**: a roster row, or membership of- the `LF` team on the Linear read below. Take the GitHub handle from the- roster. An `@clickhouse.com` / `@langfuse.com` address alone is *not* that- evidence β ClickHouse is far larger than this team, and a colleague from- another team owns none of the Langfuse tracker. Say the address named them,- that you found no Langfuse-team row, and ask once rather than assuming.-3. **`gh api user` succeeded** (desktop and similar). Then- `gh api repos/langfuse/langfuse --jq '.permissions | {push, maintain, admin}'`.- **`push: true`** β maintainer. **`push: false`** β contributor until they- say otherwise.-4. If none of the above named them, **ask once**.--**Do not treat Cursor Cloud `gh` as the person.** That token is a read-only-integration: `gh api user` is 403 and `.permissions.push` is false even for-maintainers. **Do not infer identity from `git config user.email`** β on Cloud-it is `[email protected]`, and elsewhere it is often a personal address.-Langfuse is part of ClickHouse; `@clickhouse.com` and `@langfuse.com` are both-in daily use.--**Linear, in the same step** β a maintainer with no tracker is a *setup gap*,-not a contributor. Prove access with a real read, not a status indicator:--1. Linear MCP tools exist and the namespace is not `needsAuth` β query `viewer`- (or list issues).-2. Else if `whoami.sh` reported a Linear token β GraphQL- `{ viewer { name email } teams { nodes { name key } } }` with that env var- (never echo it), or `linear-context-handover/scripts/lf-context.sh`. Record- the viewer as tracker identity, and treat the `LF` team in that response as- the Langfuse-team evidence step 1 asked for. Cloud often has the secret while- Linear MCP still shows `needsAuth` β the token is the access; do not wait on- OAuth.-3. Else: no Linear. On Cursor Cloud, **do not call `mcp_auth`** β it only works- in the desktop IDE. Tell them, in one line, to create a personal Linear API- key (Linear β Settings β Account β Security) and add it as secret- **`LINEAR_API_KEY`** at https://cursor.com/dashboard/cloud-agents, then start- a **new** Cloud run. This run cannot see a secret added later. On desktop,- authorizing the Linear MCP is enough; `LINEAR_API_KEY` is the headless- fallback.--Say what you found and let them correct it. Never announce a role silently.--## Step 2 β record it, so this happens once--Write `.langfuse/me.md` in this checkout (gitignored). That path stays inside-the project, so OpenCode and other workspace-scoped harnesses do not prompt.-Do not write `~/.config/langfuse/me.md` from an agent session β postinstall-and Cloud start still recover a machine-level copy when the harness allows-it. If a home-dir write is denied, ignore it and keep the workspace file.--```markdown-# Me, at Langfuse--- **Name:** <name>-- **Role:** maintainer | contributor-- **GitHub:** <login> # roster handle on Cloud; `gh api user` on desktop-- **Tracker identity:** <name / email as Linear knows it, or "none">-- **Focus:** <the areas they own or are learning β their own words>-- **Checkouts:** <path to langfuse> Β· <path to langfuse-docs> Β· <others>-- **Connectors verified:** <the ones that answered a real read> Β· **missing:** <the rest>-- *Recorded <date> by an agent. Edit freely; delete to be asked again.*-```--**Never commit this file, and never put a secret in it.** `.langfuse/` is-gitignored. It is notes, not config: no tokens, no keys. A repo `.env` is-the wrong home β those are app configuration and one careless `git add`-publishes them. Delete the workspace `me.md` to be asked again β recovery-re-queries Linear and does not copy `~/.config/langfuse/me.md` back over it.--**Ask for Focus β once β rather than deriving it.** What someone owns on paper-and what they are responsible for this quarter are different things, and only-they know the second. One question, their phrasing, written down so nobody asks-again. If they would rather not answer, record that and move on; a missing Focus-line is not a blocker.--Do **not** record what they own project by project β that is derivable and it-goes stale within a week. `linear-work-rhythm` reads it live from the tracker-instead.--## Step 3a β the contributor path--Read `CONTRIBUTING.md` and walk it: setup, the four gating checks before opening-a PR, and `## Maintainers` for what is not theirs to do. `.agents/AGENTS.md` β-*Verification* is the honest bar, including which checks pass without running.--Stop there. Do not describe the issue tracker, the label policy, the weekly-rhythm, or the internal handbook β a contributor cannot open any of it, and-offering it reads as a door that is locked.--## Step 3b β the maintainer path, for people who are new--**Skip this for an established colleague.** If they have commits in this repo-going back months, they know how the team ships; reading it back to them wastes-their time and yours. Configuration plus step 4 is the whole job. Offer the-walkthrough rather than starting it: *"want me to go through the handbook pages,-or just fix the two missing connectors?"*---**The handbook owns the content; you drive it.** It is `content/handbook/` in-`langfuse/langfuse-docs`, published at `langfuse.com/handbook`. Read the pages,-work through them with the person, and answer from what they actually say today β-do not paraphrase them here, because this file would then be a second, stale copy-of a document that changes without it.--**Read it from `origin/main`, not the working tree.** A docs checkout is usually-parked on some branch from the last thing that person shipped, and a working-tree-read then quotes a handbook from weeks ago without saying so. This is not-hypothetical: the first run of this skill read a checkout **576 commits behind**.-Fetch, then read the blob β it needs no checkout switch and cannot disturb work-in progress:--```bash-cd <docs checkout> && git fetch -q origin main-git show origin/main:content/handbook/product-engineering/how-we-work/onboarding.mdx-```--Start with:--| Page | What it answers |-| --- | --- |-| `content/handbook/product-engineering/how-we-work/onboarding.mdx` | Day 1, Week 1, months 1β3, month 6 β the timeline and its outcomes |-| `content/handbook/product-engineering/how-we-work/how-we-ship.mdx` | Prioritisation, specification, releases, issue states |-| `content/handbook/tools-and-processes/using-linear.mdx` | How the tracker is used, and the working agreement |-| `content/handbook/how-we-work/productivity-and-ai.mdx` | Agent tooling, and keeping `AGENTS.md` current |-| `content/handbook/product-engineering/how-we-work/code-review.mdx` | What review is for here |--Then, in the repos:--- `.agents/AGENTS.md` β always loaded, and the two things it names that nothing- else does: what a green check really proves, and the context handover.-- `linear-agent-writes` β read before the first agentic tracker write.-- `pr-stack-workflow` β before the first change too large for one PR.--**If a handbook page contradicts a skill or an `AGENTS.md`, say so.** That is a-finding worth reporting, not something to smooth over: one of the two is wrong,-and the person reading both will trust the wrong one.--## Step 4 β the connectors, and what breaks without each--Skills fail differently from code: an unauthorized connector does not error, the-agent simply cannot answer, and neither of you finds out why. So walk this list-and say which ones are missing rather than discovering it mid-task.--| Connect | Needed by |-| --- | --- |-| **Linear** | 17 skills β the tracker practice in all of it. MCP, or `LINEAR_API_KEY` on headless/Cloud (step 1). |-| **Datadog** | `debug-issue-with-datadog`, `datadog-query-recipes`, `incident-alert-tickets`, `weekly-production-review`, `infra-scaling`, `linear-bug-triage` |-| **AWS** (SSO) | preview seeding and `kubectl` in `langfuse-previews`, plus `infra-scaling`, `security-review` |-| **incident.io** | `incident-alert-tickets`, `weekly-production-review`, `debug-issue-with-datadog` |-| **PostHog** | `posthog-instrumentation`, and the usage half of `debug-issue-with-datadog` |-| **Sentry** | `sentry-instrumentation` |-| **Pylon** | `housekeeping` |-| **Hex** | `analyze-cloud-costs` |-| **Slack** | `weekly-production-review`, and reading any thread someone links you |--**Datadog is the one that fails quietly**, and it takes four skills with it.-Slack has no hosted MCP server, so it arrives through whichever connector your-tool provides rather than through this repo's config β check it the same way,-because a linked thread you cannot open is a dead end mid-conversation.-Prove each connector with a real read rather than trusting a status indicator β-a remote server can report itself connected before it holds a token.--Two prerequisites on the same checklist that are not connectors: the-`langfuse-docs` checkout below, which four skills read the handbook from, and a-working local Docker, without which the seeder cannot make test data.--## Step 5 β the checkouts, especially the docs one--A maintainer needs the app repo *and* the docs repo. The docs repo is the one-people skip, and then documentation quietly stops happening because the-alternative is a clone in the middle of a task.--```bash-git rev-parse --show-toplevel # where am I-ls -d ../langfuse-docs 2>/dev/null # is the docs repo a sibling-```--Do not `ls` under `$HOME` (`~/code/langfuse-docs` and similar). If the-sibling path is missing, say so plainly and give the clone command β do-not search the user dir, and do not carry on and hope:--```bash-git clone [email protected]:langfuse/langfuse-docs.git-```--It carries the handbook, the docs, the changelog, and the team roster-(`components-mdx/team-members.mdx` β names, roles, GitHub handles). Without it-this skill cannot read step 3b, nobody can tell you who a commit author is, and-no shipped change gets a docs page or a changelog entry without a separate-detour.--Record the paths you found in `me.md` so the next session does not search again.--## What this skill does not do--It does not decide what to work on β that is-[`linear-work-rhythm`](../linear-work-rhythm/SKILL.md), which reads `me.md` and-answers from the tracker. If someone asks "what should I do today" and no-identity file exists, run step 1 and 2 first. If Linear still does not answer,-stop and ask them to set `LINEAR_API_KEY` (Cloud) or authorize the Linear MCP-(desktop) β do not invent a day's work.diff --git a/.agents/skills/langfuse-onboarding/agents/openai.yaml b/.agents/skills/langfuse-onboarding/agents/openai.yamldeleted file mode 100644index 9df7bb01fa..0000000000--- a/.agents/skills/langfuse-onboarding/agents/openai.yaml+++ /dev/null@@ -1,4 +0,0 @@-interface:- display_name: "Langfuse Onboarding"- short_description: "Name you, then check Linear, without leaving the project"- default_prompt: "Use $langfuse-onboarding to work out who I am from the workspace identity file or Cloud run owner (not Cloud gh permissions), whether Linear answers, and if not tell me to set LINEAR_API_KEY. Do not read ~/.config."diff --git a/.agents/skills/langfuse-onboarding/scripts/whoami.sh b/.agents/skills/langfuse-onboarding/scripts/whoami.shdeleted file mode 100755index 49af59890c..0000000000--- a/.agents/skills/langfuse-onboarding/scripts/whoami.sh+++ /dev/null@@ -1,70 +0,0 @@-#!/usr/bin/env bash-# Probe identity signals for langfuse-onboarding. Never prints secret values.-#-# Do not stat $HOME/.config unless the caller opted in. Workspace-scoped-# harnesses (OpenCode and similar) prompt on any path outside the project,-# and identity is optional there β skip it rather than ask the human.-set -euo pipefail--repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"-workspace_me="${LANGFUSE_WORKSPACE_IDENTITY_DIR:-$repo_root/.langfuse}/me.md"--me_reported=0-report_me() {- echo "me.md: present (${1})"- me_reported=1-}--if [[ -n "${LANGFUSE_CONFIG_DIR:-}" && -f "${LANGFUSE_CONFIG_DIR}/me.md" ]]; then- report_me "${LANGFUSE_CONFIG_DIR}/me.md"-elif [[ -f "${workspace_me}" ]]; then- report_me "${workspace_me}"-elif [[ "${LANGFUSE_ALLOW_HOME_IDENTITY:-}" == "1" ]]; then- home_me="${HOME}/.config/langfuse/me.md"- if [[ -f "${home_me}" ]]; then- report_me "${home_me}"- fi-fi--if [[ "${me_reported}" -eq 0 ]]; then- echo "me.md: absent"-fi--# Every signal below is independent, so no probe may abort the others: a-# blocked Linear route must not hide the GitHub lines, and vice versa.-set +e-bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" --probe-linear_probe_status=$?-set -e-if [[ "${linear_probe_status}" -ne 0 ]]; then- echo "linear_viewer: unavailable (probe exited ${linear_probe_status})"-fi--set +e-gh_login="$(gh api user --jq .login 2>/dev/null)"-gh_user_status=$?-gh_name=""-gh_email=""-if [[ "${gh_user_status}" -eq 0 && -n "${gh_login}" ]]; then- gh_name="$(gh api user --jq '.name // ""' 2>/dev/null)"- gh_email="$(gh api user --jq '.email // ""' 2>/dev/null)"-fi-set -e-if [[ "${gh_user_status}" -eq 0 && -n "${gh_login}" ]]; then- echo "gh_user: ${gh_login} ${gh_name} ${gh_email}"- set +e- gh_perm_json="$(gh api repos/langfuse/langfuse --jq .permissions 2>/dev/null)"- gh_perm_status=$?- set -e- if [[ "${gh_perm_status}" -eq 0 && -n "${gh_perm_json}" ]]; then- python3 -c '-import json, sys-p = json.loads(sys.argv[1])-print("gh_permissions: push=%s maintain=%s admin=%s" % (p.get("push"), p.get("maintain"), p.get("admin")))-' "${gh_perm_json}" || echo "gh_permissions: unavailable"- else- echo "gh_permissions: unavailable"- fi-else- echo "gh_user: unavailable (Cloud integration tokens 403 here; do not treat as contributor)"-fidiff --git a/.agents/skills/linear-agent-writes/SKILL.md b/.agents/skills/linear-agent-writes/SKILL.mdindex 76fb535b8e..f41d28d7bd 100644--- a/.agents/skills/linear-agent-writes/SKILL.md+++ b/.agents/skills/linear-agent-writes/SKILL.md@@ -11,13 +11,17 @@ description: |# Linear agent writes-Agents write to Linear directly. There is **one** gate, for **one** shape: a-ticket with no parent. Everything else β comments, description edits, subtickets-β you just do.+Agents may write to Linear, but **most writes are proposals first**. Show the+text you intend to land, get an explicit go-ahead, then write it yourself. Do+not silently mutate a ticket the human is mid-session with.-The guardrail is **marking plus a bounded set of shapes**: three permitted write-shapes, each stamped with a label, each marked as agent-written in the text.-Everything outside those three shapes still belongs to a human.+The one exception is a **subticket of an existing ticket** β that shape is free,+because planning a stack is useless if every child needs its own yes.++The guardrail is **propose-then-write, plus marking, plus a bounded set of+shapes**: three permitted write shapes, each stamped with a label, each marked+as agent-written in the text. Everything outside those three shapes still+belongs to a human.This file is the **single authority** for that policy. Other skills and repoinstructions point here; none of them restate the rules. If another document@@ -27,7 +31,9 @@ It is maintainer-facing: it binds anyone whose agent can reach the Langfuse issutracker, and it has nothing to ask of an outside contributor.*Provenance: the "Agentic Coding and Linear" RFC (LFE-15914), which replaced the-earlier "Linear is read-only for agents" posture.*+earlier "Linear is read-only for agents" posture; tightened after feedback that+auto-updating tickets mid-implementation was worse than proposing the update+(LFE-16058).*## Default length@@ -44,7 +50,7 @@ stack position, a research essay.Right: "Warn sunset event types on POST /ingestion request body. Fern stilllists trace-create as if it works; say those event types stop on Nov 16."-## Why the taboo went away+## Why the taboo went away β and why a gate came back for updatesLinear used to be human-only for agents, and every skill that touched it had tostop and present a review table first. That cost more than it protected: the@@ -52,16 +58,42 @@ expensive thinking in an agent session β the decisions, the reversals, the traβ evaporated when the session ended, because the one place it could have beenwritten down was closed.-Breaking the taboo is not removing the boundary. Marking is what replaces the-gate: a human must always be able to tell, at a glance, which text on a ticket is-theirs and which an agent wrote.+Breaking the taboo is not removing every boundary. Marking is what stops+misattribution: a human must always be able to tell, at a glance, which text on+a ticket is theirs and which an agent wrote.++**Auto-writing comments and description edits** turned out to be a different+failure mode: the agent lands context the human did not choose, notifies+watchers, and can scramble the description another session is treating as+memory. So updates of an existing ticket are **proposals** β show the block,+get a yes, then write. The content still survives the session; the human+hand-selects what lands.++An explicit ask such as "write the handover", "comment on the ticket", or+"update Linear" **is** the go-ahead for that write. Do not ask twice.++## End of session: ask once whether to preserve on tickets++When a session produced decisions, reversals, or other reasoning that should+survive the chat β and you have not already been told to update Linear β+**close with a clear yes/no ask**, not a silent write and not a buried aside.++Use wording close to:++> Should I update the ticket(s) with the results of this session so they are+> preserved?++If yes, show the exact comment or description block (or the batch table), then+write. If no or unanswered, leave the block in the reply. Skip the ask only when+nothing durable came out of the session, or when they already approved the write+for this wrap-up.## The three shapesThey compose. Stamp **every** shape you used, so the labels read as a log of whatagents did to the ticket.-### 1. Comment β only when a human must be told something now+### 1. Comment β propose, then post (only when a human must be told something now)Label `AI commented`. Mark the comment body itself as agent-written.@@ -69,11 +101,14 @@ A comment notifies every watcher. Use one when someone genuinely needs to seesomething today: a blocker, a question that stops the work, a finding thatchanges their plan.+**Show the comment body in your reply, get a yes, then post it.** Do not post+unsolicited comments.+**Durable post-context does not go here.** A wrap-up handover posted as a commentsprays every watcher's inbox for something nobody needs to read today, and inboxspam is how a good practice gets switched off. That goes in the description.-### 2. Edit a description β where post-context belongs+### 2. Edit a description β propose the block, then appendLabel `AI edited`. Add a **clearly separated agent block**; never rewrite,reflow, or "improve" the human's prose around it.@@ -82,6 +117,11 @@ This is the durable half of the practice. `AI edited` is the filter a futuresession uses to find prior agent reasoning, so the label is not decoration β itis the index.+**Show the exact block you would append (and which ticket), get a yes, then+append it.** Do not edit a description unsolicited β including wrap-up+handovers. If the human declines or does not answer, leave the block in your+reply so nothing is lost.+What belongs in such a block, how to append it without destroying thedescription, and why an attachment is not optional are[`linear-context-handover`](../linear-context-handover/SKILL.md).@@ -99,9 +139,10 @@ one filed straight into a project. Show the title and the short description youintend to file, get an explicit go-ahead, then **create it yourself**; do nothand 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 ticket-lands in somebody's triage queue. It is the one shape whose cost falls on people-who did not ask for it.+A parentless ticket lands in somebody's triage queue β cost on people who did+not ask for it. A comment or description edit lands on a ticket someone is+already working β cost on their focus and on cross-session context. Both need a+yes. A child of an existing ticket does not.## What still belongs to a human@@ -109,22 +150,21 @@ Assigning, moving state, closing, estimating, re-prioritising, deleting,projects, and creating new labels.Surface these as suggestions in your reply β do not do them, and do not ask for-permission to do them as a way of getting them done. (A top-level ticket is-different: asking is exactly the right move there, and then you file it.)+permission to do them as a way of getting them done. (A gated write is+different: asking is exactly the right move there, and then you perform the+write.)## Sweeps: ask once for the batch, not once per ticketA skill that reviews a whole queue β production errors, the alerts that fired-last week, a scaling review β comes back with many findings at once, and the ones-that have no ticket yet are parentless. So they need the yes.--**Ask for the set, in one go.** Present the findings as a table with the title-and body you would file for each, and get a single go-ahead β or a go-ahead for-named rows. Then file them yourself and report what you filed. Asking twelve-separate times is worse than the pasting it replaced.+last week, a scaling review β comes back with many findings at once. Parentless+filings need a yes; so do description appends and comments onto tickets that+already exist.-Evidence onto tickets that already exist is a comment or a description edit-(shapes 1 and 2), so it is never part of that ask β do it as you go.+**Ask for the set, in one go.** Present a table with the title and body (or the+append block / comment) you would land for each, and get a single go-ahead β or+a go-ahead for named rows. Then write those rows yourself and report what you+wrote. Asking twelve separate times is worse than the pasting it replaced.## You need a Linear connection@@ -135,19 +175,15 @@ server, and `scripts/agents/sync-agent-shims.mjs` projects it into each tool'sconfig on `pnpm install`. Those generated files are gitignored build artifacts βnever hand-edit them.-What is left per developer is **authorizing** it. On desktop, the first-connection prompts for OAuth. On a headless surface (Cursor Cloud) there is-nobody to approve that prompt, and `mcp_auth` is not available β do not try it.--**Cursor Cloud:** prove Linear with a real read. If the MCP namespace is-`needsAuth` or empty, look for `LINEAR_API_KEY` (aliases `LINEAR_TOKEN`,-`LINEAR_API_TOKEN`) and query GraphQL `{ viewer { name email } }` or run-`linear-context-handover/scripts/lf-context.sh`. Never print the secret. If-the token is unset, tell them to add **`LINEAR_API_KEY`** at-https://cursor.com/dashboard/cloud-agents (personal key from Linear β Settings-β Account β Security) and start a **new** Cloud run. Do not commit that header-or key; an unset `${LINEAR_API_KEY}` passed through an MCP `headers` block-fails with no fallback, which is why it is not in `.agents/config.json`.+What is left per developer is **authorizing** it, which the first connection+prompts for. On a headless surface there is nobody to approve that prompt, and a+remote MCP can report itself connected before any token exists β so prove access+with a real read rather than trusting an indicator, and use a token in an+`Authorization` header there instead of the interactive flow. Do not commit that+header: an unset variable is passed through literally and fails with no fallback.+**Never print or echo the secret value** (`LINEAR_API_KEY` / `LINEAR_TOKEN` /+`LINEAR_API_TOKEN`) while debugging or reporting the read β say only whether+access worked.## When there is no Linear connection: say so, loudly@@ -158,8 +194,6 @@ is how a practice quietly dies.Say, in your reply, in plain language:- that this environment has no Linear access;-- on Cursor Cloud, that they should set secret **`LINEAR_API_KEY`** and start a- new run (interactive Linear OAuth does not work here);- which step you could not complete (history reconstruction, the handover, thesubtickets);- and then **the content itself**, ready to paste β the handover block, the@@ -185,3 +219,11 @@ The Linear MCP writes as the **authenticated human**, not as a bot. An unmarkedagent block reads as that person's own words to everyone who sees it. The labelis for filtering; the in-text marking is what stops the misattribution. Do both,every time.++## Where preferences live++**Org defaults** for agent behaviour β including this propose-then-write gate β+live in `.agents/skills/**` (and the maintainer handbook that points at them).+Edit the skill when the team wants a different default. Ask the person for+one-off personal preferences; do not maintain a local identity or preferences+file for them.diff --git a/.agents/skills/linear-bug-triage/SKILL.md b/.agents/skills/linear-bug-triage/SKILL.mdindex e5c94240f1..7ea9627689 100644--- a/.agents/skills/linear-bug-triage/SKILL.md+++ b/.agents/skills/linear-bug-triage/SKILL.md@@ -22,13 +22,14 @@ they differ.For this skill it resolves to:-- **An evidence comment on an issue that already exists: just do it.** Label that- issue `AI commented` and say in the comment body that an agent wrote it. This- is the common case and needs nobody's permission.+- **An evidence comment on an issue that already exists: propose, then post.**+ Show the comment body in the findings table, get a yes (one go-ahead can cover+ the whole set), then post it and label that issue `AI commented`. Mark the+ comment body as agent-written.- **A new top-level issue: ask once, then file it.** A bug cluster surfaced by a- review has no parent, and a parentless ticket is the one shape that needs a- go-ahead. Take one go-ahead for the whole set, or for named rows β never one- question per candidate.+ review has no parent, and a parentless ticket needs a go-ahead. Take one+ go-ahead for the whole set, or for named rows β never one question per+ candidate.So present the findings table either way: it is what the go-ahead is givenagainst, and it is the report afterwards. One row per candidate:@@ -40,11 +41,12 @@ against, and it is the report afterwards. One row per candidate:- Baseline measurement.- Delta / regression summary.- Key evidence links β the ones *Required Evidence* below asks for.-- Action: `commented <issue key>` for what you already did, `filed <issue key>`- once a row is approved and created, or `awaiting your go-ahead`.+- Action: `awaiting your go-ahead` with the exact comment or ticket body,+ `commented <issue key>` once approved and posted, or `filed <issue key>`+ once a row is approved and created.Never present an `awaiting your go-ahead` row without the exact title and body-you intend to file underneath it β that text is what is being approved.+you intend to land underneath it β that text is what is being approved.Deduplicate first, so comments land on the right issue.If Linear is unreachable in this environment, say so plainly and return every row@@ -75,15 +77,16 @@ Always, before writing anything:service, environment, monitor name, and observability link keywords.2. Search recently closed or canceled issues if the error is recurring or thewording is distinctive.-3. If a related issue exists, add a concise evidence comment to it and label it- `AI commented`.+3. If a related issue exists, put a concise evidence comment in the findings+ table as `awaiting your go-ahead`. Post it and label `AI commented` only+ after the go-ahead (one yes can cover the whole set).4. If no related issue exists, prepare the issue in the format below and put itin the findings table as `awaiting your go-ahead`. File it once the go-aheadcomes, and update the row to `filed <issue key>`.## Existing Issue Comments-For related existing issues, add only:+For related existing issues, after a yes, add only:- Recent window and baseline window.- Measured delta or `No measurements found` for unavailable signals.diff --git a/.agents/skills/linear-context-handover/SKILL.md b/.agents/skills/linear-context-handover/SKILL.mdindex ccc0ca61eb..61ac88b643 100644--- a/.agents/skills/linear-context-handover/SKILL.md+++ b/.agents/skills/linear-context-handover/SKILL.md@@ -19,19 +19,18 @@ Two halves, and the second one is the one people skip:1. **Before you touch a feature, reconstruct its history.** Most "new" work on anexisting surface has a paper trail that answers half the design questions.-2. **When you wrap up, write the handover into the ticket's description.**+2. **When you wrap up, propose the handover for the ticket's description.**-What an agent may write to Linear, which label stamps it, and what stays-human-only are not in this file:+What an agent may write to Linear, which label stamps it, the propose-then-write+gate, and what stays human-only are not in this file:[`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority. Readit before your first write. This file is the *craft* β where post-context goes,what 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 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.+How to slice a big change into PRs is ordinary judgment: prefer small reviewable+PRs, and create subtickets under an existing parent freely when that helps.+Reconstructing history is not by itself a reason to file a stack of subtickets.## Before you touch a feature: reconstruct its history@@ -69,10 +68,21 @@ By hand, the same chain is:Read all of it before proposing a direction.-## When you wrap up: write the handover+## When you wrap up: ask, then propose the handover-Into the **description** of the ticket the work belongs to, as a clearly-separated agent block. Label the ticket `AI edited`.+Do not end a productive session by silently writing to Linear, and do not omit+the preserve step. Close with a clear ask β wording close to:++> Should I update the ticket(s) with the results of this session so they are+> preserved?++Then draft a clearly separated agent block for the **description** of the ticket+the work belongs to. Show that block in your reply (name the ticket, say it+would be labelled `AI edited`), and **append it only after an explicit yes** β+see [`linear-agent-writes`](../linear-agent-writes/SKILL.md). An ask such as+"write the handover" or "update the ticket" is that yes (no second question). If+they decline or do not answer, leave the block in the reply so the reasoning+still survives the session.**Scale it.** One substantial handover on the project or parent ticket, shortpointers on the leaves. The same essay repeated on eight tickets is noise, notdiff --git a/.agents/skills/linear-context-handover/agents/openai.yaml b/.agents/skills/linear-context-handover/agents/openai.yamlindex c575ff1ffc..1ec35dafb0 100644--- a/.agents/skills/linear-context-handover/agents/openai.yaml+++ b/.agents/skills/linear-context-handover/agents/openai.yaml@@ -1,4 +1,4 @@interface:display_name: "Linear Context Handover"short_description: "Reconstruct a feature's history, and hand your reasoning over"- default_prompt: "Use $linear-context-handover to reconstruct a feature's history before changing it, and to write the handover onto its work item before asking for review."+ default_prompt: "Use $linear-context-handover to reconstruct a feature's history before changing it, and to propose the handover for its work item before asking for review."diff --git a/.agents/skills/linear-context-handover/scripts/lf-context.sh b/.agents/skills/linear-context-handover/scripts/lf-context.shindex 144c541f73..dfec71f90e 100755--- a/.agents/skills/linear-context-handover/scripts/lf-context.sh+++ b/.agents/skills/linear-context-handover/scripts/lf-context.sh@@ -385,6 +385,7 @@ elsenote "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 " prefer small reviewable PRs; subtickets under a parent are free."fiprintf '\n'diff --git a/.agents/skills/linear-work-rhythm/SKILL.md b/.agents/skills/linear-work-rhythm/SKILL.mdindex ab5d5f3c1e..c5a33896ef 100644--- a/.agents/skills/linear-work-rhythm/SKILL.md+++ b/.agents/skills/linear-work-rhythm/SKILL.md@@ -18,13 +18,10 @@ description: |change daily, and a plausible answer assembled from memory is worse than noanswer because nobody can tell it is stale.-Who the person is comes from `.langfuse/me.md` in this checkout, or from-`langfuse-onboarding` `whoami.sh`. Do not Read `~/.config/langfuse/me.md`.-If the workspace file is not there, run-[`langfuse-onboarding`](../langfuse-onboarding/SKILL.md) step 1 β on Cursor-Cloud that is `run-info` plus the roster, **not** Cloud `gh` permissions, and-not a "what's your name" interview. Do not guess, and do not answer this-question for an outside contributor, who owns none of it.+For whose plate to query: use Linear's authenticated viewer+(`member: "me"`), or ask once. Do not invent or maintain a personal identity+file. Do not answer this question for an outside contributor, who owns none+of it.If Linear MCP is `needsAuth` and no `LINEAR_API_KEY` (or `LINEAR_TOKEN` /`LINEAR_API_TOKEN`) is set, **stop**. Tell them to add `LINEAR_API_KEY` as a@@ -64,8 +61,7 @@ list_projects(member: "me", state: "started",```A local list of someone's projects is stale within a week β this repo has been-burned by exactly that. `me.md` holds only the durable half: name, role, and the-focus they described in their own words.+burned by exactly that. Re-query the tracker; do not cache ownership locally.## What ranking actually means here@@ -262,8 +258,8 @@ it is asking for, and propose the next step β do not ask which skill applies.not, 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 aparentless ticket needs their yes.-- **A pull request** β the review conventions are `git-workflow`, and whether it- wants a stack is `pr-stack-workflow`.+- **A pull request** β the review conventions are `git-workflow`; if it is too+ large, prefer splitting into small stacked PRs.## Writing anything backdiff --git a/.agents/skills/pr-stack-workflow/SKILL.md b/.agents/skills/pr-stack-workflow/SKILL.mddeleted file mode 100644index 24b2c4992b..0000000000--- a/.agents/skills/pr-stack-workflow/SKILL.md+++ /dev/null@@ -1,151 +0,0 @@-----name: pr-stack-workflow-description: |- Split a large change into a chained stack of small, independently reviewable- pull requests, and verify each branch on its own. Use when a change is too- large for one PR, when splitting a long-lived branch into PRs, when deciding- whether work needs a planning stage at all, when landing or propagating a fix- through a stack, or when every check is green on a stack and the change is- still wrong.------# PR Stack Workflow--Use this for any change too large to review as one pull request: deciding-whether to stack at all, where to cut the slices, the mechanics that keep a-stack reviewable, and how to verify each branch instead of only the tip.--Branch names, commit and PR-title conventions, and how to handle bot review-threads live in `git-workflow`. Read that first; this skill does not restate it.--## Decide whether it needs a stack--A stack costs real time, because every landing forces a base move plus a merge-down the rest of the chain. Pay that only when one of these is true.--| Stack it | Ship it as one PR |-| --- | --- |-| You cannot describe the diff in one sentence without the word "and" | One symptom, one cause |-| It changes a default, or a shape users already have persisted, so it needs a migration decision | The behavior is new and nobody has state in it |-| Someone will ask "why" and the answer is evidence: numbers, screenshots, a competitor's UI | The bug report is the justification |-| It touches a shared component other surfaces consume | The blast radius is one screen |-| Verification is a click path, not an assertion | An existing test proves it |--Two consequences:--- If the fix is one commit, there is no plan to make. Do not manufacture slices.-- If you cannot yet write the acceptance check, you are researching, not- planning. Do the research, publish it, then plan.--Keep the stack short. Every landing costs another round of retarget-and-merge,-so length is a running cost you pay until the last PR is in.--## Slice by what a reviewer has to hold in their head--Not by file, not by directory, not by frontend versus backend. A slice is right-when a reviewer can state what it does, and check it, without loading any other-slice. Practical shapes, in the order they should land:--1. **The bugs first.** Anything true on `main` regardless of the wider change.- It is mergeable on day one, it carries no judgment, and landing it early- shrinks everything downstream.-2. **Defaults and data shape next.** A default-visible column, a one-time- migration, "stop rendering an empty string". Cheap diffs with expensive- consequences deserve their own review.-3. **One screen per slice.** A whole component replaced is one reviewer concern- even at 30 files.-4. **Housekeeping in a bag.** Several small independent removals nobody will- argue about.-5. **One question per slice.** "Which run do we compare against?" is one slice:- the query, the picker, the auto-selection, and the URL state together.-6. **The dense one, alone.** There is always one genuinely hard slice. Give it- nothing else to carry.-7. **New capabilities last but one.** A new layout or filter reads as a feature- only once the surface under it has settled.-8. **Instrumentation last.** It wires the seams the earlier slices create. Put- it first and you instrument code that is about to change.--This repo's own agent-setup work is a worked example: #16390, #16391 and #16392-shipped a project-structure path guard as three PRs, landed in that order β the-measured baseline first, then the rules the guard's messages cite, then the hook-that enforces them. The later two are based on the first's branch, not on `main`,-and #16392's body opens by naming the merge order.--## What each PR must say--State the position and the dependency in the body, so a reviewer knows what they-may ignore:--- `2/8, based on #16913. Base retargets to main when #16913 lands.`-- What is deliberately **not** in this slice, and which slice took it. This is- the line that stops an implementer helpfully widening the scope and breaking- the union check below.-- Any unmerged upstream change that would silently break this slice. A change- that makes two mechanisms read identical data makes them go *quiet* rather- than visibly wrong, and no test catches that.--Open the whole stack as reviewable, not drafts.--## Five rules that cost us--1. **A fix-up commit lands in the PR that contains the thing it fixes**, never as- a follow-up PR later in the stack. Otherwise the earlier PR ships a state you- already know is broken, and it is the one that merges first. When you slice an- existing branch, fold each fix-up back into its parent commit's slice.-2. **Propagate downward by merging parent into child. Never rebase or force-push- a stack that is under review.** Review bots hang their threads off commit- shas, so a force-push discards review you already paid for. These PRs are- squash-merged, so merge commits in a child cost nothing in `main`'s history.- (The one documented force-push in `CONTRIBUTING.md` is the CLA author-header- fix on a single PR β not a stack under review.)-3. **Every PR must stand alone.** Lint, typecheck and tests green on its own- branch, not only on the stack tip. A slice that compiles only with its- successor is not a slice: merge it into its neighbor.-4. **Every landing costs a retarget.** When the parent merges, its immediate- child becomes the new bottom: that one PR's base moves to `main`, `main` is- merged into it, and the merge is then propagated down the rest of the chain.- Every landing, until the stack is empty. Plan for that cost instead of- meeting it on merge day.-5. **A branch that has already merged `main` cannot be split by cherry-picking- its commits.** The reconciled state exists only in the merged tree: upstream- took some of your changes, replaced others, reverted a few. Slice the final- diff instead, then prove the union.--## Prove the union--After slicing a branch, `git diff <stack-tip> <original-branch>` must be empty,-or every remaining difference must be a deliberate, named decision.--Do not skip this because the slices look right. On an eight-PR split the union-delta came to three files and one added, three removed lines β and that delta was-the finding: the original branch had dropped three ESLint disable pragmas and was-carrying a latent lint failure toward `main`.--Keep the original branch untouched as the arbiter. When a slice's behavior is in-doubt, run both and compare. Never edit the arbiter to match a slice.--The commands for slicing a merged branch and proving the union are in-[`references/stack-commands.md`](references/stack-commands.md), together with the-git-to-PR walk for recovering why a surface is the way it is before you slice it.--## Verify per branch, not per stack--Run the verification bar from `.agents/AGENTS.md` on **each branch**, in a-worktree checked out on that branch, and publish the result as a table of branch-by check. That file owns the commands and the checks that pass without executing;-follow it there rather than from memory. Three failure modes belong to stacking-specifically:--- **Worktrees share one turbo cache.** Turbo says so on every run- (`using shared worktree cache`), which is exactly why a green lint on slice 4- can be a replay of slice 3's result. Force execution when you switch branches.-- **Slicing is what provokes the unused-export gate.** Split a feature and you- routinely produce an export whose only consumer lives in a later slice: dead- code on this branch, fine on the tip, and `knip` is a required check. The fix- is to move the export into the slice that uses it, not to widen an ignore list.-- **Somebody has to load the screen, per slice.** Green checks and bot reviews- have between them approved a branch that rendered a blank page, and each slice- has its own branch and its own preview β so a look at the tip proves nothing- about slice 3. Who looks is a judgement call `.agents/AGENTS.md` covers: drive- it yourself where the outcome is uncertain, hand over the preview URL where it- is not.diff --git a/.agents/skills/pr-stack-workflow/agents/openai.yaml b/.agents/skills/pr-stack-workflow/agents/openai.yamldeleted file mode 100644index 976330f786..0000000000--- a/.agents/skills/pr-stack-workflow/agents/openai.yaml+++ /dev/null@@ -1,4 +0,0 @@-interface:- display_name: "PR Stack Workflow"- short_description: "Slice a large change into chained, reviewable PRs"- default_prompt: "Use $pr-stack-workflow to decide whether a change needs a PR stack, where to cut the slices, how to propagate and retarget the stack, and how to verify each branch on its own."diff --git a/.agents/skills/pr-stack-workflow/references/stack-commands.md b/.agents/skills/pr-stack-workflow/references/stack-commands.mddeleted file mode 100644index 02dd6a32d9..0000000000--- a/.agents/skills/pr-stack-workflow/references/stack-commands.md+++ /dev/null@@ -1,130 +0,0 @@-# Stack commands--Command recipes for the mechanics described in `SKILL.md`. Read this when-building a stack out of an existing branch, propagating a change through one,-retargeting after a landing, or recovering why a surface is the way it is.--- [Recover the context before you slice](#recover-the-context-before-you-slice)-- [Cut a stack from a finished branch](#cut-a-stack-from-a-finished-branch)-- [Prove the union](#prove-the-union)-- [Propagate a change downward](#propagate-a-change-downward)-- [Retarget after a landing](#retarget-after-a-landing)-- [Verify one branch](#verify-one-branch)--## Recover the context before you slice--Most work on an existing surface has a paper trail that answers half the design-questions, and a reversal already litigated once does not need re-litigating.-Walk it from the file to the work item:--```bash-# 1. file -> commits-git log --follow --date=short --format='%h %ad %an %s' -n 10 -- <path>--# 2. commit -> PR: squash-merge subjects carry "(#N)"; otherwise ask GitHub-git log -1 --format=%s <sha>-gh api "repos/langfuse/langfuse/commits/<sha>/pulls" --jq '.[].number'--# 3. PR -> the branch that carries the work-item identifier-gh pr view <N> --json number,state,title,headRefName,baseRefName,url,body--# 4. an identifier -> its other PRs. GitHub search cannot query branch names,-# so match the identifier against recent head branches.-gh pr list --state all --limit 300 --json number,headRefName,title \- --jq '.[] | select(.headRefName | contains("<identifier>"))'-```--Step 3 is the load-bearing one: this repo keeps work-item identifiers out of-commit messages, PR titles and PR descriptions, so the head branch name is the-only link back to the tracker.--## Cut a stack from a finished branch--A branch that has already merged `main` cannot be split by cherry-picking its-commits β the reconciled state exists only in the merged tree. Slice the final-diff instead, cutting each branch from the previous one:--```bash-git fetch origin-REF=<the finished branch>--# what actually has to land, hunk by hunk-git diff origin/main...$REF --stat-git diff origin/main...$REF -- <paths for slice 1> > /tmp/slice-1.patch--git switch -c stack/01-bugs origin/main-git apply --3way /tmp/slice-1.patch-git add -A && git commit -m "fix: ..."--git switch -c stack/02-defaults stack/01-bugs-# ... repeat, each branch cut from its predecessor-```--Stage with `git add -A`, not `git commit -am`: a slice that adds a file arrives-untracked, and `-a` stages only tracked files, so the committed stack would be-missing it and the union proof below would fail.--Push each branch and open its PR against its parent's branch, not `main`.--## Prove the union--The stack tip must reproduce the finished branch:--```bash-git diff stack/08-instrumentation $REF --stat # expect empty-git diff stack/08-instrumentation $REF # inspect every remaining hunk-```--An empty diff means the split is faithful. A non-empty diff is either a dropped-change or a deliberate decision β name it in the PR body of the slice it belongs-to. Never edit `$REF` to make the diff go away; it is the arbiter.--## Propagate a change downward--A fix belongs in the PR that contains the thing it fixes. Once it is committed-there, merge that branch into each descendant in order. Do not rebase and do not-force-push a branch that has open review threads.--```bash-git switch stack/02-defaults && git merge stack/01-bugs && git push-git switch stack/03-screen && git merge stack/02-defaults && git push-# ... down the stack-```--## Retarget after a landing--When the bottom PR squash-merges, exactly one PR retargets β its immediate-child, which is now the bottom. That child's base moves to `main` and `main` has-to come back in:--```bash-gh pr edit <child PR> --base main-git switch <child branch>-git fetch origin && git merge origin/main && git push-```--The rest of the stack keeps its existing base and picks the landed work up by-the propagate recipe above β `git merge <parent branch>` into each descendant in-order. Retargeting more than one PR to `main` per landing would make every-descendant's diff carry its unmerged ancestors, which is the thing a stack-exists to avoid. This is the running cost of a stack; budget for one round of it-per landing.--## Verify one branch--Per branch, in a worktree checked out on that branch. `.agents/AGENTS.md` owns-the authoritative bar; this is the shape of the loop:--```bash-git worktree add ../langfuse-slice-4 stack/04-housekeeping-cd ../langfuse-slice-4 && pnpm install--pnpm --filter=shared run db:generate && pnpm --filter=shared run build-pnpm exec turbo run lint --force # read the Cached: line, not just Tasks:-pnpm run typecheck-pnpm --filter=web run test-client <file>-pnpm exec knip-```--Then load the surface the slice touches in a browser and look at it. Publish the-outcome as a table of branch by check, and say which checks you skipped.diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.mdindex 9fc8f13ebe..38ddb4aeec 100644--- a/.agents/skills/skill-creator/SKILL.md+++ b/.agents/skills/skill-creator/SKILL.md@@ -45,35 +45,40 @@ Match the level of specificity to the task's fragility and variability:Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).-### Mark Ticket Writes Instead of Gating Them+### Propose Ticket Updates; Mark Every Write-Skills that write to the issue tracker do not need a human review gate first.-The guardrail is **marking plus a bounded set of shapes**: three permitted write-shapes, each stamped with a label and marked as agent-written in the text.+Skills that write to the issue tracker follow+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) β the **single+authority**. Do not restate its rules in a new skill β point at it, so there is+one text to keep correct.-The full policy is [`linear-agent-writes`](../linear-agent-writes/SKILL.md),-which is the **single authority**.-Do not restate its rules in a new skill β point at it, so there is one text to-keep correct. In summary, a skill may:+In summary, a skill may use three shapes, each labelled and marked as+agent-written in the text:-1. **Comment**, only when a human must be told something now.-2. **Edit a description**, adding a clearly separated agent block that never- rewrites the human's prose. This is where durable context belongs.+1. **Comment** β only when a human must be told something now; show the body,+ get a yes, then post.+2. **Edit a description** β append a clearly separated agent block that never+ rewrites the human's prose; show the block, get a yes, then append. 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 ititself. 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-must surface it as a suggestion in its output.+An explicit ask ("write the handover", "comment on the ticket") **is** the+go-ahead. Assigning, moving state, closing, estimating, re-prioritising,+deleting, projects, and new labels still belong to a human β surface those as+suggestions only.++At wrap-up, skills that leave durable reasoning should close with a clear ask+(wording close to "Should I update the ticket(s) with the results of this+session so they are preserved?") rather than writing silently or skipping+preservation β detail lives in `linear-agent-writes`.Two consequences worth designing for:-- **A finding with no parent ticket is the one write that asks first.** Design a- skill that reviews a whole queue to present its filings as a table and take- **one** go-ahead for the set β or for named rows β then file them and report- what it filed. Asking per ticket, or handing back text for someone to paste, is- the cost this policy exists to remove.+- **Batch the ask.** A skill that reviews a whole queue should present filings+ and description appends as one table and take **one** go-ahead for the set β+ or for named rows β then write those rows and report what it wrote.- **State that the write happened.** Because the tracker's API authenticates asthe human who configured it, an unmarked agent write is indistinguishable fromsomething that person typed. Require the skill to mark authorship in the text,diff --git a/.agents/skills/weekly-production-review/SKILL.md b/.agents/skills/weekly-production-review/SKILL.mdindex a127282360..8a1f2ad703 100644--- a/.agents/skills/weekly-production-review/SKILL.md+++ b/.agents/skills/weekly-production-review/SKILL.md@@ -21,12 +21,11 @@ audit from the linked source rows.- The review itself changes nothing outside the tracker. Do not touch incident.iorecords, follow-ups, alerts, monitors, files, Slack messages, or productionsystems unless the user explicitly asks after reviewing the findings.-- Linear is the exception: evidence may be commented onto issues that already- exist, labelled and marked as agent-written. A new issue has no parent, so it- is the one write that asks first β show the set, take one go-ahead, then file- them. [`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority;- [`linear-bug-triage`](../linear-bug-triage/SKILL.md) applies it to measured- findings.+- Linear is the exception: evidence comments on existing issues and new+ parentless filings both need a propose-then-write yes β show the set, take+ one go-ahead, then write and label. [`linear-agent-writes`](../linear-agent-writes/SKILL.md)+ is the authority; [`linear-bug-triage`](../linear-bug-triage/SKILL.md) applies+ it to measured findings.- For chat-only reviews, avoid creating report artifacts or local analysisworkspaces unless a required tool workflow explicitly does so or the user asksfor a file. If incident.io analysis tooling requires a local playbook@@ -40,8 +39,8 @@ audit from the linked source rows.- Use [`datadog-query-recipes`](../datadog-query-recipes/SKILL.md) forproduction Datadog query shapes and environment/site routing.- Use [`linear-bug-triage`](../linear-bug-triage/SKILL.md) for the Linear- write-back: it comments measured evidence onto existing issues, and files new- ones once you approve the set.+ write-back: it proposes measured evidence comments and new filings, then+ writes once you approve the set.- Use [`incident-alert-tickets`](../incident-alert-tickets/SKILL.md) to checkeach alert cluster against the per-monitor knowledge base and record newlyroot-caused clusters there as a labelled description edit.diff --git a/.gitignore b/.gitignoreindex 9fd733eccc..b1ccc4ad40 100644--- a/.gitignore+++ b/.gitignore@@ -113,7 +113,7 @@ web/test-results/*# Local overrides for AGENTS.md**/AGENTS.override.md-# Agent identity (workspace copy; never commit)+# Local agent scratch (never commit).langfuse/# Superset configdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex f08ab5c0e5..7c73fac487 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -48,7 +48,7 @@ pnpm run test # see "Running Unit Tests" below for the setup this needs`lint` and `typecheck` are cached, so a pass can be a replay of an earlier run. Read turbo's `Cached:` line as well as its `Tasks:` line, and re-run with `pnpm exec turbo run lint --force` if you need to be sure it executed. For a user-visible change, also open the affected screen in a browser and check it β every pull request gets a full preview deployment at `pr-<N>.preview.langfuse.com`.-If a change is too large to review in one pull request, split it into a chained stack of small PRs rather than widening one. `.agents/skills/pr-stack-workflow/SKILL.md` describes where to cut the slices and how to land them.+If a change is too large to review in one pull request, split it into a chained stack of small PRs rather than widening one.A good first step is to search for open [issues](https://github.com/langfuse/langfuse/issues). Issues are labeled, and some good issues to start with are labeled: [good first issue](https://github.com/langfuse/langfuse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).diff --git a/scripts/agents/configure-langfuse-identity.sh b/scripts/agents/configure-langfuse-identity.shdeleted file mode 100755index d77642427b..0000000000--- a/scripts/agents/configure-langfuse-identity.sh+++ /dev/null@@ -1,211 +0,0 @@-#!/usr/bin/env bash--set -euo pipefail--repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"-mode="${1:-write}"--if [[ "$mode" != "write" && "$mode" != "--probe" ]]; then- echo "Usage: $0 [--probe]" >&2- exit 2-fi--# Home identity is machine-level. Workspace-scoped harnesses (OpenCode) prompt-# on any $HOME path, so only touch it when the caller redirected the directory,-# opted in, or this is a normal non-OpenCode install.-opencode_env="${OPENCODE:-}${OPENCODE_DIR:-}${OPENCODE_BIN:-}${OPENCODE_CONFIG:-}"-allow_home=0-if [[ -n "${LANGFUSE_CONFIG_DIR:-}" || "${LANGFUSE_ALLOW_HOME_IDENTITY:-}" == "1" ]]; then- allow_home=1-elif [[ -z "$opencode_env" ]]; then- allow_home=1-fi--if [[ -n "${LANGFUSE_CONFIG_DIR:-}" ]]; then- identity_dir="$LANGFUSE_CONFIG_DIR"-elif [[ "$allow_home" -eq 1 ]]; then- identity_dir="$HOME/.config/langfuse"-else- identity_dir=""-fi-identity_file="${identity_dir:+$identity_dir/me.md}"--# Mirror into the checkout so agents can read identity without leaving the-# project. Tests that redirect LANGFUSE_CONFIG_DIR must set-# LANGFUSE_WORKSPACE_IDENTITY_DIR if they want this path exercised.-workspace_identity_dir=""-if [[ -n "${LANGFUSE_WORKSPACE_IDENTITY_DIR:-}" ]]; then- workspace_identity_dir="$LANGFUSE_WORKSPACE_IDENTITY_DIR"-elif [[ -z "${LANGFUSE_CONFIG_DIR:-}" ]]; then- workspace_identity_dir="$repo_root/.langfuse"-fi-workspace_identity_file="${workspace_identity_dir:+$workspace_identity_dir/me.md}"--install_identity_file() {- local dest_dir="$1"- local source="$2"- local dest_file="$dest_dir/me.md"-- if [[ -z "$dest_dir" || ! -f "$source" ]]; then- return 0- fi- if [[ -f "$dest_file" ]]; then- return 0- fi- umask 077- if ! mkdir -p "$dest_dir"; then- echo "Langfuse identity: could not create $dest_dir; onboarding can retry during the agent session."- return 0- fi- chmod 700 "$dest_dir" || true- local tmp_file- tmp_file="$(mktemp "$dest_dir/.me.md.XXXXXX")" || return 0- if cp "$source" "$tmp_file" && mv -f "$tmp_file" "$dest_file"; then- echo "Langfuse identity: wrote $dest_file"- else- rm -f "$tmp_file"- fi-}--# The workspace file is what agents edit and delete. Do not refill it from-# the home copy β that would undo "delete to be asked again". A missing-# workspace copy falls through to Linear. If only the workspace file-# exists, still seed a missing home copy.-if [[ "$mode" = "write" && -n "$workspace_identity_file" && -f "$workspace_identity_file" ]]; then- echo "Langfuse identity: already configured at $workspace_identity_file"- install_identity_file "$identity_dir" "$workspace_identity_file"- exit 0-fi--linear_token=""-linear_token_name=""-for candidate in LINEAR_API_KEY LINEAR_TOKEN LINEAR_API_TOKEN; do- if [[ -n "${!candidate:-}" ]]; then- linear_token="${!candidate}"- linear_token_name="$candidate"- break- fi-done--if [[ -z "$linear_token" ]]; then- echo "Langfuse identity: no Linear token available."- echo "Cursor Cloud: add secret LINEAR_API_KEY at https://cursor.com/dashboard/cloud-agents and start a new run."- exit 0-fi--response="$(- printf 'header = "Authorization: %s"\n' "$linear_token" |- curl --fail --silent --show-error --connect-timeout 3 --max-time 10 \- --config - \- https://api.linear.app/graphql \- -H "Content-Type: application/json" \- --data '{"query":"{ viewer { name email } teams { nodes { name key } } }"}' \- 2>/dev/null-)" || {- if [[ "$mode" = "--probe" ]]; then- echo "linear_token: set ($linear_token_name)"- echo "linear_viewer: unavailable (Linear unreachable or token rejected)"- else- echo "Langfuse identity: $linear_token_name is set but Linear rejected the viewer query."- fi- exit 0-}--if [[ "$mode" = "--probe" ]]; then- LINEAR_RESPONSE="$response" python3 - "$linear_token_name" <<'PY'-import json-import os-import sys--token_name = sys.argv[1]-try:- payload = json.loads(os.environ["LINEAR_RESPONSE"])-except json.JSONDecodeError:- print(f"linear_token: set ({token_name})")- print("linear_viewer: unavailable (invalid response)")- sys.exit(0)-viewer = (payload.get("data") or {}).get("viewer") or {}-teams = (payload.get("data") or {}).get("teams", {}).get("nodes", [])-name = viewer.get("name") or ""-email = viewer.get("email") or ""-langfuse_member = any(- team.get("key") == "LF" or team.get("name") == "Langfuse" for team in teams-)--print(f"linear_token: set ({token_name})")-if name or email:- print(f"linear_viewer: {name} <{email}>")-else:- print("linear_viewer: unavailable")-print(f"langfuse_team: {'member' if langfuse_member else 'not found'}")-PY- exit 0-fi--tmp_dir="$(mktemp -d)"-tmp_file="$tmp_dir/me.md"-cleanup() {- rm -rf "$tmp_dir"-}-trap cleanup EXIT--set +e-LINEAR_RESPONSE="$response" python3 - "$tmp_file" "$repo_root" <<'PY'-import datetime-import json-import os-import sys--tmp_file, repo_root = sys.argv[1:]-try:- payload = json.loads(os.environ["LINEAR_RESPONSE"])-except json.JSONDecodeError:- print("Langfuse identity: Linear returned an invalid response.", file=sys.stderr)- sys.exit(3)-if payload.get("errors"):- print("Langfuse identity: Linear returned GraphQL errors.", file=sys.stderr)- sys.exit(3)--data = payload.get("data") or {}-viewer = data.get("viewer") or {}-teams = (data.get("teams") or {}).get("nodes") or []-langfuse_member = any(- team.get("key") == "LF" or team.get("name") == "Langfuse" for team in teams-)-if not langfuse_member:- print(- "Langfuse identity: Linear viewer is not a member of the Langfuse team; "- "leaving me.md unchanged.",- file=sys.stderr,- )- sys.exit(4)--name = viewer.get("name") or "unknown"-email = viewer.get("email") or "unknown"-today = datetime.date.today().isoformat()-content = f"""# Me, at Langfuse--- **Name:** {name}-- **Role:** maintainer-- **GitHub:** unknown (derive from the team roster when needed)-- **Tracker identity:** {name} <{email}>-- **Focus:** not recorded yet β ask once when relevant-- **Checkouts:** {repo_root} (langfuse)-- **Connectors verified:** Linear API-- *Recovered {today} from `LINEAR_API_KEY` by the repo agent bootstrap. Edit freely; delete to recover again.*-"""--with open(tmp_file, "w", encoding="utf-8") as file:- file.write(content)-print(f"Langfuse identity: recovered {name} <{email}>")-PY-status=$?-set -e--if [[ "$status" -ne 0 ]]; then- echo "Langfuse identity: recovery skipped; onboarding can retry during the agent session."- exit 0-fi--install_identity_file "$identity_dir" "$tmp_file"-install_identity_file "$workspace_identity_dir" "$tmp_file"diff --git a/scripts/agents/configure-langfuse-identity.test.sh b/scripts/agents/configure-langfuse-identity.test.shdeleted file mode 100755index 1e8f29fa35..0000000000--- a/scripts/agents/configure-langfuse-identity.test.sh+++ /dev/null@@ -1,246 +0,0 @@-#!/usr/bin/env bash--set -euo pipefail--repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"-tmpdir="$(mktemp -d)"--cleanup() {- rm -rf "$tmpdir"-}-trap cleanup EXIT--mkdir -p "$tmpdir/bin"-cat >"$tmpdir/bin/curl" <<'EOF'-#!/usr/bin/env bash-printf '%s' "$LINEAR_FIXTURE"-EOF-chmod +x "$tmpdir/bin/curl"--run_without_token() {- env \- -u LINEAR_API_KEY \- -u LINEAR_TOKEN \- -u LINEAR_API_TOKEN \- PATH="$tmpdir/bin:$PATH" \- LANGFUSE_CONFIG_DIR="$tmpdir/no-token" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-}--no_token_output="$(run_without_token)"-grep -Fq "add secret LINEAR_API_KEY" <<<"$no_token_output"-test ! -e "$tmpdir/no-token/me.md"--fixture='{"data":{"viewer":{"name":"Nikita Kabardin","email":"[email protected]"},"teams":{"nodes":[{"name":"Langfuse","key":"LF"}]}}}'-identity_dir="$tmpdir/identity"-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$identity_dir" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"--grep -Fq -- "- **Name:** Nikita Kabardin" "$identity_dir/me.md"-grep -Fq -- "- **Role:** maintainer" "$identity_dir/me.md"-grep -Fq -- "- **Tracker identity:** Nikita Kabardin <[email protected]>" "$identity_dir/me.md"-if grep -Fq "test-secret-that-must-not-be-written" "$identity_dir/me.md"; then- echo "Identity file leaked the Linear token"- exit 1-fi--printf '\nuser edit\n' >>"$identity_dir/me.md"-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$identity_dir" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-grep -Fq "user edit" "$identity_dir/me.md"--outsider_fixture='{"data":{"viewer":{"name":"Outside User","email":"[email protected]"},"teams":{"nodes":[{"name":"Another Team","key":"OTHER"}]}}}'-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="another-test-secret" \-LINEAR_FIXTURE="$outsider_fixture" \-LANGFUSE_CONFIG_DIR="$tmpdir/outsider" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-test ! -e "$tmpdir/outsider/me.md"--# Recovery must lock the identity directory to the owner even when the-# caller inherited a permissive umask.-(- umask 000- PATH="$tmpdir/bin:$PATH" \- LINEAR_API_KEY="test-secret-that-must-not-be-written" \- LINEAR_FIXTURE="$fixture" \- LANGFUSE_CONFIG_DIR="$tmpdir/loose-umask" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-)-dir_mode="$(stat -c %a "$tmpdir/loose-umask")"-if [[ "$dir_mode" != "700" ]]; then- echo "Identity directory mode is $dir_mode, expected 700"- exit 1-fi--# A write that cannot create the identity directory must still exit 0 so-# postinstall and Cloud boot cannot fail the install for a missing HOME.-touch "$tmpdir/not-a-directory"-set +e-mkdir_fail_status=0-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$tmpdir/not-a-directory" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-mkdir_fail_status=$?-set -e-if [[ "$mkdir_fail_status" -ne 0 ]]; then- echo "Identity recovery exited $mkdir_fail_status when mkdir failed"- exit 1-fi--# The onboarding probe must still report the GitHub signals when the Linear-# side fails outright, so a blocked egress path cannot truncate step 1.-probe_tree="$tmpdir/probe-tree"-mkdir -p "$probe_tree/.agents/skills/langfuse-onboarding/scripts" "$probe_tree/scripts/agents"-cp \- "$repo_root/.agents/skills/langfuse-onboarding/scripts/whoami.sh" \- "$probe_tree/.agents/skills/langfuse-onboarding/scripts/whoami.sh"-cat >"$probe_tree/scripts/agents/configure-langfuse-identity.sh" <<'EOF'-#!/usr/bin/env bash-echo "stub identity probe failed" >&2-exit 1-EOF-chmod +x "$probe_tree/scripts/agents/configure-langfuse-identity.sh"--cat >"$tmpdir/bin/gh" <<'EOF'-#!/usr/bin/env bash-echo "gh: Resource not accessible by integration (HTTP 403)" >&2-exit 1-EOF-chmod +x "$tmpdir/bin/gh"--probe_output="$(- PATH="$tmpdir/bin:$PATH" \- HOME="$tmpdir/probe-home" \- bash "$probe_tree/.agents/skills/langfuse-onboarding/scripts/whoami.sh"-)"-grep -Fq "linear_viewer: unavailable" <<<"$probe_output"-grep -Fq "gh_user: unavailable" <<<"$probe_output"--# A rejected or unreachable Linear endpoint reports in the probe's own label-# format rather than aborting the probe.-cat >"$tmpdir/bin/curl" <<'EOF'-#!/usr/bin/env bash-exit 7-EOF-chmod +x "$tmpdir/bin/curl"--unreachable_output="$(- PATH="$tmpdir/bin:$PATH" \- LINEAR_API_KEY="unused-test-secret" \- LANGFUSE_CONFIG_DIR="$tmpdir/unreachable" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" --probe-)"-grep -Fq "linear_token: set (LINEAR_API_KEY)" <<<"$unreachable_output"-grep -Fq "linear_viewer: unavailable" <<<"$unreachable_output"-test ! -e "$tmpdir/unreachable/me.md"--cat >"$tmpdir/bin/curl" <<'EOF'-#!/usr/bin/env bash-printf '%s' "$LINEAR_FIXTURE"-EOF-chmod +x "$tmpdir/bin/curl"--# Workspace-scoped harnesses must not stat $HOME/.config. A file that exists-# only under HOME is absent unless LANGFUSE_ALLOW_HOME_IDENTITY=1.-mkdir -p "$tmpdir/hidden-home/.config/langfuse"-printf 'home identity\n' >"$tmpdir/hidden-home/.config/langfuse/me.md"-whoami_script="$repo_root/.agents/skills/langfuse-onboarding/scripts/whoami.sh"--empty_workspace="$tmpdir/empty-workspace"-mkdir -p "$empty_workspace"-hidden_home_output="$(- env \- -u LANGFUSE_CONFIG_DIR \- -u LANGFUSE_ALLOW_HOME_IDENTITY \- PATH="$tmpdir/bin:$PATH" \- HOME="$tmpdir/hidden-home" \- LANGFUSE_WORKSPACE_IDENTITY_DIR="$empty_workspace" \- bash "$whoami_script"-)"-grep -Fq "me.md: absent" <<<"$hidden_home_output"-if grep -Fq "hidden-home" <<<"$hidden_home_output"; then- echo "whoami.sh touched HOME without LANGFUSE_ALLOW_HOME_IDENTITY"- exit 1-fi--opt_in_home_output="$(- PATH="$tmpdir/bin:$PATH" \- HOME="$tmpdir/hidden-home" \- LANGFUSE_ALLOW_HOME_IDENTITY=1 \- LANGFUSE_WORKSPACE_IDENTITY_DIR="$empty_workspace" \- bash "$whoami_script"-)"-grep -Fq "me.md: present ($tmpdir/hidden-home/.config/langfuse/me.md)" <<<"$opt_in_home_output"--workspace_identity="$tmpdir/workspace-identity"-mkdir -p "$workspace_identity"-printf 'workspace identity\n' >"$workspace_identity/me.md"-workspace_output="$(- PATH="$tmpdir/bin:$PATH" \- HOME="$tmpdir/hidden-home" \- LANGFUSE_WORKSPACE_IDENTITY_DIR="$workspace_identity" \- bash "$whoami_script"-)"-grep -Fq "me.md: present ($workspace_identity/me.md)" <<<"$workspace_output"--# Recovery under OpenCode must write the workspace copy and leave HOME alone.-opencode_home="$tmpdir/opencode-home"-opencode_workspace="$tmpdir/opencode-workspace"-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-OPENCODE=1 \-HOME="$opencode_home" \-LANGFUSE_WORKSPACE_IDENTITY_DIR="$opencode_workspace" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-test ! -e "$opencode_home/.config/langfuse/me.md"-grep -Fq -- "- **Name:** Nikita Kabardin" "$opencode_workspace/me.md"--# OpenCode-first recovery leaves only the workspace file; a later normal-# install with home access must seed the machine-level copy from it.-opencode_then_home="$tmpdir/opencode-then-home"-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$opencode_then_home" \-LANGFUSE_WORKSPACE_IDENTITY_DIR="$opencode_workspace" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-grep -Fq -- "- **Name:** Nikita Kabardin" "$opencode_then_home/me.md"--# Deleting the workspace file must re-query Linear, not copy a stale home-# file back. The home copy is left as the human last edited it.-printf '\nstale home focus\n' >>"$opencode_then_home/me.md"-rm -f "$opencode_workspace/me.md"-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$opencode_then_home" \-LANGFUSE_WORKSPACE_IDENTITY_DIR="$opencode_workspace" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-grep -Fq -- "- **Name:** Nikita Kabardin" "$opencode_workspace/me.md"-if grep -Fq "stale home focus" "$opencode_workspace/me.md"; then- echo "Workspace identity was refilled from the home copy"- exit 1-fi-grep -Fq "stale home focus" "$opencode_then_home/me.md"--# Redirected LANGFUSE_CONFIG_DIR still seeds an explicit workspace copy.-PATH="$tmpdir/bin:$PATH" \-LINEAR_API_KEY="test-secret-that-must-not-be-written" \-LINEAR_FIXTURE="$fixture" \-LANGFUSE_CONFIG_DIR="$tmpdir/redirected-home" \-LANGFUSE_WORKSPACE_IDENTITY_DIR="$tmpdir/redirected-workspace" \- bash "$repo_root/scripts/agents/configure-langfuse-identity.sh"-grep -Fq -- "- **Name:** Nikita Kabardin" "$tmpdir/redirected-home/me.md"-grep -Fq -- "- **Name:** Nikita Kabardin" "$tmpdir/redirected-workspace/me.md"--echo "Langfuse identity recovery tests passed"diff --git a/scripts/agents/start-cursor-cloud.sh b/scripts/agents/start-cursor-cloud.shindex c12f1012e5..a99d51c009 100755--- a/scripts/agents/start-cursor-cloud.sh+++ b/scripts/agents/start-cursor-cloud.sh@@ -7,11 +7,6 @@ compose_file="${CURSOR_COMPOSE_FILE:-$repo_root/docker-compose.build.yml}"wait_timeout="${CURSOR_COMPOSE_WAIT_TIMEOUT_SECONDS:-600}"compose_project_name="${CURSOR_COMPOSE_PROJECT_NAME:-langfuse-cursor}"-# Environment builds do not rerun install when a new agent boots. Recover the-# developer identity before starting services so every fresh Cloud run has it.-# Best-effort: a missing HOME or a blocked Linear route must not abort the stack.-bash "$repo_root/scripts/agents/configure-langfuse-identity.sh" || true-# The workspace .env is for processes running on the host and therefore uses# localhost service URLs. Compose services need container-network hostnames.# Start from a clean environment and explicitly preserve only Docker anddiff --git a/scripts/agents/start-cursor-cloud.test.sh b/scripts/agents/start-cursor-cloud.test.shindex 9de2d8cc48..45367384d3 100755--- a/scripts/agents/start-cursor-cloud.test.sh+++ b/scripts/agents/start-cursor-cloud.test.sh@@ -67,7 +67,6 @@ chmod +x \# Leave $test_docker_socket missing so ensure_docker_socket_reachable must# repair the parent directory before the daemon probe loop.PATH="$tmpdir/bin:$PATH" \-LANGFUSE_CONFIG_DIR="$tmpdir/identity" \LINEAR_API_KEY="" \LINEAR_TOKEN="" \LINEAR_API_TOKEN="" \diff --git a/scripts/postinstall.sh b/scripts/postinstall.shindex b691dc0274..0e25efd1f8 100644--- a/scripts/postinstall.sh+++ b/scripts/postinstall.sh@@ -25,8 +25,3 @@ pnpm run agents:sync# that installs. The lint job runs the full check.node scripts/agents/sync-agent-shims.mjs --check-# Recover the developer identity in every newly installed worktree. This is-# best-effort: contributors and local installs commonly have no Linear token.-if [[ -f "scripts/agents/configure-langfuse-identity.sh" ]]; then- bash scripts/agents/configure-langfuse-identity.sh || true-fi