yi-john-huang/sdd-steering

SDD Steering Document Generation

Generate project-specific steering documents that provide context and guidance for AI-assisted development.

What Are Steering Documents?

Steering documents are markdown files in .spec/steering/ that provide project-specific context to guide AI interactions. They describe YOUR project's unique characteristics.

Document Types

| Document | Purpose | Content | |----------|---------|---------| | product.md | Product context | Vision, users, features, goals | | tech.md | Technology stack | Languages, frameworks, tools, architecture | | structure.md | Project conventions | Directory structure, naming, patterns | | custom-*.md | Custom guidance | Specialized rules for specific contexts |

Workflow

Step 1: Analyze Project

Gather information from:

1. Project manifest - Dependencies and metadata (e.g., package.json, Cargo.toml, pyproject.toml, pom.xml, go.mod)
2. Directory structure - Folder organization
3. Existing code patterns - Naming conventions, architecture
4. Documentation - README, existing docs
5. Build configuration - Build tools, scripts, CI/CD

Step 2: Generate Product Steering

Create .spec/steering/product.md:

# Product Overview

## Description
{Project description from manifest or analysis}

## Vision
{Long-term product vision}

## Target Users
- **Primary:** {Main user persona}
- **Secondary:** {Other user types}

## Core Features
1. {Feature 1} - {Brief description}
2. {Feature 2} - {Brief description}

## Key Value Propositions
- {Value 1}
- {Value 2}

## Success Metrics
- {Metric 1}: {Target}
- {Metric 2}: {Target}

Step 3: Generate Tech Steering

Create .spec/steering/tech.md:

# Technology Overview

## Stack

### Language
- **Primary:** {e.g., TypeScript, Python, Go, Rust, Java}
- **Version:** {e.g., 5.x, 3.11, 1.21}
- **Runtime:** {if applicable, e.g., Node.js, JVM, .NET}

### Frameworks
- {Framework 1}: {Purpose}
- {Framework 2}: {Purpose}

### Key Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {dep1} | {version} | {why used} |

## Architecture

### Pattern
{e.g., Clean Architecture, MVC, Microservices, Hexagonal}

### Layers

┌─────────────────┐ │ Presentation │ Controllers, CLI, UI ├─────────────────┤ │ Application │ Services, Use Cases ├─────────────────┤ │ Domain │ Entities, Business Logic ├─────────────────┤ │ Infrastructure │ Database, External APIs └─────────────────┘

## Development Environment

### Prerequisites
- {Language runtime and version}
- {Package manager} (e.g., npm, pip, cargo, go mod, maven)

### Setup
```bash
# Clone and install dependencies
{package manager install command}

# Run development server
{dev server command}

Common Commands

| Command | Purpose | |---------|---------| | {install} | Install dependencies | | {dev} | Development server | | {build} | Production build | | {test} | Run tests | | {lint} | Code linting |

Quality Standards

• Test coverage: >= 80%
• Linting: {language-appropriate linter}
• Type checking: {if applicable}

### Step 4: Generate Structure Steering

Create `.spec/steering/structure.md`:

```markdown
# Project Structure

## Directory Layout

project-root/ ├── src/ # Source code │ ├── domain/ # Business logic │ ├── application/ # Use cases │ ├── infrastructure/ # External adapters │ └── {entry point} # Main entry point ├── tests/ # Test files ├── docs/ # Documentation └── {project manifest} # Dependencies/config

## Naming Conventions

### Files
| Type | Convention | Example |
|------|------------|---------|
| Components | {project convention} | `UserProfile.{ext}` |
| Services | {project convention} | `AuthService.{ext}` |
| Utilities | {project convention} | `format_date.{ext}` |
| Tests | {test convention} | `auth_test.{ext}` |
| Types/Interfaces | {project convention} | `user_types.{ext}` |

### Code
| Element | Convention | Example |
|---------|------------|---------|
| Classes/Types | PascalCase | `UserService` |
| Functions/Methods | {language convention} | `get_user_by_id` or `getUserById` |
| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
| Variables | {language convention} | `user_name` or `userName` |
| Interfaces | {project convention} | `UserRepository` or `IUserRepository` |

## Module Organization

### Import Order
1. Standard library / built-ins
2. External packages / dependencies
3. Internal modules (absolute paths)
4. Relative imports
5. Type/interface imports (if language separates them)

### Export Pattern
- Use barrel exports / index files where appropriate
- Named exports preferred over default (language-dependent)
- Public API exposed from domain layer

## Patterns

### Dependency Injection
{DI approach used, e.g., Inversify, manual}

### Error Handling
{Error handling pattern, e.g., Result types, exceptions}

### Logging
{Logging approach, e.g., structured logging}

Step 5: Create Directory

Ensure .spec/steering/ directory exists and save documents.

MCP Tool Integration

This skill generates documents manually. For automated analysis, the sdd-init MCP tool creates basic steering during project initialization.

Quality Checklist

• [ ] Product description is clear and specific
• [ ] Target users are well-defined
• [ ] Technology stack is accurately documented
• [ ] Directory structure matches actual project
• [ ] Naming conventions are consistent
• [ ] Development setup instructions are complete
• [ ] Key patterns are documented

Notes

• Steering documents are project-specific - they describe YOUR project
• Keep them updated as the project evolves
• Use custom steering for domain-specific rules
• Reference from AGENTS.md or CLAUDE.md in project root