---
description: Manage {{SDD_DIR}}/steering/ as persistent project knowledge
allowed-tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
---

# SDD Steering Management

<background_information>
**Role**: Maintain `{{SDD_DIR}}/steering/` as the living memory of the project.

**Mission**:
- **Bootstrap**: Generate core steering files from the codebase the first time this command runs
- **Sync**: Keep steering aligned with the codebase as it evolves
- **Preserve**: User customizations take precedence — all updates are strictly additive

**Success Criteria**:
- Steering captures architectural patterns and conventions, not exhaustive inventories
- Drift between code and steering is detected and reported
- All files in `{{SDD_DIR}}/steering/*.md` are treated as first-class project memory, whether core or custom
</background_information>

<instructions>
## Mode Detection

Inspect `{{SDD_DIR}}/steering/`:

**Bootstrap Mode**: Directory is empty, or one or more of the three core files (`product.md`, `tech.md`, `structure.md`) is missing.
**Sync Mode**: All three core files are present.

---

## Bootstrap Flow

1. Read templates from `{{SDD_DIR}}/settings/templates/steering/`
2. Analyze the codebase on demand (just-in-time):
   - Glob for source files, configuration, and entry points
   - Read README files, package manifests, lock files, and build configs
   - Grep for recurring patterns (naming, imports, error handling, test conventions)
3. Extract patterns — not inventories:
   - **product.md**: Core purpose, user value, primary capabilities
   - **tech.md**: Key frameworks, language standards, architectural decisions, toolchain conventions
   - **structure.md**: Directory organization principles, module naming, import strategies
4. Write the three steering files following their templates
5. Load `{{SDD_DIR}}/settings/rules/steering-principles.md` to validate granularity and content rules
6. Present a summary for human review and approval before treating as authoritative

**Focus**: Patterns that guide future decisions, not catalogs of what exists today.

---

## Sync Flow

1. Load all existing steering files: `{{SDD_DIR}}/steering/*.md`
2. Analyze the codebase just-in-time for meaningful changes
3. Detect and classify drift:
   - **Steering references code that no longer exists** → Flag as a warning
   - **Code introduces new patterns not in steering** → Propose an additive update
   - **Custom steering files** → Check continued relevance; report if context has changed
4. Propose and apply updates — additive only; never delete user content
5. Report: which files changed, what code drift was found, and any recommendations

**Update Philosophy**: Add content, do not replace it. User-authored sections are sacred.

---

## Granularity Principle

From `{{SDD_DIR}}/settings/rules/steering-principles.md`:

> "If new code follows existing patterns, steering should not need updating."

Capture the pattern, not the instance. A description of how components are organized is more valuable than a list of every component.

**Example — avoid this**:
List every file with its one-line purpose

**Example — prefer this**:
Describe the organizational principle with one representative example
</instructions>

## Tool Guidance

- **Glob**: Locate source files, configuration, and structural artifacts
- **Read**: Load steering docs, package manifests, READMEs, and key source files
- **Grep**: Identify recurring patterns across the codebase
- **LS**: Understand directory structure without reading every file

**Just-In-Time Strategy**: Fetch only what is needed to answer the current question. Avoid reading the entire codebase upfront.

## Output Description

Chat summary only — files are written directly.

### Bootstrap Output:
```
Steering Created

Generated:
- product.md: [One-line description of what was captured]
- tech.md: [Key stack and conventions documented]
- structure.md: [Organization patterns recorded]

Review these files and approve as the project's Source of Truth.
```

### Sync Output:
```
Steering Updated

Changes Made:
- tech.md: Updated framework version reference
- structure.md: Added new module organization pattern

Code Drift Detected:
- Import convention in src/api/ does not match steering description

Recommendations:
- Consider creating api-standards.md for REST conventions
```

## Examples

### Bootstrap Scenario
**Context**: No steering files exist; project is a React TypeScript monorepo.
**Output**: Three files capturing "feature-first folder structure", "TypeScript strict mode", "React 19 with hooks pattern"

### Sync Scenario
**Context**: A new `/workers` directory appeared since the last sync.
**Output**: `structure.md` updated with background worker pattern; deviation in import style flagged; `deployment.md` suggested for worker configuration

## Safety & Fallback

- **Secrets**: Never write API keys, passwords, database credentials, or internal network addresses into any steering file — see `steering-principles.md` for the full security checklist
- **Ambiguous State**: If the codebase contradicts what steering says, report both states and ask the user to resolve the discrepancy
- **Destructive Changes**: When in doubt, add rather than replace. User sections are always preserved.

## Notes

- All `{{SDD_DIR}}/steering/*.md` files are loaded as project memory by every SDD command
- Templates and principles live in `{{SDD_DIR}}/settings/` and are customizable
- The goal is decision guidance, not documentation completeness
- **Golden Rule**: Code that follows existing patterns should not require a steering update
- Do not document agent-specific tooling directories (e.g., `.cursor/`, `.gemini/`, `.claude/`)
- `{{SDD_DIR}}/settings/` content is internal metadata and must not appear in steering files
- Light references to `{{SDD_DIR}}/specs/` and `{{SDD_DIR}}/steering/` are acceptable; avoid referencing other `.sdd/` paths
