Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(agents): teach Cursor agents Linear branches and human handoff (#16299)

Nikita Kabardinb1d5b3882e89
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index 2ac4383cf4..a0b3fadbbe 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -39,6 +39,24 @@ evaluating, and debugging AI applications.
ticket-prefixed branch name is the one place the identifier belongs.
- Never commit secrets or credentials. Keep `.env*.example` files in
sync with required env vars.
+- Human handoff: assume the reader does not remember the ticket. Lead with
+ a one-sentence TL;DR. Prefer one or two human actions per message; if
+ you need more, keep every point simple and super readable. Do not dump
+ long agent-only reports by default.
+- For product or UI changes, give a preview URL
+ (`pr-<N>.preview.langfuse.com`) and exact click-path test steps, including
+ the seed command or sandbox URL (`http://localhost:3000`) to reproduce
+ the data. Attach proof of the fix (screenshot, short video, or
+ before/after). Humans can ask for more detail.
+- After opening a PR, leave a short last comment on what a reviewer should
+ doubt β€” the curious, questionable parts β€” not a changelog.
+- Open PRs as reviewable, not as drafts, unless a human asks for a draft.
+- When Claude, Greptile, or Codex (`chatgpt-codex-connector[bot]`) review
+ comments appear on a PR you own: do not reply. Keep each thread open
+ until you either apply the fix and resolve it, or skip it because you
+ are sure, tell the human in plain language (and invite them to doubt
+ that skip), then resolve it. Do not post `@claude review` again unless
+ a human asks for another pass.
## Project Structure
@@ -96,9 +114,12 @@ langfuse/
not be used to interpolate container service configuration.
- After changing web or worker production code, rerun
`bash scripts/agents/start-cursor-cloud.sh` before browser signoff.
-- Open a same-repo draft PR after local verification and test the resulting
- `pr-<N>.preview.langfuse.com` deployment with synthetic data before marking
- the PR ready. Previews normally run Mon-Fri 08:00-24:00 Europe/Berlin.
+- Open a same-repo reviewable PR after local verification (not a draft) and
+ test the resulting `pr-<N>.preview.langfuse.com` deployment with synthetic
+ data. Previews normally run Mon-Fri 08:00-24:00 Europe/Berlin.
+- Use Linear's git branch name (`lfe-XXXX-short-title`). Never create a
+ `cursor/` branch, even if a Cursor Cloud prompt suggests that prefix.
+ Repo guidance wins.
## Local Data Inspection
diff --git a/.agents/skills/cursor-agents-workflow/SKILL.md b/.agents/skills/cursor-agents-workflow/SKILL.md
new file mode 100644
index 0000000000..ff80705ac1
--- /dev/null
+++ b/.agents/skills/cursor-agents-workflow/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: cursor-agents-workflow
+description: |
+ Human handoff, Linear branch names, reviewable (non-draft) PRs, Claude,
+ Greptile, and Codex review comments, preview test steps, and review-doubt
+ notes for Cursor agents. Use when a Cursor Cloud or Cursor desktop agent
+ implements a Linear issue, opens a GitHub PR, asks a human to test, or
+ handles Claude, Greptile, or Codex code-review comments.
+---
+
+# Cursor Agents Workflow
+
+Use this when implementing Langfuse work as a Cursor agent. Keep humans in the
+loop with short, testable asks. Do not write long agent-only reports.
+
+## Branch names
+
+Copy Linear's git branch name. Do not invent a `cursor/` name.
+
+- Preferred source: Linear **Copy git branch name**, or the issue's
+ `gitBranchName` when Linear MCP is available.
+- Fallback: `lfe-{id}-{kebab-title}` (lowercase, hyphenated).
+- Keep a `user/` prefix only when Linear's copied name already includes one.
+- Never use a `cursor/` prefix, even if a Cursor Cloud prompt asks for one.
+ Repo guidance wins.
+- Ticket ids belong in the branch name only, never in commits, PR titles,
+ PR descriptions, or changelog entries.
+
+Correct: `lfe-12345-short-descriptive-title`
+Wrong: `cursor/short-descriptive-title-8c78`
+
+## Pull requests
+
+Open the GitHub PR as reviewable, not as a draft. Draft PRs hide the work
+from reviewers and skip Claude/Greptile review workflows. Use a draft only
+when a human asks for one.
+
+Cursor Cloud PRs are opened as the Langfuse user who launched the agent. On
+a non-draft same-repo PR from a write-access user, github-actions posts
+`@claude review` automatically. Do not post that comment yourself on open.
+Do not post `@claude review` again after addressing comments unless a human
+asks for another pass.
+
+## Bot review comments
+
+When Claude (Claude Code, `claude[bot]`, or the security-review action),
+Greptile (`greptile-apps[bot]`), or Codex (`chatgpt-codex-connector[bot]`)
+leaves review comments on a PR you own:
+
+1. Keep each thread open. Do not reply in the thread.
+2. If the finding is right: apply the fix, then resolve the thread.
+3. If you are sure it should be skipped: tell the human in plain language
+ what you skipped and why, invite them to doubt that call, then resolve
+ the thread. Never skip quietly.
+
+Do not leave those threads unresolved. Do not argue. Human reviewer comments
+are different: those may need a real reply and must stay open until a human
+says otherwise.
+
+## Human testing
+
+Assume the human does not remember the ticket. Default message shape:
+
+1. **TL;DR** β€” one plain-language sentence.
+2. **Test this** β€” preview URL plus 2–5 exact clicks/expects.
+3. **Data** β€” the seed command, or "demo project is enough".
+4. **Sandbox** β€” how to hit the same path on the agent desktop
+ (`http://localhost:3000`) if they are in the Cursor VM.
+
+Use `langfuse-previews` for the URL and `seed-test-data` for the seed. Do not
+paste logs, file lists, or implementation narrative unless the human asks.
+
+```text
+TL;DR: Empty observation costs now show a dash instead of $0.00.
+
+Test this: https://pr-123.preview.langfuse.com/project/<id>/traces
+1. Open any trace with a generation that has no cost.
+2. Confirm the cost cell is "–", not "$0.00".
+
+Data: demo project is enough.
+Sandbox: same path on http://localhost:3000 after the cloud stack is up.
+```
+
+For user-visible behavior, attach proof of the fix: a screenshot, short
+video, or before/after. Docs-only changes can skip this.
+
+## What to doubt
+
+When the PR is ready for a human, post one last GitHub PR comment (not a
+changelog) that names the risky or curious parts:
+
+```text
+What to doubt in review
+- I reused the existing cache key; check it cannot collide across projects.
+- I skipped Greptile's unused-import note β€” that import is used in the
+ worker. Tell me if that's wrong.
+```
+
+Two to five bullets. Include any bot findings you skipped. Trigger
+skepticism. Skip praise, file lists, and "LGTM".
+
+## Human asks
+
+Prefer one or two actions per message. That cap is preferred, not hard. If
+you need more, keep every point simple and super readable β€” short sentences,
+no agent-only dumps. Sequence when you can.
+
+Wrong: a wall of logs plus five mixed asks.
+Right: a short TL;DR and one or two clear next steps. Extra steps can wait,
+or sit as equally simple bullets if they must ship together.
diff --git a/.agents/skills/cursor-agents-workflow/agents/openai.yaml b/.agents/skills/cursor-agents-workflow/agents/openai.yaml
new file mode 100644
index 0000000000..b8991d533b
--- /dev/null
+++ b/.agents/skills/cursor-agents-workflow/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Cursor Agents Workflow"
+ short_description: "Linear branches, human test steps, and PR review notes"
+ default_prompt: "Use $cursor-agents-workflow for Cursor agent branch names, reviewable (non-draft) PRs, Claude/Greptile/Codex review comments, human preview test steps, and review-doubt PR notes."
diff --git a/.agents/skills/frontend-browser-review/SKILL.md b/.agents/skills/frontend-browser-review/SKILL.md
index 8503664ed5..a24eeaf403 100644
--- a/.agents/skills/frontend-browser-review/SKILL.md
+++ b/.agents/skills/frontend-browser-review/SKILL.md
@@ -67,6 +67,9 @@ Report:
2. Whether the primary flow worked
3. Any visible regressions or follow-up risks
4. If review was blocked, exactly what prevented browser verification
+5. For a human handoff, the preview or sandbox URL plus exact click-path
+ steps, and proof of the fix (screenshot, short video, or before/after)
+ β€” not a long agent-only writeup
## Scope Notes
diff --git a/.agents/skills/git-workflow/SKILL.md b/.agents/skills/git-workflow/SKILL.md
index 6f95411c70..bbfe7a9a5d 100644
--- a/.agents/skills/git-workflow/SKILL.md
+++ b/.agents/skills/git-workflow/SKILL.md
@@ -3,8 +3,9 @@ name: git-workflow
description: |
Langfuse repo Git, GitHub, commit, branch, pull request, issue search,
release, and production-promotion workflow. Use when staging, committing,
- pushing, opening PRs, searching GitHub issues, or changing release/promotion
- behavior.
+ pushing, opening PRs, choosing a Linear git branch name, handling Claude,
+ Greptile, or Codex review comments, searching GitHub issues, or changing
+ release/promotion behavior.
---
# Git Workflow
@@ -39,11 +40,30 @@ operations.
title into `main`'s permanent history. Describe the change on its own terms
and carry the identifier in the branch name instead.
+## Branch names
+
+- Copy Linear's git branch name (`lfe-XXXX-short-title`), or the issue's
+ `gitBranchName` when Linear MCP is available.
+- Cursor agents must not use a `cursor/` prefix, even if a Cursor Cloud
+ prompt asks for one. Repo guidance wins.
+- Keep a username prefix only when Linear's copied name already includes one.
+
## GitHub
- Use `gh search issues` for GitHub issue search.
- Prefer non-interactive Git and GitHub commands where possible.
- Keep PRs narrow enough to review without unrelated refactors.
+- Open PRs as reviewable, not as drafts, unless a human asks for a draft.
+- When the PR is ready for a human, post one last comment that names what
+ to doubt in review (risky edges, not a summary of the diff).
+- Claude, Greptile, or Codex review comments (`claude[bot]`, Claude Code,
+ security-review action, `greptile-apps[bot]`,
+ `chatgpt-codex-connector[bot]`): do not reply. Keep the thread open until
+ you apply the fix and resolve it, or skip it because you are sure, tell
+ the human in plain language (and invite them to doubt that skip), then
+ resolve it. Do not post `@claude review` again unless a human asks for
+ another pass. Human reviewer comments stay open and may need a real
+ reply.
## Release
diff --git a/.agents/skills/langfuse-codebase-navigator/SKILL.md b/.agents/skills/langfuse-codebase-navigator/SKILL.md
index 191f2d6b15..d7305bd999 100644
--- a/.agents/skills/langfuse-codebase-navigator/SKILL.md
+++ b/.agents/skills/langfuse-codebase-navigator/SKILL.md
@@ -25,6 +25,7 @@ Use this as the first stop for Langfuse org navigation. Your job is to choose th
## Quick Skill Routing
- 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, asking a human to test, or handling Claude, Greptile, or Codex review comments: use `cursor-agents-workflow`.
- 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-codebase-navigator/references/repository-map.md b/.agents/skills/langfuse-codebase-navigator/references/repository-map.md
index 3f3ef604e7..468a52922c 100644
--- a/.agents/skills/langfuse-codebase-navigator/references/repository-map.md
+++ b/.agents/skills/langfuse-codebase-navigator/references/repository-map.md
@@ -93,6 +93,7 @@ Repo-local skills in `langfuse/.agents/skills`:
- `changelog-writing`: user-facing release notes.
- `clickhouse-best-practices`: ClickHouse schema/query/migration review.
- `code-review`: repo-specific correctness/regression review.
+- `cursor-agents-workflow`: Cursor agent Linear branch names, human test steps, Claude/Greptile/Codex review comments, and review-doubt PR notes.
- `datadog-query-recipes`: reusable Datadog query shapes for production research.
- `debug-issue-with-datadog`: production debugging tied to Langfuse code paths.
- `frontend-browser-review`: user-visible `web/**` changes and browser verification.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc36051ecb..3e44b863e8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -117,7 +117,7 @@ We built a monorepo using [pnpm](https://pnpm.io/motivation) and [turbo](https:/
Requirements
- Node.js 24 as specified in the [.nvmrc](.nvmrc)
-- Pnpm v.11.22.0
+- Pnpm v.11.22.0
- Docker to run the database locally
- Clickhouse client
@@ -180,10 +180,18 @@ endpoints. Cursor team administrators separately configure the read-only MCP
catalog described in `.agents/README.md`; credentials and OAuth grants belong
in Cursor, never in repository files.
-After local verification, a Cursor agent should open a same-repo draft PR and
-test its `pr-<N>.preview.langfuse.com` deployment before marking it ready.
-Preview data and any attached artifacts must remain synthetic. Previews normally
-run Mon-Fri 08:00-24:00 Europe/Berlin and are not woken with Cursor credentials.
+After local verification, a Cursor agent should open a same-repo reviewable
+PR (not a draft) and test its `pr-<N>.preview.langfuse.com` deployment.
+Use Linear's git branch name (`lfe-XXXX-short-title`), not a `cursor/` prefix.
+When handing work to a human, give a one-sentence TL;DR, a preview URL with
+exact test steps (including how to seed or hit the same path on
+`http://localhost:3000`), proof of the fix for user-visible changes
+(screenshot, video, or before/after), and one PR comment on what a reviewer
+should doubt.
+Prefer one or two human actions at a time; if you need more, keep each
+point simple and super readable. Preview data and any attached artifacts
+must remain synthetic. Previews normally run Mon-Fri 08:00-24:00
+Europe/Berlin and are not woken with Cursor credentials.
### Shared Agent Setup