sdd-mcp-server 3.5.0 → 4.0.0

package/skills/sdd-implement/SKILL.md

@@ -1,302 +1,41 @@
 ---
 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>.
+description: Implement approved SDD tasks test-first with focused verification and security checks.
+disable-model-invocation: true
 ---
 
-# SDD Implementation Guidelines
+# SDD Implementation
 
-Execute implementation following TDD methodology, SOLID principles, and security best practices.
+Work inline in the current turn. Do not create a serial implementation specialist. Delegate only when at least two genuinely independent slices can run concurrently.
 
 ## Prerequisites
 
-Before implementing:
-1. Tasks must be approved (use `sdd-status` to verify)
-2. If the TDD test-case review checkpoint is enabled, test cases must be reviewed first (`sdd-review-test-cases`)
-3. Review tasks in `.spec/specs/{feature}/tasks.md`
-4. Understand the design in `.spec/specs/{feature}/design.md`
+- Use `sdd-status`: requirements, design, and tasks must be approved.
+- If test-case review is configured, `sdd-review-test-cases` must already be complete.
+- Read the approved task, its acceptance criteria, design interfaces, and relevant steering before editing.
 
-## Implementation Workflow
-
-### Step 1: Load Context
-
-1. Use `sdd-status` MCP tool to verify all phases approved
-2. Confirm `TDD Test Case Review` is reviewed when that checkpoint appears in status
-3. Read the tasks document for current implementation
-4. Identify the next task to implement
-
-### Step 2: Execute TDD Cycle
+## Required 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
-
-## Steering Document References
+1. **RED:** write a focused test for observable behavior and run it to prove the expected failure.
+2. **GREEN:** implement only enough production code to pass; run the focused test.
+3. **REFACTOR:** simplify without changing behavior; rerun the focused test.
 
-Apply these steering documents during implementation:
+Do not mark a task complete without recorded failing and passing evidence. Test boundaries, errors, invariants, transitions, and precedence—not implementation plumbing.
 
-| Document | Purpose | Key Application |
-|----------|---------|-----------------|
-| `.spec/steering/tdd-guideline.md` | Test-Driven Development | Follow Red-Green-Refactor cycle for all code |
-| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Apply SOLID principles, keep code simple and focused |
-| `.spec/steering/owasp-top10-check.md` | Security checklist | Verify all OWASP Top 10 security requirements before completion |
+## Mandatory Checks
 
-**Critical Implementation Rules:**
-1. **TDD First**: Never write production code without a failing test
-2. **SOLID Always**: Apply all five principles (SRP, OCP, LSP, ISP, DIP)
-3. **Security Required**: Complete OWASP checklist before marking done
+- Preserve approved interfaces and existing conventions; update every affected caller.
+- Validate untrusted input, enforce authorization, avoid injection, protect secrets and sensitive logs, and fail safely.
+- Consider concurrency, resource cleanup, compatibility, and error propagation where applicable.
+- Run only relevant verification while iterating, then the required affected checks.
+- Update task status only after acceptance criteria and security checks pass. Never fabricate test, coverage, lint, or build results.
 
-## Common Anti-Patterns to Avoid
+## Output
 
-| 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 |
+Report completed task numbers, affected artifacts, RED/GREEN verification evidence, security-relevant decisions, and unresolved blockers. Write large artifacts to their canonical files instead of echoing them.
 
-## Specialist Delegation
+## Optional Reference
 
-When the host supports subagents, delegate implementation slices to the `implementer` role with a compact handoff containing only the approved task, acceptance criteria, relevant interfaces, and focused test command. Wait for the specialist and then integrate its result before advancing task status. If specialist delegation is unavailable, state the fallback and continue in the current agent.
+Read [REFERENCE.md](REFERENCE.md) only when detailed SOLID, OWASP, anti-pattern, or completion checklists are needed.

package/skills/sdd-requirements/REFERENCE.md

@@ -0,0 +1,31 @@
+# Requirements Reference
+
+Read only for examples or document formatting.
+
+## EARS Examples
+
+```text
+The service SHALL reject an absolute feature name.
+WHEN a valid approval request is committed THEN the service SHALL publish the derived handoff.
+WHILE a phase is unapproved THE service SHALL exclude its draft from compact context.
+WHERE test-case review is enabled THE service SHALL require review before tasks approval.
+IF handoff publication fails after approval THEN the service SHALL retain the approved state and report pending regeneration.
+```
+
+## Suggested Document Shape
+
+```markdown
+# Requirements: Feature
+## Scope
+## Functional Requirements
+### FR-1: Name
+EARS statement
+Acceptance criteria
+## Non-functional Requirements
+## Constraints and assumptions
+## Traceability
+```
+
+## Quality Checklist
+
+Each requirement has one concern, a stable ID, normative SHALL wording, measurable bounds, positive and failure behavior, and acceptance criteria that do not prescribe incidental implementation. Requirements do not conflict, duplicate one another, hide an undefined actor, or depend on ambiguous timing. Security and compatibility requirements identify an asset or existing contract rather than repeating a generic checklist.

package/skills/sdd-requirements/SKILL.md

@@ -1,151 +1,39 @@
 ---
 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>.
+description: Generate testable EARS requirements and measurable acceptance criteria for an SDD feature.
+disable-model-invocation: true
 ---
 
-# SDD Requirements Generation
-
-Generate comprehensive, EARS-formatted requirements documents that integrate with the SDD (Spec-Driven Development) workflow.
+# SDD Requirements
 
 ## 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/`
+- The feature must exist through `sdd-init`.
+- Check its durable phase with `sdd-status`.
+- Read the feature description and relevant steering. Ask only for material information that cannot be derived.
 
 ## 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}
+1. Identify users, goals, in-scope behavior, exclusions, constraints, assumptions, dependencies, and measurable success.
+2. Write independently testable functional and non-functional requirements using EARS:
+   - ubiquitous: `The system SHALL ...`
+   - event: `WHEN ... THEN the system SHALL ...`
+   - state: `WHILE ... THE system SHALL ...`
+   - optional: `WHERE ... THE system SHALL ...`
+   - unwanted behavior: `IF ... THEN the system SHALL ...`
+3. Give every requirement a stable ID and specific acceptance criteria. Replace ambiguous words such as “fast”, “appropriate”, “should”, or “may” with observable bounds.
+4. Include security, privacy, accessibility, compatibility, error, and performance requirements only where relevant; do not invent scope.
+5. Check completeness, consistency, feasibility, traceability, and testability; use `sdd-validate-gap` when existing code is in scope.
+6. Write `.spec/specs/{feature}/requirements.md`. Request requirements approval only after the artifact is complete; never self-approve silently.
 
-**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
-
-## Steering Document References
+## Specialist Delegation
 
-Apply these steering documents during requirements generation:
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only the goal, verified context, constraints, open decisions, 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.
 
-| Document | Purpose | Key Application |
-|----------|---------|-----------------|
-| `.spec/steering/principles.md` | SOLID, DRY, KISS, YAGNI | Ensure requirements follow KISS (simple, unambiguous) and YAGNI (only what's needed now) |
+## Output
 
-**Key Principles for Requirements:**
-- **KISS**: Keep requirements simple and unambiguous
-- **YAGNI**: Only specify what's actually needed now
-- **Single Responsibility**: Each requirement addresses one concern
+Return the saved path, key scope decisions, validation evidence, and approval as the next action.
 
-## Specialist Delegation
+## Optional Reference
 
-When the host supports subagents, delegate this phase to the `planner` role with a compact handoff containing only the feature goal, approved context, constraints, and required deliverable. 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 EARS examples, document structure, or the extended quality checklist.

package/skills/sdd-review/REFERENCE.md

@@ -0,0 +1,26 @@
+# Review Reference
+
+Read only when the focused review needs extra prompts.
+
+## Severity
+
+- Critical: exploitable security flaw, corruption, irreversible data loss, or broad outage.
+- Important: reproducible incorrect behavior, regression, race, leak, or contract break.
+- Minor: concrete maintenance cost likely to cause future defects.
+- Suggestion: optional preference; omit it unless specifically requested.
+
+## Language-independent Prompts
+
+Check ownership and mutation, null/empty/boundary behavior, ordering and precedence, async cancellation, retries and idempotency, resource cleanup, error identity, public API compatibility, serialization, time zones, numeric overflow, and deterministic tests.
+
+## Finding Shape
+
+```text
+[severity] path:line — concise defect
+Trigger: exact input/state/interleaving
+Impact: observable consequence
+Evidence: code path or focused reproduction
+Fix: smallest source-level remedy
+```
+
+Review tests for missing contracts, not line coverage. Reject tests that only mirror implementation, inspect source text, rely on timing sleeps, share state, or swallow real errors. End with verification actually performed and explicit residual risk.