Symfony DDD AI Skeleton
Reusable Symfony 8 / PHP 8.4 skeleton for fast project starts with
modular DDD/CQRS, multi-application structure and AI-friendly workflow.

Starting a new Symfony project with DDD and CQRS typically means hours of boilerplate: kernel configuration, module system, bus wiring, test setup, coding standard, CI pipeline and documentation conventions.

This skeleton provides all of that out of the box so you can focus on domain logic from day one.

Key features:

• Multi-application kernel — run Web, Console (and more) apps from a single repository, each with its own config, bundles and modules.
• Modular DDD/CQRS — every module follows Domain → Application → Infrastructure → Integration / Presentation layers with strict dependency direction enforced by Deptrac.
• Module system — register modules via simple config files; service auto-wiring, compiler passes and route loading are handled automatically.
• AI-ready workflow — AGENTS.md conventions, agent role system (docs/agents/), task tracking via todo-md and structured conventions give AI coding agents everything they need to work autonomously.
• Quality gate — make check runs syntax lint, codestyle, architecture analysis, doc validation, role validation and the full test suite.
• Battle-tested conventions — docs/conventions/ covers layers, patterns, modules, testing and operations in detail.

• PHP ≥ 8.4
• Composer
• php-sqlite3 (for tests)

git clone https://github.com/prikotov/symfony-ddd-ai-skeleton.git my-project
cd my-project
make setup

make setup runs composer install followed by init scripts that populate docs/conventions/, docs/git-workflow/, docs/todo-md/ and todo/AGENTS.md from vendor packages.

make check

This runs: composer validate → lint → codestyle → doc validation → todo validation → role validation → deptrac → unit tests → integration tests.

APP_ENV=test APP_DEBUG=1 APP_SECRET=test \
APP_CACHE_DIR=/tmp/skeleton-console-cache \
APP_LOG_DIR=/tmp/skeleton-console-log \
DATABASE_URL='sqlite:///:memory:' \
php bin/console app:diagnostics:runtime --id=console --no-interaction

APP_ENV=test APP_DEBUG=1 APP_SECRET=test \
APP_CACHE_DIR=/tmp/skeleton-web-cache \
APP_LOG_DIR=/tmp/skeleton-web-log \
DATABASE_URL='sqlite:///:memory:' \
php -r '
  require "vendor/autoload.php";
  $k = new Skeleton\Common\Kernel("test", true, "web");
  $r = Symfony\Component\HttpFoundation\Request::create("/health", "GET");
  $resp = $k->handle($r);
  $k->terminate($r, $resp);
  $k->shutdown();
  echo $resp->getContent().PHP_EOL;
'

bin/bootstrap "MyVendor\\MyProject" my-vendor/my-project

This replaces the Skeleton namespace, package name and description across all PHP, config and documentation files.

├── src/                          # Common shared code
│   ├── Application/              #   CommandInterface, QueryInterface, DTO
│   ├── Component/                #   Module system, Event bus
│   ├── Exception/                #   Typed exception hierarchy
│   ├── Infrastructure/           #   CommandBus, QueryBus, EventBus implementations
│   ├── Module/                   #   Shared modules (Diagnostics, …)
│   └── Kernel.php                #   Multi-app kernel
│
├── apps/web/                     # Web application
│   ├── config/                   #   bundles, modules, packages, routes, services
│   ├── src/                      #   Controllers, Components, Web-specific modules
│   └── templates/                #   Twig templates
│
├── apps/console/                 # Console application
│   ├── config/
│   └── src/                      #   Console commands, Console-specific modules
│
├── config/                       # Common Symfony config
├── docs/                         # Conventions, agent roles, git workflow
├── tests/                        # Common Unit / Integration tests
├── migrations/                   # Doctrine migrations
└── todo/                         # Task tracking (todo-md)

Controller / Console Command
  → CommandBusComponentInterface / QueryBusComponentInterface
    → Command Handler / Query Handler
      → Domain services, Repositories
        → Infrastructure implementations

The bundled Diagnostics module documents the minimal read-only Query example: docs/diagnostics-query-flow.md.

Modules are the primary building blocks. Each module:

• Lives under src/Module/{Name} (shared) or apps/{app}/src/Module/{Name} (app-specific).
• Implements ModuleInterface.
• Has Resource/config/services.yaml for service registration.
• Is registered in config/modules.php (shared) or apps/{app}/config/modules.php.

See the bundled Diagnostics module as a working example.

Run everything at once:

make check

This skeleton is built on the principles described in AI-Assisted Development Playbook — a public methodology for organizing AI-driven development with task-driven workflow, structured roles, conventions and quality gates.

Core components:

• AGENTS.md — rules, architecture summary, code style and safety constraints for AI agents.
• docs/agents/roles/team/ — structured role definitions (team lead, architects, developers, devops, analysts, writers) that guide AI agents through specialized responsibilities.
• docs/conventions/ — detailed conventions for every layer, pattern and operation so agents produce consistent code.
• todo/ — todo-md task tracking with structured statuses, priorities and types.

When using AI coding agents (Claude, GPT, etc.), point them to AGENTS.md as the entry point — it references everything else.

This skeleton depends on several purpose-built open-source packages:

• Architecture & conventions — docs/conventions/
• Module scaffold guide — docs/module-scaffold-guide.md
• Agent roles — docs/agents/roles/team/
• Git workflow — docs/git-workflow/
• UI components — docs/ui/
• Task tracking — docs/todo-md/

See CONTRIBUTING.md.

This project is licensed under the MIT License.