sdd-mcp-server 3.5.0 → 4.0.0

package/skills/sdd-steering/SKILL.md

@@ -1,229 +1,31 @@
 ---
 name: sdd-steering
-description: Create project-specific steering documents for SDD workflow. Use when setting up project context, documenting technology stack, or establishing project conventions. Invoked via /sdd-steering.
+description: Create or update concise project steering from verified repository facts.
+disable-model-invocation: true
 ---
 
-# 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 |
+# Project Steering
 
 ## 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`:
-
-```markdown
-# 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`:
-
-```markdown
-# 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
+1. Inspect manifests, source layout, build/test configuration, existing documentation, and current `.spec/steering/`.
+2. Distinguish verified facts from assumptions. Do not invent commands, versions, architecture, users, or conventions.
+3. Create or update:
+   - `product.md`: purpose, users, capabilities, boundaries;
+   - `tech.md`: languages, versions, dependencies, architecture, verified commands;
+   - `structure.md`: directory roles, naming, module boundaries, test locations.
+4. Preserve user-authored guidance and unrelated sections. In update mode, merge precise changes rather than replacing the whole steering tree.
+5. Keep guidance project-specific, actionable, non-secret, and concise. Preserve mandatory security guidance; never copy credentials, private environment values, or generated output.
+6. Validate every documented path and command against the repository; report uncertain facts as unresolved rather than guessing.
 
-### 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
+## Specialist Delegation
 
-- [ ] 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
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only verified project facts, existing conventions, requested scope, and unresolved decisions. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If the advisor or routed model is unavailable, record one fallback and continue in the parent without retrying or selecting a generic child. Where a native per-turn model override applies, execute in this turn.
 
-## Notes
+## Output
 
-- 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
+Return affected steering paths, source evidence used, validation performed, preserved user content, and unresolved blockers.
 
-## Specialist Delegation
+## Optional Reference
 
-When the host supports subagents, delegate this phase to the `planner` role with a compact handoff containing only the project facts, conventions, constraints, and requested steering scope. Wait for the specialist and then integrate its result into the current workflow. If specialist delegation is unavailable, state the fallback and continue in the current agent.
+Read [REFERENCE.md](REFERENCE.md) only for document templates or the extended validation checklist.

package/skills/sdd-steering-custom/REFERENCE.md

@@ -0,0 +1,27 @@
+# Custom Steering Reference
+
+Read only for templates or scope examples.
+
+## Template
+
+```markdown
+# Topic
+## Purpose
+Why this guidance exists.
+## Scope
+Included and excluded files or workflows.
+## Rules
+Actionable MUST/SHOULD guidance with rationale.
+## Exceptions
+Bounded exceptions and approval path.
+## Verification
+How a maintainer proves compliance.
+```
+
+## Scope Examples
+
+- Always: a repository-wide legal or safety constraint that applies to every task.
+- Conditional: test conventions for `**/*.test.ts` and `**/*.spec.ts`; API rules for `src/api/**/*`.
+- Manual: release procedure, rare migration playbook, or domain glossary.
+
+Use forward-slash globs and test both matching and near-miss paths. Avoid a broad `**/*` conditional scope when manual inclusion is honest. A custom file supplements rather than contradicts mandatory security or workflow gates. Examples should use synthetic values and contain no live credentials or private endpoints.

package/skills/sdd-steering-custom/SKILL.md

@@ -1,215 +1,31 @@
 ---
 name: sdd-steering-custom
-description: Create custom steering documents for specialized contexts. Use when you need domain-specific guidance for particular file types, modules, or workflows. Invoked via /sdd-steering-custom.
+description: Define scoped custom steering for a verified project convention or domain.
+disable-model-invocation: true
 ---
 
-# SDD Custom Steering Document Creation
+# Custom Steering
 
-Create specialized steering documents that provide context-specific guidance beyond the standard product/tech/structure documents.
+## Required Workflow
 
-## When to Use Custom Steering
+1. Define the missing guidance, its audience, and why standard steering is insufficient.
+2. Accept `fileName` only as a basename ending in `.md`; reject separators, absolute paths, traversal, control characters, and non-Markdown names.
+3. Choose the narrowest inclusion mode:
+   - always for genuinely universal project facts;
+   - conditional with explicit file globs;
+   - manual for rare or specialized guidance.
+4. Write purpose, scope, actionable rules, exceptions, and verification steps. Use examples only when they prevent ambiguity.
+5. Preserve user-authored content during updates. Never overwrite unrelated steering or weaken mandatory security guidance.
+6. Validate conditional globs against intended and unintended paths. Keep secrets and private environment values out of steering.
 
-Custom steering is useful for:
-- **Domain-specific rules**: API design, database conventions
-- **File-type guidance**: Test patterns, component standards
-- **Workflow processes**: PR reviews, deployment procedures
-- **Team conventions**: Code review standards, documentation rules
-
-## Inclusion Modes
-
-Custom steering documents can be loaded in three ways:
-
-| Mode | Behavior | Use Case |
-|------|----------|----------|
-| **ALWAYS** | Loaded in every AI interaction | Core conventions, critical rules |
-| **CONDITIONAL** | Loaded when file patterns match | Test-specific, API-specific rules |
-| **MANUAL** | Referenced with `@filename.md` | Rarely needed, specialized contexts |
-
-## Workflow
-
-### Step 1: Identify the Need
-
-Ask yourself:
-- What specialized context is missing?
-- When should this guidance apply?
-- Is this project-wide or context-specific?
-
-### Step 2: Choose Inclusion Mode
-
-```
-Is this guidance ALWAYS relevant?
-├── YES → Use ALWAYS mode
-│
-└── NO → Is it relevant for specific file types?
-         ├── YES → Use CONDITIONAL mode with patterns
-         │         Examples: *.test.ts, src/api/**/*
-         │
-         └── NO → Use MANUAL mode
-                  Reference with @filename.md when needed
-```
-
-### Step 3: Create Document
-
-Save to `.spec/steering/{filename}.md`:
-
-```markdown
-# {Topic Name}
-
-## Purpose
-{Why this steering document exists}
-
-## Scope
-{When this guidance applies}
-
-## Guidelines
-
-### Guideline 1: {Name}
-{Detailed guidance}
-
-**Do:**
-- {Good practice}
-
-**Don't:**
-- {Anti-pattern}
-
-### Guideline 2: {Name}
-{Detailed guidance}
-
-## Examples
-
-### Good Example
-```{language}
-{Code showing good practice}
-```
-
-### Bad Example
-```{language}
-// DON'T: {explanation}
-{Code showing anti-pattern}
-```
-
-## Checklist
-- [ ] {Verification item 1}
-- [ ] {Verification item 2}
-
----
-<!-- Steering Metadata -->
-Inclusion Mode: {ALWAYS | CONDITIONAL | MANUAL}
-File Patterns: {patterns for CONDITIONAL mode}
-Created: {date}
-```
-
-## Common Custom Steering Documents
-
-### API Design Standards
-```markdown
-# API Design Standards
-
-## Inclusion
-Mode: CONDITIONAL
-Patterns: src/api/**/*.ts, src/routes/**/*.ts
-
-## Guidelines
-
-### RESTful Conventions
-- Use plural nouns for resources: `/users`, not `/user`
-- Use HTTP methods correctly: GET (read), POST (create), PUT (update), DELETE (remove)
-- Return appropriate status codes
-
-### Request/Response Format
-- Use JSON for request/response bodies
-- Include `Content-Type: application/json` header
-- Wrap responses in consistent envelope
-```
-
-### Test Patterns
-```markdown
-# Test Patterns
-
-## Inclusion
-Mode: CONDITIONAL
-Patterns: **/*.test.ts, **/*.spec.ts
-
-## Guidelines
-
-### Arrange-Act-Assert
-Every test should follow:
-1. **Arrange**: Set up test data and mocks
-2. **Act**: Execute the code under test
-3. **Assert**: Verify the results
-
-### Naming Convention
-`describe('{Class/Function}', () => {`
-`  it('should {expected behavior} when {condition}', () => {`
-```
-
-### Component Standards
-```markdown
-# Component Standards
-
-## Inclusion
-Mode: CONDITIONAL
-Patterns: src/components/**/*.tsx
-
-## Guidelines
-
-### Component Structure
-1. Imports (external, internal, types)
-2. Type definitions
-3. Component function
-4. Helper functions
-5. Exports
-```
-
-### Database Conventions
-```markdown
-# Database Conventions
-
-## Inclusion
-Mode: CONDITIONAL
-Patterns: src/db/**/*.ts, **/migrations/**/*
-
-## Guidelines
-
-### Table Naming
-- Use snake_case: `user_accounts`
-- Use plural: `orders`, not `order`
-- Prefix with domain: `auth_sessions`
-
-### Column Naming
-- Use snake_case: `created_at`
-- Foreign keys: `{table}_id`
-- Booleans: `is_active`, `has_access`
-```
-
-## File Pattern Syntax
-
-Patterns use glob syntax:
-
-| Pattern | Matches |
-|---------|---------|
-| `*.test.ts` | All test files in current dir |
-| `**/*.test.ts` | All test files recursively |
-| `src/api/**/*` | All files in api directory tree |
-| `*.{ts,tsx}` | TypeScript and TSX files |
-| `!node_modules/**` | Exclude node_modules |
-
-## MCP Tool Integration
+## Specialist Delegation
 
-Custom steering documents are managed manually. After creating:
-1. Save to `.spec/steering/{name}.md`
-2. Verify file patterns work as expected
-3. Reference in AGENTS.md/CLAUDE.md if needed
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only domain facts, intended file scope, project constraints, and output contract. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If the advisor or routed model is unavailable, record one fallback and continue in the parent without retrying or selecting a generic child. Where a native per-turn model override applies, execute in this turn.
 
-## Quality Checklist
+## Output
 
-- [ ] Purpose is clearly stated
-- [ ] Inclusion mode is appropriate
-- [ ] File patterns are specific (for CONDITIONAL)
-- [ ] Guidelines are actionable
-- [ ] Examples show good and bad practices
-- [ ] Checklist for verification included
+Return the contained path, inclusion mode/globs, evidence used, validation results, preserved user content, and blockers.
 
-## Specialist Delegation
+## Optional Reference
 
-When the host supports subagents, delegate this phase to the `planner` role with a compact handoff containing only the specialized domain, file scope, project constraints, and requested steering outcome. Wait for the specialist and then integrate its result into the current workflow. If specialist delegation is unavailable, state the fallback and continue in the current agent.
+Read [REFERENCE.md](REFERENCE.md) only for templates, glob examples, or sample domain steering.

package/skills/sdd-tasks/REFERENCE.md

@@ -0,0 +1,25 @@
+# Task Planning Reference
+
+Read only for formatting and decomposition help.
+
+## Task Template
+
+```markdown
+### N.M Outcome
+Affected artifacts:
+Requirements/design traceability:
+Dependencies:
+RED: focused failing behavior test and command
+GREEN: smallest complete behavior
+REFACTOR: bounded cleanup
+Acceptance criteria:
+Verification:
+```
+
+## Decomposition
+
+Prefer a vertical behavior slice over separate “write all tests” and “write all code” phases. Split when a task has distinct observable outcomes, ownership boundaries, or independently verifiable failure modes. Merge tasks that would otherwise require a serial handoff with no standalone value. Mark concurrency only when slices do not edit the same contract or require one another's output.
+
+## Checklist
+
+Every requirement and design component is covered; dependencies form an acyclic order; each behavioral task begins with RED; edge/error/security/migration scenarios appear where relevant; acceptance criteria are measurable; optional test-case review is explicit; no task is merely “finish”, “wire up”, or “add tests”; and approval remains a separate user-visible gate.