AGENTS.mdMarkdown
# GastroOS — Repository Instructions for Developers and Coding Agents
This file is the mandatory entry point for humans, AI coding assistants, agents and automation working in this repository.
GastroOS is not a collection of isolated restaurant features. It is a modular Hospitality Operational Intelligence Platform designed to scale from a one-person kiosk or Imbiss to restaurants, bars, caterers, temporary operations, hotel F&B, resorts, franchise groups and multi-brand organizations.
The repository already contains substantial architecture, product and implementation decisions. Do not treat a new task as permission to redesign the system from scratch.
## 1. Read before making architectural or product changes
Read these documents in this order before substantial implementation, refactoring, domain expansion or UX/navigation work:
1. `docs/GASTROOS_MASTER_CONSTITUTION.md`
2. `docs/MASTER_ROADMAP_EXTENSIONS.md`
3. `docs/PRODUCT_ROADMAP.md`
4. `docs/UX_MASTER_SPEC.md`
5. `docs/UI_SURFACE_MATRIX.md`
6. `docs/PLACES_AND_TEMPORARY_OPERATIONS.md`
7. relevant ADRs in `docs/`
8. `README.md`
9. `PROJECT_INDEX.md` where relevant
10. runtime/bootstrap documents such as `docs/MASTER_PACKAGE_FIRST_START.md` and `docs/MASTER_PACKAGE_STATUS.md`
If a task touches a domain with its own contract, schema note, ADR or capability document, read that document before modifying the domain.
## 2. Canonical product laws
All changes must preserve these principles unless the product constitution is deliberately amended.
### One brain — many surfaces
Backend domains are not navigation. The same canonical operational truth is exposed through role-, task-, device-, Place-, operational-unit-, archetype-, permission- and state-specific surfaces.
### One system — many realities
Temporary, seasonal, mobile, event-based, degraded and exceptional operations are normal hospitality realities, not edge cases.
### Verticals are compositions, not separate products
Imbiss, Fine Dining, High-Volume Bar, Catering, Hotel F&B, Resort, Franchise and temporary event operations should compose shared primitives and capabilities instead of creating parallel domain truth or separate codebases.
### Maximum operational reach. Minimum local complexity.
The system may be deep internally, but each user should see only the small, clear surface needed for the current job.
### GastroOS absorbs stress. It does not visualize stress.
Operational complexity must not become UI complexity. Under pressure, visible interfaces should become simpler, not noisier.
## 3. Architecture protection rules
Before introducing a new module, service, model, navigation section or vertical-specific implementation, ask:
1. Is this genuinely a new canonical domain capability?
2. Is it instead a primitive, policy, archetype, workflow, integration, surface, blueprint or context?
3. Which existing capabilities already compose most of the requirement?
4. What new canonical information must actually be stored?
5. Can a small operation ignore this completely?
6. Can a complex operation configure it deeply?
7. Does the change preserve one canonical truth rather than create another truth pool?
8. Does activating it make the wider GastroOS system more capable or intelligent?
Avoid panic refactors and avoid replacing sound foundations merely because a new use case appears.
## 4. Protected cross-cutting foundations
Major changes must respect and, where required, extend these foundations:
- tenant/security boundary;
- Legal Entities;
- Organization Graph;
- Locations;
- Operational Units;
- Places, including temporary/mobile Places;
- contextual and temporal scope;
- universal fulfillment rather than mandatory table-service assumptions;
- commitments and fulfillable capacity;
- operational readiness;
- append-only inventory/financial ledgers where applicable;
- Cases, Plans, Tasks and Dependencies;
- policy, permissions, provenance and audit;
- surface architecture;
- offline/degraded-operation capability.
Do not collapse distinct truth domains such as payment, settlement, fiscal, accounting, inventory, commercial and operational truth into one convenient model.
## 5. Offline, Edge and connectivity
Live hospitality operations must not depend on public internet connectivity more than the specific command truly requires.
Current repository foundations already include Drift/SQLite offline capability, transactional outbox patterns, realtime abstractions and snapshot reconciliation.
When the GastroOS Edge Runtime ADR is present in the branch being worked on, it is canonical for local operational runtime behavior.
For every live-operation feature, explicitly consider:
- what remains readable without WAN connectivity;
- what can be written locally;
- what requires site-level coordination;
- what genuinely requires cloud or external-provider connectivity;
- idempotency and retry behavior;
- conflict/reconciliation semantics;
- device/peripheral failure;
- extended outage and reconnect behavior.
Do not create a generic last-write-wins strategy for protected domain truth.
## 6. WordPress and public integrations
WordPress is an integration surface, not the GastroOS core and not a canonical operational database.
The WordPress integration may expose booking and future guest-facing capabilities such as menus, events, preorder or inquiries. Canonical reservations, commitments, products and operational truth remain in GastroOS.
External channels must not become independent reservation, inventory or operational truth pools.
## 7. AI roadmap protection
The existing AI roadmap `AI-0` through `AI-12` is canonical.
Do not renumber it, replace it or silently create a competing AI roadmap. New intelligence tracks must extend the existing roadmap additively.
AI may infer, summarize, explain, recommend, simulate and prepare actions, but critical facts remain authoritative in deterministic GastroOS domain logic.
AI must not silently invent or overwrite:
- allergens;
- payments;
- fiscal/accounting truth;
- inventory movements;
- permissions;
- immutable compliance or financial records.
High-impact actions must pass through deterministic commands, constraints, policy, permission and approval where required.
## 8. Human trust rules
### Guests
Technology exists to improve hospitality, not replace it. Preserve appropriate human and accessible alternatives where reasonable.
Distinguish declared, observed and inferred guest information. Respect purpose limitation and need-to-know visibility.
### Employees
Do not build hidden generalized employee-worth scores, speculative psychological/health inference or automatic disciplinary decision systems.
Human professional overrides are valid operational input and must be auditable where appropriate.
Temporary and occasional workers should receive just-in-time guidance instead of being exposed to the whole system.
## 9. UX rules
Before broad UI work, read `docs/UX_MASTER_SPEC.md` and `docs/UI_SURFACE_MATRIX.md`.
Core rules include:
- backend modules are not navigation;
- one obvious next action;
- information comes to the work;
- every tap must earn its existence;
- context changes priority, not geography;
- muscle memory beats dynamic cleverness;
- power without exposure;
- hide the model, show the intention;
- interruptions must earn the interruption;
- calm by default;
- friendly under pressure.
Do not use the existing Flutter feature routes as proof of final navigation architecture.
## 10. Scenario testing requirement
Major architectural and product decisions should be tested mentally and, where appropriate, technically against at least:
- one-person Imbiss / kiosk;
- standard restaurant;
- fine dining;
- high-volume bar/nightclub;
- temporary event/market Place;
- foodtruck/mobile catering;
- hotel/resort multi-outlet F&B;
- 100+ location/franchise organization;
- occasional worker on first shift;
- poor/no connectivity;
- live operational disruption;
- multilingual team;
- accessible guest interaction;
- professional human override.
A design that works only for a standard restaurant is not sufficient for GastroOS.
## 11. Implementation discipline
Prefer additive evolution over rewrites.
Before changing code:
- inspect existing implementation and relevant docs;
- search for existing primitives, services, schemas, adapters and tests;
- preserve existing contracts unless a migration is intentional;
- update documentation when architecture or product behavior changes;
- add or update ADRs for consequential architectural decisions;
- keep migrations explicit and auditable;
- maintain tenant and permission boundaries;
- do not bypass tests, security checks or audit failures merely to make CI green.
If a security audit finds a real high-severity dependency issue, fix or deliberately document the dependency decision; do not simply disable the audit.
## 12. Repository and collaboration workflow
The default branch is `main`.
For consequential work:
- create a focused branch;
- keep commits understandable;
- open a pull request into `main`;
- review CI failures rather than assuming the new change caused them;
- do not merge red security/build checks without understanding the failure;
- ensure architecture documents and implementation stay synchronized.
Developers cloning the repository should begin with this file and the documents listed in section 1.
## 13. Definition of done for substantial changes
A substantial change is not done merely because code compiles.
Confirm, as applicable:
- architecture remains consistent with the Constitution;
- no parallel truth pool was created;
- small-operation complexity remains low;
- enterprise depth remains possible;
- offline/degraded behavior is understood;
- permissions/audit/provenance are preserved;
- UX follows surface doctrine;
- relevant tests pass;
- security checks pass;
- documentation/ADR/roadmap are updated;
- the change has been considered across the GastroOS scenario set.
## Final rule
> Specialists know their domain. GastroOS must know the operation.
When in doubt, optimize for one coherent operational platform rather than another isolated feature.