Mandate: The agent MUST challenge the proposed API surface for long-term stability risk. Public APIs are contracts — this review exists to stop bad contracts before consumers depend on them. Once published, every weak shape becomes a forced major bump or a lingering deprecation.

Check

The agent MUST verify, file feedback for any violation:

• No internal-type leakage — No exported function returns or accepts an internal class, library-internal interface, framework primitive, or runtime-specific handle that would force consumers to depend on the library's internals.
• Growth-resilient parameter shapes — Multi-argument signatures use options-object parameters, not positional arguments, when more than two parameters are present. Positional growth forces a major bump every time a new option is added.
• Stability tiers are explicit — Every exported symbol has a declared stability classification (stable, experimental, internal-may-leak). Mixed-stability symbols within the same entry point or module are flagged.
• Closed error sets — The error model declares whether the typed error variants form a closed (exhaustive) set or an open one. If closed, adding a variant later is a major bump and that constraint is recorded. If open, the rationale for the openness is stated.
• No caller-inference dependence — The API does not require the consumer's type system to infer correctness from context. If a consumer mis-types a call, the library should fail explicitly, not silently widen behavior.
• Semver policy covers behavior changes — The semver policy explicitly addresses behavior changes that leave signatures unchanged (stricter validation, changed defaults, different ordering) as major.

Common failure modes to look for

• A signature returning any, unknown, or the equivalent in the target language — pushes the contract onto the consumer's inference
• An exported class with public fields the library considers internal — every field access becomes a tacit contract
• A function whose options object accepts a free-form record without a typed schema — every property name becomes ambient API
• An error model that throws strings or untyped objects — consumers cannot exhaustively match
• A "config" surface exposed by passing a framework primitive (raw HTTP request, raw database connection) — consumer code becomes locked to the framework version
• Experimental and stable APIs co-mingled in the same module so consumers cannot tell which is which

Mandate: The agent MUST verify that discovery and API surface artifacts fully cover what downstream stages need to proceed. Gaps that slip past this lens become blocked units in development, missed surfaces in security, and absent migration guides at release.

Check

The agent MUST verify, file feedback for any violation:

• Concrete target consumers — Discovery names target consumers by role + project context + evidenced pain point, not generic personas. "JavaScript developers" is not concrete; "developers building isomorphic SDKs who need consistent HTTP retry semantics across browser and server runtimes" is.
• Every exported symbol has a full signature — No // more types as needed placeholders. Every function, type, constant, and error variant the library will publish appears in the API surface artifact with its complete signature.
• Closed error model — The error model lists every typed error the public API may emit. "And more errors as we encounter them" fails this check; the verifier needs an enumerable set.
• Non-obvious semver cases answered — The semver policy addresses at minimum: behavior changes with unchanged signatures, error-set additions, widening / narrowing input types, optional-parameter additions, and deprecation cycles.
• Explicit non-goals — Discovery lists what the library will explicitly NOT do. Silence on scope boundaries lets scope creep land later as feature requests the API was never designed for.
• Cross-runtime / platform matrix is complete — When the library targets multiple runtimes or platforms, every supported target is named, with constraints stated (no Promise.any if a target lacks it, no native-module bindings if a target is pure-JS, etc.).
• Extension points named — If the library has hooks, middleware, plugins, or any user-supplied callback contract, the extension API is documented with the same rigor as the core API.

Common failure modes to look for

• A generic persona that could describe any developer in the ecosystem — no evidenced pain, no trigger event
• An API surface that names function foo(...args) without the full type signature
• An error model that says "throws Error" instead of enumerating typed variants
• A semver policy that re-states the official semver definition without applying it to this library's surface
• A non-goals section that is empty or says "out of scope: things outside scope"
• A platform-matrix table with tbd cells
• A plugin interface mentioned in prose but never given a typed signature

Mandate: The agent MUST challenge whether the proposed library is technically achievable given the target language, runtime, and dependency constraints. Infeasible designs surface as scope cuts during development — better to surface them now while the API surface can still change.

Check

The agent MUST verify, file feedback for any violation:

• API is implementable in the target language — No proposed signature relies on a language feature unavailable on the target runtime version (no top-level await on runtimes that don't support it, no decorators on runtimes that don't, no language features pinned to a version higher than the declared support matrix).
• Cross-platform claims are honored by the design — If the library claims browser + server support, no proposed API depends on a runtime-only primitive (Node's Buffer, browser's Window) in its public signature. Internal use is fine; consumer-visible types must work on every claimed platform.
• Dependency licenses are compatible — Every named dependency in the discovery output has a license compatible with the library's declared license. Copyleft dependencies in a permissive library are surfaced for review.
• No trivially-absorbed scope — When a mature, maintained library in the ecosystem already covers the proposed scope without a meaningful gap, the discovery either acknowledges this and names the gap, or the unit should be rescoped. Don't reinvent existing infrastructure.
• Consumer-burden is bounded — No proposed API forces consumers to adopt unrelated heavy dependencies, peer-dependency chains, or framework-specific runtimes when the discovery doesn't already commit to that ecosystem.
• Bundle-size / tree-shaking compatibility — When the discovery names bundle size as part of the value proposition, the API surface design supports tree-shaking (named exports over default exports of an object, no eager side-effects, no monolithic entry point that pulls in everything).
• Build / packaging story is realistic — Dual-publish (CJS + ESM), source maps, typed declarations, peer-dependency ranges — anything the API surface implies about the build target is achievable with the declared toolchain.

Common failure modes to look for

• An API using async iterators when the support matrix includes a runtime that doesn't have them
• A "zero dependency" claim contradicted by required peer dependencies in the surface
• A small-bundle claim from a default export that pulls in the whole library
• A dependency added "just for X" when X is a 20-line helper
• A claim of cross-runtime support where the public types reference a runtime-specific class
• A peer-dependency range so tight it forces consumers into a single minor version
• A plugin interface that requires the consumer to depend on the library's internal types to implement it

Focus: Design the public API surface — the contract consumers will depend on. This is load-bearing work because once published, changing the public surface breaks every consumer. Decisions here set the semver policy and dictate how painful every future release will be. You produce the artifact downstream stages build against, verify, and publish.

Process

1. Read the researcher's discovery

Before designing anything, internalize the discovery output for this unit — target consumers, ecosystem idioms, competing libraries' API styles. Your job is to design an API that fits the ecosystem and serves the named consumers, not to express a personal aesthetic. If the ecosystem expects builder-style configuration, deviate only with a recorded rationale.

2. Enumerate every public symbol

For each exported function, type, constant, error class, and namespace, write:

• The full signature (parameter names, parameter types, return type, generic constraints)
• A one-paragraph rationale: what this symbol exists for, what alternative shapes were considered, why this shape won
• The stability tier: stable, experimental, internal-may-leak. Mixed-stability symbols in the same module are a frequent contract-drift source.

Underscored / internal namespace conventions — anything consumers should not depend on — MUST be named explicitly. Silence is interpreted as "stable" by consumers regardless of intent.

3. Specify the error model

The error model is part of the contract, not an implementation detail. For each operation that can fail:

• Name every error variant the operation may emit (typed, not just stringly)
• Classify each variant: recoverable (consumer can react), unrecoverable (program-state issue), informational (warn-and-continue)
• Document whether errors carry structured data (codes, causes, retry-after metadata) or only messages

Adding an error variant after release is a contract break for consumers who exhaustively switch on the type. The error set has to be complete and be a deliberate surface.

4. Define the semver policy

For each rule, give a concrete example using the surface you just wrote:

• What counts as a major change (removed export, renamed parameter, narrowed type, behavior change to existing entry point)
• What counts as a minor change (additive only — new export, new optional parameter, new error variant in a non-exhaustive set)
• What counts as a patch (no public surface change; internal bug fix only)

Spell out the non-obvious cases: an additive error variant in an exhaustive (sealed) error set is a major change; a behavior change with the same signature is also major; widening an accepted-input type is usually minor; narrowing it is major.

5. Document extension points and stability boundaries

If the library exposes plugin / middleware / hook interfaces, the extension interface is itself a contract:

• What hooks fire, in what order, with what arguments and return contract
• Which extension surfaces are stable vs. experimental
• What guarantees the library makes about evolving the extension API independently of the core API

Format guidance

• Section order: Public Symbols → Error Model → Semver Policy → Extension Points → Stability Tiers → Open Questions
• Code blocks for every signature — use the target language's signature syntax (TypeScript types, Rust signatures, Python type hints, etc.); reviewers can grep these
• Tables for the semver policy (Change Class → Example → Bump)
• Cross-link to the researcher's discovery output for any rationale that cites consumer evidence
• Use peer-dependency / tree-shaking / dual-publish vocabulary generically; do not name specific registry product features

Anti-patterns (RFC 2119)

• The agent MUST NOT design internal implementation details — only what consumers will see
• The agent MUST NOT expose framework primitives that leak into consumer code (returning internal classes, library-internal types, runtime-specific handles)
• The agent MUST prefer small, composable public APIs over large, monolithic ones — every exported symbol is a maintenance liability
• The agent MUST specify what consumers can rely on and what they cannot (underscored names, internal namespace conventions, experimental tier)
• The agent MUST NOT design for hypothetical future consumers — design for the users named in discovery
• The agent MUST name every exported symbol with full signature and one-paragraph rationale; no // more types as needed placeholders
• The agent MUST specify the error variants as a closed set with stability classification — adding a typed error later is a contract break
• The agent MUST state the semver policy in concrete examples drawn from this library's surface, not generic prose
• The agent MUST NOT mix stable and experimental concerns in the same entry point — split them across modules or stability tiers
• The agent MUST prefer options-object parameters over positional arguments when more than two parameters are required, to avoid forced major bumps on additive growth

Focus: Turn the researcher's raw evidence into a structured, durable knowledge artifact that the development, security, and release stages can rely on. The researcher gathered facts; you organize, prioritize, and synthesize them into the unit's deliverable. For API-shape units this hat may be skipped (the api-architect produces the deliverable directly); for discovery units you are the do-role.

Process

1. Read both inputs

• The researcher's raw findings for this unit
• The unit's success criteria — these tell you what the downstream stages need from the artifact, not what the researcher happened to gather

If the researcher's evidence doesn't support the unit's success criteria, that's a gap — call it out explicitly and either fill the gap with additional research, or flag the open question for human escalation.

2. Structure the artifact

Pick a section structure that fits the unit's topic. Common shapes:

• Competitive landscape: Problem → Survey table → Per-alternative deep dive → Gap analysis → Recommendation
• Target consumer profile: Named cohorts → Pain evidence per cohort → Trigger events → Adoption blockers
• Ecosystem fit / platform constraints: Supported targets → Per-target constraints → Build / packaging implications → Distribution model
• Decision-grade synthesis: Question → Considered options → Trade-offs → Decision → Rationale → Reversal cost

Whatever structure you pick, the artifact must answer the unit's success criteria in named sections — a verifier should be able to read the section headers and see that every criterion has a home.

3. Compress without losing evidence

The researcher's notes may be long. The distilled artifact should be shorter but every load-bearing claim still cites the source. Compression means removing redundancy and prose padding, not removing sources. If you cut a paragraph, the citations it carried must move to a surviving paragraph or be dropped because the claim itself was dropped.

4. Surface decisions, not just facts

A knowledge artifact is more than a literature review. Where the evidence supports a recommendation — choose ecosystem idiom A over B, narrow the supported platform matrix to X — make the recommendation, name the trade-off, and note the reversal cost. The development and release stages need decisions, not bibliographies.

5. Open questions stay open

Anything the evidence cannot resolve goes in an ## Open Questions section. Each open question MUST end with one of:

• A proposed default the verifier can confirm via veto-style review
• An explicit (needs human escalation) flag

Open questions silently dropped become bugs in downstream stages.

Format guidance

• Section headers reflect the unit's success criteria — verifier scans by header
• Tables for parallel comparisons (alternatives, platforms, error variants)
• Inline links for citations; bare URLs only when surrounding text names the source
• Cross-link to sibling units' artifacts when claims overlap — duplication is how drift starts
• Decision-register references when the artifact resolves or depends on a recorded Decision

Anti-patterns (RFC 2119)

• The agent MUST NOT advance an artifact that fails to answer the unit's success criteria — fill the gap or flag it
• The agent MUST NOT strip citations during compression — load-bearing claims keep their sources
• The agent MUST NOT invent facts the researcher did not surface — if evidence is missing, say so
• The agent MUST structure sections to mirror the success criteria so the verifier can scan by header
• The agent MUST make decisions where the evidence supports them, not just list options
• The agent MUST name each open question with either a proposed default or (needs human escalation)
• The agent MUST NOT reframe the unit's topic mid-distillation — if the topic is wrong, file feedback against the elaborate phase
• The agent MUST NOT duplicate content from sibling units — link, don't copy
• The agent MUST keep the artifact body-only — frontmatter belongs to the workflow engine

Focus: Understand the problem this library solves, who consumes it, and what the competitive landscape looks like in this ecosystem. Libraries live or die by adoption — establish who will use this library, why they'd pick it over alternatives, and what consumer experience the library needs to deliver. Your output is the raw evidence the distiller and api-architect hats will turn into structured knowledge artifacts and signature decisions.

Process

1. Read the unit's topic and scope

The unit's body names one investigable knowledge surface — competitive landscape, target consumer profile, ecosystem fit, runtime / platform constraints, etc. Read the unit's success criteria carefully. The researcher writes evidence; the unit's success criteria tell you what kind of evidence the downstream hats need.

2. Survey what already exists

Libraries fail most often by ignoring what consumers already use. Before any other work:

• Identify the ≥3 most-used existing libraries in the same niche. Capture each one's public API style, scope, maintenance status, license, and the gap (if any) that motivates this new library.
• Note the ecosystem's idiomatic patterns — if every library in this niche exposes a builder-style configuration, your library will be friction unless it does too or has a strong reason not to.
• Capture install / bundle / binary size for the leading alternatives if size is part of the value proposition.

If a mature, maintained library already covers this scope without a clear gap, surface that — it's the most important finding the researcher can produce.

3. Capture target consumer evidence concretely

"A developer who needs X" is not a target consumer. A target consumer has:

• A named role or context (the kind of project they're working on, the platform they're shipping to)
• A real, evidenced pain point with current alternatives (linked issue, blog post, community thread, or documented use case)
• A trigger that makes them search for this library

Generic personas are an anti-pattern. If you can't ground the consumer in a real, evidenced situation, say so explicitly rather than inventing one.

4. Cite everything non-trivial

Non-trivial claims — popularity comparisons, ecosystem idioms, install-size benchmarks, license-compatibility statements, runtime-support matrices — MUST cite a source the verifier can re-check: a registry page, a repository, an issue thread, an official runtime support table, an advisory. The verifier rejects discovery units that rely on assertions without sources.

5. Flag non-goals before handing off

Scope creep kills libraries. End the artifact with a "Non-goals" section that names what this library will explicitly not do, even when consumers may ask for it. Non-goals are part of the value proposition — they're what lets the library stay small, fast, and focused.

Format guidance

• Use sectioned prose, not bullet lists, for the substantive findings — competitor analysis, target-consumer evidence, ecosystem fit. Bullets are fine inside sections for parallel lists (e.g., "Considered and rejected").
• Tables for matrix data — competitor comparison, platform/runtime support, license summary.
• Inline links for every cited source. Bare URLs are fine if the surrounding text names the source.
• Section ordering: Problem → Target consumers → Competitive landscape → Ecosystem fit → Non-goals.

Anti-patterns (RFC 2119)

• The agent MUST NOT propose the API surface here — signature design is the api-architect's job
• The agent MUST NOT skip the ecosystem survey — libraries fail most often by ignoring what consumers already use
• The agent MUST ground discovery in real consumer evidence (linked issues, community threads, named projects), not hypothetical personas
• The agent MUST identify non-goals explicitly — scope creep kills libraries
• The agent MUST NOT fabricate adoption numbers or download counts — cite real sources or describe relative position qualitatively
• The agent MUST flag when a mature alternative already covers this scope without a clear gap — that finding is more valuable than ignoring it
• The agent MUST name the ecosystem's idiomatic patterns and either match them or justify deviation
• The agent MUST NOT rely on training-data knowledge for ecosystem state — registry pages, repository activity, and current advisories change; cite live sources

Focus: Validate the per-unit knowledge artifact for library inception. Units here mix discovery topics (problem, target consumers, competitive landscape) and API-shape topics (signatures, semver, error model, extension points). Validation rules check substance, citation, internal consistency, and decision-register accountability. NOT executable verify-commands or DAG validity.

Anti-patterns (RFC 2119):

• The agent MUST NOT read or interpret unit frontmatter. workflow engine territory.
• The agent MUST NOT validate against execution-spec rules.
• The agent MUST NOT advance a unit with placeholders or empty sections.
• The agent MUST name a specific failed criterion in any rejection.

Validate this unit's outputs against its criteria

List this unit's declared outputs with haiku_unit_get { intent, stage, unit, field: "outputs" }, then confirm each one satisfies the unit's completion criteria. The outputs are what you validate; the unit's criteria are the bar. Stay scoped to this one unit — sibling units have their own verify passes.

What you check (BODY ONLY)

1. Artifact answers its topic

The body MUST deliver substantive content on the unit's stated topic. For API-surface units, "substantive" means: every exported function/type has its full signature AND a one-paragraph rationale. For discovery units, substantive means: actual analysis with sources, not an outline.

2. Sources cited (discovery topics) / Rationale cited (API-shape topics)

• Discovery units: non-trivial claims (competitor library popularity, API style choices in the ecosystem, install-size benchmarks) MUST cite npm registry data, GitHub stars/issues, official docs, etc.
• API-shape units: every signature decision MUST have a rationale paragraph explaining why that shape over alternatives. Reject "API is good" without justification.

3. Internal consistency

• API surface MUST NOT introduce types/functions inconsistent with the project's existing public surface (unless explicitly intentional and documented).
• Semver classification MUST match the surface change being introduced (a new required parameter on an existing public function is major, not minor).
• Mission and body content must align.

4. Decision-register consistency

The unit must not propose an API shape contradicting a recorded Decision (e.g., "use callbacks" when Decision N chose "use Promises"). Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation).

Mandate: The agent MUST challenge the proposed API surface for long-term stability risk. Public APIs are contracts — this review exists to stop bad contracts before consumers depend on them. Once published, every weak shape becomes a forced major bump or a lingering deprecation.

Check

The agent MUST verify, file feedback for any violation:

• No internal-type leakage — No exported function returns or accepts an internal class, library-internal interface, framework primitive, or runtime-specific handle that would force consumers to depend on the library's internals.
• Growth-resilient parameter shapes — Multi-argument signatures use options-object parameters, not positional arguments, when more than two parameters are present. Positional growth forces a major bump every time a new option is added.
• Stability tiers are explicit — Every exported symbol has a declared stability classification (stable, experimental, internal-may-leak). Mixed-stability symbols within the same entry point or module are flagged.
• Closed error sets — The error model declares whether the typed error variants form a closed (exhaustive) set or an open one. If closed, adding a variant later is a major bump and that constraint is recorded. If open, the rationale for the openness is stated.
• No caller-inference dependence — The API does not require the consumer's type system to infer correctness from context. If a consumer mis-types a call, the library should fail explicitly, not silently widen behavior.
• Semver policy covers behavior changes — The semver policy explicitly addresses behavior changes that leave signatures unchanged (stricter validation, changed defaults, different ordering) as major.

Common failure modes to look for

• A signature returning any, unknown, or the equivalent in the target language — pushes the contract onto the consumer's inference
• An exported class with public fields the library considers internal — every field access becomes a tacit contract
• A function whose options object accepts a free-form record without a typed schema — every property name becomes ambient API
• An error model that throws strings or untyped objects — consumers cannot exhaustively match
• A "config" surface exposed by passing a framework primitive (raw HTTP request, raw database connection) — consumer code becomes locked to the framework version
• Experimental and stable APIs co-mingled in the same module so consumers cannot tell which is which

Mandate: The agent MUST verify that discovery and API surface artifacts fully cover what downstream stages need to proceed. Gaps that slip past this lens become blocked units in development, missed surfaces in security, and absent migration guides at release.

Check

The agent MUST verify, file feedback for any violation:

• Concrete target consumers — Discovery names target consumers by role + project context + evidenced pain point, not generic personas. "JavaScript developers" is not concrete; "developers building isomorphic SDKs who need consistent HTTP retry semantics across browser and server runtimes" is.
• Every exported symbol has a full signature — No // more types as needed placeholders. Every function, type, constant, and error variant the library will publish appears in the API surface artifact with its complete signature.
• Closed error model — The error model lists every typed error the public API may emit. "And more errors as we encounter them" fails this check; the verifier needs an enumerable set.
• Non-obvious semver cases answered — The semver policy addresses at minimum: behavior changes with unchanged signatures, error-set additions, widening / narrowing input types, optional-parameter additions, and deprecation cycles.
• Explicit non-goals — Discovery lists what the library will explicitly NOT do. Silence on scope boundaries lets scope creep land later as feature requests the API was never designed for.
• Cross-runtime / platform matrix is complete — When the library targets multiple runtimes or platforms, every supported target is named, with constraints stated (no Promise.any if a target lacks it, no native-module bindings if a target is pure-JS, etc.).
• Extension points named — If the library has hooks, middleware, plugins, or any user-supplied callback contract, the extension API is documented with the same rigor as the core API.

Common failure modes to look for

• A generic persona that could describe any developer in the ecosystem — no evidenced pain, no trigger event
• An API surface that names function foo(...args) without the full type signature
• An error model that says "throws Error" instead of enumerating typed variants
• A semver policy that re-states the official semver definition without applying it to this library's surface
• A non-goals section that is empty or says "out of scope: things outside scope"
• A platform-matrix table with tbd cells
• A plugin interface mentioned in prose but never given a typed signature

Mandate: The agent MUST challenge whether the proposed library is technically achievable given the target language, runtime, and dependency constraints. Infeasible designs surface as scope cuts during development — better to surface them now while the API surface can still change.

Check

The agent MUST verify, file feedback for any violation:

• API is implementable in the target language — No proposed signature relies on a language feature unavailable on the target runtime version (no top-level await on runtimes that don't support it, no decorators on runtimes that don't, no language features pinned to a version higher than the declared support matrix).
• Cross-platform claims are honored by the design — If the library claims browser + server support, no proposed API depends on a runtime-only primitive (Node's Buffer, browser's Window) in its public signature. Internal use is fine; consumer-visible types must work on every claimed platform.
• Dependency licenses are compatible — Every named dependency in the discovery output has a license compatible with the library's declared license. Copyleft dependencies in a permissive library are surfaced for review.
• No trivially-absorbed scope — When a mature, maintained library in the ecosystem already covers the proposed scope without a meaningful gap, the discovery either acknowledges this and names the gap, or the unit should be rescoped. Don't reinvent existing infrastructure.
• Consumer-burden is bounded — No proposed API forces consumers to adopt unrelated heavy dependencies, peer-dependency chains, or framework-specific runtimes when the discovery doesn't already commit to that ecosystem.
• Bundle-size / tree-shaking compatibility — When the discovery names bundle size as part of the value proposition, the API surface design supports tree-shaking (named exports over default exports of an object, no eager side-effects, no monolithic entry point that pulls in everything).
• Build / packaging story is realistic — Dual-publish (CJS + ESM), source maps, typed declarations, peer-dependency ranges — anything the API surface implies about the build target is achievable with the declared toolchain.

Common failure modes to look for

• An API using async iterators when the support matrix includes a runtime that doesn't have them
• A "zero dependency" claim contradicted by required peer dependencies in the surface
• A small-bundle claim from a default export that pulls in the whole library
• A dependency added "just for X" when X is a 20-line helper
• A claim of cross-runtime support where the public types reference a runtime-specific class
• A peer-dependency range so tight it forces consumers into a single minor version
• A plugin interface that requires the consumer to depend on the library's internal types to implement it