sdd-mcp-server 3.0.1 → 3.1.0

package/hooks/session-end/save-session-summary.md

@@ -0,0 +1,72 @@
+---
+name: save-session-summary
+description: Saves a summary of the session for continuity between sessions
+event: session-end
+priority: 100
+enabled: true
+---
+
+# Save Session Summary Hook
+
+This hook saves a summary of the session when it ends, enabling seamless continuity in future sessions.
+
+## What Gets Saved
+
+1. **Workflow Progress**
+   - Features worked on during session
+   - Phases completed
+   - Tasks implemented
+
+2. **Decisions Made**
+   - Architecture decisions
+   - Implementation choices
+   - Trade-offs considered
+
+3. **Context to Preserve**
+   - Current working state
+   - Pending items
+   - Blockers or questions
+
+## Summary Location
+
+```
+.spec/sessions/
+└── 2024-01-15T10-30-00Z.md
+```
+
+## Summary Format
+
+```markdown
+# Session Summary - 2024-01-15
+
+## Duration
+Started: 10:30 AM | Ended: 2:45 PM (4h 15m)
+
+## Features Worked On
+
+### plugin-architecture-v3
+- Completed: requirements phase approved
+- In Progress: design phase
+- Next: Complete component diagram
+
+### user-authentication
+- Implemented: Tasks 1.1, 1.2, 1.3
+- Tests: 12 new tests, all passing
+- Blockers: Need OAuth provider decision
+
+## Key Decisions
+1. Using BaseManager pattern for all component managers
+2. Hooks organized by event type in nested directories
+3. YAML frontmatter for all component metadata
+
+## Continuation Notes
+- Resume design.md at "Data Flow" section
+- Review OAuth options before next session
+- Run integration tests after completing design
+```
+
+## Benefits
+
+- **Seamless Continuity** - Start next session with full context
+- **Knowledge Preservation** - Decisions and context don't get lost
+- **Progress Tracking** - Clear record of work accomplished

package/hooks/session-start/load-project-context.md

@@ -0,0 +1,62 @@
+---
+name: load-project-context
+description: Loads project context and steering documents at session start
+event: session-start
+priority: 100
+enabled: true
+---
+
+# Load Project Context Hook
+
+This hook loads project-specific context and steering documents when a new session starts.
+
+## Actions
+
+1. **Detect Project Type**
+   - Check for `.spec/steering/` directory
+   - Identify project technology stack
+   - Load appropriate steering documents
+
+2. **Load Steering Documents**
+   ```
+   .spec/steering/
+   ├── PROJECT.md      # Project overview and conventions
+   ├── AGENTS.md       # Agent configuration
+   ├── ARCHITECTURE.md # System architecture
+   └── custom/         # Project-specific guides
+   ```
+
+3. **Restore Workflow State**
+   - Read `.spec/specs/*/spec.json` for active features
+   - Identify current phase for each feature
+   - Surface any incomplete workflows
+
+4. **Set Session Context**
+   - Configure AI persona based on active agent
+   - Apply relevant rules
+   - Activate appropriate context mode
+
+## Session Initialization Message
+
+```
+📋 Project Context Loaded
+
+Project: sdd-mcp
+Type: Node.js/TypeScript
+Active Features:
+  • plugin-architecture-v3 (design phase)
+  • user-authentication (implementation phase)
+
+Steering Documents:
+  ✓ PROJECT.md loaded
+  ✓ AGENTS.md loaded
+  ✓ 3 custom guides loaded
+
+Ready to continue. Run /sdd-status for full workflow state.
+```
+
+## Benefits
+
+- **Consistent Context** - Every session starts with full project understanding
+- **Workflow Continuity** - Pick up where you left off
+- **Best Practices** - Steering documents are always active

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-mcp-server",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "MCP server for spec-driven development workflows across AI-agent CLIs and IDEs",
   "main": "dist/index.js",
   "bin": {
@@ -12,6 +12,10 @@
     "dist/**/*",
     "skills/**/*",
     "steering/**/*",
+    "rules/**/*",
+    "contexts/**/*",
+    "agents/**/*",
+    "hooks/**/*",
     "sdd-entry.js",
     "mcp-server.js",
     "atomicWrite.js",

package/rules/coding-style.md

@@ -0,0 +1,97 @@
+---
+name: coding-style
+description: Enforce consistent TypeScript/JavaScript coding conventions and design principles
+priority: 100
+alwaysActive: true
+---
+
+# Coding Style Rules
+
+## TypeScript/JavaScript Guidelines
+
+### Type Safety
+- Use explicit types for function parameters and return values
+- Avoid `any` type - use `unknown` or proper generics instead
+- Enable strict mode in TypeScript configuration
+
+### Naming Conventions
+- **Classes**: PascalCase (e.g., `UserService`)
+- **Functions/Methods**: camelCase (e.g., `getUserById`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_RETRIES`)
+- **Files**: kebab-case (e.g., `user-service.ts`)
+
+### Functions
+- Keep functions small and focused (single responsibility)
+- Limit function parameters to 3-4; use options object for more
+- Use early returns to reduce nesting
+
+### Code Organization
+- One class per file (with rare exceptions)
+- Keep files under 300 lines when possible
+- Write self-documenting code - minimize inline comments
+
+---
+
+# Core Design Principles
+
+**Golden Rule**: Always ask "Does this code follow SOLID, DRY, KISS, YAGNI?" before committing.
+
+## SOLID Principles
+
+### S - Single Responsibility Principle (SRP)
+A class/module should have one, and only one, reason to change.
+
+### O - Open/Closed Principle (OCP)
+Open for extension, closed for modification. Use interfaces/abstractions.
+
+### L - Liskov Substitution Principle (LSP)
+Derived classes must be substitutable for their base classes.
+
+### I - Interface Segregation Principle (ISP)
+No client should depend on methods it doesn't use. Keep interfaces small.
+
+### D - Dependency Inversion Principle (DIP)
+Depend on abstractions, not concrete implementations. Use dependency injection.
+
+## DRY (Don't Repeat Yourself)
+Every piece of knowledge should have a single, authoritative representation.
+
+## KISS (Keep It Simple)
+Simplicity should be a key goal. Avoid unnecessary complexity.
+
+## YAGNI (You Aren't Gonna Need It)
+Don't implement functionality until it's actually needed.
+
+---
+
+## Code Review Checklist
+
+### SOLID
+- [ ] Does each class/module have a single responsibility?
+- [ ] Can I extend functionality without modifying existing code?
+- [ ] Are interfaces small and focused?
+- [ ] Do dependencies point toward abstractions?
+
+### DRY
+- [ ] Is there any duplicated logic that should be extracted?
+- [ ] Are magic numbers/strings extracted to constants?
+
+### KISS
+- [ ] Is the solution as simple as possible?
+- [ ] Are variable/function names clear without comments?
+
+### YAGNI
+- [ ] Is every feature actually needed now?
+- [ ] Are there "future-proofing" additions that can be removed?
+
+---
+
+## Common Anti-Patterns to Avoid
+
+| Anti-Pattern | Violates | Fix |
+|--------------|----------|-----|
+| God Object/Class | SRP | Split into focused classes |
+| Copy-Paste Programming | DRY | Extract common logic |
+| Premature Optimization | KISS, YAGNI | Optimize when needed |
+| Long Parameter List | KISS | Use parameter objects |
+| Magic Numbers | DRY | Extract to named constants |

package/rules/error-handling.md

@@ -0,0 +1,134 @@
+---
+name: error-handling
+description: Error handling patterns and best practices
+priority: 90
+alwaysActive: true
+---
+
+# Error Handling Rules
+
+## Error Types
+
+### Custom Error Classes
+Define domain-specific errors for better handling:
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string, public field?: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+class NotFoundError extends Error {
+  constructor(resource: string, id: string) {
+    super(`${resource} with id "${id}" not found`);
+    this.name = 'NotFoundError';
+  }
+}
+
+class AuthorizationError extends Error {
+  constructor(action: string) {
+    super(`Not authorized to ${action}`);
+    this.name = 'AuthorizationError';
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Try-Catch Best Practices
+```typescript
+// Good: Specific error handling
+try {
+  await saveUser(user);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    return { status: 400, message: error.message };
+  }
+  if (error instanceof DuplicateError) {
+    return { status: 409, message: 'User already exists' };
+  }
+  // Re-throw unexpected errors
+  throw error;
+}
+
+// Bad: Swallowing all errors
+try {
+  await saveUser(user);
+} catch (error) {
+  console.log('Something went wrong');
+  // Error lost, no recovery, no logging
+}
+```
+
+### Async Error Handling
+```typescript
+// Always use try-catch with async/await
+async function fetchData(): Promise<Data> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new HttpError(response.status, response.statusText);
+    }
+    return await response.json();
+  } catch (error) {
+    logger.error('Failed to fetch data', { error, url });
+    throw error;
+  }
+}
+```
+
+### Error Propagation
+- Let errors bubble up to appropriate handlers
+- Add context when re-throwing
+- Don't catch errors you can't handle
+
+```typescript
+// Good: Add context when re-throwing
+async function processOrder(orderId: string): Promise<void> {
+  try {
+    await validateOrder(orderId);
+    await chargePayment(orderId);
+    await fulfillOrder(orderId);
+  } catch (error) {
+    throw new OrderProcessingError(
+      `Failed to process order ${orderId}`,
+      { cause: error }
+    );
+  }
+}
+```
+
+## Logging Errors
+
+### What to Log
+- Error message and stack trace
+- Request/operation context
+- User identifier (not PII)
+- Timestamp
+
+### What NOT to Log
+- Passwords or tokens
+- Personal identifiable information (PII)
+- Full credit card numbers
+- Internal implementation details in production
+
+### Log Levels
+- **ERROR**: Unexpected failures requiring attention
+- **WARN**: Handled issues that may indicate problems
+- **INFO**: Normal operations, significant events
+- **DEBUG**: Detailed information for troubleshooting
+
+## User-Facing Errors
+
+### Never Expose
+- Stack traces
+- Database errors
+- Internal paths
+- Implementation details
+
+### Always Provide
+- Clear, actionable message
+- Error code for support reference
+- Next steps when possible

package/rules/git-workflow.md

@@ -0,0 +1,92 @@
+---
+name: git-workflow
+description: Git commit and branching conventions
+priority: 80
+alwaysActive: true
+---
+
+# Git Workflow Rules
+
+## Commit Messages
+
+### Format
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+- **feat**: New feature
+- **fix**: Bug fix
+- **docs**: Documentation only changes
+- **style**: Code style changes (formatting, semicolons)
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **perf**: Performance improvement
+- **test**: Adding or updating tests
+- **chore**: Build process or auxiliary tool changes
+
+### Subject Line
+- Use imperative mood ("add" not "added")
+- No period at the end
+- Maximum 50 characters
+- Capitalize first letter
+
+### Body
+- Explain "what" and "why", not "how"
+- Wrap at 72 characters
+- Separate from subject with blank line
+
+### Examples
+```
+feat(auth): add JWT token refresh endpoint
+
+Implement automatic token refresh to improve user experience.
+Tokens are refreshed 5 minutes before expiration.
+
+Closes #123
+```
+
+```
+fix(api): handle null response from external service
+
+The external payment API occasionally returns null instead of
+an error object. This caused unhandled exceptions in production.
+
+Fixes #456
+```
+
+## Branching Strategy
+
+### Branch Types
+- **main/master**: Production-ready code
+- **develop**: Integration branch for features
+- **feature/**: New features (`feature/add-user-auth`)
+- **fix/**: Bug fixes (`fix/login-validation`)
+- **refactor/**: Code refactoring (`refactor/better-architecture`)
+
+### Branch Naming
+- Use lowercase with hyphens
+- Include ticket number if applicable
+- Keep names descriptive but concise
+
+## Pull Requests
+
+### Before Creating PR
+- Rebase on latest target branch
+- Run all tests locally
+- Update documentation if needed
+- Self-review your changes
+
+### PR Description
+- Reference related issues
+- Describe what changed and why
+- Include testing instructions
+- Add screenshots for UI changes
+
+### Review Process
+- Address all review comments
+- Don't force-push after review started
+- Squash commits when merging (if team policy)

package/rules/sdd-workflow.md

@@ -0,0 +1,116 @@
+---
+name: sdd-workflow
+description: Spec-Driven Development process rules
+priority: 85
+alwaysActive: true
+---
+
+# SDD Workflow Rules
+
+## Spec-Driven Development Process
+
+### Phase Order
+Follow the SDD phases in strict order:
+
+1. **Initialize** (`sdd-init`)
+   - Define feature name and description
+   - Answer clarification questions
+   - Create spec directory structure
+
+2. **Requirements** (`sdd-requirements`)
+   - Generate EARS-formatted requirements
+   - Define acceptance criteria
+   - Identify constraints and assumptions
+
+3. **Design** (`sdd-design`)
+   - Create technical design specifications
+   - Define component architecture
+   - Document interfaces and data flows
+
+4. **Tasks** (`sdd-tasks`)
+   - Break down into implementable tasks
+   - Apply TDD methodology
+   - Estimate complexity
+
+5. **Implement** (`sdd-implement`)
+   - Follow TDD (Red-Green-Refactor)
+   - Reference steering documents
+   - Update spec status
+
+## EARS Requirements Format
+
+Use Easy Approach to Requirements Syntax:
+
+| Pattern | Template | Use Case |
+|---------|----------|----------|
+| Ubiquitous | The `<system>` SHALL `<action>` | Always true |
+| Event-Driven | WHEN `<trigger>` THEN the `<system>` SHALL `<action>` | Response to event |
+| State-Driven | WHILE `<state>` THE `<system>` SHALL `<action>` | During state |
+| Optional | WHERE `<feature>` THE `<system>` SHALL `<action>` | Configurable |
+| Unwanted | IF `<condition>` THEN the `<system>` SHALL `<action>` | Exception |
+
+### Example
+```markdown
+## FR-1: User Authentication
+WHEN a user submits valid credentials
+THEN the system SHALL authenticate the user and return a session token
+
+**Acceptance Criteria:**
+1. Token expires after 24 hours of inactivity
+2. Invalid credentials return 401 error
+3. Rate limiting prevents brute force attempts
+```
+
+## Steering Documents
+
+### Always Reference
+- `.spec/steering/tdd-guideline.md` - TDD methodology
+- `.spec/steering/principles.md` - SOLID, DRY, KISS, YAGNI
+- `.spec/steering/linus-review.md` - Code review standards
+
+### When to Reference
+- Before writing any code, review relevant steering docs
+- During code review, verify compliance
+- When refactoring, ensure principles are maintained
+
+## Approval Gates
+
+### Requirements Approval
+Before proceeding to design:
+- [ ] All requirements use EARS format
+- [ ] Each requirement is testable
+- [ ] Acceptance criteria are specific
+- [ ] Constraints are documented
+
+### Design Approval
+Before proceeding to tasks:
+- [ ] Architecture diagram included
+- [ ] Interfaces defined
+- [ ] Dependencies identified
+- [ ] Security considerations addressed
+
+### Tasks Approval
+Before proceeding to implementation:
+- [ ] Tasks follow TDD structure
+- [ ] Complexity estimated
+- [ ] Dependencies mapped
+- [ ] Steering doc references included
+
+## Spec File Locations
+
+```
+.spec/
+├── steering/          # Project-wide rules
+│   ├── product.md
+│   ├── tech.md
+│   ├── structure.md
+│   ├── tdd-guideline.md
+│   ├── principles.md
+│   └── linus-review.md
+└── specs/             # Feature specifications
+    └── {feature-name}/
+        ├── spec.json
+        ├── requirements.md
+        ├── design.md
+        └── tasks.md
+```

package/rules/security.md

@@ -0,0 +1,89 @@
+---
+name: security
+description: Security best practices aligned with OWASP Top 10
+priority: 99
+alwaysActive: true
+---
+
+# Security Rules
+
+## OWASP Top 10 Alignment
+
+### A01: Broken Access Control
+- Implement proper authentication checks before sensitive operations
+- Use principle of least privilege for permissions
+- Validate user authorization for every request
+- Never expose internal IDs directly to users
+
+### A02: Cryptographic Failures
+- Never store passwords in plain text - use bcrypt or similar
+- Use HTTPS for all external communications
+- Don't hardcode secrets in source code
+- Use secure random number generators for tokens
+
+### A03: Injection
+- Always use parameterized queries for database operations
+- Validate and sanitize all user inputs
+- Escape output data appropriately for context (HTML, SQL, etc.)
+- Never use `eval()` or similar dynamic code execution
+
+### A04: Insecure Design
+- Apply defense in depth - multiple layers of security
+- Implement rate limiting for APIs
+- Design with security in mind from the start
+- Use secure defaults
+
+### A05: Security Misconfiguration
+- Disable unnecessary features and services
+- Keep dependencies updated
+- Remove default credentials
+- Configure proper error handling (no stack traces in production)
+
+### A06: Vulnerable Components
+- Regularly audit and update dependencies
+- Use `npm audit` or similar tools
+- Pin dependency versions in production
+- Monitor security advisories
+
+### A07: Authentication Failures
+- Implement strong password policies
+- Use multi-factor authentication where possible
+- Protect against brute force attacks
+- Secure session management
+
+### A08: Data Integrity Failures
+- Validate data integrity with checksums
+- Use code signing for releases
+- Verify software updates are from trusted sources
+
+### A09: Logging Failures
+- Log security-relevant events
+- Never log sensitive data (passwords, tokens, PII)
+- Ensure logs are tamper-proof
+- Monitor logs for suspicious activity
+
+### A10: Server-Side Request Forgery (SSRF)
+- Validate and sanitize URLs before making requests
+- Use allowlists for external services
+- Don't expose internal services to user-controlled URLs
+
+## Code Security Practices
+
+### Input Validation
+```typescript
+// Always validate user input
+function processUserInput(input: unknown): ValidatedInput {
+  if (typeof input !== 'string') {
+    throw new ValidationError('Input must be a string');
+  }
+  if (input.length > MAX_INPUT_LENGTH) {
+    throw new ValidationError('Input too long');
+  }
+  return sanitize(input);
+}
+```
+
+### Error Handling
+- Never expose internal errors to users
+- Log errors with context for debugging
+- Return generic error messages to clients