CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

tessl/factory-setup

Set up, understand, and change a Tessl factory on a repository: pick automations that fit how you work, such as shipping tickets as pull requests, answering reviews and fixing checks on those pull requests, code review, and scheduled jobs; prepare the repository for agents; write issues for the factory to build; then see what the factory has done, find out why a run failed or never started, and change or extend it.

Quality

91%

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/factory-setup/

name:
factory-setup
description:
Set up a Tessl factory on a repository: Tessl agents that turn tickets into pull requests, answer reviews and fix checks on them, and review every pull request. Use when someone wants Tessl agents to do work in their repo, or asks what a factory is. To explain or change a factory that exists, use the understand-factory and change-factory skills.

Factory setup

A factory is a set of automations on a repository. Each one is a rule: when something happens (a ticket is handed to Tessl, a pull request gets a review), a Tessl agent runs in the cloud and does one job.

Your job is to set up the same factory the Tessl web app sets up, without asking the person to make choices, then offer the extras only an agent that can read the repository can recommend.

What done looks like

Setup is done when the repository has a Tessl project; Ticket to PR is on; Code Review is on, or the person chose not to install its app; the person has had the "Your factory is live." message, the first-ticket offer and the suggested next steps; and every step they accepted is done.

Read where things stand, take the first situation that applies, do its next action, and look again.

  1. The person asked what a factory is, what theirs does, or to change it. Explain in a few sentences, or use understand-factory or change-factory. Set nothing up.
  2. The CLI is obsolete or not logged in. For an obsolete CLI follow Check the Tessl CLI. When tessl whoami fails, ask the person to run tessl login and wait. A newer CLI build is not a reason to stop: mention tessl cli update once in the live message.
  3. The folder is not a GitHub repository. Say automations run on a GitHub repository and ask which one to use.
  4. No project for this repository, or you do not know its org. Find or create it.
  5. The Tessl App cannot reach the repository. Get it there.
  6. The repository is empty on GitHub, or Issues is off and the factory would take GitHub issues. Deal with it.
  7. The repository is public or its visibility is unknown, and the person has not confirmed the defaults. Confirm them.
  8. Ticket to PR is not on. Turn it on.
  9. Code Review is not on, and the person has not said to skip it. Turn it on.
  10. The live message has not been sent. Send it.
  11. The first ticket has not been offered. Offer it.
  12. The suggested next steps have not been sent. Send them.
  13. The person accepted a next step that is not done. Do it, as its step says.

If what you find fits none of these, say what you found and ask.

Invariants

Talking to the person

  1. Ask nothing that a default answers. The only things to ask for are what only the person can do (log in, install an app), which org or workspace when the rules below leave more than one, the first ticket, and which suggested next steps to take.
  2. Use plain words; see Plain words. Never show a generated identifier, such as a workspace name that starts with ws-; with one workspace, say "your Tessl workspace".
  3. Give a browser link whenever you create or check something the person may want to see, from the command's webUrl (Browser links), as a plain URL. Add onboarding=true to every link on the Tessl web app's host: ?onboarding=true, or &onboarding=true when the link already has a query. Links to other sites, such as GitHub, stay as they are.
  4. Say what you have checked and what you have not. Never say the factory is running until its Loops are listed, or that a run worked until you have seen what it did.
  5. After a side request, answer it, then go back to the situation you were on.

Changes

  1. Change nothing in the repository before the factory is live: no tessl init, no tessl.json, no commit. Afterwards, change it only for an extra the person accepted, and ask before each push and merge.
  2. Never set up an automation the project already has (What is there already), and never change a Code Review setting on a repository whose review is already on.

Region

Keep setup in the person's Tessl region; follow Regional setup before login, project discovery, or integration checks. In the EU, use GitHub issues and skip every Linear check and offer.

Commands

  1. When a command is refused, by the agent's permission system or by GitHub, do not retry or work around it: ask the person to run it.
  2. Every command acts on the org and workspace this setup chose: pass --org <org id> to tessl code repo and --workspace <workspace> to tessl integrations show and tessl launch models, so none falls back to a local or default one.
  3. A person watches this session, and a command that exits with an error reads as the setup going wrong, even when it only answered "not there yet". Run each command in a form that gives a clean, non-error response, and read the answer from what it prints: a list over a view of one thing (tessl code repo list, not tessl code repo view, until the repository is listed), a file check before a command that needs the file (tessl.json before tessl project repair), and what an earlier step told you over asking again. The commands below are written in that form; keep to them. When a command still exits with an error, handle it from what it printed, take the situation that applies, and tell the person the next step, not the error. Something they have to do themselves, such as tessl login, is a next step, not an error.

Environment facts

  • Ticket to PR is four automations set up in Tessl in one call: "ship tickets" (Implement ticket), "answer reviews and fix checks" (Shepherd PR), "follow ticket changes" and "fix merge conflicts" (Merge conflict sweep). On a public repository it is the first three, as Public repositories says. They are on as soon as the call returns, with cloud environments Tessl creates. To change what they do, they move into the repository's tessl.json, with any Learn from past work Loops, in one pull request, and change there. Set up automations in Tessl has the calls.
  • "Ship tickets" starts a run as soon as its event arrives; "answer reviews and fix checks" waits 90 seconds first, so that events close together fold into one run. Each run uses Tessl credits. tessl org list --json gives each org's usage.credits.state (ok, over_budget, unlimited, or unavailable) and, for ok and over_budget, usage.credits.remaining and usage.credits.blocked, which is true when runs cannot start; usage is null when it could not be read.
  • Two GitHub Apps: the Tessl App lets agents comment, push branches and open pull requests; Tessl Reviewer runs Code Review.
  • tessl api <path> calls the Tessl API with the person's login; send a body with --input <file>.
  • gh repo view --json nameWithOwner,isFork,parent,visibility gives the repository, once git remote -v shows a GitHub remote (situation 3 otherwise). A fork gets its own factory, not its parent's.

Judgment

  • While you set up, read the repository for the first ticket and suggested next steps: package manifests, lockfiles and CI install steps (what a cloud run needs to build and test), the services its tests need, its agent context (AGENTS.md, CLAUDE.md), and its review history. Use what you find when offering the first ticket, and save the other recommendations for the suggested next steps.
  • A person who wants something other than Ticket to PR, such as a schedule or a trigger of their own, gets the factory first, then change-factory for the rest.

The project

  1. The org. From tessl org list --json: the only one; otherwise the one that already has a project for this repository; otherwise the one whose Tessl App can see the repository (/v1/orgs/<org id>/integrations, then /v1/orgs/<org id>/integrations/<integration id>/repositories?scope=account&q=<repo>); otherwise ask which, by name. When its usage.credits.blocked is true, say once that runs will not start until it has credits, and carry on.
  2. The project. List the org's projects with tessl api '/v1/orgs/<org id>/projects?filter[q]=<owner>/<repo>' and take the one whose sourceUri names <owner>/<repo> on github.com and whose repoSubpath is empty. Projects store the same repository in several spellings (github.com/<owner>/<repo>, https://github.com/<owner>/<repo>, www., .git, any case), so compare case-insensitively after dropping a leading https:// or http://, www. and a trailing .git. filter[q] also matches names and other repositories, so match those two fields yourself. When more than one project matches, take the one whose sourceUri is exactly github.com/<owner>/<repo>; otherwise the one whose loopCount is above 0; otherwise ask which, by name.
  3. Otherwise create it in the org's workspace (tessl api /v1/orgs/<org id>/workspaces: the only one, or the one the person names) with tessl api -X POST /v1/projects --input <file> and {"workspaceId": "<workspace id>", "name": "<repo>", "sourceType": "git", "sourceUri": "github.com/<owner>/<repo>", "repoSubpath": ""}. When the name is taken, add -2, -3 and so on.
  4. Keep the project's id and give the person its link: the web app's /go/projects/<project id>, on the host the other commands' webUrl values use (such as https://tessl.io), saying it is the repository's home in Tessl, where its automations and runs will show. The create call returns no link. A refusal about permissions: check permissions and ask for exactly what is missing.

The Tessl App

tessl api /experimental/projects/<project id>/factory/helper-access gives data.attributes.status: accessible, missing, or unavailable (Tessl could not check; try again shortly). When it is missing, give one link from tessl integrations show github-app-agent --json, as Browser links says, and say it asks for read and write access so agents can comment, push branches and open pull requests. Wait until the person says it is done, then go on to Ticket to PR: this check keeps answering missing for up to five minutes after access is granted, and the Ticket to PR call refuses with "Connect the Tessl App to this repository" while access is really missing. When it refuses, say the access can take a few minutes to show, and try again.

Empty repositories and Issues off

Check both before Ticket to PR is on, when starting and when resuming.

  • Empty. gh repo view --json isEmpty gives true when nothing has been pushed to GitHub; commits only in the local checkout do not count. Say "A factory needs existing code to work on. Push a first commit to GitHub, then run setup again." and stop. Turn nothing on and do not push for them.
  • Issues off. Only when the issue source Ticket to PR would use is GitHub issues; with Linear, say nothing about Issues. Read meta.issuesEnabled from tessl api /experimental/projects/<project id>/factory/implement/github-issues. When it is false, say "The factory can't pick up GitHub issues here. Turn Issues on, or use Linear for issues." and offer to turn Issues on for them. Change nothing without their yes in this session. With a yes, run gh api -X PATCH repos/<owner>/<repo> -F has_issues=true and check again. When they say no, gh is not logged in, or the call is refused, give https://github.com/<owner>/<repo>/settings and wait until they say it is done, then check again.
  • When either check gives no clear answer (issuesEnabled is null, or the command fails), say you could not check it and go on.

Public repositories

Read visibility from gh repo view before the first call that sets up Ticket to PR, when starting and when resuming. A private or internal repository skips this section. For PUBLIC, or when the visibility cannot be read (say it is unknown; never assume private), say before activating anything:

  • Setup turns on three automations at once. Anyone who can add the label to an issue, which needs triage access, can start a run that changes code and uses Tessl credits. On Tessl's pull requests and issues, comments and reviews start runs only from the people on a list. It starts as everyone with the maintain or admin role on the repository, and the person can add or remove GitHub usernames before setup runs. Someone added after setup starts nothing until the automations move into tessl.json.
  • Check results do not start runs, so the factory does not fix a failing check on its own, and Code Review's reviews start nothing. "Fix merge conflicts" is not set up.
  • Read https://docs.tessl.io/automations/factory-on-public-repositories first.
  • Optional: if you do not expect outside collaboration, GitHub's temporary interaction limits can restrict who comments. This also limits real collaborators. Do not apply them; the person does, in GitHub, if they want to.

Then ask "Continue with these defaults?" and wait for an explicit yes. Without one, set nothing up and say how to resume.

Ticket to PR

Turn it on as Ticket to PR says. The issue source in the EU is GitHub issues with the tessl label. In the US, use Linear when its connection has a team routed to this project (Linear prerequisites); otherwise use GitHub issues with the tessl label. Do not ask. When the project already takes tickets, setup refuses; say which Loop does and stop. Confirm the Loops setup reported (four, or three on a public repository) are listed and active.

Code Review

tessl code repo list --org <org id> --json lists the repositories the Tessl Reviewer app can see; the repository is the entry in repositories whose fullName is <owner/repo>, compared ignoring case. When two entries share the name, use the one on the owner's account, and pass its id instead of the name below. When its review.enabled is true, leave every setting as it is. When there is no entry, the Tessl Reviewer app cannot see the repository: give the webUrl from tessl integrations show github-app-code-review --json, say it reviews every pull request, including Tessl's, and that the person can say to skip it; wait until they say it is done or to skip, then list again. An entry whose attentionReason is not null is one the app cannot write to: give its installation.manageUrl to fix the access, and wait the same way. Then turn it on to review every push: tessl code repo update <owner/repo> --org <org id> --review-enabled --review-trigger every-push, and confirm with tessl code repo view <owner/repo> --org <org id> --json. A refusal, of the list or the update, needs an organization admin; say so and carry on without it.

It's live

One message that starts "Your factory is live.":

  • What is on, what starts each, and the project's Loops link (the project link with /loops added), using the issue source the Ticket to PR plan reported (issueSource): "Add the <label> label to an issue and Tessl opens a pull request for it", or for Linear, "Delegate an issue to Tessl and move it to an unstarted status, usually Todo. An issue in Backlog or Triage will not trigger action by the factory until you move it to an unstarted status". An unstarted status makes the issue eligible to start; an unanswered Tessl question or an open blocker still holds it.
  • How to stop each: removing that label or taking the issue back stops one ticket; pausing a Loop on that page prevents automatic starts, but runs already active continue and manual runs stay possible.
  • The org's remaining credits, from usage.credits.remaining, when it has that field.
  • That their agent can later explain what the factory did (understand-factory) or change it (change-factory).
  • That Tessl manages these automations: to change what they do, such as adding "run the linter before you push", their agent moves them into tessl.json in the repository with one pull request, and from then on they change them there.

The first ticket

Offer it as The first ticket says: a few of the open issues the web would offer, and a useful starter issue you propose from the checked-out repository. Giving Tessl a ticket starts a run that uses credits, so this is the one choice in setup; when the person declines, say how to give it one later and go on. When they pick one, follow its run as Testing the factory says, and send the suggested next steps while it runs. Report only what you saw: the run starting, its pull request, or what stopped it.

Suggested next steps

One message under the heading "Suggested next steps". Open with one line: the factory is doing its job, and these steps make it better at this repository. Then at most three steps as peers, each ending with what it gains the person, not with a caveat. Learn from past work always comes first; suggest the others only when the evidence from the repository supports them, and give that evidence:

  • Learn from past work: each week Tessl reads the factory's runs and the pull requests' reviews, records the problems that keep coming back as findings, and turns them into tickets the factory builds. If accepted, turn on all four Loops with the suggested environment for tickets, as Learn from past work says.
  • A setup script for cloud runs, when building or testing needs tools, dependencies or services, such as a lockfile to install from or a database the tests use. Name what you found and what .tessl/cloud-launch-setup.sh would install, so the next run builds and tests like CI does. If accepted, write it as the setup hook reference says, on a branch with a pull request, check it on a cloud machine before the merge as Check the setup hook in the cloud says, never by running it here, and ask before pushing and merging.
  • prepare-repo, when agent context is thin or missing: it reads the repository's review history, CI failures and fix commits, and turns what it finds into agent context, checks and review rules, so the next pull request starts from what the first one had to work out (prepare-repo). It changes nothing until the person picks what to keep.
  • Code Review, when it ended up off: say that Tessl did not review the pull request it opened, because review is off for this repository, and that with it on every pull request gets findings and the agent answering reviews fixes them. Say nothing about whether anyone else reviewed it. Turn it on as Code Review says, or point to Code reviews in the web app when that was refused.

End with one question that assumes a start: which step to begin with, and which one you would begin with now. Do not call the steps optional, and do not offer "none"; a person who wants to stop says so, and then leave it. Add one line on what else they can ask for later, such as other automations from the starters.

Plain words

Say the plain words. When a command, link or screen shows a Tessl term, say what it means in one line, once, at that point, and only when it bears on what the person does next. Plain words has each line.

README.md

tile.json