The shortest build path
If your real goal is "show me how to build one," use this order:
- Read the exact route and field contracts.
- Compare against the shipped minimal fixture.
- Build your own
POST /state. - Build your own
POST /policy. - Build your own worker action behind
POST /v0/adapter/work-orders/claims. - Smoke test one admitted path and one blocked path.
That is the practical adapter-author path.
Start with the exact contract
Use the main API and protocol docs when you need field names, headers, and accepted wire shapes:
Use the practical adapter guide
When you are ready to build in code, the shortest technical path is:
That page is the implementation bridge between the public model and the actual route shapes.
Compare against the shipped fixture
If you want a concrete reference implementation, use:
Treat it as a fixture and template, not as a production adapter. The point is to show the contract in a small, inspectable form.
Build by replacement, not by reinvention
The easiest way to build your own adapter is usually:
- take the minimal fixture as the reference shape,
- replace its state logic with your own target read,
- replace its policy logic with your own admitted or blocked rules,
- replace its worker action with your own target-side effect,
- keep the host-side claim and outcome contract unchanged.
That is faster and safer than inventing a new protocol shape.
Choose the next page by the kind of example you need
03 - API Reference and 06 - External Adapter Protocol.
same three-role model from this section: StateProvider, PolicyBoundary, and a worker that only materializes after a claim. ImpactRoom is a reference shape, not a different protocol.
- If you want the smallest shipped example, start with
- If you want the exact wire-level contract, go straight to
- If you are picturing a reference adapter such as ImpactRoom, keep using the
Use the deeper technical pages selectively
When you are implementing one side at a time, these pages are the next layer:
What success looks like
You know your first adapter is real when you can show both of these:
performs the effect, and posts an accepted outcome
- blocked path: the host returns a real blocked decision and no work becomes claimable
- admitted path: the host returns an admitted decision, the worker claims work,
That is already enough to prove that you can build your own adapter on top of the v0.1.0 bundle.
The right mental model to keep
You are not extending the bundle from the inside. You are connecting your own system from the outside through a stable boundary.
That is why the bundle can be source-free and still useful. The integration surface is the HTTP protocol, and that is enough to build a real adapter.