Skip to content

feat: add the work command family - #225

Merged
outofcoffee merged 5 commits into
mainfrom
work-command-family
Sep 14, 2026
Merged

outofcoffee merged 5 commits into
mainfrom
work-command-family

Conversation

@outofcoffee

Copy link
Copy Markdown
Collaborator

The work items file — the backlog the orchestrator works — is worked from the shell: add an item, list the backlog's state, abort a running item, remove an item.

Summary

  • spinloop work add appends an item to the items file: the item's fields from flags (--id, --instructions, --dir, --tag, --priority), the file's validation applied, a duplicate id or an ended record refused, a missing file created with the one item
  • spinloop work list (alias ls) reports every item with its record from the state beside the file, in file order: state, node, started and ended — a dash where a value is absent, the state colour only on a terminal
  • spinloop work abort <id> stops a running item and puts it back in the backlog, through the abort marker the run's pass takes up; only a running item is abortable, and with no orchestrator running the command says so
  • spinloop work remove <id> takes an item out of the items file, its state, and its log; a running item is refused, naming the abort that goes first
  • The run converges on file-side changes: it drops a record the file no longer carries (and is not in flight), and an id the file let go can be worked again where its record has stood ended
  • Reference in docs/commands/work.md, pointers from docs/README.md and docs/work-items.md

Implementation details

The commands work the files directly and never take the run's lock: the file beside the items file is the whole hand-off, and a running orchestrator picks each change up on its next pass.

  • The abort channel is a marker directory beside the items file (<file>.aborts/<id>): work abort leaves one, and the run's pass takes it up — the agent stopped the way a clean interrupt stops it (the polite signal, the grace, then the hard end), the record removed, the marker gone, and the item not re-admitted on that pass.
  • work abort and work remove wait on a live run for the change to converge, bounded, and report the outcome — the bound running out, or the run dying mid-wait, are both named.
  • Where the run dies while a remove is pending, the command's own write of the state is the final word.

Builds on #205 (the orchestrator) and #204 (the work list API). The GitHub action that works the items file from issue events is tracked in #223.

Closes #206, #207, #208, #209.

@outofcoffee
outofcoffee marked this pull request as ready for review September 14, 2026 21:36
@outofcoffee
outofcoffee merged commit 38df707 into main Sep 14, 2026
3 checks passed
@outofcoffee
outofcoffee deleted the work-command-family branch September 14, 2026 21:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add spinloop work add

1 participant