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.
87%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
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.
.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.
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.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.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.
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 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:
thought with what you are doing, and
externalUrls set to View the run with $TESSL_LAUNCH_RUN_URL when it is
set;elicitation whose body is the question;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.
For each repository the issue needs:
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.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.A PR from tessl/<id> that has merged finishes its repository's part, unless
the issue now needs more there.
Read the record and take the first situation that applies.
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.
The issue is already done. Every item of What done looks like holds. Stop and say so in the run output.
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.
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).
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.
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.
<!-- tessl-factory -->. That marker is
how a later round tells your comments from a person's.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.--force-with-lease=<branch>:<head you read>.Do each of these in the clone of the repository it concerns.
<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.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> 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.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.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.AGENTS.md, CLAUDE.md, README.md
or the team's rules say for the project you changed. Run them again after
merging the base.git merge --no-ff origin/<base>,
resolve, push, test.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.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.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.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.