Architecture and decisions
Architecture decisions
Read the decision log and the rules for changing durable system boundaries.
On this page
Architecture decision records explain durable boundaries that code alone does not make obvious. They capture the context, decision, consequences, and the conditions under which a decision should be revisited.
Decision Index#
- ADR 0001: Local-first project boundary
- ADR 0002: Progressive public documentation
- ADR 0003: Project-bound agent authority
- ADR 0004: Durable document identity and repository ownership
- ADR 0005: Command, resource, and lifecycle authority
Record Rules#
- Use a stable four-digit identifier and a descriptive filename.
- Mark the status as proposed, accepted, superseded, or deprecated.
- Name the decision owner and decision date.
- Record the alternatives considered, including why they were not selected.
- State compatibility and migration requirements for existing data and callers.
- State consequences, revisit conditions, and any supersedes/superseded-by link.
- Link a superseding decision in both records.
- State security, privacy, accessibility, and migration consequences directly.
- Keep implementation plans and temporary task state out of ADRs.
- Never include credentials, private project content, or workstation paths.
An ADR describes why a boundary exists. Current APIs and operational commands remain authoritative in their dedicated reference guides.