diff --git a/packages/iterward/README.md b/packages/iterward/README.md index 03e43c9..9bc748b 100644 --- a/packages/iterward/README.md +++ b/packages/iterward/README.md @@ -1,9 +1,44 @@ -# Iterward +

+ + + Iterward + +

LLMs do the work. Iterward decides what happens next. Iterward is a deterministic control plane for agentic engineering workflows. It moves routing, retries, approvals, failures, and stop conditions out of prompts and into a loop file and code that you can test. +## Install + +Iterward needs Node.js 22.18 or later and has no npm dependencies. Install it as a development dependency of the repository your loop works on: + +```bash +npm install --save-dev @push-based/iterward +``` + +The package gives you the `iterward` command, which you run as `npx iterward`, the engine, which a test imports from `@push-based/iterward`, the MCP server, the default loop, and the build-loop skill. To work on Iterward itself, see the [repository README](https://github.com/push-based/iterward#readme). + +To try Iterward without an install, run each command as `npx @push-based/iterward`, such as `npx @push-based/iterward init`. An install pins the version your runs use, and lets a test import the engine. + +## Quick start + +Node.js doesn't strip types from files under `node_modules`, so it can't load the default loop's `hooks.mts` where npm installs it. `init` copies the default loop into `loops/default/` in your repository. From the repository root, copy the loop, and start a run: + +```bash +npx iterward init +npx iterward new --config loops/default/default.loop.json --run runs/example/run.json --subject 'the settings page' +npx iterward next --run runs/example/run.json +``` + +`next` prints the first dispatch, the planner's standard message: + +```json +{"do":"dispatch","id":1,"agent":"planner","message":"Step: plan\nRun: runs/example/run.json\nDocument: runs/example/plan.md\nInputs:\n subject: the settings page\nNote: none\nFixes: none"} +``` + +To play each agent by hand through the gate, the build, and the verification, continue with [Run the default loop by hand](docs/tutorial.md). To start a loop of your own, change the copy, as [The default loop](examples/default/README.md) describes. + ## The problem A multi-agent workflow often keeps its control logic in prose: orchestration prompts, instructions in `AGENTS.md` files and agent definitions, conventions about which agent runs next, and ad hoc retry limits. This works for simple happy paths. It gets much harder to reason about once the workflow has to support human decisions, retries, partial failures, invalidated work, and resumed runs. @@ -114,36 +149,6 @@ The engine checks the run file on every call. These rules hold for every loop: For every rule and the terms it uses, see [Protocol rules](docs/protocol.md). -## Install - -Iterward needs Node.js 22.18 or later and has no npm dependencies. Install it as a development dependency of the repository your loop works on: - -```bash -npm install --save-dev @push-based/iterward -``` - -The package gives you the `iterward` command, which you run as `npx iterward`, the engine, which a test imports from `@push-based/iterward`, the MCP server, the default loop, and the build-loop skill. To work on Iterward itself, see the [repository README](https://github.com/push-based/iterward#readme). - -To try Iterward without an install, run each command as `npx @push-based/iterward`, such as `npx @push-based/iterward init`. An install pins the version your runs use, and lets a test import the engine. - -## Quick start - -Node.js doesn't strip types from files under `node_modules`, so it can't load the default loop's `hooks.mts` where npm installs it. `init` copies the default loop into `loops/default/` in your repository. From the repository root, copy the loop, and start a run: - -```bash -npx iterward init -npx iterward new --config loops/default/default.loop.json --run runs/example/run.json --subject 'the settings page' -npx iterward next --run runs/example/run.json -``` - -`next` prints the first dispatch, the planner's standard message: - -```json -{"do":"dispatch","id":1,"agent":"planner","message":"Step: plan\nRun: runs/example/run.json\nDocument: runs/example/plan.md\nInputs:\n subject: the settings page\nNote: none\nFixes: none"} -``` - -To play each agent by hand through the gate, the build, and the verification, continue with [Run the default loop by hand](docs/tutorial.md). To start a loop of your own, change the copy, as [The default loop](examples/default/README.md) describes. - ## Design a loop with an agent The build-loop skill turns a workflow you describe into a loop file and its hooks module. An agent following it drafts the whole loop first, asks you one decision at a time with a recommended answer, and checks the result with `compile`. The agent gets the skill from the MCP server's `build-loop` tool, or from `npx iterward build-loop`, which prints the same text. For the server, see [MCP server](docs/mcp.md).