Lesson 35 — Add a second adapter/environment without breaking the architecture

Outcome

Use a second provider strategy or execution environment as an architecture test: adding it should not require provider/runtime branches throughout Forge.

Why this comes now

An abstraction is not proven by its first implementation. The second implementation exposes where we accidentally coupled concepts.

Understand

Choose based on real need. A second Agent Strategy is likely more valuable first; a second Execution Environment (Docker/SSH) comes only if your workflow needs it. The existing contract suite should do most of the behavioral validation.

When capabilities differ, the UI/domain should naturally enable/disable behaviors through capability semantics rather than if provider == ....

Build the real project

1. Choose one new Driver/Strategy or Environment.
2. Document its actual protocol/lifecycle differences from the first.
3. Implement through existing boundary.
4. Run shared contract suite.
5. Add only new capabilities that correspond to real semantic differences.
6. Search codebase for provider/runtime-name conditionals; justify or remove them.
7. Revisit interfaces that became awkward and simplify them while keeping canonical docs current.

Completion gate

Second integration works without changing Task lifecycle or React feature logic around provider names. Unsupported capabilities produce intentional UI behavior. Contract suite catches semantic gaps.

Pitfalls to avoid

Do not preserve a bad abstraction simply because “the ADR says so.” ADRs explain decisions; evidence from a second implementation can justify change. Do not create a public plugin API yet.

References

OpenHands environment separation: https://docs.openhands.dev/openhands/usage/sandboxes/overview ; Mux runtimes: https://github.com/coder/mux/blob/main/docs/config/policy-file.mdx ; Emdash remote/worktree overview: https://github.com/generalaction/emdash

Checkpoint

At this point the course becomes normal product development. Create feature plans from actual needs and continue using the documentation/status discipline rather than extending the course speculatively.