ZAIXOS Engineering Platform — Adoption Model
Document type: Product Definition
Version: 1.0 · Phase: 12-2
Status: Permanent product authority
Adoption Lifecycle
New Product
↓
Platform Installation
↓
Customization (extensions)
↓
Development (phases + AI runtime)
↓
Validation (local + CI)
↓
Upgrade (platform pin bump)
↓
Release (product version)
↓
Platform Upgrade (scheduled)
↺ (cycle)Each stage has explicit Platform, Product, Architect, and Developer responsibilities.
Stage 1 — New Product
| Role | Responsibilities |
|---|---|
| Platform | Publish supported platform version matrix; provide bootstrap documentation |
| Product | Create product repo; adopt product constitution; choose Laravel baseline |
| Architect | Define product module boundaries; plan phase roadmap |
| Developer | — (not yet engaged) |
Exit criteria: Product repo exists with architecture docs; decision to adopt ZEP recorded.
Stage 2 — Platform Installation
| Role | Responsibilities |
|---|---|
| Platform | Deliver package/submodule; document install steps; provide default manifests |
| Product | Add dependency; create .zaixos/platform.lock; wire Composer |
| Architect | Approve platform version pin; approve adapter choice (Cursor v1 default) |
| Developer | Execute install; run first validation |
Exit criteria: .zaixos/ present; lock file committed; integrity tests executable.
Stage 3 — Customization
| Role | Responsibilities |
|---|---|
| Platform | Maintain extension schema; document allowed customization |
| Product | Register .zaixos/extensions/manifest.yml entries; never patch vendor core |
| Architect | Review extensions for architecture alignment |
| Developer | Implement extension content; rematerialize adapter if required |
Exit criteria: Extensions registered; no undocumented .cursor/ drift.
Stage 4 — Development
| Role | Responsibilities |
|---|---|
| Platform | Provide phase templates, RESPONSE_TEMPLATE, runtime spec |
| Product | Implement domain features in app/Modules/ |
| Architect | Issue phase prompts; review Format A/B reports; issue RESPONSE_TEMPLATE decisions |
| Developer | Execute Runtime Implementation; produce ERP/platform reports; use adapter workspace |
Exit criteria: Phase accepted by architect; no boundary violations.
Stage 5 — Validation
| Role | Responsibilities |
|---|---|
| Platform | Maintain integrity tests; document pass criteria |
| Product | Configure CI to run architecture + platform tests on PR |
| Architect | Block merge on validation failure for architectural phases |
| Developer | Fix failures; run locally before push |
Exit criteria: Green CI including platform suite.
Stage 6 — Upgrade (Product Release Cycle)
| Role | Responsibilities |
|---|---|
| Platform | Publish release notes |
| Product | Schedule pin bump; execute product release |
| Architect | Accept release phase; confirm no scope creep |
| Developer | Implement features; tag product release |
Note: Product release does not require platform upgrade every time.
Stage 7 — Release
| Role | Responsibilities |
|---|---|
| Platform | — (unless platform defect discovered) |
| Product | Tag product version; deploy application |
| Architect | Freeze acceptance per product freeze policy |
| Developer | Execute Git freeze procedure (product); not platform freeze |
Stage 8 — Platform Upgrade
| Role | Responsibilities |
|---|---|
| Platform | Semver release; migration guide; deprecation notices |
| Product | Bump lock + composer; integration branch; CI green |
| Architect | Approve major upgrades; assess ADR impacts |
| Developer | Apply migration steps; rematerialize adapter |
Cadence: Patch/minor — quarterly review; major — ADR + architect approval.
Responsibility Summary Matrix
| Activity | Platform | Product (org) | Architect | Developer |
|---|---|---|---|---|
| Platform core source | R/A | C | I | I |
| Product domain code | I | R/A | A | R |
| Platform pin version | P | A | A | R |
| Extension manifest | P (schema) | R/A | A | R |
| Phase acceptance | P (process) | I | R/A | R |
| CI validation wiring | P (tests) | R/A | A | R |
| Adapter certification | R/A | C | I | I |
| Git freeze (product) | I | A | A | R |
| Platform release tag | R/A | C | I | I |
R/A = Responsible/Accountable · C = Consulted · I = Informed
Adoption Patterns
Pattern A — Greenfield Product
Install platform at latest stable v1.x → empty modules → phases from day one.
Pattern B — Migration (Dental Clinic)
Embedded ERP → platform package → remove duplicate docs → lock file → KPI-10 to zero.
Pattern C — Experimental Spike
Defer platform until productization ADR; spike repos not long-lived without migration plan.
Failure Modes & Escalation
| Symptom | Likely owner | Action |
|---|---|---|
| Validation fails on fresh install | Platform | Fix package or docs |
| Module boundary fail | Product / Architect | Fix product code |
| Adapter missing contract file | Adapter maintainer | Patch adapter release |
| Architect/ERP doc conflict | Platform docs | Fix platform index |
| Developer edited vendor platform | Product | Revert; use extensions |
Adoption Prerequisites Checklist
Before adopting ZEP, product must confirm:
- [ ] PHP/Laravel product (v1) or future adapter path accepted
- [ ] Architect role assigned
- [ ] CI can run PHPUnit architecture tests
- [ ] Team accepts phase + RESPONSE_TEMPLATE discipline
- [ ] No requirement from Never Included scope (PRODUCT_SCOPE.md)
Adoption Model v1.0 — Phase 12-2.