The Principles

I. Contract-First Development

API contracts MUST be defined in a schema language before any implementation begins. All server and client code derives from these contracts. Schema evolution MUST be backward-compatible. No contract, no feature.

• Contracts are the single source of truth for every API surface.
• Generated code from contracts is never hand-edited.
• Breaking changes require a new major version of the contract.
• Client libraries and bridge layers derive types from contracts.

II. Test-First (NON-NEGOTIABLE)

TDD is mandatory: write failing tests, then implement, then refactor. cargo test MUST pass at every commit. No exceptions.

• RED: Write a test that fails for the right reason.
• GREEN: Write the minimum code to make the test pass.
• REFACTOR: Improve the code while keeping tests green.
• Every commit MUST have all tests passing.

III. Integration-First Testing

Prefer real databases (testcontainers) over mocks. Contract tests are mandatory before implementation. Test in realistic environments.

• Use testcontainers for database-dependent tests.
• Contract tests validate API boundaries before implementation.
• Mocks are acceptable only for external services with no test mode.
• Integration tests run in environments that mirror production.

IV. Security by Default

Security is never an afterthought. Content MUST be scanned before storage. Data at rest MUST be encrypted. Tenant isolation MUST be enforced at the database level. Every API call MUST be authenticated.

• Input scanning occurs before any persistence or processing.
• Encryption at rest is mandatory for all stored data.
• Tenant isolation is enforced at the data layer, not application logic.
• Authentication is required on every API call, no exceptions.

V. Simplicity & Anti-Abstraction

200 lines per file maximum. No premature abstraction. No convenience wrappers around frameworks. Start simple, add complexity only when proven necessary. YAGNI.

• Files exceeding 200 lines MUST be split.
• Framework APIs are used directly — no wrapping layers.
• Abstractions require proven justification (multiple consumers or concrete future need), not speculative reuse.
• Prefer duplication over the wrong abstraction.

VI. Observability

All errors MUST be actionable with next-step suggestions. Logging goes to stderr only (stdout reserved for protocol transport). Structured logging is required.

• Error messages tell the user what went wrong AND what to do next.
• stdout is reserved for protocol I/O (gRPC, MCP stdio, etc.).
• All diagnostic output goes to stderr via structured logging.
• Log levels are filterable via environment configuration.

VII. Modularity

Each component is independently testable with clear boundaries. Bridge layers MUST be thin proxies with zero business logic. Business logic lives in the core service only.

• Components have explicit public interfaces and encapsulated internals.
• Bridge/proxy layers translate protocols — no business decisions.
• Business logic is never duplicated across layers.
• Each module can be tested in isolation with its own test suite.

VIII. Solved Problems Stay Solved

The system exists to eliminate redundant problem-solving. When a problem has been solved before, agents MUST receive the existing optimal solution instead of re-deriving one from scratch.

• Every query checks existing solutions before new reasoning occurs.
• Better solutions MUST supersede worse ones automatically.
• Solution quality is tracked: naive vs optimized, verified vs unverified, proven-in-production vs single-use.
• The measure of success is reduction in redundant LLM reasoning and improvement in solution quality — not volume of stored knowledge.
• Quantity is irrelevant. Quality is everything.

IX. Feature-Sliced Architecture

Every service exposes a public API contract. Internal implementation is private. Services communicate through their public APIs only, never through internal modules. This applies at BOTH levels: project-wide (between services) and within each service (between feature slices).

• Each service directory has an api/ module defining its public contract.
• Internal implementation details are never imported across service boundaries.
• Feature slices within a service communicate through defined interfaces (traits).
• Bridge layers consume only the public API of the services they connect.
• An LLM should understand a service's capabilities by reading only its public API — without needing to load internal source files.
• Public APIs are the ONLY coupling point between services; changing internals MUST NOT break consumers.

Every commit MUST pass all quality gates. No exceptions, no bypass flags.

• Static analysis MUST pass with all warnings treated as errors.
• Code formatting MUST pass automated checks.
• All tests MUST pass.
• No unsafe patterns: .unwrap() and .expect() are FORBIDDEN.
• The ? operator is the ONLY acceptable error propagation mechanism.

IMPORTANT: TigerBeetle is a quality standard to emulate, not infrastructure to deploy. It is studied for its engineering philosophy and is here for coding excellence.

Specific practices to emulate in Jarvis components, particularly Engram (knowledge-service/):

• Deterministic simulation testing (test the system, not just units).
• No undefined behavior — every edge case handled.
• Every error handled explicitly (no silent failures).
• Assertion-driven integrity (invariants checked at runtime).

1. Interface over implementation — Every component communicates via protobuf contracts. Swap any backend without touching consumers.
2. Boring technology — PostgreSQL, gRPC, Docker. No novel infrastructure in the critical path.
3. Budget-aware retrieval — Never dump all knowledge. Pack the best facts within a token budget.
4. Darwinian feedback — Track what knowledge gets used and helps. Prune what doesn't.
5. Scope hierarchy — Knowledge has scope: global → domain → project. Retrieval prioritizes narrow scope.
6. Compaction is continuous — Dedup on write, decay on schedule, supersession on conflict. Never unbounded growth.
7. Human-readable export — Any knowledge can be exported as markdown. Anti-fragility against system failure.
8. Zero human intervention in QA — All verification via agent tools (Playwright, curl, tmux). No "user checks manually."

This constitution supersedes all other engineering practices within the Coeus project. Amendments require:

1. Written justification documenting the change and rationale.
2. Impact analysis on existing code and tests.
3. Version bump following semver:
   • MAJOR: principle removal/redefinition
   • MINOR: new principle or material expansion
   • PATCH: clarification
4. Update to all dependent specs and plans referencing changed principles.

All code reviews MUST verify compliance with these principles.

The .specify/ workflow ensures structured, predictable development:

• spec.md → feature specification
• plan.md → implementation plan
• tasks.md → ordered task list

Templates are located in .specify/templates/.