Skip to content

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

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.md
index 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 outside
diff --git a/.agents/skills/langfuse-onboarding/SKILL.md b/.agents/skills/langfuse-onboarding/SKILL.md
index f476e73d41..55e2a0d6ab 100644
--- a/.agents/skills/langfuse-onboarding/SKILL.md
+++ b/.agents/skills/langfuse-onboarding/SKILL.md
@@ -1,20 +1,27 @@
---
name: langfuse-onboarding
description: |
- 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 are
app 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 it
goes 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 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
+## 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.md
index 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 tracker
rather than from memory: which projects you lead, which owe an update before
Monday 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 no
answer 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 been
burned by exactly that. `me.md` holds only the durable half: name, role, and the
focus they described in their own words.
-## The five checks
+## The six checks
Run them, then report as **a short ranked list with the reason attached**, not a
status 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 not
running. 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 decision
Triage normally gets a decision within one working day. Check the triage state on
your teams, and your own inbox-shaped work: things assigned to you that you have
not moved, and requests routed to you as a feature owner.
-### 4. Your open bugs
+### 5. Your open bugs
A 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 one
that slips.
-### 5. Lifecycle compliance, but only where it changes what you do
+### 6. Lifecycle compliance, but only where it changes what you do
Report 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 than
a per-project table, and the agreement is explicit that this system stays
lightweight.
+## 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 back
Every write follows [`linear-agent-writes`](../linear-agent-writes/SKILL.md) β€”