sdd-mcp-server 1.8.1 → 2.0.0

package/skills/sdd-design/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: sdd-design
+description: Create technical design specifications for SDD workflow. Use when designing architecture, defining components, or creating system design documents after requirements are approved. Invoked via /sdd-design <feature-name>.
+---
+
+# SDD Technical Design Generation
+
+Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.
+
+## Prerequisites
+
+Before generating design:
+1. Requirements must be generated using `/sdd-requirements`
+2. Requirements phase should be approved (use `sdd-approve requirements` MCP tool)
+3. Review existing architecture in `.spec/steering/tech.md` and `.spec/steering/structure.md`
+
+## Workflow
+
+### Step 1: Verify Prerequisites
+
+Use `sdd-status` MCP tool to verify:
+- `requirements.generated: true`
+- `requirements.approved: true` (recommended before design)
+
+### Step 2: Review Requirements
+
+1. Read `.spec/specs/{feature}/requirements.md`
+2. Identify all functional requirements (FR-*)
+3. Identify all non-functional requirements (NFR-*)
+4. Note constraints and assumptions
+
+### Step 3: Choose Architecture Pattern
+
+Select appropriate patterns based on requirements:
+
+| Pattern | Use When | Key Characteristics |
+|---------|----------|---------------------|
+| **Clean Architecture** | Domain-heavy apps | Layers: Domain → Use Cases → Interface → Infrastructure |
+| **MVC/MVP** | Web applications | Model-View-Controller separation |
+| **Microservices** | Distributed systems | Independent deployable services |
+| **Event-Driven** | Async processing | Event producers and consumers |
+| **Hexagonal** | Testable business logic | Ports and Adapters pattern |
+
+### Step 4: Design Components
+
+For each component, specify:
+
+```markdown
+## Component: {ComponentName}
+
+**Type:** Service | Controller | Repository | Adapter | Provider
+
+**Purpose:** {Single responsibility description}
+
+**Responsibilities:**
+- {Responsibility 1}
+- {Responsibility 2}
+
+**Interface:**
+```typescript
+interface I{ComponentName} {
+  methodName(input: InputType): Promise<OutputType>;
+}
+```
+
+**Dependencies:**
+- {Dependency 1 via interface}
+- {Dependency 2 via interface}
+
+**Error Handling:**
+- {Error scenario 1}: {How to handle}
+```
+
+### Step 5: Define Data Models
+
+```markdown
+## Data Models
+
+### Model: {EntityName}
+
+**Purpose:** {What this entity represents}
+
+| Property | Type | Required | Description | Validation |
+|----------|------|----------|-------------|------------|
+| id | string | Yes | Unique identifier | UUID format |
+| name | string | Yes | Display name | 1-100 chars |
+| createdAt | Date | Yes | Creation timestamp | ISO 8601 |
+
+**Relationships:**
+- Has many: {RelatedEntity} (one-to-many)
+- Belongs to: {ParentEntity} (many-to-one)
+
+**Invariants:**
+- {Business rule 1}
+- {Business rule 2}
+```
+
+### Step 6: Specify Interfaces
+
+```markdown
+## API Interfaces
+
+### REST Endpoints
+
+| Method | Path | Description | Request | Response | Auth |
+|--------|------|-------------|---------|----------|------|
+| POST | /api/v1/resource | Create resource | CreateDTO | Resource | Bearer |
+| GET | /api/v1/resource/:id | Get by ID | - | Resource | Bearer |
+
+### Internal Service Interfaces
+
+Following Interface Segregation Principle:
+
+```typescript
+// Read operations
+interface IResourceReader {
+  getById(id: string): Promise<Resource>;
+  list(filter: Filter): Promise<Resource[]>;
+}
+
+// Write operations
+interface IResourceWriter {
+  create(data: CreateDTO): Promise<Resource>;
+  update(id: string, data: UpdateDTO): Promise<Resource>;
+  delete(id: string): Promise<void>;
+}
+```
+```
+
+### Step 7: Document Error Handling
+
+```markdown
+## Error Handling Strategy
+
+### Error Categories
+
+| Category | HTTP Status | Retry | Log Level |
+|----------|-------------|-------|-----------|
+| Validation | 400 | No | WARN |
+| Not Found | 404 | No | INFO |
+| Conflict | 409 | No | WARN |
+| Rate Limit | 429 | Yes (backoff) | WARN |
+| Internal | 500 | Yes (limited) | ERROR |
+
+### Error Response Format
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable message",
+    "details": [{ "field": "email", "issue": "Invalid format" }],
+    "requestId": "uuid-for-tracing"
+  }
+}
+```
+```
+
+### Step 8: Apply Linus-Style Quality Review
+
+Before finalizing, validate against these principles:
+
+#### 1. Taste - Is it elegant?
+- Does the design feel natural and intuitive?
+- Are there unnecessary complications?
+
+#### 2. Complexity - Is it simple?
+- Can any component be simplified?
+- Are there too many abstractions?
+
+#### 3. Special Cases - Are edge cases handled?
+- What happens at boundaries?
+- How does it fail gracefully?
+
+#### 4. Data Structures - Are they optimal?
+- Is the right data structure chosen?
+- Does data flow make sense?
+
+#### 5. Code Organization - Is it maintainable?
+- Can new developers understand it?
+- Is it easy to modify?
+
+### Step 9: Save and Validate
+
+1. Save design to `.spec/specs/{feature}/design.md`
+2. Use `sdd-validate-design` MCP tool for GO/NO-GO review
+3. If GO, use `sdd-approve design` MCP tool
+
+## Design Document Template
+
+```markdown
+# Design: {Feature Name}
+
+## Overview
+{Brief summary of the design approach}
+
+## Architecture Pattern
+{Selected pattern and rationale}
+
+## Component Diagram
+```
+[Component A] ──> [Component B]
+       │
+       └──> [Component C]
+```
+
+## Components
+
+### {Component 1}
+{Component details as described above}
+
+## Data Models
+
+### {Entity 1}
+{Model details as described above}
+
+## Interfaces
+
+### External APIs
+{API specifications}
+
+### Internal Interfaces
+{Service interfaces}
+
+## Error Handling
+{Error strategy}
+
+## Security Considerations
+- Authentication: {approach}
+- Authorization: {approach}
+- Data protection: {approach}
+
+## Testing Strategy
+- Unit tests: {coverage target}
+- Integration tests: {scope}
+- E2E tests: {critical paths}
+
+## Dependencies
+- External: {list}
+- Internal: {list}
+```
+
+## MCP Tool Integration
+
+| Tool | When to Use |
+|------|-------------|
+| `sdd-status` | Verify requirements phase complete |
+| `sdd-validate-design` | Perform GO/NO-GO review |
+| `sdd-approve` | Mark design phase as approved |
+
+## Quality Checklist
+
+- [ ] All FR-* requirements have corresponding components
+- [ ] All NFR-* requirements have technical solutions
+- [ ] SOLID principles are followed
+- [ ] Interfaces are well-defined (ISP)
+- [ ] Dependencies flow inward (DIP)
+- [ ] Data models are complete with invariants
+- [ ] Error handling strategy is comprehensive
+- [ ] Security considerations are addressed
+- [ ] Testing approach is specified
+- [ ] Linus-style review passed

package/skills/sdd-implement/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: sdd-implement
+description: Implementation guidelines for SDD workflow. Use when implementing features, applying TDD, checking security, or ensuring code quality. Invoked via /sdd-implement <feature-name>.
+---
+
+# SDD Implementation Guidelines
+
+Execute implementation following TDD methodology, SOLID principles, and security best practices.
+
+## Prerequisites
+
+Before implementing:
+1. Tasks must be approved (use `sdd-status` to verify)
+2. Review tasks in `.spec/specs/{feature}/tasks.md`
+3. Understand the design in `.spec/specs/{feature}/design.md`
+
+## Implementation Workflow
+
+### Step 1: Load Context
+
+1. Use `sdd-status` MCP tool to verify all phases approved
+2. Read the tasks document for current implementation
+3. Identify the next task to implement
+
+### Step 2: Execute TDD Cycle
+
+For each task:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. RED: Write Failing Test                                 │
+│     - Define expected behavior                              │
+│     - Run test, confirm it FAILS                           │
+│                                                             │
+│  2. GREEN: Write Minimal Code                               │
+│     - Just enough to pass the test                         │
+│     - No extra features                                     │
+│     - Run test, confirm it PASSES                          │
+│                                                             │
+│  3. REFACTOR: Improve Code                                  │
+│     - Clean up without changing behavior                    │
+│     - Run tests, confirm still PASSING                     │
+│                                                             │
+│  REPEAT for each test case                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Apply SOLID Principles
+
+#### S - Single Responsibility Principle
+```typescript
+// GOOD: One class, one job
+class UserValidator {
+  validate(user: User): ValidationResult { ... }
+}
+
+class UserRepository {
+  save(user: User): Promise<void> { ... }
+}
+
+// BAD: Class doing too much
+class UserManager {
+  validate(user: User) { ... }
+  save(user: User) { ... }
+  sendEmail(user: User) { ... }
+  generateReport() { ... }
+}
+```
+
+#### O - Open/Closed Principle
+```typescript
+// GOOD: Open for extension, closed for modification
+interface PaymentProcessor {
+  process(amount: number): Promise<Result>;
+}
+
+class StripeProcessor implements PaymentProcessor { ... }
+class PayPalProcessor implements PaymentProcessor { ... }
+
+// BAD: Modifying existing code for new payment types
+class PaymentService {
+  process(type: string, amount: number) {
+    if (type === 'stripe') { ... }
+    else if (type === 'paypal') { ... }
+    // Adding new type requires modifying this class
+  }
+}
+```
+
+#### L - Liskov Substitution Principle
+```typescript
+// GOOD: Subtypes are substitutable
+class Bird {
+  move(): void { /* fly or walk */ }
+}
+
+class Sparrow extends Bird {
+  move(): void { this.fly(); }
+}
+
+class Penguin extends Bird {
+  move(): void { this.walk(); }
+}
+
+// BAD: Subtype breaks expected behavior
+class Bird {
+  fly(): void { ... }
+}
+
+class Penguin extends Bird {
+  fly(): void { throw new Error("Can't fly!"); }
+}
+```
+
+#### I - Interface Segregation Principle
+```typescript
+// GOOD: Specific interfaces
+interface Readable {
+  read(): Data;
+}
+
+interface Writable {
+  write(data: Data): void;
+}
+
+class FileHandler implements Readable, Writable { ... }
+class ReadOnlyFile implements Readable { ... }
+
+// BAD: Fat interface forcing unnecessary implementation
+interface FileOperations {
+  read(): Data;
+  write(data: Data): void;
+  delete(): void;
+  execute(): void;
+}
+```
+
+#### D - Dependency Inversion Principle
+```typescript
+// GOOD: Depend on abstractions
+interface IUserRepository {
+  findById(id: string): Promise<User>;
+}
+
+class UserService {
+  constructor(private repo: IUserRepository) {}
+}
+
+// BAD: Depend on concrete implementations
+class UserService {
+  private repo = new PostgresUserRepository();
+}
+```
+
+### Step 4: Security Checklist (OWASP Top 10)
+
+Before marking implementation complete, verify:
+
+#### 1. Broken Access Control
+- [ ] Enforce access control on every request
+- [ ] Deny by default
+- [ ] Validate user owns the resource
+
+#### 2. Cryptographic Failures
+- [ ] Use strong encryption (AES-256, RSA-2048+)
+- [ ] Never store passwords in plain text (use bcrypt/argon2)
+- [ ] Use HTTPS for all communications
+
+#### 3. Injection
+- [ ] Use parameterized queries for database
+- [ ] Validate and sanitize all user inputs
+- [ ] Escape output in templates
+
+#### 4. Insecure Design
+- [ ] Apply threat modeling
+- [ ] Implement defense in depth
+- [ ] Fail securely
+
+#### 5. Security Misconfiguration
+- [ ] Remove default credentials
+- [ ] Disable unnecessary features
+- [ ] Keep dependencies updated
+
+#### 6. Vulnerable Components
+- [ ] Use dependency audit tools (e.g., `npm audit`, `pip-audit`, `cargo audit`, `snyk`)
+- [ ] Update vulnerable packages
+- [ ] Remove unused dependencies
+
+#### 7. Authentication Failures
+- [ ] Implement proper session management
+- [ ] Use MFA where appropriate
+- [ ] Implement account lockout
+
+#### 8. Software Integrity
+- [ ] Verify package integrity
+- [ ] Use lockfiles (e.g., `package-lock.json`, `Cargo.lock`, `poetry.lock`, `go.sum`)
+- [ ] Sign commits if required
+
+#### 9. Logging & Monitoring
+- [ ] Log security events
+- [ ] Don't log sensitive data
+- [ ] Implement alerting
+
+#### 10. SSRF (Server-Side Request Forgery)
+- [ ] Validate and sanitize URLs
+- [ ] Use allowlists for external calls
+- [ ] Disable redirects or validate them
+
+### Step 5: Code Quality Standards
+
+#### Naming
+```typescript
+// GOOD
+const userEmail = user.email;
+function calculateTotalPrice(items: Item[]): number { ... }
+
+// BAD
+const e = user.email;
+function calc(i: any): any { ... }
+```
+
+#### Comments
+```typescript
+// GOOD: Explain WHY, not WHAT
+// Use retry because the external API has rate limits
+const result = await retryWithBackoff(fetchData);
+
+// BAD: Obvious comments
+// Get the user
+const user = getUser(id);
+```
+
+#### Error Handling
+```typescript
+// GOOD: Specific, informative errors
+class UserNotFoundError extends Error {
+  constructor(userId: string) {
+    super(`User with ID ${userId} not found`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+// BAD: Generic errors
+throw new Error('Error');
+```
+
+### Step 6: Update Task Status
+
+After implementing each task:
+1. Mark task as complete in tasks.md
+2. Verify test coverage >= 80%
+3. Run `sdd-quality-check` MCP tool on new code
+
+## MCP Tool Integration
+
+| Tool | When to Use |
+|------|-------------|
+| `sdd-status` | Check all phases approved before implementing |
+| `sdd-spec-impl` | Execute specific tasks with TDD |
+| `sdd-quality-check` | Validate code quality after implementation |
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] All tests pass
+- [ ] Code coverage >= 80%
+- [ ] No lint/type errors
+- [ ] Security checklist verified
+- [ ] SOLID principles applied
+- [ ] Code self-documenting or commented where needed
+
+## Common Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **God Class** | Class does too much | Split by responsibility |
+| **Feature Envy** | Method uses another class's data extensively | Move method to that class |
+| **Primitive Obsession** | Using primitives for domain concepts | Create value objects |
+| **Magic Numbers** | Unexplained numeric literals | Use named constants |
+| **Deep Nesting** | Multiple levels of if/loops | Extract methods, early returns |
+| **Long Methods** | Methods doing too much | Split into smaller methods |

package/skills/sdd-requirements/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sdd-requirements
+description: Generate EARS-formatted requirements for SDD workflow. Use when starting a new feature specification, creating requirements documents, or defining acceptance criteria. Invoked via /sdd-requirements <feature-name>.
+---
+
+# SDD Requirements Generation
+
+Generate comprehensive, EARS-formatted requirements documents that integrate with the SDD (Spec-Driven Development) workflow.
+
+## Prerequisites
+
+Before generating requirements:
+1. Feature must be initialized with `sdd-init` MCP tool
+2. Check current phase with `sdd-status` MCP tool
+3. Review project steering documents in `.spec/steering/`
+
+## Workflow
+
+### Step 1: Gather Context
+
+1. Use `sdd-status` MCP tool to verify feature exists and check current phase
+2. Read project context from `.spec/steering/product.md` if available
+3. Review the feature description from `.spec/specs/{feature}/spec.json`
+
+### Step 2: Analyze Requirements
+
+Identify and document:
+- **Primary user goal**: What problem are we solving?
+- **Target users**: Who will use this feature?
+- **Core functionality**: What must the system do?
+- **Success criteria**: How do we know it works?
+
+### Step 3: Generate EARS-Formatted Requirements
+
+Use the **EARS (Easy Approach to Requirements Syntax)** format for all requirements.
+
+#### EARS Patterns
+
+| Pattern | Syntax | Use When |
+|---------|--------|----------|
+| **Ubiquitous** | `The <system> SHALL <action>` | Always true requirement |
+| **Event-Driven** | `WHEN <trigger> THEN the <system> SHALL <action>` | Response to event |
+| **State-Driven** | `WHILE <state> THE <system> SHALL <action>` | During specific state |
+| **Optional** | `WHERE <feature enabled> THE <system> SHALL <action>` | Configurable feature |
+| **Unwanted Behavior** | `IF <condition> THEN the <system> SHALL <action>` | Exception handling |
+
+#### Examples
+
+```markdown
+## FR-1: User Authentication
+WHEN a user submits valid credentials
+THEN the system SHALL authenticate the user and return a session token
+
+## FR-2: Session Management
+WHILE a user session is active
+THE system SHALL maintain the session for up to 24 hours of inactivity
+
+## NFR-1: Performance
+The system SHALL respond to authentication requests within 200ms
+```
+
+### Step 4: Structure the Document
+
+Generate requirements.md with this structure:
+
+```markdown
+# Requirements: {Feature Name}
+
+## Overview
+Brief description of the feature and its purpose.
+
+## Functional Requirements
+
+### FR-1: {Requirement Name}
+**Objective:** As a {user type}, I want {goal}, so that {benefit}
+
+**EARS Specification:**
+WHEN {trigger}
+THEN the system SHALL {action}
+
+**Acceptance Criteria:**
+1. {Specific, testable criterion}
+2. {Specific, testable criterion}
+
+### FR-2: {Next Requirement}
+...
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+{Performance requirements with specific metrics}
+
+### NFR-2: Security
+{Security requirements aligned with OWASP guidelines}
+
+### NFR-3: Scalability
+{Scalability requirements if applicable}
+
+## Constraints
+{Technical or business constraints}
+
+## Assumptions
+{Assumptions made during requirements gathering}
+```
+
+### Step 5: Validate and Save
+
+After generating requirements:
+1. Ensure all requirements are testable
+2. Verify EARS format is correctly applied
+3. Save to `.spec/specs/{feature}/requirements.md`
+4. Use `sdd-approve` MCP tool to mark phase complete when ready
+
+## MCP Tool Integration
+
+This skill works with these MCP tools:
+
+| Tool | When to Use |
+|------|-------------|
+| `sdd-status` | Check current workflow phase before starting |
+| `sdd-validate-gap` | Validate requirements against existing codebase |
+| `sdd-approve` | Mark requirements phase as approved |
+
+## Quality Checklist
+
+Before completing requirements:
+- [ ] All requirements use EARS format
+- [ ] Each requirement is independently testable
+- [ ] Acceptance criteria are specific and measurable
+- [ ] Security requirements align with OWASP Top 10
+- [ ] Performance requirements have specific metrics
+- [ ] Requirements are traceable to user stories
+- [ ] No ambiguous terms (avoid "should", "may", "might")
+- [ ] Each FR has clear acceptance criteria
+
+## Coding Principles Applied
+
+- **SOLID**: Single Responsibility - each requirement addresses one concern
+- **KISS**: Keep requirements simple and unambiguous
+- **YAGNI**: Only specify what's actually needed now