sdd-mcp-server 3.5.1 → 5.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,51 @@
+# 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.
+
+## Exact Document Shape
+
+```markdown
+# Design: Feature
+## Requirements Traceability
+## Architecture and Data Flow
+## Components and Interfaces
+### D-1: Decision title
+**Covers:** FR-1, NFR-1
+**Decision:** The chosen mechanism and trade-off.
+**Failure behavior:** The observable safe failure.
+**Verification:** How the decision is tested.
+## Failure Handling
+## Verification
+```
+
+## 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,44 @@
 ---
 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
+# SDD Design
 
-Generate comprehensive technical design documents that translate approved requirements into actionable architecture specifications.
+The user invokes this Skill; backend lifecycle calls are internal. Never tell the user to call a raw MCP tool or expose revision, hash, fingerprint, or backend JSON except in explicit debug output.
 
-## Prerequisites
+## Resolve and Restore
 
-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`
+1. Internally resolve status. If no feature name is supplied, resume the sole incomplete feature or ask the user to select when several exist.
+2. Requirements must be approved. If durable status says otherwise, present the persisted blocker and make no file change.
+3. Load the latest approved compact context before method work. Load an unapproved design draft only with full mode and explicit unapproved inclusion.
+4. If status reports an observed artifact identity for an orphan or manual edit, read that exact design file before revising. Never acknowledge its hash without inspecting and deliberately incorporating or replacing its content.
 
-## Workflow
+If the runtime is unavailable because of host permission, report an actionable reload/trust or policy blocker; never substitute manual backend instructions.
 
-### Step 1: Verify Prerequisites
+## Method and Artifact Contract
 
-Use `sdd-status` MCP tool to verify:
-- `requirements.generated: true`
-- `requirements.approved: true` (recommended before design)
+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. Include exact headings `## Requirements Traceability`, `## Architecture and Data Flow`, `## Components and Interfaces`, `## Failure Handling`, and `## Verification`.
+4. Give each decision a unique `### D-N: ...` section with same-line labels `**Covers:**`, `**Decision:**`, `**Failure behavior:**`, and `**Verification:**`. `Covers` is a comma-separated list of known requirement IDs.
+5. Specify responsibilities, interfaces, dependencies, invariants, persistence/migration, compatibility, authorization, input boundaries, concurrency, failure behavior, rollback, and verification where relevant.
 
-### Step 2: Review Requirements
+Internally submit the complete Markdown with the exact revision and artifact identity last observed. Submission, not direct file editing, is the canonical write. Present the saved path and concise validation outcome. On failed validation, keep the durable draft, load it explicitly, and revise; do not request approval.
 
-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
+## Human Gate
 
-### Step 3: Choose Architecture Pattern
+When validation passes, ask one explicit question: **“Approve this design?”** Only an unambiguous affirmative answer in this Skill flow permits internal approval of the exact reviewed revision and artifact. Never self-approve. Reread status after approval and report the persisted outcome.
 
-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 |
-
-## 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, architecture facts, constraints, and needed decisions. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If unavailable, record one fallback and continue in the parent without retrying or spawning a generic child.
 
-## 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
+Return the canonical saved path, traceable decisions, concise validation evidence, the approval question or persisted approval, and durable blockers. Do not present raw MCP operations as next steps.
 
-## 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 for the exact design shape, component template, checklist, or pattern comparison.