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.

/sdd-steer manages the openspec/steering/ files — the persistent project memory that every SDD skill reads before making decisions. It has three modes: bootstrap generates all steering files from scratch by reading the codebase and loaded skills; sync compares current conventions against the code and proposes targeted updates; report gives a read-only health analysis. Use it when starting a project without /sdd-init, after major refactors, or whenever conventions may have drifted.

​
Usage

/sdd-steer          # Bootstrap: generate all steering files from scratch
/sdd-steer sync     # Sync: detect drift and propose updates
/sdd-steer report   # Report: analyze steering health and coverage

​
Prerequisites

  • Architecture and code-quality skills for the project are loaded (or ready to load)
  • You are in the project root directory

​
Bootstrap mode

Bootstrap generates product.md, tech.md, structure.md, and conventions.md from scratch by reading the codebase. Use this when /sdd-init was not run or when the steering files need full regeneration.
1
Step 1 — Detect project and load skills
2
Detects the project from the working directory and loads the following skills in parallel:
3
  • {project}-architecture
  • {project}-code-quality
    • 4
    If openspec/steering/ already has content, it asks for confirmation before overwriting:
    5
    ⚠️  openspec/steering/ already has content.
Use `/sdd-steer sync` to update instead of overwriting.
Continue anyway? (y/n)
    6
    Step 2 — Explore codebase (read-only)
    7
    Reads in parallel:
    8
  • Directory structure (ls -la src/ or equivalent)
  • Config files (pyproject.toml, composer.json, package.json, etc.)
  • 2-3 representative files from each layer (handlers, controllers, entities, components)
  • MEMORY.md or equivalent project memory files, if available
  • openspec/specs/ to understand the documented domain
    • 9
    Step 3 — Generate product.md
    10
    Captures the project’s purpose, audience, and explicit boundaries:
    11
    # Product: {Project Name}

## What it builds
{1-2 paragraphs: purpose, domain, value}

## For whom
{users/systems that consume it}

## Bounded context
{system boundaries — what it does NOT do}
    12
    Step 4 — Generate tech.md
    13
    Records the full stack: language, runtime, framework, key dependencies, and how to run the project locally and in CI.
    14
    Step 5 — Generate structure.md
    15
    Documents the directory layout, the responsibilities of each layer, and the standard flow of a typical request or operation (as an ASCII diagram or prose description).
    16
    Step 6 — Generate conventions.md
    17
    The most valuable steering file. Derives conventions from three sources in priority order:
    18
  • Architecture/code-quality skills — most reliable source
  • Project MEMORY.md — patterns discovered in previous sessions
  • Existing code — empirical evidence (naming, structure, decorators)
    • 19
    Each rule is written in RFC 2119 format:
    20
    # Conventions: {Project}

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

## {Area} — {Sub-area}

- **MUST** {concrete rule} — {one-line reason}
- **MUST NOT** {concrete rule} — {one-line reason}
- **SHOULD** {concrete rule} — {one-line reason}
    21
    Aim for 5–15 rules covering the patterns that most often cause PR review failures. Derive areas from the stack (e.g., Imports, Framework patterns, Workers, Tests, Commits, Architecture layers).
    22
    Step 7 — Write files
    23
    Creates the openspec/steering/ directory and writes all four files. Prints a summary when done:
    24
    STEER COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files generated:
  openspec/steering/product.md
  openspec/steering/tech.md
  openspec/steering/structure.md
  openspec/steering/conventions.md ← {N} conventions documented

Next: /sdd-audit to verify the current codebase against these conventions.

    ​
    Sync mode

    /sdd-steer sync detects drift between the current conventions.md and three sources of truth, then presents a targeted set of proposed changes for your review.
    1
    Step 1 — Read current state
    2
    Reads in parallel:
    3
  • openspec/steering/conventions.md (existing)
  • Architecture/code-quality skills for the project
  • Project MEMORY.md
    • 4
    Step 2 — Detect drift
    5
    Compares the three sources and identifies:
    6
  • Conventions present in the skills that are missing from conventions.md
  • Conventions in conventions.md that no longer reflect the current code
  • New patterns that have appeared in recent commits or MEMORY.md
    • 7
    Step 3 — Propose changes
    8
    Presents specific, line-level proposals using + (add), ~ (update), and - (remove) prefixes:
    9
    DRIFT DETECTED in conventions.md:

ADD (new conventions found):
+ ## Signals
+   - MUST use signal() for reactive state

UPDATE (outdated convention):
~ OLD: MUST NOT use async/await directly
~ NEW: MUST use async/await with asyncio mode

REMOVE (no longer applies):
- MUST support Python 3.9 (min is now 3.13)

Apply these changes? (y/n/select)
    Sync mode never auto-applies changes. It always presents the full diff and waits for your confirmation — or lets you select individual changes with select — before modifying any file.

    ​
    Report mode

    /sdd-steer report is a read-only health check. No files are modified. It analyzes:
    1. conventions.md — rule counts by RFC 2119 level (MUST / SHOULD / MAY) and by area
    2. project-rules.md — rules accumulated from user corrections since bootstrap
    3. Archived changes — how many completed change cycles live in openspec/changes/archive/
    4. Drift indicators — whether tech.md versions match what the project currently uses (e.g., package.json has a different Node version)
    Example output: 
    STEERING REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Conventions (conventions.md):
  MUST:   12 rules across 4 areas
  SHOULD: 6 rules across 3 areas
  MAY:    2 rules

Project rules (project-rules.md):
  Total:  5 rules
  Style:  2 | Tests: 1 | Architecture: 2

History:
  Archived changes: 8
  Domains with canonical specs: 3

Health:
  ✓ conventions.md — up to date
  ⚠ tech.md — Node version mismatch (file: 18, detected: 22)
  ✓ structure.md — matches current layout
  ✗ project-rules.md — empty sections (Style, Tests)

Suggestions:
  - Run /sdd-steer sync to update tech.md
  - Consider adding rules to empty sections after next code review

    ​
    Output

    ArtifactPathMode
    Product definitionopenspec/steering/product.mdBootstrap
    Tech stack referenceopenspec/steering/tech.mdBootstrap
    Directory layoutopenspec/steering/structure.mdBootstrap
    Coding conventionsopenspec/steering/conventions.mdBootstrap / Sync
    Accumulated project rulesopenspec/steering/project-rules.mdBootstrap

    ​
    Skill metadata

    FieldValue
    namesdd-steer
    model_hintsonnet
    requiresopenspec/steering/
    producesopenspec/steering/conventions.md, openspec/steering/project-rules.md, openspec/steering/tech.md, openspec/steering/structure.md, openspec/steering/product.md

    ​
    Next steps

    • /sdd-audit — verify the codebase against newly generated or updated conventions
    • /sdd-new "description" — start a new change with up-to-date steering context loaded

    Build docs developers (and LLMs) love

    Get started for freeTalk to us