Skip to main content

​
Linear workflow for agent sessions

Every piece of work an agent does in this repo is tracked in Linear, from the moment the session starts until the PR merges. Two skills drive it:
  • /new-task (.agents/skills/new-task/SKILL.md) runs at the start of a working session. It finds or creates the ticket and moves it to In Progress. At PR time it links the PR and adds a short summary of what shipped.
  • /new-project (.agents/skills/new-project/SKILL.md) plans a larger piece of work with the user, creates the Linear project, then creates its tasks so each one can later be started with /new-task.

​
Why the ticket comes first

Linear stamps startedAt when an issue first moves to a started state (In Progress) and completedAt when it reaches Done. The time between the two is how we measure how long a task took. If the ticket is only created, or only moved to In Progress, when the PR opens, that measurement is meaningless. CFO-8066 shows 20 minutes from start to done because its clock started at PR time. Creating the ticket and moving it to In Progress at the start of the session makes the number real. It is wall-clock time, so it includes nights and time waiting on review. Read it as “how long the task was open”, not as hours of effort.

​
Setup (once per person)

The skills use the Linear MCP server, which signs in as you. Tickets you create show you as the creator, and “assign to me” means you.
Then start claude, run /mcp, choose linear and approve the sign-in in the browser. Start a new session afterwards, because a session that was open when the server was added never sees it. Other agents can add the same URL as a remote MCP server. The tool names depend on the name you gave the server (mcp__linear__* with the command above) and on the server version. Look for the tools that list, get and create or save issues, projects, labels and statuses. If the Linear MCP is not connected, the skills stop and point here. They do not fall back to the raw API with someone else’s key, because tickets created that way show the key’s owner as the creator.

​
Conventions

Other labels (source:*, tier:*, platform labels such as iOS) are added by the systems and people that own them. Agents only add the category label.

​
Which ticket to use

Reuse an existing ticket whenever one fits. A new ticket is only for work that has none. A ticket already exists when:
  • the user names one (CFO-1234), or the branch name contains cfo-NNNN;
  • the work started from a user bug report, a Silvia-filed ticket or a Sentry-linked ticket;
  • it is a companion PR (for example in CFO-Silvia/skills) to a PR that already has one;
  • a search of open CFO tickets finds one describing the same work.

​
Writing tickets

Tickets are read by the whole team, including people who are not engineers.
  • The title says what will change, specifically: “Stop the iPhone chat from overflowing on wide tables”, not “Fix chat bug”.
  • The description covers what, why and scope in plain language. Add the root cause once it is known.
  • Never paste secrets, tokens or user personal data (emails, names, account numbers, balances). Refer to a user by their internal id if needed.
  • At PR time, add an Outcome section and keep the original description intact.

​
Guardrails

  • Agents may search, read, create and update tickets and projects that the current session owns or was asked to work on.
  • Deleting, archiving, cancelling, or editing tickets that belong to other people needs an explicit ask from the user in that session.
  • Creating workspace-level things (labels, teams, workflow states, integrations) is a human action in Linear settings, not an agent action.