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.

Steering files are the project-specific context that makes SDD skills work correctly for your project. They live in openspec/steering/ and are generated by /sdd-init. Skills like /sdd-apply are generic — they work with any language or framework — but to write correct code the AI needs to know your testing framework, architectural patterns, naming conventions, and commit format. Steering files provide this context. Without them, /sdd-apply refuses to start.

​
The 7 steering files

The most important steering file. It uses RFC 2119 severity levels (MUST / MUST NOT / SHOULD / MAY) to define rules that, if broken, would fail a PR review. Loaded by /sdd-apply before every implementation and by /sdd-audit when checking code quality.
# Conventions: My Project

> Rules that cause PR review failures. RFC 2119: MUST / MUST NOT / SHOULD / MAY.

## Python -- Imports
- **MUST** use `from __future__ import annotations` in all modules -- forward refs

## Architecture -- Layers
- **MUST NOT** inject Repository directly into handlers -- use via use case interfaces
- **SHOULD** keep handlers under 50 lines

## Tests -- Patterns
- **MUST** use `pytest-asyncio` with `asyncio_mode = "auto"`
- **MUST NOT** mock the database in integration tests
Starts empty after /sdd-init. Grows automatically during /sdd-apply sessions as the AI learns from corrections. Rules are recorded in RFC 2119 format with the reason and date they were established.
# Project Rules: My Project

## Style
- **MUST** use single quotes for strings -- user preference established 2026-03-05

## Tests
- **MUST** use `factory_boy` for test fixtures -- established after T03 correction
Describes what the project is, who it is for, and where its boundaries are. Helps the AI understand whether a proposed change is in scope and how it fits the product’s purpose.
# Product: My Project

## What it builds
A web app where users can book parking spaces in real time.

## For whom
End users via browser and mobile app.

## Bounded context
Does NOT handle payments -- that's a separate system.
Documents the language, runtime, key dependencies, and the commands used to run the project in each environment. Skills read this to know which test runner to invoke and which tools are available.
# Tech Stack: My Project

## Language & runtime
- Python 3.12
- FastAPI 0.110

## Key dependencies
- SQLAlchemy: ORM
- Alembic: migrations
- pytest: testing

## Environments
- Dev: `uv run fastapi dev`
- Test: `uv run pytest`
Maps the directory structure to architectural layers and responsibilities. Prevents the AI from putting code in the wrong layer and makes it easy to understand where a new file should live.
# Structure: My Project

## Layers & responsibilities

| Layer | Directory | Responsibility |
|-------|-----------|----------------|
| API | `src/api/` | HTTP handlers, request validation |
| Domain | `src/domain/` | Business logic, entities |
| Infra | `src/infra/` | Database, external services |
Lists available MCP servers and CLI tools with their versions. Skills use this to decide which tools to call during exploration, verification, and archiving.
# Environment: My Project

## Available MCPs
- context7: available
- github: available

## CLI tools
- git: 2.44
- gh: available
- docker: available
- uv: 0.5.x
The entry point loaded first by all skills. Points to every other steering file and provides a summary of the stack and architecture so skills can orient quickly before deciding what else to read.
## Quick reference
- **Stack**: Python + FastAPI
- **Architecture**: Hexagonal
- **Tests**: pytest, TDD for critical logic

## Steering files (read before implementing)
- `openspec/steering/conventions.md` -- architectural rules
- `openspec/steering/project-rules.md` -- granular rules (grows)
- `openspec/steering/tech.md` -- stack details
- `openspec/steering/structure.md` -- directory layout

​
How project-rules.md grows

project-rules.md is the only steering file that changes automatically during normal workflow use. It grows whenever the AI learns a project-specific preference from a correction:
TriggerBehavior
User says “always use X” or “remember this”Rule saved immediately to project-rules.md
User overrides the AI’s choice during /sdd-applyAI asks “save as rule?” before continuing
Same correction happens twice in the same projectSaved automatically without asking
All saved rules use RFC 2119 format with the reason and context: **MUST** use X — reason from correction context.

​
Updating steering

Steering files are plain markdown — you can edit them directly at any time. Skills pick up changes on the next invocation. For detecting drift after major refactors or convention changes, use the sync command: 
/sdd-steer sync
This compares current conventions against the codebase, existing skills, and any MEMORY.md file, then presents proposed additions, updates, and removals for your confirmation. Nothing is auto-applied — you review each proposed change. project-rules.md also grows automatically during /sdd-apply sessions when the AI learns from corrections, so no manual intervention is needed for that file.

​
Specialists

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

​
Available specialists

SpecialistSeverityWhat it adds
accessibilityImportantWCAG 2.1 AA — semantic HTML, ARIA, keyboard navigation, contrast, screen reader support. For projects with user-facing UI.
anti-overengineeringImportantRules against premature abstractions, unnecessary patterns, and speculative design. Applies to all projects.
async-nodeImportantNode.js async/concurrency — async/await correctness, unhandled rejections, child_process safety, stream handling, and timeout discipline.
clean-archImportantClean architecture — domain/application/infrastructure layer separation, dependency inversion, port/adapter isolation. For TypeScript projects.
llmImportantLLM integration — prompt construction, response validation, context management, prompt injection prevention, and model selection. For projects calling Claude or other LLMs.
nodejs-patternsImportantNode.js performance and functional design — event loop awareness, immutability, pure functions, no shared mutable state, stream backpressure.
observabilityImportantStructured logging, log levels, correlation IDs, what to log and what never to log, and how to trace async operations.
performanceImportantN+1 prevention, pagination, async I/O, lazy loading, indexed queries. Not premature optimization — avoiding known traps.
readabilityImportantDescriptive naming, clear structure, guard clauses, no abbreviations, no clever tricks.
result-patternImportantResult/Either monad — models expected errors as values, reserves try/catch for infrastructure boundaries. For TypeScript projects.
securityCriticalOWASP top 10 — injection, auth, secrets, input validation, access control. Classifies violations as Critical.
tddCriticalEnforces Red/Green/Refactor cycle, tests written before implementation, changes task ordering (test before code).
testingImportantProper test doubles (stub vs mock vs fake), no redundant tests, behavior-focused assertions.

​
Installing a specialist

# From the sdd-skills repo:
./install-specialist.sh                        # list available
./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
This copies the specialist’s convention file(s) to openspec/steering/. Skills pick them up automatically on the next invocation. For a full overview of how specialists work and how to create a custom one, see Specialists.

Build docs developers (and LLMs) love

Get started for freeTalk to us