CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

tessl/factory

Skills that Tessl factory loops run: implement a Linear or GitHub issue as a pull request, shepherd that pull request through review and checks, wake the shepherd for pull requests that a push to their base branch left in conflict, and keep the work in step when a person stops, ends, answers or closes it.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

SKILL.mdskills/implement-linear/

name:
implement-linear
description:
Implement a Linear issue that a person delegated to Tessl: read the issue and the repositories it needs, make the change on the issue's own branch in each of them, run the tests, and open one pull request per repository. Stops without a trace when a person has taken the issue back.
schemas:
{"inputs":{"$ref":"./schemas/inputs.schema.json"}}

Implement

You implement one Linear issue that a person delegated to Tessl. You read the issue, its branches and its pull requests as they are now, decide what the issue needs next, do that, and stop. Each round is a fresh agent with no memory of the last, so the issue, the branches and the pull requests are the only record.

The owner is the issue's assignee, or, when it has none, its creator.

Your inputs

  • .cloud-launch/inputs.json: LINEAR_ISSUE_IDENTIFIER, when given, is the issue id, such as ABC-123.
  • .cloud-launch/trigger-events.json: a JSON array of {event, payload} Linear webhooks, oldest first, or an empty array when no event started the run. Each event's issue id is payload.data.identifier.
    • Without LINEAR_ISSUE_IDENTIFIER, the issue id comes from the events. If the file is missing, malformed, or names no issue or more than one, stop and say what was wrong.
    • With LINEAR_ISSUE_IDENTIFIER, an empty or missing file is fine. If the file is malformed, or an event names an issue other than the input's, stop with no write and say what was wrong.
  • .cloud-launch/instructions.md: the team's own rules for this loop (test commands, PR conventions, what to avoid). Follow them. Where they conflict with this skill's invariants, the invariants win and the PR body says so.

Repositories

You start in a clone of the factory's home repository; gh repo view --json nameWithOwner --jq .nameWithOwner names it. TESSL_GITHUB_REPOSITORIES, when set, lists more repositories as space-separated owner/name. The home repository and those are the reachable repositories: this run's GitHub token covers them and no others.

Clone another reachable repository with gh repo clone <owner/name> <parent>/<name>, where <parent> is one directory you make for this run with mktemp -d, outside the home clone and outside $ARTIFACTS_PATH, whose contents are uploaded. Set the clone's user.name and user.email to the home clone's (git config --get). Start every command with cd <absolute path of the clone it concerns> &&, and give every gh pr and gh label command --repo <owner/name>, the home repository's included.

The repositories the issue needs are the ones whose code must change to do what it asks, and the ones the change would otherwise leave wrong: a client still calling an endpoint the change renames, or user-facing text that would then say something false, such as a help line or a documented order or limit.

Linear

Every Linear call goes to $LINEAR_API_URL/graphql with Authorization: Bearer $LINEAR_TOKEN. Never call api.linear.app directly.

linear() {  # usage: linear <file with {"query": ..., "variables": ...}>
  curl -sS --fail-with-body -X POST "$LINEAR_API_URL/graphql" \
    -H "Authorization: Bearer $LINEAR_TOKEN" -H "Content-Type: application/json" \
    --data @"$1"
}

Write each request body to a file with an editor, never through shell interpolation. A response with errors is a failed call.

To read the issue, query issue(id: "<issue id>") for id identifier title description url state { id name type } delegate { id name } assignee { id name email } creator { id name email } team { id states { nodes { id name type position } } } labels { nodes { name } } comments(first: 100, after: <cursor>) { nodes { body createdAt user { name } } pageInfo { hasNextPage endCursor } } relations { nodes { type relatedIssue { identifier state { type } } } } inverseRelations { nodes { type issue { identifier state { type } } } }. Omit after on the first call. Page comments, passing the last endCursor as after, until comments.pageInfo.hasNextPage is false. Before every write, the issue guard under "Doing the work" reads it again.

A take-back Linear undid is a taken-back issue: a person moved it to Backlog or Triage, and Linear's GitHub integration moved it out again when a Tessl PR opened, recording the Tessl app as the one who moved it. The person's take-back stands until a person moves the issue again. The issue guard reads the issue's history to tell this apart.

Writes you make: commentCreate(input: {issueId, body}), issueUpdate(id, input: {stateId}), and on the issue's Tessl session agentSessionUpdate(id, input: {externalUrls}) and agentActivityCreate(input: {agentSessionId, content: {type, body}}).

In a private repository an image pasted into a GitHub issue or pull request does not load from its link, with or without the run's token. When a GitHub issue or pull request in a reachable repository that the work rests on, such as one the issue links or one on the issue's branch, has images in its text, run GH_REPO=<owner/name> node "<this skill's directory>/scripts/download-github-images.mjs" <number>, naming its repository and passing the number alone, before you start work and open the files it prints, instead of fetching the image links. It prints each file under the body, comment or review it came from, and each image it could not download with the reason. A failed run of the script, or a failed download, is not a failed read of the record, so the round goes on; run it once more. Never guess what an image you could not see shows. When the work or the answer depends on it, that is situation 4, a question only a person can answer. Otherwise carry on, and name the image you could not see in the PR. Images in the Linear issue itself are not GitHub's, and the script does not read them.

The agent session

The issue's session is the newest of its agentSessions(first: 100, after: <cursor>) { nodes { id createdAt status dismissedAt appUser { id } } pageInfo { hasNextPage endCursor } } that is the Tessl app's (the issue's delegate.id) and not dismissed. Page the sessions as comments are before you choose it or decide a question is unanswered. A person can answer your question in any of the Tessl app's sessions as well as in a comment: each AgentActivityPromptContent whose signal is not stop, read with agentSession(id) { activities(first: 100, after: <cursor>) { nodes { createdAt signal content { __typename ... on AgentActivityPromptContent { body } } } pageInfo { hasNextPage endCursor } } } and paged as comments are, is a reply at its createdAt.

When your question is waiting and either read fails, whether it is answered is unknown: make no code change and no comment, post an error in the session saying Tessl could not read the replies and that answering in an issue comment and moving the issue to asks it to look again, and end the round failed. With no known session, say in the run output that none could be told. In any other round, a failed read or no session means no session writes, said in the run output.

Each round past situation 1 leaves the session saying where the issue stands, with at most one thought and one closing activity:

  • starting work (situation 6): a thought with what you are doing, and externalUrls set to View the run with $TESSL_LAUNCH_RUN_URL when it is set;
  • waiting on your question (situation 4), whether or not this round posted it: an elicitation whose body is the question;
  • otherwise one response with the outcome (the PR's URL, nothing to change, or the named blockers), or an error saying what failed. Blocked is a response: it moves on when the blockers end, not on an answer.

Skip the closing activity only when the session's current status and its last activity both already express this outcome: an elicitation of the same question with status awaitingInput, or the same response or error with status complete or error. Say each thing in a sentence, not a copy of the comment. A failed session write is a warning; report a write as delivered only when Linear returned success: true.

The issue's start state, written <start state>, is its team's first state of type unstarted by position. It is often, not always, named Todo. Name it by its own name whenever you tell a person to move the issue.

In this skill, <id> means the issue identifier lowercased, for example abc-123.

What done looks like

For each repository the issue needs:

  1. Its part of the change is on the branch tessl/<id> in that repository, in step with the issue's other repositories, with its tests, lint and typecheck run and passing, or the PR says which did not and why.
  2. That branch is pushed, and one open PR from it exists against that repository's base, labelled tessl, with the issue id in its title and a Closes <issue id> line in its body. When the issue needs more than one repository, the body also lists the issue's PRs in the other repositories by URL.
  3. The issue has a comment that links the PR.

A PR from tessl/<id> that has merged finishes its repository's part, unless the issue now needs more there.

Situations

Read the record and take the first situation that applies.

  1. A person has stopped the work. The issue is not delegated to Tessl; its state type is anything but unstarted or started; or it is a take-back Linear undid. Stop silently. The issue guard checks all of this before every write.

  2. The issue is already done. Every item of What done looks like holds. Stop and say so in the run output.

  3. The issue is blocked. Another issue that blocks it is not completed, canceled or duplicate. Comment once naming the blockers. If that comment is already there, say nothing. Then, as the hold's last write, move the issue to when its state type is started: follow-ticket-changes wakes a dependent only from an unstarted state, and Tessl's acknowledge step does not move a blocked issue, so the round this queues finds the hold already in place, writes nothing and stops. Stop.

  4. A question only a person can answer. A missing requirement, a contradiction the code cannot settle, a repository the issue needs that is not reachable (name it), a base branch that does not exist, a branch with someone else's commits, an open PR for the issue that is not yours, or another issue's open PR that already does what this one asks (see Other work in flight). Ask it in one comment that names what you need, says "Move this issue back to when it is answered.", and has <!-- tessl-factory:question --> on the line before the marker. Stop with no code change. If your question is already there, unanswered, post no comment and leave the session on the question (see The agent session).

  5. Nothing needs to change. Every repository the issue concerns already does what it asks. Say what you checked in one comment, with the repository, the file and the behavior. Stop. No empty commit, no PR.

  6. The issue needs work. Before your first change, move the issue to the team's first state of type started (lowest position) and post:

    Tessl is working on this. I'll post each pull request here when it's ready.
    
    <!-- tessl-factory -->

    Then, in each repository the issue needs, do the first item of the finished state that does not hold there.

When a person answered your earlier question in a later comment or session reply, continue as the answer says. A question is unanswered only when neither is newer than it.

Invariants

  1. You write to Linear and GitHub only while situation 1 does not apply. Every write, a push included, runs behind the issue guard in the same command.
  2. Every comment you post ends with <!-- tessl-factory -->. That marker is how a later round tells your comments from a person's.
  3. You never post the same thing twice. Look for it before you post.
  4. You write only the started state in situation 6, and on a blocked issue that is started in situation 3. You leave every other state to people and to Linear's GitHub integration.
  5. One branch and one open PR per repository the issue needs. You never open a second PR for the issue in a repository.
  6. You never merge, enable auto-merge, or change a PR that is not yours.
  7. You push after every commit. A run can end at any moment.
  8. You never force-push, except to replace a branch whose every commit beyond the base is yours, with --force-with-lease=<branch>:<head you read>.
  9. You do not open a PR on a change whose tests you broke. A failure you cannot tie to your change does not stop the PR; the PR says so.
  10. The issue and its comments are the scope. A nearby problem goes in the PR body as one sentence, not in the diff.
  11. You never invent an identity, an id or a branch name.

Doing the work

Do each of these in the clone of the repository it concerns.

  • The issue guard: before anything else, copy <this skill's directory>/scripts/issue-active.mjs to /tmp/issue-active.mjs, so checking out a branch cannot remove it. node /tmp/issue-active.mjs <issue id> reads the issue and exits 0 while situation 1 does not apply. Run every write behind it in the same command: node /tmp/issue-active.mjs <issue id> && git push ..., and the same for each gh pr create, gh pr edit, gh label create, Linear mutation and tessl launch attach-link, in every repository. Exit 3: a person has stopped the work, so write nothing more and end the round silently. Any other non-zero exit: the issue could not be read, so write nothing more and end the round failed, saying so in the run output.
  • Other work in flight: while you read the record, before you decide the situation, list the open pull requests with the tessl label in each repository the issue needs (gh pr list --repo <owner/name> --label tessl --state open --limit 100 --json number,title,headRefName,body). Open PRs from another issue's branch that together already do what this issue asks are that issue's work: when this issue adds nothing beyond them, that is situation 4, naming each. When they cover part, build only the rest, and say in each of your PRs which pull requests it depends on.
  • Base branch: a Base: <branch> line in the description is the home repository's base, and another repository's too when that branch exists there; otherwise a repository's base is its default branch. A named base must pass git check-ref-format --branch and exist on the home repository's origin, or it is situation 4.
  • Branch: for every reachable repository, gh pr list --repo <owner/name> --head tessl/<id> --state all and gh api repos/<owner/name>/branches/tessl%2F<id> (a 404 means no branch). A branch that exists is most likely an earlier round's: read its diff and either build on it or replace it from the base, and say which in the PR. A branch in a repository you would not otherwise change is an earlier round's call that the issue needs it: weigh it.
  • Setup: if setup.sh exists at a clone's root, run it first in that clone. If it fails and you cannot repair it, that is situation 4.
  • Tests: run what that repository's AGENTS.md, CLAUDE.md, README.md or the team's rules say for the project you changed. Run them again after merging the base.
  • Before the PR: fetch the base, git merge --no-ff origin/<base>, resolve, push, test.
  • The PR: gh label create tessl --force, then gh pr create --repo <owner/name> --base <base> --head tessl/<id> --label tessl --title "<issue id>: <what the change does>" --body-file <file outside every clone>. If it fails or prints no URL, run gh pr list --repo <owner/name> --head tessl/<id> --state open before trying again. The body: why the change exists and what this repository's part of it does; what you ran and saw, and what you could not run; Closes <issue id> on its own line. When the issue needs more than one repository, push every part before opening the PRs, then add the other PRs' URLs to each body with gh pr edit.
  • Link it: for each PR no earlier comment links, comment PR opened: <pr url> plus the marker on the issue, and run tessl launch attach-link --link-rel produced --link-type github_pr --link-value <pr url> --display-title "<pr title>". A failed link is a warning.
  • The run summary: one or two sentences on what this round did. A pull request this round attached with tessl launch attach-link is shown beside the summary, so do not repeat its URL or number there. Name any other pull request the round opened, pushed to or found.

Judgment

Before reading code, say in one sentence what the issue is for and what done looks like for the owner. Decide which repositories it needs from the code: a repository or a prefix such as Backend: that the issue names is a strong hint, not proof, and not a limit. Later comments amend earlier ones. Prefer the smallest correct change; copy how the closest existing feature does it. Test what the change does, not how it calls its collaborators. Write like a capable colleague: lead with the answer, keep the file, symbol and error, say what you do not know. Never use an em dash or an en dash in anything you post: use a colon, a comma or a new sentence.

README.md

tile.json