ZAIXOS Engineering Index
Engineering Operating System v1.0 · Engineering Runtime Platform v1.0 (Phase 11-2A)
Runtime baseline: v5.2-local-development-runtime (Consumer #1 local development)
Product platform baseline: v4.2-public-experience-platform
Target freeze tag (EOS): v5.0-ai-development-environment — release doc
Target freeze tag (ERP): v5.1-engineering-runtime-platform (provisional)
Consumer #1 frozen engineering layers (Dental Clinic ROS)
| Layer | Tag | Doc |
|---|---|---|
| Environment & Configuration | v5.2-local-development-runtime | Consumer docs/development/FROZEN_ENGINEERING_LAYERS.md |
| Local DNS Platform | v5.2-local-development-runtime | Consumer docs/development/LOCAL_DEVELOPMENT_RUNTIME.md |
| Local Development Runtime | v5.2-local-development-runtime | v5.2-local-development-runtime.md |
Lifecycle: Standalone platform repository @ Platform GA v1.0.0 — Consumer #1 (Dental Clinic ROS) integrated via Composer +
.zaixos/lock (phase-12-9-platform-ga-report.md). Terminology EOS / ERP is transitional; forward platform name is ZEP (PLATFORM_INDEX.md).
Onboarding: ERP_DEVELOPER_GUIDE.md — start here for engineering workflow. This index is the asset map, not the entry point.
Root authority: AI_DEVELOPMENT_ENVIRONMENT.md
Platform authority: PLATFORM_INDEX.md
EOS design authority: phase-10-ai-development-environment-specification.md
ERP Core authority: phase-11-engineering-runtime-platform-specification.md
1. Governance (read first)
Authority chain (conflict resolution)
| Priority | Path | Key documents |
|---|---|---|
| 1 | docs/releases/ | Frozen baselines |
| 2 | docs/architecture/ | PROJECT_CONSTITUTION.md, MODULE_BOUNDARIES.md, LONG_TERM_ROADMAP.md |
| 3 | docs/development/ | AI_DEVELOPMENT_ENVIRONMENT.md, ENGINEERING_INDEX.md, Phase 10 spec, Phase 11 ERP spec |
| 4 | docs/company/ + docs/product/ | COMPANY_CONSTITUTION.md, PRODUCT_VISION_AND_STRATEGY.md |
| 5 | knowledge/ | Operational patterns, playbooks, recipes |
EOS operational documents
ERP reports (Runtime Implementation)
Two formats only — templates/implementation-report.md:
| Format | Sections | When |
|---|---|---|
| Implementation phase | Architecture Summary, Files Changed, Tests, Remaining Risks | Code/runtime passes |
| Documentation phase | Summary, Files Created, Files Modified, Verification, Remaining Gaps, Decision | Documentation-only passes |
2. ERP Core
Authority: phase-11-engineering-runtime-platform-specification.md
IDE-agnostic runtime abstraction. ERP Core defines abstract components — not vendor file formats.
| ERP component | Canonical manifest / policy | Count |
|---|---|---|
| Runtime Constraints | EOS rule categories + rules catalog (adapter mirror) · RuntimeConstraintContract | 9 enforcement + 11 reference catalogs |
| Runtime Procedures | skills-manifest.md · RuntimeProcedureContract | 10 |
| Runtime Workflows | commands-catalog.md · RuntimeWorkflowContract | 10 |
| Runtime Delegation | agents-manifest.md · RuntimeDelegationContract | 10 |
| Runtime Enforcement | enforcement-manifest.md · RuntimeEnforcementContract | Minimum event set (4) |
| Runtime Context Providers | context-providers-manifest.md · RuntimeContextProviderContract | Immediate tier (3) — disabled |
| Runtime Execution | execution-manifest.md · RuntimeExecutionContract | 4 modes (Local · CLI · Cloud · Background) |
| Runtime Adapters | docs/development/adapters/*-profile.md | See §3 |
Layer model: Documentation Authority → ERP Core → Runtime Adapter → Native IDE Runtime → Human Authority.
3. Runtime Adapters
Every IDE implements ERP Core through a Runtime Adapter profile. Vendor paths and formats live in adapter profiles only — not in ERP Core.
| Adapter | Status | Profile |
|---|---|---|
| Adapter v1 (Cursor) | First implementation target | cursor-adapter-v1-profile.md |
| Claude Adapter | Future | TBD |
| OpenAI IDE Adapter | Future | TBD |
| VS Code AI Adapter | Future | TBD |
| Windsurf Adapter | Future | TBD |
Adapter v1 workspace (Cursor)
Native mirror paths — see cursor-adapter-v1-profile.md for full mapping.
| ERP component | Adapter v1 path |
|---|---|
| Runtime Constraints | .cursor/rules/*.mdc |
| Runtime Procedures | .cursor/skills/*/SKILL.md |
| Runtime Workflows | .cursor/skills/{workflow}/SKILL.md |
| Runtime Delegation | .cursor/agents/*.md |
| Runtime Enforcement | .cursor/hooks.json |
| Runtime Context Providers | .cursor/mcp.json |
| Runtime Execution (local) | Committed .cursor/ workspace |
| Runtime Execution (CLI) | .cursor/cli.json |
| Runtime Execution (cloud) | .cursor/environment.json |
| Runtime Execution (background) | Inherits parent session .cursor/ |
See §14 Version control policy.
4. Manifests (docs/development/)
| Manifest | Path | Canonical for |
|---|---|---|
| Runtime Procedure Manifest | skills-manifest.md | Domain procedure inventory · RuntimeProcedureContract |
| Runtime Delegation Manifest | agents-manifest.md | Delegation role inventory · RuntimeDelegationContract |
| Runtime Workflow Manifest | commands-catalog.md | Workflow inventory · RuntimeWorkflowContract |
| Runtime Enforcement Manifest | enforcement-manifest.md | Hook inventory · RuntimeEnforcementContract |
| Runtime Context Provider Manifest | context-providers-manifest.md | Provider inventory · RuntimeContextProviderContract |
| Runtime Execution Manifest | execution-manifest.md | Execution mode inventory · RuntimeExecutionContract |
| ERP freeze preparation | erp-freeze-preparation.md | Validation summary · freeze readiness (11-9) |
| ERP developer guide | ERP_DEVELOPER_GUIDE.md | Onboarding · official workflow · daily examples |
| ERP acceptance checklist | ERP_ACCEPTANCE_CHECKLIST.md | DX acceptance gate (11-10) |
| ERP runtime validation | ERP_RUNTIME_VALIDATION.md | Manual runtime validation procedures |
| Context provider policy | mcp-governance.md | Pointer → adapter governance |
| Context provider registry summary | mcp-registry.md | Pointer → canonical manifest |
5. Runtime Constraints catalog
| Category | Catalog | .mdc rule |
|---|---|---|
| EOS authority | 00-eos-authority.mdc | alwaysApply |
| Freeze | catalog/freeze.md | 10-freeze-boundary.mdc |
| Architecture | catalog/architecture.md | 20-architecture-patterns.mdc |
| DDD | catalog/ddd.md | extends B |
| Implementation | catalog/implementation.md | 30-implementation.mdc |
| Review / scope | catalog/review.md | 40-phase-scope.mdc |
| Documentation | catalog/documentation.md | 50-documentation.mdc |
| AI | catalog/ai.md | 60-ai-alignment.mdc |
| Git / tooling | catalog/git.md | 70-tooling-safety.mdc |
| UI | catalog/ui.md | shared with B |
| Testing | catalog/testing.md | shared with C |
| Release | catalog/release.md | shared with E/G |
| Repository | 90-repo-specific.mdc | alwaysApply |
Precedence: A > B > D > C > F > E > G — rules/catalog/README.md
6. Runtime Procedures (10)
Contract: RuntimeProcedureContract · phase-11-engineering-runtime-contracts.md §5
Specification: phase-11-4-runtime-procedures-workflows-specification.md §6
Canonical inventory: skills-manifest.md
Adapter mapping: cursor-adapter-v1-profile.md · .cursor/skills/{domain}/SKILL.md
Status: Phase 11-4A — implemented in Cursor Adapter v1
| Manifest ID | Domain | Tier | Adapter path |
|---|---|---|---|
skill-architecture | Architecture | Core | .cursor/skills/architecture/SKILL.md |
skill-platform | Platform | Core | .cursor/skills/platform/SKILL.md |
skill-laravel | Laravel | Implementation | .cursor/skills/laravel/SKILL.md |
skill-ddd | DDD | Implementation | .cursor/skills/ddd/SKILL.md |
skill-testing | Testing | Core | .cursor/skills/testing/SKILL.md |
skill-documentation | Documentation | Core | .cursor/skills/documentation/SKILL.md |
skill-ui-ux | UI/UX | Implementation | .cursor/skills/ui-ux/SKILL.md |
skill-ai-experience | AI Experience | Specialist | .cursor/skills/ai-experience/SKILL.md |
skill-security | Security | Specialist | .cursor/skills/security/SKILL.md |
skill-devops | DevOps | Specialist | .cursor/skills/devops/SKILL.md |
Each procedure includes Purpose, Inputs, Outputs, Responsibilities, Forbidden Actions, Dependencies, and cites RuntimeProcedureContract. Auto-invocation permitted via skill description metadata.
7. Runtime Delegation (10)
Contract: RuntimeDelegationContract · phase-11-engineering-runtime-contracts.md §7
Canonical inventory: agents-manifest.md
Adapter mapping: cursor-adapter-v1-profile.md · .cursor/agents/{role}-agent.md
Status: Phase 11-5 — implemented in Cursor Adapter v1
| Delegate ID | Role | Owner | Readonly | Adapter path |
|---|---|---|---|---|
delegate-architecture | Architecture | Developer launches; Architect consumes | Yes | .cursor/agents/architecture-agent.md |
delegate-implementation | Implementation | Developer via Phase Implementation | No | .cursor/agents/implementation-agent.md |
delegate-testing | Testing | Developer (parallel) | No | .cursor/agents/testing-agent.md |
delegate-documentation | Documentation | Developer for documentation phases | No | .cursor/agents/documentation-agent.md |
delegate-ui | UI | Developer for UI sub-phases | No | .cursor/agents/ui-agent.md |
delegate-ai-experience | AI Experience | Developer for AI host phases | No | .cursor/agents/ai-experience-agent.md |
delegate-security | Security | Developer before review (optional) | Yes | .cursor/agents/security-agent.md |
delegate-boundary | Boundary | Developer before Architect review | Yes | .cursor/agents/boundary-agent.md |
delegate-review | Review | Developer via Review Preparation (optional) | Yes | .cursor/agents/review-agent.md |
delegate-release | Release | Developer during freeze preparation | No | .cursor/agents/release-agent.md |
Each delegate cites RuntimeDelegationContract, includes valid YAML frontmatter, and enforces escalation Runtime Delegation → Developer → Architect (RESPONSE_TEMPLATE.md). No direct delegation–Architect channel.
Readonly delegates: Architecture, Security, Boundary, Review — readonly: true in frontmatter.
7A. Runtime Enforcement
Contract: RuntimeEnforcementContract · phase-11-engineering-runtime-contracts.md §8
Canonical inventory: enforcement-manifest.md
Configuration: .cursor/hooks.json · schema version 1
Adapter mapping: cursor-adapter-v1-profile.md
Status: Phase 11-6 — implemented in Cursor Adapter v1
| Enforcement ID | ERP category | Native event | Handler | failClosed |
|---|---|---|---|---|
enforcement-shell-guard | Shell execution | beforeShellExecution | shell_guard.py | Yes |
enforcement-mcp-guard | Context provider execution | beforeMCPExecution | mcp_guard.py | Yes |
enforcement-delegation-guard | Delegation start | subagentStart | delegation_guard.py | Yes |
enforcement-prompt-guard | Prompt submit (optional) | beforeSubmitPrompt | prompt_guard.py | No |
Execution order: shell → MCP → delegation → prompt. Critical handlers fail-closed on error. Runtime Constraints remain authoritative — enforcement implements deterministic guards only.
8. Runtime Workflows (10)
Contract: RuntimeWorkflowContract · phase-11-engineering-runtime-contracts.md §6
Specification: phase-11-4-runtime-procedures-workflows-specification.md §7
Canonical inventory: commands-catalog.md
Adapter mapping: cursor-adapter-v1-profile.md · .cursor/skills/{catalog-id}/SKILL.md
Status: Phase 11-4B — implemented in Cursor Adapter v1
Git freeze is not a workflow — GIT_FREEZE_PROCEDURE.md.
| Workflow ID | ERP class | Catalog ID | Invoker | Report | Adapter path |
|---|---|---|---|---|---|
workflow-bootstrap | Bootstrap Verification | bootstrap | Developer + Architect | B | .cursor/skills/bootstrap/SKILL.md |
workflow-discovery | Architecture Discovery | discovery | Architect | B | .cursor/skills/discovery/SKILL.md |
workflow-spec | Architecture Specification | spec | Architect | B | .cursor/skills/spec/SKILL.md |
workflow-phase | Phase Implementation | phase | Architect | A | .cursor/skills/phase/SKILL.md |
workflow-review | Review Preparation | review | Developer (+ optional Delegation) | A or B | .cursor/skills/review/SKILL.md |
workflow-hardening | Hardening | hardening | Architect → Developer | A | .cursor/skills/hardening/SKILL.md |
workflow-freeze | Freeze Preparation | freeze | Architect | B | .cursor/skills/freeze/SKILL.md |
workflow-release | Release Documentation | release | Documentation role + Architect | B | .cursor/skills/release/SKILL.md |
workflow-report | Report Generation | report | All implementation passes | A or B | .cursor/skills/report/SKILL.md |
workflow-status | Status Verification | status | Developer (+ optional Delegation) | B-aligned | .cursor/skills/status/SKILL.md |
Each workflow cites RuntimeWorkflowContract, requires explicit user invocation (disable-model-invocation: true), and produces Format A or Format B ERP Runtime Reports only. Template authority remains in prompts/commands/.
Legacy EOS aliases: /bootstrap, /discovery, /spec, /phase, /review, /hardening, /freeze, /release, /report, /status
9. Prompt library
| Template | Path |
|---|---|
| Architecture discovery | prompts/phases/architecture-discovery.md |
| Architecture specification | prompts/phases/architecture-specification.md |
| Foundation | prompts/phases/foundation.md |
| Hardening | prompts/phases/hardening.md |
| Freeze review | prompts/phases/freeze-review.md |
| Git freeze (Developer) | prompts/phases/git-freeze.md |
| Architecture review | prompts/phases/architecture-review.md |
| Documentation review | prompts/phases/documentation-review.md |
10. Templates
| Template | Path |
|---|---|
| Discovery | templates/discovery.md |
| Specification | templates/specification.md |
| Implementation report | templates/implementation-report.md |
| Architecture review | templates/architecture-review.md |
| Freeze review | templates/freeze-review.md |
| Release notes | templates/release-notes.md |
| Decision record | templates/decision-record.md |
11. Knowledge hierarchy
Canonical path: knowledge/ (intentional — groups operational knowledge under one subtree; see knowledge/README.md).
| Area | Path | Status |
|---|---|---|
| Index | knowledge/README.md | Navigation |
| Patterns | knowledge/patterns/ | Structure only |
| Playbooks | knowledge/playbooks/ | Pointers to procedures |
| Recipes | knowledge/recipes/ | Structure only |
| ADR | knowledge/adr/ | Structure only |
| Lessons | knowledge/lessons/ | Structure only |
| Assets | knowledge/assets/ | Template links |
| Decision records | knowledge/decision-records/ | EOS engineering decisions |
12. Runtime Context Providers
Contract: RuntimeContextProviderContract · phase-11-engineering-runtime-contracts.md §9
Canonical inventory: context-providers-manifest.md
Configuration template: .cursor/mcp/mcp.config.template.json → .cursor/mcp.json (Developer local, gitignored)
Adapter mapping: cursor-adapter-v1-profile.md
Status: Phase 11-7 — configuration layer implemented · all providers disabled pending Architect approval
| Document | Role |
|---|---|
| context-providers-manifest.md | Canonical provider inventory |
| .cursor/mcp/governance.md | Adapter governance policy |
| .cursor/mcp/registry.md | Adapter registry summary |
| .cursor/mcp/manifest.md | Adapter mirror pointer |
| mcp-governance.md | Repository pointer |
| mcp-registry.md | Repository pointer |
Immediate tier (disabled)
| Provider ID | Name | Access | Enabled | Template |
|---|---|---|---|---|
provider-github | GitHub | read-only | No | .cursor/mcp/providers/provider-github.json |
provider-laravel-docs | Laravel Docs | read-only | No | .cursor/mcp/providers/provider-laravel-docs.json |
provider-php-docs | PHP Docs | read-only | No | .cursor/mcp/providers/provider-php-docs.json |
Fail-closed: No committed .cursor/mcp.json. Runtime Enforcement denies MCP until Developer enables locally after Architect approval. No write-capable providers. No secrets in Git.
12A. Runtime Execution
Contract: RuntimeExecutionContract · phase-11-engineering-runtime-contracts.md §10
Canonical inventory: execution-manifest.md
CLI configuration: .cursor/cli.json
Cloud configuration: .cursor/environment.json
Adapter mapping: cursor-adapter-v1-profile.md
Status: Phase 11-8 — execution layer implemented · subordinate to all prior ERP layers
| Document | Role |
|---|---|
| execution-manifest.md | Canonical execution mode inventory |
| .cursor/execution/manifest.md | Adapter mirror pointer |
| .cursor/cli.json | CLI permission overlay |
| .cursor/environment.json | Cloud bootstrap config |
Execution modes
| Execution ID | Mode | Native artifact | Owner |
|---|---|---|---|
execution-local | Local | Committed .cursor/ workspace | Developer IDE session |
execution-cli | CLI | .cursor/cli.json | Developer terminal |
execution-cloud | Cloud | .cursor/environment.json + dashboard | Cursor Cloud VM |
execution-background | Background | Inherits parent .cursor/ mirror | Async continuation |
Boundaries: Execution hosts ERP components from committed mirror — does not replace governance. No Git freeze from remote. No autonomous Architect review. No secrets in committed execution config.
13. Phase delivery status
Phase 10 (EOS v1.0)
| Sub-phase | Status |
|---|---|
| 10-1 Discovery | Complete |
| 10-2 Specification | Complete |
| 10-3 Foundation | Complete |
| 10-4 Content Review | Complete |
| 10-5 Refinement | Complete |
| 10-6 Validation | Complete |
| 10-7 Hardening | Complete |
| 10-8 Freeze Preparation | Complete |
| 10-9 Git Freeze | Pending — Developer only |
Phase 11 (ERP v1.0)
| Sub-phase | Status |
|---|---|
| 11-1 Discovery | Complete |
| 11-2 Specification | Complete |
| 11-2A Runtime-agnostic refinement | Complete |
| 11-2B Documentation alignment | Complete |
| 11-2C Runtime Contracts | Complete |
| 11-3 Adapter version control & constraints | Complete |
| 11-4 Procedures & workflows specification | Complete |
11-4A Runtime Procedures (RuntimeProcedureContract) | Complete |
11-4B Runtime Workflows (RuntimeWorkflowContract) | Complete |
11-5 Runtime Delegation (RuntimeDelegationContract) | Complete |
11-6 Runtime Enforcement (RuntimeEnforcementContract) | Complete |
11-7 Runtime Context Providers (RuntimeContextProviderContract) | Complete |
11-8 Runtime Execution (RuntimeExecutionContract) | Complete |
| 11-9 Validation & freeze prep | Complete — ERP v1.0 validated; Ready for Phase 11-10 |
| 11-10 Acceptance, DX & freeze preparation | Complete — developer guides · RESPONSE_TEMPLATE v2 (nine sections) |
| 11-11 Git Freeze | Pending — Developer only — tag v5.1-engineering-runtime-platform |
14. Version control policy (adapter workspace)
Current state: Enacted Phase 11-3 — .cursor/ engineering assets are tracked in Git. Secrets and local overrides excluded — see .cursor/VERSION_CONTROL.md.
Belongs in Git (when policy enacted — Adapter v1)
| Path | ERP component |
|---|---|
.cursor/rules/ | Runtime Constraints |
.cursor/skills/ | Runtime Procedures + Runtime Workflows |
.cursor/agents/ | Runtime Delegation stubs |
.cursor/hooks.json + .cursor/hooks/ | Runtime Enforcement |
.cursor/mcp/mcp.config.template.json + .cursor/mcp/providers/ | Runtime Context Providers (templates — no secrets) |
.cursor/mcp/governance.md, .cursor/mcp/registry.md, .cursor/mcp/manifest.md | Context provider policy |
.cursor/environment.json · .cursor/cli.json · .cursor/execution/manifest.md | Runtime Execution |
.cursor/manifest/ | Adapter workspace manifest |
docs/development/ manifests, prompts, templates, ERP spec, and adapter profiles always belong in Git — canonical repository truth for EOS and ERP Core.
Never belongs in Git
| Item | Rationale |
|---|---|
| MCP tokens, API keys, credentials | Secrets — Developer local only |
.cursor/mcp.json | Local enablement with env bindings — gitignored |
| Personal IDE user settings | Not engineering assets |
| Chat history or session exports | Not repository truth |
Rationale
EOS and ERP principle "Repository Is Truth" requires shareable engineering assets in Git. Adapter v1 workspace tracking enacted in Phase 11-3. Exclude .cursor/mcp.json and local override patterns only.
Permanent engineering asset index for ZAIXOS. Update at EOS/ERP amendments and freeze phases.