AI Development Environment
Status: Permanent — Engineering Operating System v1.0
Applies to: Every Architecture, Planning, Prompt Design, Implementation, Review, Hardening, and Freeze workflow
Authority: Canonical reference for Developer, ChatGPT Desktop, Cursor Agent, OpenAI Codex, and Repository collaboration
Baseline (runtime): v4.2-public-experience-platform
Target freeze (EOS): v5.0-ai-development-environment — release doc
Asset index: ENGINEERING_INDEX.md
Design authority: runtime/specification/archive/phase-10-ai-development-environment-specification.md
Runtime authority: runtime/specification/engineering-runtime-platform.md (ERP Core)
Purpose
This document is the official AI Development Environment / Engineering Operating System (EOS) v1.0 methodology for the ZAIXOS Engineering Platform (ZEP) repository.
Every future phase must follow this methodology. It complements — and does not replace — docs/architecture/ (what must be built) and docs/releases/ (frozen baselines).
Supporting operational documents live in docs/development/. This document is the root authority for AI-assisted workflow, terminology, context rules, and tool responsibilities. Runtime Constraints, Runtime Procedures, Runtime Workflows, Runtime Delegation, and Runtime Context Providers are indexed in ENGINEERING_INDEX.md and specified in runtime/specification/engineering-runtime-platform.md (ERP Core).
Engineering Stack
Permanent layering — governance first, runtime abstraction second, vendor implementation last:
EOS (Engineering Operating System)
↓ what engineering governance is
ERP Core (Engineering Runtime Platform)
↓ abstract runtime concepts — IDE-agnostic
Runtime Adapter
↓ maps ERP Core to native IDE files (Adapter v1: Cursor)
Native IDE Runtime
↓ session execution (constraints, procedures, enforcement)
Human Authority (Architect + Developer)
↓ approval, review, freeze, Git| Layer | Authority document | Role |
|---|---|---|
| EOS | This document + Phase 10 spec | Methodology, manifests, templates, Architect workflow |
| ERP Core | runtime/specification/engineering-runtime-platform.md | Abstract runtime components, validation, adapter interfaces |
| Runtime Adapter | adapters/cursor-adapter-v1/profile.md (v1) | Native paths, formats, capability mapping |
| Native IDE | Adapter profile + IDE vendor docs | Session injection and execution |
Rule: ERP Core never embeds vendor-specific normative terms. Cursor is Adapter v1 only — not the runtime specification.
Official Terminology
Use these canonical terms in all development documentation, prompts, and reviews.
| Term | Definition |
|---|---|
| Engineering Operating System (EOS) | Permanent engineering governance — methodology, manifests, templates, lifecycle |
| Engineering Runtime Platform (ERP Core) | IDE-agnostic runtime abstraction — constraints, procedures, workflows, delegation, enforcement, context |
| Runtime Adapter | Vendor-specific mapping of ERP Core to native IDE files and formats |
| Native IDE Runtime | Session-time execution layer (injection, procedures, enforcement) |
| Runtime Implementation | Scoped code or documentation work executed via Runtime Adapter |
| Runtime Implementation Context | Material scoped for Runtime Implementation (indexing, @files, open editors) |
| Runtime Validation | Manual and automated checks proving adapter parity with ERP Core and EOS manifests |
| ERP Report | Format A or Format B deliverable from a Runtime Implementation pass |
| AI Development Environment | The five-component collaboration system: Developer, Repository, ChatGPT Desktop, Runtime Adapter tools, OpenAI Codex |
| Developer | Human owner of approvals, freeze, releases, and Git decisions |
| Repository | Git working tree — single source of truth for code, tests, and governance docs |
| ChatGPT Desktop | Architect tool — IDE integration, uploads, multi-modal review |
| Architect | The architecture/review role performed by ChatGPT Desktop (not Runtime Implementation agents) |
| Architect Context | All material shared with ChatGPT Desktop for planning, specification, or review |
| Live Context | Exactly one active editor tab shared via ChatGPT Desktop IDE bridge |
| Uploaded Context | Files manually attached in ChatGPT Desktop |
| Visual Context | Screenshots, images, PDFs shared with ChatGPT Desktop |
| Text Context | Pasted terminal output, logs, ERP reports, markdown snippets |
| Runtime Adapter v1 (Cursor) | First supported Runtime Adapter — see adapters/cursor-adapter-v1/profile.md |
| Cursor Agent | Cursor-native prompt-driven implementation agent (Adapter v1) |
| OpenAI Codex | Autonomous Implementation Agent inside Cursor (Adapter v1) |
| Autonomous Implementation Agent | Codex's role — multi-step execution without per-step paste |
Legacy term: Context File referred to Runtime Implementation Context in older documentation. Use Runtime Implementation Context unless citing legacy text.
AI Development Environment Overview
┌──────────────────────────────────────────────────────────────────────┐
│ Repository (source of truth) │
└───────────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Developer │ │ ChatGPT Desktop │ │ ERP Runtime Layer │
│ │◀────▶│ (Architect) │ │ Adapter → Native │
└─────────────┘ └──────────────────┘ │ IDE (Adapter v1) │
└─────────────────────┘| Component | Authority level |
|---|---|
| Developer | Final approval — architecture, implementation, freeze, releases, Git |
| ChatGPT Desktop | Architecture authority — specifications, reviews, prompt design |
| Runtime Adapter + Native IDE | Runtime Implementation — no architecture authority |
| Repository | Source of truth — overrides chat assumptions |
Official Context Hierarchy
Architect Context for ChatGPT Desktop follows this permanent priority:
Live Context
↓
Uploaded Files
↓
Images / PDFs
↓
Copied Specifications
↓
Conversation History
↓
General KnowledgeRules
| Rule | Detail |
|---|---|
| Live Context = one tab | Exactly one active editor tab via IDE bridge; switching tabs replaces Live Context immediately |
| Uploaded files extend Architect Context | Additional Primary documents must be uploaded — not assumed from prior tabs |
| Runtime indexing is independent | Native IDE runtimes use repository indexing, @files, @folders — ChatGPT does not |
| ChatGPT never indexes repositories | No automatic full-repo access; only explicit sharing counts as reviewed |
Governance document priority (within Uploaded / Live)
When choosing which file to share first:
Release Docs → Architecture Docs → Development Docs → Implementation Files → External ReferencesIf Release Docs conflict with Conversation History, Release Docs win. If Specifications conflict with implementation, Specifications win (until formally revised by Architect).
Runtime Implementation Context (separate channel)
Runtime Implementation Context for Runtime Adapter / Native IDE sessions includes:
- Repository indexing
- Open editors
@files/@folders- Selections
- Terminal output
- Git history (when available)
ChatGPT does not consume Runtime Implementation Context unless Developer copies it into Text Context.
Legacy term: Implementation Context and Cursor Context — use Runtime Implementation Context.
Official AI Responsibilities
Developer
| Responsibility | Detail |
|---|---|
| Architecture approval | Accepts or rejects Architect recommendations before implementation |
| Implementation approval | Reviews Runtime Implementation output before sharing with Architect |
| Freeze | Executes backup, commit, tag, push on Architect instruction only |
| Releases | Owns release doc hash update timing with Architect guidance |
| Git decisions | Final authority on destructive or out-of-scope Git operations |
ChatGPT Desktop (Architect)
| Responsibility | Detail |
|---|---|
| Architecture | Module design, boundaries, contract-first patterns |
| Specifications | Phase architecture specs — design-only before code |
| Reviews | RESPONSE_TEMPLATE.md after every implementation pass |
| Planning | Scope, baseline verification, non-goals |
| Prompt generation | Runtime Implementation prompts for approved specifications |
| Documentation | Methodology, release doc guidance, governance alignment |
Runtime Implementation (Adapter v1: Cursor Agent / Codex)
| Responsibility | Detail |
|---|---|
| Repository understanding | Workspace indexing and navigation via Runtime Adapter |
| Implementation | Scoped changes within authorized Runtime Implementation prompts |
| Navigation | Cross-file edits within prompt scope |
| Refactoring | Structural changes when explicitly prompted |
| Project-wide edits | Multi-file updates under Developer + Architect authorization |
Adapter v1 native tools: Cursor Agent (prompt-driven) · OpenAI Codex (autonomous, terminal-heavy).
Repository
| Responsibility | Detail |
|---|---|
| Source of truth | Code, tests, docs/architecture/, docs/development/, docs/releases/ |
Official Development Workflow
Canonical lifecycle for every phase:
Idea
↓
Architecture
↓
Specification
↓
Prompt Design
↓
Implementation
↓
Review
↓
Hardening (if required)
↓
Freeze
↓
ReleaseStage reference
| Stage | Primary AI | Secondary AI | Context source | Expected deliverables |
|---|---|---|---|---|
| Idea | Developer | ChatGPT Desktop | Conversation; optional Visual/Text | Problem statement, scope hypothesis |
| Architecture | ChatGPT Desktop | Developer | Live Context: architecture doc; Upload: release doc | Approved direction, constraints, non-goals |
| Specification | ChatGPT Desktop | Developer | Live Context: spec or MODULE_BOUNDARIES.md; Upload: reference platform | Architecture Specification (no code) |
| Prompt Design | ChatGPT Desktop | — | Architect prior outputs; governance refs | Ready-to-paste Runtime Implementation prompt |
| Implementation | Runtime Adapter (Native IDE) | Developer monitors | Runtime Implementation Context: @files, @folders, indexing | Code, tests, ERP report (Format A) |
| Review | ChatGPT Desktop | Developer delivers | Text Context: ERP report; Upload: tests/config; Live: key file | RESPONSE_TEMPLATE (nine sections — ERP v1.0), Decision |
| Hardening | Runtime Adapter (Native IDE) | ChatGPT Desktop | Runtime Implementation Context per hardening prompt | Corrective/additive changes, updated ERP report |
| Freeze | Developer | ChatGPT Desktop instructs | Text: git status, test output; Upload: release draft | Backup, commit, tag, push per GIT_FREEZE_PROCEDURE.md |
| Release | ChatGPT Desktop validates | Developer executes | Upload: final docs/releases/{version}.md | Tagged baseline, remote verified, next phase declared |
Hardening repeats Implementation → Review until Decision is Approved. See DEVELOPMENT_WORKFLOW.md for the Architecture Review Loop.
Tool selection at Runtime Implementation
| Situation | Preferred native tool (Adapter v1) |
|---|---|
| Architecture-sensitive, tight scope | Cursor Agent |
| Repetitive, multi-step, terminal-heavy | OpenAI Codex (after architecture approval) |
| Documentation-only phase | Cursor Agent (or Codex with doc folder scope) |
Capability Matrix
Canonical comparison — ChatGPT Desktop (Architect) vs Runtime Implementation native tools (Adapter v1: Cursor Agent · OpenAI Codex).
| Capability | ChatGPT Desktop | Cursor Agent | OpenAI Codex |
|---|---|---|---|
| Repository indexing | No | Yes | Yes |
| Active editor access (Live Context) | Yes — one tab | Yes — multiple tabs | Yes — via Cursor |
| Multi-file context | No (Upload only) | Yes | Yes |
| Uploaded files | Yes | N/A | N/A |
| Images | Yes | Partial | Partial |
| PDFs | Yes | Limited | Limited |
| Markdown | Yes (Live/Upload/Text) | Yes | Yes |
| Architecture review | Yes — authority | No | No |
| Implementation | No | Yes | Yes |
| Autonomous execution | No | Limited | Yes — primary |
| Terminal | No | Yes | Yes |
| Git | No | On Developer request | When authorized in task |
| Testing | No | Yes | Yes |
| Planning | Yes — architecture | Prompt-scoped | Yes — plan mode |
| Background execution | No | Limited | Yes |
| Prompt generation | Yes — authority | No | No |
Official Best Practices
Architecture work
- Keep architecture documents as Live Context during Architecture and Specification stages.
- Upload additional documents manually when multiple files are required — never rely on tab switching alone.
- Architecture decisions always originate from ChatGPT Desktop (Architect).
Runtime Implementation work
- Allow the Runtime Adapter to use repository indexing and
@references during implementation. - Use OpenAI Codex only after architecture approval — never before Specification is accepted (Adapter v1).
- Review all Runtime Implementation output before sharing ERP report with Architect.
- Prefer Cursor Agent for boundary-sensitive platform modules (Adapter v1).
Review and freeze
- Never freeze code that has not passed Architecture Review with Decision: Approved.
- Paste ERP reports as Text Context — they are not automatically visible to Architect.
- Freeze Git is Developer-only on Architect instruction — even if a native tool ran git during a task.
Context hygiene
- Confirm which tab is Live Context before requesting Architect review.
- Close unrelated IDE tabs to reduce Runtime Implementation Context noise.
- Label pre-existing issues explicitly in ERP reports.
Permanent Rules
These rules are immutable unless changed through an explicit documentation phase.
| # | Rule |
|---|---|
| 1 | ChatGPT never assumes repository state — verify via Text Context (git status, test output) |
| 2 | Runtime Implementation never becomes the architecture authority |
| 3 | Autonomous agents never become the architecture authority |
| 4 | Live Context is temporary — one active tab; not retained on switch |
| 5 | Uploaded files become conversation context — persist in chat; Live Context does not |
| 6 | Repository remains the source of truth |
| 7 | Specifications override implementation — until Architect revises specification |
| 8 | Frozen architecture cannot be bypassed — see FREEZE_POLICY.md |
| 9 | Architecture precedes implementation — no implementation prompt before approved Specification |
| 10 | No freeze without Approved — Architecture Review Loop must exit with Decision: Approved |
| 11 | Developer owns freeze Git — Architect instructs timing only |
| 12 | ERP reports require Architect review — Runtime Implementation output is not self-approved |
Future AI Integration
Distinction: This section covers development tooling (ChatGPT Desktop, Runtime Adapters, native IDE agents). The product AI architecture — AI workers, Platform Contract consumption, and the three-layer knowledge model — is defined separately in AI-Native Platform Architecture (ANPA).
New AI tools may be added as Runtime Adapters without redesigning EOS or ERP Core.
A new assistant must document only:
| Field | Question answered |
|---|---|
| Responsibility | What work it performs (architecture vs implementation vs execution) |
| Context capabilities | Live, upload, indexing, terminal, etc. |
| Workflow stage | Which canonical stage(s) it participates in |
| Authority level | Whether it can approve architecture, implementation, or freeze |
Integration procedure:
- Add the tool to the Capability Matrix in this document
- Update CHATGPT_CURSOR_COLLABORATION.md role table
- Update DEVELOPMENT_WORKFLOW.md stage table if workflow changes
- Do not weaken Permanent Rules or architecture governance
New tools default to implementation authority only unless explicitly promoted through architecture review.
Related Documents
| Document | Role |
|---|---|
| ENGINEERING_INDEX.md | Canonical index of EOS and ERP assets |
| runtime/specification/archive/phase-10-ai-development-environment-specification.md | EOS v1.0 design authority |
| runtime/specification/engineering-runtime-platform.md | ERP Core design authority |
| adapters/cursor-adapter-v1/profile.md | Runtime Adapter v1 profile (Cursor) |
| ../technical/TECHNICAL_ARCHITECTURE.md | Product AI architecture methodology (ANPA) — separate from development tooling |
| DEVELOPMENT_WORKFLOW.md | Operational lifecycle, baseline verification, review loop |
| CONTEXT_FILE_POLICY.md | Architect and Implementation Context delivery rules |
| CHATGPT_CURSOR_COLLABORATION.md | Role boundaries and collaboration flow |
| RESPONSE_TEMPLATE.md | Architect review response format |
| PHASE_CHECKLIST.md | Pre-baseline and Git freeze checklist |
| GIT_FREEZE_PROCEDURE.md | Developer Git commands at freeze |
Repository is truth. Architect designs. Runtime Adapter implements. Developer approves and freezes.