Repository navigation
1.0.0 (2026-11-10)
Patchmill 1.0 is a rebuild. The old workflow engine is gone, and a small kernel takes its place: it starts Pi, claims issues, reads git and the issue host, and checks what the agent actually did. Everything that needs judgment, such as how to plan, code, review, and write, now lives in skills you can read and change. The production code went from 53,542 lines to 4,300.
On top of that kernel, this release adds two things we've wanted for a long time. You can now plan an issue with Patchmill in a chat, approve the spec from a dialog, and let a background worker build it. And you can run Patchmill without touching your tracker's labels at all. The skill pack also grew: frontend design with real HTML mockups, an independent frontend review, plain-English writing rules, and an implementation skill that always gets a fresh reviewer.
This is a breaking release. There is no upgrade path from 0.20 configuration or saved state. Read Upgrading below before you run it on an existing repository.
A skills-first kernel
- The kernel does five jobs and nothing else. It supervises the Pi process, claims and releases issues, derives the next phase from git and the host, verifies the outcome, and keeps branch and document names stable. Logs, result files, and approval labels never decide what happens next. Only pushed branches, merged pull requests, and open PRs do. (#329)
- Skills own the workflow. Triage, planning, and implementation are skill paths in
patchmill.config.json. To change how Patchmill plans or reviews, edit a skill, not TypeScript. (#329) - It's much smaller. Production TypeScript dropped by 92%, from 53,542 lines to 4,300, including both the GitHub and Forgejo adapters. Many of the 0.20 recovery fixes were for engine states that can no longer happen. (#329)
- Spec and plan gates are now planning pull requests. A required gate passes when its planning PR merges into base. The
spec-review,spec-approved,plan-review, andplan-approvedlabels are retired. Gates are off by default. (#329)
Interactive Issue runs
patchmill run-once --interactive [--issue N] opens a Pi console for one issue. It is the same Run-once workflow, but you are in the room. (#335)
- Planning happens in the chat. You talk the spec and plan through with the agent. When it's ready, one dialog shows the files, the branch, and 2–5 key decisions, rather than the agent's full summary. For a required gate you can Approve and open a planning PR, Approve without a PR (continue now), or Request changes. (#335)
- Implementation runs as a background worker. The chat stays open while a
pi-subagentsworker builds the change. If the worker gets blocked, its questions come to you in the chat, and your answer goes back to the same phase. (#335) - The run stays open until the PR merges. After the pull request is verified, the console waits for review. When it merges, Patchmill removes the issue's clean worktrees and local branches. (#335)
- Each issue has its own conversation. Type
/patchmill-issue <N>to switch to another issue. Reopening an issue resumes its newest session. A new issue never reopens another issue's chat. (#335) - Ask how it's going. The agent can show the current run, worker, wait, and estimated cost. Planning cost from the chat goes into the PR's cost report too. (#335)
--interactive is opt-in. Non-interactive runs work as before.
Local state mode
Set workflow.stateTracking to "local" and Patchmill keeps its workflow state on your machine, in the git-ignored .patchmill/state/, instead of in tracker labels and status comments. (#344)
- Upstream, Patchmill acts like one more person on the team. It posts questions that unblock work, opens pull requests, adds cost reports to PR bodies, and adds dependency links. It creates no labels, changes no labels, and posts no status comments. This makes it easy to try Patchmill on a repository you don't control, or one where the team doesn't want bot labels. (#344)
- Questions are the only issue comments. When an unattended run needs input, local mode posts just the question. The full stop summary stays in the local status history. (#344)
patchmill statusshows where everything stands. It groups issues by status without a sync, and reads live blockers for ready and in-progress issues. Same-repository blockers show their local status, for example#4 (Done, PR not merged). Use--allfor closed issues, or--issue Nfor one issue's full history. (#344)- Patchmill syncs before it decides. Triage and Issue runs sync issues first and stop before any claim if the sync fails. Damaged copies trigger a full sync, and state from another repository stops every read and write. (#344)
Local mode is for one user on one machine. The default is still "labels", and switching modes does not migrate state.
Native issue dependencies
- Blockers are now real tracker links. Triage adds GitHub Blocked by or Forgejo/Gitea Depends on links instead of a
blockedlabel. Automatic runs skip issues with open dependencies, and explicit runs refuse them. (#339) - Closing the last blocker is enough. The issue becomes eligible on the next selection, with no new triage, label change, or comment. Reopening a blocker reverses that. (#339)
Skills
- Frontend design with real mockups. When an issue changes something people see in the browser, planning adds a linked, offline, full-page HTML mockup to the spec. Backend, docs, and small copy changes skip it. (#323)
- An independent frontend review. After validation, a fresh reviewer checks the frontend against pinned local rules. The implementer fixes every valid finding and records the review in the PR. (#323)
- Plain-English specs and plans. The new
simple-englishskill applies Simplified Technical English rules to spec and plan prose: short sentences, active voice, one word for one meaning. (#274) - One implementation skill, with a reviewer that wasn't there.
patchmill-implementationreplaces the threesubagent-dev-*skills. It always asks a fresh reviewer, with stronger simplicity and readability checks, and waits for pull request checks before it marks the PR ready. (aa9227c) patchmill skills updateis back. It updates the managed skill pack to your installed Patchmill version, refuses to overwrite managed files you edited, and removes files the pack dropped. (47e7a95, #342)
Upgrading
There is no compatibility layer. Old configuration, saved workflow state, commands, and labels are not migrated.
- Start from the new configuration. See the README. Unknown keys fail by name. The
developmentEnvironmentandlandingskills,git.allowDirectLand, and the approval label settings are gone. Retired approval-label settings andlabels.blockedare accepted and ignored. - Point
skills.implementationat.patchmill/skills/patchmill-implementation, then runpatchmill skills update. set-specandset-planare gone. Gates are planning pull requests, or a chat approval in an interactive run.- Move blocked issues to native links by hand. For each issue with the old
blockedlabel: add its dependencies in the tracker, remove the label, and apply the ready label if it suits automation. Old comments do not create links. (#339) - Give each workflow status its own label. Config validation now rejects duplicate workflow label names, ignoring case. A shared label made statuses ambiguous. (#344)
- Rename old plans. Plans now end in
-plan.md, for example2026-10-01-issue-9-login-plan.md.
Dependencies and tooling
- Superpowers is now v7.0.2. Pi runtime packages are 1.5.1, and pi-subagents is 0.80.0. (#340, #345, #330)
- Dependency updates fail fast on stale runtime packages, reuse an open pi-subagents upgrade PR, and support compiled pi-subagents workflow checks. (#200, #202, a0f7723)
- The Superpowers updater now removes skill files that upstream dropped, and validation fails on installed files that the manifest does not list. (#342)
- The dev shell runs the checkout's CLI instead of rebuilding the package each time it starts. (a9008fd)
- The docs site has updated dependencies that clear audit advisories, including GHSA-7w5x-hrqm-74c2. (#214, #218, #221, #333, 1978053)