sdd-mcp-server 3.5.1 → 5.0.0

package/skills/sdd-tasks/SKILL.md

@@ -1,264 +1,47 @@
 ---
 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
+# SDD Tasks
 
-Generate comprehensive TDD-based task breakdowns that translate approved designs into implementable work items.
+The user invokes this Skill; backend lifecycle calls are internal. Never tell the user to call a raw MCP tool or expose revision, hash, fingerprint, or backend JSON except in explicit debug output.
 
-## Prerequisites
+## Resolve and Restore
 
-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`
+1. Internally resolve status. If no feature name is supplied, resume the sole incomplete feature or ask the user to select when several exist.
+2. Design and requirements must be approved. If durable status says otherwise, present the persisted blocker and make no file change.
+3. Load the latest approved compact context before method work. Load an unapproved tasks draft only with full mode and explicit unapproved inclusion.
+4. The saved test-case-review choice is authoritative. Ask once only when status has no choice; reuse it on every revision.
+5. If status reports an observed artifact identity for an orphan or manual edit, read that exact tasks file before revising. Never acknowledge its hash without inspecting and deliberately incorporating or replacing its content.
 
-## 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: Verify Prerequisites
+## Method and Artifact Contract
 
-Use `sdd-status` MCP tool to verify:
-- `design.generated: true`
-- `design.approved: true` (recommended before tasks)
+1. Map every requirement and design decision to small, ordered implementation and verification slices.
+2. Use unique `### N.M ...` task sections with same-line labels `**Covers:**`, `**Dependencies:**`, `**TDD:**`, `**Affected artifacts:**`, `**Acceptance criteria:**`, and `**Verification:**`.
+3. `Covers`, dependencies, and affected artifacts are comma-separated; an empty set is exactly `none`. Dependencies name existing task IDs and must be acyclic.
+4. `TDD` is exactly `required` or `not-applicable — <reason>`. Behavioral work uses RED → GREEN → REFACTOR and covers relevant boundaries, errors, transitions, security, migration, and integration.
+5. Mark concurrency only for genuinely independent slices.
 
-### Step 2: Review Design
+Internally submit complete Markdown with the exact revision and artifact identity last observed and the persisted review choice. Submission is the canonical write. Present the saved path and concise validation outcome. A failed validation remains a durable draft to revise and cannot advance.
 
-1. Read `.spec/specs/{feature}/design.md`
-2. Identify all components to implement
-3. Note interfaces and data models
-4. Understand dependencies between components
+## Human Gates
 
-### Step 3: Apply TDD Workflow
+If test-case review is required, present the concrete behavior, boundary, and error cases. Only explicit confirmation records the internal checkpoint for the exact tasks revision and artifact. This is separate from approval.
 
-For each task, follow the Red-Green-Refactor cycle:
+After validation and any required review, ask **“Approve these implementation tasks?”** Only an unambiguous affirmative answer in this Skill flow permits internal approval of the exact reviewed artifact. Never self-approve. Reread status after each checkpoint and approval.
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    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.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 decisions, constraints, dependencies, and the task 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.
 
-## 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 canonical saved path, traceability, saved checkpoint choice, concise validation evidence, the current human decision, 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 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 the exact task template, sizing heuristics, dependency diagrams, or 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.