sdd-mcp-server 3.5.1 → 5.0.0

package/skills/sdd-implement/REFERENCE.md

@@ -0,0 +1,30 @@
+# Implementation Reference
+
+Read only when a detailed checklist is needed for the current task.
+
+## Progress Recording Example
+
+For a TDD-required task, persist the observed sequence: start; RED with the exact command, non-zero exit code, and failure summary; GREEN with command, zero exit code, and passing summary; final zero-exit verification plus affected project-relative artifacts. If interrupted, status supplies the persisted state and next action; never reconstruct it from conversation history.
+
+## 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.

package/skills/sdd-implement/SKILL.md

@@ -1,302 +1,45 @@
 ---
 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. Backend lifecycle calls are internal; never ask the user to operate raw MCP tools.
 
-## Prerequisites
+## Restore Durable Progress
 
-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`
+1. Internally resolve status and load compact implementation context. Requirements, design, tasks, and any required test-case review must be approved.
+2. If invoked too early or state is blocked, present the persisted blocker and make no workflow or source change.
+3. Internally begin implementation when status requests it. Otherwise follow the returned next action: continue the exact active task, ask the user to select among resumable candidates, or select only a dependency-ready pending task.
+4. Read the approved task, acceptance criteria, design interfaces, and relevant steering before editing. Never infer progress from chat or Markdown checkboxes.
 
-## Implementation 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: Load Context
+## Governed Task Loop
 
-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
+For each selected task, internally record `start` with the exact implementation revision. Then:
 
-### Step 2: Execute TDD Cycle
+1. **RED:** for TDD-required work, write a focused observable test and run it to prove the expected failure. Record the observed command, non-zero exit code, and concise summary before production changes.
+2. **GREEN:** implement only enough to pass and run the focused test. Record the observed command, zero exit code, and summary.
+3. **REFACTOR:** simplify without changing behavior; rerun focused verification.
+4. **COMPLETE:** run final verification. Only after a zero exit code and all acceptance/security checks, record completion with the observed affected project-relative artifacts.
 
-For each task:
+For `not-applicable` TDD tasks, start, implement, verify, then complete with zero-exit verification evidence. If work cannot continue after start, internally record the blocker and reason; do not fabricate evidence. On resume, continue from persisted `in-progress`, `red-observed`, `green-observed`, or `blocked` state without replaying completed transitions. Reread status after every progress record.
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│  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                                  │
-└─────────────────────────────────────────────────────────────┘
-```
+## Mandatory Checks
 
-### Step 3: Apply SOLID Principles
+- Preserve approved interfaces and existing conventions; update every affected caller.
+- Test relevant boundaries, errors, invariants, transitions, and precedence—not implementation plumbing.
+- Validate untrusted input, enforce authorization, avoid injection, protect secrets and sensitive logs, and fail safely.
+- Consider concurrency, cleanup, compatibility, cancellation, rollback, and error propagation where applicable.
+- Run only relevant verification while iterating, then all affected checks. Never fabricate test, coverage, lint, or build results.
 
-#### S - Single Responsibility Principle
-```typescript
-// GOOD: One class, one job
-class UserValidator {
-  validate(user: User): ValidationResult { ... }
-}
+## Output
 
-class UserRepository {
-  save(user: User): Promise<void> { ... }
-}
+Report persisted task numbers/states, observed affected artifacts, RED/GREEN/final verification evidence, security decisions, next action, and blockers. Do not expose backend JSON or present raw MCP operations as user steps.
 
-// BAD: Class doing too much
-class UserManager {
-  validate(user: User) { ... }
-  save(user: User) { ... }
-  sendEmail(user: User) { ... }
-  generateReport() { ... }
-}
-```
+## Optional Reference
 
-#### 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
-
-Apply these steering documents during implementation:
-
-| 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 |
-
-**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
-
-## 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 |
-
-## Specialist Delegation
-
-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 progress examples, SOLID, OWASP, anti-pattern, or completion checklists are needed.

package/skills/sdd-requirements/REFERENCE.md

@@ -0,0 +1,39 @@
+# 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.
+```
+
+## Exact Document Shape
+
+```markdown
+# Requirements: Feature
+
+## Functional Requirements
+
+### FR-1: Observable outcome
+**Objective:** Why this behavior matters.
+**EARS Specification:** WHEN an event occurs THEN the system SHALL produce an observable result.
+**Acceptance Criteria:**
+1. A measurable result is observed.
+
+## Non-functional Requirements
+
+### NFR-1: Bounded quality
+**Objective:** The quality attribute and stakeholder value.
+**EARS Specification:** The system SHALL satisfy a measurable bound.
+**Acceptance Criteria:**
+1. The bound is verified under stated conditions.
+```
+
+## 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,47 @@
 ---
 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
+# SDD Requirements
 
-Generate comprehensive, EARS-formatted requirements documents that integrate with the SDD (Spec-Driven Development) workflow.
+The user invokes this Skill; all MCP calls below are internal. Never ask the user to call a backend tool or expose revision, hash, fingerprint, or backend JSON except in explicit debug output.
 
-## Prerequisites
+## Resolve and Restore
 
-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/`
+1. Internally read status before doing method work.
+2. With a supplied missing feature, internally initialize it from the user's name and complete goal. If clarification is required, present the structured questions, collect answers, and retry initialization. Use the returned canonical feature name.
+3. With no supplied name: ask for a name and goal when no feature exists; resume the sole incomplete feature; when several are incomplete, list them and ask the user to select. Never infer identity from process memory.
+4. Load compact approved context. For a failed or unapproved requirements revision, load that draft only with full mode and explicit unapproved inclusion.
+5. If status reports an observed artifact identity for an orphan or manual edit, read that exact requirements file before revising. Never acknowledge its hash without inspecting and deliberately incorporating or replacing its content.
 
-## Workflow
+If durable state reports a conflict or host permission failure, present an actionable blocker and make no artifact change.
 
-### Step 1: Gather Context
+## Method and Artifact Contract
 
-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`
+1. Identify users, goals, scope, exclusions, constraints, assumptions, dependencies, and measurable success.
+2. Write independently testable EARS requirements. Every requirement uses a unique `### FR-N: ...` or `### NFR-N: ...` section and same-line metadata labels:
+   - `**Objective:** ...`
+   - `**EARS Specification:** ... SHALL ...`
+   - `**Acceptance Criteria:** 1. ...` with at least one numbered item on the same line.
+3. Replace ambiguous words with observable bounds. Include security, privacy, accessibility, compatibility, errors, and performance only when relevant.
+4. Check completeness, consistency, feasibility, traceability, and testability; run gap analysis internally when existing code is in scope.
 
-### Step 2: Analyze 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 a concise validation result. A failed validation is a durable draft: revise it using the observed draft content and identity; do not request approval.
 
-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?
+## Human Gate
 
-### Step 3: Generate EARS-Formatted Requirements
+When validation passes, ask one explicit question: **“Approve these requirements?”** Only an unambiguous affirmative answer in this Skill flow permits the internal approval call for the exact reviewed revision and artifact. Never self-approve or treat host tool permission as approval. After approval, reread status and report the persisted outcome.
 
-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
-
-## 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 unavailable, record one fallback and continue in the parent without retrying or selecting a generic child.
 
-| 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 canonical saved path, key scope 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 `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, exact document shape, 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.