Specifications

Every feature starts as a spec. The spec is the source of truth: tests derive from acceptance criteria, implementation derives from tests.

• Spec template — the canonical format. Copy this to start a new feature spec.
• Example spec — a filled-in template for a real feature, showing what complete looks like.

Component specifications

These are the foundational specs describing each component's architecture, API surface, and design invariants.

• Server — control + gateway + indexer, event store, authorization model, internal packages.
• SDK — protobuf definitions, generated code, capability library, testing strategy.
• Agent — execution model, offline scheduling, security properties, LUKS daemon.

How specs drive development

1. Discuss — you and the agent discuss the feature. The agent asks clarifying questions until the design is unambiguous.
2. Write — the agent drafts the spec in the template format. You review and approve it.
3. Test — the agent writes tests that encode every acceptance criterion. Tests must fail before implementation exists.
4. Implement — the agent writes the implementation. Tests pass.
5. Verify — the agent runs the verification gate. All checks green.
6. Document — any architectural decisions from the spec become ADRs. Public-facing changes update the docs.

A spec is done when every acceptance criterion has a passing test, the verification gate is green, and any docref-marked code that changed has been re-approved.