| name | public-api-evolution |
| description | Design and review changes to Tilewright's durable core-library API, keeping adapters thin, data transformations explicit, compatibility intentional, and error behavior testable. |
| license | MPL-2.0 |
| compatibility | opencode |
| metadata | {"audience":"library-maintainers","workflow":"api-design"} |
Public API evolution
Use this whenever a change adds, removes, or materially alters public types, traits, functions, errors, serialization behavior, or cross-crate contracts.
Review sequence
- Define the caller's real use case without assuming CLI, MCP, OpenCode, or GUI concepts belong in the core.
- Identify the smallest domain operation that supports that use case.
- Establish input, output, invariants, failure modes, and mutation boundaries.
- Check whether unknown project data survives a read-modify-write round trip.
- Keep I/O separate from pure transformation where that improves testability.
- Prefer typed errors with useful context over strings or panics.
- Consider forward compatibility and pre-1.0 migration cost without freezing premature abstractions.
- Require examples, public docs, and focused tests for the contract.
Boundary test
A public core API is suspect if its vocabulary includes:
- prompts, agents, models, MCP tool calls, or OpenCode sessions;
- terminal formatting or CLI argument parsing;
- GUI state or commercial-edition concepts.
Those belong in adapters unless they describe an editor-independent domain concept.
Decision output
Return:
- proposed contract;
- alternatives considered;
- why the behavior belongs in the selected crate;
- data-preservation and error semantics;
- compatibility impact;
- required tests and docs;
- whether an ADR is warranted.
