πͺ’ 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
chore(agents): teach Cursor agents Linear branches and human handoff (#16299)
Nikita Kabardinb1d5b3882e89
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.mdindex 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 insync 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 Inspectiondiff --git a/.agents/skills/cursor-agents-workflow/SKILL.md b/.agents/skills/cursor-agents-workflow/SKILL.mdnew file mode 100644index 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.yamlnew file mode 100644index 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.mdindex 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 worked3. Any visible regressions or follow-up risks4. 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 Notesdiff --git a/.agents/skills/git-workflow/SKILL.md b/.agents/skills/git-workflow/SKILL.mdindex 6f95411c70..bbfe7a9a5d 100644--- a/.agents/skills/git-workflow/SKILL.md+++ b/.agents/skills/git-workflow/SKILL.md@@ -3,8 +3,9 @@ name: git-workflowdescription: |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 termsand 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.## Releasediff --git a/.agents/skills/langfuse-codebase-navigator/SKILL.md b/.agents/skills/langfuse-codebase-navigator/SKILL.mdindex 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.mdindex 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.mdindex 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 MCPcatalog described in `.agents/README.md`; credentials and OAuth grants belongin 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