ERP Developer Guide

Version: 1.0 · ERP: v1.0 · Adapter: Cursor Adapter v1
Audience: Developers new to this repository or migrating ERP to another project
Lifecycle: Standalone platform repository — platform authority at PLATFORM_INDEX.md (ZEP)
Start here after clone: this guide · Asset map: ENGINEERING_INDEX.md

---

What ERP Is

The Engineering Runtime Platform (ERP) is the layer between governance documents and your IDE. It answers: how does engineering work actually run in Cursor?

Documentation Authority (docs/architecture/, docs/releases/)
    → ERP Core (abstract components — IDE-agnostic)
    → Runtime Adapter (Cursor v1 — .cursor/ workspace)
    → Native IDE Runtime (Agent session)
    → Human Authority (Architect review + Developer Git)

ERP is not Laravel application code. It is the committed engineering workspace (.cursor/) plus canonical manifests in docs/development/.

You want to…	Read
Understand the full asset map	ENGINEERING_INDEX.md
See Cursor-specific file paths	adapters/cursor-adapter-v1/profile.md
Validate ERP is working	docs/runtime-validation.md
Accept ERP before freeze	docs/acceptance-checklist.md
Official lifecycle steps	DEVELOPMENT_WORKFLOW.md

---

How ERP Works (Five Minutes)

ERP component	What it does in practice	Where (Cursor v1)
Runtime Constraints	Non-negotiable rules loaded every session	.cursor/rules/*.mdc
Runtime Procedures	Domain guidance (architecture, Laravel, testing…) — may auto-invoke	.cursor/skills/{domain}/SKILL.md
Runtime Workflows	Explicit phase commands (/phase, /discovery…) — you must invoke	.cursor/skills/{workflow}/SKILL.md
Runtime Delegation	Specialist subagents for scoped tasks	.cursor/agents/*-agent.md
Runtime Enforcement	Blocks destructive Git, readonly violations, MCP without config	.cursor/hooks.json
Runtime Context Providers	External read-only context (disabled by default)	.cursor/mcp/ + local mcp.json
Runtime Execution	Local / CLI / Cloud / Background modes	.cursor/cli.json, .cursor/environment.json

Golden rules:

1. Workflows are explicit — type /phase or invoke the workflow skill; they do not auto-run.
2. Procedures are advisory — they guide the agent; they do not approve architecture.
3. Architect approves — via RESPONSE_TEMPLATE.md, not via agent self-approval.
4. Git is Developer-only — agents must not push, tag, or freeze.

---

Starting a New Project (or New Phase)

1. Clone and open

git clone <repository>
cd "zaixos-engineering-platform"
# Open in Cursor — project .cursor/ loads automatically

No user-home Cursor configuration is required for ERP constraints. See .cursor/VERSION_CONTROL.md.

2. Confirm baseline

Step	Action
Find latest release	docs/releases/ — highest version tag
Read boundaries	MODULE_BOUNDARIES.md
Confirm ERP assets	docs/acceptance-checklist.md § Installation

3. Start Architect chat

Share with ChatGPT Desktop (Architect):

• Latest docs/releases/*.md (Live Context — one tab)
• ENGINEERING_INDEX.md or phase spec (Upload)
• Baseline tag name (Text Context)

See DEVELOPMENT_WORKFLOW.md § Starting a New Chat.

4. Run Bootstrap workflow

Invoke workflow-bootstrap (legacy alias /bootstrap) when starting a new phase. Produces Format B ERP report confirming readiness.

---

Official Workflow (End-to-End)

Discovery → Specification → Phase Implementation → Review
    → Hardening → Freeze Preparation → Architecture Review → Git Freeze → Release doc

Stage	Who invokes	Runtime Workflow	ERP report
Discovery	Architect	workflow-discovery (/discovery)	Format B
Specification	Architect	workflow-spec (/spec)	Format B
Implementation	Architect → Developer	workflow-phase (/phase)	Format A
Review prep	Developer	workflow-review (/review)	A or B
Hardening	Architect → Developer	workflow-hardening (/hardening)	Format A
Freeze prep	Architect	workflow-freeze (/freeze)	Format B
Release doc	Documentation delegate + Architect	workflow-release (/release)	Format B
Status check	Developer	workflow-status (/status)	B-aligned
Any pass report	Developer	workflow-report (/report)	A or B

Git freeze is not a workflow. After Architect approval, Developer runs GIT_FREEZE_PROCEDURE.md manually.

Full workflow inventory: runtime/manifests/defaults/workflows-catalog.md.

---

Discovery

Goal: Understand scope, constraints, and frozen platforms before writing a spec.

Item	Detail
Invoker	Architect
Workflow	workflow-discovery · template: prompts/commands/discovery.md
Procedures	skill-architecture, skill-documentation (advisory)
Delegate (optional)	delegate-architecture (readonly explore)
Output	Format B report → Architect review

Developer role: Run Runtime Implementation when Architect provides the prompt; paste Format B report back to Architect.

---

Specification

Goal: Authoritative phase spec before any code.

Item	Detail
Invoker	Architect
Workflow	workflow-spec · template: prompts/commands/spec.md
Output	Spec under docs/development/ + Format B report

Developer role: Documentation-only Runtime Implementation unless Architect authorizes code.

---

Runtime Implementation

Goal: Execute approved spec scope in the codebase.

Item	Detail
Invoker	Architect (prompt) → Developer (Cursor Agent)
Workflow	workflow-phase · template: prompts/commands/phase.md
Procedures	skill-platform, skill-laravel, skill-ddd, skill-testing
Delegates	delegate-implementation, delegate-testing (parallel)
Output	Format A ERP report

Format A sections: Architecture Summary · Files Changed · Tests · Remaining Risks

Template: templates/implementation-report.md

After implementation: Paste Format A to Architect → receive RESPONSE_TEMPLATE.md response.

---

Architecture Review

Goal: Architect decides Approved / Approved with hardening / Rejected.

Item	Detail
Owner	ChatGPT Desktop (Architect) only
Format	RESPONSE_TEMPLATE.md — nine sections (not an ERP report)
Developer action	Follow Decision, Developer Actions, Runtime Workflow, and Git Actions sections

Architecture Review covers scope, patterns, tests, and governance — not IDE session mechanics.

---

ERP Runtime Validation

Goal: Confirm .cursor/ ERP layer is loaded and behaving.

Manual steps: docs/runtime-validation.md
Acceptance gate: docs/acceptance-checklist.md

Architect may reference runtime validation results in §2 ERP Runtime Validation of the response template.

---

Freeze

Goal: Immutable baseline tag after approval.

Step	Owner	Document
Freeze preparation	Architect invokes workflow-freeze	Format B report
Architecture Review	Architect	RESPONSE_TEMPLATE §7 Freeze Status
Backup	Developer	BACKUP_POLICY.md
Commit / tag / push	Developer	GIT_FREEZE_PROCEDURE.md

ERP target tag (provisional): v5.1-engineering-runtime-platform

Agents and workflows must not execute Git freeze.

---

Reports (ERP Runtime Reports)

Two formats only — never invent a third.

Format	When	Sections
A	Code/runtime passes	Architecture Summary, Files Changed, Tests, Remaining Risks
B	Documentation-only passes	Summary, Files Created, Files Modified, Verification, Remaining Gaps, Decision

Generate via workflow-report or follow templates/implementation-report.md.

Architect review uses RESPONSE_TEMPLATE — eight sections in legacy EOS; nine sections in ERP v1.0.

---

Finding the Right Skill or Agent

Runtime Procedures (domain skills)

Inventory: runtime/manifests/defaults/procedures-manifest.md

Need	Manifest ID	Path
Architecture / boundaries	skill-architecture	.cursor/skills/architecture/SKILL.md
Platform patterns	skill-platform	.cursor/skills/platform/SKILL.md
Laravel implementation	skill-laravel	.cursor/skills/laravel/SKILL.md
Tests	skill-testing	.cursor/skills/testing/SKILL.md
Documentation	skill-documentation	.cursor/skills/documentation/SKILL.md

Procedures auto-invoke when the agent matches the skill description. They do not replace workflows.

Runtime Workflows (explicit only)

Inventory: runtime/manifests/defaults/workflows-catalog.md

In Cursor: invoke by name (/phase, /discovery) or open the workflow skill with disable-model-invocation: true.

Common mistake: Expecting /phase to run automatically — it will not. You must invoke it.

Runtime Delegation (subagents)

Inventory: runtime/manifests/defaults/delegation-manifest.md

Need	Delegate	Readonly
Compliance matrix	delegate-architecture	Yes
Scoped implementation	delegate-implementation	No
Run tests	delegate-testing	No
Security diff review	delegate-security	Yes
Pre-review diff	delegate-review	Yes

Escalation: Delegate → Developer → Architect. Delegates never talk to ChatGPT directly.

---

Daily Workflow Examples

Example A — Small documentation fix

1. Architect provides scoped prompt (no new spec required for trivial doc fix)
2. Developer runs Cursor Agent on docs/development/ only
3. Developer produces Format B report
4. Architect responds with RESPONSE_TEMPLATE (Git Actions: No)

Example B — New production phase

1. Architect: /discovery → Format B → review
2. Architect: /spec → spec doc → review
3. Architect: /phase prompt → Developer implements → Format A
4. Developer: /review optional + architecture tests
5. Architect: hardening or freeze path
6. Architect: /freeze → Developer: GIT_FREEZE_PROCEDURE

Example C — ERP validation before freeze

1. Developer: docs/acceptance-checklist.md
2. Developer: docs/runtime-validation.md
3. Paste results to Architect as Text Context
4. Architect: Acceptance Status in RESPONSE_TEMPLATE

---

Common Mistakes

Mistake	Correct approach
Agent pushes to Git	Blocked by hooks; freeze is Developer-only
Skipping Architect review	Every pass ends with RESPONSE_TEMPLATE
Using Format C or custom report	Format A or B only
Relying on ~/.cursor/ rules	Use committed .cursor/ only
Enabling MCP without approval	All providers disabled until Architect ADR
Confusing Procedures with Workflows	Workflows = explicit invocation
Autonomous freeze approval	Architect + Developer Git only
Editing ERP Core for Cursor paths	Vendor paths live in adapter profile only

---

Migrating ERP to Another Project

ERP is designed to be extractable as a reusable engineering platform.

Layer	Migrate	Notes
docs/development/ manifests + ERP specs	✓	Adjust project-specific README links
.cursor/ adapter workspace	✓	Full Cursor Adapter v1
docs/architecture/	Project-specific	Keep constitution pattern
tests/Architecture/Engineering*IntegrityTest.php	Optional	Architecture validation
Laravel app/Modules/	✗	Not part of ERP

Steps:

1. Copy docs/development/ ERP manifests, specs, guides, and adapters/
2. Copy .cursor/ engineering assets per VERSION_CONTROL.md
3. Copy architecture integrity tests if desired
4. Update ENGINEERING_INDEX.md baseline tags and project name
5. Run docs/acceptance-checklist.md in the target repo
6. Future adapters: add profile under docs/development/adapters/ without changing ERP Core

---

Related Documents

Document	Role
DEVELOPMENT_WORKFLOW.md	Operational lifecycle detail
RESPONSE_TEMPLATE.md	Architect review format
CHATGPT_CURSOR_COLLABORATION.md	Role boundaries
docs/planning/archive/erp-freeze-preparation.md	Phase 11-9 validation record
GIT_FREEZE_PROCEDURE.md	Developer Git sequence

---

ERP Developer Guide v1.0 — permanent onboarding document. Update only through documentation phases.