Change the factory

Make the change the person asks for to the factory on this repository, or suggest what to add, and leave the factory working afterwards. Every change to tessl.json goes through a branch and a pull request, and reaches the automations only once it is on the default branch.

What done looks like

• The person agreed to the change in plain words before you made it.
• A change to tessl.json or the hook is on the default branch, or in an open pull request they can merge, and you gave them its link. A setting change shows its new value in the matching view command.
• After a merge, the automations match the new tessl.json: you checked the Loops, as below.
• You told them what is now different, what it costs, and how to undo it.

Invariants

1. Ask before each write: the branch push, the pull request, a Code Review setting, an environment change. Agreeing to one is not agreeing to the next.
2. Change only what the person named. Keep every other key in tessl.json, every other trigger, and every stored environment key as it is.
3. tessl doctor --automations reports the configuration valid before you push. When the setup hook changed, the cloud check, which runs on the pushed branch, has passed before the change is merged.
4. Before a change that costs more credits, such as reviewing every push or a larger model, say so.
5. Never print, ask for, or handle the value of a secret.

The references you build on

The factory-setup skill's references hold the starters, trigger entries, setup-hook guidance, cloud check, Loops check, and skill edits this skill uses: starters, triggers, setup hook, cloud check, confirm the Loops, and editing a factory skill. A factory set up with an older version keeps the trigger filters it was written with: when one of its triggers lacks a filter that the triggers reference now has, such as the repository ID or an open-state check, say so and offer to add it.

1. Read the factory

Do what understand-factory step 1 does: the linked project (tessl project repair --json), the automations in tessl.json, and their Loops (tessl schedule list --project-id <project id> --all --json). The project's organization is environment.attributes.orgId in tessl environment view <environment> --json, for any environment an action names; pass it as --org to every tessl code repo command. Run tessl launch models --json from the repository root, so it reads this repository's workspace.

A change to tessl.json or the setup hook goes on a branch. Check git status first. When the uncommitted changes are the person's own work, ask them to commit or set them aside. When they are factory configuration the person wants kept, such as a plugin they just installed, ask whether to include them in this change. Find the default branch with gh repo view --json defaultBranchRef --jq .defaultBranchRef.name, fetch it, and start a new branch from it named for the change, such as tessl-allow-teammate. A change to a setting (Code Review, the cloud environment) needs no branch.

2. Make the change

Say what will change and what the person gains or loses, and ask. Then:

• Let someone else start runs. Add their GitHub ID (gh api users/<login> --jq .id) to event.sender.id in every GitHub trigger that has one, as { "in": [<id>, <id>] }, so every trigger lists the same people. shepherd-pr-review also lists the Tessl Review bot (gh api 'users/tessl-reviewer[bot]' --jq .id): keep it there, and never add it anywhere else. The shepherd-checks-* triggers have no sender list, because checks start them. Then check the person's access: gh api repos/<owner>/<repo>/collaborators/<login>/permission --jq .role_name. Adding a label needs triage or above, so with read they can comment on Tessl's pull requests but cannot start an issue; tell the person. Runs from Linear are started by anyone who can delegate to Tessl; nothing to change there.
• Change the agent or model. Use only a pair that tessl launch models --json lists; it spells claude as claude-code. Change agent and model on the named action. Removing model runs the listed default pair, which can be a different agent and a much smaller model: say which before you offer it.
• Change Code Review. These are settings, not tessl.json: tessl code repo update <owner/repo> --org <org> with --review-trigger every-push|open-and-command (every push re-reviews the agent's fixes and uses credits each time), --review-publication enforcing|advisory (whether a review can approve or request changes), --review-auto-approve (approve once its findings are resolved), or --no-review-enabled to turn it off. Confirm with tessl code repo view <owner/repo> --org <org> --json. Changing these needs an organization admin.
• Stop or remove an automation. Remove its triggers, or its action and everything that names it, from tessl.json. That stops new runs once it is on the default branch; it does not cancel a run in progress. Do not use tessl schedule pause for these: a Loop defined in tessl.json is changed through the file. Before you ask, say what stops working, from that automation's section in triggers.md or starters.md. For "follow ticket changes": taking an issue back no longer cancels its run at once, closing an issue no longer closes its pull request, and a reply to Tessl's question no longer wakes the issue, so the person has to remove the label and add it again.
• Update the setup hook when the repository's tools or versions change. Edit .tessl/cloud-launch-setup.sh as setup-hook.md says, then run the cloud check from cloud-check.md on the branch before the merge.
• Change what the cloud environment can access. Run tessl environment view <environment> --json to see its access and key names. GitHub or Linear access: tessl environment update <environment> --github-access <level> or --linear-access <level>, which keeps every stored key. To add a key, send the person to the environment's page in the web app, which adds it to the others; never use --env-file, which replaces every stored key with the file's. Then check the key name appears in environment view.
• Change what an automation does, such as "run the linter before you push" or "never touch the migrations folder". Follow customize.md: a small change is an instructions string on the action, which keeps the published skill and its fixes; a larger one is a copy of the skill in the repository, which the person then owns. Say which, and that a copy stops getting fixes, before you start. Ask whether the change also applies to other actions that do the same kind of work, such as the shepherd, which pushes fixes too.
• Add another automation. Follow its starter in starters.md and its entries in triggers.md: create its environment when it needs its own, add its entries to tessl.json, create its label if it uses one. To show it working, wait until its Loop has appeared after the merge, then follow testing the factory. Run a scheduled one only with tessl schedule trigger <loop id>: a run started with tessl launch skill belongs to no Loop, so Tessl refuses its findings and the run's work is lost. When you are done with this change, give the "Suggest what to add" list below a look for the person's next step.
• Something else. If no case above fits, say what you would change and why, and ask before you do it.

3. Check and publish the change

For a setting, the command's own output and the view command after it are the check: skip to item 5. For a change on a branch:

1. Run tessl doctor --automations. Act on the Automation Configuration section only, and fix what it reports.
2. Show the diff, and say in one sentence what each change does.
3. Ask: "Do you want me to push this and open a pull request?" If yes, push and open it against the default branch, and give the link. Ask before you merge it; if the person declines, or the merge is refused, leave it for them.
4. Once it is merged, check the Loops as confirm-loops.md says: every action in the new tessl.json has its Loop with every trigger. For a removed action, check that its Loop is no longer listed; if it still is after 10 minutes, tell the person, with the Loops link, and do not say it is stopped.
5. Tell the person what is now different, what it costs, and how to undo it: revert the pull request, or for a setting, the same command with the old value.

Suggest what to add

When the person asks what to add, or after you finish a change, show them what else Tessl can do for this repository. Read the factory first, then the last 7 days of runs from one tessl launch list pass, as understand-factory step 2 does: enough to see patterns, without a lookup per run. Check each feature in features, and offer only the ones that are off and that something in this repository points to, each in one or two sentences: what it does, what this repository would get from it, and what it costs. Leave out a feature with nothing behind it; offering none is fine.

1. Lead with a fix for anything the runs show is stuck or broken, because the person is waiting on it: pull requests stalled on canceled checks, a setup hook that keeps failing, teammates whose labels start nothing. gh pr checks shows a canceled check as fail; read the conclusion from gh api repos/<owner>/<repo>/commits/<head sha>/check-runs.
2. Then Improve development while it is off, and say which of its two automations this repository is ready for now. When it is on, its open findings instead, with an offer to act on one.
3. Then up to two more features the repository points to:
   • Code Review lenses, verifiers, or prepare-repo, when its reviews keep repeating the same kind of comment.
   • A scheduled job, when the person mentions a recurring chore or the repository shows one: a CHANGELOG.md updated by hand, tests that keep failing in CI. Offer it as a question, not a recommendation.
4. Then any gap in the factory itself:
   • Answer reviews and fix checks, when "ship tickets" is on without it.
   • Code Review, when it is off.
   • Code Review that can approve, when it is on in advisory mode and the default branch requires an approving review: in enforcing mode Tessl can approve its own pull requests once their findings are resolved. Check with gh api repos/<owner>/<repo>/branches/<default branch>/protection (a 404 means the branch is not protected) and gh api repos/<owner>/<repo>/rules/branches/<default branch>.

Give the docs link from the features page where there is one. Ask which, if any, they want, and make it as in step 2.