README

Comprehensive guidelines for AI-assisted development within the Editor platform

AI Documentation - editor2 Platform

Documentation optimized for AI code generators Version: 1.0.0 | Last Updated: December 27, 2025

Purpose

This directory contains documentation specifically designed for AI code generators (Claude, GPT, Copilot, etc.) to efficiently generate business modules for the editor2 platform.

Document Index

Document	Purpose	Priority
MODULE-TEMPLATE.md	Complete module structure and code templates	Start Here
AI-RULES.md	Mandatory rules and patterns for AI code generation	Critical
QUICK-REFERENCE.md	Copy-paste ready code snippets	Reference
WORKFLOW-GUIDE.md	How to use WorkflowService	Reference
AGENT-GUIDE.md	How to use AgentProcessService	Reference
INTELLIGENCE-PYRAMID-GUIDE.md	MCP tools usage	Reference

Quick Start for AI Generators

1. Read the Rules First

Start by reading AI-RULES.md to understand mandatory patterns and anti-patterns.

2. Use the Template

Follow MODULE-TEMPLATE.md for the complete module structure.

3. Copy Code Snippets

Use QUICK-REFERENCE.md for ready-to-use code templates.

4. Integrate with editor2 Systems

Flash Persistence: Use autoFlashState for persistent UI state
Theme System: Use CSS variables (var(--ux-*))
Intelligence Pyramid: Call preflight() before generation, log_decision() after

Module Generation Overview

Location

libs/libs-modules/<module-name>/     # Business modules

Library Alias

@libs-modules/<module-name>

Core Contract

All modules MUST implement BrowserModuleContract from @libs-core/module-base.

Generation Methods

Method 1: AI Platform Generator (Complete Platforms)

Route: /modularity/ai-platform
Use for: Multi-module business platforms
Output: Complete universe with 5-10 modules
Service: WorkflowService (5-phase with SSE)

Method 2: Module Workbench (Guided Creation)

Route: /modularity/workbench
Use for: Individual modules with step-by-step guidance
Output: Single Nx library module
Service: AgentProcessService (8-phase with learning)

Method 3: AI Builder (Quick Scaffolding)

Route: /modularity/ai-builder
Use for: Quick module scaffolding
Output: Module definition
Service: AIModuleGeneratorService

Method 4: Modular Universe (Visual Canvas)

Route: /modular-universe
Use for: Visual universe building with AI modules
Output: Visual universe structure
Service: AI Panel + UniverseModuleService

Required Core Library Integrations

Library	Purpose	Import
`@libs-core/module-base`	Module contract	`BrowserModuleContract, ModuleDecorator, ModuleManifest`
`@libs-core/log-system`	Logging	`LoggerService`
`@libs-core/security`	Auth & guards	`authGuard, permissionGuard, roleGuard`
`@libs-core/shared-models`	Base types	`BaseEntity, ApiResponse, Permission`
`@libs-core/action-registry`	Public actions	`PublicAction, ExecutableAction`
`@libs-core/data-access`	Repositories	`BaseRepository`
`@libs-core/event-system`	Domain events	`EventBusService, DomainEvent`
`@storage-system`	Flash persistence	`autoFlashState, GgStorage`

editor2-Specific Features

Three-Tier AI Architecture

Tier 1: Development AI (MCP with Cursor)
Tier 2: Platform AI (WorkflowService, AgentProcessService)
Tier 3: Tenant AI (SpaceAgentOrchestrator)

Intelligence Pyramid

// Load context before generation
await preflight({ task: 'Generate module' });

// Log decisions after generation
await log_decision({
  type: 'implementation',
  question: 'How to implement?',
  chosen: 'Selected approach',
  reasoning: 'Because...',
  confidence: 0.9
});

Flash Persistence

// Automatic state persistence
readonly settings = autoFlashState('settings', { theme: 'dark' });

Theme System

// Use CSS variables only
.my-component {
  background: var(--ux-surface);
  color: var(--ux-text-primary);
  backdrop-filter: blur(16px);
}

Essential Patterns

Angular 20 Requirements

Standalone components ONLY
OnPush change detection ALWAYS
inject() function for DI (not constructor injection)
Signals for local state
RxJS for async operations
Separate files (.ts, .html, .scss) - BEST PRACTICE

Naming Conventions

Files: kebab-case (e.g., user-management.module.ts)
Classes: PascalCase (e.g., UserManagementModule)
Variables: camelCase (e.g., userManagement)
Permissions: <resource>:<action> (e.g., users:read)

Required Documentation

Each module needs documentation in docs/english/modules/<module-name>/:

README.md - Overview
requirements.md - Requirements
design.md - Architecture
tasks.md - Implementation tasks

Anti-Patterns to Avoid

NgModules (use standalone: true)
Constructor injection (use inject())
setTimeout in production (use RxJS)
Promises (use RxJS)
Inline templates (use separate .html files)
Inline styles (use separate .scss files)
Hardcoded colors (use CSS variables)
Direct localStorage (use autoFlashState)
any type (use SafeAny if needed)

Checklist

Before marking a module complete, verify:

Implements BrowserModuleContract
Uses @ModuleDecorator
All routes protected with guards
All components standalone + OnPush
All components use separate .ts, .html, .scss files
All actions use @PublicAction
Repository extends BaseRepository
Events extend DomainEvent
Uses autoFlashState for persistent state
Uses CSS variables (no hardcoded colors)
Documentation complete
Barrel exports complete
Called preflight() before generation
Logged decision with log_decision()