sdd-mcp-server 3.0.1 → 3.1.0

package/rules/testing.md

@@ -0,0 +1,85 @@
+---
+name: testing
+description: Testing requirements and best practices
+priority: 95
+alwaysActive: true
+---
+
+# Testing Rules
+
+## Test-Driven Development (TDD)
+
+Follow the Red-Green-Refactor cycle:
+1. **RED**: Write a failing test that defines expected behavior
+2. **GREEN**: Write minimum code to make the test pass
+3. **REFACTOR**: Clean up code while keeping tests green
+
+## Test Organization
+
+### File Structure
+- Test files should mirror source structure
+- Name test files as `{source-file}.test.ts`
+- Group tests in `__tests__` directories or alongside source files
+
+### Test Structure
+```typescript
+describe('ComponentName', () => {
+  describe('methodName', () => {
+    it('should describe expected behavior', () => {
+      // Arrange - Set up test data
+      // Act - Execute the code
+      // Assert - Verify results
+    });
+  });
+});
+```
+
+## Test Quality
+
+### Test Naming
+- Use descriptive names that explain the scenario
+- Pattern: `should {expected behavior} when {condition}`
+- Examples:
+  - `should return empty array when directory is empty`
+  - `should throw error for invalid input`
+
+### Test Independence
+- Each test should be independent and isolated
+- Use `beforeEach` to reset state between tests
+- Never rely on test execution order
+
+### Assertions
+- One logical assertion per test (can have multiple `expect` calls)
+- Test behavior, not implementation
+- Include both positive and negative test cases
+
+## Coverage Requirements
+
+### Minimum Coverage
+- Aim for 80% code coverage for new code
+- Critical paths require 100% coverage
+- Cover edge cases and error conditions
+
+### What to Test
+- Public API methods
+- Edge cases and boundary conditions
+- Error handling paths
+- Integration points
+
+### What Not to Test
+- Third-party library internals
+- Simple getters/setters without logic
+- Framework-generated code
+
+## Mocking
+
+### When to Mock
+- External services and APIs
+- File system operations
+- Network requests
+- Time-dependent code
+
+### Mock Best Practices
+- Mock at the boundary, not internal implementation
+- Verify mock interactions when relevant
+- Reset mocks in `beforeEach`

package/sdd-entry.js

@@ -12,7 +12,7 @@
  *   npx sdd-mcp-server                     # MCP: Start MCP server
  */
 
-const CLI_COMMANDS = ['install', 'install-skills', 'migrate-kiro'];
+const CLI_COMMANDS = ['install', 'install-skills', 'migrate-kiro', 'migrate-steering'];
 const args = process.argv.slice(2);
 const command = args[0];
 

package/skills/sdd-commit/SKILL.md

@@ -271,20 +271,6 @@ git rebase origin/main
 git push origin feature/AUTH-123-jwt-auth
 ```
 
-## Steering Document References
-
-Apply these steering documents for commits and PRs:
-
-| Document | Purpose | Key Application |
-|----------|---------|-----------------|
-| `.spec/steering/commit.md` | Commit message conventions | Follow type prefixes, scope, and format guidelines |
-
-**Key Commit Rules:**
-1. Use type prefixes: `feat`, `fix`, `docs`, `refactor`, `test`, etc.
-2. Keep subject line under 72 characters
-3. Use imperative mood ("add" not "added")
-4. Reference issues in footer
-
 ## Quality Checklist
 
 - [ ] Commit message follows format

package/steering/product.md

@@ -0,0 +1,29 @@
+# Product Overview
+
+## Product Description
+<!-- Describe your product/project in 1-2 sentences -->
+
+**Project**: <!-- project name -->
+**Version**: <!-- current version -->
+**Type**: <!-- Web App, CLI Tool, Library, API, etc. -->
+
+## Core Features
+<!-- List the main features of your product -->
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Target Use Case
+<!-- Describe the primary use case this product solves -->
+
+## Key Value Proposition
+<!-- What makes this product valuable? What problems does it solve? -->
+
+## Target Users
+<!-- Who are the primary users of this product? -->
+
+## Success Metrics
+<!-- How do you measure success for this product? -->
+
+## Technical Advantages
+<!-- What technical benefits does this architecture provide? -->

package/steering/structure.md

@@ -0,0 +1,60 @@
+# Project Structure
+
+## Directory Organization
+```
+├── src/                    # Source code
+│   ├── components/        # UI components (if applicable)
+│   ├── services/          # Business logic services
+│   ├── models/            # Data models
+│   ├── utils/             # Utility functions
+│   └── index.ts           # Entry point
+├── tests/                  # Test files
+│   ├── unit/              # Unit tests
+│   └── integration/       # Integration tests
+├── dist/                   # Build output
+├── docs/                   # Documentation
+├── .spec/                  # SDD workflow files
+│   ├── steering/          # Project steering documents
+│   └── specs/             # Feature specifications
+├── package.json            # Project configuration
+├── tsconfig.json           # TypeScript configuration (if applicable)
+└── README.md               # Project documentation
+```
+
+## Key Directories
+- **src/**: Main source code directory
+- **tests/**: Test files organized by type
+- **dist/**: Compiled/built output for production
+- **docs/**: Project documentation
+
+## Code Organization Patterns
+<!-- Describe how code is organized -->
+- Pattern 1
+- Pattern 2
+
+## File Naming Conventions
+<!-- Define naming conventions for different file types -->
+- **Source files**: <!-- e.g., kebab-case.ts -->
+- **Test files**: <!-- e.g., *.test.ts or *.spec.ts -->
+- **Configuration**: <!-- e.g., .json or .config.js -->
+- **Constants**: UPPER_SNAKE_CASE
+- **Functions/Variables**: camelCase
+- **Classes/Types**: PascalCase
+
+## Module Organization
+<!-- Describe how modules are organized -->
+
+## Architectural Principles
+- **Separation of Concerns**: Each module handles a specific responsibility
+- **Type Safety**: Use strong typing where applicable
+- **Dependency Inversion**: Depend on abstractions, not concrete implementations
+
+## Testing Structure
+- **Unit tests**: Test individual functions/components in isolation
+- **Integration tests**: Test interactions between modules
+- **E2E tests**: Test complete user workflows
+
+## Build Output
+- **Command**: <!-- e.g., npm run build -->
+- **Output directory**: <!-- e.g., dist/ -->
+- **Artifacts**: <!-- What gets generated -->

package/steering/tech.md

@@ -0,0 +1,52 @@
+# Technology Stack
+
+## Architecture
+**Type**: <!-- MVC, DDD, Clean Architecture, Microservices, etc. -->
+**Language**: <!-- Primary language -->
+**Module System**: <!-- CommonJS, ES Module, etc. -->
+**Framework**: <!-- Main framework if any -->
+**Build Tool**: <!-- Webpack, Vite, TypeScript Compiler, etc. -->
+
+## Core Technologies
+<!-- List main technologies used -->
+- **Runtime**: <!-- Node.js, Python, Go, etc. -->
+- **Language**: <!-- TypeScript, JavaScript, Python, etc. -->
+- **Framework**: <!-- Express, FastAPI, Spring Boot, etc. -->
+- **Testing**: <!-- Jest, pytest, JUnit, etc. -->
+
+## Development Environment
+- **Runtime Version**: <!-- e.g., Node.js >=18.0.0 -->
+- **Package Manager**: <!-- npm, yarn, pip, etc. -->
+- **Testing Framework**: <!-- Jest, pytest, etc. -->
+
+## Dependencies
+### Production Dependencies
+<!-- List key production dependencies -->
+
+### Development Dependencies
+<!-- List key development dependencies -->
+
+## Development Commands
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run tests
+npm run test
+
+# Lint code
+npm run lint
+```
+
+## Quality Assurance
+- **Linting**: <!-- ESLint, Pylint, etc. -->
+- **Type Checking**: <!-- TypeScript, mypy, etc. -->
+- **Testing**: <!-- Coverage requirements, test types -->
+
+## Deployment Configuration
+- **Containerization**: <!-- Docker, Kubernetes, etc. -->
+- **Build Process**: <!-- How to build for production -->
+- **CI/CD**: <!-- GitHub Actions, GitLab CI, etc. -->

package/steering/AGENTS.md

@@ -1,281 +0,0 @@
-# AI Agents Integration Guide
-
-## Purpose
-This document defines how AI agents should interact with the SDD workflow and provides guidelines for effective agent collaboration in spec-driven development.
-
-## Agent Types and Roles
-
-### Development Agents
-AI agents that assist with code implementation, testing, and documentation.
-
-**Primary Tools**: Claude Code, Cursor, GitHub Copilot, and similar AI development assistants.
-
-**Responsibilities**:
-- Follow SDD workflow phases strictly
-- Generate code based on approved specifications
-- Maintain consistency with project steering documents
-- Ensure quality through automated testing
-
-### Review Agents
-AI agents specialized in code review, quality analysis, and security validation.
-
-**Primary Focus**:
-- Apply Linus-style code review principles
-- Validate implementation against requirements
-- Check for security vulnerabilities
-- Ensure performance standards
-
-### Planning Agents
-AI agents that help with requirements gathering, design decisions, and task breakdown.
-
-**Primary Activities**:
-- Analyze project requirements using EARS format
-- Generate technical design documents
-- Create implementation task breakdowns
-- Validate workflow phase transitions
-
-## Agent Communication Protocol
-
-### Context Sharing
-All agents must:
-1. Load project steering documents at interaction start:
-   - `product.md` - Product context and business objectives
-   - `tech.md` - Technology stack and architectural decisions
-   - `structure.md` - File organization and code patterns
-   - `linus-review.md` - Code quality review principles
-   - `commit.md` - Commit message standards
-   - **`owasp-top10-check.md` - OWASP Top 10 security checklist (REQUIRED for code generation and review)**
-   - **`tdd-guideline.md` - Test-Driven Development workflow (REQUIRED for all new features)**
-   - **`principles.md` - Core coding principles (SOLID, DRY, KISS, YAGNI, Separation of Concerns, Modularity)**
-2. Check current workflow phase before proceeding
-3. Validate approvals before phase transitions
-4. Update spec.json with progress tracking
-
-### Information Flow
-```
-User Request → Agent Analysis → SDD Tool Invocation → Result Validation → User Response
-```
-
-### State Management
-- Agents must maintain awareness of current project state
-- Phase transitions require explicit approval tracking
-- All changes must be logged in spec.json metadata
-
-## Agent Tool Usage
-
-### Required Tools for All Agents
-- `sdd-status`: Check current workflow state
-- `sdd-context-load`: Load project context
-- `sdd-quality-check`: Validate code quality
-
-### Phase-Specific Tools
-
-**Initialization Phase**:
-- `sdd-init`: Create new project structure
-- `sdd-steering`: Generate steering documents
-
-**Requirements Phase**:
-- `sdd-requirements`: Generate requirements document
-- `sdd-validate-gap`: Analyze implementation gaps
-
-**Design Phase**:
-- `sdd-design`: Create technical design
-- `sdd-validate-design`: Review design quality
-
-**Tasks Phase**:
-- `sdd-tasks`: Generate task breakdown
-- `sdd-spec-impl`: Execute tasks with TDD
-
-**Implementation Phase**:
-- `sdd-implement`: Get implementation guidelines
-- `sdd-quality-check`: Continuous quality validation
-
-## Agent Collaboration Patterns
-
-### Sequential Collaboration
-Agents work in sequence through workflow phases:
-```
-Planning Agent → Design Agent → Implementation Agent → Review Agent
-```
-
-### Parallel Collaboration
-Multiple agents work on different aspects simultaneously:
-- Frontend Agent handles UI tasks
-- Backend Agent handles API tasks
-- Test Agent creates test suites
-- Documentation Agent updates docs
-
-### Feedback Loops
-Agents provide feedback to improve specifications:
-- Implementation issues feed back to design
-- Test failures inform requirement updates
-- Performance problems trigger architecture reviews
-
-## Quality Standards for Agents
-
-### Code Generation Standards
-- Follow project coding conventions from structure.md
-- Implement comprehensive error handling
-- Include appropriate logging and monitoring
-- Write self-documenting code with clear naming
-
-### Testing Requirements
-- Generate unit tests for all new functions
-- Create integration tests for workflows
-- Implement performance benchmarks
-- Ensure test coverage meets project standards
-
-### Documentation Expectations
-- Update relevant documentation with changes
-- Maintain clear commit messages following commit.md
-- Document design decisions and trade-offs
-- Keep README and API docs current
-
-## Agent Configuration
-
-### Environment Setup
-Agents should configure their environment with:
-```bash
-# Load SDD MCP server
-npx sdd-mcp-server
-
-# Initialize project context
-sdd-context-load [feature-name]
-
-# Check current status
-sdd-status [feature-name]
-```
-
-### Steering Document Loading
-Agents must respect steering document modes:
-- **Always**: Load for every interaction
-- **Conditional**: Load based on file patterns
-- **Manual**: Load when explicitly requested
-
-### Tool Invocation Patterns
-```javascript
-// Check phase before proceeding
-const status = await sdd-status(featureName);
-
-// Validate requirements exist
-if (!status.requirements.generated) {
-  await sdd-requirements(featureName);
-}
-
-// Proceed with implementation
-await sdd-implement(featureName);
-```
-
-## Best Practices for AI Agents
-
-### 1. Context Awareness
-- Always load full project context before making changes
-- Understand the current workflow phase and requirements
-- Check for existing implementations before creating new ones
-
-### 2. Incremental Progress
-- Complete one task fully before moving to the next
-- Update task checkboxes in tasks.md as work progresses
-- Commit changes frequently with clear messages
-
-### 3. Quality Focus
-- Run quality checks after each significant change
-- Address issues immediately rather than accumulating debt
-- **Follow TDD principles strictly: Red → Green → Refactor**
-  - **RED**: Write failing tests BEFORE any implementation
-  - **GREEN**: Write minimal code to make tests pass
-  - **REFACTOR**: Improve code quality while keeping tests green
-  - Refer to `.spec/steering/tdd-guideline.md` for complete TDD workflow
-
-### 4. Communication Clarity
-- Provide clear explanations for design decisions
-- Document assumptions and constraints
-- Report blockers and issues promptly
-
-### 5. Workflow Compliance
-- Never skip workflow phases
-- Ensure approvals are in place before proceeding
-- Maintain traceability from requirements to implementation
-
-## Error Handling for Agents
-
-### Common Issues and Solutions
-
-**Phase Violation**: Attempting to skip workflow phases
-- Solution: Follow the prescribed phase sequence
-- Use `sdd-status` to check current phase
-
-**Missing Context**: Operating without project understanding
-- Solution: Load context with `sdd-context-load`
-- Review steering documents before proceeding
-
-**Quality Failures**: Code doesn't meet standards
-- Solution: Run `sdd-quality-check` regularly
-- Apply Linus-style review principles
-
-**Integration Conflicts**: Changes break existing functionality
-- Solution: Run comprehensive tests before committing
-- Ensure backward compatibility
-
-## Performance Guidelines
-
-### Efficiency Standards
-- Minimize redundant tool invocations
-- Cache project context when possible
-- Batch related operations together
-
-### Resource Management
-- Clean up temporary files after operations
-- Limit concurrent file operations
-- Optimize for large codebases
-
-## Security Considerations
-
-### Code Review Security
-- Check for credential exposure
-- Validate input sanitization
-- Review authentication/authorization logic
-- Identify potential injection vulnerabilities
-
-### Data Handling
-- Never commit sensitive data
-- Use environment variables for configuration
-- Implement proper encryption for sensitive operations
-- Follow least privilege principles
-
-## Integration with CI/CD
-
-### Automated Workflows
-Agents should support CI/CD integration:
-- Trigger quality checks on commits
-- Validate phase requirements in pipelines
-- Generate reports for review processes
-- Update documentation automatically
-
-### Deployment Readiness
-Before deployment, agents must ensure:
-- All tests pass successfully
-- Documentation is complete and current
-- Quality standards are met
-- Security scans show no critical issues
-
-## Continuous Improvement
-
-### Learning from Feedback
-- Analyze failed implementations
-- Update patterns based on successes
-- Refine task estimation accuracy
-- Improve requirement interpretation
-
-### Metrics and Monitoring
-Track agent performance metrics:
-- Task completion accuracy
-- Code quality scores
-- Time to implementation
-- Defect rates post-deployment
-
-## Conclusion
-
-AI agents are integral to the SDD workflow, providing automation and intelligence throughout the development lifecycle. By following these guidelines, agents can effectively collaborate to deliver high-quality, specification-compliant software while maintaining the rigor and discipline of spec-driven development.
-
-Remember: Agents augment human decision-making but don't replace it. Critical decisions, approvals, and architectural choices should always involve human oversight.

package/steering/commit.md

@@ -1,59 +0,0 @@
-# Commit Message Guidelines
-
-Commit messages should follow a consistent format to improve readability and provide clear context about changes. Each commit message should start with a type prefix that indicates the nature of the change.
-
-## Format
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-## Type Prefixes
-
-All commit messages must begin with one of these type prefixes:
-
-- **docs**: Documentation changes (README, comments, etc.)
-- **chore**: Maintenance tasks, dependency updates, etc.
-- **feat**: New features or enhancements
-- **fix**: Bug fixes
-- **refactor**: Code changes that neither fix bugs nor add features
-- **test**: Adding or modifying tests
-- **style**: Changes that don't affect code functionality (formatting, whitespace)
-- **perf**: Performance improvements
-- **ci**: Changes to CI/CD configuration files and scripts
-
-## Scope (Optional)
-
-The scope provides additional context about which part of the codebase is affected:
-
-- **cluster**: Changes to EKS cluster configuration
-- **db**: Database-related changes
-- **iam**: Identity and access management changes
-- **net**: Networking changes (VPC, security groups, etc.)
-- **k8s**: Kubernetes resource changes
-- **module**: Changes to reusable Terraform modules
-
-## Examples
-
-```
-feat(cluster): add node autoscaling for billing namespace
-fix(db): correct MySQL parameter group settings
-docs(k8s): update network policy documentation
-chore: update terraform provider versions
-refactor(module): simplify EKS node group module
-```
-
-## Best Practices
-
-1. Keep the subject line under 72 characters
-2. Use imperative mood in the subject line ("add" not "added")
-3. Don't end the subject line with a period
-4. Separate subject from body with a blank line
-5. Use the body to explain what and why, not how
-6. Reference issues and pull requests in the footer
-
-These guidelines help maintain a clean and useful git history that makes it easier to track changes and understand the project's evolution.