📘 DSLs in ConnectSoft¶

🧠 What Is a DSL?¶

A Domain-Specific Language (DSL) in ConnectSoft is a structured, declarative YAML or JSON document that defines:

System intent (what to build)
Module structure (how to build it)
Artifact contracts (what it must emit)
Event interfaces (how it integrates)
Execution triggers (when agents should act)

DSLs are the formal interface between vision, architecture, and autonomous generation.

🎯 Why DSLs Matter in an AI Software Factory¶

Traditional Model:¶

Humans write requirements → translate into specs → code
Risk: unstructured input, missed logic, no audit trail

ConnectSoft Model (AI-First):¶

DSLs are machine-readable contracts generated from prompts and blueprints
DSLs drive agents, validate outputs, and orchestrate flows

“DSLs are the control plane of automation — they make agentic execution safe, observable, and predictable.”

🧱 What DSLs Enable¶

Capability	DSL Role
Structure	Define bounded contexts, aggregates, events
Traceability	Carry `traceId`, `dslRef`, `context`, `agentId`
Agent Execution	Trigger skills like `GenerateHandler`, `EmitContract`
Orchestration	Route, validate, and replay DSLs
Observability	Emit logs, spans, and metrics with DSL metadata
Autonomous Generation	Blueprint → DSL → Artifact → PR → Deployment
Audit & Compliance	Versioned DSLs = traceable system blueprint

🔁 DSLs in the ConnectSoft Lifecycle¶

sequenceDiagram
    participant VisionAgent
    participant DSLAgent
    participant Orchestrator
    participant GeneratorAgent

    VisionAgent->>DSLAgent: Generate DSLs (ddd.yaml, event.yaml)
    DSLAgent->>Orchestrator: Emit DslGenerated
    Orchestrator->>GeneratorAgent: Trigger Skill (GenerateHandler)
    GeneratorAgent->>Orchestrator: Emit CodeGenerated

Hold "Alt" / "Option" to enable pan & zoom

📦 DSLs vs Other Platform Assets¶

Asset Type	DSL?	Role
`ddd.yaml`	✅	Describes aggregates, commands, events
`event.yaml`	✅	Defines domain/integration events
`pipeline.yaml`	✅	CI/CD stages and triggers
`MicroserviceTemplate`	❌	Folder + project scaffolding
`ConnectSoft.*.NuGet`	❌	Reusable precompiled code (library)
`SendNotification.cs`	❌	Output artifact generated from DSL

🧠 Without DSLs, You'd Lose:¶

Structure: Agents wouldn’t know what to generate
Safety: No validation between blueprint → code
Autonomy: Orchestration would rely on free-form text
Reuse: No shared contract across services or tenants
Observability: No traceable metadata

✅ Summary¶

DSLs are:

The foundation of traceable software generation
The execution contract between prompts and agents
The schema that defines software logic, structure, and interaction
The fuel that drives autonomous delivery pipelines

Every service, event, adapter, and test in ConnectSoft starts with a DSL — not code.

⚖️ DSLs vs Skills vs Prompts in ConnectSoft¶

In the ConnectSoft AI Software Factory, three core building blocks drive intelligent software generation:

Concept	Purpose
DSL	Structured input that defines what to build
Skill	Executable capability that knows how to build
Prompt	Instructional or contextual input that tells when/why to build

Each plays a distinct role in the agentic execution lifecycle.

🧱 Conceptual Comparison Table¶

Aspect	DSL	Skill	Prompt
What it is	Declarative specification (YAML/JSON)	Named agent capability	Instructional or contextual message
Produced by	Blueprint or DSL Generator Agent	Engineering agent registry	Prompt Engine, Orchestrator
Consumed by	Agents + Orchestrators	Internally by agents	Agents and skill execution layers
Used for	Defining structure, triggers, events	Executing transformation/generation	Driving execution or enriching skill
Example	`ddd.yaml`, `event.yaml`	`GenerateHandler`, `EmitContract`	“Create a handler for BookCommand”
Traceable?	✅ Yes (`dslRef`, `traceId`)	✅ Yes (`skillId`, `agentId`)	✅ Yes (`promptId`, `traceId`)

🧠 How They Work Together¶

Full Lifecycle Example¶

Goal: Generate a handler for BookAppointment command.

DSL (ddd.yaml):

command:
  name: BookAppointment
  fields:
    - patientId: Guid
    - timeSlot: DateTime

Prompt:

"Generate a handler for the BookAppointment command using Clean Architecture."

Skill: GenerateHandler skill is invoked by the Backend Developer Agent.
Output: File: BookAppointmentHandler.cs Metadata: skillId=GenerateHandler, dslRef=ddd.yaml, traceId=...

🔁 Execution Flow Relationship¶

flowchart TD
    Vision --> DSL
    DSL -->|Provides structure| Prompt
    Prompt -->|Activates| Skill
    Skill -->|Produces| Artifact

Hold "Alt" / "Option" to enable pan & zoom

🧬 Metadata Anchors¶

Identifier	Origin	Description
`dslRef`	DSL	Unique path/id for DSL document
`skillId`	Skill	Registered name of agent capability
`promptId`	Prompt	Optional hash of structured input
`traceId`	All	Shared execution context across system

✅ Summary¶

DSL	Skills	Prompts
Define the structure	Perform the action	Trigger or refine the action
Declarative and reusable	Executable and composable	Contextual and conversational
Drive agent orchestration	Power agent internals	Inject natural language into flow

DSLs are the contracts, skills are the tools, and prompts are the instructions.

🔄 DSL Lifecycle in the ConnectSoft AI Software Factory¶

The DSL Lifecycle defines how DSLs flow through the ConnectSoft platform — from their creation to validation, consumption, and traceable execution across agents, pipelines, and orchestrators.

🧭 Phases of the DSL Lifecycle¶

flowchart TD
    A[🔁 Triggered by Prompt/Blueprint] --> B[📝 DSL Generated]
    B --> C[✅ DSL Validated]
    C --> D[📦 DSL Stored & Versioned]
    D --> E[⚙️ DSL Consumed by Agents]
    E --> F[🧪 Artifact Emitted - Code/Test]
    F --> G[📊 DSL Traced in Observability]

Hold "Alt" / "Option" to enable pan & zoom

1️⃣ Trigger (Prompt or Blueprint)¶

Triggered by:
- Vision Agent (from initial problem statement)
- Solution Architect Agent (from blueprint)
- User prompt (e.g., “create a booking domain”)
Event: DslGenerationRequested

2️⃣ Generation¶

Agent: DSL Generator Agent, Domain Modeler Agent
DSL file emitted:
- Format: YAML or JSON
- Stored in: /dsl/{context}/{dslType}.yaml
Event: DslGenerated

3️⃣ Validation¶

Agent: DslValidatorAgent or validation service
Schema checked:
- Against internal DSL schemas (e.g., ddd.schema.json)
- Linted for AI correctness, naming, duplication
If valid:
- Event: DslValidated
If invalid:
- Event: DslValidationFailed
- Error stored in execution-metadata.json

4️⃣ Storage & Registry¶

DSL is stored with:
- traceId, dslRef, version, context, dslType
- DSL folder: dsl/Booking/ddd.yaml
Versioned and immutable
Linked to blueprint and orchestrator session

5️⃣ Agent Consumption¶

Trigger: DslReady, DslValidated, or BlueprintReady
Consumed by:
- Backend Developer Agent
- Event Architect Agent
- Adapter Generator Agent
- Test Generator Agent
Agent looks up:
- dslRef, context, commandName or eventName
Skill executed: GenerateHandler, EmitContract, etc.

6️⃣ Artifact Emission¶

Result: .cs, .feature, .yaml, .md
Metadata:
- dslRef, agentId, skillId, traceId, status
Event: CodeGenerated, TestCaseCreated, ArtifactReady

7️⃣ Observability & Tracing¶

DSL lifecycle is fully visible in:
- Studio (Trace Explorer → DSL View)
- Logs (dslType, dslRef, context, agentId)
- Metrics (e.g., dsl_validation_success_rate, dsl_artifact_latency)
- Events (e.g., DslGenerated, CodeGenerated with dslRef)

📘 Sample Lifecycle Log (Structured)¶

{
  "traceId": "trace-a1b2c3",
  "dslRef": "dsl/Booking/ddd.yaml",
  "dslType": "DDD",
  "agentId": "backend-developer",
  "skillId": "GenerateHandler",
  "status": "Success",
  "artifact": "BookAppointmentHandler.cs"
}

✅ Summary¶

The DSL lifecycle ensures:

Predictable, auditable generation of artifacts
Safe, schema-validated automation
Full traceability from DSL → code → deployment
Reusability and version control of software knowledge

🏷️ DSL Metadata & Traceability in ConnectSoft¶

Every DSL in the ConnectSoft AI Software Factory is treated as a traceable, first-class artifact. This ensures that:

Agents can identify where a DSL came from
Orchestrators know how it should be routed
Observability pipelines can trace what it affected

“If you can’t trace a DSL, it doesn’t belong in the factory.”

📦 Metadata Structure for All DSLs¶

All DSLs carry a standardized metadata header — either embedded or stored in a linked .metadata.json file.

Example: Embedded Metadata in `ddd.yaml`¶

$meta:
  dslType: DDD
  dslRef: dsl/Booking/ddd.yaml
  context: Booking
  moduleId: BookingService
  version: 1.0.0
  traceId: trace-a1b2c3
  agentId: domain-modeler
  generatedAt: 2025-05-17T13:00:00Z
  source: VisionAgent
  status: Validated

🧱 Metadata Field Reference¶

Field	Description
`dslType`	The type of DSL (`DDD`, `Event`, `Pipeline`, etc.)
`dslRef`	Canonical path or unique ID of the DSL
`context`	Bounded context or domain (e.g., `Booking`, `Billing`)
`moduleId`	Module associated with the DSL
`version`	DSL version (e.g., `1.0.0`)
`traceId`	Trace for execution flow (shared across all related artifacts/events)
`agentId`	Agent that generated or processed the DSL
`generatedAt`	UTC timestamp of when DSL was emitted
`source`	Upstream source agent or user (e.g., `VisionAgent`, `BlueprintTool`)
`status`	Current DSL status (`Generated`, `Validated`, `Consumed`, `Failed`)

🔎 How Metadata Supports Platform Flows¶

1. Agent Routing¶

Orchestrators use dslType, context, and traceId to decide which agents to activate.
Example: if dslType == DDD → route to Backend Developer Agent and Event Architect Agent.

Users can search or trace:
- "Show me all DSLs generated by VisionAgent in trace XYZ"
- "Open dslRef for BookingService version 1.0.0"

3. Observability & Audit Logs¶

Metrics emitted:
- dsl_validation_success_total{dslType="DDD", context="Booking"}
- dsl_generation_latency_seconds{agentId="domain-modeler"}
Events include:
- DslGenerated, DslValidated, DslSegmentConsumed, DslConsumedByAgent

🧠 Linked Execution Metadata Example¶

{
  "traceId": "trace-a1b2c3",
  "dslRef": "dsl/Booking/ddd.yaml",
  "agentId": "backend-developer",
  "skillId": "GenerateHandler",
  "artifact": "BookAppointmentHandler.cs",
  "status": "Success"
}

→ Linked to logs, metrics, test results, PRs, and commits.

✅ Summary¶

DSL metadata provides routing, traceability, and observability across the entire platform.
Every DSL is self-identifying and context-aware.
DSLs without metadata are invalid in ConnectSoft — no trace = no execution.

🧬 Anatomy of a DSL Document in ConnectSoft¶

Every DSL in the ConnectSoft platform follows a standardized structure to ensure:

It is understandable by agents
It can be validated automatically
It supports traceability and modular reuse

“A DSL is not just a YAML file — it is a typed, self-aware, composable source of system truth.”

🧱 Standard DSL Document Structure¶

$meta:
  dslType: DDD
  dslRef: dsl/Booking/ddd.yaml
  context: Booking
  moduleId: BookingService
  version: 1.0.0
  traceId: trace-a1b2c3
  agentId: domain-modeler
  status: Validated

aggregate:
  name: Appointment
  id: AppointmentId
  description: A veterinary appointment to be booked by pet owners.

commands:
  - name: BookAppointment
    fields:
      - name: patientId
        type: Guid
        required: true
      - name: slot
        type: DateTime
    emits: AppointmentBooked

events:
  - name: AppointmentBooked
    fields:
      - name: appointmentId
        type: AppointmentId
      - name: slot
        type: DateTime
      - name: patientId
        type: Guid

🧩 Core Sections of a DSL¶

Section	Purpose
`$meta`	Metadata block for orchestration, traceability, validation
`aggregate` / `event` / `pipeline`	Core object the DSL defines (depends on `dslType`)
`commands`, `fields`, `steps`	Detailed declarations per DSL type
`dependencies` (optional)	References to other DSLs or artifacts
`settings` (optional)	Generation flags, feature toggles

🧠 DSL Meta Section¶

Field	Purpose
`dslType`	Type of DSL (`DDD`, `Event`, `Pipeline`, etc.)
`dslRef`	Path or ID used by orchestrators and Studio
`context`	Bounded context (e.g., `Booking`, `Billing`)
`traceId`	Lifecycle trace key for linking to generation flow
`status`	Validation status (`Validated`, `Invalid`, etc.)

✅ This section is required for the DSL to be routable and observable.

🛠️ Optional Sections by DSL Type¶

DSL Type	Optional Sections
`DDD`	`valueObjects`, `services`
`Event`	`version`, `source`, `topic`
`Pipeline`	`matrix`, `env`, `outputs`
`Adapter`	`protocol`, `bindings`, `mode`
`Test`	`scenarios`, `steps`, `tags`
`Execution`	`skills`, `chain`, `memory`

📚 Validation Rules¶

Every DSL type has an associated schema:

DSL Type	Schema Location
`DDD`	`schemas/ddd.schema.json`
`Event`	`schemas/event.schema.json`
`Test`	`schemas/test.schema.json`
`Adapter`	`schemas/adapter.schema.json`
`Pipeline`	`schemas/pipeline.schema.json`

Validation ensures:

Correct field structure
Required elements present
Valid types and enums

✅ Summary¶

DSLs are structured into metadata + body
The $meta block is mandatory for orchestration and traceability
Body schema varies by dslType and supports validation + downstream execution
Agents and Studio use this structure to route, display, and generate artifacts

🤖 Agent Interaction with DSLs in ConnectSoft¶

In the ConnectSoft AI Software Factory, DSLs are the primary interface between architectural intent and agent execution. Agents use DSLs to:

Understand what to generate
Decide how to execute their skills
Report where output came from
Emit traceable, testable artifacts

🧠 Types of Agent Interactions with DSLs¶

Action	Agent Behavior
Consume DSL	Agent reads DSL file to determine what code/test/infrastructure to emit
Emit Artifact	Agent produces `.cs`, `.feature`, `.yaml`, `.md` etc. with DSL references
Tag Output	All generated outputs include `dslRef`, `traceId`, `context`, `agentId`
React to Event	Agent subscribes to DSL-based events (`DslValidated`, `DslSegmentReady`)
Use in Prompt	DSL is injected into the prompt context to make agent output precise

⚙️ Execution Flow Example¶

sequenceDiagram
    participant Orchestrator
    participant DSLAgent
    participant BackendAgent
    participant CommitAgent

    Orchestrator->>DSLAgent: Generate ddd.yaml
    DSLAgent->>Orchestrator: Emit DslValidated
    Orchestrator->>BackendAgent: Process dslRef: dsl/Booking/ddd.yaml
    BackendAgent->>CommitAgent: Emit BookAppointmentHandler.cs (with metadata)

Hold "Alt" / "Option" to enable pan & zoom

🧱 Agent Skill Decision from DSL¶

Agents map DSL segments to skills like:

DSL Element	Skill Triggered
`commands[]` in DDD	`GenerateHandler`
`events[]` in DDD	`EmitEventContract`
`valueObjects[]`	`GenerateValueObjectClass`
`aggregate.name`	`GenerateAggregateClass`
`scenarios[]` in Test	`GenerateSpecFlowTest`
`jobs[]` in Pipeline	`EmitPipelineYaml`

→ These skills are explicitly mapped to DSL paths, allowing deterministic behavior.

🧩 Agent Runtime Context Injection¶

When an agent is activated by a DSL, its prompt context includes:

{
  "dslRef": "dsl/Booking/ddd.yaml",
  "traceId": "trace-a1b2c3",
  "dslType": "DDD",
  "command": "BookAppointment",
  "context": "Booking",
  "agentId": "backend-developer",
  "skillId": "GenerateHandler"
}

✅ Ensures observability and reproducibility.

📄 Example: Agent-Generated Output with DSL Link¶

File: BookAppointmentHandler.cs

// Generated by Backend Developer Agent
// Based on DSL: dsl/Booking/ddd.yaml
// traceId: trace-a1b2c3
// skill: GenerateHandler

📊 Studio View of Agent+DSL Execution¶

Trace Timeline: DSL → Agent → Skill → Output
Explorer Drilldown:
- Select DSL → see related artifacts and PR
- Select Agent → see all DSLs consumed
Audit Logs:
- “dslRef dsl/Booking/ddd.yaml was used by backend-developer to emit handler file”

✅ Summary¶

DSLs are the primary input contracts for most agent executions
Agents use DSLs to determine what to generate, how to trace it, and where it belongs
All outputs are tagged with dslRef, enabling observability, reproducibility, and auditability

🧭 Orchestration Layer Integration with DSLs¶

In ConnectSoft, the orchestration layer acts as the central dispatcher and controller of all autonomous flows. It relies on DSLs as the source of truth for:

Determining which agents to activate
Routing execution plans
Enforcing validation
Connecting lifecycle events from blueprint to release

“DSLs are the connective tissue between agent decisions, orchestration logic, and blueprint alignment.”

⚙️ Orchestration Lifecycle Flow (With DSLs)¶

flowchart TD
    Vision[Vision Document Created] --> DslGen[Generate DSLs]
    DslGen --> DslValidated
    DslValidated --> Orchestrator[Orchestrator Routes DSL]
    Orchestrator --> Agent[Agent Executes Skill]
    Agent --> PR[Pull Request Created]

Hold "Alt" / "Option" to enable pan & zoom

🔄 What the Orchestrator Does with DSLs¶

Task	Description
Monitor DSL events	Listens to `DslGenerated`, `DslValidated`, `DslSegmentReady`
Route to agents	Uses `dslType`, `context`, and `traceId` to dispatch correct agent & skill
Validate schemas	Uses JSON schema validation for structural correctness
Apply gating logic	Blocks downstream execution until DSL passes validation
Attach trace metadata	Links every DSL to traceId and execution lifecycle
Emit progress events	Sends `DslSegmentConsumed`, `ArtifactGenerated`, `TraceAdvanced`

🧩 How DSLs Are Matched to Agent Flows¶

DSL Type	Target Agent(s)	Skills Mapped
`DDD`	Backend Developer, Domain Modeler	`GenerateHandler`, `EmitEvent`, `GenerateAggregate`
`Event`	Event Architect, Messaging Configurator	`EmitContract`, `ConfigurePublisher`
`Adapter`	Infrastructure Engineer	`GeneratePortAdapter`, `EmitBindings`
`Test`	Test Generator Agent	`GenerateSpecFlow`, `EmitTestCode`
`Pipeline`	DevOps Agent	`EmitYamlPipeline`, `AttachStagePolicy`

✅ This mapping is defined in the execution FSM and agent registry.

🧠 Triggering Strategy (Example)¶

trigger:
  when: DslValidated
  dslType: DDD
  context: Booking
  skill: GenerateHandler
  agent: backend-developer

→ Stored in execution-plan.yaml or orchestrator config

📂 DSL Folder Routing Convention¶

dsl/
  Booking/
    ddd.yaml
    event.yaml
  Notifications/
    event.yaml
  Billing/
    pipeline.yaml

The orchestrator detects changes and routes by:

Folder (context)
File (dslType)
Execution metadata (traceId, version, etc.)

📊 DSL in Orchestration Metrics¶

Metric	Meaning
`dsl_routed_total`	Count of DSLs routed to agents
`dsl_validation_failure_total`	Schema or semantic failures
`dsl_execution_latency_seconds`	Time from `DslValidated` to `CodeGenerated`
`dsl_blocked_pending_dependency`	DSLs waiting for other DSLs (e.g., Event needs DDD first)

✅ Summary¶

The orchestration layer treats DSLs as typed inputs to deterministic execution
It uses DSL metadata to route, validate, trigger, and trace flows
DSLs allow orchestration to be event-driven, parallel, and auditable

📡 DSL Observability & Events in ConnectSoft¶

DSLs in ConnectSoft are observable units — not just static files. Every DSL is part of a traceable lifecycle, emitting telemetry and triggering platform events at each phase.

This enables:

Real-time status tracking
Agent trace correlation
Studio diagnostics
Compliance auditing

“If a DSL is used to generate production code, it must be observable from birth to release.”

🧠 DSL Lifecycle Events¶

📍 Key Events Emitted¶

Event Name	Triggered By	Payload Includes
`DslGenerated`	DSL Generator Agent	`dslRef`, `traceId`, `dslType`, `agentId`
`DslValidated`	DSL Validator / Orchestrator	`dslRef`, `context`, `status=success`
`DslValidationFailed`	Orchestrator / Schema Validator	`dslRef`, `errors`, `agentId`, `traceId`
`DslSegmentReady`	Manual segment release	Signifies partial DSL availability
`DslSegmentConsumed`	Agent processing the DSL	`dslRef`, `skillId`, `status`, `artifactRef`
`DslTraceComplete`	Final state in a generation loop	Summary of all DSLs and output statuses

✅ All events are published on the internal event bus with full observability headers.

📊 DSL Metrics¶

Emitted to OpenTelemetry or Prometheus:¶

Metric Name	Tags
`dsl_generated_total`	`dslType`, `agentId`, `context`, `status`
`dsl_validation_latency_seconds`	`dslType`, `context`, `agentId`
`dsl_consumed_total`	`dslRef`, `skillId`, `agentId`
`dsl_errors_total`	`dslType`, `traceId`, `validationError`

Sample Prometheus Metric¶

# HELP dsl_generated_total Total number of DSLs generated
# TYPE dsl_generated_total counter
dsl_generated_total{dslType="DDD", context="Booking", agentId="domain-modeler"} 3

📘 Studio DSL Observability Features¶

Feature	Description
DSL Trace View	Timeline of DSL events in context of a trace
Artifact Explorer	Reverse map from `.cs` → `dslRef`
Validation Diagnostics	Shows schema error reasons in-line
Segment Health Status	Shows which DSLs are incomplete, expired, or invalid
Event Viewer Filters	Filter logs/events by `dslType`, `context`, `agentId`

🔐 Audit & Compliance Support¶

DSL observability allows:

✅ DSL → Artifact → Commit → PR → Deployment chain of custody
✅ Identification of invalid generation triggers
✅ Tracking of every DSL used to produce live service code
✅ Automated retention or purging policies by status

✅ Summary¶

Every DSL in ConnectSoft emits structured lifecycle events
These events power observability, replayability, traceability, and auditing
Studio, agents, and orchestrators all subscribe to DSL-related event streams
DSL observability enables full control and validation of AI-driven code production

✅ DSL Validation & Schemas in ConnectSoft¶

Every DSL in ConnectSoft must be validated before it can be processed by agents or orchestrators. Validation ensures that:

The DSL is structurally correct
Required fields and relationships exist
The schema matches the intended dslType
Errors are traceable and recoverable

“Validation is what turns a file into a contract.”

🧠 What Is Validated?¶

✅ Schema Validation¶

Each DSL type (e.g., DDD, Event, Pipeline) is linked to a strict JSON Schema that defines:

Required fields
Allowed values and types
Pattern constraints (e.g., PascalCase, kebab-case)
Embedded or linked definitions (e.g., commands[], events[])

✅ Semantic Validation¶

Goes beyond schema and checks for:

Duplicate identifiers (e.g., two commands with same name)
Conflicting fields across DSLs
Unsupported cross-context references
Context leakage (e.g., Billing DSL referencing Booking aggregate)

📂 DSL Schema File Locations¶

DSL Type	Schema File Location
`DDD`	`schemas/ddd.schema.json`
`Event`	`schemas/event.schema.json`
`Test`	`schemas/test.schema.json`
`Adapter`	`schemas/adapter.schema.json`
`Pipeline`	`schemas/pipeline.schema.json`

All schemas are centrally versioned, OpenAPI-compatible, and referenced by dslType.

🧰 Validation Engine Integration¶

Component	Role
DslValidatorAgent	Validates new DSLs using schema and semantic rules
Orchestrator FSM	Blocks execution if DSL fails validation
Studio	Shows validation errors in UI
CI Gate (optional)	Can run `dsl lint` CLI during commits or PR checks

🔍 Sample Validation Result (Failure)¶

{
  "dslRef": "dsl/Booking/ddd.yaml",
  "dslType": "DDD",
  "context": "Booking",
  "status": "Failed",
  "errors": [
    {
      "field": "commands[0].fields[1].type",
      "message": "Missing required property 'type'"
    },
    {
      "field": "aggregate.name",
      "message": "Must be PascalCase"
    }
  ]
}

🔄 Validation Lifecycle Events¶

Event Name	Triggered By	Description
`DslValidated`	On successful validation	DSL is ready for use
`DslValidationFailed`	On failure	Agent/orchestrator/studio notified
`DslRetryScheduled`	Optional retry if auto-fixable	Triggered by planner or CLI

🛑 What Happens If a DSL Is Invalid?¶

Orchestrator blocks downstream agent execution
Studio shows validation banner on DSL page
Retry path may be proposed by CorrectionAgent
Errors are logged, tagged, and audited

📊 Metrics Emitted¶

Metric	Description
`dsl_validation_success_total`	Count of passed DSLs by type
`dsl_validation_failure_total`	Count of invalid DSLs
`dsl_validation_duration_seconds`	Time to run schema+semantic checks

✅ Summary¶

Every DSL must pass schema + semantic validation
Validation blocks downstream actions, preserving safety and consistency
Failed validations emit structured errors and events
Studio, CI, and agents all rely on consistent schema enforcement

⚡ Event-Driven Activation of DSLs in ConnectSoft¶

In ConnectSoft, DSLs are not manually triggered — they are part of an event-driven execution graph.

This means that every step in the DSL lifecycle — generation, validation, consumption — is initiated by platform events emitted by agents, orchestrators, or system triggers.

“If something important happens in the factory, it emits an event — and DSLs are no exception.”

🔁 End-to-End Event Flow (Example)¶

sequenceDiagram
    participant User
    participant VisionAgent
    participant DSLAgent
    participant Orchestrator
    participant BackendAgent

    User->>VisionAgent: Submit Vision Prompt
    VisionAgent->>DSLAgent: Generate ddd.yaml
    DSLAgent->>Orchestrator: Emit DslGenerated
    Orchestrator->>DSLAgent: Validate DSL
    DSLAgent->>Orchestrator: Emit DslValidated
    Orchestrator->>BackendAgent: Trigger GenerateHandler

Hold "Alt" / "Option" to enable pan & zoom

📡 Key DSL Events & Triggers¶

Event	Description
`VisionDocumentCreated`	Triggers DSL generation from blueprint
`DslGenerated`	DSL created by agent; triggers validation
`DslValidated`	DSL approved; triggers agent execution
`BlueprintReady`	Blueprint contains DSL fragments to extract
`AgentExecutionCompleted`	May emit `DslSegmentReady` for partial DSLs
`DslConsumedByAgent`	Used for tracking + orchestrator progress update

🧠 Why Events Drive DSL Execution¶

Loose coupling: Orchestrators don’t poll — they react to DSL lifecycle changes
Parallelization: DSLs can activate multiple agents simultaneously
Safety: Events ensure that a DSL must be validated before it's consumed
Replayability: DSL flows can be replayed by re-emitting prior events

📦 Examples of Event-Driven DSLs¶

Event Triggered	DSL Activated
`VisionDocumentCreated`	`ddd.yaml`, `event.yaml`
`ProductPlanCreated`	`product-plan.yaml`
`BlueprintReady`	`adapter.yaml`, `test.yaml`
`PipelineRequested`	`pipeline.yaml`
`ReleaseCandidateReady`	`execution-dsl.yaml`

🔄 Flow Control: Orchestrator FSM¶

The orchestrator subscribes to DSL events like:

transitions:
  - on: DslValidated
    if: dslType == "DDD"
    then:
      trigger:
        agent: backend-developer
        skill: GenerateHandler

→ Declarative FSM makes DSLs automatically route themselves based on event flow.

📊 Observability Hooks¶

Tool	Feature
Studio	DSL Event Feed, Trace Timeline, Trigger Map
Metrics	`dsl_activated_total`, `dsl_routing_latency`
Audit Logs	All DSLs include triggering event + origin

🔐 Security Consideration¶

Only events from trusted emitters (e.g., agents, orchestrators) can trigger DSL execution. Untrusted events or malformed DslGenerated are ignored or quarantined.

✅ Summary¶

DSLs are activated by events, not manually invoked
This supports safe, scalable, autonomous execution
Events provide visibility, flexibility, and orchestration continuity
Every DSL participates in a traceable, auditable event graph

🧩 DSL Templates and Inheritance in ConnectSoft¶

In ConnectSoft, DSLs are not one-off documents — they are composable, reusable contracts. The platform supports DSL templates and inheritance structures to enable:

Reuse of shared patterns across modules
Tenant-specific overrides
Multi-edition support
Declarative extensions of architectural blueprints

“A DSL template is a blueprint of a blueprint — a reusable base from which DSLs evolve.”

📦 What Is a DSL Template?¶

A DSL template is a partial or base DSL definition stored in the DSL registry. It contains reusable structure and logic that can be:

Extended
Overridden
Referenced
Composed

DSL templates are typically parameterized or inherited by context-specific DSLs.

🧱 Example: Template + Instance¶

🔹 Base Template — `ddd.template.yaml`¶

$meta:
  dslType: DDD
  context: Shared
  template: true
aggregate:
  name: Appointment
  id: AppointmentId
commands:
  - name: CancelAppointment
    fields:
      - appointmentId: AppointmentId
    emits: AppointmentCancelled

🔸 Inheriting DSL — `Booking/ddd.yaml`¶

$extends: ../../shared/ddd.template.yaml
$meta:
  dslType: DDD
  context: Booking
  traceId: trace-abc123

commands:
  - name: BookAppointment
    fields:
      - patientId: Guid
      - slot: DateTime
    emits: AppointmentBooked

✅ Merges both commands under aggregate: Appointment.

🧠 Inheritance Rules¶

Feature	Behavior
`$extends`	Specifies path to parent/base template
`aggregate`, `commands`, etc.	Merged (child overrides take precedence)
`$meta.template: true`	Marks file as non-executable base
`traceId`, `agentId`	Inherited only if not explicitly overridden
Array merging	Default: append unless `name` matches, then override

🔄 Use Cases¶

Use Case	DSL Strategy
Shared aggregates across domains	DSL template
Multi-tenant feature toggles	Base + edition override
Product tier differentiation	Extend + prune features
Centralized OpenAPI template	Base DSL for APIs + extensions per service

📁 Recommended Structure¶

dsl/
  shared/
    ddd.template.yaml
    event.template.yaml
  Booking/
    ddd.yaml          ← extends shared/ddd.template.yaml
    event.yaml
  Billing/
    ddd.yaml

🔍 Agent Awareness¶

Agents support template inheritance natively. They receive the merged final DSL via orchestration — no need to resolve templates themselves.

→ Keeps agent logic simple and centralized.

📊 Observability & Traceability¶

DslMerged event emitted during inheritance resolution
sourceTemplates[] field in execution metadata
Studio shows base vs. effective structure
Validation runs on the final merged DSL

✅ Summary¶

DSL templates reduce duplication and encode reusable patterns
$extends lets you build specialized DSLs from generalized ones
The orchestration layer resolves inheritance before agent execution
All inheritance is traceable, observable, and version-controlled

🧠 Domain DSL (DDD DSL) — Deep Dive¶

The DDD DSL (Domain-Driven Design DSL) defines the core business structure and behavior of a service using domain-driven principles:

Aggregates
Commands
Events
Value Objects
Handlers (implicit)

This DSL provides the canonical source of truth for the application layer and is consumed by agents to generate:

Domain models
Command handlers
Event contracts
Use case tests

“DDD DSL is where your business rules come to life — in a form that agents can understand, validate, and build from.”

📦 DSL File Location¶

dsl/
  Booking/
    ddd.yaml

📘 Example: `ddd.yaml`¶

$meta:
  dslType: DDD
  context: Booking
  moduleId: BookingService
  traceId: trace-abc123
  version: 1.0.0
  agentId: domain-modeler

aggregate:
  name: Appointment
  id: AppointmentId
  description: Represents a veterinary appointment booked by a pet owner.

valueObjects:
  - name: TimeSlot
    fields:
      - name: start
        type: DateTime
      - name: end
        type: DateTime

commands:
  - name: BookAppointment
    fields:
      - patientId: Guid
      - slot: TimeSlot
    emits: AppointmentBooked

  - name: CancelAppointment
    fields:
      - appointmentId: AppointmentId
    emits: AppointmentCancelled

events:
  - name: AppointmentBooked
    fields:
      - appointmentId: AppointmentId
      - patientId: Guid
      - slot: TimeSlot

  - name: AppointmentCancelled
    fields:
      - appointmentId: AppointmentId

🧩 DSL Fields & Semantics¶

`aggregate`¶

Defines the root entity that encapsulates business behavior.

`commands[]`¶

Declares actions that mutate aggregate state. Mapped to handlers.

`events[]`¶

Defines outcomes triggered by commands or internal transitions.

`valueObjects[]`¶

Reusable, immutable models for encapsulated logic or structure.

⚙️ Consumed By¶

Agent	Skill	Output
Backend Developer Agent	`GenerateHandler`	`BookAppointmentHandler.cs`
Domain Modeler Agent	`EmitAggregateClass`	`Appointment.cs`
Event Architect Agent	`EmitDomainEventContract`	`AppointmentBooked.cs`
Test Generator Agent	`GenerateSpecFlow`	`BookAppointment.feature`

📚 DSL-Driven Folder Structure¶

/BookingService/
  /Domain/
    Appointment.cs
    TimeSlot.cs
    Events/
      AppointmentBooked.cs
  /Application/
    Handlers/
      BookAppointmentHandler.cs
  /Tests/
    Features/
      BookAppointment.feature

🧪 Validation Rules¶

All commands must emit at least one event
Aggregate must have name and id
No duplicate command or event names
Field types must be resolvable (Guid, DateTime, VO)

🧠 Advanced Features (Supported)¶

Feature	Support
Nested value objects	✅
Inheritance via `$extends`	✅
Command metadata	✅ (`description`, `deprecated`)
Internal-only events	✅ via `visibility: internal`

📊 Traceability Fields¶

dslRef: Path to the DSL
traceId: Execution lifecycle trace
agentId: Origin of generator
dslType: Always DDD for this format

✅ Summary¶

DDD DSL is the foundation of domain logic generation
Used by multiple agents to generate a complete Clean Architecture slice
Easily extended, validated, and versioned across services
Enables full traceability, parallel execution, and safe regeneration

📣 Event DSL — Deep Dive¶

The Event DSL in ConnectSoft defines system-wide, domain, and integration events as first-class, versioned contracts.

It enables:

Agents to generate event classes, schemas, and publish/subscribe bindings
Orchestrators to reason about event flow between bounded contexts
Services to evolve using event-driven architecture principles

“If it's important, it emits an event — and if it emits, it’s defined in the Event DSL.”

📂 DSL File Location¶

dsl/
  Booking/
    event.yaml

📘 Example: `event.yaml`¶

$meta:
  dslType: Event
  context: Booking
  traceId: trace-xyz789
  version: 1.0.0
  agentId: event-architect

events:
  - name: AppointmentBooked
    version: v1
    topic: booking.appointment.booked
    emittedBy: BookingService
    description: Raised when a booking is completed
    fields:
      - name: appointmentId
        type: Guid
      - name: patientId
        type: Guid
      - name: slot
        type: TimeSlot
    consumers:
      - NotificationService
      - AnalyticsAgent

  - name: AppointmentCancelled
    version: v1
    topic: booking.appointment.cancelled
    emittedBy: BookingService
    fields:
      - appointmentId: Guid

🧩 Key Fields¶

Field	Description
`name`	Name of the event
`version`	Schema version (e.g. `v1`)
`topic`	Routing key / message broker topic
`emittedBy`	Source service or aggregate
`fields[]`	Payload schema (typed)
`consumers[]`	Expected subscribers (services or agents)

⚙️ Consumed By¶

Agent	Skill	Output
Event Architect Agent	`EmitDomainEventContract`	`AppointmentBooked.cs`
Messaging Configurator	`ConfigureEventBindings`	`MassTransit` consumer config
Test Generator Agent	`GenerateEventFlowTest`	`AppointmentBooked.spec`
API Designer Agent	`ExposeWebhookEvent`	`WebhookRegistered.cs` (optional)

🔁 Generated Artifacts¶

DomainEvent class
Schema file: AppointmentBooked.event.json
Event registry file (event catalog)
Message broker mapping (e.g., RabbitMQ, Azure Service Bus)

🧪 Validation Rules¶

All events must have unique name per context
Field types must be resolvable globally or declared locally
Topics must follow platform topic naming conventions
Version must be present and semver-compatible

📦 Versioning & Compatibility¶

Scenario	Strategy
Add new field (non-required)	v1 → v1.1
Remove or rename field	v1 → v2
Change topic or structure	v1 → v2

✅ Multiple versions can coexist. Consumers declare supported versions explicitly.

📊 Observability Hooks¶

Field	Traced In
`traceId`	Event generation logs
`dslRef`	All output files and commit tags
`topic`	Event bus instrumentation (e.g. OTEL)
`version`	Event catalog, test coverage report

📘 Example Schema Output¶

{
  "$id": "AppointmentBooked.event.json",
  "title": "AppointmentBooked",
  "type": "object",
  "properties": {
    "appointmentId": { "type": "string", "format": "uuid" },
    "patientId": { "type": "string", "format": "uuid" },
    "slot": {
      "type": "object",
      "properties": {
        "start": { "type": "string", "format": "date-time" },
        "end": { "type": "string", "format": "date-time" }
      }
    }
  },
  "required": ["appointmentId", "patientId", "slot"]
}

✅ Summary¶

Event DSLs define traceable, reusable, observable system events
They power inter-service communication and event-first orchestration
Events include schema, topic, version, emitter, and consumers
All event artifacts are versioned, validated, and linked to their origin DSL

🔌 Adapter DSL — Deep Dive¶

The Adapter DSL defines how ConnectSoft microservices connect to external systems and infrastructure layers — including:

Databases
Message queues
HTTP APIs
Storage services
Identity providers

It describes the contract between a service’s ports and their implementation adapters, ensuring that infrastructure details remain cleanly separated from domain logic.

“Adapter DSL tells the platform how your ports are wired — and lets agents build those connections cleanly and traceably.”

📂 DSL File Location¶

dsl/
  Booking/
    adapter.yaml

📘 Example: `adapter.yaml`¶

$meta:
  dslType: Adapter
  context: Booking
  traceId: trace-def123
  version: 1.0.0
  agentId: infrastructure-engineer

adapters:
  - name: BookingRepositoryAdapter
    port: IBookingRepository
    protocol: database
    type: Postgres
    implements: CreateBooking, CancelBooking
    connection:
      database: BookingDB
      table: Bookings
    injected: true

  - name: NotificationPublisher
    port: INotificationSender
    protocol: messaging
    type: MassTransit
    topic: notification.send
    injected: true

🧩 Key Fields¶

Field	Description
`name`	Name of the adapter class to generate
`port`	Interface or contract it implements
`protocol`	Category: `database`, `http`, `messaging`, `cache`, etc.
`type`	Specific tech: `Postgres`, `RabbitMQ`, `HttpClient`, etc.
`implements`	Optional: methods/commands implemented by this adapter
`connection`	Endpoint, db, URL, topic, queue, etc.
`injected`	Whether to wire it via DI automatically

⚙️ Consumed By¶

Agent	Skill	Output
Infrastructure Engineer Agent	`GeneratePortAdapter`	`BookingRepositoryAdapter.cs`
Messaging Configurator Agent	`EmitPublisherConfiguration`	`MassTransitOptions.cs`
API Gateway Generator Agent	`ExposeAdapterRoute` (for HTTP)	`booking.routes.yaml`
DevOps Agent	`EmitAdapterSecrets`	`bicep:secrets`, `.env`

🧱 Typical Adapter Outputs¶

Class implementation for *.Adapter.cs
Dependency injection binding (services.AddScoped<IBookingRepository, BookingRepositoryAdapter>())
Infrastructure manifest (Bicep/Terraform: secrets, queues, connections)
Messaging or HTTP route configuration

🛡 Security Considerations¶

Secrets referenced via:

secretRef: BookingDB__ConnectionString

* Agents never embed secrets — only emit secure bindings * Secret injection handled via env.yaml, Azure Key Vault, or Kubernetes secrets

🧪 Validation Rules¶

port must be declared or resolved via known interfaces
protocol must match type (e.g., messaging → MassTransit)
connection fields required for http, database, messaging
Duplicate adapter names are blocked per context

📊 Observability Integration¶

Metadata Traced	Used In
`dslRef`, `traceId`, `agentId`	PR annotations, logs, execution metadata
`port`, `type`	Studio DI map, telemetry injectors
`protocol`	MassTransit metrics, DB client spans

📘 Infrastructure Manifest Example (Generated)¶

param BookingDB_ConnectionString string

resource sqlDb 'Microsoft.Sql/servers/databases@2022-02-01-preview' = {
  name: 'booking-db'
  location: resourceGroup().location
  properties: {
    collation: 'SQL_Latin1_General_CP1_CI_AS'
  }
}

✅ Summary¶

The Adapter DSL defines how to bind ports to infrastructure
Supports multiple protocols: database, messaging, http, auth, etc.
Generates adapters, DI registrations, and infrastructure configuration
Keeps service logic clean, testable, and infrastructure-agnostic

🧪 Test DSL — Deep Dive¶

The Test DSL allows ConnectSoft agents to define structured, versioned, and traceable test cases for:

Unit tests
BDD/SpecFlow feature files
Integration tests
Event-driven assertions

It enables autonomous agents to define test intentions declaratively, then generate implementation artifacts in the appropriate framework.

“The Test DSL is where expected behavior meets automation — declaratively.”

📂 DSL File Location¶

dsl/
  Booking/
    test.yaml

📘 Example: `test.yaml`¶

$meta:
  dslType: Test
  context: Booking
  moduleId: BookingService
  traceId: trace-test001
  version: 1.0.0
  agentId: qa-engineer

features:
  - name: Booking Appointment
    scenarios:
      - name: Successful booking
        given:
          - patient exists
          - slot is available
        when:
          - patient books appointment
        then:
          - appointment is saved
          - AppointmentBooked event is emitted

      - name: Duplicate booking
        given:
          - patient already booked
        when:
          - patient books again
        then:
          - error is returned
          - no event is emitted

🧩 Core Fields¶

Field	Description
`features[]`	Test features (aligned with use cases)
`scenarios[]`	Specific BDD-style test paths
`given[]`	Preconditions or test setup
`when[]`	Actions performed
`then[]`	Assertions — state, output, or events
`tags[]`	Optional tags: `@regression`, `@edge`, `@critical`

⚙️ Consumed By¶

Agent	Skill	Output
Test Generator Agent	`GenerateSpecFlow`	`.feature` file
QA Engineer Agent	`EmitTestClass`	`BookingTests.cs`
Bug Investigator Agent	`ReproduceFromTestDsl`	Replay scenarios
Code Reviewer Agent	`VerifyTestCoverageFromDsl`	Diff missing handlers/events

🛠 DSL-to-Test Output Mapping¶

DSL Scope	Output File
`features[]`	`*.feature` file
`then[]`	NUnit / MSTest / FluentAssertions
`events[]`	MassTransit test consumer hooks
`given[]`	AutoFixture, builder pattern setup

📋 Supported Output Formats¶

.feature (Gherkin/SpecFlow)
.cs or .ts test classes
Postman/Newman .json scenarios (optional)
YAML test assertions (contract-based modules)

📊 Observability Tags¶

All test runs, results, and PRs are tagged with:

traceId
dslRef
dslType: Test
context
scenarioName

✅ Enables per-scenario tracking, regression coverage heatmaps, and feedback loops.

🔍 Studio Integration¶

Feature	Description
DSL Trace View	View `.feature` file generated from each scenario
Test Coverage Map	DSL vs Code: what’s tested and what’s not
Auto-fix Suggestions	“This handler is missing a test”
Scenario Replay (Future)	Replay `given` → `when` → `then` via test runner

🧪 Best Practices¶

Guideline	Rationale
Use `@edge`, `@error` tags	Helps prioritization and test generation
Keep `then[]` atomic	Encourages clear assertions and diagnostics
Align with `ddd.yaml` commands	Ensures functional parity
Reuse vocabulary with `valueObjects`	Improves schema alignment and test clarity

✅ Summary¶

The Test DSL defines structured test cases in a reusable, declarative format
Supports BDD, integration, and unit test generation
Fully traceable to domain logic and agent execution
Enables regression safety and intelligent feedback loops for AI-driven generation

🚀 Pipeline DSL — Deep Dive¶

The Pipeline DSL defines autonomous, declarative CI/CD workflows that ConnectSoft agents use to:

Build, test, and deploy services
Manage multi-stage environments (dev, staging, prod)
Integrate security, observability, and test gates
Emit traceable and observable release flows

“Pipeline DSL transforms deployment from script to orchestrated intelligence.”

📂 DSL File Location¶

dsl/
  Billing/
    pipeline.yaml

📘 Example: `pipeline.yaml`¶

$meta:
  dslType: Pipeline
  context: Billing
  traceId: trace-pipe001
  version: 1.0.0
  agentId: devops-engineer

pipeline:
  name: BuildAndDeployBillingService
  trigger:
    event: BlueprintReady
  stages:
    - name: Build
      jobs:
        - dotnet restore
        - dotnet build
        - dotnet test
    - name: Package
      jobs:
        - docker build -t billing-service .
        - docker push billing-service
    - name: DeployStaging
      environment: staging
      jobs:
        - pulumi up --stack staging
    - name: DeployProduction
      environment: production
      approvals:
        - approver: ReleaseManager
      jobs:
        - pulumi up --stack production

🧩 Key Fields¶

Field	Description
`trigger`	Event that activates the pipeline (e.g., `BlueprintReady`, `DslValidated`)
`stages[]`	Ordered phases of the pipeline
`jobs[]`	Shell or task commands to execute
`environment`	Target environment (`dev`, `staging`, `prod`)
`approvals[]`	Optional manual or role-based approvals
`artifacts[]`	Output packages, docker images, test results

⚙️ Consumed By¶

Agent	Skill	Output
DevOps Agent	`EmitYamlPipeline`	`.yaml`, `.yml` (Azure DevOps, GitHub Actions, etc.)
Deployment Orchestrator	`CoordinateStageExecution`	Tracked stage execution with events
Observability Agent	`InjectTelemetryHooks`	Pipeline logs, spans, and metrics
Security Agent	`EnforcePreReleaseChecks`	Stage blocks if policy fails

📋 Supported Backends¶

Platform	Support
Azure DevOps	✅
GitHub Actions	✅
GitLab CI	🟡 planned
Harness, CircleCI	🟡 custom integration via job emitters

🧪 Validation Rules¶

Stage names must be unique
jobs[] must be non-empty
Trigger event must be resolvable in orchestrator FSM
Approvals must match user roles (optional)

📊 Observability Signals¶

Metric	Tags
`pipeline_started_total`	`context`, `dslRef`, `triggerEvent`
`pipeline_stage_duration_seconds`	`stageName`, `status`, `traceId`
`pipeline_artifacts_emitted_total`	`dslRef`, `environment`

🧠 Studio Pipeline View¶

Feature	Description
Stage Timeline	Visual execution flow with durations
Artifact Viewer	View packages, logs, and test results per stage
Approval Flow	See approval logs and decisions
Trigger Tracker	Show event → pipeline run linkage

🔐 Security Features¶

Role-based approvals (e.g., ReleaseManager)
Manual gate triggers
Secret injection via Key Vault/Env from adapter bindings
Rollback plans registered via DSL annotation (future)

✅ Summary¶

Pipeline DSL defines declarative, event-driven CI/CD flows
Converts DSL triggers into YAML pipelines and observable artifacts
Enables agents to autonomously generate, track, and secure deployment processes
Fully integrated into orchestration and observability pipelines

🤖 Agent Execution DSL — Deep Dive¶

The Agent Execution DSL defines declarative plans for how agents coordinate and execute skills, toolchains, memory access, and output pipelines in the ConnectSoft AI Software Factory.

It powers:

Intelligent skill chaining
Prompt and context composition
Memory and knowledge injection
Agent-to-agent handoff
Reproducible execution graphs

“The Agent Execution DSL is the blueprint for how thinking happens in the factory — not just what is built, but how it’s built.”

📂 DSL File Location¶

dsl/
  Booking/
    execution.yaml

📘 Example: `execution.yaml`¶

$meta:
  dslType: Execution
  context: Booking
  traceId: trace-exec001
  version: 1.0.0
  agentId: orchestrator

execution:
  flowName: GenerateBookingService
  steps:
    - skill: ComposeVisionDocument
      agent: vision-architect
      input:
        prompt: "Build a modular SaaS for booking veterinary appointments"
        memoryScope: vision/Booking
    - skill: EmitDomainModelDsl
      agent: domain-modeler
      input:
        source: vision/Booking/vision.md
    - skill: GenerateHandler
      agent: backend-developer
      input:
        dslRef: dsl/Booking/ddd.yaml
        target: BookAppointment
    - skill: CommitToGit
      agent: code-committer
      input:
        artifacts: [BookAppointmentHandler.cs, Appointment.cs]
        branch: feature/booking-service

🧩 Core Fields¶

Field	Description
`flowName`	Logical name of the execution pipeline
`steps[]`	Ordered or conditional steps
`skill`	Name of skill to execute (must be registered)
`agent`	Responsible agent persona
`input`	Prompt, DSL reference, memory, context
`output` (optional)	Expected files or metadata
`condition` (optional)	Execution guard (e.g., if not exists)

⚙️ Consumed By¶

Agent	Skill Engine	Usage
Planner Agent	`EmitAgentPlan`	Generates the execution DSL itself
Orchestrator Agent	`RunExecutionFlow`	Walks through and executes all steps
Studio	Visual execution map	Tracks skill-by-skill progress
Debugger Agent (future)	`ReplayAgentPlan`	Replays or diagnoses failed steps

🔁 Conditional & Parallel Execution (Planned)¶

DSL supports planned extension for:

parallel:
  - skill: GenerateSpecFlow
    agent: test-generator
  - skill: EmitOpenApiContract
    agent: api-designer

And:

condition:
  exists: dsl/Booking/ddd.yaml

📊 Execution Telemetry (Per Step)¶

Field	Description
`stepId`	Unique per step
`status`	`started`, `completed`, `failed`
`skillId`	Mapped to `GenerateHandler`, etc.
`outputChecksum`	Hash of emitted artifact(s)
`durationMs`	Runtime duration of the skill

→ All steps traceable in logs, metrics, and Studio UI.

🧠 Studio Features¶

Feature	Description
Execution Graph	Visual trace of skill chain
Step Replay	Re-run from failed point
Memory Injection Viewer	See what memory was injected into each prompt
Output Verification	Compare emitted artifacts against expected form

🧪 Validation Rules¶

All skills must exist in skillRegistry
agent must support the given skill
Steps must specify either prompt, dslRef, or memoryScope
Outputs are validated via checksum if declared

✅ Summary¶

Agent Execution DSL defines how agents work together
Drives modular, observable multi-skill orchestration plans
Supports memory injection, prompt binding, and output validation
Enables full lifecycle control from problem → blueprint → code → PR

🧠 Linking DSLs to Blueprint & Vision Documents¶

In the ConnectSoft platform, DSLs aren’t created in isolation — they are derived, aligned, and traceable from:

✨ Vision Documents: business goals, feature intent, user personas
🧱 Blueprints: technical structure, modules, service responsibilities

This linking ensures that generated DSLs accurately reflect business context and can be evolved as upstream inputs change.

“Blueprints define what to build, vision explains why — DSLs are the bridge.”

🔁 Source Hierarchy Overview¶

graph TD
    A[Vision Document] --> B[Blueprint]
    B --> C[DSLs]
    C --> D[Artifacts (Code, Tests, Pipelines)]

Hold "Alt" / "Option" to enable pan & zoom

Each DSL includes a source or upstream reference to its originating vision/blueprint.

🧩 How Linking Works¶

1. Vision → DSL Mapping¶

Vision Entity	Translates to DSL
Feature: "Book Appointment"	Command in `ddd.yaml`
Persona: "Pet Owner"	Test scenario in `test.yaml`
Module: "Notifications"	Event in `event.yaml`, Adapter in `adapter.yaml`
Constraint: "Multi-tenant"	Added to `pipeline.yaml`, `adapter.yaml` injection rules

2. Blueprint → DSL Binding¶

Blueprint Field	DSL Output
`boundedContext: Billing`	→ `dsl/Billing/ddd.yaml`
`service: NotificationService`	→ `dsl/Notifications/event.yaml`
`dependsOn: UserService`	→ `adapter.yaml` reference
`events: emits[]`	→ `event.yaml` contracts

📘 DSL Metadata Example (Linked to Blueprint)¶

$meta:
  dslType: DDD
  context: Booking
  source:
    blueprint: blueprints/booking/blueprint.yaml
    feature: BookAppointment
    visionDoc: vision/booking/vision.md
  traceId: trace-link001
  agentId: domain-modeler

📂 Folder Convention¶

vision/
  booking/
    vision.md
blueprints/
  booking/
    blueprint.yaml
dsl/
  booking/
    ddd.yaml
    event.yaml

Studio recognizes and auto-links these paths.

🧠 Agent Behavior¶

Agent	Behavior
Vision Architect Agent	Emits `vision.md` with goals, scope, and personas
Blueprint Generator Agent	Produces `blueprint.yaml` (context, modules, integrations)
DSL Generator Agent	Reads both upstream files to generate accurate DSLs
QA Agent / Reviewer	Can trace generated code/tests back to feature justification

📊 Studio Support¶

Feature	Description
“Show DSL Source”	View original blueprint + vision fields
“Jump to Blueprint”	Cross-navigate from `ddd.yaml` to `blueprint.yaml`
“Compare Generated DSL vs Vision”	Highlights mismatch or missing outputs
“DSL Drift Detector” (future)	Detects changes in upstream vision/blueprint not reflected in current DSL

✅ Summary¶

DSLs are tightly coupled to upstream vision and blueprint documents
This ensures alignment to business goals and technical architecture
Agents embed source metadata to enable full traceability
DSL–Blueprint–Vision linkage is visible, validated, and auditable in Studio

🗂️ DSL Registry and Artifact Management¶

Every DSL in ConnectSoft is a versioned, traceable, and auditable artifact, managed by the DSL Registry — a central component of the platform’s modular, multi-agent architecture.

The registry ensures:

Consistent access to DSLs across agents and orchestrators
Version tracking and change history
Discovery and reuse of DSL components across modules or tenants
Linkage to generated artifacts, metrics, and commits

“The DSL registry is the factory’s source of truth for all structured intent.”

📂 Recommended Folder Structure¶

dsl/
  Booking/
    ddd.yaml
    event.yaml
    adapter.yaml
    test.yaml
    execution.yaml
  Billing/
    ddd.yaml
    pipeline.yaml

Each context (bounded context or domain) has its own namespace.

📘 DSL File Naming Conventions¶

Type	File Name
Domain	`ddd.yaml`
Events	`event.yaml`
Adapters	`adapter.yaml`
Tests	`test.yaml`
Pipeline	`pipeline.yaml`
Execution	`execution.yaml`
Shared	`*.template.yaml`

✅ DSLs may also include *.metadata.json or $meta: blocks for traceability.

🔁 Versioning Model¶

Each DSL includes a version field (semver):

$meta:
  version: 1.0.2

Versioning Triggers:¶

Trigger	Version Change
Added new optional field	Patch (1.0.1 → 1.0.2)
Changed field structure/order	Minor (1.0 → 1.1)
Breaking semantic meaning	Major (1.x → 2.0)

All versions are retained in the registry under:

dsl/Booking/.history/ddd.v1.0.0.yaml

📦 Artifact Linking¶

All artifacts emitted by agents (code, tests, configs) include:

{
  "traceId": "trace-abc123",
  "dslRef": "dsl/Booking/ddd.yaml",
  "dslVersion": "1.0.2",
  "artifact": "BookAppointmentHandler.cs"
}

This allows:

Audit of what code was generated from which DSL
Rebuild or rollback to a known version
Clear association of DSL → Artifact → PR

📊 Studio Registry Features¶

Feature	Description
DSL Explorer	Navigate all DSLs by context and type
Version History	Compare versions, diffs, rollback
Artifact Links	See what files came from which DSL
Status Indicators	Validated ✅, Invalid ❌, Deprecated ⏳
Search & Filtering	By agent, skill, module, tag, or traceId

🔐 Governance and Policies¶

DSLs must pass validation before being published
Mutating a DSL post-consumption triggers revalidation
Archived DSLs are retained for audit but not processed
Only specific agents (e.g., DSL Generator, Editor Agent) can write to the registry

🤖 Agent Interactions with Registry¶

Agent	Role
DSL Generator Agent	Emits DSL into registry with metadata
Planner / Orchestrator	Looks up DSLs by type, version, or context
Rebuilder Agent	Regenerates artifacts from pinned DSLs
Studio CLI (future)	CLI tools to list, diff, export DSLs

✅ Summary¶

The DSL Registry is the platform’s authoritative source of structured software intent
All DSLs are versioned, validated, and linked to generated artifacts
Registry features power traceability, rebuilds, analytics, and reuse
Studio and agents use the registry to coordinate modular execution at scale

🧪 Future DSL Extensions and Custom Module Types¶

While the current ConnectSoft DSL suite covers foundational areas (DDD, Event, Test, Adapter, Pipeline, Execution), the platform is built to evolve new DSL types to support emerging needs such as:

Knowledge modeling
Analytics definitions
UI layout generation
Migration management
Custom orchestrator extensions

“DSLs are not just tools — they are language primitives for the factory’s next capabilities.”

🔮 Planned & Proposed DSL Types¶

DSL Type	Purpose
Migration DSL	Define DB schema evolutions, versioned changesets
UI DSL	Describe component layout, binding to APIs, form logic
Analytics DSL	Declare events, dimensions, metrics, and dashboards
Feature Flag DSL	Define toggleable features, conditions, rollout plans
Workflow DSL	Describe orchestration logic, human-in-loop flows
Memory DSL	Declare structured memory objects for vector storage
Knowledge DSL	Index long-form documents, FAQs, definitions
IAM DSL	Role definitions, scopes, claims, policies
Task DSL	Describe a multi-agent execution sequence (low-code automation)

📘 Example: Migration DSL (Draft)¶

$meta:
  dslType: Migration
  context: Billing
  version: 1.0.0
  traceId: trace-migrate123

migrations:
  - id: 001_create_invoices
    up:
      - createTable:
          name: Invoice
          columns:
            - name: Id
              type: Guid
              primaryKey: true
            - name: Amount
              type: Decimal
    down:
      - dropTable: Invoice

🤖 Agent Support for Future DSLs¶

DSL Type	Agent (Planned/Existing)	Skill
`Migration`	Database Migration Agent	`EmitFluentMigratorScript`
`UI`	Frontend Layout Agent	`GenerateComponentLayout`
`Analytics`	Insights Agent	`EmitEventTrackingSchema`
`Workflow`	Orchestration Designer Agent	`EmitCoordinatorFlow`
`Memory`	Knowledge Ingestion Agent	`VectorizeMemoryEntry`
`IAM`	Security Architect Agent	`EmitAccessPolicy`

🧠 Use Cases for Custom Module DSLs¶

Use Case	DSL Outcome
Multi-tenant dashboarding	`analytics.yaml` per context
Custom onboarding form	`ui-layout.yaml`
Offline worker replay and retry	`workflow.yaml`
Feature toggle-based release	`feature-flag.yaml`
Memory-rich agents per tenant	`memory.yaml` with vector embeddings

📊 DSL Plugin System (Future)¶

ConnectSoft plans to support:

Plugin-registered DSL schemas
Custom validation rules per organization
Agent/skill mappings per custom DSL type
Auto-discovery via DSL metadata index

→ Example: dslType: CRMRules → validated by custom agent, with downstream artifact emission.

🧩 DSL Composition (Experimental)¶

DSLs will support cross-type references, e.g.:

test.yaml reusing commands[] from ddd.yaml
analytics.yaml importing events from event.yaml
ui.yaml wiring to adapters declared in adapter.yaml

This unlocks advanced reuse and modular alignment across the system.

✅ Summary¶

The ConnectSoft DSL engine is designed for extensibility
New DSLs can support UI, analytics, migrations, IAM, and more
Agent orchestration will adapt as DSL types evolve
DSLs will become composable and declaratively linked, enabling higher-level generation across more modules

📚 Recipes and Knowledge Memory vs DSLs¶

DSLs are not the only form of reusable intelligence in ConnectSoft.

The platform also supports:

Recipes → step-by-step, human-readable, contextualized guidance
Knowledge memory → semantic embeddings, indexed documents, and examples These power agent understanding, while DSLs power agent execution.

“DSLs are code contracts. Recipes are how-tos. Knowledge is meaning. All three matter.”

🧩 Core Differences¶

Concept	Format	Used For	Agent Role
DSL	YAML/JSON	Declarative contracts, generation	Execution & artifact emission
Recipe	Markdown	Step-by-step instructions	Prompt enhancement & planning
Memory	Semantic vector	Long-form docs, Q\&A, examples	Prompt context & enrichment

📘 Example: DSL vs Recipe vs Memory¶

DSL (`ddd.yaml`)¶

commands:
  - name: BookAppointment
    fields:
      - patientId: Guid

Recipe (`recipes/booking/book-appointment.md`)¶

# BookAppointment Command

1. Validate patientId is not null
2. Check appointment slot is available
3. Save appointment
4. Emit AppointmentBooked event

Knowledge Memory¶

"The BookAppointment command must ensure that overlapping appointments are not allowed. If the time slot is occupied, return a domain exception."

Stored as a semantic chunk in the Booking context memory.

🤖 How Agents Use Them¶

Action	DSL Used	Recipe Used	Memory Used
Generate `BookAppointmentHandler.cs`	✅	✅ (optional prompt context)	✅ (injected context)
Plan test scenario from blueprint	✅	✅	✅
Rebuild failed pipeline	✅	✅	❌
Explain reasoning to user (studio UI)	❌	✅	✅
Perform decision on best adapter type	❌	✅	✅

🧠 Storage & Versioning¶

Asset Type	Path	Versioned?
DSL	`dsl/<context>/<type>.yaml`	✅
Recipe	`recipes/<context>/<use-case>.md`	✅
Memory	`memory/<context>/<semantic>.json`	✅ (via embeddings snapshots)

📊 Traceability and Observability¶

DSLs are observable: emit DslGenerated, DslValidated, etc.
Recipes are referenced in execution metadata, but not executed
Memory entries are recorded in memoryInjectionLog with traceId

🧩 Studio Features¶

Feature	DSL	Recipe	Memory
Trace to code	✅	🔄 linked	🔄 enriched
Display during prompt	✅	✅	✅
Edit in UI	✅	✅	🟡 embedded only
Diff vs. generated output	✅	✅ (planned)	❌

🔄 Complementarity Model¶

graph TD
    A[DSL] --> C[Agent Execution]
    B[Recipe] --> C
    D[Memory Vector] --> C
    C --> E[Generated Code / Plan]

Hold "Alt" / "Option" to enable pan & zoom

DSL = declarative truth Recipe = procedural logic Memory = contextual intent

All are combined at execution time by the orchestrator and planner.

✅ Summary¶

DSLs define what should be built
Recipes define how it should be done
Knowledge memory defines why it works or what matters

Together, they form the connective intelligence fabric of ConnectSoft’s autonomous engineering system.

🧠 DSL-Aware Knowledge Graph¶

The DSL-Aware Knowledge Graph in ConnectSoft is the semantic structure that connects:

DSLs
Generated artifacts
Blueprints
Vision documents
Recipes
Memory embeddings
Agents and skills

This graph enables agents and orchestrators to reason across context, enforce consistency, and trace cause-and-effect across the entire software lifecycle.

“The knowledge graph is the map that lets agents navigate a factory of 3,000+ services — with precision.”

🧩 What Is a DSL-Aware Knowledge Graph?¶

It is a semantic graph built from platform metadata, where nodes include:

DSLs (dslRef)
Skills (skillId)
Agents (agentId)
Trace IDs
Output files (artifacts)
Blueprints and recipes
Events (emitted/consumed)

And edges include:

definedBy
consumes
emits
linkedTo
derivedFrom
extends

📘 Example Subgraph¶

graph TD
    V[vision.md] -->|defines| BP[blueprint.yaml]
    BP -->|emits| D[ddd.yaml]
    D -->|consumed by| A1[Backend Agent]
    D -->|produces| H[BookAppointmentHandler.cs]
    D -->|extends| T[ddd.template.yaml]
    H -->|committed in| PR[PR #123]

Hold "Alt" / "Option" to enable pan & zoom

Each node and edge is tagged with traceId, context, dslType, etc.

🔍 Queries Supported¶

Query	Purpose
“What DSLs were used to generate this artifact?”	Trace backward from code
“Which agents modified this module?”	Identify contributors
“What vision goal led to this event contract?”	Business-to-code mapping
“What DSLs were extended by this one?”	Inheritance map
“What tests validate a command?”	Validation chain

🧠 Powered By¶

Internal graph database or metadata index
Updated continuously by orchestrator and agents
Enriched with recipe references, memory usage, and user activity

📊 Studio Features (Graph-Aware)¶

Feature	Description
Trace Graph Explorer	Navigate entity relationships visually
Dependency Impact Explorer	Show affected DSLs/tests if aggregate changes
Coverage Map	DSLs with missing artifacts/tests
“Why was this generated?”	Reverse map blueprint → DSL → skill → artifact

🤖 Agent Capabilities (Graph-Enabled)¶

Agent	Behavior
Planner Agent	Queries graph to decide next skill
QA Agent	Uses graph to trace test gaps
Security Agent	Flags orphaned/unused DSLs
Studio Assistant Agent	Answers “How did this handler get here?” questions

🧠 Knowledge Graph vs Knowledge Memory¶

Knowledge Graph	Knowledge Memory
Structured, relational	Semantic, vectorized
Used for traceability	Used for context enrichment
GraphQL/DSL-exposed	Natural language/prompt-based
Indexed by IDs and refs	Indexed by semantic embeddings

✅ Together, they provide full contextual + relational understanding of the software factory.

✅ Summary¶

The DSL-Aware Knowledge Graph connects all entities in the platform: vision → blueprint → DSL → skill → artifact
Enables traceability, reasoning, planning, and impact analysis
Used by agents, Studio, and orchestration pipelines
Serves as the structural backbone of autonomy at scale

📘 DSLs in ConnectSoft¶

🧠 What Is a DSL?¶

🎯 Why DSLs Matter in an AI Software Factory¶

Traditional Model:¶

ConnectSoft Model (AI-First):¶

🧱 What DSLs Enable¶

🔁 DSLs in the ConnectSoft Lifecycle¶

📦 DSLs vs Other Platform Assets¶

🧠 Without DSLs, You'd Lose:¶

✅ Summary¶

⚖️ DSLs vs Skills vs Prompts in ConnectSoft¶

🧱 Conceptual Comparison Table¶

🧠 How They Work Together¶

Full Lifecycle Example¶

🔁 Execution Flow Relationship¶

🧬 Metadata Anchors¶

✅ Summary¶

🔄 DSL Lifecycle in the ConnectSoft AI Software Factory¶

🧭 Phases of the DSL Lifecycle¶

1️⃣ Trigger (Prompt or Blueprint)¶

2️⃣ Generation¶

3️⃣ Validation¶

4️⃣ Storage & Registry¶

5️⃣ Agent Consumption¶

6️⃣ Artifact Emission¶

7️⃣ Observability & Tracing¶

📘 Sample Lifecycle Log (Structured)¶

✅ Summary¶

🏷️ DSL Metadata & Traceability in ConnectSoft¶

📦 Metadata Structure for All DSLs¶

Example: Embedded Metadata in ddd.yaml¶

🧱 Metadata Field Reference¶

🔎 How Metadata Supports Platform Flows¶

1. Agent Routing¶

2. Studio Navigation¶

3. Observability & Audit Logs¶

🧠 Linked Execution Metadata Example¶

✅ Summary¶

🧬 Anatomy of a DSL Document in ConnectSoft¶

🧱 Standard DSL Document Structure¶

🧩 Core Sections of a DSL¶

🧠 DSL Meta Section¶

🛠️ Optional Sections by DSL Type¶

📚 Validation Rules¶

✅ Summary¶

🤖 Agent Interaction with DSLs in ConnectSoft¶

🧠 Types of Agent Interactions with DSLs¶

⚙️ Execution Flow Example¶

🧱 Agent Skill Decision from DSL¶

🧩 Agent Runtime Context Injection¶

📄 Example: Agent-Generated Output with DSL Link¶

📊 Studio View of Agent+DSL Execution¶

✅ Summary¶

🧭 Orchestration Layer Integration with DSLs¶

⚙️ Orchestration Lifecycle Flow (With DSLs)¶

🔄 What the Orchestrator Does with DSLs¶

🧩 How DSLs Are Matched to Agent Flows¶

🧠 Triggering Strategy (Example)¶

📂 DSL Folder Routing Convention¶

📊 DSL in Orchestration Metrics¶

✅ Summary¶

📡 DSL Observability & Events in ConnectSoft¶

🧠 DSL Lifecycle Events¶

📍 Key Events Emitted¶

📊 DSL Metrics¶

Emitted to OpenTelemetry or Prometheus:¶

Sample Prometheus Metric¶

📘 Studio DSL Observability Features¶

🔐 Audit & Compliance Support¶

✅ Summary¶

✅ DSL Validation & Schemas in ConnectSoft¶

🧠 What Is Validated?¶

✅ Schema Validation¶

✅ Semantic Validation¶

📂 DSL Schema File Locations¶

🧰 Validation Engine Integration¶

🔍 Sample Validation Result (Failure)¶

🔄 Validation Lifecycle Events¶

🛑 What Happens If a DSL Is Invalid?¶

📊 Metrics Emitted¶

Example: Embedded Metadata in `ddd.yaml`¶

🔹 Base Template — `ddd.template.yaml`¶

🔸 Inheriting DSL — `Booking/ddd.yaml`¶

📘 Example: `ddd.yaml`¶

`aggregate`¶

`commands[]`¶

`events[]`¶

`valueObjects[]`¶

📘 Example: `event.yaml`¶

📘 Example: `adapter.yaml`¶

📘 Example: `test.yaml`¶