Engineering Playbook

AEGIS ENGINEERING PLAYBOOK — Permanent Engineering Principles

» **Status:** Living contract. Every implementation slice validates against this.
» **Role:** The behavioral rules for how Aegis code is written, evolved, and reviewed. Complements the Platform Blueprint (structure) and Runtime Spec (behavior).

---


1. CONTINUOUS ARCHITECTURE VALIDATION

After completing every major implementation slice, perform an **architecture review** before moving on.

Review the implementation against:
• Platform Blueprint
• Domain Model
• Runtime Specification
• SDK Specification
• Product Principles
• Application Design System

For every discrepancy:
1. **Explain** it.
2. **Decide** whether implementation or architecture should change.
3. **Make the change.**
4. **Document the reasoning** (in the daily memory + the relevant doc).

Do not allow implementation and architecture to drift apart. **Architecture is a living contract** — implementation must continuously validate it.

---


2. REFACTORING PRINCIPLES

Prefer **additive migrations** over destructive rewrites.

• Preserve working systems whenever possible.
• Introduce new architecture *beneath* existing features.
• Migrate incrementally.
• Remove legacy implementations only after the replacement is fully validated.
• Avoid big-bang rewrites unless they eliminate a critical architectural flaw.

---


3. PUBLIC API STABILITY

Every exported SDK interface is considered **public**.

Changing a public interface requires:
• backward compatibility, **OR**
• an explicit migration strategy.

Avoid breaking SDK consumers. Prefer **evolving contracts** over replacing them.

---


4. REUSABILITY-FIRST (FORM-FACTOR & CONSUMER AGNOSTIC)

Before writing any platform/runtime code, ask:

Can mobile reuse this?
Can desktop reuse this?
Can tests reuse this?
Can simulations reuse this?
Can replay reuse this?
Can AI reuse this?

If not, it is probably too UI-centric. Runtime code must not import React/UI; it lives in `platform/` and `sdk/`, independently testable and replaceable.

---


5. VERTICAL SLICES

Implement complete vertical slices, not isolated components. Each slice includes:
UI + Runtime + SDK integration + Domain integration + Event integration + Testing + Error handling + Documentation.

Each slice must be usable when complete. Build foundational pieces before consumers. Avoid unnecessary abstractions and premature optimization.

---


6. NO BROKER-SPECIFIC CODE OUTSIDE PLUGINS

Every broker implements the SDK (`BrokerAdapter`). No broker-specific logic lives outside broker plugins. Products consume capabilities, never broker identity.

---


7. PERFORMANCE IS A FEATURE

Every implementation must define its **performance contract before it is considered complete**:

• **Expected latency** (p50/p95 target for the hot path)
• **Expected memory** (bounded footprint; no unbounded caches)
• **Expected update frequency** (how often the data refreshes)
• **Expected scalability** (how it behaves as N grows: positions, brokers, users)
• **Expected failure behavior** (what happens when the operation is slow / fails)

Reference budgets (stretch targets; tighter than „will optimize later“):

  Operation | Budget
  Broker sync | < 250 ms
  Mission Control refresh | < 100 ms
  Protection evaluation | < 20 ms
  Widget render | < 16 ms (1 frame)
  Command execution | < 50 ms
  Data-grid virtualization (100K rows) | < 16 ms scroll
  Cold start (desktop / mobile) | < 800 ms / < 2 s

A subsystem with no stated budget is **not done**. Performance is part of the contract, not an afterthought.

---


8. TECHNICAL DEBT IS TRACKED

Every architectural compromise is recorded in `TECHNICAL_DEBT.md`, not carried silently. Columns: **Deferred · Reason · Risk · Priority · Owner · Review date.**

"We'll fix it later" is only acceptable if it is written down with a risk + review date.

---


OWNER
Platform Engineering · enforced in every architecture review (§1).