ADR-004 — Adapter Architecture
Status: Accepted
Date: 2026-06-28
Phase: 12-1A
Deciders: Platform Architect
Certified adapters at v1.0 GA: cursor-adapter-v1
Context
ERP v1.0 implemented Cursor Adapter v1 with workspace at .cursor/. Multi-IDE future and product independence require:
- Resolved namespace (
.zaixos/vs.cursor/) - Clear materialization model
- Certification process
- No vendor paths in Platform Core
Decision
Adapter architecture
- Adapters are platform-owned packages under
adapters/{adapter-id}/ - Each adapter ships: profile.md, workspace template, metadata JSON, capability gaps
- Certification requires passing
AdapterWorkspaceTest+ manual acceptance checklist - Products select adapter in
platform.yml— never author uncertified adapters
Namespace resolution (final)
| Path | Role |
|---|---|
.zaixos/ | Canonical platform namespace in product repos |
.zaixos/platform.lock | Pinned versions |
.zaixos/extensions/ | Product extensions |
.cursor/ | Materialization target for cursor-adapter-v1 only |
Materialization rule: Installer copies adapters/cursor-v1/workspace/ → product .zaixos/adapters/cursor-v1/ and creates symlink .cursor/ → .zaixos/adapters/cursor-v1/workspace/ (or direct copy if symlinks unsupported).
This resolves Phase 12-1 ambiguity: platform owns .zaixos/; Cursor IDE reads .cursor/.
Adapter versioning
- Independent semver tied to platform compatibility range
- See PLATFORM_VERSIONING_POLICY.md
First certified adapter
- ID:
cursor-adapter-v1 - Source: ERP v1.0
.cursor/tree (byte-identical at 1.0.0 GA) - Profile:
adapters/cursor-adapter-v1/profile.mdmigrated to platform repo
Consequences
Positive
- Multi-adapter registry without core changes
- Clear CI checks on materialized workspace
- Cursor compatibility preserved via
.cursor/mount
Negative
- Symlink/copy step adds installer complexity
- Windows symlink permissions may require copy fallback
Alternatives considered
| Alternative | Rejected because |
|---|---|
Keep .cursor/ as canonical | Platform namespace not IDE-neutral |
Only .zaixos/ — reconfigure Cursor | Poor DX; non-standard |
Product-maintained .cursor/ | Drift from platform |
ADR-004 — Adapters materialize; platform owns .zaixos/.