Skip to main content
Keep a workflow in a central collection, in the repository it works on, or inside a service. It runs the same way from each. Use a central collection when the same team serves many repositories, the repository itself when the workflow is about that code alone, and a service when the workflow is part of what the service does at run time.

​
Motivation

A team you run every week outlives any one repository: the same writer, reviewer and sign-off serve your docs today and a client’s codebase tomorrow. A workflow is a TypeScript file and run() is a library call, so where the file sits is your choice, and the repository it works on is an argument.

​
Three homes

  • A central collection. A repository of its own holds your workflows, their briefs and their records, and each run is pointed at the repository it works on. This is the home for the teams you reuse.
  • Inside the repository. The workflow sits beside the code it changes and runs from that directory. This is the home for a workflow about one codebase, and the shape the first run shows.
  • Inside a service. The service imports the workflow and calls run() when its own logic says so. The workflow file exports the team and does nothing on import, so a terminal launcher and a service share one file.

​
Point at a repository

run(job, { cwd }) runs every stage in that directory. The path is absolute; the engines refuse a relative one. Leave cwd out and the run uses the directory you started it from, which is what “run it from the directory the work belongs in” means on the first-run page.
examples/tournament.ts (excerpt)
The file lives in this repository, and the candidates write into repo, a repository the example created somewhere else. The built-in teams take the same directory as their workspace argument. A brief loaded by path is read from the directory you started in, not from beside the workflow file. Pin it to the file with a URL: briefFromFile(new URL('./briefs/add.md', import.meta.url)).

​
The supervised runner

The supervised runner is stricter than run(). Its runRoot must be the top level of the repository the workspace provider captures, and the host module file must sit inside that root. A provider for another repository is refused with WORKSPACE_ROOT before any run is stored. The host file can import everything else from wherever the workflow lives, so a central collection keeps a small host file in each repository it supervises.

​
Next steps

  • Running: what run() does with the file, one bounded step at a time.
  • Supervised local runs: the watchdog, and the root and host rules it adds.
  • Workspace: a worktree per writer inside the repository a run is pointed at.