A good first adapter

Start narrower than you think

A good first adapter usually has:

• one target_adapter
• one concrete target_ref
• one bounded target_scope
• one StateProvider response shape
• one admitted path and one blocked path
• one worker action

That is enough to validate the model without burying yourself in target-specific complexity.

What the first adapter should prove

Your first adapter should let you observe four things clearly:

• the host can call your StateProvider
• the host can call your PolicyBoundary
• an admitted decision becomes claimable work
• your worker can claim, materialize, and post an accepted outcome

If you can see those transitions clearly, the integration is already doing something real.

A real first-pass recipe

• Pick one target_adapter, one target_ref, and one target_scope.
• Make POST /state return one bounded target-state view.
• Make POST /policy return admitted for one case and blocked for one case.
• Start a worker that claims only for your target_adapter.
• Submit one intent with matching bindings.
• Verify admitted decision -> claim -> outcome.

That is a complete first adapter, even if it only supports one action.

Three concrete first-pass shapes

If you are thinking in terms of ImpactRoom, keep the first proof narrow in the same way: one state shape, one admitted path, one blocked path, one materialized effect. Do not start by trying to model the whole room system at once.

Example: repository adapter

One practical first adapter might look like this:

• target_adapter = github-pr-adapter
• target_ref = repo:example/project
• target_scope = branch:main
• /state reads branch and pull-request state
• /policy admits "open PR" when the branch is clean, blocks otherwise
• worker opens one pull request after a claim

That is enough to prove the pattern without trying to support every repository operation.

Example: ImpactRoom-style reference adapter

A room-shaped reference adapter can start just as narrowly:

• one room binding
• one state read for current room or turn state
• one policy candidate for one room-side effect
• one worker action that materializes only after claim

The important point is not the room model itself. The important point is that even a room-shaped target still fits the same three-role adapter pattern.

The shipped shortest path

If you want the smallest current starting point, use the shipped minimal target adapter.

It already demonstrates:

• one StateProvider callback
• one PolicyBoundary callback
• one worker claim loop
• one admitted path and one blocked path

That fixture is generic, which is useful. It lets you prove the contract first, then replace the generic state, policy, and worker logic with your own target logic one piece at a time.

What to avoid in the first pass

Do not start by adding:

• durable persistence
• multiple target families
• complex retry orchestration
• hosted identity
• a production queue model
• elaborate approval workflows

Those may matter later, but they are not the first proof you need.

The first proof is simpler: can your system provide state, return a policy candidate, and materialize a bounded effect only after a claim?