@consultancy-outfit/ai-draftsman-cli 2.0.0 → 2.2.0

package/README.md

@@ -166,11 +166,85 @@ ad connectors call slack chat.postMessage --params '{"channel":"#dev","text":"bu
   `mcp__aidraftsman__call_connector`. Grant actions with `--allowedTools mcp__aidraftsman` (or
   `mcp__aidraftsman__call_connector`, or `call_connector`).
 
+## Several agents at once
+
+These work in an interactive session (`ad`). `ad -p` is unchanged: it offers none of these tools.
+
+| Command | What it does |
+|---|---|
+| `/spawn [name:] <task>` | Start a background agent on a task, e.g. `/spawn reviewer: check the auth changes` |
+| `/workers` | Status board: queued / running / done / failed, time, tool uses, tokens, what each is doing. Enter opens one. |
+| `/workers <name>` | One agent in detail: its task, recent steps, messages and final report |
+| `/msg <name> <text>` | Send an agent a message (a finished agent wakes up to handle it) |
+| `/stop <name\|all>` | Stop one agent, or every running one |
+| `/coordinate [--eager] <goal>` | Split a big goal into parallel agents, then merge their results. `/coordinate off` stops it |
+| `/code-review [ref]` | Review your uncommitted changes, or everything that differs from a branch, commit or range |
+| `/rewind` | Undo: go back to before an earlier prompt |
+| `/side [--edit] <question>` (or `/btw`) | Ask on the side, in a split view, while the main agent keeps working. `Ctrl+O` switches where you type |
+| `/sessions`, `/send <session> <text>` | See other `ad` sessions on this machine, and message one |
+
+**Background agents.** Each has its own conversation and keeps working while you carry on. The status line shows
+`⚙ 2 running · 1 done`. When one finishes you get a notice, and its report goes to the main agent with your next
+prompt. The main agent can start agents itself (`spawn_agent`), and agents talk to each other and to the main agent
+with `message_agent` / `list_agents`: a message reaches its recipient before its next step. Agents use your current
+permission mode and ask through the same prompt, labelled `[name]`. Their edits count toward `/rewind` and their token
+use toward `/usage`. They run at most 3 at once (the sub-agent limit below), 8 can be alive, a team may send 200
+messages in all, and an agent cannot start other agents.
+
+**`/coordinate`.** The main agent plans, splits the goal into 2-5 independent tasks, starts an agent for each and stops.
+When every agent has finished it is woken automatically with their reports, checks them against the goal, follows up on
+anything that failed, runs your tests if code changed, and gives one answer. At most 5 rounds; it switches itself off
+if the agent decides the task is too small to split. By default it waits for *all* agents, so one slow agent delays the
+rest. `/coordinate --eager <goal>` wakes it as *each* agent finishes instead: it is told how many are still running,
+acts on the early reports, and holds the final answer until all are done (up to 12 rounds, since it wakes more often).
+
+**`/code-review`.** A read-only `reviewer` agent gets the diff (plus any new files git does not track yet) and reports
+problems by severity with file:line, how to trigger each and a fix: correctness, security, error handling, races,
+tests; not style. The findings are printed when it finishes. `ref` is a branch, tag, commit or range
+(`main`, `HEAD~3`, `origin/main..HEAD`); a diff over 60,000 characters is cut and the reviewer is told. Needs git.
+
+**`/rewind`** (also `/undo`). A checkpoint is taken at every prompt. Pick one and choose **Code + conversation**,
+**Conversation only** or **Code only**. Files the agent created are removed and edited files return to how they
+were. Rewind points are saved with the session, so they come back after `/resume`.
+
+*Shell commands.* Inside a git repository, what a command changed is undone too: the work tree is snapshotted before
+and after each shell command, and only the files that command changed are put back, so your own edits are left alone.
+This uses a scratch git index, never your real index, HEAD, branches or stash; it does add a few loose objects to
+`.git/objects` (`git gc` removes them) and costs one snapshot before and after each command. Line endings and
+`.gitattributes` filters are switched off for it so files come back byte for byte. Outside a git repository, or if
+git is slow or fails, the command still runs but is **not** undone, and `/rewind` tells you how many were not
+tracked. Things to know: files changed *while* a command ran (by you, or another agent) count as that command's;
+ignored files (`.gitignore`) are not tracked; files over 5 MB changed by the file tools are not saved (it tells you);
+the saved rewind points are capped at 48 MB per session (oldest dropped first); and `/clear` and `/compact` forget
+them. A repository large enough for a snapshot to take over 8 seconds turns shell tracking off for the session.
+
+**Messages between sessions.** Sessions on one machine see each other through a small folder in the config
+directory (owner-only; no server). `/sessions` lists them; `/send web the API now returns 201` delivers to the one
+whose id or title matches. The agent can do the same with `list_sessions` / `send_to_session`. A message appears as
+`✉ message from session …`. If that session's agent is mid-turn it reads the message before its next step; if it is
+idle the message reaches it with that user's **next prompt**. It never starts a turn by itself, so a person is always in
+the loop. Messages are capped at 8,000 characters and 50 unread per session.
+
+**Side sessions and split view.** `/side <question>` (or `/btw`) opens a second, separate conversation next to the main
+one, for something you want to ask without interrupting it. It is given the main conversation so far as context (the
+newest ~12,000 characters of what you and the agent said, without tool output), it is read-only unless you start it with
+`--edit`, and the main agent keeps working meanwhile. While it is open it is shown in a pane in the live area: beside the
+main area on terminals at least 110 columns wide, under it on narrower ones. The prompt box types to one of the two: the
+status line says `→ typing to side` when it is the side session, and **Ctrl+O** switches (so do `/side` and `/side main`).
+`/side show` prints the whole side conversation, `/side send` passes its last answer to the main agent with your next
+prompt, and `/side close` ends it (so does `/clear`, since it was given the old conversation). There is one side session
+at a time: another `/side <question>` continues it. It counts toward the 8-agent limit and shows in `/workers`, but it is
+a conversation, not a job: it does not report back to the main agent by itself and is not part of `/coordinate`. Only
+the live area is split; the main transcript still scrolls in your terminal's own history.
+
+**Not yet:** chatting inside a *background agent's* own conversation (you can read it and message it; use `/side` for a
+conversation of your own), and sessions on different machines.
+
 ## Load and limits
 
 The agent is shaped to be light on the shared gateway:
 
-- **Sub-agents** run at most 3 at a time (`ad config set maxParallelSubagents 2`, or `AD_MAX_PARALLEL_SUBAGENTS`). A server that returns `capabilities.max_parallel` on `/v1/agents` caps it.
+- **Sub-agents** (and background agents) run at most 3 at a time (`ad config set maxParallelSubagents 2`, or `AD_MAX_PARALLEL_SUBAGENTS`). A server that returns `capabilities.max_parallel` on `/v1/agents` caps it.
 - **Sub-agent model:** under Auto, built-in sub-agents use `aidraftsman/auto-fast` when the server lists it in `/v1/models` (checked once per session), and Auto otherwise. Choose one yourself with `ad config set subagentModel <slug>` (or `AD_SUBAGENT_MODEL`); `inherit` keeps the main agent's model.
 - **Step limits:** 40 model steps per turn (`maxSteps` / `AD_MAX_STEPS`) and 15 per sub-agent (`subagentMaxSteps` / `AD_SUBAGENT_MAX_STEPS`). An interactive session asks whether to continue; `ad -p` stops cleanly.
 - **Headless runs** (`-p`, `--output-format json`, or stdout not a terminal) send `x-ad-automation: headless` and `x-ad-client-class: cli-automated`; interactive sessions send `x-ad-client-class: cli-interactive`. Every step of a turn sends the same `x-ad-run-id`; sub-agents add `x-ad-parent-run-id`.