Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

Specialists are pre-built convention packs that add domain expertise to the SDD workflow. They install as .md files into openspec/steering/ and are read automatically by /sdd-apply, /sdd-audit, and /sdd-verify. No new agents, no new phases — same workflow, more knowledge.

​
Available specialists

Each specialist ships with a manifest.yaml that declares its name, scope, and severity. The table below is drawn directly from those manifests.
SpecialistSeverityWhat it adds
accessibilityImportantWCAG-aware accessibility advisor — semantic HTML, ARIA, keyboard navigation, contrast, screen reader support. For projects with user-facing UI.
anti-overengineeringImportantDetects premature abstractions, unnecessary patterns, and speculative design. Advises all agents to keep code simple and proportional to the actual problem.
async-nodeCritical / ImportantNode.js async/concurrency advisor — async/await correctness, unhandled rejections, child_process safety, stream handling, and timeout discipline for Node.js backends.
clean-archImportantClean architecture advisor — enforces domain/application/infrastructure layer separation, dependency inversion, and port/adapter isolation so business logic never depends on frameworks or external services.
llmImportantLLM integration advisor — prompt construction, response validation, context management, prompt injection prevention, and model selection for projects that call Claude or other LLMs.
nodejs-patternsImportantNode.js performance and functional design advisor — event loop awareness, immutability, pure functions, no shared mutable state, stream backpressure, and worker threads for CPU-bound work.
observabilityImportantObservability advisor — structured logging, log levels, correlation IDs, what to log and what never to log, and how to trace async operations across pipeline phases.
performanceImportantPrevents common performance pitfalls — N+1 queries, unbounded data loading, missing pagination, unnecessary computation. Not premature optimization, just avoiding known traps.
readabilityImportantEnforces descriptive naming, clear structure, and code that reads like prose. No abbreviations, no clever tricks, no implicit behavior.
result-patternImportantResult/Either monad advisor — models expected errors as values, reserves try/catch for infrastructure boundaries, and eliminates implicit throws from domain and application code.
securityCriticalOWASP-aware security advisor — injection prevention, authentication, secrets management, input validation, and secure defaults. Classifies vulnerabilities as Critical.
tddCriticalEnforces Test-Driven Development — tests are written BEFORE implementation. Changes task ordering (test first, code second) and prevents code without a failing test.
testingImportantExpert in test design — proper test doubles, no redundant tests, behavior-focused assertions. Advises sdd-apply and sdd-verify to write tests that are maintainable and meaningful.

​
Installing specialists

Run install-specialist.sh from the root of the sdd-skills repository. The script reads specialists/*/manifest.yaml and copies each specialist’s .md convention files into your project’s openspec/steering/ directory. 
./install-specialist.sh                        # list available specialists
./install-specialist.sh anti-overengineering    # install one
./install-specialist.sh --all                   # install all
./install-specialist.sh --installed             # list installed
./install-specialist.sh --remove testing        # remove one
Once a convention file lands in openspec/steering/, every subsequent skill invocation picks it up automatically — there is nothing else to configure. To remove a specialist and stop applying its rules, use --remove.
openspec/steering/ must already exist before you run the installer. If it doesn’t, run /sdd-init first to create the full steering scaffold.

​
How specialists integrate

​
Selective loading

Skills load only the specialist files that are relevant to the current task. For example:
  • conventions-testing.md is loaded only when the task touches test files.
  • conventions-security.md is loaded only when the task touches authentication, API handlers, or input-processing code.
  • conventions-simplicity.md (anti-overengineering) applies universally because its applies_to field is all.
This keeps context tight and avoids sending irrelevant rules to the model on every invocation.

​
RFC 2119 severity levels

Specialists use the same MUST / MUST NOT / SHOULD / SHOULD NOT / MAY levels as your project’s own conventions.md. Rules marked MUST are enforced as hard requirements; rules marked SHOULD are strong recommendations with room for justified exceptions.

​
How violations are classified

Critical

Blocks the PR. Applies to security and tdd violations. There is no acceptable level of known security risk, and code without a preceding failing test must be rewritten.

Important

Logged as technical debt. Most specialists operate at this level. The task can complete, but the finding must be addressed before the change is considered production-ready.

Minor

Stylistic or cosmetic. Logged for awareness; does not block progress. Common in readability and anti-overengineering at the MAY level.

​
Specialist deep-dive: security

The security specialist (conventions-security.md) covers the OWASP Top 10 and classifies all findings as Critical — meaning they block PRs. It is the only specialist that applies equally to every project regardless of language or framework. A sample of rules from the file: 
- **MUST** use parameterized queries or ORM methods for all database operations.
  Never concatenate user input into SQL strings.
- **MUST** use templating engines with auto-escaping for HTML output.
  Never insert user input into HTML via string concatenation.
- **MUST NOT** use `eval()`, `new Function()`, or equivalent dynamic code
  execution with user-controlled input.

- **MUST NOT** hardcode secrets (API keys, passwords, tokens, connection strings)
  in source code, config files, or comments.
- **MUST** read secrets from environment variables or a secrets manager.
- **MUST NOT** log secrets, tokens, or credentials at any log level.
- **MUST** add sensitive files (`.env`, `*.pem`, `*.key`, `credentials.*`) to
  `.gitignore` before first commit.

- **MUST** validate all input at system boundaries (HTTP handlers, CLI parsers,
  message consumers). Never trust data from external sources.
- **MUST** validate type, format, length, and range — not just presence.
- **MUST** reject unexpected fields in request bodies (allowlist, not denylist).
- **MUST NOT** rely solely on client-side validation. Server-side validation is
  the authority.
The file ends with a “How to detect violations” section that gives /sdd-audit a concrete checklist: string concatenation in SQL/HTML/shell, hardcoded secrets, missing input validation on HTTP handlers, SELECT * results returned directly to clients, and so on.

​
Specialist deep-dive: tdd

The tdd specialist (conventions-tdd.md) is the only specialist that changes the structure of the workflow itself — it rewrites how /sdd-tasks orders its output. Normal task ordering (without tdd): 
- [ ] **T01** Create `src/middleware/rate-limit.js` — implement rate limit middleware
- [ ] **T02** Add tests for rate limit middleware
Task ordering with tdd active: 
- [ ] **T01** Create `test/rate-limit.test.js` — test: returns 429 when limit exceeded
- [ ] **T02** Create `src/middleware/rate-limit.js` — implement rate limit middleware (make T01 pass)
- [ ] **T03** Create `test/rate-limit-config.test.js` — test: reads limit from config
- [ ] **T04** Modify `src/middleware/rate-limit.js` — add configurable limits (make T03 pass)
Tests and implementation are interleaved as adjacent pairs — never batched apart. The spec also governs /sdd-apply directly:
  • The test MUST run and fail (Red) before any implementation code is written.
  • Only the minimum code to make the test pass is written (Green).
  • All tests run after each implementation to verify no regressions.
  • New behavior during refactoring requires a new Red test first.
TDD violations are classified as Critical: code without a preceding failing test must be rewritten using the cycle.
Combining specialists: Start with security for any project that handles user data — it costs nothing and prevents the most expensive bugs. Add tdd for critical business logic where correctness is non-negotiable. Add readability for team projects where the bottleneck is code review speed, not feature velocity.

Build docs developers (and LLMs) love

Get started for freeTalk to us