Newton

§1One engine, two drivers

Newton runs YAML workflow graphs: shell steps, agents, human gates and nested workflows, with explicit transitions, checkpoints and artifacts.

The same engine drives an optimizer. It grades a project, plans a change, develops it and grades the result. It keeps the change only if the evidence says it is better.

§2The loop

You write an Optimization Definition. It sets the objective (a Grade, or a number with units such as bytes or verified vulnerabilities), the comparison policy, the constraints and limits, and the workflows that play grade, plan and develop.

baseline grade ──▶ plan ──▶ develop ──▶ candidate grade ──▶ accept?
      ▲                                                        │
      └───────────────────────── next cycle ───────────────────┘

software spine  Finding → Change Request → Plan → Execution

A candidate is accepted only when the exact artifact that was evaluated qualifies. Passing tests is not enough. Newton never pushes or opens a pull request. An accepted candidate is a local commit, and you decide how to promote it.

Every run ends with a reason you can read:

• converged
• cycle_complete
• resource_limit
• no_progress
• regressed
• stalled_on_blocked

§3A workflow is a graph

Tasks are operators, and edges are transitions with conditions. There is no hidden control flow and no glue script. This workflow scans the dependencies, asks a person before touching anything, then loops an agent against the tests.

# scan-and-fix.yaml (excerpt)
version: "2.0"
mode: workflow_graph
workflow:
  settings: { entry_task: scan, default_engine: claude }
  tasks:
    - id: approve
      operator: HumanApprovalOperator
      params: { prompt: "Apply the upgrade plan in plan.md?" }
      transitions:
        - to: develop
          priority: 0
          when: { "$expr": "tasks.approve.output.approved == true" }
        - { to: done, priority: 10 }

    - id: test
      operator: CommandOperator
      max_iterations: 3
      params:
        cmd: ./scripts/run-tests.sh && echo "TEST_STATUS: passed"
      transitions:
        - to: done
          priority: 0
          when: { "$expr": 'contains(tasks.test.output.stdout, "passed")' }
        - { to: develop, priority: 10 }

The full file is examples/scan-and-fix.yaml. Newton drew its graph:

Check it before it runs:

§4Findings that remember

Every grade is matched against what Newton already knows, first by a stable fingerprint and then by meaning. Known issues are refreshed, new ones are created and vanished ones are resolved. A fixed issue that comes back is reopened.

The same Findings are the work queue for your agents.

§5People where they matter

Approval and decision gates pause a graph and ask a person live, over ailoop. Everything else runs on its own.

A Plan that keeps failing doesn't loop forever. Its Findings are marked blocked and the optimizer carries on with the rest. If nothing else is actionable, the run stops as stalled_on_blocked and waits for a human.

§6Yours, and durable

Newton is one binary. State lives in your workspace under .newton/: checkpoints, artifacts and history. There is no hosted service, and no issue board pretending to be the source of truth.

newton serve adds a web UI, REST and MCP on one port. It stays on loopback by default. Bind it anywhere else and OIDC becomes mandatory.

§7Get started

Then run newton init . at a repo root, and newton doctor to check the environment.