sdl-author

# SDL Author ## Overview Use this skill to turn architecture intent into valid SDL v1.1. Favor small, schema-valid SDL over comprehensive-looking YAML that invents facts. ## Reference Loading 1. If working in the `solution-definition-language` repo, load `reference/ai-authoring.md` first. It is the compact machine reference. 2. For deeper contract questions, load `spec/SDL-v1.1.md` or `reference/canonical-contract.md`. 3. If those repo files are unavailable, load `references/authoring-fast-path.md` from this skill. 4. For unclear input mapping, load `references/input-mapping.md`. Do not use stale README snippets, old `.d.ts` files, or legacy SDL examples as the source of truth. ## Workflow 1. Extract facts from the input. - Identify product name, purpose, stage, architecture style, projects, database, auth, deployment, integrations, compliance, SLOs, and generated artifacts. - Separate explicit facts from assumptions. Put uncertain details in review notes or `x-*` metadata, not stable schema fields. 2. Draft the minimum valid SDL first. - Always include `sdlVersion`, `solution`, `architecture`, and `data`. - Add optional sections only when the input provides real facts or the user asks for a richer architecture baseline. 3. Use canonical SDL v1.1 values exactly. - Preserve enum casing and hyphenation, such as `MVP`, `modular-monolith`, `python-fastapi`, and `github-actions`. - Translate common aliases to canonical values before writing YAML. 4. Avoid unsupported schema fields. - Put custom metadata under `x-*` extension fields. - Do not invent non-`x-*` root sections. 5. Validate and repair. - Run `scripts/validate-sdl.mjs <file>` when a file exists. - If validation fails, fix the SDL and validate again. - Mention remaining warnings or assumptions in the final response. ## Authoring Rules - Prefer omit over guess. Missing optional sections are valid; unknown enum values are not. - Do not set normalizer-inferred fields unless the input explicitly requires an override. - If an optional section is present, include that section's required fields. - Use `features[]` as an array of objects. Do not group features by phase. - Use `contracts.apis[]`, not a top-level `contracts[]`. - Use `slos.services[]`, not a top-level `slos[]`. - Use `auth.strategy: oidc` with `auth.sessions.accessToken: jwt` when the input says JWT-based OIDC. - Use `x-*` keys for navigation patterns, UI notes, repo evidence, confidence, open questions, and source traceability. ## Output Shape When generating SDL for a user, provide: 1. The SDL YAML or the path to the created SDL file. 2. A short list of assumptions or review items. 3. Validation result, including command run and any warnings. When editing an existing SDL file, keep unrelated content intact and scope changes to the requested sections. ## Validation Script From this skill folder, use: ```bash node scripts/validate-sdl.mjs path/to/solution.sdl.yaml ``` Useful options: ```bash node scripts/validate-sdl.mjs path/to/solution.sdl.yaml --repo /path/to/solution-definition-language node scripts/validate-sdl.mjs path/to/solution.sdl.yaml --json ``` The script looks for the SDL core package in the current repo and uses its parser, validator, semantic validator, resolver, and normalizer when available.