Development

External / Ask review

Implement the library against the API contract from inception

Hats
3
Review Agents
3
Review
External, ask
Inputs
Inception, Inception

Dependencies

Inceptiondiscovery
Inceptionapi-surface

Hat Sequence

1

Builder

Focus: Implement the library to match the API surface exactly. Write code AND the tests that prove the contract holds. Public behavior is load-bearing — if the implementation doesn't match the documented surface, consumers will break when they upgrade.

Produces: Working code and tests that implement the unit's completion criteria.

Reads: API Surface, plan, existing project conventions, existing tests.

Anti-patterns (RFC 2119):

  • The agent MUST NOT deviate from the API surface signatures — if the signature needs to change, flag it for review and don't proceed
  • The agent MUST write tests that exercise the public API, not internal helpers
  • The agent MUST preserve the documented error model — error types are part of the contract
  • The agent MUST NOT introduce new public exports not in the API surface
  • The agent MUST keep internal-only symbols clearly marked (underscored, internal namespace, etc.)
2

Planner

Focus: Plan how to implement the library against the API surface defined in inception. Sequence the work so public-facing primitives are built first (they're the hardest to change later) and internal implementation follows.

Produces: Implementation plan with:

  • Module layout — how the internal code is organized, which files own which public APIs
  • Dependency graph — internal dependency order so foundational modules land before dependents
  • Test strategy — which layer each behavior is tested at (unit, integration, end-to-end contract tests)
  • Risk notes — anything in the API surface that's hard to implement without compromising the contract

Reads: Discovery, API Surface, existing project conventions.

Anti-patterns (RFC 2119):

  • The agent MUST NOT propose changes to the API surface at this stage — that contract is fixed
  • The agent MUST plan the public surface implementation before internal helpers
  • The agent MUST identify test strategy upfront, not defer it
  • The agent MUST NOT add dependencies not listed as acceptable in discovery
3

Reviewer

Focus: Review the implementation against the API surface and the completion criteria. The reviewer catches contract drift — places where the code "works" but doesn't match what was promised in inception.

Produces: Review verdict with:

  • Pass/fail per criterion — each completion criterion explicitly checked
  • Contract drift notes — any place the implementation diverges from the API surface
  • Test adequacy — whether tests cover the public API surface, including error cases

Reads: API Surface, code, tests, unit completion criteria.

Anti-patterns (RFC 2119):

  • The agent MUST NOT pass a unit where the implementation exports symbols not in the API surface
  • The agent MUST NOT pass a unit where error handling diverges from the documented error model
  • The agent MUST explicitly check tests cover the public API entry points
  • The agent MUST NOT approve code that depends on internal symbols from other parts of the library (layering violations)

Review Agents

Api Compatibility

Mandate: The agent MUST verify the implementation does not introduce breaking changes to the public API surface relative to what was declared in inception.

Check:

  • The agent MUST verify no public symbol was removed or renamed
  • The agent MUST verify no public signature was changed (parameter added, type narrowed, return type widened)
  • The agent MUST verify no error type was added or removed from the documented error model
  • The agent MUST flag any behavior change to an existing public entry point that would be observable to consumers (stricter validation, changed default, different ordering, etc.)
  • The agent MUST require an explicit semver impact note if any of the above are present

Correctness

Mandate: The agent MUST verify the implementation matches the API surface contract and the unit completion criteria.

Check:

  • The agent MUST verify every exported symbol matches the API surface signature (name, parameters, return type)
  • The agent MUST verify the error model matches: error types thrown match what the surface declares
  • The agent MUST verify no public symbol exists that's not declared in the API surface
  • The agent MUST verify all completion criteria have verification commands that pass

Test Quality

Mandate: The agent MUST verify tests actually exercise the public API in representative ways.

Check:

  • The agent MUST verify tests call the public API the way consumers would (not through internal backdoors)
  • The agent MUST verify tests cover each error path declared in the API surface
  • The agent MUST verify tests cover edge cases for every public entry point (empty inputs, boundary values, type edge cases)
  • The agent MUST flag tests that are tightly coupled to internal implementation and would break under legitimate refactoring

Development

Implement the library against the public API surface defined in inception. Public API stability is a hard constraint — any change that breaks the contract requires explicit review and a semver bump. Internal refactoring is free; public signature changes are not.

Completion Signal (RFC 2119)

Code MUST implement the full API surface from inception. Tests MUST cover the public API and its documented error modes. Any deviation from the inception contract MUST be flagged for review with a semver impact assessment.