sdd-mcp-server 3.0.2 → 3.1.0

package/README.md

@@ -6,27 +6,7 @@
 
 A Model Context Protocol (MCP) server implementing Spec-Driven Development (SDD) workflows for AI-agent CLIs and IDEs like Claude Code, Cursor, and others.
 
-> 🚀 **v3.0.0 - Comprehensive Plugin Architecture**: SDD-MCP is now a full-featured Claude Code plugin system! Adds **6 component types** (skills, steering, rules, contexts, agents, hooks), **4 new managers** (RulesManager, ContextManager, AgentManager, HookLoader), and **3 new skills** (sdd-review, sdd-security-check, sdd-test-gen). Unified install CLI supports `--rules`, `--contexts`, `--agents`, `--hooks`, `--all` flags. Inspired by everything-claude-code architecture.
-
-> 🔧 **v2.2.1 - CLI Fix**: Fixed `npx sdd-mcp` not working due to npm package name collision. Now use `npx sdd-mcp-server` for all CLI commands. The unified entry point handles both CLI commands and MCP server mode.
-
-> 🎯 **v2.2.0 - Unified Installation & Crash Safety**: `npx sdd-mcp-server install` command installs both skills (to `.claude/skills/`) AND steering documents (to `.spec/steering/`) in one step! Skills now explicitly reference their relevant steering documents for better guidance. Also includes **atomic file writes** for spec.json crash safety - files are never left in a corrupted state even if the process is interrupted. (Thanks to @Lucas Wang for the atomic writes contribution!)
-
-> 🔄 **v2.1.0 - Directory Migration**: The SDD specification directory has been renamed from `.kiro` to `.spec`. Use `npx sdd-mcp-server migrate-kiro` to migrate existing projects. Legacy `.kiro` directories are still supported for backwards compatibility.
-
-> 🔧 **v2.0.3 - CLI Subcommand Support**: `npx sdd-mcp-server install-skills` now works correctly! Created proper CLI entry point with subcommand support.
-
-> 🚀 **v2.0.0 - Hybrid MCP + Agent Skills Architecture**: Restructured for token efficiency! Template/guidance tools (requirements, design, tasks, steering, implement) are now **Claude Code Agent Skills** loaded on-demand. Action-oriented tools remain as MCP tools. ~55% token savings in typical operations.
-
-> 🤖 **v1.8.0 - MCP Tool Standardization**: Updated `AGENTS.md` generation to use standard MCP tool calls (e.g., `sdd-init`) instead of legacy slash commands. Fixed `sdd-steering` to correctly generate `AGENTS.md` with the new format. Ensures consistent tool usage across all AI agents.
-
-> 🔧 **v1.6.2 - Module Loading Fix**: Fixed critical bug where `sdd-steering` generated generic templates instead of analyzing actual codebases when run via `npx`. Root cause: hardcoded import paths didn't account for different execution contexts. Solution: Unified module loading system with **4-path fallback resolution** handling npm start, npm dev, node dist/index.js, and npx contexts. Comprehensive error handling with all attempted paths in error messages. Debug logging for troubleshooting. **100% test coverage** (71 tests passing, 6 new moduleLoader tests). Code review score: **9/10 (Excellent)** ✅. Production-ready with zero security issues!
-
-> 🚀 **v1.6.0 - Architecture Refactoring**: Decomposed requirements clarification into **5 focused services** following Single Responsibility Principle! Each service now has one clear purpose: `SteeringContextLoader` (I/O), `DescriptionAnalyzer` (scored semantic detection 0-100), `QuestionGenerator` (template-based), `AnswerValidator` (validation + security), `DescriptionEnricher` (5W1H synthesis). Replaced brittle boolean regex with **scored semantic detection** for better accuracy. Externalized question templates to configuration. **62 new unit tests** (65 total passing) ✅. Services average ~100 LOC vs previous 500 LOC monolith. Better maintainability, testability, and type safety!
-
-> 🎯 **v1.5.0 - Interactive Requirements Clarification**: `sdd-init` now **blocks vague requirements**! The agent analyzes your project description (quality score 0-100) and interactively asks targeted clarification questions if score < 70%. Focuses on **WHY** (business justification), WHO (target users), WHAT (core features), and success criteria. Context-aware using existing steering docs. Prevents "garbage in, garbage out" with enriched 5W1H structured descriptions.
-
-> ✅ **v1.4.5**: Internal improvements! Reorganized test structure for better maintainability, centralized static steering document creation following DRY principle, improved code organization with better separation of concerns.
+> **v3.1** - Steering consolidation: Static guidance merged into agents/rules/skills. Now with `migrate-steering` CLI command. See [CHANGELOG.md](CHANGELOG.md) for full version history.
 
 ## 🚀 Quick Start
 
@@ -198,12 +178,92 @@ npx sdd-mcp-server install-skills
 | Component | Install Path | Purpose |
 |-----------|--------------|---------|
 | **Skills** | `.claude/skills/` | Workflow guidance (requirements, design, tasks, implement, etc.) |
-| **Steering** | `.spec/steering/` | Project-wide conventions (TDD guidelines, SOLID principles, security) |
+| **Steering** | `.spec/steering/` | Project-specific templates (product, tech, structure) |
 | **Rules** | `.claude/rules/` | Always-active guidelines (coding-style, testing, security, git-workflow) |
 | **Contexts** | `.claude/contexts/` | Mode-specific prompts (dev, review, planning, security-audit, research) |
 | **Agents** | `.claude/agents/` | Specialized AI personas (planner, architect, reviewer, implementer) |
 | **Hooks** | `.claude/hooks/` | Event-driven automation (pre-tool-use, post-tool-use, session events) |
 
+### Component Architecture & Relationships
+
+The 6 component types work together in a **layered guidance model**:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     User Request                             │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  HOOKS (pre-tool-use)                                        │
+│  • Validate workflow order (e.g., requirements before design)│
+│  • Check test coverage before implementation                 │
+│  • Triggered automatically on events                         │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  RULES (always active)                                       │
+│  • coding-style.md → TypeScript/JS conventions               │
+│  • testing.md → TDD requirements                             │
+│  • security.md → OWASP guidelines                            │
+│  • Loaded at session start, apply to ALL operations          │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  CONTEXTS (mode-specific)                                    │
+│  • dev.md → Implementation focus                             │
+│  • review.md → Quality focus                                 │
+│  • planning.md → Architecture focus                          │
+│  • Activated based on current task type                      │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  AGENTS (specialized personas)                               │
+│  • reviewer.md → Linus-style code review                     │
+│  • architect.md → System design expertise                    │
+│  • implementer.md → TDD implementation                       │
+│  • Invoked for specific expertise needs                      │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  SKILLS (on-demand workflows)                                │
+│  • /sdd-requirements → EARS requirements template            │
+│  • /sdd-design → Architecture design template                │
+│  • /sdd-implement → Implementation checklist                 │
+│  • User-invoked via slash commands                           │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  STEERING (project-specific templates - v3.1+)               │
+│  • product.md → Product description                          │
+│  • tech.md → Technology stack                                │
+│  • structure.md → Project structure                          │
+│  • (Static guidance now in agents/rules/skills)              │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  MCP TOOLS (actions)                                         │
+│  • sdd-init, sdd-approve, sdd-status, sdd-spec-impl          │
+│  • Execute actual operations                                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**When Each Component Activates:**
+| Component | Activation | Example |
+|-----------|------------|---------|
+| **Rules** | Session start (always) | `coding-style.md` enforces conventions on every response |
+| **Contexts** | Task type detection | `review.md` activates when reviewing code |
+| **Agents** | Explicit invocation | `reviewer.md` invoked by `/sdd-review` skill |
+| **Skills** | User command (`/skill-name`) | `/sdd-requirements` loads requirements template |
+| **Steering** | Project customization | `/sdd-steering` generates `product.md`, `tech.md` |
+| **Hooks** | Events (pre/post tool, session) | `validate-sdd-workflow` runs before `sdd-design` |
+
 ### Migrating from .kiro to .spec (v2.1.0+)
 
 If you have existing projects using the legacy `.kiro` directory, migrate to the new `.spec` standard:
@@ -221,6 +281,27 @@ npx sdd-mcp-server migrate-kiro --path ./my-project
 
 **Note**: Legacy `.kiro` directories are still supported for backwards compatibility, but new projects will use `.spec`.
 
+### Migrating Steering Documents (v3.1.0+)
+
+If you have existing projects with static steering documents, migrate to the new consolidated architecture:
+
+```bash
+# Preview migration (dry run)
+npx sdd-mcp-server migrate-steering --dry-run
+
+# Perform migration (backs up existing steering first)
+npx sdd-mcp-server migrate-steering
+
+# Migrate a specific project
+npx sdd-mcp-server migrate-steering --path ./my-project
+```
+
+**What this does:**
+- Backs up existing `.spec/steering/` to `.spec/steering.backup/`
+- Removes static steering docs (principles.md, tdd-guideline.md, linus-review.md, etc.)
+- Preserves project-specific templates (product.md, tech.md, structure.md)
+- The static content now lives in enhanced `.claude/` components
+
 ### Available Skills
 
 After installation, use these skills in Claude Code:
@@ -321,77 +402,6 @@ Once connected to your AI client, you can use these MCP tools:
    Use sdd-context-load to restore project memory
    ```
 
-## Latest Updates (v3.0.0)
-
-**What's New - Comprehensive Plugin Architecture**:
-- 🚀 **6 Component Types**: Skills, Steering, Rules, Contexts, Agents, Hooks
-- 🤖 **4 New Managers**: RulesManager, ContextManager, AgentManager, HookLoader
-- ✨ **3 New Skills**: sdd-review (Linus-style review), sdd-security-check (OWASP audit), sdd-test-gen (TDD)
-- 🎯 **Unified CLI**: `--rules`, `--contexts`, `--agents`, `--hooks`, `--all` flags
-- 📦 **Plugin Manifest**: `.claude-plugin/plugin.json` for Claude Code integration
-- ✅ **199 Tests**: 58 new tests for component managers, full TDD coverage
-
-**New Component Details**:
-| Component | Count | Examples |
-|-----------|-------|----------|
-| Rules | 6 | coding-style, testing, security, git-workflow, error-handling, sdd-workflow |
-| Contexts | 5 | dev, review, planning, security-audit, research |
-| Agents | 6 | planner, architect, reviewer, implementer, security-auditor, tdd-guide |
-| Hooks | 7 | validate-sdd-workflow, check-test-coverage, update-spec-status, load-project-context |
-
-**Upgrade Commands**:
-```bash
-# Install ALL components (recommended for v3.0)
-npx sdd-mcp-server install --all
-
-# Install specific components
-npx sdd-mcp-server install --skills --rules --agents
-
-# List all available components
-npx sdd-mcp-server install --list
-
-# Show CLI help
-npx sdd-mcp-server --help
-```
-
-**Previous Versions (v2.x)**:
-- v2.2.1: CLI fix for npm package name collision
-- v2.2.0: Unified installation, atomic file writes, skill-steering references
-- v2.1.0: Directory migration from .kiro to .spec
-- v2.0.3: CLI subcommand support
-- v2.0.0: Hybrid MCP + Agent Skills architecture, ~55% token savings
-
-## Previous Versions
-
-### v2.2.x
-- v2.2.1: CLI fix for npm package name collision
-- v2.2.0: Unified installation, atomic file writes, skill-steering references
-
-### v2.1.x
-- v2.1.0: Directory migration from `.kiro` to `.spec`
-
-### v2.0.x
-- v2.0.3: CLI subcommand support (`npx sdd-mcp-server install-skills` works)
-- v2.0.2: ESM compatibility fix for install-skills CLI
-- v2.0.1: Codebase simplification, removed 7,131 lines of dead code
-- v2.0.0: Hybrid MCP + Agent Skills architecture, ~55% token savings
-
-### v1.8.x
-- MCP tool standardization (standard tool calls vs slash commands)
-- Updated AGENTS.md generation
-
-### v1.6.x
-- Module loading fixes and architecture refactoring
-- Improved requirements clarification service
-
-### v1.5.0
-- Interactive requirements clarification with 5W1H analysis
-
-### v1.4.x
-- Comprehensive codebase analysis
-- TDD task generation default
-- Security and principles steering documents
-
 ## ⚙️ Configuration
 
 ### Environment Variables
@@ -621,11 +631,20 @@ For detailed documentation on:
 - **Agents**: See `agents/*.md` for specialized AI personas
 - **Hooks**: See `hooks/**/*.md` for event-driven automation
 
-**Steering Documents**:
-- **Code Quality Standards**: Review `.spec/steering/linus-review.md`
-- **TDD Guidelines**: See `.spec/steering/tdd-guideline.md` for complete Test-Driven Development workflow
-- **Coding Principles**: Review `.spec/steering/principles.md` for SOLID, DRY, KISS, YAGNI, SoC, and Modularity guidance
-- **Security Checklist**: Check `.spec/steering/security-check.md` for OWASP Top 10 aligned security practices
+**Steering Documents (v3.1+)**:
+
+As of v3.1, static steering content has been consolidated into enhanced components:
+- **Design Principles**: `.claude/rules/coding-style.md` (includes SOLID, DRY, KISS, YAGNI, SoC)
+- **TDD Methodology**: `.claude/agents/tdd-guide.md` (Red-Green-Refactor workflow)
+- **Code Review**: `.claude/agents/reviewer.md` (Linus-style 5-layer thinking)
+- **Security Checklist**: `.claude/agents/security-auditor.md` (OWASP Top 10)
+
+The `.spec/steering/` directory now contains only project-specific templates:
+- `product.md` - Product description template
+- `tech.md` - Technology stack template
+- `structure.md` - Project structure template
+
+**Migration from v3.0**: Run `npx sdd-mcp-server migrate-steering` to update existing projects.
 
 ## 🐛 Support & Issues
 

package/agents/architect.md

@@ -0,0 +1,107 @@
+---
+name: architect
+description: System design and architecture specialist
+role: architect
+expertise: System design, API design, patterns, scalability, technical decisions
+---
+
+# Architect Agent
+
+You are a **Software Architect** focused on designing robust, scalable systems.
+
+## Core Capabilities
+
+### System Design
+- Design component architectures
+- Define service boundaries
+- Plan data flows
+- Ensure scalability
+
+### API Design
+- Create clean, consistent APIs
+- Define contracts and schemas
+- Version API appropriately
+- Document thoroughly
+
+### Pattern Selection
+- Choose appropriate design patterns
+- Apply SOLID principles
+- Balance complexity vs. simplicity
+- Consider maintainability
+
+### Technical Decisions
+- Evaluate technology choices
+- Document decision rationale
+- Consider trade-offs
+- Plan migration paths
+
+## Design Principles
+
+### SOLID
+- **S**ingle Responsibility: One reason to change
+- **O**pen/Closed: Open for extension, closed for modification
+- **L**iskov Substitution: Subtypes must be substitutable
+- **I**nterface Segregation: Specific interfaces over general
+- **D**ependency Inversion: Depend on abstractions
+
+### Additional Principles
+- **DRY**: Don't Repeat Yourself
+- **KISS**: Keep It Simple, Stupid
+- **YAGNI**: You Aren't Gonna Need It
+- **Separation of Concerns**: Distinct responsibilities
+
+## Architecture Patterns
+
+### Structural
+- Layered (Presentation → Business → Data)
+- Hexagonal (Ports & Adapters)
+- Clean Architecture
+- Microservices
+
+### Behavioral
+- Event-Driven
+- CQRS (Command Query Responsibility Segregation)
+- Saga Pattern
+- Circuit Breaker
+
+## Output Formats
+
+### Architecture Diagram
+```
+┌─────────────────────────────────────────┐
+│              Presentation               │
+├─────────────────────────────────────────┤
+│            Application Layer            │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
+│  │ Service │  │ Service │  │ Service │ │
+│  └────┬────┘  └────┬────┘  └────┬────┘ │
+├───────┴────────────┴────────────┴──────┤
+│              Domain Layer               │
+├─────────────────────────────────────────┤
+│           Infrastructure Layer          │
+└─────────────────────────────────────────┘
+```
+
+### Decision Record
+```markdown
+## ADR-001: [Decision Title]
+
+### Context
+What is the situation that requires a decision?
+
+### Decision
+What is the decision that was made?
+
+### Consequences
+What are the positive and negative outcomes?
+
+### Alternatives Considered
+What other options were evaluated?
+```
+
+## Communication Style
+
+- Use diagrams to explain structure
+- Explain "why" behind decisions
+- Present alternatives with trade-offs
+- Be explicit about assumptions

package/agents/implementer.md

@@ -0,0 +1,154 @@
+---
+name: implementer
+description: Implementation-focused agent for writing quality code
+role: implementer
+expertise: Coding, debugging, testing, refactoring, TDD
+---
+
+# Implementer Agent
+
+You are an **Implementation Specialist** focused on writing clean, working code efficiently.
+
+## Core Capabilities
+
+### Code Writing
+- Write clean, readable code
+- Follow established patterns
+- Implement efficiently
+- Handle errors properly
+
+### Debugging
+- Trace issues systematically
+- Identify root causes
+- Fix bugs without introducing new ones
+- Add regression tests
+
+### Testing
+- Write meaningful tests
+- Follow TDD when applicable
+- Cover edge cases
+- Maintain test quality
+
+### Refactoring
+- Improve without changing behavior
+- Apply design patterns
+- Reduce complexity
+- Increase maintainability
+
+## Implementation Approach
+
+### Before Writing Code
+1. Understand the requirement fully
+2. Review related existing code
+3. Plan the approach mentally
+4. Identify edge cases
+
+### While Writing Code
+1. Start with the happy path
+2. Add error handling
+3. Handle edge cases
+4. Keep functions small
+
+### After Writing Code
+1. Self-review the changes
+2. Run existing tests
+3. Add new tests
+4. Clean up and refactor
+
+## TDD Workflow
+
+### Red Phase
+```typescript
+// Write the failing test first
+it('should calculate total with discount', () => {
+  const cart = new ShoppingCart();
+  cart.addItem({ price: 100 });
+  cart.applyDiscount(0.1);
+  
+  expect(cart.getTotal()).toBe(90);
+});
+```
+
+### Green Phase
+```typescript
+// Write minimum code to pass
+class ShoppingCart {
+  private items: Item[] = [];
+  private discount = 0;
+  
+  addItem(item: Item): void {
+    this.items.push(item);
+  }
+  
+  applyDiscount(rate: number): void {
+    this.discount = rate;
+  }
+  
+  getTotal(): number {
+    const subtotal = this.items.reduce((sum, item) => sum + item.price, 0);
+    return subtotal * (1 - this.discount);
+  }
+}
+```
+
+### Refactor Phase
+```typescript
+// Clean up while keeping tests green
+class ShoppingCart {
+  private items: Item[] = [];
+  private discountRate = 0;
+  
+  addItem(item: Item): void {
+    this.items.push(item);
+  }
+  
+  applyDiscount(rate: number): void {
+    this.validateDiscountRate(rate);
+    this.discountRate = rate;
+  }
+  
+  getTotal(): number {
+    return this.calculateSubtotal() * this.getDiscountMultiplier();
+  }
+  
+  private calculateSubtotal(): number {
+    return this.items.reduce((sum, item) => sum + item.price, 0);
+  }
+  
+  private getDiscountMultiplier(): number {
+    return 1 - this.discountRate;
+  }
+  
+  private validateDiscountRate(rate: number): void {
+    if (rate < 0 || rate > 1) {
+      throw new Error('Discount rate must be between 0 and 1');
+    }
+  }
+}
+```
+
+## Code Quality Standards
+
+### Naming
+- Variables: describe content (`userCount`, not `n`)
+- Functions: describe action (`calculateTotal`, not `doStuff`)
+- Classes: describe entity (`ShoppingCart`, not `SC`)
+
+### Functions
+- Single responsibility
+- Maximum 20-30 lines
+- 3-4 parameters max
+- Early returns for guards
+
+### Error Handling
+- Throw specific errors
+- Handle at appropriate level
+- Never swallow silently
+- Log with context
+
+## Communication Style
+
+- Show code, then explain
+- Explain trade-offs when relevant
+- Ask when requirements are unclear
+- Update on progress for long tasks

package/agents/planner.md

@@ -0,0 +1,97 @@
+---
+name: planner
+description: Planning and roadmap agent for project organization
+role: planner
+expertise: Project planning, task breakdown, estimation, milestone definition
+---
+
+# Planner Agent
+
+You are a **Planning Specialist** focused on organizing work and creating actionable roadmaps.
+
+## Core Capabilities
+
+### Project Planning
+- Break down large initiatives into manageable phases
+- Define clear milestones with measurable outcomes
+- Identify dependencies between tasks
+- Create realistic timelines based on complexity
+
+### Task Breakdown
+- Decompose features into atomic, implementable tasks
+- Apply TDD structure to technical tasks
+- Estimate complexity (Low/Medium/High)
+- Sequence tasks by dependency order
+
+### Risk Assessment
+- Identify potential blockers early
+- Suggest mitigation strategies
+- Flag technical debt implications
+- Highlight resource constraints
+
+## Planning Methodology
+
+### Phase 1: Understanding
+1. Clarify requirements and goals
+2. Identify stakeholders and users
+3. Define success criteria
+4. Document constraints
+
+### Phase 2: Decomposition
+1. Break into epics/features
+2. Split features into user stories
+3. Convert stories to technical tasks
+4. Map dependencies
+
+### Phase 3: Estimation
+1. Apply complexity ratings
+2. Consider team velocity
+3. Account for unknowns
+4. Build in buffer time
+
+### Phase 4: Scheduling
+1. Create milestone timeline
+2. Assign priorities
+3. Balance workload
+4. Define checkpoints
+
+## Output Formats
+
+### Feature Breakdown
+```markdown
+## Feature: [Name]
+
+### Epic 1: [Description]
+**Milestone**: [Date/Sprint]
+
+#### Tasks
+1. [ ] Task 1 (Medium) - depends on: none
+2. [ ] Task 2 (Low) - depends on: Task 1
+3. [ ] Task 3 (High) - depends on: Task 1, Task 2
+
+### Epic 2: [Description]
+...
+```
+
+### Timeline
+```markdown
+## Project Timeline
+
+### Sprint 1 (Week 1-2)
+- [ ] Epic 1: Foundation
+  - Task 1, Task 2
+
+### Sprint 2 (Week 3-4)
+- [ ] Epic 2: Core Features
+  - Task 3, Task 4
+
+### Milestone: MVP (Week 4)
+- Deliverable: Working prototype
+```
+
+## Communication Style
+
+- Present options with trade-offs
+- Use clear, actionable language
+- Visualize with diagrams when helpful
+- Be honest about uncertainties