Skip to content

Releases

AgentMachinist 0.21.0

Choose a tag to compare

@vscarpenter vscarpenter released this 16 Nov 00:38
2de64f8

AgentMachinist 0.21.0 puts the decision first when you inspect a local Task or revise a plan. It also refreshes the project's dependencies.

Read the decision before the details

  • machinist inspect T1 opens with a bounded decision summary: the paths the Task changed, each Gate outcome, high-severity advisory Review findings, and the next actions you can take. The full plan, diff, checks, and history follow, and the actions repeat after them.
  • After machinist revise T1 --feedback "...", AgentMachinist shows a bounded difference between the two Spec commits before the revised plan. A revision that changes only line endings says so. Every revised plan still needs fresh Approval.
  • The summary counts results before it truncates them, so omitted failures and findings stay visible. It leaves out an Execute report whose commit does not match the candidate instead of showing it as a passing check.

Recovery

  • When approve or continue meets a stopped local Phase, the message names machinist retry --task T1 --phase execute. It used to print the GitHub issue form, machinist retry 1.

Documentation

  • The documentation now lives at https://agentmachinist.com/docs/.
  • The first-run guide covers the local workflow only. The GitHub Actions setup has its own page.
  • Two new pages: a reader glossary, and a local Task lifecycle diagram that shows each state machinist status prints and the command that moves it.

Dependencies

  • The lockfile moves to Click 8.5.1, pydantic 2.14.3, and pytest 9.2.0. The pinned development tools move to Ruff 0.17.5, mypy 2.4.1, and Hatchling 1.33.0. Runtime requirements keep their existing minimums.
  • The managed Spec workflow template now pins astral-sh/setup-uv v10.3.3. If your repository runs Spec in GitHub Actions, run machinist sync-workflows after you upgrade.

Upgrade:

uv tool upgrade agentmachinist
machinist --version

Python 3.12 or later is required.

The release workflow verifies the exact version, builds and smoke-tests the wheel and source distribution, and publishes using PyPI Trusted Publishing. Distributions and SHA-256 checksums are attached after successful publication.

AgentMachinist 0.20.0

Choose a tag to compare

@vscarpenter vscarpenter released this 06 Oct 20:41
6496d5c

AgentMachinist 0.20.0 makes the local workflow easier to learn and inspect, and improves recovery before implementation.

Learn the workflow before your first Task

  • machinist rehearse --guided pauses at the saved plan and reviewed candidate so you can practice Approval and acceptance for free. It runs from an installed package without a source checkout.
  • machinist doctor --local --fresh-workshop checks committed code and dependencies in a disposable checkout before a paid run.
  • CLI help and first-run documentation lead with the local plan, review, and integration journey.

Make informed decisions and recover safely

  • machinist revise T1 --feedback "..." revises an initial plan while preserving Task identity, prior Specs, and feedback history. Every revised plan needs fresh Approval.
  • machinist inspect T1 [--json] brings the plan, candidate diff, checks, Review, and next action into one read-only view.
  • machinist config show/set --local makes saved local settings and their effects explicit.
  • Local retries can explicitly select another Harness or model without changing saved preferences.

Reliability and documentation

  • Goose Specs and Reviews retain the final assistant answer from its structured transcript.
  • Failed local Reviews report a concise error and retain raw output for diagnosis.
  • Verification has larger finite time budgets for the full real-Git suite, preserving every check and publication guard.
  • Documentation includes the updated 90-second explainer, clearer recovery guidance, more readable labels and headings, improved contrast in both themes, and simpler layouts. Commands, diagrams, and onboarding controls are preserved.

Install or upgrade:

uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --version
machinist rehearse --guided

Python 3.12 or later is required. The free rehearsal makes no model/API calls. Real Tasks use your configured coding assistant and its provider usage.

The release workflow verifies the exact version, builds and smoke-tests the wheel and source distribution, and publishes using PyPI Trusted Publishing. Distributions and SHA-256 checksums are attached after successful publication.

v0.19.0

Choose a tag to compare

@vscarpenter vscarpenter released this 28 Sep 03:09
141c5ef

0.19.0 adds a built-in Goose Harness adapter and clearer first-run guidance found by walking the first-Task path as a newcomer. Human Approval, exact-SHA binding, and controller ownership of Git operations remain unchanged.

  • Add a built-in Goose adapter (harness.name: goose). Spec and Review run
    goose run -q --no-session --no-profile --with-builtin developer, and
    Execute runs goose run --no-session. The developer builtin can also write
    files, so read-only custody is advisory and the controller's postconditions
    enforce it, as for OpenCode.
  • Set GOOSE_MODE=auto for every Goose run. The approval modes wait for a
    confirmation that a headless Task Run cannot give.
  • Keep Goose out of first-run discovery. pressly/goose, a Go database
    migration tool, installs the same goose executable, so choose Goose with
    --harness goose.
  • Goose has no managed GitHub Spec CI profile and no non-interactive auth
    probe. Workflow projection refuses it with the local-dispatch recovery, and
    doctor asks you to verify its login yourself.
  • Adapters can pin non-secret environment variables with
    environment_overrides() and opt out of first-run discovery with
    auto_select = False.
  • Point config show and config set at machinist start when neither
    machinist.yaml nor saved local settings exist, instead of recommending
    GitHub onboarding. Neither command creates a file.
  • Align help text with the local workflow: onboard is optional GitHub
    automation, amend --task starts from a reviewed candidate, and
    retry --fresh names both defaults.
  • Document that the controller ignores global Git identity. Set
    user.name and user.email inside the repository, or Spec and candidate
    commits use the AgentMachinist identity. The first-Task example now does
    this and clones the repository before copying.

Upgrade:

uv tool upgrade agentmachinist
machinist --version

Goose is never chosen automatically; select it with machinist start --harness goose. If your commits should carry your name, set git config user.name and git config user.email inside the repository, because the controller ignores your global Git identity.

The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.

v0.18.0

Choose a tag to compare

@vscarpenter vscarpenter released this 26 Sep 20:01
6a59af4

0.18.0 adds combined local and legacy reporting, an opt-in single repair round inside Execute, and the first-run fixes found by setting up a fresh repository from scratch. Repair defaults off. Human Approval, exact-SHA binding, and controller ownership of Git operations remain unchanged.

  • Report baseline Verification failures truthfully in the local workflow. The
    Gate's own error replaces the misleading read-only Workshop message, files a
    Gate created are named, failure messages show both output streams, and
    status prints the error, the log directory, and a baseline failed state
    with both recoveries.
  • Detect uv run pytest when uv is installed and python3 -m pytest
    otherwise; a lockfile no longer selects the runner.
  • Check the checkout before start saves local configuration, name pending
    paths in the refusal, and let --harness and --test-cmd replace saved
    settings until the first Task exists.
  • Route doctor, status, config, clean, and runs to the local workflow
    when machinist.yaml is absent. clean --task T1 removes one local Task's
    retained Workshops.
  • Add examples/first-task, a disposable project for a first Task, linked from
    the short guide and the README.
  • Simplify documentation navigation around the workflow diagram and a short
    first-Task guide. Add complete Markdown/web directories, group alternate
    formats and historical records, and retain existing document URLs.
  • Include local and legacy Task history in machinist report, with explicit
    source selection, separate Task namespaces, first-pass Execute and repair
    outcomes, current local delivery snapshots, and token usage coverage. Reports
    work without local setup or root configuration. Local/all telemetry export
    requires an explicit endpoint; configured legacy export uses --source legacy.
  • Add an opt-in single repair round inside Execute after ordinary required
    Verification failures. Persist the consumed round and extra-work deadline,
    retain separate Evidence, recheck custody and limits, and rerun final gates.
    Control failures stop immediately. Failed Task Runs still need explicit retry,
    and interrupted repairs require a fresh attempt rather than replaying paid work.
  • Expand this repository's configured Verification to required, check-only
    workflow drift, formatting, lint, types, and coverage/test gates. Existing
    saved local configurations keep their settings until explicitly updated.
  • Align operating, visual, contributor, and architecture documentation with
    the repair and reporting contracts in this release. Clarify metrics, recovery,
    telemetry consent, and release availability; correct the managed Spec
    workflow's instructions for switching back to local dispatch.

Upgrade:

uv tool upgrade agentmachinist
machinist --version

For an existing managed GitHub setup, run machinist sync-workflows, review and commit any generated changes, and deliver them to the default branch. Existing saved local configurations keep their Verification settings until you edit them.

The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.

AgentMachinist 0.17.1

Choose a tag to compare

@vscarpenter vscarpenter released this 14 Sep 05:03
85dd41d

machinist init and machinist onboard now print explicit staging commands for managed workflow files. Fresh setup includes new workflows in the commit, setup reruns retain the right files, and mode changes include tracked workflow removals while leaving unrelated workflow edits unstaged. Review the staged diff before committing as before.

This release also includes the Approval policy, advisory source-text guidance in all three Harness prompts, and the workflow diagram prepared for 0.17.0. Human Approval and controller ownership of Git operations remain unchanged.

Upgrade:

uv tool upgrade agentmachinist
machinist --version

For an existing managed GitHub setup, run machinist sync-workflows, review and commit any generated changes, and deliver them to the default branch.

The release workflow verifies the package, publishes through PyPI Trusted Publishing, attaches wheel and source distributions with SHA-256 checksums, and checks an isolated install of the published version.

AgentMachinist 0.16.0

Choose a tag to compare

@vscarpenter vscarpenter released this 12 Sep 22:20
a27ce2f

AgentMachinist 0.16.0 makes the next step easier to find. CLI completion messages now suggest the next activity and a sample command throughout the local and GitHub workflows.

  • Issue creation guides direct Spec generation, watcher processing, or hosted Spec progress according to the configured source.
  • Spec and Approval receipts explain the human review step and how to wait for trusted GitHub Approval.
  • Completed Review and local integration guide inspection and optional GitHub/GitLab publication. One-pass watcher runs print the same completion receipts.
  • The full documentation directory has been reviewed and updated, including command examples, recovery instructions, Harness settings, and historical applicability notes.

Exact-SHA Approval, dispatch eligibility, structured JSON output, verification, and independent Review remain intact.

Upgrade with uv tool upgrade agentmachinist, then verify with machinist --version. The package name is agentmachinist; the executable is machinist.

AgentMachinist 0.15.0

Choose a tag to compare

@vscarpenter vscarpenter released this 08 Sep 02:14
2b701f9

AgentMachinist 0.15.0 adds optional local readiness diagnostics, exact remote-base validation for new legacy Task Workshops, and bounded, credential-redacting diagnostics. The guided local workflow and optional GitHub/GitLab publication from 0.14.0 are unchanged.

Install or upgrade

uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --version   # 0.15.0

Optional local readiness

machinist doctor --local
machinist doctor --local --json
# Explicitly run the configured Verification Gates in this checkout:
machinist doctor --local --run-gates

doctor --local reuses the configuration resolution that start uses, checks Git, Harness probes, and verification command availability, creates no Task or runtime state, and contacts no forge. Plain machinist doctor keeps its GitHub setup checks.

Changes

  • Add optional machinist doctor --local [--json] [--run-gates] readiness for
    new and existing local projects. Reuse start's configuration resolution,
    inspect Git/Harness/verification readiness without creating local state or
    contacting a forge, and execute project gates only when requested. Existing
    GitHub doctor behavior remains available without --local.
  • Fetch and validate the exact remote base before provisioning a new legacy
    Task Workshop. Deleted or renamed remote branches fail despite stale local
    tracking refs; construction uses the captured commit. Existing remote Task
    branches remain authoritative for recovery, and local Tasks remain offline
    with respect to Git.
  • Sanitize bounded Git, GitHub, GitLab, and doctor diagnostics before rendering:
    redact recognized credential syntax and remove unsafe terminal controls while
    preserving useful multiline failures. Successful Git and forge data remains
    unchanged; arbitrary raw logs are outside this defense-in-depth boundary.

See ADR 0004 · Local workflow guide · Visual first-run guide

Release verification

The tag points to merged commit 2b701f9438d68b4ff1fd49e7957e0799d95c6a05 (PR #44).
The pull request CI passed on Linux and macOS with Python 3.12, 3.13, and 3.14, including coverage, minimum dependencies, packaging, static checks, and both CodeQL analyses. The local bash scripts/verify.sh gate passed on the merged head: 1,508 tests at 88% coverage, lockfile, managed-workflow, format, lint, and type checks, and installed wheel and sdist smoke tests reporting 0.15.0.

The release PR also corrected two CI-environment assumptions in the new local doctor tests (a Git author name derived from the OS account, and a snapshot race with Git's background auto-maintenance); no controller behavior changed.

Full changelog: v0.14.0...v0.15.0

AgentMachinist 0.14.0

Choose a tag to compare

@vscarpenter vscarpenter released this 07 Sep 15:43
cf96718

AgentMachinist 0.14.0 adds an end-to-end local workflow for solo developers and small teams. Start from a Git checkout, approve the exact Spec, and inspect a verified candidate with independent advisory Review. Integrate locally and publish to GitHub or GitLab when collaboration is useful.

Install or upgrade

uv tool install agentmachinist
# Existing uv installation:
uv tool upgrade agentmachinist
machinist --version

First local Task

machinist start "Handle an invalid timezone without crashing" --test-cmd "uv run pytest"
# Read the Spec and use the exact full SHA printed by start:
machinist approve --task T1 --spec-sha <full-spec-commit-sha>
machinist status T1
# Inspect the candidate diff and advisory Review before integrating:
machinist integrate T1
# Optional: matching origin and authenticated forge CLI required:
machinist publish T1 --provider gitlab

Local Tasks require at least one required Verification Gate and always complete independent Review. GitLab support covers issue import and MR publication through glab, including nested projects and self-managed hosts; it does not add hosted GitLab Spec CI or remote Approval. A local workflow can still use cloud models. Existing GitHub issue automation remains supported.

Changes

  • Allow 30 minutes for the expanded real-Git CI test and package/release build jobs, keeping all checks required.
  • Add the guided foreground local journey: start saves a Task and generates
    its Spec; approve --task T1 --spec-sha <sha> continues verified Execute and
    independent advisory Review. Status shows the local result and next action.
    Initial setup needs Git, an installed Harness, and a verification command;
    no origin, forge account, labels, daemon, or hosted workflows are required.
  • Add durable local Task IDs, exact repository/Task/Spec Approval, retained
    candidate refs, reports, explicit amendments, cancellation, and retry. Local
    Task Run construction reuses the dispatcher, lifecycle, custody, and
    Verification engine. Local orchestration does not imply offline inference.
  • Add explicit local integration: fast-forward only, from a clean expected
    base to the exact reviewed candidate, with persisted recovery intent.
    Automatic and remote merges remain outside the controller's contract.
  • Make local publication optional and recoverable through GitHub PRs or GitLab
    MRs. GitLab issue intake and MR publication use authenticated glab, including
    nested projects and explicit self-managed hosts. Exact repository/head
    checks and leased pushes prevent silent destination changes or overwrites;
    publication retries do not rerun successful Harness work or verification.
    Native GitLab Spec CI and remote GitLab Approval are not included.
  • Fix GitHub setup PR's circular deployed-workflow prerequisite. Validate local
    setup before creating the PR and check deployed readiness after merge.
    Recognized partial onboarding resumes while preserving configuration.
  • Permit a fresh Review after a new successful Execute candidate, including
    amendments, while blocking duplicate Review of the same successful head.
    Print Review completion and finding counts instead of claiming it passed an
    unimplemented severity policy.
  • Run rehearsal through the production local Phases, real Git, Verification,
    Review, and integration. The default uses a deterministic fake Harness;
    configured provider invocation remains an explicit --harness choice.
  • Accept Task bodies from files/stdin and preserve drafts on lint or creation
    failure. Lint recognizes ## and GitHub issue forms' ### sections, respects
    nested headings, and rejects empty or placeholder acceptance checkboxes.
  • Rename the daily Phase-attempt limit to max_runs_per_day. Legacy
    max_tasks_per_day still loads with unchanged counting semantics; conflicting
    aliases fail validation and effective configuration emits the canonical key.
  • Update the complete documentation set and interactive guides for local
    onboarding, configuration and command namespaces, recovery, optional
    publication, and GitLab support. Preserve earlier design records with
    applicability notes and current references.
  • Reconcile a crashed Execute push from the remote Task branch as well as
    GitHub's PR listing. When the listing lagged a push the controller had just
    made, a fresh run failed its approved-head check and advised approving the
    current head again, which could rerun the Harness on already-verified code.
    That window now delivers the pushed implementation; the head-mismatch
    messages say the remote branch moved after Approval and point at
    machinist inspect.
  • One push step for fresh and resumed Execute runs. A retry after the
    implementation commit re-enters the same leased push, observation, and
    delivery instead of a separate resume-push path; a remote already at the
    implementation is a no-op, one that moved elsewhere fails the lease.
  • Legacy GitHub machinist approve takes exactly one of --issue <n> or --pr <n>. The
    positional target, which resolved issue-versus-PR ambiguity with its own
    error, is removed; every documented example already used the flags.

Local workflow guide · Visual first-run guide

Release verification

The tag points to merged commit cf967186083f3195322bfb6fb0e76b7ae1a9b93d.
The release build and publication workflow passed all 1,413 tests, built and smoke-tested both distributions, published through PyPI Trusted Publishing, and verified an uncached install from PyPI. The release candidate CI passed on Linux and macOS with Python 3.12, 3.13, and 3.14, including coverage, minimum dependencies, packaging, and static checks.

The wheel and source archive were downloaded independently from GitHub and PyPI; both matched the attached SHA256SUMS. All 23 deployed documentation files matched the tagged source. The installed PyPI package passed the complete production local rehearsal with a deterministic fake Harness, including Spec, exact-SHA Approval, Execute, verification, Review, and local integration.

CI on the tagged, merged main commit also passed every job, including the complete Linux/macOS matrix and aggregate CI gate. Both CodeQL analyses passed on the same commit.

v0.13.0

Choose a tag to compare

@vscarpenter vscarpenter released this 04 Sep 02:30
1c203c7
  • Trust an approval marker only when the managed approve workflow authored it
    (github-actions[bot]). A marker typed by a human is no longer Approval,
    whatever their repository association: only the workflow checks write
    access before minting Evidence. A repository that runs its own approve
    workflow must post the marker as the bot. Invariant 2 in CLAUDE.md and
    the architecture notes say so.
  • Remove run --retry, run --resume, and run --fresh. The one recovery
    entry is retry <n> --phase execute --run [--resume|--fresh], which, unlike
    the removed flags, also recovers an interrupted run.
  • Fix retry --run on an Execute Task reporting "marked ready for review" and
    sending the PR-ready notification while independent Review was enabled and
    the PR was still draft. It now prints the Review next action, as run does.
    The same renderer serves every command, so retry --phase review --run
    now sends the PR-ready notification exactly as review does, and amend's
    cancellation refusal uses run's wording with the --clear hint.
  • Fix two operator instructions: Execute's approval refusal names the full
    /machinist-execute <sha> form the workflow requires, and the Spec PR body
    no longer claims that AgentMachinist only watches the label.
  • Stop writing Task Run Evidence that no recovery path or report reads
    (ready_intended_sha, ready_observed_sha, review_required_sha,
    completion_comment_intended_sha, completion_comment_observed_sha,
    workspace_head, recovery_mode, pr_observed_base,
    pr_observed_number, pr_observed_sha, verification_log_dir,
    completion_duration_seconds, spec_recovery, resume_forbidden_reason)
    and record the instruction overlay under one vocabulary
    (instructions_sha256, instruction_paths, instruction_append) for Spec
    and Execute. Existing records keep the old keys as readable unknowns.
  • The Workshop owns Git-custody invocation. Workspace.git_custody() exposes
    the token provision captured and Workspace.resume(..., git_custody=)
    asserts it before any Git subprocess, refusing with "start a fresh retry"
    when the checkpoint has none; Execute's parallel custody layer is gone. A
    custody violation detected after the Harness surfaces as a WorkspaceError
    with the Workshop's message.
  • Verification Gate failures carry the engine's own message and report shape
    in Task Run errors instead of a second renderer with a different separator
    and excerpt length.
  • Internal simplifications with no operator-visible change: Harness adapters
    splice Harness._passthrough_argv() for model and extra_args; preview
    clones no longer write an ownership sidecar file; every Phase requires a
    Claim and takes plain boolean options; Spec decides existing-PR identity
    through repository custody and previews through the dispatcher; approved
    label metadata lives once in github.py; RunDisposition and
    WatchResult lose fields nothing read.
  • Correct invariant 7 in CLAUDE.md: a crash after push is reconciled without
    rerunning the Harness or the verification gates; gates rerun only when the
    crash happened before the implementation commit.

Install or upgrade:

uv tool install agentmachinist    # or: uv tool upgrade agentmachinist
machinist --version               # 0.13.0

Full changelog: https://github.com/vscarpenter/AgentMachinist/blob/main/CHANGELOG.md

v0.12.1

Choose a tag to compare

@vscarpenter vscarpenter released this 03 Sep 17:34
9d27cfe
  • Fix independent Review failing at "provision Review preview" with a misleading
    "outside managed workspace root" error. Review named its ephemeral clone
    review-issue-<n>, but Workspace only accepts preview clones named
    <repo>-preview-*; Review now uses preview-review-issue-<n>-<hex>, matching
    Spec. A regression test drives run_review_phase through a real Workspace.
  • Accept a Review report that a harness wraps in a Markdown fence or prefixes
    with a sentence, as long as it contains exactly one JSON object followed by
    nothing but whitespace or the closing fence. Two objects, trailing prose, or
    no object still fail closed with "review report must be valid JSON".
  • State the Review report contract in the prompt: exactly one JSON object with
    no fence or prose, and severity and confidence limited to low, medium, or
    high. A harness previously had to guess the allowed levels and could emit
    values such as "critical" that the parser rejects.

Install or upgrade:

uv tool install agentmachinist    # or: uv tool upgrade agentmachinist
machinist --version               # 0.12.1

Full changelog: https://github.com/vscarpenter/AgentMachinist/blob/main/CHANGELOG.md