sdd-mcp-server 3.5.0 → 4.0.0

package/skills/sdd-commit/REFERENCE.md

@@ -0,0 +1,31 @@
+# Commit and Pull Request Reference
+
+Read only when the core workflow needs examples or repository conventions do not answer the question.
+
+## Commit Messages
+
+Use `<type>(<scope>): <imperative subject>` when Conventional Commits applies. Common types: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. Keep scope specific, explain why in the body, and use `BREAKING CHANGE:` for migration-impacting behavior.
+
+Examples:
+
+```text
+feat(auth): add password reset flow
+fix(api): preserve error cause
+refactor(storage): centralize key validation
+```
+
+Prefer one logical change per commit. Do not combine unrelated cleanup. Never claim co-authorship without consent.
+
+## Branches and Staging
+
+Follow repository policy. Otherwise use a short `<type>/<ticket>-<description>` branch. Before committing, inspect status, inspect the intended diff, stage explicit paths, re-inspect the staged diff, and verify no secrets or unrelated changes entered it. Do not rewrite published history or force-push unless explicitly directed.
+
+## Pull Request Checklist
+
+- concise summary and motivation;
+- behavioral changes and affected artifacts;
+- linked requirement/issue and breaking-change migration;
+- exact tests/checks observed, with failures disclosed;
+- security, privacy, compatibility, and rollout impact;
+- screenshots only for visual behavior;
+- unresolved blockers or follow-up work.

package/skills/sdd-commit/SKILL.md

@@ -1,285 +1,29 @@
 ---
 name: sdd-commit
-description: Guide commit message and PR creation for SDD workflow. Use when committing changes, creating pull requests, or documenting changes. Invoked via /sdd-commit.
+description: Commit verified SDD changes and prepare a focused pull request.
+disable-model-invocation: true
 ---
 
-# SDD Commit & PR Guidelines
+# Commit and Pull Request
 
-Create clear, consistent commit messages and pull requests that document changes effectively.
+Run this skill locally in the current turn. Do not delegate commit, branch, or pull-request work.
 
-## Commit Message Format
+## Required Workflow
 
-Follow the Conventional Commits specification:
+1. Inspect repository status and the exact changes to include; preserve unrelated work.
+2. Confirm the focused tests or checks relevant to those changes passed. Never claim unobserved verification.
+3. Review the staged diff before committing. Never stage secrets, credentials, generated backups, or unrelated files.
+4. Use the repository's established commit style. Otherwise use an imperative Conventional Commit subject:
+   `<type>(<scope>): <subject>`.
+5. Explain why in the body when the subject cannot; record breaking behavior explicitly.
+6. For a pull request, summarize intent, affected behavior, focused test evidence, migration or security impact, and unresolved blockers.
 
-```
-<type>(<scope>): <subject>
+Do not rewrite history, force-push, discard changes, bypass hooks, or create a commit unless the user requested it.
 
-[optional body]
+## Output
 
-[optional footer(s)]
-```
+Return the commit or PR identifier when created, the included paths, verification evidence, and any blocker. Do not echo a large diff.
 
-### Type Prefixes
+## Optional Reference
 
-| Type | When to Use | Example |
-|------|-------------|---------|
-| `feat` | New feature | `feat(auth): add JWT refresh token` |
-| `fix` | Bug fix | `fix(api): handle null user response` |
-| `docs` | Documentation only | `docs(readme): update installation steps` |
-| `style` | Formatting, no code change | `style(lint): fix linter warnings` |
-| `refactor` | Code change, no new feature or fix | `refactor(user): extract validation logic` |
-| `perf` | Performance improvement | `perf(query): add index for user lookup` |
-| `test` | Adding/updating tests | `test(auth): add login failure tests` |
-| `build` | Build system changes | `build(deps): update dependencies` |
-| `ci` | CI/CD changes | `ci(github): add test workflow` |
-| `chore` | Other changes | `chore(deps): bump lodash version` |
-| `revert` | Revert previous commit | `revert: feat(auth): add JWT refresh` |
-
-### Scope
-
-The scope should indicate the area affected:
-
-```
-feat(auth):       # Authentication module
-fix(api/users):   # Users API endpoint
-docs(readme):     # README file
-test(e2e):        # End-to-end tests
-refactor(db):     # Database layer
-```
-
-### Subject Line
-
-- Use imperative mood: "add" not "added" or "adds"
-- Don't capitalize first letter
-- No period at the end
-- Max 50 characters
-
-```
-# GOOD
-feat(auth): add password reset flow
-fix(cart): prevent duplicate items
-
-# BAD
-feat(auth): Added password reset flow.
-fix(cart): Fixes the duplicate items bug
-```
-
-### Body (Optional)
-
-Use for explaining:
-- **What** changed and **why**
-- Breaking changes
-- Related issues
-
-```
-feat(auth): add multi-factor authentication
-
-Implement TOTP-based 2FA for enhanced security.
-Users can now enable 2FA from their profile settings.
-
-- Add TOTP secret generation
-- Add QR code for authenticator apps
-- Add backup codes for recovery
-
-Closes #123
-```
-
-### Footer (Optional)
-
-```
-BREAKING CHANGE: API endpoint changed from /users to /api/v1/users
-
-Refs: #123, #456
-Co-authored-by: Name <email@example.com>
-```
-
-## Pull Request Template
-
-```markdown
-## Summary
-<!-- 1-3 bullet points describing the changes -->
-- Add user authentication with JWT
-- Implement password reset flow
-- Add comprehensive test coverage
-
-## Motivation
-<!-- Why is this change needed? -->
-Users need secure authentication to access protected resources.
-
-## Changes
-<!-- Detailed list of changes -->
-### Added
-- `AuthService` for handling authentication logic
-- `JWTProvider` for token generation/validation
-- Unit and integration tests for auth flow
-
-### Changed
-- Updated `UserController` to use AuthService
-- Modified API routes to require authentication
-
-### Removed
-- Deprecated session-based authentication
-
-## Testing
-<!-- How was this tested? -->
-- [x] Unit tests pass
-- [x] Integration tests pass
-- [x] Manual testing completed
-- [ ] E2E tests (pending)
-
-## Screenshots
-<!-- If applicable -->
-
-## Checklist
-- [x] Code follows project style guidelines
-- [x] Tests added/updated
-- [x] Documentation updated
-- [x] No breaking changes (or documented)
-- [x] Security considerations reviewed
-
-## Related Issues
-Closes #123
-Refs #456
-```
-
-## Commit Best Practices
-
-### Atomic Commits
-Each commit should be one logical change:
-
-```bash
-# GOOD: Separate commits for separate changes
-git commit -m "feat(user): add email validation"
-git commit -m "test(user): add email validation tests"
-
-# BAD: Multiple unrelated changes
-git commit -m "add email validation, fix bug, update docs"
-```
-
-### Commit Frequency
-- Commit when a logical unit is complete
-- Don't commit broken code
-- Small, frequent commits are better than large, infrequent ones
-
-### Commit Message Examples
-
-#### Feature
-```
-feat(cart): add quantity update functionality
-
-Allow users to update item quantities directly from the cart.
-Includes optimistic UI updates and error handling.
-
-- Add updateQuantity method to CartService
-- Add quantity input component
-- Add debounced API calls
-
-Closes #234
-```
-
-#### Bug Fix
-```
-fix(auth): prevent session fixation attack
-
-Regenerate session ID after successful login to prevent
-session fixation attacks.
-
-Security: OWASP A7 - Identification and Authentication Failures
-```
-
-#### Refactor
-```
-refactor(api): extract common error handling
-
-Move error handling logic to middleware for consistency
-across all API endpoints.
-
-- Create ErrorHandlerMiddleware
-- Add custom error classes
-- Update all controllers to throw custom errors
-
-No functional changes.
-```
-
-#### Breaking Change
-```
-feat(api)!: change user endpoint response format
-
-BREAKING CHANGE: The /api/users endpoint now returns
-a paginated response instead of an array.
-
-Before:
-[{ id: 1, name: "John" }, ...]
-
-After:
-{
-  data: [{ id: 1, name: "John" }, ...],
-  pagination: { page: 1, total: 100 }
-}
-
-Migration: Update all clients to handle the new response format.
-```
-
-## Branch Naming
-
-```
-<type>/<ticket>-<description>
-
-Examples:
-feature/AUTH-123-jwt-authentication
-bugfix/CART-456-duplicate-items
-hotfix/PROD-789-security-patch
-chore/update-dependencies
-```
-
-## Git Workflow
-
-### Before Committing
-```bash
-# Check status
-git status
-
-# Review changes
-git diff
-
-# Stage specific files
-git add src/auth/
-
-# Or stage all
-git add -A
-```
-
-### Creating Commit
-```bash
-# With message
-git commit -m "feat(auth): add login endpoint"
-
-# Open editor for longer message
-git commit
-```
-
-### Before PR
-```bash
-# Update from main
-git fetch origin main
-git rebase origin/main
-
-# Run tests
-{your test command}  # e.g., npm test, pytest, cargo test, go test
-
-# Push
-git push origin feature/AUTH-123-jwt-auth
-```
-
-## Quality Checklist
-
-- [ ] Commit message follows format
-- [ ] Type prefix is appropriate
-- [ ] Scope is specific
-- [ ] Subject is imperative and concise
-- [ ] Body explains why (if needed)
-- [ ] Breaking changes documented
-- [ ] Related issues linked
-- [ ] Branch name follows convention
-- [ ] Tests pass before commit
-- [ ] PR description complete
+Read [REFERENCE.md](REFERENCE.md) only when message examples, branch naming, staging guidance, or the pull-request checklist is needed.

package/skills/sdd-design/REFERENCE.md

@@ -0,0 +1,35 @@
+# Design Reference
+
+Read only for format help after the mandatory core design workflow is understood.
+
+## Pattern Selection
+
+- Layered or clean architecture: business rules need stable inward dependencies.
+- Hexagonal: domain logic needs replaceable external adapters.
+- Event-driven: asynchronous producers and consumers are inherent to the requirement.
+- Service split: independent ownership/deployment is proven; do not choose it merely for fashion.
+
+## Component Template
+
+```markdown
+### Component name
+Purpose and owned data:
+Responsibilities and non-responsibilities:
+Public interface:
+Dependencies and direction:
+Invariants:
+Failure/timeout/retry behavior:
+Authorization and validation boundary:
+Verification:
+```
+
+## Design Checklist
+
+- every FR/NFR maps to a decision and test strategy;
+- data lifecycle, ownership, cardinality, validation, and migration are explicit;
+- interfaces specify inputs, outputs, errors, idempotency, and compatibility;
+- trust boundaries and least privilege are visible;
+- retry behavior cannot amplify a failure or duplicate side effects;
+- alternatives explain why simpler options were rejected;
+- diagrams clarify real flow rather than decorate the document;
+- rollout and rollback preserve valid existing state.

package/skills/sdd-design/SKILL.md

@@ -1,281 +1,35 @@
 ---
 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>.
+description: Design an approved SDD feature with traceable components, interfaces, risks, and tests.
+disable-model-invocation: true
 ---
 
-# SDD Technical Design Generation
-
-Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.
+# SDD Design
 
 ## 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`
+- Resolve the feature with `sdd-status`.
+- Requirements must be generated and approved. Stop rather than designing from an unapproved draft.
+- Read approved requirements plus relevant product, technology, and structure steering.
 
 ## 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
+1. Map every FR/NFR and constraint to a design decision.
+2. Define data ownership and flow before components. Choose the simplest fitting architecture and explain trade-offs.
+3. Specify component responsibilities, public interfaces, dependencies, invariants, and failure behavior.
+4. Cover persistence/migration, concurrency, compatibility, authorization, input boundaries, sensitive data, observability, and rollback where relevant.
+5. Define unit, integration, and end-to-end verification against acceptance criteria.
+6. Write `.spec/specs/{feature}/design.md`, then run `sdd-validate-design`. Resolve a NO-GO result before requesting design approval.
+7. Request approval only after the design is complete and requirements remain traceable.
 
-| 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 |
-
-## Steering Document References
-
-Apply these steering documents during design:
-
-| Document | Purpose | Key Application |
-|----------|---------|-----------------|
-| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Apply SOLID principles to component design, ensure interfaces follow ISP and DIP |
-| `.spec/steering/linus-review.md` | Code quality, data structures | Focus on data structures first, eliminate special cases, ensure backward compatibility |
+## Specialist Delegation
 
-**Key Linus Principles for Design:**
-1. **Data Structures First**: "Bad programmers worry about the code. Good programmers worry about data structures."
-2. **Eliminate Special Cases**: "Good code has no special cases"
-3. **Simplicity**: "If implementation needs more than 3 levels of indentation, redesign it"
-4. **Never Break Userspace**: Ensure backward compatibility
+Target renderers provide the `architect` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only approved requirements, relevant architecture facts, constraints, and decisions needed. The specialist must not delegate again. Keep both the handoff and returned summary at or below 2,048 estimated tokens. Integrate its decisions and verification evidence. If the advisor or routed model is unavailable, record one fallback and continue in the parent without retrying or spawning a generic child. Where the target applies a native per-turn model override, execute in this turn instead of spawning.
 
-## Quality Checklist
+## Output
 
-- [ ] 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
+The design must include overview, requirements traceability, architecture/data flow, components, interfaces, data models, errors, security, testing, dependencies, alternatives, and risks.
 
-## Specialist Delegation
+## Optional Reference
 
-When the host supports subagents, delegate this phase to the `architect` role with a compact handoff containing only the approved requirements, relevant project context, constraints, and required design decisions. 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 when a component template, design checklist, or architecture-pattern comparison is needed.

package/skills/sdd-implement/REFERENCE.md

@@ -0,0 +1,26 @@
+# Implementation Reference
+
+Read only when a detailed checklist is needed for the current task.
+
+## Design Prompts
+
+- SRP: does each unit own one reason to change?
+- OCP: is a real extension point needed, or is direct code simpler?
+- LSP: can every subtype preserve the advertised contract?
+- ISP: can consumers depend on a smaller capability?
+- DIP: do policy decisions avoid depending on infrastructure details?
+- Prefer KISS and YAGNI over speculative abstraction; eliminate special cases through better data shape when possible.
+
+## Security Prompts
+
+Check only relevant risks, but never skip the analysis: authorization/ownership, validation and canonicalization, parameterized queries and command arguments, output encoding, safe URL handling, cryptographic primitives, secret storage, session state, dependency integrity, error disclosure, and sensitive logging. Default deny at trust boundaries and clean up resources on every failure path.
+
+## Completion Checklist
+
+- acceptance criteria have observable tests;
+- RED failure was caused by missing behavior, not broken setup;
+- GREEN and post-refactor focused results were observed;
+- all affected callers and schemas were migrated;
+- concurrency, errors, cancellation, and rollback were considered;
+- no dead compatibility alias, debug output, placeholder, or secret remains;
+- task record names exact evidence rather than estimated coverage.