Skip to main content
@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

Included in @obversa/obversa.

Quickstart

A writer, a real Node check and a reviewer, with scripted engines so it runs offline:
examples/builtin-workflows.ts (excerpt)
The writer writes the file, the test command checks it, and the reviewer reads it back; a rejection returns the findings to the writer. Run it with 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:
  1. 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.
  2. 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. With briefPath, a resume reads the brief file again, so a fixed brief needs no relaunch. A warning goes to the builder.
  3. Build. The implement seat builds the change. Its report ends with a commit message in a fenced block marked commit.
  4. Report. The builder’s report goes to the team.
  5. 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.
  6. Checks. Each command in checks runs 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.
  7. 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.
  8. 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.
Only the review panel’s verdicts go through the judge. A failed check, a change too large to review and missing proof go straight back to their step, so a judge never passes a tree whose checks failed. The report’s answer to a send-back runs on the builder’s seat and its candidates, as the build does. With 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 with run’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_DECISION by outcomeFromAgentText.
  • Seats from one model family on both sides of a review are refused before any model runs.
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. ImproveWorkflowConfig takes record, workflow, proposer and reviewer. 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, stage and person for a team of your own.