@obversa/builtin-workflows ships three teams you configure instead of
write: a writer and a reviewer, a review panel with a threshold, and a
nine-stage feature delivery. Give one its brief, workspace, expected files,
test command and engine seats, and it returns a job for run from
@obversa/runtime. To declare your own roles and stages, use workflow()
from the Runtime instead; this package
doesn’t export the builders.
The package also ships improveWorkflow. It reads the record of a
workflow’s run, proposes one change to the workflow file, and applies it
when a person says yes. Workflows That Improve
Themselves shows it end to
end.
Install
@obversa/obversa.
Quickstart
A writer, a real Node check and a reviewer, with scripted engines so it runs offline:examples/builtin-workflows.ts (excerpt)
npx tsx builtin-workflows.ts:
Output
Choose a recipe
writerReviewerPair and thresholdPanel take a TeamInput. A seat is a TeamSeat from
@obversa/api, an engine with its declared identity:
examples/builtin-workflows.ts (excerpt)
Feature delivery
featureDelivery(config) builds one change in a worktree and runs it to a
passed, reviewed change. It runs these steps in order:
- Seat check. Each seat whose engine has an admission check starts its CLI and reports its version, before any build spend. A seat that cannot start is replaced by its next candidate, and every later step starts on the seat that answered. With no candidate left, the run pauses and names the seat.
- Brief check. The first reviewer reads the brief against the
repository and lists every finding it can establish, in one pass. With
houseRules, it reads the house rules too. It blocks only on a wrong goal, a false claim about the repository or its base, a check that cannot fail, or a house rule that says the brief check blocks it. It never blocks because the tree does not yet do what the brief asks the build to do. A block pauses the run. WithbriefPath, a resume reads the brief file again, so a fixed brief needs no relaunch. A warning goes to the builder. - Build. The
implementseat builds the change. Its report ends with a commit message in a fenced block markedcommit. - Report. The builder’s report goes to the team.
- Size check. The review input is measured for every reviewer seat. A change too large for one, even with data files listed, goes back to the build with its largest files named, before any check runs.
- Checks. Each command in
checksruns on the tree. A failure runs once more before it counts. A failure’s output goes to the builder once, cut to fit the builder’s whole next prompt. - Proof check. The
reader(the first reviewer by default) asks only for proof the run cannot produce itself. A check the run passed counts as proven. The first missing-proof send-back in a run goes to the report and costs no review round; a later one goes to the build, with the report the proof check read. A resumed run keeps both. - Review. The panel reviews the change, with the judge between its verdict and each send-back. From round 2 each reviewer reads its own open findings and the diff since its last round.
commit: true, a passed run commits its work with the report’s
commit message. See commit.
Accepted proofs
Each proof the proof check accepts is kept with the brief item it answers, the tree it was accepted on and the files it covers. The proof check names those files: the code the proof tests or measures, its test file and the script it ran. A proof with no files named covers the whole change. A later report replaces the last report, but never the accepted list, and a resumed run reads the list back from the record. The run’s own files (its record, the records kept beside it and its check output) are never part of a proof’s tree, so a record inside the worktree does not stale a proof. A proof stands until the diff from its tree to the current tree touches a file it covers. The builder’s prompt lists the proofs that stand, so it does not run them again.Carrying on from an earlier run
Run it withrun’s carryFrom to carry on
from an earlier run on the same brief. The first build answers the earlier
run’s open findings, and its accepted proofs still stand while their files
are unchanged. The first build and the brief check are both told that the
worktree may hold the earlier run’s work, and how that run ended, so the
brief needs no note about it.
Improve a workflow
climbWorkflow(config) scores a proposed change to a workflow file. It runs
the workflow on tuning tasks and held-out tasks, with and without the
change, and keeps the change only when the workflow scores better with it.
A person approves a kept change. With mode: 'auto', the numbers alone
decide for a change that the auto option allows: the files, and the
settings keys and values, it may change. Any other kept change goes to a
person. formatClimbReport(report) prints the comparison. See
Workflows that improve themselves.
Read a review decision
outcomeFromAgentText(text, target?) reads a reviewer’s reply: the first
JSON decision object becomes a pass, or findings aimed at target.
INVALID_TEAM_DECISION is the message for a reply that holds no decision.
Both are re-exported from @obversa/runtime/workflow-support.
Options
TeamInput
FeatureDeliveryConfig
Seats and thresholds
Errors
- A reply with no decision is marked
INVALID_TEAM_DECISIONbyoutcomeFromAgentText. - Seats from one model family on both sides of a review are refused before any model runs.
Full file
Full file
examples/builtin-workflows.ts
API
writerReviewerPair(config),thresholdPanel(config),featureDelivery(config): the three recipes. Choose a recipe.improveWorkflow(config): one change to a workflow file from its run’s record, applied on a person’s yes.ImproveWorkflowConfigtakesrecord,workflow,proposerandreviewer. Workflows That Improve Themselves.climbWorkflow(config),formatClimbReport(report): keep a change to a workflow only when it scores better. Improve a workflow.outcomeFromAgentText,INVALID_TEAM_DECISION: read a reviewer’s reply. Read a review decision.- Types:
PairConfig,PanelConfig,FeatureDeliveryConfig,ImproveWorkflowConfig,TeamInput,TestCommand,ReviewerSeat,ClimbAuto,ClimbConfig,ClimbProtection,ClimbReport,ClimbRun,ClimbSettingRule,ClimbTaskReport,ClimbTotals.
Next steps
- A writer and a reviewer: the same pair
declared with
workflow()and run on real engines. - Runtime:
workflow,stageandpersonfor a team of your own.