Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Solution Design Language (SDL) specification — schema, validation, normalization, and generation rules
SDL Knowledge
Identity
You understand the Solution Design Language (SDL) — a YAML-based architecture specification format used by arch0 to capture complete system designs. SDL transforms raw requirements into a validated, normalized intermediate representation that drives deterministic artifact generation.
Core Principle
SDL sits between requirements gathering and artifact generation. The manifest captures what the user said. SDL transforms that into what the system will build — with smart defaults filled in, incompatibilities caught, and warnings surfaced.
What SDL Is
SDL is a machine-readable YAML specification. This plugin uses the v1.1 path for architecture workflows. Older v0.1 material should be treated as obsolete and upgraded rather than reused for new generation.
Solution metadata and stage (MVP / Growth / Enterprise)
Product personas and core user flows
Architecture style and project structure (frontend, backend, mobile)
Authentication strategy and provider
Data layer (databases, cache, queues, search, storage)
These are hard errors — SDL will not compile if violated (27 rules from spec/SDL-v1.1.md):
Reference Integrity
#
Condition
Requirement
Fix
1
environments[].components defined
Every component name must exist in architecture.projects
Rename or add missing component
2
slos[].componentId defined
Must match a component in architecture.projects
Fix componentId to match project name
3
costs.infrastructure[].component defined
Must match a component in architecture.projects
Fix component name or remove entry
4
architecture.projects[].dependsOn[] defined
Must not form a cycle
Break circular dependency
5
contracts[].paths[].service defined
Service must exist in architecture.projects
Fix service name in contract paths
6
domain.entities[].relationships[].target defined
Target entity must exist in domain.entities
Add missing entity or fix target name
7
features.phase*.features[].dependsOn[] defined
Referenced IDs must exist in same or earlier phases
Move feature to correct phase or fix ID
8
resilience.circuitBreaker[].service defined
Service must exist in architecture.projects
Fix service name in circuit breaker config
9
backupDr.databases[].name defined
Must match a name in data.databases or data.primaryDatabase
Fix database name
Type Compatibility
#
Condition
Requirement
Fix
10
Any architecture.projects[].orm set
Must be compatible with data.primaryDatabase.type (Prisma ✓ relational/MongoDB; Mongoose ✓ MongoDB only; EF Core ✗ MongoDB)
Change ORM or database type
11
architecture.projects[].framework + .language
Must be compatible (NestJS → node/ts; Django → python; Spring → java)
Fix framework or language
12
auth.provider references an integration
Provider must exist in integrations[]
Add missing integration or fix provider name
Deployment Integrity
#
Condition
Requirement
Fix
13
architecture.style = "microservices"
architecture.services[] must have 2+ items
Add services or switch to modular-monolith
14
architecture.projects[].deployable = true
Component must appear in at least one environment
Add to environments or set deployable: false
15
Multiple components in same environment
No duplicate ports
Change port on one component
16
deployment.regions[] defined
Regions must be valid for deployment.cloud
Fix region for cloud provider
17
deployment.infrastructure.iac = "cloudformation"
deployment.cloud must be "aws"
Use terraform/cdk or change cloud to aws
Data Model Integrity
#
Condition
Requirement
Fix
18
domain.entities[] defined
Every entity must have exactly one primaryKey: true field
Add primary key field
19
FK relationship spans different databases
Flag as limitation (no DB-level enforcement)
Use application-level FK or consolidate to one DB
20
All architecture.projects entries
Component names must be globally unique
Rename duplicate component
21
domain.entities[] defined
Each entity should be owned by a component (soft)
Add x-owner field to entity
Configuration Completeness
#
Condition
Requirement
Fix
22
architecture.projects[].deployable = true
Component must have path and runtime
Add missing path/runtime fields
23
auth.strategy = "oidc"
auth.identityProvider must be set
Add identityProvider
24
compliance.frameworks[].name defined
Must be recognised: GDPR | HIPAA | SOC2-Type2 | PCI-DSS | CCPA | ISO27001
Fix framework name
Resilience & Performance
#
Condition
Requirement
Fix
25
resilience.circuitBreaker[].failureThreshold or retryPolicy[].maxAttempts defined
Must be > 0
Set positive integer value
26
slos[].availability.target defined
Must be 90–99.99%; latency.p99 must be > latency.p50
Adjust target or latency values
PII & Security
#
Condition
Requirement
Fix
27
Any entity field contains PII data
nonFunctional.security.pii: true AND encryptionAtRest: true
Set both fields
Normalization Rules
The normalizer applies 15 auto-inference defaults. Do not manually set these — let the normalizer handle them:
#
Field
Default
Condition
1
solution.regions.primary
"us-east-1"
If regions missing
2
data.primaryDatabase.name
"{name}_db"
Lowercased, non-alphanumeric → _
3
frontend[].type
"web"
If type not set
4
backend[].type
"backend"
If type not set
5
deployment.runtime.frontend
From cloud mapping
See table below
6
deployment.runtime.backend
From cloud mapping
See table below
7
deployment.networking.publicApi
true
If undefined
8
deployment.ciCd.provider
"github-actions"
If ciCd missing
9
nonFunctional.availability.target
Stage-based
concept/mvp→99%, growth→99.9%, enterprise→99.99%
10
security.encryptionAtRest
true
If pii=true
11
security.encryptionInTransit
true
If undefined
12
(reserved)
—
—
13
backend[].orm
Framework+DB based
See ORM mapping below
14
testing.unit.framework
Backend framework based
See test mapping below
15
observability.logging.provider
Backend framework based
See logging mapping below
Cloud → Runtime Mapping
Cloud
Frontend Runtime
Backend Runtime
vercel
vercel
vercel
aws
s3+cloudfront
ecs
railway
railway
railway
gcp
cloudflare-pages
cloud-run
azure
static-web-apps
container-apps
Framework → ORM Mapping
Framework
postgres
mysql
mongodb
nodejs
prisma
prisma
mongoose
python-fastapi
sqlalchemy
sqlalchemy
—
dotnet-8
ef-core
ef-core
—
go
gorm
gorm
—
java-spring
hibernate
hibernate
—
Framework → Test Framework Mapping
Framework
Test Framework
nodejs
vitest
python-fastapi
pytest
dotnet-8
xunit
go
go-test
java-spring
junit
ruby-rails
rspec
php-laravel
phpunit
Framework → Logging Provider Mapping
Framework
Logging Provider
nodejs
pino
python-fastapi
structured
dotnet-8
serilog
go
zerolog
java-spring
log4j
Warning Detection
Warnings are non-fatal checks applied after validation passes:
Warning 1: Complexity vs Team
TRIGGER: architecture.style = "microservices" AND (totalDevs < 3 OR devops = 0)
CODE: COMPLEXITY_EXCEEDS_TEAM_CAPACITY
MESSAGE: "Microservices with {N} service(s) may be too complex for {D} developer(s)"
FIX: "Consider modular-monolith for MVP — plan microservices migration when team grows"
Warning 2: Timeline vs Scope
TRIGGER: (projectCount × flowCount × 1.5) / totalDevs > timelineWeeks
CODE: TIMELINE_TOO_AGGRESSIVE
MESSAGE: "{P} project(s) with {F} core flow(s) may not fit in {W} weeks"
FIX: "Reduce scope, extend timeline, or add developers"
Warning 3: Multi-Persona without Auth
TRIGGER: auth section missing AND personas > 1 AND (any has admin role OR count > 2)
CODE: MISSING_RECOMMENDED_FIELD
MESSAGE: "{N} personas defined but no auth configuration"
FIX: "Add an auth section with strategy and roles"
TRIGGER: architecture.style = "microservices" AND team.developers < 3
CODE: MICROSERVICES_TEAM_TOO_SMALL
MESSAGE: "Microservices architecture with only {N} developer(s) — operational overhead is high"
FIX: "Use modular-monolith for MVP; migrate to microservices as team grows"
Warning 6: Cross-Database Foreign Keys
TRIGGER: domain.entities[].relationships[].target entity lives in different database
CODE: CROSS_DATABASE_FOREIGN_KEY
MESSAGE: "{entity}.{field} → {target} spans databases — no DB-level enforcement"
FIX: "Enforce referential integrity at application layer; consider consolidating entities"
Warning 7: Unused Integrations
TRIGGER: integration defined in integrations[] but not referenced in any component's dependsOn[]
CODE: UNUSED_INTEGRATION
MESSAGE: "Integration '{name}' is defined but not referenced by any component"
FIX: "Add to relevant component's dependsOn[], or remove if not needed"
Warning 8: Missing Observability for Production
TRIGGER: solution.stage = "growth" OR "enterprise" AND observability section absent
CODE: MISSING_OBSERVABILITY
MESSAGE: "{stage}-stage project has no observability configuration"
FIX: "Add observability section with logging, tracing, and metrics; run /architect:setup-monitoring"
Warning 9: Loose SLO Targets
TRIGGER: solution.stage = "growth" OR "enterprise" AND any slos[].availability.target < 99%
CODE: LOOSE_SLO_TARGET
MESSAGE: "SLO target {X}% is below recommended minimum for {stage} stage"
FIX: "Raise availability target or document reason for lower target"
Warning 10: High Cost Variance
TRIGGER: costs.scenarios.high > costs.scenarios.low × 10
CODE: HIGH_COST_VARIANCE
MESSAGE: "Cost scenarios vary {X}x (low: ${L}/mo vs high: ${H}/mo)"
FIX: "Review usage assumptions; choose tiers with more predictable pricing"
Warning 11: Compliance Gaps
TRIGGER: solution.stage = "growth" OR "enterprise" AND compliance section absent
OR constraints.compliance defined but compliance.frameworks[] absent
CODE: COMPLIANCE_NOT_ADDRESSED
MESSAGE: "Stage or constraints suggest compliance needs but no compliance section defined"
FIX: "Add compliance section or run /architect:compliance for gap analysis"
Warning 12: Design Tokens Missing for Production
TRIGGER: solution.stage = "growth" OR "enterprise" AND design section absent
CODE: DESIGN_TOKENS_MISSING
MESSAGE: "{stage}-stage project has no design tokens defined"
FIX: "Run /architect:design-system to generate a complete design token set"
Error Codes
Parse Errors
Code
Trigger
Fix
EMPTY_INPUT
Empty YAML string
Provide valid YAML
INVALID_YAML
Result is not an object
Start with key-value pairs
YAML_PARSE_ERROR
Syntax error
Fix indentation, colons, special characters
Schema Errors
Code
Trigger
Fix
MISSING_REQUIRED
Required field absent
Add the field
INVALID_ENUM
Value not in allowed list
Use allowed value
INVALID_TYPE
Wrong data type
Provide correct type
UNKNOWN_FIELD
Unknown field without x- prefix
Remove or prefix with x-
INVALID_FORMAT
Pattern mismatch
Follow required format
VALUE_TOO_SHORT
Below min length
Provide longer value
ARRAY_TOO_SHORT
Below min items
Add more items
Conditional Rule Errors
Code
Trigger
Fix
MICROSERVICES_REQUIRES_SERVICES
Microservices without 2+ services
Add services or use modular-monolith
OIDC_REQUIRES_PROVIDER
OIDC without provider
Add provider field
PII_REQUIRES_ENCRYPTION
PII without encryption
Set encryptionAtRest: true
INCOMPATIBLE_CLOUD_IAC
CloudFormation on non-AWS
Use terraform or change to AWS
INCOMPATIBLE_DATABASE_ORM
MongoDB with EF Core
Use mongoose or change database
Manifest-to-SDL Mapping
When converting a system manifest to SDL:
Manifest Field
SDL Field
project.name
solution.name
project.description
solution.description
project.type (app/agent/hybrid)
solution.stage — infer: new idea → MVP, scaling → Growth
users[].role
product.personas[].name
users[].description
product.personas[].goals (split into goal statements)
users[].count (sum)
nonFunctional.scaling.expectedUsersYear1
frontends[]
architecture.projects.frontend[]
services[]
architecture.projects.backend[]
databases[0]
data.primaryDatabase
databases[1+]
data.secondaryDatabases[]
integrations[category=payments]
integrations.payments
integrations[category=email]
integrations.email
integrations[category=auth]
auth section
integrations[category=storage]
data.storage
integrations[category=cache]
data.cache
application_patterns.style
architecture.style
security.auth
auth section
security.api_security
nonFunctional.security
devops.ci_cd.provider
deployment.ciCd.provider
deployment.targets[0]
deployment.cloud
communication_patterns[]
interServiceCommunication[]
application_patterns.error_handling
errorHandling
devops.config_management
configuration
services[].name + frontends[].name (cross-referenced with communication patterns)
architecture.projects.*[].dependsOn[] — required on every component. Array of names of other components and external providers this component calls. Rules: frontend lists every backend it calls; backend lists downstream services + external integrations (e.g. ["stripe", "sendgrid"]); lambda/worker lists its trigger source + any downstream service; shared lib gets []. Always emit the field even when empty. Use the component's SDL name as identifier. External providers in lowercase (e.g. "razorpay", "anthropic").
Detected domain objects (entity names from models/schemas)
domain.entities[] — list of core domain object names
Auth note: Use auth.identityProvider for the external IdP (cognito, auth0, clerk) and auth.serviceTokenModel for how services validate tokens (jwt, session, api-key). These are often different — e.g. Cognito issues tokens, services validate them as JWT.
Integration Provider Mapping
Manifest Service
SDL Path
Stripe
integrations.payments.provider: stripe
SendGrid
integrations.email.provider: sendgrid
Resend
integrations.email.provider: resend
Twilio
integrations.sms.provider: twilio
PostHog
integrations.analytics.provider: posthog
Datadog
integrations.monitoring.provider: datadog
Sentry
integrations.monitoring.provider: sentry
Cloudflare
integrations.cdn.provider: cloudflare
Auth0
auth.identityProvider: auth0
Firebase Auth
auth.identityProvider: firebase
Clerk
auth.identityProvider: clerk
Cognito
auth.identityProvider: cognito
S3
data.storage.blobs.provider: s3
GCS
data.storage.blobs.provider: gcs
Azure Blob
data.storage.blobs.provider: azure-blob
Cloudflare R2
data.storage.blobs.provider: cloudflare-r2
Redis
data.cache.type: redis
RabbitMQ
data.queues.provider: rabbitmq
SQS
data.queues.provider: sqs
Kafka
data.queues.provider: kafka
Azure Service Bus
data.queues.provider: azure-service-bus
Elasticsearch
data.search.provider: elasticsearch
Algolia
data.search.provider: algolia
Typesense
data.search.provider: typesense
Meilisearch
data.search.provider: meilisearch
Azure Search
data.search.provider: azure-search
Pinecone
data.search.provider: pinecone
Qdrant
data.search.provider: qdrant
Weaviate
data.search.provider: weaviate
Domain Entities
The domain section captures the core business objects of the system. It is optional but strongly recommended for any system with 3+ services or a complex data model.
generate-data-model — to enumerate all entities that need ORM schemas
blueprint — to drive the data model section and ERD generation
prototype — to generate typed mock data and CRUD pages
Rules:
List entity names only (PascalCase) — no fields, no relationships here. Those belong in the data model deliverable.
Include any object that has its own lifecycle, identity, and persistence
Do NOT include value objects (Money, Address) or enums
SDL Generation Rules
When generating SDL from a conversation or manifest:
Save to project root — always write the SDL file as solution.sdl.yaml in the project root directory (current working directory). Never place it inside architecture/, artifacts/, output/, or any other subfolder.
Always setsdlVersion: "1.1"
Infer architecture style:
Single backend → modular-monolith
2+ backends with separate concerns → microservices
All functions/lambdas → serverless
Include only sections with data — omit empty optional sections
Let normalizer handle defaults — do not manually set fields covered by the 15 normalization rules
Check the applicable v1.1 conditional rules mentally before outputting:
Cross-reference the rules from spec/SDL-v1.1.md when using v1.1 sections
At minimum, check service references, feature dependencies, component references, and compatibility constraints
If plugin workflows need explicit generation metadata, set artifacts.generate based on what the user needs. This is plugin metadata, not a universally required upstream v1.1 root section. For a full blueprint:
Use comments sparingly — only for non-obvious choices
Validate the output — ensure all required fields are present and enums are valid
Quote YAML-unsafe string values — any scalar value that starts with or contains a YAML special character MUST be wrapped in double quotes. Failure to quote these causes parse errors. Apply this rule to every string value you write:
Character / pattern
Why it breaks YAML
Example fix
Value starts with >
Interpreted as block scalar folding indicator
condition: ">5 failures in 5 min"
Value starts with |
Interpreted as block scalar literal indicator
format: "| pipe-delimited"
Value starts with { or [
Interpreted as inline mapping/sequence
config: "{key: val}"
Value starts with * or &
Interpreted as alias/anchor
ref: "*base"
Value starts with !
Interpreted as tag
type: "!important"
Value contains : (colon-space) anywhere
Parsed as a nested mapping key
trigger: "EventBridge Schedule (rate: 1 day)"
Value contains # (space-hash)
Everything after is treated as a comment
desc: "retry # times"
Value contains ' or "
May terminate the string early
Use double quotes and escape inner doubles as \"
Value is a bare true, false, yes, no, on, off, null
Coerced to boolean/null
flag: "true"
Value is a bare number that should be a string
Coerced to number
version: "1.0"
Practical checklist — before writing any string value, ask:
SDL Output Format
Output SDL as a YAML code block with triple-backtick yaml fencing. After the SDL, report the validation summary:
