sdd-mcp-server 3.5.0 → 4.0.0

package/skills/sdd-tasks/SKILL.md

@@ -1,264 +1,35 @@
 ---
 name: sdd-tasks
-description: Generate TDD task breakdown for SDD workflow. Use when breaking down design into implementable tasks with test-first approach. Invoked via /sdd-tasks <feature-name>.
+description: Generate an approved-design task plan with test-first slices and measurable completion.
+disable-model-invocation: true
 ---
 
-# SDD Task Breakdown Generation
-
-Generate comprehensive TDD-based task breakdowns that translate approved designs into implementable work items.
+# SDD Tasks
 
 ## Prerequisites
 
-Before generating tasks:
-1. Design must be generated using `/sdd-design`
-2. Design phase should be approved (use `sdd-approve design` MCP tool)
-3. Review the design document in `.spec/specs/{feature}/design.md`
+- Resolve the feature with `sdd-status`.
+- Design must be generated and approved. Stop rather than planning from an unapproved draft.
+- Read the approved requirements and design, including interfaces, dependencies, risks, and acceptance criteria.
 
 ## Workflow
 
-### Step 1: Verify Prerequisites
-
-Use `sdd-status` MCP tool to verify:
-- `design.generated: true`
-- `design.approved: true` (recommended before tasks)
-
-### Step 2: Review Design
-
-1. Read `.spec/specs/{feature}/design.md`
-2. Identify all components to implement
-3. Note interfaces and data models
-4. Understand dependencies between components
-
-### Step 3: Apply TDD Workflow
-
-For each task, follow the Red-Green-Refactor cycle:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    TDD CYCLE                                │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│   1. RED    ──────>  Write failing test first              │
-│                      (Test describes expected behavior)     │
-│                                                             │
-│   2. GREEN  ──────>  Write minimal code to pass            │
-│                      (Just enough to make test green)       │
-│                                                             │
-│   3. REFACTOR ────>  Clean up, maintain tests passing      │
-│                      (Improve design without breaking)      │
-│                                                             │
-│   ─────────────────────────────────────────────────────    │
-│                      REPEAT                                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Step 4: Choose Test Case Review Checkpoint
-
-Ask the user whether they want to review TDD test cases before implementation:
-
-- If yes, enable the checkpoint when generating tasks by setting `reviewTestCases: true` where the MCP tool supports it, or record the choice in `spec.json` under `workflow_options.review_test_cases`.
-- Generate a concise **Test Case Review Checklist** in `tasks.md` listing the behavior, edge, and error scenarios that need approval.
-- Before approving tasks, the user or agent should run `sdd-review-test-cases` after reviewing the test cases.
-
-Keep this checkpoint optional. If the user declines, continue with normal task approval.
-
-### Step 5: Apply Test Pyramid
-
-Structure tests following the 70/20/10 ratio:
-
-```
-                    ╱╲
-                   ╱  ╲
-                  ╱ E2E╲         10% - Critical user journeys
-                 ╱──────╲
-                ╱        ╲
-               ╱Integration╲    20% - Component interactions
-              ╱────────────╲
-             ╱              ╲
-            ╱   Unit Tests   ╲  70% - Individual functions
-           ╱──────────────────╲
-```
-
-| Level | Coverage | Scope | Speed |
-|-------|----------|-------|-------|
-| **Unit** | 70% | Single function/class | Fast (ms) |
-| **Integration** | 20% | Component interactions | Medium (s) |
-| **E2E** | 10% | Full user journeys | Slow (min) |
-
-### Step 6: Generate Task Breakdown
-
-Structure tasks hierarchically:
-
-```markdown
-# Tasks: {Feature Name}
-
-## Overview
-{Summary of implementation approach}
-
-## Task Groups
-
-### 1. {Component/Layer Name}
-
-#### 1.1 {Task Name}
-**Type:** Unit | Integration | E2E
-**Estimated Effort:** S | M | L | XL
-**Dependencies:** {Task IDs}
-
-**TDD Steps:**
-1. RED: Write test for {specific behavior}
-   ```typescript
-   describe('{Component}', () => {
-     it('should {expected behavior}', () => {
-       // Arrange
-       // Act
-       // Assert
-     });
-   });
-   ```
-2. GREEN: Implement {minimal solution}
-3. REFACTOR: {Specific improvements}
-
-**Acceptance Criteria:**
-- [ ] Test passes
-- [ ] Code coverage >= 80%
-- [ ] No lint errors
-
-#### 1.2 {Next Task}
-...
-
-### 2. {Next Component}
-...
-
-## Implementation Order
+1. Map every design component and requirement to implementation and verification work.
+2. Split work into small, ordered slices that each produce observable value. State affected artifacts, dependencies, and acceptance criteria.
+3. For behavioral work, make RED → GREEN → REFACTOR explicit: first a focused failing test, then minimal implementation, then cleanup with the test green.
+4. Cover happy paths, boundaries, errors, state transitions, security controls, migration, and integration where applicable. Do not impose a test ratio when the architecture calls for a different mix.
+5. Mark genuinely independent slices so they may run concurrently; never invent parallelism or a serial specialist.
+6. Ask whether the optional test case review checkpoint is required. If enabled, record behavior/edge/error cases and require `sdd-review-test-cases` before tasks approval.
+7. Write `.spec/specs/{feature}/tasks.md`. Request tasks approval only after dependencies, traceability, and completion criteria are validated.
 
-```
-[1.1] ──> [1.2] ──> [2.1]
-              │
-              └──> [1.3] ──> [2.2]
-```
-
-## Definition of Done
-- [ ] All tests pass
-- [ ] Code coverage >= 80%
-- [ ] No lint/type errors
-- [ ] TDD test cases reviewed (if checkpoint enabled)
-- [ ] Code reviewed
-- [ ] Documentation updated
-```
-
-### Step 7: Task Sizing Guidelines
-
-| Size | Description | Test Count | Time |
-|------|-------------|------------|------|
-| **S** | Single function, 1-2 tests | 1-2 | < 1 hour |
-| **M** | Multiple functions, 3-5 tests | 3-5 | 1-4 hours |
-| **L** | Component with integration | 5-10 | 4-8 hours |
-| **XL** | Complex component, many edge cases | 10+ | 1-2 days |
-
-### Step 8: Test-First Task Template
-
-For each implementation task:
-
-```markdown
-#### Task {X.Y}: {Task Name}
-
-**Component:** {ComponentName}
-**Type:** Unit Test → Implementation
-
-**Test Scenarios:**
-1. Happy path: {Expected behavior when inputs are valid}
-2. Edge case: {Boundary conditions}
-3. Error case: {Invalid inputs, failures}
-
-**Test Code (RED):**
-```typescript
-import { {Component} } from './{component}';
-
-describe('{Component}', () => {
-  describe('{method}', () => {
-    it('should {happy path behavior}', async () => {
-      // Arrange
-      const input = { /* valid input */ };
-
-      // Act
-      const result = await component.method(input);
-
-      // Assert
-      expect(result).toEqual({ /* expected */ });
-    });
-
-    it('should throw when {error condition}', async () => {
-      // Arrange
-      const invalidInput = { /* invalid */ };
-
-      // Act & Assert
-      await expect(component.method(invalidInput))
-        .rejects.toThrow('{ErrorType}');
-    });
-  });
-});
-```
-
-**Implementation (GREEN):**
-{Brief description of minimal implementation}
-
-**Refactor:**
-- Extract {helper function} if needed
-- Apply {specific pattern}
-```
-
-### Step 9: Save and Execute
-
-1. Save tasks to `.spec/specs/{feature}/tasks.md`
-2. If test-case review is enabled, review the Test Case Review Checklist and run `sdd-review-test-cases`
-3. Use `sdd-approve tasks` MCP tool to mark phase complete
-4. Use `sdd-spec-impl` MCP tool to execute tasks with TDD
-
-## MCP Tool Integration
-
-| Tool | When to Use |
-|------|-------------|
-| `sdd-status` | Verify design phase complete |
-| `sdd-review-test-cases` | Mark optional TDD test-case review complete |
-| `sdd-approve` | Mark tasks phase as approved |
-| `sdd-spec-impl` | Execute tasks using TDD methodology |
-| `sdd-quality-check` | Validate code quality during implementation |
-
-## Quality Checklist
-
-- [ ] All design components have corresponding tasks
-- [ ] Tasks follow TDD (test first)
-- [ ] Test pyramid ratio maintained (70/20/10)
-- [ ] Dependencies between tasks are clear
-- [ ] Each task has specific acceptance criteria
-- [ ] Tasks are sized appropriately (avoid XL when possible)
-- [ ] Implementation order respects dependencies
-- [ ] Definition of Done is clear
-
-## Steering Document References
-
-Apply these steering documents during task breakdown:
-
-| Document | Purpose | Key Application |
-|----------|---------|-----------------|
-| `.spec/steering/tdd-guideline.md` | Test-Driven Development | Structure all tasks using Red-Green-Refactor cycle, follow test pyramid (70/20/10) |
+## Specialist Delegation
 
-**Key TDD Principles for Tasks:**
-1. **RED**: Every task starts with writing a failing test
-2. **GREEN**: Implement minimal code to pass the test
-3. **REFACTOR**: Clean up while keeping tests green
-4. **Test Pyramid**: 70% unit, 20% integration, 10% E2E
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only approved design decisions, constraints, dependencies, and task 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.
 
-## Common Anti-Patterns to Avoid
+## Output
 
-| Anti-Pattern | Problem | Solution |
-|--------------|---------|----------|
-| **Test After** | Missing edge cases | Always write test first |
-| **Ice Cream Cone** | Too many E2E tests | Follow pyramid (70/20/10) |
-| **Big Tasks** | Hard to track progress | Break into S/M sizes |
-| **No Dependencies** | Blocked work | Map dependencies explicitly |
-| **Vague Criteria** | Unclear completion | Specific, measurable criteria |
+Return the saved path, requirement/design traceability, checkpoint choice, 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 approved design, constraints, dependencies, and required task format. 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 task templates, sizing heuristics, dependency diagrams, or the extended checklist.

package/skills/sdd-test-gen/REFERENCE.md

@@ -0,0 +1,15 @@
+# Test Generation Reference
+
+Read only when selecting cases or matching a framework.
+
+## Behavior Matrix
+
+For each contract consider: normal input, empty/zero, minimum/maximum boundary, malformed input, missing dependency, dependency error identity, repeated call/idempotency, ordering/precedence, concurrent transition, cancellation/cleanup, authorization, and sensitive output. Include only cases plausible for the target.
+
+## Test Quality
+
+Name the condition and expected behavior. Arrange only necessary state, act once, and assert the observable result plus critical side effects. Keep time, randomness, network, and filesystem boundaries deterministic. Restore global state and close resources. Prefer table-driven cases when inputs share one contract.
+
+## Framework Guidance
+
+Detect the existing runner and nearby conventions from project files; do not assume Jest. Place tests beside or under the established test tree. Reuse existing helpers only when they preserve isolation. Run the narrowest supported command that executes the new test. A valid RED run must reach the intended assertion and fail because the behavior is missing.

package/skills/sdd-test-gen/SKILL.md

@@ -1,299 +1,29 @@
 ---
 name: sdd-test-gen
-description: Generate comprehensive tests following TDD methodology. Creates unit tests, integration tests, and edge case coverage. Works with existing test frameworks in the project. Invoked via /sdd-test-gen [file-path or function-name].
+description: Generate focused tests for observable behavior, boundaries, and real failures.
+disable-model-invocation: true
 ---
 
-# SDD Test Generation
+# Test Generation
 
-Generate comprehensive tests following Test-Driven Development (TDD) methodology. Write tests that serve as living documentation and ensure code correctness.
+Work inline in the current turn; do not create a serial TDD specialist.
 
-## TDD Philosophy
+## Required Workflow
 
-> "Write a failing test before you write the code to make it pass."
+1. Identify the exact behavior contract, scope, framework, and existing test conventions.
+2. Read related requirements/design and nearby tests. Avoid duplicate coverage and incidental implementation assertions.
+3. Write the smallest focused test that proves observable behavior. Cover relevant boundaries, invariants, transitions, precedence, concurrency, and real error propagation.
+4. Keep tests deterministic, isolated, and full-suite safe. Prefer real domain collaborators; mock only external or nondeterministic boundaries.
+5. Run the new test before production changes and confirm it fails for the intended reason. A syntax/import failure is not valid RED evidence.
+6. If implementation is in scope, make the minimal change, rerun the focused test to GREEN, refactor, and rerun.
+7. Never weaken assertions, snapshot unstable output, add sleeps, or claim coverage/test results that were not observed.
 
-Tests are not an afterthought—they're a design tool that:
-1. **Document behavior** - Tests show how code is intended to be used
-2. **Prevent regressions** - Catch bugs before they ship
-3. **Enable refactoring** - Change with confidence
-4. **Drive design** - Writing tests first leads to better interfaces
+Use focused test commands during the cycle. Broader verification belongs after the requested behavior works.
 
-## The TDD Cycle
+## Output
 
-```
-┌─────────────────────────────────────┐
-│                                     │
-│   ┌─────────┐   Write failing test  │
-│   │   RED   │◄──────────────────────┤
-│   └────┬────┘                       │
-│        │                            │
-│        ▼ Make it pass               │
-│   ┌─────────┐                       │
-│   │  GREEN  │                       │
-│   └────┬────┘                       │
-│        │                            │
-│        ▼ Improve code               │
-│   ┌─────────┐                       │
-│   │REFACTOR │───────────────────────┘
-│   └─────────┘
-└─────────────────────────────────────┘
-```
+Report tests added or changed, contracts protected, the expected failing-test evidence, focused passing-test evidence, affected artifacts, and unresolved blockers.
 
-## Workflow
+## Optional Reference
 
-### Step 1: Identify Test Scope
-
-```
-/sdd-test-gen src/services/UserService.ts           # Generate tests for file
-/sdd-test-gen UserService.createUser                # Generate for specific method
-/sdd-test-gen src/services/ --integration           # Integration tests for module
-```
-
-### Step 2: Analyze the Code
-
-Before generating tests:
-1. Read the source file to understand its behavior
-2. Check existing tests (if any) to avoid duplication
-3. Review related requirements in `.spec/specs/`
-4. Identify dependencies that need mocking
-
-### Step 3: Test File Structure
-
-Generate tests with this structure:
-
-```typescript
-import { UserService } from '../UserService';
-import { UserRepository } from '../../repositories/UserRepository';
-import { EmailService } from '../../services/EmailService';
-
-// Mock dependencies
-jest.mock('../../repositories/UserRepository');
-jest.mock('../../services/EmailService');
-
-describe('UserService', () => {
-  let userService: UserService;
-  let mockUserRepo: jest.Mocked<UserRepository>;
-  let mockEmailService: jest.Mocked<EmailService>;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    mockUserRepo = new UserRepository() as jest.Mocked<UserRepository>;
-    mockEmailService = new EmailService() as jest.Mocked<EmailService>;
-    userService = new UserService(mockUserRepo, mockEmailService);
-  });
-
-  describe('createUser', () => {
-    it('should create a user with valid input', async () => {
-      // Arrange
-      const input = { email: 'test@example.com', name: 'Test User' };
-      mockUserRepo.save.mockResolvedValue({ id: '1', ...input });
-
-      // Act
-      const result = await userService.createUser(input);
-
-      // Assert
-      expect(result.id).toBeDefined();
-      expect(mockUserRepo.save).toHaveBeenCalledWith(expect.objectContaining(input));
-    });
-
-    it('should throw error when email already exists', async () => {
-      // Arrange
-      mockUserRepo.findByEmail.mockResolvedValue({ id: '1', email: 'test@example.com' });
-
-      // Act & Assert
-      await expect(userService.createUser({ email: 'test@example.com' }))
-        .rejects.toThrow('Email already exists');
-    });
-  });
-});
-```
-
-## Specialist Delegation
-
-When the host supports subagents, delegate test design and generation to the `tdd-guide` role with a compact handoff containing only the behavior contract, affected code, existing test conventions, and edge cases. 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.
-
-### Step 4: Test Categories to Generate
-
-#### Unit Tests
-
-Test individual functions in isolation:
-- Mock all external dependencies
-- Test one behavior per test
-- Use descriptive test names
-
-```typescript
-describe('calculateTotal', () => {
-  it('should sum all item prices', () => { ... });
-  it('should apply discount when provided', () => { ... });
-  it('should handle empty cart', () => { ... });
-  it('should throw error for negative quantities', () => { ... });
-});
-```
-
-#### Edge Case Tests
-
-Always test:
-- Null/undefined inputs
-- Empty arrays/objects
-- Boundary values (0, -1, MAX_INT)
-- Invalid types
-- Concurrent access (if applicable)
-
-```typescript
-describe('edge cases', () => {
-  it('should handle null input gracefully', () => { ... });
-  it('should handle empty array', () => { ... });
-  it('should handle maximum allowed length', () => { ... });
-  it('should reject invalid email format', () => { ... });
-});
-```
-
-#### Error Handling Tests
-
-Verify error paths:
-```typescript
-describe('error handling', () => {
-  it('should throw ValidationError for invalid input', async () => {
-    await expect(service.create({})).rejects.toThrow(ValidationError);
-  });
-
-  it('should propagate database errors', async () => {
-    mockRepo.save.mockRejectedValue(new DatabaseError('Connection failed'));
-    await expect(service.create(validInput)).rejects.toThrow(DatabaseError);
-  });
-});
-```
-
-#### Integration Tests (when requested)
-
-Test component interactions:
-```typescript
-describe('UserService integration', () => {
-  let app: Express;
-  let db: Database;
-
-  beforeAll(async () => {
-    db = await createTestDatabase();
-    app = createApp({ database: db });
-  });
-
-  afterAll(async () => {
-    await db.close();
-  });
-
-  it('should create user and send welcome email', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ email: 'test@example.com', name: 'Test' });
-
-    expect(response.status).toBe(201);
-    // Verify email was queued
-    expect(await getEmailQueue()).toContainEqual(
-      expect.objectContaining({ to: 'test@example.com' })
-    );
-  });
-});
-```
-
-### Step 5: Test Naming Convention
-
-Use the pattern: `should [expected behavior] when [condition]`
-
-```typescript
-// Good
-it('should return empty array when no users match criteria', () => {});
-it('should throw AuthError when token is expired', () => {});
-it('should create user and return ID when input is valid', () => {});
-
-// Bad
-it('test createUser', () => {});
-it('works correctly', () => {});
-```
-
-## Test Quality Checklist
-
-For each generated test:
-- [ ] Test name describes behavior, not implementation
-- [ ] Arrange-Act-Assert pattern used
-- [ ] Only one assertion concept per test
-- [ ] Tests are independent (no shared state)
-- [ ] Mocks are minimal (only external deps)
-- [ ] Edge cases covered
-- [ ] Error paths tested
-- [ ] Async tests properly awaited
-
-## Integration with SDD Workflow
-
-When generating tests for a spec:
-1. Read requirements from `.spec/specs/{feature}/requirements.md`
-2. Map each acceptance criterion to test cases
-3. Check design.md for expected interfaces
-4. Reference tasks.md for implementation details
-
-## Test Generation Prompt
-
-When running `/sdd-test-gen`:
-
-```markdown
-## Test Generation Summary
-
-### Target: {file/function}
-
-### Tests Generated:
-- **Unit Tests**: {count}
-- **Edge Cases**: {count}
-- **Error Handling**: {count}
-- **Integration**: {count} (if requested)
-
-### Coverage Targets:
-- Statements: 80%+
-- Branches: 75%+
-- Functions: 90%+
-- Lines: 80%+
-
-### Files Created:
-- `src/__tests__/unit/{file}.test.ts`
-- `src/__tests__/integration/{file}.integration.test.ts` (if requested)
-```
-
-## Framework Detection
-
-Automatically detect and use project's test framework:
-- **Jest** (default for TypeScript/JavaScript)
-- **Vitest** (if vite.config.ts present)
-- **Mocha/Chai** (if mocha in dependencies)
-- **Pytest** (for Python projects)
-
-## Example Output
-
-For input: `/sdd-test-gen src/services/AuthService.ts`
-
-```typescript
-import { AuthService } from '../AuthService';
-import { TokenService } from '../../utils/TokenService';
-import { UserRepository } from '../../repositories/UserRepository';
-
-jest.mock('../../utils/TokenService');
-jest.mock('../../repositories/UserRepository');
-
-describe('AuthService', () => {
-  // ... setup ...
-
-  describe('login', () => {
-    it('should return token when credentials are valid', async () => { ... });
-    it('should throw AuthError when user not found', async () => { ... });
-    it('should throw AuthError when password is incorrect', async () => { ... });
-    it('should increment failed login count on failure', async () => { ... });
-    it('should lock account after 5 failed attempts', async () => { ... });
-  });
-
-  describe('logout', () => {
-    it('should invalidate token when called', async () => { ... });
-    it('should handle already-logged-out user gracefully', async () => { ... });
-  });
-
-  describe('refreshToken', () => {
-    it('should return new token when refresh token is valid', async () => { ... });
-    it('should throw AuthError when refresh token is expired', async () => { ... });
-  });
-});
-```
+Read [REFERENCE.md](REFERENCE.md) only for test matrices, framework examples, naming guidance, or the extended quality checklist.

package/skills/simple-task/REFERENCE.md

@@ -0,0 +1,22 @@
+# Simple Task Reference
+
+Read only when scope or completion is unclear.
+
+## Appropriate Scope
+
+Good candidates are one focused bug, a small behavior addition, a contained refactor, or a configuration correction with known acceptance behavior. Use formal SDD when the work needs competing architecture decisions, new subsystem boundaries, durable phase approvals, or a multi-step migration contract.
+
+## TDD Reminder
+
+RED proves the test can detect the missing behavior. GREEN implements the complete requested contract with minimal surface area. REFACTOR removes duplication or accidental complexity while preserving GREEN. Test externally observable results and real failures rather than private calls or source text.
+
+## Completion Checklist
+
+- request and non-goals remain unchanged;
+- existing repository conventions were reused;
+- focused RED and GREEN evidence was observed;
+- relevant boundary and error behavior is protected;
+- authorization, injection, secrets, and logging were considered;
+- every affected caller/artifact is updated;
+- unrelated user work is preserved;
+- response lists exact changes, verification, and blockers without dumping file contents.