CodaColaLight/nightmill

A lights-out development workflow for Claude Code: the maintainer reviews
issues and approves specs on a GitHub project board; agents do everything in between, in parallel,
in permanent worktree slots, and every step leaves the board showing the real state.
nightmill is a Claude Code plugin. It carries the process; a project carries its own values in one
file, .claude/nightmill.json.
## The flow
Backlog > Ready > Spec > Spec review > Approved > In progress > Review > Done
| Status | Meaning | Who sets it |
| Backlog | Filed, not reviewed | /story, the maintainer |
| Ready | Acceptance criteria reviewed; an agent may start the spec (or, for a bug, the fix) | only the maintainer |
| Spec | An agent is writing the spec | the agent |
| Spec review | The spec is merged as a docs PR; waiting for the maintainer | the agent |
| Approved | The spec is approved; any worker may implement it | only the maintainer |
| In progress | Being implemented or fixed | the agent |
| Review | A PR is open | the agent |
| Done | Merged or closed | the PR's Closes #N |
Bugs skip the spec: Ready > In progress > Review > Done.
Two gates belong to the maintainer, Ready and Approved. Everything else is an agent's job, and a
different agent can pick a story up at any stage because the board and the repository hold the state,
not a conversation.
## What is in the plugin
| Piece | What it does |
| /nightmill:spec [N] | Takes a Ready story and writes its spec as its own PR, sets Spec review and stops. |
| /nightmill:next [N] | Takes an Approved story and implements it: slot, tests, code, check, PR, auto-merge. With nothing Approved it lists the Ready stories and points to /spec. |
| /nightmill:fix [N\|all] | Fixes a bug: failing test first, smallest fix, one PR. all fixes every Ready bug, several at once (one per free slot, within the agent limit and the room), and ends with one table. |
| /nightmill:story | Turns a one-line idea into a story issue under the right epic, in Backlog. |
| /nightmill:status | One table of what waits for the maintainer and what is stuck: board items with their PR and CI state, every slot with what its agent is doing (running, stalled), stale states flagged. Read-only. |
| /nightmill:models | One table of each agent role's model, where it comes from (the config or the default), its rank and whether the reviewer pairings hold. Read-only. |
| /nightmill-slots [off] | Opens a read-only pane beside the chat with every slot and its agent (running, stalled, unknown), rereading them every panelRefreshSeconds; off closes it. Needs Claude Code 2.1.287 or later (see "Watching the run beside the chat"). |
| /nightmill:control | One pass of the opt-in load controller: measures the load and, in apply mode, raises or lowers the agent limit within the configured bounds; /loop 5m /nightmill:control runs it in a session. |
| /nightmill:check | Runs the project's check command and fixes the cause of a failure. |
| /nightmill:init | The install chat: detects what gh and the repository can tell, asks the rest one question at a time, shows one plan and, after one confirmation, creates the board with its columns view, the labels, the config, the issue forms, the CLAUDE.md snippet and the permission rules. |