Avoca — Internal

Appearance

Design Docs ​

Design documents written to be read by Avoca engineers — the ones whose agreement a change needs, not just our own record of it.

They follow the format used by docs/superpowers/specs/ in avoca-next: Goal, Decisions, Current Reusable Systems, Architecture, mechanism sections, API Contracts, Error and Escalation Rules, Observability, Tests, and a Pull Request Split. Declarative present tense, a flat decision list carrying the argument, and explicit scope negations. That format is the house style of the Superpowers Claude Code plugin, which three Avoca engineers use — so it is the shape they already read and write in.

These differ from Briefs and Proposals, which argue for an investment to leadership. A design doc specifies a system for the people who will build it.

Documents ​

Testing ​

Foundations — what a test is, and how something that is not ours produces a result.

  • Data Model — one first-class assistant_test_* foundation. Replaces four unconnected lineages with one model whose atom is a result per assertion, and makes that foundation the verifier Avo Support calls. Success criteria are their own table, keyed by suite and consumer. Schema in review as avoca-next #17479. Draft, 2026-08-18.
  • Adapter Contract — author a test once and run it on any runner. A runner's job ends at an outcome; assertions are judged against it afterwards. Draft, 2026-08-18.

The tiers — cheapest and most certain first.

  • Chat-Based Unit Testing — one real turn replayed against a candidate config in about a second, for a fraction of a cent. The tier that fits inside an edit loop, and the only one cheap enough to run across the fleet. Draft, 2026-08-18.
  • Chat-Based Integration Testing — a full chat conversation, with assertions on what the system did — which tools executed, with what arguments. Deterministic where a rubric would flake. Draft, 2026-08-18.
  • Chat-Based Sim Testing — the same surface, judged on what the agent said. A simulated caller holds the conversation; no audio. Draft, 2026-08-18.

Superseded

Status and destination ​

A doc here is ours until it is agreed. The working destination is Notion, where the engineers who need to read it will. A copy lands in avoca-next at docs/superpowers/specs/ only once we are ready for it to live beside the designs it relates to.