sdd-mcp-server 1.8.1 → 2.0.0

package/skills/sdd-steering/SKILL.md

@@ -0,0 +1,225 @@
+---
+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.
+---
+
+# 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`:
+
+```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
+
+### 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

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

@@ -0,0 +1,211 @@
+---
+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.
+---
+
+# SDD Custom Steering Document Creation
+
+Create specialized steering documents that provide context-specific guidance beyond the standard product/tech/structure documents.
+
+## When to Use Custom 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
+
+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
+
+## Quality Checklist
+
+- [ ] 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

package/skills/sdd-tasks/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: sdd-tasks
+description: Generate TDD task breakdown for SDD workflow. Use when breaking down design into implementable tasks with test-first approach. Invoked via /sdd-tasks <feature-name>.
+---
+
+# SDD Task Breakdown Generation
+
+Generate comprehensive TDD-based task breakdowns that translate approved designs into implementable work items.
+
+## Prerequisites
+
+Before generating tasks:
+1. Design must be generated using `/sdd-design`
+2. Design phase should be approved (use `sdd-approve design` MCP tool)
+3. Review the design document in `.spec/specs/{feature}/design.md`
+
+## Workflow
+
+### Step 1: Verify Prerequisites
+
+Use `sdd-status` MCP tool to verify:
+- `design.generated: true`
+- `design.approved: true` (recommended before tasks)
+
+### Step 2: Review Design
+
+1. Read `.spec/specs/{feature}/design.md`
+2. Identify all components to implement
+3. Note interfaces and data models
+4. Understand dependencies between components
+
+### Step 3: Apply TDD Workflow
+
+For each task, follow the Red-Green-Refactor cycle:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TDD CYCLE                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   1. RED    ──────>  Write failing test first              │
+│                      (Test describes expected behavior)     │
+│                                                             │
+│   2. GREEN  ──────>  Write minimal code to pass            │
+│                      (Just enough to make test green)       │
+│                                                             │
+│   3. REFACTOR ────>  Clean up, maintain tests passing      │
+│                      (Improve design without breaking)      │
+│                                                             │
+│   ─────────────────────────────────────────────────────    │
+│                      REPEAT                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Step 4: Apply Test Pyramid
+
+Structure tests following the 70/20/10 ratio:
+
+```
+                    ╱╲
+                   ╱  ╲
+                  ╱ E2E╲         10% - Critical user journeys
+                 ╱──────╲
+                ╱        ╲
+               ╱Integration╲    20% - Component interactions
+              ╱────────────╲
+             ╱              ╲
+            ╱   Unit Tests   ╲  70% - Individual functions
+           ╱──────────────────╲
+```
+
+| Level | Coverage | Scope | Speed |
+|-------|----------|-------|-------|
+| **Unit** | 70% | Single function/class | Fast (ms) |
+| **Integration** | 20% | Component interactions | Medium (s) |
+| **E2E** | 10% | Full user journeys | Slow (min) |
+
+### Step 5: Generate Task Breakdown
+
+Structure tasks hierarchically:
+
+```markdown
+# Tasks: {Feature Name}
+
+## Overview
+{Summary of implementation approach}
+
+## Task Groups
+
+### 1. {Component/Layer Name}
+
+#### 1.1 {Task Name}
+**Type:** Unit | Integration | E2E
+**Estimated Effort:** S | M | L | XL
+**Dependencies:** {Task IDs}
+
+**TDD Steps:**
+1. RED: Write test for {specific behavior}
+   ```typescript
+   describe('{Component}', () => {
+     it('should {expected behavior}', () => {
+       // Arrange
+       // Act
+       // Assert
+     });
+   });
+   ```
+2. GREEN: Implement {minimal solution}
+3. REFACTOR: {Specific improvements}
+
+**Acceptance Criteria:**
+- [ ] Test passes
+- [ ] Code coverage >= 80%
+- [ ] No lint errors
+
+#### 1.2 {Next Task}
+...
+
+### 2. {Next Component}
+...
+
+## Implementation Order
+
+```
+[1.1] ──> [1.2] ──> [2.1]
+              │
+              └──> [1.3] ──> [2.2]
+```
+
+## Definition of Done
+- [ ] All tests pass
+- [ ] Code coverage >= 80%
+- [ ] No lint/type errors
+- [ ] Code reviewed
+- [ ] Documentation updated
+```
+
+### Step 6: Task Sizing Guidelines
+
+| Size | Description | Test Count | Time |
+|------|-------------|------------|------|
+| **S** | Single function, 1-2 tests | 1-2 | < 1 hour |
+| **M** | Multiple functions, 3-5 tests | 3-5 | 1-4 hours |
+| **L** | Component with integration | 5-10 | 4-8 hours |
+| **XL** | Complex component, many edge cases | 10+ | 1-2 days |
+
+### Step 7: Test-First Task Template
+
+For each implementation task:
+
+```markdown
+#### Task {X.Y}: {Task Name}
+
+**Component:** {ComponentName}
+**Type:** Unit Test → Implementation
+
+**Test Scenarios:**
+1. Happy path: {Expected behavior when inputs are valid}
+2. Edge case: {Boundary conditions}
+3. Error case: {Invalid inputs, failures}
+
+**Test Code (RED):**
+```typescript
+import { {Component} } from './{component}';
+
+describe('{Component}', () => {
+  describe('{method}', () => {
+    it('should {happy path behavior}', async () => {
+      // Arrange
+      const input = { /* valid input */ };
+
+      // Act
+      const result = await component.method(input);
+
+      // Assert
+      expect(result).toEqual({ /* expected */ });
+    });
+
+    it('should throw when {error condition}', async () => {
+      // Arrange
+      const invalidInput = { /* invalid */ };
+
+      // Act & Assert
+      await expect(component.method(invalidInput))
+        .rejects.toThrow('{ErrorType}');
+    });
+  });
+});
+```
+
+**Implementation (GREEN):**
+{Brief description of minimal implementation}
+
+**Refactor:**
+- Extract {helper function} if needed
+- Apply {specific pattern}
+```
+
+### Step 8: Save and Execute
+
+1. Save tasks to `.spec/specs/{feature}/tasks.md`
+2. Use `sdd-approve tasks` MCP tool to mark phase complete
+3. Use `sdd-spec-impl` MCP tool to execute tasks with TDD
+
+## MCP Tool Integration
+
+| Tool | When to Use |
+|------|-------------|
+| `sdd-status` | Verify design phase complete |
+| `sdd-approve` | Mark tasks phase as approved |
+| `sdd-spec-impl` | Execute tasks using TDD methodology |
+| `sdd-quality-check` | Validate code quality during implementation |
+
+## Quality Checklist
+
+- [ ] All design components have corresponding tasks
+- [ ] Tasks follow TDD (test first)
+- [ ] Test pyramid ratio maintained (70/20/10)
+- [ ] Dependencies between tasks are clear
+- [ ] Each task has specific acceptance criteria
+- [ ] Tasks are sized appropriately (avoid XL when possible)
+- [ ] Implementation order respects dependencies
+- [ ] Definition of Done is clear
+
+## Common Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Test After** | Missing edge cases | Always write test first |
+| **Ice Cream Cone** | Too many E2E tests | Follow pyramid (70/20/10) |
+| **Big Tasks** | Hard to track progress | Break into S/M sizes |
+| **No Dependencies** | Blocked work | Map dependencies explicitly |
+| **Vague Criteria** | Unclear completion | Specific, measurable criteria |