sfe — Software Factory Enablement

A small shell script that runs the Tessl agent across a batch of GitHub repositories to help you improve their agentic workflows.

For each repo you name, sfe clones it, then runs one continued tessl agent session in yolo (auto-approve) mode. Each prompt asks the agent to document suggestions in a markdown file rather than change code or file issues — so you end up with a set of agent-ready handoff documents you can review and action later. Finally it writes a timestamped report summarising what was produced in each repo.

Every playbook runs a setup/grounding turn first, then a series of document-only deliverables. Because the deliverables share one session, they avoid the cross-prompt duplication you get from independent cold runs, and each is told to reference — not restate — the earlier ones.

Pick a playbook with --playbook NAME (default: advisory).

The Tessl trio. Mirrors Tessl's documented flow (setup-memory → review → optimise → automate):

0. Setup — grounds shared context (à la /setup-memory); not a deliverable.
1. AGENTIC-CODE-REVIEW.md — setting up agentic code review (tessl change review)
2. AGENT-OPTIMISATIONS.md — finding optimisations for your agents (à la find-optimizations)
3. AGENT-AUTOMATIONS.md — recurring tasks to automate/delegate (à la find-automations)

A repo-specific plan for building your own software factory, distilled into six stages (after Tessl's build guide). Each stage produces one advisory handoff doc explaining how to build that stage in this repo, restating the stage's "prove it" acceptance checks as its definition of done. It plans the factory — it does not build it (still document-only).

0. Setup — grounds context and records factory prerequisites (CI on PRs, gh as a machine user, a headless agent, a protected branch); not a deliverable.
1. FACTORY-STAGE-1-SHIP-ONE-TICKET.md — one issue → one PR (run-one)
2. FACTORY-STAGE-2-MAKE-IT-A-LOOP.md — the polling daemon that claims issues
3. FACTORY-STAGE-3-CLOSE-THE-LOOP.md — the PR watcher (CI + review feedback)
4. FACTORY-STAGE-4-HUMAN-LEVERS.md — the human control grammar (pause/resume)
5. FACTORY-STAGE-5-TEACH-IT-TO-ASK.md — clarification protocol + sizing
6. FACTORY-STAGE-6-MAKE-IT-COMPOUND.md — maintenance runs, context habit, metric

The factory playbook is built to be run one stage at a time with --step (below): run a stage, verify its acceptance checks by hand, then advance.

• tessl — installed and authenticated (tessl login)
• gh — the GitHub CLI, authenticated (gh auth login)
• git
• bash

The script checks that all three tools are present and authenticated before it does anything.

./sfe [--playbook NAME] [--step] [--start-at N] org1/repo1 org2/repo2 ...

For example:

./sfe popey/slomore ainativedev/agentic-cheat-sheets     # advisory trio, all steps
./sfe --playbook factory --step popey/slomore            # factory, one stage at a time

Each repo is given as owner/repo. Repos are cloned into repos/<repo>/ (re-runs reuse the existing clone). Cloning is done over HTTPS using gh as a credential helper, so it works regardless of your SSH key setup.

By default sfe runs a repo's whole playbook in one go. Pass --step to run only the next uncompleted step, print that step's acceptance checks, and stop. You verify the checks by hand, then re-run the same command to advance to the next step. This is the intended way to drive the factory playbook — build and prove each stage before moving on:

./sfe --playbook factory --step popey/slomore   # runs setup, stops, shows prereqs
./sfe --playbook factory --step popey/slomore   # runs stage 1, stops, shows checks
./sfe --playbook factory --step popey/slomore   # runs stage 2, ...

Progress is tracked per repo (see below), so each invocation picks up exactly where the last one stopped. Without --step, the whole remaining playbook runs.

Each repo tracks its progress in repos/<repo>/.sfe-progress (the last step that completed successfully — 0 for setup, then 1…N for the playbook's deliverables). If a run is interrupted — you close the laptop, the network drops, a step fails — just run the same command again. Each repo automatically resumes from where it left off (reusing the same Tessl session via --continue), and finished repos are skipped entirely.

To force where a run begins, use --start-at N (a deliverable number: 1–3 for advisory, 1–6 for factory), which applies to every repo in that invocation and assumes setup already ran:

./sfe --start-at 2 popey/snapupdates   # begin at the 2nd deliverable

To force a full re-run of a repo, delete its progress file:

rm repos/snapupdates/.sfe-progress

• Markdown handoff docs land inside each repo's working copy under repos/<repo>/, with fixed names (AGENTIC-CODE-REVIEW.md, AGENT-OPTIMISATIONS.md, AGENT-AUTOMATIONS.md) so batch tooling can find them.
• A run report is written to REPORT-<timestamp>.md in this directory, listing the markdown files produced (or changed) per repo, plus any failures or resumes. The report is also printed to the terminal at the end.

The script exits non-zero if any repo failed to clone or any prompt failed, so it's safe to use in a larger pipeline.

• Each prompt is a full agent session, so runs take a while — expect several minutes per repo.
• The prompts live in the load_playbook_* functions near the top of the script (each sets SETUP_PROMPT, SETUP_CHECKS, and the index-aligned DELIVERABLE_PROMPTS / DELIVERABLE_FILES / DELIVERABLE_CHECKS arrays); edit them there to change what the agent is asked to do, or add a new playbook by writing another load_playbook_* function and wiring it into load_playbook.
• Tessl's own .tessl/ memory files are excluded from the report so only genuine deliverables are listed.

MIT — see LICENSE.