Steering Files¶

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.

Why steering?¶

Skills like /sdd-apply are generic — they work with any language or framework. But to write correct code, the AI needs to know:

What testing framework to use
What architectural patterns to follow
What naming conventions apply
What commit format the project uses

Steering files provide this context. Without them, /sdd-apply refuses to start.

The files¶

`conventions.md` — Rules that cause PR failures¶

The most important steering file. Uses RFC 2119 severity levels:

# 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

This file is loaded by /sdd-apply before every implementation and by /sdd-audit when checking code quality.

`project-rules.md` — Rules that grow with the project¶

Starts empty. Grows when the user corrects the AI during implementation:

Trigger	Behavior
User says "always use X" or "remember this"	Saved immediately
User overrides the AI's choice	The AI asks "save as rule?"
Same correction happens twice	Saved automatically

# 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

`product.md` — What the project builds¶

# 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.

`tech.md` — Stack details¶

# 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`

`structure.md` — Directory layout and layers¶

# 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 |

`environment.md` — Available tools¶

# Environment: My Project

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

## CLI tools
- git: 2.44
- gh: available
- docker: available
- uv: 0.5.x

`project-skill.md` — Quick reference index¶

Points to all other steering files. Loaded first by skills to find what 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

Specialists — domain-specific advisors¶

Specialists are pre-built convention packs that add domain expertise to the workflow. They are .md files with 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¶

Specialist	Severity	What it adds
accessibility	Important	WCAG 2.1 AA — semantic HTML, ARIA, keyboard navigation, contrast, focus management
anti-overengineering	Important	Rules against premature abstractions, unnecessary patterns, speculative design
performance	Important	N+1 prevention, pagination, async I/O, lazy loading, indexed queries
readability	Important	Descriptive naming, clear structure, guard clauses, no abbreviations
security	Critical	OWASP top 10 — injection, auth, secrets, input validation, access control
tdd	Critical	Enforces Red/Green/Refactor cycle, changes task ordering (test before code)
testing	Important	Proper 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 convention files to openspec/steering/. Skills pick them up automatically on next invocation.

Creating a custom specialist¶

A specialist is a directory in specialists/{name}/ with two things:

1. manifest.yaml — metadata:

name: nodejs
description: Node.js expert — event loop, async patterns, streams, memory management
applies_to: ["node", "typescript"]
files:
  - conventions-nodejs.md → openspec/steering/conventions-nodejs.md

2. One or more .md files — conventions in RFC 2119 format:

# Specialist: Node.js

> Rules for Node.js-specific patterns and anti-patterns.
> Read by sdd-apply, sdd-audit, and sdd-verify.

## Event Loop
- **MUST NOT** use synchronous fs methods (readFileSync, writeFileSync)
- **MUST** use Promise.all() for independent async operations
- **SHOULD** use streams for data > 1MB

## Error handling
- **MUST** handle rejected promises — unhandled rejections crash Node 18+
- **MUST NOT** use try/catch around synchronous code that cannot throw

## How to detect violations
When reviewing code, flag:
1. Any import of a *Sync function from node:fs
2. Sequential awaits that could be parallelized
3. Large buffers created from file reads

Guidelines for writing specialist rules:

Use RFC 2119 levels (MUST/SHOULD/MAY) — same as conventions.md
Include a "How to detect violations" section for audit clarity
Classify violations as Important (quality goal) not Critical (hard gate)
Keep rules actionable: "MUST use X" is better than "consider using X"
Include the why after each rule — a one-line reason after the dash
Don't duplicate rules already in the project's conventions.md

Updating steering¶

After major changes¶

/sdd-steer sync

Detects drift between documented conventions and the current codebase. Shows proposed additions, updates, and removals. Does not auto-apply — you confirm each change.

Automatic growth¶

project-rules.md grows automatically during /sdd-apply sessions when the AI learns from corrections. No manual intervention needed.

Manual edits¶

Steering files are plain markdown. You can edit them directly at any time. Skills will pick up the changes on next invocation.