@sleds/cli 0.1.25 → 0.1.27

package/README.md

@@ -50,6 +50,44 @@ Inside Claude Code:
 
 Nothing changes until a wall.
 
+## Routes and the engine
+
+An item can have a route: its work split into nodes, each one session on its own branch, each waiting on the nodes before it. Draft one with the `route` tool; read and run it from here.
+
+```
+sleds route QW-142                    the nodes, what each waits on, what is ready, where each run can be watched
+sleds route QW-142 --dot | dot -Tpng -o route.png    the same route as a Graphviz picture
+sleds route run QW-142                run this one item's route here until it lands, then exit
+sleds engine                          the long-running loop over every route Run armed on your sled
+sleds engine --jira EPIC-7            the same loop over a Jira epic's Blocks links, no SLEDS route needed
+```
+
+For each ready node the engine makes a worktree, starts an agent session on the node's branch (default `route/{item}-{node}`), and follows its PR to the merge: CI failures and review feedback go back to the session; a merge lands the node, closes the session, removes the worktree and, on Jira, moves the issue to Done. Stopping the engine leaves its sessions running — the next start picks them up from its state file. `sleds route run` keeps its own state file, so it can run beside a `sleds engine` on the same box.
+
+Where each node runs is `--runner`:
+
+```
+tmux       the default — any terminal; one detached session per node, `tmux attach -t <name>` to watch
+headless   Claude Code's -p with no terminal; the transcript goes to a file beside the prompt, nothing goes in
+command    your own launcher: --runner-cmd '<shell template>' with {prompt} {cwd} {name} {branch} {agent};
+           it must block until the session ends, or the node reads as exited at once
+orca       for people who run agents in Orca: Orca makes the worktree and starts the agent in its terminal
+```
+
+The flags `sleds route run` and `sleds engine` share:
+
+```
+--at-once <n>             sessions at once (default 1; one per seat)
+--agent '<command>'       the agent CLI each session starts (default Claude Code); its flags go in the command
+--mode <permission-mode>  Claude Code's (default auto); refused with --agent
+--model <id>              Claude Code's model; refused with --agent
+--branch '<template>'     the node's branch: {key} {ticket} {item} {node} {slug}, e.g. 'feature/{key}-{slug}'
+--pr-title '<template>'   the PR title: {key} {ticket} {item} {node} {title}, e.g. 'feat: [{key}] {title}'
+--repo <path> | --repos-dir <dir>   where the node's repo is checked out
+```
+
+`sleds engine` also takes `--name <n>` (default the hostname; it signs as `engine:<n>`), `--interval <s>`, `--lease <min>`, `--idle <min>` (default 20: a session showing nothing new and no PR has ended) and `--once` for a single tick. `--jira` reads `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_TOKEN`. `sleds help` has the full list.
+
 ## Docs
 
 Repo: github.com/spdyadam/sleds · Site: sleds.ai