πͺ’ 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): split the repo by audience, and make the maintainer half an assistant (#17058)
Nikita Kabardin83f72b1f133d
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.mdindex d3b10110a0..58615cc95d 100644--- a/.agents/AGENTS.md+++ b/.agents/AGENTS.md@@ -3,6 +3,55 @@Langfuse is an open source LLM engineering platform for developing, monitoring,evaluating, and debugging AI applications.+## Who You Are Working For++This repo serves two different people, and they get different halves of it.+Work out which before anything else, and never guess silently.++It is a configuration question, not an interview. Read+`~/.config/langfuse/me.md`; if it is not there, `gh api repos/langfuse/langfuse+--jq .permissions` settles contributor versus maintainer on its own, and for+anything it cannot tell you β which areas they work on β **just ask, once**, and+write the answer to that file so nobody asks again. That is a question and a+file, not a process. 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.+## How To Work- Know who you are working for before you assume what they may do. An outsidediff --git a/.agents/skills/langfuse-onboarding/SKILL.md b/.agents/skills/langfuse-onboarding/SKILL.mdindex f476e73d41..55e2a0d6ab 100644--- a/.agents/skills/langfuse-onboarding/SKILL.md+++ b/.agents/skills/langfuse-onboarding/SKILL.md@@ -1,20 +1,27 @@---name: langfuse-onboardingdescription: |- Work out who the person in front of you is β outside contributor or Langfuse- maintainer, and which product areas they own β record it, and walk them- through onboarding. Use on "onboard me", "I'm new here", "what do I need to- set up", "am I set up correctly", and whenever you need to know someone's- role or focus and no identity file exists yet.+ Configure an agent for whoever is using it β outside contributor or Langfuse+ maintainer, which areas they work on, which integrations are connected β and,+ for someone genuinely new, walk them through onboarding. 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", and whenever you need to know someone's role and+ no identity file exists yet.---# Onboarding at Langfuse-Two jobs. **Establish who you are talking to**, once, and record it so no later-session has to ask again. Then **walk the onboarding path** for that person.+Two jobs, and they are separable β most of the time you only want the first.-Everything an agent needs to behave differently for a contributor than for a-maintainer follows from the first job, so do it before anything else.+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 β derive the role; do not ask what you can find out@@ -63,9 +70,11 @@ cannot live in one repo. Create the directory if it does not exist.config: no tokens, no keys. A repo `.env` is the wrong home β those areapp configuration and one careless `git add` publishes them.-Ask for **Focus** rather than deriving it. What someone owns on paper and what-they are actually responsible for this quarter are different things, and only-they know the second. Keep their phrasing.+**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 itgoes stale within a week. `linear-work-rhythm` reads it live from the tracker@@ -81,7 +90,14 @@ Stop there. Do not describe the issue tracker, the label policy, the weeklyrhythm, or the internal handbook β a contributor cannot open any of it, andoffering it reads as a door that is locked.-## Step 3b β the maintainer path+## 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,@@ -138,9 +154,12 @@ and say which ones are missing rather than discovering it mid-task.| **Sentry** | `sentry-instrumentation` || **Pylon** | `housekeeping` || **Hex** | `analyze-cloud-costs` |-| **Slack** | `weekly-production-review` |+| **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.@@ -166,9 +185,11 @@ carry on and hope:git clone [email protected]:langfuse/langfuse-docs.git```-It carries the handbook, the docs, and the changelog. Without it this skill-cannot read step 3b, and no shipped change can get a docs page or a changelog-entry without a separate detour.+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.diff --git a/.agents/skills/linear-work-rhythm/SKILL.md b/.agents/skills/linear-work-rhythm/SKILL.mdindex 5fc05a49fb..0fe563a2d2 100644--- a/.agents/skills/linear-work-rhythm/SKILL.md+++ b/.agents/skills/linear-work-rhythm/SKILL.md@@ -4,8 +4,12 @@ description: |Answer "what should I do today" for a Langfuse maintainer, from the trackerrather than from memory: which projects you lead, which owe an update beforeMonday planning, what shipped but is not finished, what is waiting on your- decision. Use on "what should I do today", "what's on my plate", "what should- I work on next", "prep my Monday update", "what did I say last week".+ decision, and what colleagues are working on that overlaps. Use on "what+ should I do today", "what's on my plate", "what should I work on next", "prep+ my Monday update", "what did I say last week", "who else is working on this",+ "who should review this", and whenever someone hands over a bare link β a+ ticket, a pull request, a Slack permalink β and expects you to take it from+ there.---# The working rhythm, read live@@ -14,10 +18,11 @@ 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 `~/.config/langfuse/me.md`. If that file does not-exist, run [`langfuse-onboarding`](../langfuse-onboarding/SKILL.md) first β do-not guess, and do not answer this question for an outside contributor, who owns-none of it.+Who the person is comes from `~/.config/langfuse/me.md`. If it is not there,+**ask** β their name and what they work on, in one question β and write the file+so it is answered for good. Do not send a colleague of a year through onboarding+to find out their name; that skill is for people who are new. Do not guess, and+do not answer this question for an outside contributor, who owns none of it.**The rules behind every check below are the working agreement**, published in`content/handbook/tools-and-processes/using-linear.mdx` in@@ -43,7 +48,7 @@ A local list of someone's projects is stale within a week β this repo has beenburned by exactly that. `me.md` holds only the durable half: name, role, and thefocus they described in their own words.-## The five checks+## The six checksRun them, then report as **a short ranked list with the reason attached**, not astatus dump. Ranking beats completeness: the point is what to do next, and a@@ -100,13 +105,59 @@ to do; propose it.An issue that has been in `Merged` for weeks is the signal this step is notrunning. Count them and lead with the number.-### 3. Waiting on your decision+### 3. What the rest of the team is doing++The updates you have not read are worth more than the ones you wrote. Colleagues+post weekly on their own projects, and that is where you find out somebody is+already inside the surface you were about to change.++The workspace is shared with the wider organisation, and there is no team filter+on the updates query β so a bare `get_status_updates(type: "project")` returns+whatever is newest across every team and truncates at the limit. Filtering that+page down to Langfuse afterwards silently drops the rows you wanted, and the+answer comes back as "nobody is working on this."++Ask per project instead, so nothing competes for the page:++```+list_projects(team: "<the Langfuse team>", state: "started", fields: [name, lead])+get_status_updates(type: "project", project: "<each one>", limit: 5)+```++Then look for overlap with what this person leads or is about to touch, and+**name the colleague, not the ticket**:++> Trang was reworking that flow last week β worth asking her to review.++That sentence is the whole feature. A list of forty updates is not.++Two places to look beyond project updates: a colleague's `<Name> Housekeeping`+project, which is where people post work that belongs to no single project, and+the `AI edited` label on anything you are about to open β an earlier agent may+have left the reasoning already.++**The roster is what makes a name usable.** `components-mdx/team-members.mdx` in+`langfuse/langfuse-docs` lists everyone with their role and their **GitHub+handle**, which is the only join between the three places a colleague appears:+a display name in the tracker, a handle in `git log` and `git blame`, and a+reviewer on a pull request. Read it from `origin/main`, the same as the handbook.+Mind the direction. `git log` and `git blame` give you an author **name and+email**, not a handle β so the name is what you join on, and the handle is what+you get back, for asking GitHub to add them as a reviewer. If a name does not+match the roster, `gh api repos/langfuse/langfuse/commits/<sha>` carries the+author's login directly.++It is maintained by people adding themselves, so it lags β someone missing from+it is not evidence they are not on the team. When the roster and `git log`+disagree, `git log` is the one that just happened.++### 4. Waiting on your decisionTriage normally gets a decision within one working day. Check the triage state onyour teams, and your own inbox-shaped work: things assigned to you that you havenot moved, and requests routed to you as a feature owner.-### 4. Your open bugs+### 5. Your open bugsA weekly look at your own bugs, to catch what is slipping.@@ -117,7 +168,7 @@ list_issues(assignee: "me", label: "bug", state: "started")Also check unstarted bugs assigned to you β a bug nobody has begun is the onethat slips.-### 5. Lifecycle compliance, but only where it changes what you do+### 6. Lifecycle compliance, but only where it changes what you doReport a gap only when fixing it is the next action. In-progress projects need a*specific* target date; planned ones need owner, priority, a quarter-level target@@ -128,6 +179,22 @@ Do not turn this into an audit. One line naming the pattern is more useful thana per-project table, and the agreement is explicit that this system stayslightweight.+## Someone hands you a link++A 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 applies.++- **A tracker ticket** β reconstruct its history first+ ([`linear-context-handover`](../linear-context-handover/SKILL.md)), then say+ whether it is one commit or needs planning+ ([`linear-planning`](../linear-planning/SKILL.md)).+- **A Slack permalink** β read the thread if a Slack tool is connected. If it is+ 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 a+ parentless ticket needs their yes.+- **A pull request** β the review conventions are `git-workflow`, and whether it+ wants a stack is `pr-stack-workflow`.+## Writing anything backEvery write follows [`linear-agent-writes`](../linear-agent-writes/SKILL.md) β