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, use one of these commands:

insideapps:start

Or the new enhanced context loading command:

insideapps load context

These commands 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 .insideapps/memory/ 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/engineering/general-context.md
   - .insideapps/docs/engineering/entity-creation-rules.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]

Command Reference

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

1. Initialize Context

insideapps:start

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

2. Load Full Context

insideapps load context

This enhanced command loads the complete engineering and business context from both the .insideapps and business-context directories, ensuring AI assistants have access to all architectural patterns and business rules.

3. General InsideApps Commands

Any command starting with insideapps will trigger the context loading system, ensuring that AI assistants apply the correct architectural and business contexts to their responses.

4. Create New Module

insideapps create new module <ModuleName>

Creates a new module with the complete hexagonal architecture structure.

5. Create Entity

insideapps create entity <EntityName>

Creates a new entity with all required supporting files.

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 .insideapps/memory/ directory:

General Memory (.insideapps/memory/general.md)
- Contains the project's purpose, structure, and important context
- Read at the beginning of each session
Date-Stamped Memory Logs (.insideapps/memory/logs/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 .insideapps/protocols/ directory:

Self-Evaluation Protocol (.insideapps/protocols/self_evaluation_protocol.md)
- Defines the evaluation process for verifying compliance with architectural rules
AI Workflow Protocol (.insideapps/protocols/ai_workflow.md)
- Documents the complete workflow for AI assistants
Testing Protocol (.insideapps/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 <ModuleName>
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 .insideapps/docs/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 .insideapps/docs/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.
NO COMMENTS: AI assistants must NEVER generate code with comments, as this violates the architectural rules.

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

Getting Started with the Framework

Step 1: Install the Package

composer require insideapps/ddd-iacontext

Step 2: Verify Installation

Check that the following files and directories have been created:

insideapps.md in your project root
.insideapps/ directory with documentation and memory files
business-context/ directory for your business rules

Step 3: Add Your Business Rules

Create markdown files in the business-context/ directory to define your specific business rules and domain concepts.

Step 4: Start Using with AI Assistants

Begin your conversation with any AI assistant by using one of these commands:

insideapps:start

insideapps load context

Step 5: Use the Command Reference

Refer to the Command Reference section above to see all available commands and how to use them.

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