This directory contains AgentDeck's engineering law.
Read these in order:
principles.md- why we build AgentDeck this way.coding-standards.md- the binding front door for every code change.- Specialized documents only when the change touches that area.
architecture.md- dependency direction, boundaries, adapters, surfaces.runtime-contracts.md- run lifecycle, events, control, concurrency, liveness.testing.md- determinism, contracts, races, recovery, goldens.dependencies.md- dependency policy and binary assets.repository-policy.md- PRs, reviewability, judgment records, change discipline.coding-agents.md- additional rules for coding agents.import-boundaries.md- current approved external import exceptions.
Design rationale and historical decisions belong under docs/design/ and ADRs, not in the standards themselves.
When guidance conflicts:
- CI-enforced compatibility and safety contracts.
- Product philosophy and engineering principles.
- Accepted architecture decisions / ADRs.
coding-standards.md.- Specialized engineering standards in this directory.
- Existing local repository convention.
- Normal Python practice.
A lower-level convention must not override a higher-level product or architectural invariant.