workline

package module
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: MIT Imports: 1 Imported by: 0

README

workline

A software factory for AI-assisted development:

  • each role — committer, documentalist… — does one job, with only the context it needs;
  • tools do the mechanical work; an AI is called only when a decision needs judgement;
  • everything keeps working without AI;
  • people state the need and accept the result; the line does the work in between (principles).

Status (2026-10-06): runs on every commit of its author, and in CI on the pull requests and nightly gardening of workline and of another project;

548 conformance cases green in CI.

Get started

  • Install the binary, then workline setup: the global hooks, your agent, the tools the roles use (install).
  • Choose your agent: none, Claude Code, or any command as cmd: (the choice).
  • Adopt a repository: workline init (install).
  • Add CI: the GitHub or GitLab templates (install).
  • Step by step, in ten minutes: the quickstart.

Documentation

Start here Use it Go further
Install — your machine, then CI Roles — what each does and not, its settings Principles
Quickstart — ten minutes, on your machine Usage — commands, options, exit codes Role contract — what a role is
Concepts — the words used everywhere Configuration — settings, files, variables Decisions · Research
Troubleshooting CI — GitHub, GitLab, other forges, none Backlog
Contributing — build, test, commits Any trigger · GitLab, started by a tool · Only a part

The roles

Role What it does for you Status
Committer checks each commit's message, the secrets it adds and its author beta
Documentalist keeps the docs true to the code they name beta
Reviewer reads a change before a person does and says what it breaks; never approves beta
Product owner keeps the open issues true to the code, refined and in order beta
Judge answers one yes-or-no question for the other roles, from another context or model beta
Auditor re-checks a weekly sample of the roles' acts (the docs' today) beta
Inspector will post the static-analysis findings a merge request adds planned
Security will add security scanners as gates and a security lens planned
Process engineer will read the line's measures and propose fixes planned
Tester will write an issue's tests first, kept from the developer planned
Architect will read specs for structure and keep architecture rules planned
UX will check accessibility and flows, for projects with a user interface planned
PM will map the product and suggest functions planned
Developer will take a ready issue and open the pull request, last planned
  • What each role does and does not, its settings and costs: its page, or all the roles.
  • A planned role links to its issue, which holds its design.
  • The auditor widening to every role: #205.
  • Why these roles, in this order: the roles panorama.

Where it runs

  • One routing says which roles each event runs: routing.default.yaml as shipped, changed in .workline/config.yaml.
  • A role behaves the same wherever it runs; only the trigger, the agent at hand and how its proposals are applied differ.
  • On a forge, one job judges, with the agent and no write token; another applies, with the write token and no AI key.
  • Forges: GitHub and GitLab built in; none (forge: local, kept in the clone); any other through a command (cmd:, a Forgejo and Gitea sample, untried on a live instance).
flowchart LR
  machine["Your machine"]
  mr["The merge request"]
  main["main"]
  issues["The issues"]
  machine -- git push --> mr
  mr -- a person merges --> main
  main -- gardening --> mr
  main -- the product owner --> issues
  mr -- a finding outside the change --> issues

Each role, from a hook, a script or a CI job: triggers.

Your machine

When Roles Agent
git commit (the global hook) committer yours, to rewrite a refused message
git push (the global hook, once workline init routes it) committer; documentalist, counting the docs made suspect never
workline review reviewer, before you push yours
workline review --spec <file>, --issue <n> reviewer, on a spec before it is built yours
workline docs documentalist: fixes the docs made suspect, you keep or drop each yours

The merge request

What Roles Writes
each push to it committer; documentalist; reviewer, opt-in the docs' fix on its branch; one summary comment; the findings in the forge's code-scanning view; the job's summary
a release tool's (release-please…) documentalist, on the docs due at the release the docs' fix in a merge request of its own
a fork's judged with no agent on GitHub, a comment; on GitLab, nothing

main: schedules and releases

When Roles Writes
gardening, nightly or weekly (workline route schedule) documentalist; product owner, opt-in one merge request per task; the issues
the weekly sample (workline sample) auditor: a second look at one doc in ten the documentalist confirmed; the product owner's acts, drawn for a person one issue, a comment a week; a merge request undoing a wrong confirmation
each push to main (workline follow) the engine, no agent: rebuilds the documentalist's release fix on main's new tip its merge request, force-pushed
before your release tool tags (workline route release) documentalist, on the docs due at the release a non-zero exit holds the release
  • workline cuts no releases: it runs before your release tool.
  • Templates: GitHub's gardening and sample, follow in workline.yml; on GitLab, two pipeline schedules and a push to the default branch, all in the same template.
  • Each command in detail: usage.

The issues

Who What
product owner, on gardening reads a share of the open issues against the code: duplicates, obsolete, refined to ready, split, ordered; one report issue
workline issues import <file> a roadmap file to issues
reviewer a finding outside the change: an issue, needs-triage
documentalist the code disagrees with a decision a doc records: an issue
a person accepts: the label workline:accepted, a parent closed

Gates

  • A gate is a checkpoint before merging or releasing: it runs your tools and gives a verdict by rules, never by asking a model.
  • Your tools, your thresholds: any command; its exit code, or its results in SARIF (the common format of static-analysis tools) counted against a max set before it runs.
  • Three outcomes for each check: pass, finding, or error — a tool missing, crashed or unreadable fails the gate, never passes it (an optional check is still reported).
  • Run with workline gate <name>, or as gate:<name> in a routing sequence.
gates:
  release:
    checks:
      - {id: load, run: k6 run load/checkout.js, output: exit}
      - {id: deps, run: "osv-scanner scan --format sarif --output {out}/deps.sarif .", output: sarif, max: {error: 0}}
  • Everything else: the gates spec.
  • Not built yet: a merge request's new findings only, posted on it (#202); a SonarQube quality gate read, never rerun (#203); other outputs (k6 or benchmark JSON); baselines with an expiry date.

Documentation

Overview

Package workline ships the built-in roles and the default routing inside the binary, so the engine works from any repository without a checkout of this one.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultRouting []byte

DefaultRouting is the line as shipped (routing.default.yaml).

View Source 
var Roles embed.FS

Roles holds the roles/ folder as shipped.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
workline command
Command workline runs the roles of the line.
 Command workline runs the roles of the line.
internal
agent
Package agent runs the "propose" step: it gives the role's question to a coding agent and collects its proposals in out/intentions.yaml.
 Package agent runs the "propose" step: it gives the role's question to a coding agent and collects its proposals in out/intentions.yaml.
backlog
Package backlog decides what becomes of a role's acts on a project's issues (docs/spec/backlog-acts.md): each is checked against the code and the forge, then done, proposed to a person, or dropped.
 Package backlog decides what becomes of a role's acts on a project's issues (docs/spec/backlog-acts.md): each is checked against the code and the forge, then done, proposed to a person, or dropped.
builtin/committer
Package committer holds the deterministic checks of the committer role (roles/committer).
 Package committer holds the deterministic checks of the committer role (roles/committer).
builtin/documentalist
Package documentalist holds the deterministic part of the documentalist role (roles/documentalist): which docs became suspect because a source changed, which are only pending because the cascade is cut, the hygiene checks (budgets, duplicates, links, identifiers gone from the code), and the judge of the patches the agent proposes for suspect docs.
 Package documentalist holds the deterministic part of the documentalist role (roles/documentalist): which docs became suspect because a source changed, which are only pending because the cascade is cut, the hygiene checks (budgets, duplicates, links, identifiers gone from the code), and the judge of the patches the agent proposes for suspect docs.
builtin/productowner
Package productowner holds the deterministic steps of the product owner role (roles/product-owner): pre lists the open issues with what the engine knows of each; the acts the agent proposes are checked when the engine applies them (internal/backlog).
 Package productowner holds the deterministic steps of the product owner role (roles/product-owner): pre lists the open issues with what the engine knows of each; the acts the agent proposes are checked when the engine applies them (internal/backlog).
builtin/reviewer
Package reviewer holds the deterministic steps of the reviewer role (roles/reviewer, ADR-0020): the rules no judgement is needed for, the lenses put to the agent as parts of one question, each finding's quotes found again, whether it lies in the change or outside it, the judge's answers read, and the verdict.
 Package reviewer holds the deterministic steps of the reviewer role (roles/reviewer, ADR-0020): the rules no judgement is needed for, the lenses put to the agent as parts of one question, each finding's quotes found again, whether it lies in the change or outside it, the judge's answers read, and the verdict.
doctor
Package doctor says what workline needs on this machine and in a repository, what is missing, and the command that sets each one up, as `flutter doctor` and `brew doctor` do.
 Package doctor says what workline needs on this machine and in a repository, what is missing, and the command that sets each one up, as `flutter doctor` and `brew doctor` do.
engine
Package engine runs one role once: check, prepare, propose, judge, apply (docs/spec/role-contract.md, "One run").
 Package engine runs one role once: check, prepare, propose, judge, apply (docs/spec/role-contract.md, "One run").
forge
Package forge applies what reaches a forge — comments, labels, issues, merge requests — on GitHub, GitLab, or a simulated forge for the tests.
 Package forge applies what reaches a forge — comments, labels, issues, merge requests — on GitHub, GitLab, or a simulated forge for the tests.
gate
Package gate runs a gate: a list of checks, each a command whose result is read against thresholds decided in advance (docs/spec/gates.md).
 Package gate runs a gate: a list of checks, each a command whose result is read against thresholds decided in advance (docs/spec/gates.md).
gitrange
Package gitrange reads the range of commits a run is given: `base..head`, a single commit, or `head ^base…` when the commits stand on several commits already pushed — a branch that merged main (internal/hooks).
 Package gitrange reads the range of commits a run is given: `base..head`, a single commit, or `head ^base…` when the commits stand on several commits already pushed — a branch that merged main (internal/hooks).
hooks
Package hooks installs workline's git hooks.
 Package hooks installs workline's git hooks.
intent
Package intent reads the proposals an agent writes and checks them against the closed catalogue (docs/spec/role-contract.md, "Intentions").
 Package intent reads the proposals an agent writes and checks them against the closed catalogue (docs/spec/role-contract.md, "Intentions").
judge
Package judge asks an agent one yes-or-no question on what a role produced, at the best independence available from the agent that produced it (ADR-0005): another provider, another model of it, or the same model in a context of its own.
 Package judge asks an agent one yes-or-no question on what a role produced, at the best independence available from the agent that produced it (ADR-0005): another provider, another model of it, or the same model in a context of its own.
line
Package line runs the steps routing names for an event, in order, and the handoffs they ask for (docs/spec/routing.md).
 Package line runs the steps routing names for an event, in order, and the handoffs they ask for (docs/spec/routing.md).
pathglob
Package pathglob matches repository paths against patterns where `*` stays within one folder and `**` spans any number of folders.
 Package pathglob matches repository paths against patterns where `*` stays within one folder and `**` spans any number of folders.
release
Package release says what a project's releases are, for the roles that hold them (ADR-0017): the branches a release tool opens its pull request from, and the last release, one lookup for every reader.
 Package release says what a project's releases are, for the roles that hold them (ADR-0017): the branches a release tool opens its pull request from, and the last release, one lookup for every reader.
report
Package report writes findings in the formats forges read: SARIF 2.1.0, for GitHub code scanning (and GitLab Ultimate), and GitLab's Code Quality report, which every GitLab tier shows on a merge request.
 Package report writes findings in the formats forges read: SARIF 2.1.0, for GitHub code scanning (and GitLab Ultimate), and GitLab's Code Quality report, which every GitLab tier shows on a merge request.
review
Package review shows a person what the machine proposes, for them to accept or refuse: a page any browser opens, and a question on the terminal.
 Package review shows a person what the machine proposes, for them to accept or refuse: a page any browser opens, and a question on the terminal.
role
Package role loads a role's contract (role.yaml) and the project's settings for it, as described in docs/spec/role-contract.md.
 Package role loads a role's contract (role.yaml) and the project's settings for it, as described in docs/spec/role-contract.md.
rolefs
Package rolefs extracts the built-in roles to a cache folder, because their pre and post scripts must exist as executable files to be run.
 Package rolefs extracts the built-in roles to a cache folder, because their pre and post scripts must exist as executable files to be run.
routing
Package routing reads which roles and gates run on which event, and which handoffs are allowed (docs/spec/routing.md).
 Package routing reads which roles and gates run on which event, and which handoffs are allowed (docs/spec/routing.md).
sample
Package sample is the weekly sample of the docs the documentalist vouched for (ADR-0014, step 4): one in ten of the docs whose `checked` it moved in a week, read whole against their sources at the commit `checked` names, by a judge standing apart from the model that vouched (ADR-0005).
 Package sample is the weekly sample of the docs the documentalist vouched for (ADR-0014, step 4): one in ten of the docs whose `checked` it moved in a week, read whole against their sources at the commit `checked` names, by a judge standing apart from the model that vouched (ADR-0005).
setup
Package setup sets workline up on a machine, asking what to enable: the global git hooks, the agent, the tools the roles use.
 Package setup sets workline up on a machine, asking what to enable: the global git hooks, the agent, the tools the roles use.
tools
Package tools knows the programs workline calls but does not ship — the optional tools a role `uses`, the agents, the forges' CLIs — and how each one is installed, so a missing one is named with the command that installs it on this machine.
 Package tools knows the programs workline calls but does not ship — the optional tools a role `uses`, the agents, the forges' CLIs — and how each one is installed, so a missing one is named with the command that installs it on this machine.
verdict
Package verdict reads and writes the verdict a run ends with.
 Package verdict reads and writes the verdict a run ends with.
work
Package work reads and moves work items kept as files in .workline/work/, for projects without a forge (docs/spec/routing.md, "Work starts from a clear need").
 Package work reads and moves work items kept as files in .workline/work/, for projects without a forge (docs/spec/routing.md, "Work starts from a clear need").
tests
evaluation/summary command
Summary reads results.tsv and prints, per case, models, effort and judge, how many runs there were, the pass rate (the share of runs earning every point), the mean score and its range, and what a run used: one run says little, since a model answers differently from one run to the next, and a best run hides the others (ADR-0014).
 Summary reads results.tsv and prints, per case, models, effort and judge, how many runs there were, the pass rate (the share of runs earning every point), the mean score and its range, and what a run used: one run says little, since a model answers differently from one run to the next, and a best run hides the others (ADR-0014).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.