From 66438e56c572d395384279792d11c255bc48752b Mon Sep 17 00:00:00 2001 From: Kirill Date: Tue, 20 Oct 2026 15:43:32 +0300 Subject: [PATCH] docs: render the README sequence diagram as SVG for npm npm doesn't render Mermaid code blocks, so the package page showed the diagram source. Replace the block with light and dark SVG files rendered by mermaid-cli, and keep the Mermaid source in assets/ to regenerate them. --- assets/how-iterward-works-dark.svg | 1 + assets/how-iterward-works.mmd | 16 ++++++++++++++++ assets/how-iterward-works.svg | 1 + packages/iterward/README.md | 22 ++++------------------ 4 files changed, 22 insertions(+), 18 deletions(-) create mode 100644 assets/how-iterward-works-dark.svg create mode 100644 assets/how-iterward-works.mmd create mode 100644 assets/how-iterward-works.svg diff --git a/assets/how-iterward-works-dark.svg b/assets/how-iterward-works-dark.svg new file mode 100644 index 0000000..2796e9f --- /dev/null +++ b/assets/how-iterward-works-dark.svg @@ -0,0 +1 @@ +AgentiterwardOrchestratorAgentiterwardOrchestratorHumannextdispatch (agent, message)messageDo the work, write the documentReply for the humanresultRead the status through the guard, follow the machineNext dispatch, or a stop with the human's movesStop summary and movesAnswer, gate decision, or transitionanswer, gate, or transitionHuman \ No newline at end of file diff --git a/assets/how-iterward-works.mmd b/assets/how-iterward-works.mmd new file mode 100644 index 0000000..a1d8f78 --- /dev/null +++ b/assets/how-iterward-works.mmd @@ -0,0 +1,16 @@ +sequenceDiagram + actor Human + participant O as Orchestrator + participant L as iterward + participant A as Agent + O->>L: next + L-->>O: dispatch (agent, message) + O->>A: message + A->>A: Do the work, write the document + A-->>O: Reply for the human + O->>L: result + L->>L: Read the status through the guard, follow the machine + L-->>O: Next dispatch, or a stop with the human's moves + O->>Human: Stop summary and moves + Human-->>O: Answer, gate decision, or transition + O->>L: answer, gate, or transition diff --git a/assets/how-iterward-works.svg b/assets/how-iterward-works.svg new file mode 100644 index 0000000..b8cc783 --- /dev/null +++ b/assets/how-iterward-works.svg @@ -0,0 +1 @@ +AgentiterwardOrchestratorAgentiterwardOrchestratorHumannextdispatch (agent, message)messageDo the work, write the documentReply for the humanresultRead the status through the guard, follow the machineNext dispatch, or a stop with the human's movesStop summary and movesAnswer, gate decision, or transitionanswer, gate, or transitionHuman \ No newline at end of file diff --git a/packages/iterward/README.md b/packages/iterward/README.md index 0a98e43..e47dcd4 100644 --- a/packages/iterward/README.md +++ b/packages/iterward/README.md @@ -55,24 +55,10 @@ Agents own execution. Iterward owns protocol. A dispatch can go to Claude Code, Your orchestrator drives the loop with two calls, plus one command for each human move. `next` prints the move the run needs. `result` hands the document the agent wrote to its guard, which returns the status, and follows the loop's machine to the status's target. The following diagram shows one dispatch and one human stop: -```mermaid -sequenceDiagram - actor Human - participant O as Orchestrator - participant L as iterward - participant A as Agent - O->>L: next - L-->>O: dispatch (agent, message) - O->>A: message - A->>A: Do the work, write the document - A-->>O: Reply for the human - O->>L: result - L->>L: Read the status through the guard, follow the machine - L-->>O: Next dispatch, or a stop with the human's moves - O->>Human: Stop summary and moves - Human-->>O: Answer, gate decision, or transition - O->>L: answer, gate, or transition -``` + + + Sequence diagram: the orchestrator calls next, carries the dispatch to the agent, reports the result, and relays the stop to the human. + The `iterward` CLI keeps each run's state in a `run.json` file and refuses any move the loop doesn't declare. The orchestrator doesn't interpret routing instructions: it carries each message to its agent and each result back to the CLI, and it can be an agent, a script, or you at a terminal. A sub-agent doesn't need the orchestration graph either. It receives one task, performs it, and writes one document whose frontmatter carries its status. The agent can still write a human-readable reply, but Iterward reads only the document, and only through your hooks.