ADR 0008 — Tech specs in three trees before feature code

Status: accepted
Date: 2026-09-20

Context

Later agents need class names, DTOs, mappers, and Flutter repositories before they write Java or Dart. Putting both stacks in one file mixes two implementers. Stub source would violate the rule that feature code waits until the user asks.

Decision

Technical specs live under ai-agent/docs/tech/ as markdown only.

• api/ is Spring types and signatures.
• app/ is Flutter types and signatures.
• exchange/ is the workflow and the JSON on the wire. Each exchange spec carries a mermaid sequence of that workflow.

One file per work package in each tree, plus exchange/envelope.md for the shared envelope. WP-10 has no class specs. manifest/tech-specs.tsv is the index. The pack checker requires all three surfaces for every non-blocked work package.

Bodies stay not implemented until the user asks.

Consequences

• An API agent loads api/ and exchange/. A Flutter agent loads app/ and exchange/.
• Field lists stay in docs/contracts.md. Specs name the contract type. They do not copy the table.
• Adding a work package means adding three spec files and three TSV rows.