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

The AI Self-Evaluation Protocol is a groundbreaking framework that enables AI assistants to evaluate their own planned actions against established rules before executing commands. This ensures consistent adherence to architectural patterns without requiring external code execution or human oversight.

🤔 What is the AI Self-Evaluation Protocol?

🌟 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