linear-agent-writes · diff
git:20260910.1acfa5d to git:20260911.a85d3ec
84 added, 42 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: linear-agent-writes
description: |
The org policy for what an agent may write to Linear, and how it must be
marked. Read this before creating a ticket, editing a description, or
commenting on a ticket as an agent — "file this in Linear", "comment on the
ticket", "create a subticket", "write the handover". Default those writes
to a short human description; expand with research only when asked. Also
covers the required Linear connection and what to do when there isn't one.
---
# 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 repo
instructions point here; none of them restate the rules. If another document
disagrees with this one, this one wins — fix the other document.
It is maintainer-facing: it binds anyone whose agent can reach the Langfuse issue
tracker, 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
Ordinary Linear writes are short. A new ticket or subticket is a title and
two to four sentences: what to do, and why in one line if it is not obvious.
Comments stay to the thing the watcher needs today.
Expand — research, file lists — only when they ask ("expand this", "add
context"). Do not invent an implementation-ready brief.
Wrong (they said "create a subticket"): six fields, entry-point files, a
stack position, a research essay.
Right: "Warn sunset event types on POST /ingestion request body. Fern still
lists 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 updates
Linear used to be human-only for agents, and every skill that touched it had to
stop and present a review table first. That cost more than it protected: the
expensive thinking in an agent session — the decisions, the reversals, the traps
— evaporated when the session ended, because the one place it could have been
written 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 shapes
They compose. Stamp **every** shape you used, so the labels read as a log of what
agents 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.
A comment notifies every watcher. Use one when someone genuinely needs to see
something today: a blocker, a question that stops the work, a finding that
changes 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 comment
sprays every watcher's inbox for something nobody needs to read today, and inbox
spam 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 append
Label `AI edited`. Add a **clearly separated agent block**; never rewrite,
reflow, or "improve" the human's prose around it.
This is the durable half of the practice. `AI edited` is the filter a future
session uses to find prior agent reasoning, so the label is not decoration — it
is 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 the
description, and why an attachment is not optional are
[`linear-context-handover`](../linear-context-handover/SKILL.md).
### 3. Create a ticket — a subticket freely, a top-level one after a yes
Label `AI created`. Say in the description that an agent created it and who it is
for. Default length is the short human ticket in *Default length* above.
**A subticket of an existing ticket needs no permission.** File the short
ticket. "Create a subticket" / "file this" / "add a ticket" is this shape.
**A ticket with no parent needs the human's yes first** — a top-level issue, or
one filed straight into a project. Show the title and the short description you
intend to file, get an explicit go-ahead, then **create it yourself**; do not
hand 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
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 ticket
A 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
The practice only works if your agent can actually reach Linear — reading history
before you start, writing the handover when you finish. In this repo the server is
already declared for you: `.agents/config.json` lists `linear` as an HTTP MCP
server, and `scripts/agents/sync-agent-shims.mjs` projects it into each tool's
config 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
If the Linear tools are absent, **do not silently skip the reconstruct or the
handover.** Silent non-compliance is indistinguishable from compliance, and that
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, the
subtickets);
- and then **the content itself**, ready to paste — the handover block, the
subticket bodies, the comment.
The work is not lost that way, and the missing configuration becomes visible
instead of invisible.
```text
No Linear access in this environment, so the handover was not written.
Here is the block that should go on the parent ticket's description
(label it `AI edited`):
<the handover block>
```
Never guess at a ticket's history from the code alone and present it as
recovered context. Say the history could not be read.
## Marking in the text, not only the label
The Linear MCP writes as the **authenticated human**, not as a bot. An unmarked
agent block reads as that person's own words to everyone who sees it. The label
is 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.