@spoolway/win32-x64 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,13 @@
   </picture>
 </p>
 
-Minimalistic command line state machine for turning coding agents into a pipeline you can actually reason about. No dependencies, terminal native. Runs headless or controls supported multiplexers. Worktree management and built-in support for GitHub's stacked pull requests.
+<p align="center">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/github/license/marvingygas/spoolway?style=flat-square&label=license&labelColor=3f3f46&color=18181b"></a>
+  <a href="https://github.com/marvingygas/spoolway/actions/workflows/ci.yml"><img alt="ci" src="https://img.shields.io/github/actions/workflow/status/marvingygas/spoolway/ci.yml?branch=main&style=flat-square&label=ci&labelColor=3f3f46"></a>
+  <a href="https://github.com/marvingygas/spoolway/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/marvingygas/spoolway?style=flat-square&label=release&labelColor=3f3f46&color=18181b"></a>
+</p>
+
+Minimalistic command line state machine for turning coding agents into a pipeline you can actually reason about. No dependencies, terminal native. Runs headless or in a supported multiplexer. Manages worktrees and opens GitHub stacked pull requests.
 
 Supported providers:
 
@@ -20,34 +26,33 @@ Supported multiplexers:
 
 ## Why
 
-Running one coding agent is easy. Running five is tab-juggling: which one is done, which
-one is stuck, and which one is quietly rewriting a file another one needs. The order lives
-in your head, and it stops the moment you look away.
+Running one coding agent is easy. Running five is hard: which one is done, which one is
+stuck, and which one is rewriting a file another one needs. The order lives in your head.
 
-It replaces the orchestrating agent that is supposed to keep everything together — and
-sometimes does. spoolway won't surprise you with a bill or an opinion.
+spoolway replaces the orchestrating agent that keeps everything together. It has no model
+inside, so it never surprises you with a bill or an opinion.
 
 ## Features
 
-- **A dispatcher with no model in it.** Every scheduling decision is mechanical — a
-  counter, a timestamp, a position in the pipeline file. It never drifts, costs nothing,
-  and is safe to interrupt at any point.
+- **A dispatcher with no model in it.** Every scheduling decision is a counter, a
+  timestamp, or a position in the pipeline file. It costs nothing and is safe to interrupt.
 - **Any mix of agents.** Each step names its own agent and model: a local model for
-  implementation, a cloud model for review, a shell command for the test suite.
-- **A worktree per task.** Every task builds on its own branch in its own checkout, so
-  parallel tasks never step on each other.
+  implementation, a cloud model for review, a shell command for the tests.
+- **A worktree per task.** Every task works on its own branch in its own checkout.
+  Parallel tasks never touch each other's files.
 - **Stacked pull requests.** A dependent task's branch is cut from its dependency's
-  branch, so a chain of tasks arrives as one ordered stack of PRs. Nothing merges itself;
-  you land the stack. Optional, and driven by **`spoolway stack`**.
-- **Session reuse.** A step can resume its prompt's earlier conversation instead of
-  paying to rebuild context, bounded by how full the model's window already is.
-- **Unattended runs.** Overnight, nothing parks for a person: blocked work is resumed by
-  an unblocker prompt, with an output-token ceiling as the brake.
-- **Trials.** Fork one task into an arm per pipeline and queue them together, then read the
-  arms side by side in eval.
-- **Routines.** Keep the tasks you run over and over in `.spoolway/routines/`.
-- **Eval built in.** Every lane's spend and outcome land in a ledger, so you can see what
-  your last pipeline edit did to pass rate and price.
+  branch. A chain of tasks arrives as one ordered stack of PRs. You land the stack.
+  Optional, driven by **`spoolway stack`**.
+- **Session reuse.** A step can resume its prompt's earlier conversation. It stops
+  reusing when the model's window is too full.
+- **Unattended runs.** Overnight, an unblocker prompt resumes blocked work. A token or
+  dollar ceiling stops the run.
+- **Trials.** Fork a group into one arm per task, each on its own pipeline, and compare
+  the arms in eval.
+- **Routines.** Keep the tasks you run more than once in `.spoolway/routines/`.
+- **Jobs.** Run a routine on a cron schedule. A running dispatcher fires it.
+- **Eval built in.** Every lane's spend and outcome go into a ledger. You see what your
+  last pipeline edit did to pass rate and price.
 
 ## Install
 
@@ -55,8 +60,9 @@ sometimes does. spoolway won't surprise you with a bill or an opinion.
 npm install -g spoolway
 ```
 
-A prebuilt binary, not a Node program — the package is a thin wrapper that runs it. Linux
-(x64, arm64, musl), macOS (Apple Silicon, Intel) and Windows (x64, experimental).
+The package is a small wrapper around a prebuilt binary. It runs on Linux (x64, arm64,
+musl), macOS (Apple Silicon, Intel) and Windows (x64, experimental). `spoolway update` shows
+what changed, and `spoolway whats-new` prints the release notes offline.
 
 From source instead, in a clone of this repository:
 
@@ -74,24 +80,20 @@ Platform notes and requirements in full: **[Installation and setup](docs/install
 spoolway init
 ```
 
-`spoolway doctor` checks that everything the configured pipeline needs is actually
-present, any time you want to confirm the project would run.
+`spoolway doctor` checks that everything the configured pipeline needs is present.
 
 ### 2. Plan, or create queueable spoolway tasks directly
 
-Tell the `/spoolway-plan` skill what you want built. It argues the shape with you until
-every question is settled, and writes the result as one plan page. Approve the page and it
-cuts the plan into tasks.
+Tell the `/spoolway-plan` skill what you want built. It talks the shape through with you
+and writes one plan page. Approve the page and it cuts the plan into tasks.
 
 <img src="docs/screenshots/plan.png" alt="a plan page written by /spoolway-plan">
 
-Already know the shape you want? `/spoolway-tasks` skips the argument and cuts the task
-documents straight away.
+If you already know the shape, `/spoolway-tasks` cuts the task documents straight away.
 
-**Both skills are optional.** A task is only a Markdown file in
-`~/.spoolway/<project>/pending/`, so anything that writes Markdown can produce one — an
-issue exporter, a script, or a model you already talk to. The following command prints
-the frontmatter a task document must carry:
+**Both skills are optional.** A task is a Markdown file in `~/.spoolway/<project>/pending/`.
+An issue exporter, a script, or any model can write one. This command prints the
+frontmatter a task document must carry:
 
 ```
 spoolway task contract
@@ -105,10 +107,10 @@ spoolway queue
 
 <img src="docs/screenshots/queue.png" alt="the queue screen">
 
-*The queue screen lists the groups on the left and previews the selected group's tasks on the
-right — `enter` queues what is checked and offers to start dispatching on the spot. `g` gates
-a task on the fly, `p` forks one across several pipelines as a trial, and `r` opens the
-repeatable tasks you keep in `.spoolway/routines/`.*
+*The queue screen lists groups on the left and the selected group's tasks on the right.
+Each task names its own pipeline. `enter` queues what is checked and offers to start
+dispatching. `g` gates a task, `p` forks a group into a trial, `s` saves a group as a
+routine, and `r` opens the routines in `.spoolway/routines/`.*
 
 ### 4. Dispatch
 
@@ -118,32 +120,30 @@ spoolway dispatch      # watch the board, and step in only where you are needed
 
 <img src="docs/screenshots/dispatch.png" alt="the dispatcher board">
 
-*One row per task, grouped by `group:`. The board says what each lane is spending as it
-spends it, what every queued task is waiting on, and which tasks are waiting on you — the
-paused one above passed a gated step. Tasks can be paused and resumed from the board.*
+*One row per task, grouped by `group:`. The board shows what each lane is spending, what
+every queued task waits on, and which tasks are paused for you. NEXT tells a lane holding a
+question apart from a task waiting at a gate. The bottom line shows the slots in use and
+every scheduled job with its next firing.*
 
 Every task on the board is in one of a few states:
 
 | State | Meaning |
 |---|---|
 | `queued` | Waiting for its dependencies and a free slot. |
-| `running` | An agent is working the task's current step right now. |
-| `waiting on you` | A lane ended its turn on a question; answering it is what moves the task. |
-| `paused` | Passed a gated step; you decide whether it goes on. |
-| `blocked` | Something needs a person. |
+| `running` | An agent is working the task's current step, or it has just moved there and a lane is starting. |
+| `paused` | Waiting for you on purpose: a gate, a question in its pane, or a park. `r` on the board resumes it. |
+| `blocked` | A step reported a block, or ran out of loops. Read the task's `## Blocker`, then `spoolway resume`. An unattended run hands it to the unblocker prompt instead. |
 | `unreachable` | A task it depends on is blocked, so it cannot start until you clear that one. |
 | `done` | Finished: the branch is handed over, the worktree removed, the task archived. |
 
 ### 5. Calibrate
 
-The `/spoolway-calibrate` skill reads your archived tasks and the spend ledger over them, and
-works out what actually cost you loops and money — a prompt that keeps sending work back, a
-step running on a model far bigger than it needs.
+The `/spoolway-calibrate` skill reads your archived tasks, their step-level evaluation results
+and the spend ledger. It compares them with the prompts, pipelines and settings that produced
+them. The comparison explains review failures, blocked sessions and wasted loops.
 
-It walks each finding with you, with the arithmetic behind it. The ones you keep are cut
-into tasks of their own, so the fix to your pipeline goes through the same line as
-everything else. This is how a pipeline that blocks constantly turns into one that runs
-unattended.
+It walks each finding with you, with the numbers behind it. It applies the prompt and pipeline
+changes you pick.
 
 ## A task is what travels the line, and you define it
 
@@ -164,8 +164,8 @@ depends_on:
 ## References
 ```
 
-**The frontmatter is spoolway's, the body is yours.** spoolway never reads the body; it is
-what the agent works from, written from a skeleton you own.
+**The frontmatter is spoolway's, the body is yours.** spoolway never reads the body. The
+agent works from it, and you own the skeleton it is written from.
 
 ## The pipeline is a file
 
@@ -181,7 +181,7 @@ steps:
     description: Write the code to satisfy the task's acceptance criteria.
     agent: pi
     prompt: implementer
-    model: qwen3-coder-30b
+    model: Ornith-1.5-35B-A3B
     session: true
     on_pass: review
     on_fail: blocked
@@ -202,7 +202,7 @@ steps:
     description: Bring the domain documents in line with what this task changed.
     agent: pi
     prompt: archivist
-    model: qwen3-coder-30b
+    model: Ornith-1.5-35B-A3B
     on_pass: handover
     on_fail: blocked
 
@@ -221,75 +221,150 @@ steps:
     on_fail: blocked
 ```
 
-**You do not have to write one by hand.** The `/spoolway-pipeline` skill writes a pipeline
-for you, and edits the one you already have.
+**You do not have to write one by hand.** The `/spoolway-config` skill writes and edits
+pipelines for you.
 
-## Configurable per project
+## Jobs
+
+A job runs a routine on a schedule. It has three parts: a cron expression, a pipeline, and a
+routine saved under `.spoolway/routines/`.
+
+The dispatcher fires a due job at the start of its pass. While any job is enabled, the
+dispatcher stays up on an empty queue. A `spoolway dispatch` left running overnight is all a
+job needs.
+
+```
+spoolway jobs              # the screen: write, edit, pause, delete, or fire a job
+spoolway jobs list         # every job, its schedule, and when it fires next
+spoolway jobs run <name>   # fire one now, ignoring its schedule
+```
+
+<img src="docs/screenshots/jobs.png" alt="the jobs screen">
 
-- Unattended mode delegates **`blocked`** tasks to a prompt you define. It clears
-  obstacles on its own and keeps your pipeline running while nobody is watching.
-- Set specific models for generating pipelines or pull request summaries.
+*The jobs screen. `n` asks for three things: the routine, the cron expression, and the
+pipeline. A job fires once per matching minute. It skips a window while its previous run is
+still in the queue. A window that passes while no dispatcher runs is not caught up later.*
+
+A job is a few lines of TOML in `~/.spoolway/<project>/jobs.toml`. Put one in
+`.spoolway/jobs.toml` inside the checkout to share it with the team.
 
 ```toml
-skills = ["spoolway-plan"]   # which skills `spoolway eval` gives a block of their own
+[jobs.nightly-audit]
+schedule = "0 3 * * 1-5"   # weekdays at 03:00, local time
+pipeline = "impl_fast"
+routine  = "nightly"       # a folder or a single .md under .spoolway/routines/
+```
+
+### Routines
+
+A routine is work you run more than once. It lives in `.spoolway/routines/`, tracked in git.
+Press `s` on a group in the queue screen to save it there, and `r` to browse and queue what is
+saved. Every queued copy gets a fresh id, so a routine can run again. The saved files are
+never changed.
+
+### Trials
+
+A trial answers one question: which pipeline does this task best? Press `p` on a group in the
+queue screen, pick a pipeline per task, and tick any steps to skip. Every task becomes one arm
+under its chosen pipeline, and all arms share one trial id. Compare them with
+`spoolway eval --runs --trial <id>`. An arm never pushes a branch or opens a pull request. When
+the last arm finishes, every arm's copy is removed. The source group and the ledger rows stay.
+
+## Issue tracker
+
+Event hooks sync tasks with an issue tracker. Sample scripts for GitHub and Jira ship with `spoolway init`.
+
+| Event | When it fires |
+|---|---|
+| `fetch` | `spoolway issue show <ref>` reads one issue out of the tracker |
+| `open` | `spoolway queue add` opens a ticket per document |
+| `queued` | A task arrives in the queue |
+| `blocked` | A task comes to rest on `blocked` |
+| `paused` | A task arrives on the persisted `paused` stage; a live-step row whose public state is `paused` does not fire it |
+| `done` | A task finishes |
 
+**The two shipped scripts are samples.** `spoolway init` writes `github.sh` and `jira.sh` into
+`.spoolway/hooks/`. A native Windows install gets the `.ps1` pair.
+
+See **[Issue Tracking](docs/configuration.md#issue_tracking--a-hook-fired-on-four-task-events)**.
+
+## Configurable per project
+
+- Unattended mode hands **`blocked`** tasks to a prompt you define, so the pipeline keeps
+  running while nobody is watching.
+- Set a model for generating pipelines.
+
+```toml
 [dispatch]
 backend = "herdr"            # herdr, tmux, or headless
 herdr_mode = "split"         # "split": a workspace per task; "grouped": one shared tab, a pane per task
-interval = "10s"
+tmux_mode = "grouped"        # "grouped": one session for the run; "split": a session per task
+worktree_root = ""           # where a task's worktree is cut; blank is ~/.spoolway/<project>/worktrees
+interval = "10s"             # how long the dispatcher waits between passes
 lane_quiet = "15m"           # silence before a lane is reminded to report
 default_pipeline = "default" # which pipeline a task runs when it names none
-auto_commit = true
+auto_commit = true           # commit a lane's leftover work when its step settles
 
 [unattended]
 enabled = true               # the overnight switch
-max_output_tokens = 0        # spend ceiling for a run with nobody watching; 0 is none
+max_output_tokens = 0        # output-token ceiling for a run with nobody watching; 0 is none
+max_cost_usd = 0.0           # dollar ceiling for the same run; 0 is none
 skip_blocked_lane = true     # a cleared block carries the task past the step it blocked on
 blocked_agent = "claude"     # who staffs `blocked` when nobody is at the keyboard
 blocked_model = "claude-opus-5"
 blocked_effort = "medium"
+blocked_session = true       # the unblocker carries its own earlier session forward
 blocked_prompt = "unblocker"
 
 [pipeline_gen]
 pipeline_agent = "claude"    # who `spoolway pipeline gen` opens its session as
 pipeline_model = "claude-opus-5"
 pipeline_effort = "medium"
-pipeline_auto = false        # false asks before writing the pipeline
-pipeline_local_models = false
 
-[update]
-check = true                 # tell a person at a keyboard that a newer release is out
+[housekeeping]
+update_check = true          # tell a person at a keyboard that a newer release is out
+calibrate_window = "14d"     # how far back `/spoolway-calibrate` reads
+retention_days = 30          # how long run records and archived tasks are kept; 0 keeps everything
+price_max_age_days = 30      # how old the price table may be before `spoolway doctor` says so
 
-[calibrate]
-window = "14d"               # how far back `/spoolway-calibrate` reads
+[agents.claude]
+kind = "claude"
+concurrency = 3              # most lanes of this profile at once
+session_reuse_ctx = 50       # % of the window before a carried session restarts fresh
+session_blocked_ctx = 0      # % of the window at which a running lane is stopped and blocked; 0 is off
+permission_mode = "auto"
 
-[stack.summary]
-agent = "claude"             # writes each PR's title and summary
-model = "claude-haiku-4-5"   # blank: the task file itself is the PR body
-prompt = "summariser"
+[agents.codex]
+kind = "codex"
+concurrency = 3
+session_reuse_ctx = 50
+session_blocked_ctx = 0
+permission_mode = "never"
 
 [agents.pi]
 kind = "pi"
-session_reuse_ctx = 50       # % of the window before a carried session restarts fresh
-
-[agents.claude]
-kind = "claude"
-concurrency = 3
 session_reuse_ctx = 50
-permission_mode = "auto"
+session_blocked_ctx = 0
 
-[models."*qwen3-coder-30b*"]
+[models."Ornith-1.5-35B-A3B"]  # a local model, served by llama.cpp
 context_window = 100096
-slots = 3                    # parallel lanes the local server can actually hold
+slots = 2                    # parallel lanes the local server can actually hold
 exclusive = true             # never alongside another exclusive model
+local = true                 # runs on hardware you own
+
+[issue_tracking]
+hook = ""                    # a script in .spoolway/hooks/, e.g. "github.sh"; blank runs none
+project_key = ""             # handed to the hook verbatim, e.g. owner/repo
+on_fail = "ignore"           # what a failing hook does: ignore it, or pause the task
+key_in_names = false         # prefix branch and worktree names with the tracker's slug
 ```
 
 See **[Configuration](docs/configuration.md)**.
 
 ## Eval every run
 
-Every lane's transcript is read when it settles and banked to a ledger: tokens, cost, wall
-time, and what the lane reported. Every edit to your pipelines, prompts or config mints a
+When a lane finishes, its transcript is read and written to a ledger: tokens, cost, wall
+time, and what the lane reported. Every edit to your pipelines, prompts or config creates a
 new version, so you can see what your last change did to pass rate and price.
 
 ```
@@ -298,13 +373,13 @@ spoolway eval
 
 <img src="docs/screenshots/eval.png" alt="the eval screen">
 
-*The eval screen on its runs view, one row per attempt at a task — `tab` cycles the four
-views: the version comparisons per pipeline and per step, this one, and what your skills
-came to. `f` filters, `e` exports CSV.*
+*The eval screen on its runs view, one row per attempt at a task. `tab` cycles the views: per
+pipeline, per step, runs, per watched directory, and per session outside the lanes. `f` filters,
+`e` exports CSV.*
 
 ## Documentation
 
-See **[Documentation index](DOCS.md)**. 
+See **[Documentation index](DOCS.md)**.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoolway/win32-x64",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "spoolway binary for win32 x64",
   "license": "MIT",
   "author": "Marvin Gygas",