README

A powerful framework for Domain-Driven Design (DDD) code generation with integrated AI governance

Featuring the revolutionary AI Self-Evaluation Protocol

🌟 Overview

DDD-IA-CONTEXT combines Domain-Driven Design principles with AI-assisted code generation, ensuring architectural consistency through the innovative AI Interpretation Protocol (AIP).

This standardized protocol ensures consistent behavior across all AI models, eliminating interpretation variance and delivering predictable, high-quality code generation.

┌───────────────────────────────────────────────────────────────┐
│                                                               │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     │
│  │   Domain    │     │ Application │     │Infrastructure│     │
│  │    Layer    │◄───►│    Layer    │◄───►│    Layer    │     │
│  └─────────────┘     └─────────────┘     └─────────────┘     │
│                                                               │
└───────────────────────────────────────────────────────────────┘

📦 Installation

🚀 Standard Installation

composer require insideapps/ddd-iacontext

🛠️ Development Environment Installation

composer require --dev insideapps/ddd-iacontext

When installed as a dev dependency, the package will still set up all necessary files and directories, but won't be included in your production environment when using --no-dev flag during deployment.

🚀 Quick Start

🤖 Using with AI Assistants

IMPORTANT FIRST STEP: To initialize insideapps in any AI assistant, type:

read insideapps.md and load context

This command will load the entire DDD architectural context and display a welcome message.

⚙️ Automatic Setup Process

The following happens automatically during installation:

📄 An insideapps.md file is created in your project root
📚 Documentation files are copied to .insideapps/docs/ for AI accessibility
📋 A business-context directory is created for your specific business rules
💾 Memory and protocol files are created in the var/ directory

🔄 Alternative: Via Direct Command

insideapps:start

I'm working with a project that uses the insideapps/ddd-iacontext package. Before proceeding:

1. Check if the vendor/insideapps/ddd-iacontext package exists in my project
2. If it exists, first read .insideapps/docs/AI_QUICKSTART.md for a quick overview
3. Then explore these key files to understand our architecture:
   - .insideapps/docs/AI_CONTEXT.md
   - .insideapps/docs/engineering/general-context.md
   - .insideapps/docs/engineering/entity-creation-rules.md
   - .insideapps/docs/engineering/application-context.md
   - .insideapps/docs/engineering/infrastructure-context.md
   - .insideapps/docs/engineering/module-creation-rules.md
4. Also read the business rules in the business-context/ directory
5. For any code you generate, strictly follow the architectural patterns and business rules
6. Remember this context for our entire conversation

My current task is: [DESCRIBE YOUR TASK HERE]

🧠 The AI Self-Evaluation Protocol: A Revolutionary Approach

🤔 What is the AI Self-Evaluation Protocol?

A groundbreaking framework that transforms how AI assistants interact with your codebase, ensuring architectural consistency and code quality.

🌟 Why is it Important?

As AI code generation becomes increasingly prevalent in development workflows, ensuring architectural consistency becomes a critical challenge. The AI Self-Evaluation Protocol addresses this by:

🏗️ Enforcing Architectural Integrity: Ensures all AI-generated code follows your established patterns
🛡️ Preventing Common Errors: Catches violations of architectural rules before code is generated
👁️ Creating Transparency: Makes the AI's decision-making process visible and understandable
⏱️ Reducing Review Burden: Minimizes the need for extensive human review of AI-generated code
🔄 Ensuring Consistency: Guarantees uniform application of architectural patterns across your codebase
🚀 Accelerating Development: Allows developers to confidently delegate code generation tasks to AI

✨ Key Features

Key Components of Our Protocol:

🔍 Structured Evaluation: Step-by-step process for evaluating planned actions
📋 Command Checklists: Specific checklists for each command type
📊 Compliance Scoring: Quantitative scoring for rule adherence
🔄 Self-Correction: Identifies and fixes rule violations
👁️ Transparency: Results displayed after command execution
✅ Auto-Verification: Runs tests after executing commands

🔄 How it Works

Pre-Execution Evaluation: Before executing any command, the AI evaluates its planned actions against established rules
Compliance Scoring: The AI assigns scores to different aspects of its plan based on rule adherence
Self-Correction: If compliance scores fall below thresholds, the AI adjusts its plan
Execution: Only after verifying compliance does the AI execute the command
Post-Execution Verification: After execution, the AI runs verification tests to confirm success
Results Display: The evaluation results are automatically displayed to the developer

💾 Memory System

This framework includes a comprehensive memory system that allows AI assistants to track changes and maintain context between sessions:

📁 Memory Files

Located in the var/memory/ directory:

📝 General Memory (var/memory/general_memory.md)
- Contains the project's purpose, structure, and important context
- Read at the beginning of each session
📅 Date-Stamped Memory Logs (var/memory/memory_YYYY-MM-DD.md)
- Track changes made on specific dates
- New file created for each day when changes are made

📋 Protocol Files

Located in the var/protocols/ directory:

🧪 Self-Evaluation Protocol (var/protocols/self_evaluation_protocol.md)
- Defines the evaluation process for verifying compliance with architectural rules
🔄 AI Workflow Protocol (var/protocols/ai_workflow.md)
- Documents the complete workflow for AI assistants
✅ Testing Protocol (var/protocols/testing_protocol.md)
- Outlines approaches for testing the framework

🌟 Benefits of the Memory System

🔄 Continuity: Maintains context between different sessions
📝 Documentation: Automatically documents all changes to the codebase
👁️ Transparency: Provides clear visibility into the development history
👥 Collaboration: Facilitates collaboration between different developers and AI assistants

🔍 AI Accessibility Solution

This package solves the common issue of AI assistants being unable to access files in the vendor/ directory due to gitignore restrictions:

When installed, it automatically copies documentation files to a .insideapps/docs/ directory in your project root
All references in the insideapps.md file point to these accessible copies
AI assistants can now read the architectural context without permission errors

🛠️ Using the AI Self-Evaluation Protocol

👨‍💻 For Developers

If you're a developer working with this package, here's how to use the AI Self-Evaluation Protocol in your workflow:

Issue Commands: Use standard commands like insideapps create new module Customer
Request Evaluation: Add Before you proceed, can you show me your self-evaluation process for this command? to see the AI's thought process
Review & Proceed: Review the evaluation and tell the AI to proceed with execution
Verify Results: After execution, the AI will automatically run verification tests and show the results

For a comprehensive developer guide, see src/engineering/ai-testing/integration-guide.md.

🧪 Testing AI Adherence

To test if an AI assistant is correctly following the rules:

Issue a command that should trigger self-evaluation
Ask the AI to show its self-evaluation process
Verify that the evaluation follows the protocol
Check that the final execution adheres to all rules

For detailed information, see the documentation in src/engineering/ai-testing/.

⚠️ Important Rules for AI Assistants

When working with this package, AI assistants MUST follow these critical rules:

🚫 NEVER Create Domain Files Without Explicit Request: AI assistants must NEVER create entities, value objects, or any domain files unless explicitly requested to do so.
📚 ALWAYS Load Business Rules: AI assistants must ALWAYS load and apply business-specific rules from the business-context directory when working on any task.
👉 ONLY Follow Explicit Commands: When a preset prompt is called, AI assistants MUST ONLY perform the specific actions described in that prompt.
📏 Strict Command Adherence: AI assistants must strictly adhere to the command syntax and not attempt to extend functionality beyond what is specified.
🔄 Single Operation Principle: When creating module structures, create the ENTIRE structure in a SINGLE operation without prompting for each folder.

📋 Business Context Directory

The package creates a business-context/ directory in your project root for defining specific business rules:

Purpose: Store domain-specific business logic in markdown files
Usage: Create one file per domain concept (e.g., customer-rules.md, order-process.md)
Benefits: AI assistants will combine these business rules with the architectural patterns

Example structure:

business-context/
├── README.md                 # Overview of the business domain
├── customer-rules.md         # Rules for customer management
├── order-process.md          # Order processing workflow
└── product-catalog.md        # Product catalog rules

🛠️ Command Reference

Here are the main commands available for working with this package:

1. Initialize Context

insideapps:init

This command initializes the AI context, loading all architectural patterns and business rules.

2. Create New Module

insideapps create new module <ModuleName>

Creates a new module with the complete hexagonal architecture structure.

3. Create Business Context

insideapps create business context <ContextName>

Creates a new business context file and generates all required entities.

4. Generate Model from Description

insideapps generate model from description

Generates a complete domain model from a natural language description.

5. Generate Use Case

insideapps generate use case <UseCaseName>

Generates a complete use case implementation including command, handler, and tests.

6. Create New Entity

insideapps create new entity <EntityName>

Creates a new entity with all required supporting files.

📚 Documentation

For comprehensive documentation, please refer to:

📊 Self-Evaluation Results Example

╔═══════════════════════════════════════════════════════════════════════════
║ AI SELF-EVALUATION PROTOCOL: MODULE CREATION COMPLIANCE CHECK
╠═══════════════════════════════════════════════════════════════════════════
║ Module Name: Sales
║ Command: insideapps create new module Sales
║ Evaluation Date: 2025-05-23
╠═══════════════════════════════════════════════════════════════════════════
║ DIRECTORY STRUCTURE COMPLIANCE:
║ ✓ Created app/Sales/Domain directory
║ ✓ Created app/Sales/Application directory
║ ✓ Created app/Sales/Infrastructure directory
║ ✓ Created all required subdirectories in a single operation
╠═══════════════════════════════════════════════════════════════════════════
║ OVERALL COMPLIANCE SCORE: 100/100
║ 
║ RESULT: ✅ PASS
╚═══════════════════════════════════════════════════════════════════════════

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

InsideApps • Documentation • GitHub

insideapps / ddd-iacontext

Maintainers

Details