Custom AI Skills
Relevant source files
The following files were used as context for generating this wiki page:
Custom AI Skills in this project represent a set of specialized instructions and automation scripts designed to assist AI agents (such as Claude Code) in managing the complex Domain-Driven Design (DDD) and Event-Driven Architecture environment. These skills facilitate automated environment setup, Docker orchestration management, and multi-tenant developer isolation through "Worktree Slots."
Sources: claude.md:1-10, claude.md:180-190
Worktree Slot Management
The Worktree Slot system is a core "skill" that allows multiple developers or AI sub-agents to work in isolated environments simultaneously without port or database collisions. It supports up to five concurrent slots, where Slot 1 is the main checkout and Slots 2-5 are for parallel worktrees.
Slot Resolution Logic
The system resolves the active slot using a specific hierarchy:
- An environment variable named
worktree-slot. - A
.worktree-slotfile located in theAspire.AppHostdirectory. - Defaulting to Slot 1 if neither is present.
The diagram above illustrates the resolution priority for determining which isolated environment slot to use.
Sources: Aspire.AppHost/WorktreeSlot.cs:33-56, scripts/worktree-init.ps1:1-15
Automated Initialization
The worktree-init.ps1 script automates the claiming of slots. It uses a lockfile (worktree-slot.lock) in the git common directory to ensure atomic slot assignment, preventing two concurrent processes from claiming the same ports.
Sources: scripts/worktree-init.ps1:70-90
Infrastructure Orchestration Skills
The project utilizes .NET Aspire to orchestrate microservices and infrastructure components like RabbitMQ. This orchestration is "slot-aware," dynamically adjusting configuration based on the assigned Custom AI Skill context.
Dynamic Port Offsetting
To prevent collisions, ports are calculated using the formula: Base Port + 100 * (Slot - 1).
| Service | Base Port (Slot 1) | Slot 2 Port | Slot 5 Port |
|---|---|---|---|
| Identity WebApi | 7010 | 7110 | 7410 |
| Scheduling WebApi | 7001 | 7101 | 7401 |
| Billing WebApi | 7002 | 7102 | 7402 |
| Angular SPA | 7003 | 7103 | 7403 |
Sources: Aspire.AppHost/WorktreeSlot.cs:11-15, WebApplications/Identity.WebApi.Tests/IdentityServerConfigTests.cs:12-100
Database Isolation
The orchestration skill automatically rewrites connection strings to point to slot-specific databases. For example, a base database DDD becomes DDD_S2 for Slot 2. This is implemented via the WithSlotDatabase helper which modifies the Initial Catalog token.
Sources: Aspire.AppHost/WorktreeSlot.cs:64-78, Aspire.AppHost/AppHost.cs:176-193
Docker Management and Reliability
A critical component of the AI-assisted developer experience is the Docker autostart and health check system. This prevents build hangs and ensures the messaging infrastructure (RabbitMQ) is available before the services attempt to start.
Health Check and Fail-Fast Logic
The ensure-docker.ps1 script provides non-interactive Docker verification, which is essential for CI/CD and AI agent execution.
This sequence ensures that the build process fails gracefully and informatively if the required container environment cannot be established.
Sources: scripts/DOCKER_AUTOSTART_FIX.md:10-50, scripts/DOCKER_AUTOSTART_FIX.md:144-155
Authentication Configuration
The Custom AI Skills extend to the security layer by dynamically configuring OpenID Connect (OIDC) and cookie settings per slot. This allows parallel login sessions in different browser tabs for different worktree slots.
- Cookie Isolation: Cookies are named dynamically (e.g.,
DDD.Auth.S2) to prevent session bleeding between slots. - Authority Overrides: The OIDC
AuthorityandValidAudiencesare updated to match the shifted ports of the Identity provider. - CORS Policies: Allowed origins are dynamically updated to include the slot-specific SPA URLs.
Sources: BuildingBlocks/BuildingBlocks.Infrastructure.Auth/AuthExtensions.cs:34-45, Aspire.AppHost/AppHost.cs:148-166
Conclusion
Custom AI Skills in this project provide a robust framework for automated development and testing. By integrating Worktree Slots, dynamic port mapping, and reliable Docker orchestration directly into the build and hosting pipeline, the system enables AI agents and developers to work in highly isolated, collision-free environments. This architecture is fundamental to maintaining the project's complex Event-Driven and DDD structure during rapid, parallel iteration.