smart-spec-kit-mcp 2.0.0 → 2.0.2

package/starter-kit/prompts/speckit.specify.md

@@ -0,0 +1,123 @@
+---
+description: Create a functional specification from requirements or an Azure DevOps work item. Focus on WHAT you want to build, not the tech stack.
+---
+
+# /speckit.specify - Create Specification
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are creating a functional specification document. Follow this workflow:
+
+### 1. Setup Check
+
+First, verify the Spec-Kit environment:
+- Check if `.spec-kit/` directory exists
+- If not, inform the user to run `/speckit.init` first
+
+### 2. Parse Requirements Source
+
+Determine the source of requirements from user input:
+
+**Option A: Azure DevOps Work Item**
+- If input contains an ADO work item ID (e.g., "#12345", "AB#12345", "Feature 12345")
+- Use the `fetch_ado_workitem` MCP tool to retrieve work item data
+
+**Option B: Direct Description**
+- If input is a feature description
+- Parse the description for key concepts: actors, actions, data, constraints
+
+### 3. Analyze Requirements
+
+For the provided requirements, identify:
+1. **Core user need** and business value
+2. **Explicit requirements** - what was directly stated
+3. **Implicit requirements** - reasonable inferences from context
+4. **Assumptions** - things that need validation
+5. **Risks and dependencies**
+6. **Edge cases and error scenarios**
+
+### 4. Generate Specification
+
+Load the template from `.spec-kit/templates/functional-spec.md` and fill it with:
+
+1. **Metadata Section**
+   - Title, date, version, status
+   - Link to Azure DevOps work item (if applicable)
+
+2. **Overview**
+   - Purpose (the problem being solved)
+   - Scope (what's in/out)
+   - Background context
+
+3. **Requirements**
+   - Functional requirements with IDs and priorities (Must Have/Should Have/Could Have)
+   - Non-functional requirements (performance, security, etc.)
+   - Acceptance criteria in Given/When/Then format
+
+4. **User Experience**
+   - User personas
+   - User stories (As a... I want... So that...)
+   - User flow descriptions
+
+5. **Technical Considerations**
+   - Dependencies
+   - Constraints
+   - Data requirements
+
+### 5. Handle Ambiguity
+
+For unclear aspects:
+- **Make informed guesses** based on context and industry standards
+- **Document assumptions** in the Assumptions section
+- **Limit clarifications**: Maximum 3 `[NEEDS CLARIFICATION]` markers for critical decisions only
+
+Only use `[NEEDS CLARIFICATION]` when:
+- The choice significantly impacts feature scope or user experience
+- Multiple reasonable interpretations exist with different implications
+- No reasonable default exists
+
+### 6. Save Specification
+
+Save the specification to:
+```
+specs/{context_id}-spec.md
+```
+
+If no context ID is provided, create a timestamped filename or ask for a feature short-name.
+
+### 7. Report Completion
+
+Output:
+- Path to created specification file
+- Summary of requirements captured
+- List of assumptions made
+- Any `[NEEDS CLARIFICATION]` items that need user input
+- Next step suggestion: `/speckit.plan` to create implementation plan
+
+## Quick Guidelines
+
+### Writing Style
+- Use active voice and clear, concise language
+- Include concrete examples for complex requirements
+- Define all technical terms and acronyms
+- Use tables for structured data (requirements, test cases)
+
+### Quality Checks
+- Every requirement should be testable and unambiguous
+- Each requirement should have a unique ID
+- Acceptance criteria should be in Given/When/Then format
+- No undefined placeholders in final output (except intentional `[NEEDS CLARIFICATION]`)
+
+## Handoffs
+
+After completing the specification, suggest:
+- **Clarify requirements**: `/speckit.clarify` - If there are `[NEEDS CLARIFICATION]` items
+- **Create implementation plan**: `/speckit.plan` - Once specification is approved

package/starter-kit/prompts/speckit.tasks.md

@@ -0,0 +1,137 @@
+---
+description: Generate actionable task breakdown from the implementation plan. Creates a tasks.md file with ordered, dependency-aware tasks.
+---
+
+# /speckit.tasks - Generate Task Breakdown
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are generating an actionable task list from the implementation plan. Follow this workflow:
+
+### 1. Load Design Documents
+
+Read from the feature's spec directory:
+- **Required**: `plan.md` (tech stack, libraries, structure)
+- **Required**: `spec.md` (user stories with priorities)
+- **Optional**: `data-model.md` (entities)
+- **Optional**: `contracts/` (API endpoints)
+- **Optional**: `research.md` (decisions)
+
+If required files are missing, inform user to run `/speckit.plan` first.
+
+### 2. Extract Implementation Context
+
+From the documents, identify:
+- User stories with their priorities (P1, P2, P3)
+- Tech stack and frameworks
+- Database entities and relationships
+- API endpoints
+- External dependencies
+
+### 3. Generate Task Breakdown
+
+Create `specs/{feature}/tasks.md` with this structure:
+
+```markdown
+# Tasks: {Feature Name}
+
+**Input**: Design documents from `/specs/{feature}/`
+**Generated**: {Date}
+
+## Task Format
+
+- [ ] T### [P?] [Story?] Description - `path/to/file.ext`
+
+Legend:
+- T###: Task ID (sequential)
+- [P]: Can be executed in parallel with other [P] tasks
+- [Story?]: Associated user story ID (if applicable)
+```
+
+### 4. Phase Structure
+
+Organize tasks into these phases:
+
+**Phase 1: Setup (Shared Infrastructure)**
+- Project initialization
+- Dependency installation
+- Configuration files
+- Development environment setup
+
+**Phase 2: Foundational (Blocking Prerequisites)**
+- Database schema and migrations
+- Base models/entities
+- Authentication/authorization framework
+- Core utilities and helpers
+- Error handling infrastructure
+
+⚠️ **CRITICAL**: No user story work begins until Phase 2 is complete.
+
+**Phase 3+: User Stories (One Phase per Story)**
+For each user story in priority order:
+- Tests (if requested) → Models → Services → Endpoints → Integration
+- Each phase should be independently testable
+- Include checkpoint validation
+
+**Final Phase: Polish & Cross-Cutting**
+- Code cleanup and refactoring
+- Documentation updates
+- Performance optimization
+- Security hardening
+
+### 5. Task Generation Rules
+
+Each task MUST:
+- Be completable in 1-3 days by a single developer
+- Have a clear verb + object title
+- Include the file path(s) affected
+- Have explicit dependencies noted
+
+Mark with `[P]` if the task can run in parallel with others at the same level.
+
+### 6. Generate Dependency Graph
+
+Add a section showing:
+- Task dependencies (which tasks must complete first)
+- Parallel execution opportunities
+- Critical path identification
+
+### 7. Report Completion
+
+Output:
+- Path to generated `tasks.md`
+- Total task count
+- Task count per user story
+- Parallel execution opportunities identified
+- Suggested MVP scope (typically User Story 1 only)
+
+## Task Template
+
+```markdown
+## Phase 3: User Story 1 - {Title} (Priority: P1) 🎯 MVP
+
+**Goal**: {User story goal}
+**Independent Test**: {How to verify this story works alone}
+
+- [ ] T010 [US-1] Create {model} entity - `src/models/{model}.ts`
+- [ ] T011 [P] [US-1] Create {model} repository - `src/repositories/{model}.ts`
+- [ ] T012 [P] [US-1] Create {model} service - `src/services/{model}.ts`
+- [ ] T013 [US-1] Create {endpoint} API endpoint - `src/api/{endpoint}.ts`
+- [ ] T014 [US-1] Add integration tests - `tests/integration/{feature}.test.ts`
+
+**Checkpoint**: Story 1 complete - run `npm test` and verify {criteria}
+```
+
+## Handoffs
+
+After completing the tasks, suggest:
+- **Analyze plan**: `/speckit.analyze` - Cross-check consistency
+- **Implement**: `/speckit.implement` - Start executing tasks

package/starter-kit/templates/bugfix-report.md

@@ -0,0 +1,127 @@
+---
+title: "[TO FILL: Bug Title]"
+workitem_id: "[TO FILL]"
+type: Bugfix Report
+version: "1.0"
+status: Draft
+author: "[TO FILL]"
+created: "[TO FILL: Date]"
+severity: "[Critical/High/Medium/Low]"
+---
+
+# Bug Fix Report: [TO FILL: Bug Title]
+
+## 1. Bug Summary
+
+### 1.1 Description
+[TO FILL: Clear, concise description of the bug]
+
+### 1.2 Impact
+- **Severity**: [Critical/High/Medium/Low]
+- **Affected Users**: [TO FILL: Who is affected]
+- **Business Impact**: [TO FILL: How this affects the business]
+
+---
+
+## 2. Reproduction
+
+### 2.1 Environment
+| Component | Value |
+|-----------|-------|
+| OS | [TO FILL] |
+| Browser/Runtime | [TO FILL] |
+| Version | [TO FILL] |
+
+### 2.2 Steps to Reproduce
+1. [TO FILL: Step 1]
+2. [TO FILL: Step 2]
+3. [TO FILL: Step 3]
+
+### 2.3 Expected Behavior
+[TO FILL: What should happen]
+
+### 2.4 Actual Behavior
+[TO FILL: What actually happens]
+
+### 2.5 Evidence
+```
+[TO FILL: Error messages, logs, screenshots]
+```
+
+---
+
+## 3. Root Cause Analysis
+
+### 3.1 Investigation
+[TO FILL: What was investigated and findings]
+
+### 3.2 Root Cause
+[TO FILL: The underlying cause of the bug]
+
+### 3.3 Related Code
+```
+File: [path/to/file]
+Line: [line numbers]
+```
+
+---
+
+## 4. Fix Proposal
+
+### 4.1 Solution
+[TO FILL: Proposed fix approach]
+
+### 4.2 Changes Required
+| File | Change |
+|------|--------|
+| [TO FILL] | [TO FILL] |
+
+### 4.3 Risks
+- [TO FILL: Any risks with the proposed fix]
+
+---
+
+## 5. Testing
+
+### 5.1 Test Cases
+| ID | Scenario | Expected Result |
+|----|----------|-----------------|
+| TC-001 | [TO FILL: Original bug scenario] | Bug no longer occurs |
+| TC-002 | [TO FILL: Regression test] | Existing functionality intact |
+
+### 5.2 Verification Steps
+1. [TO FILL: How to verify the fix]
+2. [TO FILL: Regression testing steps]
+
+---
+
+## 6. Deployment
+
+### 6.1 Deployment Plan
+- [ ] Code review completed
+- [ ] Tests passing
+- [ ] Staging verification
+- [ ] Production deployment
+
+### 6.2 Rollback Plan
+[TO FILL: How to rollback if issues occur]
+
+---
+
+## 7. Post-Mortem (Optional)
+
+### 7.1 Timeline
+| Time | Event |
+|------|-------|
+| [TO FILL] | Bug reported |
+| [TO FILL] | Investigation started |
+| [TO FILL] | Root cause identified |
+| [TO FILL] | Fix deployed |
+
+### 7.2 Lessons Learned
+- [TO FILL: What can we improve to prevent similar issues]
+
+### 7.3 Action Items
+| Item | Owner | Due Date |
+|------|-------|----------|
+| [TO FILL] | [TO FILL] | [TO FILL] |

package/starter-kit/templates/functional-spec.md

@@ -0,0 +1,144 @@
+---
+title: "[TO FILL: Feature Title]"
+workitem_id: "[TO FILL]"
+type: Functional Specification
+version: "1.0"
+status: Draft
+author: "[TO FILL]"
+created: "[TO FILL: Date]"
+last_updated: "[TO FILL: Date]"
+---
+
+# Functional Specification: [TO FILL: Feature Title]
+
+## 1. Overview
+
+### 1.1 Purpose
+[TO FILL: Brief description of the feature's purpose and the problem it solves]
+
+### 1.2 Scope
+**In Scope:**
+- [TO FILL: What is included]
+
+**Out of Scope:**
+- [TO FILL: What is explicitly excluded]
+
+### 1.3 Background
+[TO FILL: Context and history leading to this feature request]
+
+---
+
+## 2. Stakeholders
+
+| Role | Name | Responsibility |
+|------|------|----------------|
+| Product Owner | [TO FILL] | Requirements validation |
+| Tech Lead | [TO FILL] | Technical decisions |
+| QA Lead | [TO FILL] | Test strategy |
+
+---
+
+## 3. Requirements
+
+### 3.1 Functional Requirements
+
+| ID | Requirement | Priority | Source |
+|----|-------------|----------|--------|
+| FR-001 | [TO FILL] | Must Have | |
+| FR-002 | [TO FILL] | Should Have | |
+| FR-003 | [TO FILL] | Could Have | |
+
+### 3.2 Non-Functional Requirements
+
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | [TO FILL] | [TO FILL] |
+| NFR-002 | Security | [TO FILL] | [TO FILL] |
+| NFR-003 | Availability | [TO FILL] | [TO FILL] |
+
+### 3.3 Acceptance Criteria
+
+```gherkin
+Feature: [TO FILL: Feature Name]
+
+  Scenario: [TO FILL: Main Success Scenario]
+    Given [TO FILL: Initial context]
+    When [TO FILL: Action performed]
+    Then [TO FILL: Expected outcome]
+
+  Scenario: [TO FILL: Alternative Scenario]
+    Given [TO FILL]
+    When [TO FILL]
+    Then [TO FILL]
+```
+
+---
+
+## 4. User Experience
+
+### 4.1 User Personas
+
+**Persona 1: [TO FILL: Name]**
+- Role: [TO FILL]
+- Goals: [TO FILL]
+- Pain Points: [TO FILL]
+
+### 4.2 User Stories
+
+| ID | As a... | I want to... | So that... | Priority |
+|----|---------|--------------|------------|----------|
+| US-001 | [TO FILL] | [TO FILL] | [TO FILL] | P1 |
+| US-002 | [TO FILL] | [TO FILL] | [TO FILL] | P2 |
+
+### 4.3 User Flow
+
+```
+[TO FILL: Describe or link to user flow diagram]
+┌─────────┐    ┌─────────┐    ┌─────────┐
+│ Step 1  │───▶│ Step 2  │───▶│ Step 3  │
+└─────────┘    └─────────┘    └─────────┘
+```
+
+---
+
+## 5. Technical Considerations
+
+### 5.1 Dependencies
+- [TO FILL: External systems, services, or components this feature depends on]
+
+### 5.2 Constraints
+- [TO FILL: Technical or business constraints]
+
+### 5.3 Data Requirements
+- [TO FILL: Data entities, storage, and access patterns]
+
+---
+
+## 6. Assumptions & Risks
+
+### 6.1 Assumptions
+| ID | Assumption | Impact if Wrong |
+|----|------------|-----------------|
+| A-001 | [TO FILL] | [TO FILL] |
+
+### 6.2 Risks
+| ID | Risk | Probability | Impact | Mitigation |
+|----|------|-------------|--------|------------|
+| R-001 | [TO FILL] | Medium | High | [TO FILL] |
+
+---
+
+## 7. Clarifications
+
+| # | Topic | Question | Answer | Date |
+|---|-------|----------|--------|------|
+| | | | | |
+
+---
+
+## 8. Approval
+
+| Role | Name | Date | Status |
+|------|------|------|--------|
+| Product Owner | | | ⬜ Pending |
+| Tech Lead | | | ⬜ Pending |

package/starter-kit/templates/plan-template.md

@@ -0,0 +1,126 @@
+# Implementation Plan: [FEATURE NAME]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link to spec.md]
+
+## Summary
+
+[TO FILL: Brief description of the implementation approach]
+
+## Technical Context
+
+### Tech Stack
+| Component | Technology | Version |
+|-----------|------------|---------|
+| Language | [TO FILL] | |
+| Framework | [TO FILL] | |
+| Database | [TO FILL] | |
+| Testing | [TO FILL] | |
+
+### Architecture Overview
+
+```
+[TO FILL: ASCII diagram or description of architecture]
+
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Client    │───▶│     API     │───▶│  Database   │
+└─────────────┘    └─────────────┘    └─────────────┘
+```
+
+---
+
+## Project Structure
+
+```text
+[TO FILL: Project directory structure]
+
+src/
+├── models/
+├── services/
+├── api/
+└── utils/
+
+tests/
+├── unit/
+├── integration/
+└── e2e/
+```
+
+---
+
+## Implementation Phases
+
+### Phase 0: Research & Design
+**Duration**: [X days]
+**Output**: research.md, data-model.md
+
+- [ ] Validate tech stack choices
+- [ ] Research key libraries/patterns
+- [ ] Design data model
+- [ ] Define API contracts
+
+### Phase 1: Foundation
+**Duration**: [X days]
+**Dependencies**: Phase 0
+
+- [ ] Set up project structure
+- [ ] Configure build/test pipeline
+- [ ] Create base models
+- [ ] Set up database schema
+
+### Phase 2: Core Implementation
+**Duration**: [X days]
+**Dependencies**: Phase 1
+
+- [ ] Implement core services
+- [ ] Create API endpoints
+- [ ] Add unit tests
+
+### Phase 3: Integration & Polish
+**Duration**: [X days]
+**Dependencies**: Phase 2
+
+- [ ] Integration testing
+- [ ] Error handling improvements
+- [ ] Documentation
+- [ ] Performance optimization
+
+---
+
+## Quality Gates
+
+| Gate | Criteria | Status |
+|------|----------|--------|
+| Code Review | All PRs reviewed | ⬜ |
+| Unit Tests | >80% coverage | ⬜ |
+| Integration Tests | All scenarios pass | ⬜ |
+| Documentation | README updated | ⬜ |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [TO FILL] | Medium | High | [TO FILL] |
+
+---
+
+## Technical Decisions
+
+| Decision | Options Considered | Choice | Rationale |
+|----------|-------------------|--------|-----------|
+| [TO FILL] | [TO FILL] | [TO FILL] | [TO FILL] |
+
+---
+
+## Dependencies
+
+| Dependency | Version | Purpose | Notes |
+|------------|---------|---------|-------|
+| [TO FILL] | | | |
+
+---
+
+## Notes
+
+[TO FILL: Additional implementation notes, gotchas, or considerations]