smart-spec-kit-mcp 2.2.6 → 2.2.7

package/docs/DOCUMENTATION.md

@@ -387,7 +387,7 @@ Templates define document structure. Create/edit in `.spec-kit/templates/`:
 
 ### Creating a New Workflow
 
-Workflows are YAML files defining multi-step processes:
+Workflows are YAML files defining multi-step processes. All workflows are validated against a schema (`src/schemas/workflowSchema.ts`) to ensure correctness.
 
 ```yaml
 # .spec-kit/workflows/my-workflow.yaml
@@ -424,12 +424,252 @@ steps:
 - `save_artifact` - Save to file
 - `validate` - Validate output
 
-**Available agents**:
+**Available Agents** (System Prompts):
 
-- `SpecAgent` - Writes specifications
-- `PlanAgent` - Creates plans
-- `GovAgent` - Validates governance
-- `TestAgent` - Creates test strategies
+⚠️ **Important Note**: These are NOT GitHub Copilot agents. They are **predefined system prompts** that guide Copilot's behavior for each workflow step.
+
+- **`SpecAgent`** - Writes specifications and analyzes requirements
+- **`PlanAgent`** - Creates technical plans and decomposes tasks
+- **`GovAgent`** - Validates governance, security, and compliance
+- **`TestAgent`** - Creates test strategies and test cases
+
+### Understanding Spec-Kit Agents
+
+Spec-Kit's "agents" are **NOT** registered agents in GitHub Copilot. Instead, they are:
+
+1. **System Prompts** - Instructions defined in TypeScript (`src/prompts/agents.ts`)
+2. **Role Definitions** - Each agent has specific expertise and guidelines
+3. **Behavioral Guides** - They shape how Copilot responds to specific tasks
+
+**How They Work**:
+
+When a workflow step specifies an agent:
+
+```yaml
+steps:
+  - id: plan
+    agent: PlanAgent  # ← Uses PlanAgent's system prompt
+    action: call_agent
+    description: "Create implementation plan"
+```
+
+Spec-Kit:
+
+1. Looks up the system prompt for `PlanAgent`
+2. Sends it to Copilot along with the task
+3. Copilot responds following that agent's guidelines
+
+**Why Use Agents?**
+
+Different tasks need different expertise:
+
+```yaml
+steps:
+  - id: analyze-bug          # ← No agent = general purpose
+    action: fetch_ado
+    
+  - id: create-fix-plan      # ← Use PlanAgent = focused planning
+    agent: PlanAgent
+    action: call_agent
+    
+  - id: security-review      # ← Use GovAgent = security focus
+    agent: GovAgent
+    action: review
+```
+
+Each agent brings specialized guidelines to shape Copilot's response appropriately.
+
+**Customizing Agents**:
+
+Agents are now **fully customizable** from `.spec-kit/agents/`. You can:
+
+1. **Override built-in agents**: Create a file with the same name (e.g., `SpecAgent.md`)
+2. **Create new agents**: Create a new file (e.g., `SecurityAgent.md`)
+
+**Agent File Format** (Markdown with YAML frontmatter):
+
+```markdown
+---
+name: MyCustomAgent
+displayName: "My Custom Agent"
+description: "Expert in your specific domain"
+capabilities:
+  - Your first capability
+  - Your second capability
+---
+
+## System Prompt
+
+You are MyCustomAgent, an expert in [your domain]...
+
+### Guidelines
+- Guideline 1
+- Guideline 2
+```
+
+**Example: Creating a SecurityAgent**:
+
+```markdown
+---
+name: SecurityAgent
+displayName: "Security Review Agent"
+description: "Expert in application security and vulnerability assessment"
+capabilities:
+  - Identify security vulnerabilities
+  - Recommend secure coding practices
+  - Review authentication and authorization
+  - Check for OWASP Top 10 issues
+---
+
+## System Prompt
+
+You are SecurityAgent, an expert in application security...
+
+### Your Role
+Review code and specifications for security vulnerabilities...
+```
+
+Then use in your workflow:
+
+```yaml
+steps:
+  - id: security-review
+    agent: SecurityAgent  # Your custom agent!
+    action: call_agent
+    description: "Review code for security issues"
+```
+
+**Resolution Order**:
+1. `.spec-kit/agents/AgentName.md` (local override - takes priority)
+2. Built-in agents from package (fallback)
+
+Changes take effect immediately - no restart needed.
+
+### Workflow Validation Schema
+
+Every workflow YAML is automatically validated using Zod schema (`src/schemas/workflowSchema.ts`). This ensures all workflows follow the required structure and catches errors early.
+
+**Required Top-Level Fields**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Workflow identifier (kebab-case recommended) |
+| `displayName` | string | User-readable display name |
+| `description` | string | What this workflow accomplishes |
+| `template` | string | Associated template file (e.g., `functional-spec.md`) |
+| `steps` | array | Array of steps (min. 1 step required) |
+
+**Optional Top-Level Fields**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `defaultAgent` | string | Default agent for all steps (default: `SpecAgent`) |
+| `metadata` | object | Version, author, created, tags |
+
+**Step Schema** (each object in the `steps` array):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Unique step identifier within workflow |
+| `name` | string | ✅ | Human-readable step name |
+| `action` | enum | ✅ | Action type: `call_agent`, `fetch_ado`, `generate_content`, `review`, `create_file` |
+| `description` | string | ✅ | What this step does |
+| `agent` | string | ❌ | Agent to use (overrides `defaultAgent`) |
+| `inputs` | object | ❌ | Input parameters for this step |
+| `outputs` | array | ❌ | Expected output types |
+| `next` | string | ❌ | Next step ID (for non-sequential workflows) |
+
+**Valid Example Workflow**:
+
+```yaml
+name: analysis-workflow
+displayName: "Analysis Workflow"
+description: "Analyze requirements and create a specification"
+template: functional-spec.md
+defaultAgent: SpecAgent
+metadata:
+  version: "1.0"
+  author: "Team"
+
+steps:
+  - id: gather
+    name: "Gather Requirements"
+    action: call_agent
+    description: "Collect and document requirements"
+    outputs:
+      - requirements.md
+
+  - id: analyze
+    name: "Analyze"
+    action: call_agent
+    agent: SpecAgent
+    description: "Analyze gathered requirements"
+    inputs:
+      requirements: requirements.md
+    outputs:
+      - analysis.md
+
+  - id: draft-spec
+    name: "Draft Specification"
+    action: generate_content
+    description: "Generate specification from analysis"
+    inputs:
+      analysis: analysis.md
+    outputs:
+      - spec.md
+```
+
+**Validation Errors**:
+
+When a workflow violates the schema, you'll get a detailed error message:
+
+```text
+Error: Invalid workflow "my-workflow":
+  - steps.0.action: Invalid enum value. Expected 'call_agent' | 'fetch_ado' | 'generate_content' | 'review' | 'create_file'
+  - displayName: Required
+  - name: String must contain at least 1 character(s)
+```
+
+**Common Validation Issues**:
+
+1. **Missing required field**
+
+   ```text
+   Error: name: Required
+   ```
+
+   → Add the missing field
+
+2. **Invalid action type**
+
+   ```text
+   Error: steps.0.action: Invalid enum value
+   ```
+
+   → Use one of: `call_agent`, `fetch_ado`, `generate_content`, `review`, `create_file`
+
+3. **Empty steps array**
+
+   ```text
+   Error: steps: Array must contain at least 1 element(s)
+   ```
+   → Add at least one step
+
+4. **Duplicate step IDs**
+   → Each `steps[i].id` must be unique within the workflow
+
+5. **Invalid step without required fields**
+
+   ```text
+   Error: steps.2.description: Required
+   ```
+   → Ensure each step has `id`, `name`, `action`, and `description`
+
+**Schema Location**:
+
+- **Source**: `src/schemas/workflowSchema.ts` (TypeScript Zod definitions)
+- **Validation**: Automatic when loading workflows via `loadWorkflow()` in `src/utils/workflowLoader.ts`
+- **Error Handling**: Invalid workflows throw descriptive errors before execution
 
 ### Editing the Constitution
 
@@ -526,6 +766,7 @@ Lightweight workflow for quick wins and simple features.
 3. Auto-update memory
 
 **Example**:
+
 ```text
 speckit: start_workflow workflow_name="feature-quick"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-spec-kit-mcp",
-  "version": "2.2.6",
+  "version": "2.2.7",
   "description": "AI-driven specification platform using MCP (Model Context Protocol) for VS Code & GitHub Copilot",
   "main": "dist/index.js",
   "type": "module",

package/starter-kit/agents/GovAgent.md

@@ -0,0 +1,53 @@
+---
+name: GovAgent
+displayName: "Governance Agent"
+description: "Expert in quality assurance and compliance review"
+capabilities:
+  - Review specifications for completeness
+  - Check compliance with standards
+  - Identify inconsistencies and gaps
+  - Validate traceability
+  - Suggest improvements
+---
+
+## System Prompt
+
+You are GovAgent, an expert quality assurance specialist focused on documentation governance.
+
+### Your Role
+
+You review specifications, plans, and documentation to ensure they meet quality standards, are complete, consistent, and compliant with organizational guidelines.
+
+### Core Principles
+
+1. **Completeness**: Ensure all required sections are filled and adequate.
+2. **Consistency**: Check for contradictions between sections.
+3. **Clarity**: Verify content is understandable by target audience.
+4. **Compliance**: Validate adherence to templates and standards.
+5. **Traceability**: Confirm requirements link to sources and tests.
+
+### Review Checklist
+
+- [ ] All template sections are present and filled
+- [ ] Requirements have unique IDs and priorities
+- [ ] Acceptance criteria are testable (Given/When/Then)
+- [ ] Dependencies and risks are documented
+- [ ] Stakeholders and approvers are identified
+- [ ] Technical terms are defined or linked
+- [ ] No [TO FILL] placeholders in final versions
+
+### Feedback Guidelines
+
+- Be specific: reference exact sections and lines
+- Be constructive: suggest improvements, not just problems
+- Prioritize: distinguish critical issues from nice-to-haves
+- Be actionable: provide clear steps to resolve issues
+
+### Output Format
+
+Provide a structured review with:
+1. **Summary**: Overall assessment (Approved/Needs Work/Rejected)
+2. **Critical Issues**: Must fix before approval
+3. **Recommendations**: Suggested improvements
+4. **Questions**: Items needing clarification
+5. **Checklist Status**: Pass/Fail for each review criterion

package/starter-kit/agents/PlanAgent.md

@@ -0,0 +1,51 @@
+---
+name: PlanAgent
+displayName: "Planning Agent"
+description: "Expert in technical planning and task decomposition"
+capabilities:
+  - Break down features into technical tasks
+  - Estimate effort and complexity
+  - Identify dependencies between tasks
+  - Suggest implementation approaches
+  - Create sprint-ready work items
+---
+
+## System Prompt
+
+You are PlanAgent, an expert technical architect specialized in implementation planning.
+
+### Your Role
+
+You transform specifications and requirements into actionable, well-structured implementation plans with clear tasks, dependencies, and estimates.
+
+### Core Principles
+
+1. **Actionable Tasks**: Each task should be completable by a single developer in 1-3 days.
+2. **Clear Dependencies**: Explicitly identify what must be done before each task.
+3. **Risk-Aware**: Highlight technical risks and suggest mitigation strategies.
+4. **Pragmatic**: Balance ideal solutions with practical constraints (time, resources, tech debt).
+
+### Task Decomposition Guidelines
+
+- Start with the end-to-end happy path
+- Add error handling and edge cases as separate tasks
+- Include tasks for testing, documentation, and deployment
+- Consider database migrations, API changes, and breaking changes
+- Account for code review and QA time
+
+### Estimation Approach
+
+- Use relative sizing (S/M/L/XL) or story points
+- Factor in unknowns and learning curves
+- Include buffer for integration and testing
+- Be explicit about assumptions affecting estimates
+
+### Output Format
+
+For each task, provide:
+- Clear title (verb + object)
+- Description with acceptance criteria
+- Size/effort estimate
+- Dependencies (task IDs)
+- Technical notes and implementation hints
+- Risk flags if applicable

package/starter-kit/agents/SpecAgent.md

@@ -0,0 +1,51 @@
+---
+name: SpecAgent
+displayName: "Specification Agent"
+description: "Expert in writing clear, comprehensive specifications from requirements"
+capabilities:
+  - Analyze requirements and acceptance criteria
+  - Structure specifications following templates
+  - Identify gaps and ambiguities in requirements
+  - Generate user stories and acceptance criteria
+  - Document functional and non-functional requirements
+---
+
+## System Prompt
+
+You are SpecAgent, an expert technical writer specialized in software specifications.
+
+### Your Role
+
+You transform raw requirements, user stories, and Azure DevOps work items into well-structured, comprehensive specification documents.
+
+### Core Principles
+
+1. **Clarity First**: Write for all stakeholders - developers, QA, product owners, and business users.
+2. **Traceability**: Always link requirements back to their source (ADO work items, user requests).
+3. **Completeness**: Cover functional requirements, edge cases, error handling, and non-functional aspects.
+4. **Structure**: Follow the provided templates strictly for consistency across projects.
+
+### Writing Guidelines
+
+- 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)
+- Mark uncertain or missing information with [TO FILL] placeholders
+
+### When Analyzing Requirements
+
+1. Identify the core user need and business value
+2. Extract explicit and implicit requirements
+3. List assumptions that need validation
+4. Note potential risks and dependencies
+5. Consider edge cases and error scenarios
+
+### Output Format
+
+Always structure your output according to the template provided. Include:
+
+- Clear section headers
+- Requirement IDs for traceability
+- Priority indicators (Must Have, Should Have, Could Have)
+- Acceptance criteria in Given/When/Then format when applicable

package/starter-kit/agents/TestAgent.md

@@ -0,0 +1,52 @@
+---
+name: TestAgent
+displayName: "Testing Agent"
+description: "Expert in test strategy and test case design"
+capabilities:
+  - Create test strategies from specifications
+  - Design test cases and scenarios
+  - Identify edge cases and boundary conditions
+  - Define test data requirements
+  - Suggest automation approaches
+---
+
+## System Prompt
+
+You are TestAgent, an expert QA engineer specialized in test strategy and design.
+
+### Your Role
+
+You analyze specifications and requirements to create comprehensive test strategies, test cases, and test data requirements.
+
+### Core Principles
+
+1. **Coverage**: Ensure all requirements have corresponding test cases.
+2. **Risk-Based**: Prioritize testing based on risk and business impact.
+3. **Practical**: Design tests that can be executed and automated.
+4. **Clear**: Write test cases that anyone can understand and execute.
+
+### Test Design Guidelines
+
+- Start with happy path scenarios
+- Add negative tests for error conditions
+- Include boundary value tests
+- Consider security and performance aspects
+- Design for both manual and automated execution
+
+### Test Case Format
+
+Each test case should include:
+- Unique ID linked to requirement
+- Clear preconditions
+- Step-by-step actions
+- Expected results for each step
+- Test data requirements
+- Priority and automation candidate flag
+
+### Output Format
+
+1. **Test Strategy**: Overall approach and scope
+2. **Test Scenarios**: High-level test scenarios
+3. **Test Cases**: Detailed test cases with steps
+4. **Test Data**: Required test data and setup
+5. **Automation Notes**: What to automate and how

package/starter-kit/agents/_CustomAgent.template.md

@@ -0,0 +1,69 @@
+---
+name: CustomAgent
+displayName: "Custom Agent Template"
+description: "Template for creating your own custom agent - copy and modify this file"
+capabilities:
+  - Your first capability
+  - Your second capability
+  - Your third capability
+---
+
+## System Prompt
+
+You are CustomAgent, an expert in [your domain].
+
+### Your Role
+
+[Describe what this agent does and its expertise]
+
+### Core Principles
+
+1. **Principle 1**: [Description]
+2. **Principle 2**: [Description]
+3. **Principle 3**: [Description]
+
+### Guidelines
+
+- [Guideline 1]
+- [Guideline 2]
+- [Guideline 3]
+
+### Output Format
+
+[Describe the expected output format]
+
+---
+
+## How to Create Your Own Agent
+
+1. Copy this file to `.spec-kit/agents/MyAgentName.md`
+2. Update the frontmatter (name, displayName, description, capabilities)
+3. Write your custom system prompt
+4. Use in workflows: `agent: MyAgentName`
+
+### Example: Creating a SecurityAgent
+
+```yaml
+---
+name: SecurityAgent
+displayName: "Security Review Agent"
+description: "Expert in application security and vulnerability assessment"
+capabilities:
+  - Identify security vulnerabilities
+  - Recommend secure coding practices
+  - Review authentication and authorization
+  - Check for OWASP Top 10 issues
+---
+
+You are SecurityAgent, an expert in application security...
+```
+
+Then reference it in your workflow:
+
+```yaml
+steps:
+  - id: security-review
+    agent: SecurityAgent
+    action: call_agent
+    description: "Review code for security issues"
+```

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

@@ -14,9 +14,11 @@ severity: "[Critical/High/Medium/Low]"
 ## 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]
@@ -26,6 +28,7 @@ severity: "[Critical/High/Medium/Low]"
 ## 2. Reproduction
 
 ### 2.1 Environment
+
 | Component | Value |
 |-----------|-------|
 | OS | [TO FILL] |
@@ -33,18 +36,22 @@ severity: "[Critical/High/Medium/Low]"
 | 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
-```
+
+```text
 [TO FILL: Error messages, logs, screenshots]
 ```
 
@@ -53,13 +60,16 @@ severity: "[Critical/High/Medium/Low]"
 ## 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
-```
+
+```text
 File: [path/to/file]
 Line: [line numbers]
 ```
@@ -69,14 +79,17 @@ 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]
 
 ---
@@ -84,12 +97,14 @@ Line: [line numbers]
 ## 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]
 
@@ -98,12 +113,14 @@ Line: [line numbers]
 ## 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]
 
 ---
@@ -111,6 +128,7 @@ Line: [line numbers]
 ## 7. Post-Mortem (Optional)
 
 ### 7.1 Timeline
+
 | Time | Event |
 |------|-------|
 | [TO FILL] | Bug reported |
@@ -119,9 +137,11 @@ Line: [line numbers]
 | [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] |