Specky

Table of Contents

What is Specky?

Specky is an open-source MCP server that turns the Spec-Kit SDD methodology into a programmable enforcement engine with 56 validated tools. It provides a deterministic pipeline from any input (meeting transcripts, documents, Figma designs, or natural language prompts) through specifications, architecture, infrastructure as code, implementation, and deployment.

Spec-Kit provides the methodology: EARS notation, gated pipeline phases, constitution model, quality patterns. Specky reimplements all of it as MCP tools and adds programmatic enforcement: a state machine that blocks phase-skipping, an EARS validator, cross-artifact analysis, compliance engines, test generation, and MCP-to-MCP routing.

Install Specky and you get both. The Spec-Kit methodology is already built in. It works inside any AI IDE that supports MCP, via .github/agents/ or .claude/commands/, and natively in Cursor, Windsurf, or any MCP-compatible client. See how they complement each other.

Why Specifications Matter in the AI Era

The Problem: Vibe Coding

AI coding assistants are fast but chaotic. You say "build me a login system" and the AI generates code immediately, skipping requirements, guessing architecture, and producing something that works but doesn't match what anyone actually needed. This is vibe coding: generating code based on vibes instead of validated specifications.

The result? Teams spend 40% of their time on rework because requirements were never written down, acceptance criteria were never defined, and there's no way to verify the code matches the original intent.

The Solution: Deterministic Development

Specifications are structured documents that describe what the system must do before anyone writes code. They've existed for decades in engineering, but AI development mostly ignores them. Specky brings them back, with AI enforcement.

Key concepts you should know:

How Specky Enforces Determinism

Specky adds a deterministic engine between your intent and your code:

• State Machine: 10 mandatory phases, no skipping. Init, Discover, Specify, Clarify, Design, Tasks, Analyze, Implement, Verify, Release.

• EARS Validator: Every requirement validated against 6 patterns. No vague statements pass.

• Cross-Artifact Analysis: Automatic alignment checking between spec, design, and tasks. Orphaned requirements are flagged instantly.

• MCP-to-MCP Architecture: Specky outputs structured JSON that your AI client routes to GitHub, Azure DevOps, Jira, Terraform, Figma, and Docker MCP servers. No vendor lock-in.

The AI is the operator; Specky is the engine. The AI's creativity is channeled through a validated pipeline instead of producing unstructured guesswork. For a complete educational walkthrough, see GETTING-STARTED.md.

What Makes Specky Different

Quick Start

Prerequisites

• Node.js 18+: Download here

• An AI IDE: VS Code with Copilot, Claude Code, Claude Desktop, Cursor, or Windsurf

Step 1: Choose Your Installation Scope

Step 2: Install

Install globally so specky-sdd is always available — no re-download on every run:

npm install -g specky-sdd

Then configure your IDE to use the global install:

VS Code (.vscode/mcp.json):

{
  "servers": {
    "specky": {
      "command": "specky-sdd",
      "env": { "SDD_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Claude Code:

claude mcp add specky -- specky-sdd

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "specky": {
      "command": "specky-sdd",
      "env": { "SDD_WORKSPACE": "/path/to/your/project" }
    }
  }
}

Add a config file to the repo so teammates get Specky automatically on clone — no global install needed.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "specky": {
      "command": "specky-sdd",
      "env": { "SDD_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Claude Code:

claude mcp add specky -- specky-sdd

Commit .vscode/mcp.json to Git so every team member gets Specky automatically.

Run Specky as an HTTP server in a container:

docker run -d --name specky -p 3200:3200 -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest

Verify it's running:

curl http://localhost:3200/health

Point any MCP client that supports HTTP to http://localhost:3200/mcp

Stop when done:

docker stop specky && docker rm specky

Step 3: Verify

Open your AI IDE and type:

> What tools does Specky have?

The AI should list the 56 SDD tools. If you see them, Specky is working.

Try It Now

Once connected, type this in your AI chat to see Specky in action:

> Initialize a Specky project for a todo API and help me define the scope

Specky creates the project structure and asks you 7 discovery questions. From here, follow the guide for your project type:

Tip: New to Spec-Driven Development? Specky already includes all the SDD methodology from Spec-Kit. Just install Specky and the pipeline guides you through every phase with educative outputs that explain the concepts as you work.

Where Specifications Live

Every feature gets its own numbered directory inside .specs/. This keeps specifications, design documents, and quality reports together as a self-contained package.

your-project/
├── src/                          ← Your application code
├── .specs/                       ← All Specky specifications
│   ├── 001-user-authentication/  ← Feature #1
│   │   ├── CONSTITUTION.md       ← Project principles and governance
│   │   ├── SPECIFICATION.md      ← EARS requirements with acceptance criteria
│   │   ├── DESIGN.md             ← Architecture, data model, API contracts
│   │   ├── RESEARCH.md           ← Resolved unknowns and technical decisions
│   │   ├── TASKS.md              ← Implementation breakdown with dependencies
│   │   ├── ANALYSIS.md           ← Quality gate report
│   │   ├── CHECKLIST.md          ← Domain-specific quality checklist
│   │   ├── CROSS_ANALYSIS.md     ← Spec-design-tasks alignment score
│   │   ├── COMPLIANCE.md         ← Regulatory framework validation
│   │   ├── VERIFICATION.md       ← Drift and phantom task detection
│   │   └── .sdd-state.json       ← Pipeline state (current phase, history)
│   ├── 002-payment-gateway/      ← Feature #2
│   └── 003-notification-system/  ← Feature #3
├── reports/                      ← Cross-feature analysis reports
└── .specky/config.yml            ← Optional project-level configuration

Naming convention: NNN-feature-name, zero-padded number + kebab-case name. Each directory is independent; you can work on multiple features simultaneously.

Input Methods: 6 Ways to Start

Specky accepts multiple input types. Choose the one that matches your starting point:

1. Natural Language Prompt (simplest)

Type your idea directly into the AI chat. No files needed.

> I need a feature for user authentication with email/password login,
  password reset via email, and JWT session management

The AI calls sdd_init + sdd_discover to structure your idea into a spec project.

Best for: Quick prototyping, brainstorming, greenfield projects.

2. Meeting Transcript (VTT / SRT / TXT / MD)

Import a transcript from Teams, Zoom, or Google Meet. Specky extracts topics, decisions, action items, and requirements automatically.

> Import the requirements meeting transcript and create a specification

The AI calls sdd_import_transcript → extracts:

• Participants and speakers

• Topics discussed with summaries

• Decisions made

• Action items

• Raw requirement statements

• Constraints mentioned

• Open questions

Supported formats: .vtt (WebVTT), .srt (SubRip), .txt, .md

Pro tip: Use sdd_auto_pipeline to go from transcript to complete spec in one step:

> Run the auto pipeline from this meeting transcript: /path/to/meeting.vtt

Got multiple transcripts? Use batch processing:

> Batch import all transcripts from the meetings/ folder

The AI calls sdd_batch_transcripts → processes every .vtt, .srt, .txt, and .md file in the folder.

3. Existing Documents (PDF / DOCX / PPTX)

Import requirements documents, RFPs, architecture decks, or any existing documentation.

> Import this requirements document and create a specification:
  /path/to/requirements.pdf

The AI calls sdd_import_document → converts to Markdown, extracts sections, and feeds into the spec pipeline.

Supported formats: .pdf, .docx, .pptx, .txt, .md

Batch import from a folder:

> Import all documents from the docs/ folder into specs

The AI calls sdd_batch_import → processes every supported file in the directory.

Tip: For best results with PDF/DOCX, install the optional mammoth and pdfjs-dist packages for enhanced formatting, table extraction, and image handling.

4. Figma Design (design-to-spec)

Convert Figma designs into requirements specifications. Works with the Figma MCP server.

> Convert this Figma design into a specification:
  https://figma.com/design/abc123/my-app

The AI calls sdd_figma_to_spec → extracts components, layouts, and interactions, then routes to the Figma MCP server for design context.

Best for: Design-first workflows, UI-driven projects.

5. Codebase Scan (brownfield / modernization)

Scan an existing codebase to detect tech stack, frameworks, structure, and patterns before writing specs.

> Scan this codebase and tell me what we're working with

The AI calls sdd_scan_codebase → detects:

Best for: Understanding an existing project before adding features or modernizing.

6. Raw Text (paste anything)

No file? Just paste the content directly. Every import tool accepts a raw_text parameter as an alternative to a file path.

> Here's the raw requirements from the client email:

  The system needs to handle 10,000 concurrent users...
  Authentication must support SSO via Azure AD...
  All data must be encrypted at rest and in transit...

  Import this and create a specification.

Three Project Types, One Pipeline

Specky adapts to any project type. The pipeline is the same; the starting point is what changes.

Greenfield Project: Start from Scratch

Scenario: You're building a new application with no existing code.

Step 1: Initialize and discover

> I'm building a task management API. Initialize a Specky project and help
  me define the scope.

The AI calls sdd_init → creates .specs/001-task-management/CONSTITUTION.md Then calls sdd_discover → asks you 7 structured questions:

1. Scope: What problem does this solve? What are the boundaries of v1?

2. Users: Who are the primary users? What are their skill levels?

3. Constraints: Language, framework, hosting, budget, timeline?

4. Integrations: What external systems, APIs, or services?

5. Performance: Expected load, concurrent users, response times?

6. Security: Authentication, authorization, compliance requirements?

7. Deployment: CI/CD, monitoring, rollback strategy?

Answer each question. Your answers feed directly into the specification.

Step 2: Write the specification

> Write the specification based on my discovery answers

The AI calls sdd_write_spec → creates SPECIFICATION.md with EARS requirements:

## Requirements

REQ-001 [Ubiquitous]: The system shall provide a REST API for task CRUD operations.

REQ-002 [Event-driven]: When a user creates a task, the system shall assign
a unique identifier and return it in the response.

REQ-003 [State-driven]: While a task is in "in-progress" state, the system
shall prevent deletion without explicit force confirmation.

REQ-004 [Unwanted]: If the API receives a malformed request body, then the
system shall return a 400 status with a descriptive error message.

The AI pauses here. Review .specs/001-task-management/SPECIFICATION.md and reply LGTM when satisfied.

Step 3: Design the architecture

> LGTM.proceed to design

The AI calls sdd_write_design → creates DESIGN.md with:

• System architecture diagram (Mermaid)

• Data model / ER diagram

• API contracts with endpoints, request/response schemas

• Sequence diagrams for key flows

• Technology decisions with rationale

Review and reply LGTM.

Step 4: Break into tasks

> LGTM.create the task breakdown

The AI calls sdd_write_tasks → creates TASKS.md with implementation tasks mapped to acceptance criteria, dependencies, and estimated complexity.

Step 5: Quality gates

> Run analysis, compliance check for SOC2, and generate all diagrams

The AI calls:

• sdd_run_analysis → completeness audit, orphaned criteria detection

• sdd_compliance_check → SOC2 controls validation

• sdd_generate_all_diagrams → architecture, sequence, ER, flow, dependency, traceability diagrams

Step 6: Generate infrastructure and tests

> Generate Terraform for Azure, a Dockerfile, and test stubs for vitest

The AI calls:

• sdd_generate_iac → Terraform configuration

• sdd_generate_dockerfile → Dockerfile + docker-compose

• sdd_generate_tests → Test stubs with acceptance criteria mapped to test cases

Step 7: Export and ship

> Export tasks to GitHub Issues and create a PR

The AI calls sdd_export_work_items + sdd_create_pr → generates work item payloads and PR body with full spec traceability.

Next: Next: Learn about EARS notation to understand the requirement patterns, or see All 56 Tools for a complete reference.

Brownfield Project: Add Features to Existing Code

Scenario: You have a running application and need to add a new feature with proper specifications.

Step 1: Scan the codebase first

> Scan this codebase so Specky understands what we're working with

The AI calls sdd_scan_codebase → detects tech stack, framework, directory structure. This context informs all subsequent tools.

Detected: TypeScript + Next.js + npm + Node.js
Files: 247 across 32 directories

Step 2: Initialize with codebase context

> Initialize a feature for adding real-time notifications to this Next.js app.
  Use the codebase scan results as context.

The AI calls sdd_init → creates .specs/001-real-time-notifications/CONSTITUTION.md Then calls sdd_discover with the codebase summary → the 7 discovery questions now include context about your existing tech stack:

"What technical constraints exist? Note: This project already uses TypeScript, Next.js, npm, Node.js. Consider compatibility with the existing stack."

Step 3: Import existing documentation

If you have existing PRDs, architecture docs, or meeting notes:

> Import the PRD for notifications: /docs/notifications-prd.pdf

The AI calls sdd_import_document → converts to Markdown and adds to the spec directory. The content is used as input when writing the specification.

Step 4: Write spec with codebase awareness

> Write the specification for real-time notifications. Consider the existing
  Next.js architecture and any patterns already in the codebase.

The specification references existing components, APIs, and patterns from the codebase scan.

Step 5: Check for drift

After implementation, verify specs match the code:

> Check if the implementation matches the specification

The AI calls sdd_check_sync → generates a drift report flagging any divergence between spec and code.

Step 6: Cross-feature analysis

If you have multiple features specified:

> Run cross-analysis across all features to find conflicts

The AI calls sdd_cross_analyze → checks for contradictions, shared dependencies, and consistency issues across .specs/001-*, .specs/002-*, etc.

Next: Next: See compliance frameworks for regulatory validation, or MCP integration for routing to external tools.

Modernization Project: Assess and Upgrade Legacy Systems

Scenario: You have a legacy system that needs assessment, documentation, and incremental modernization.

Step 1: Scan and document the current state

> Scan this legacy codebase and help me understand what we have

The AI calls sdd_scan_codebase → maps the technology stack, directory tree, and file counts.

Step 2: Import all existing documentation

Gather everything you have.architecture documents, runbooks, meeting notes about the system:

> Batch import all documents from /docs/legacy-system/ into specs

The AI calls sdd_batch_import → processes PDFs, DOCX, PPTX, and text files. Each becomes a Markdown reference in the spec directory.

Step 3: Import stakeholder meetings

If you have recorded meetings with stakeholders discussing the modernization:

> Batch import all meeting transcripts from /recordings/

The AI calls sdd_batch_transcripts → extracts decisions, requirements, constraints, and open questions from every transcript.

Step 4: Create the modernization specification

> Write a specification for modernizing the authentication module.
  Consider the legacy constraints from the imported documents and
  meeting transcripts.

The specification accounts for:

• Current system behavior (from codebase scan)

• Existing documentation (from imported docs)

• Stakeholder decisions (from meeting transcripts)

• Migration constraints and backward compatibility

Step 5: Compliance assessment

Legacy systems often need compliance validation during modernization:

> Run compliance checks against HIPAA and SOC2 for the modernized auth module

The AI calls sdd_compliance_check → validates the specification against regulatory controls and flags gaps.

Step 6: Generate migration artifacts

> Generate the implementation plan, Terraform for the new infrastructure,
  and a runbook for the migration

The AI calls:

• sdd_implement → phased implementation plan with checkpoints

• sdd_generate_iac → infrastructure configuration for the target environment

• sdd_generate_runbook → operational runbook with rollback procedures

Step 7: Generate onboarding for the team

> Generate an onboarding guide for developers joining the modernization project

The AI calls sdd_generate_onboarding → creates a guide covering architecture decisions, codebase navigation, development workflow, and testing strategy.

Next: Next: See compliance frameworks for regulatory validation during modernization, or project configuration to customize Specky for your team.

Pipeline and LGTM Gates

Every Specky project follows the same 10-phase pipeline. The state machine blocks phase-skipping. You cannot jump from Init to Design without completing Specify first.

LGTM gates: After each major phase (Specify, Design, Tasks), the AI pauses and asks you to review. Reply LGTM to proceed. This ensures human oversight at every quality gate.

Feedback loop: If sdd_verify_tasks detects drift between specification and implementation, Specky routes you back to the Specify phase to correct the divergence before proceeding.

Advancing phases: If you need to manually advance:

> Advance to the next phase

The AI calls sdd_advance_phase → moves the pipeline forward if all prerequisites are met.

All artifacts are saved in .specs/NNN-feature/. See Input Methods for how to feed data into the pipeline.

All 56 Tools

Input and Conversion (5)

Pipeline Core (8)

Quality and Validation (5)

Diagrams and Visualization (4) -- 17 Diagram Types

Infrastructure as Code (3)

Dev Environment (3)

Integration and Export (5)

Documentation (4)

Utility (5)

Testing (3)

Turnkey Specification (1)

Checkpointing (3)

Ecosystem (1)

The Spec-Driven Development Platform

How Spec-Kit and Specky Complement Each Other

Spec-Kit is the open-source SDD methodology: EARS notation, gated pipeline phases, constitution model, 25+ specialized agents, and Markdown prompt templates. It defines what to do.

Specky is the MCP engine that reimplements that methodology as 53 enforceable tools with programmatic validation. It enforces how to do it.

Together: The Complete SDD Layer

When you install Specky, you get the full Spec-Kit methodology reimplemented as validated MCP tools. No separate installation of Spec-Kit needed. But Spec-Kit remains available as a standalone learning tool for teams that want to adopt SDD concepts before using the engine.

Together they form the SDD layer of the GitHub + Microsoft enterprise platform. Specky reimplements the Spec-Kit methodology as enforceable MCP tools with compliance, traceability, and automation built in.

{
  "servers": {
    "specky": {
      "command": "specky-sdd"
    }
  }
}

Note: This example assumes specky-sdd is installed globally (npm install -g specky-sdd). See the Installation section for per-workspace and Docker alternatives.

Project Configuration

Create .specky/config.yml in your project root to customize Specky:

# .specky/config.yml
templates_path: ./my-templates       # Override built-in templates
default_framework: vitest            # Default test framework
compliance_frameworks: [hipaa, soc2] # Frameworks to check
audit_enabled: true                  # Enable audit trail

When templates_path is set, Specky uses your custom templates instead of the built-in ones. When audit_enabled is true, tool invocations are logged locally.

MCP Integration Architecture

Specky outputs structured JSON with routing instructions. Your AI client calls the appropriate external MCP server:

Specky --> sdd_export_work_items(platform: "azure_boards") --> JSON payload
  --> AI Client --> Azure DevOps MCP --> create_work_item()

Specky --> sdd_validate_iac(provider: "terraform") --> validation payload
  --> AI Client --> Terraform MCP --> plan/validate

Specky --> sdd_figma_to_spec(file_key: "abc123") --> Figma request
  --> AI Client --> Figma MCP --> get_design_context()

Supported External MCP Servers

EARS Notation

Every requirement in Specky follows EARS (Easy Approach to Requirements Syntax):

The EARS validator programmatically checks every requirement against these 6 patterns. Vague terms like "fast", "good", "easy" are flagged automatically.

Compliance Frameworks

Built-in compliance checking against:

• HIPAA: Access control, audit, encryption, PHI protection

• SOC 2: Logical access, monitoring, change management, incident response

• GDPR: Lawful processing, right to erasure, data portability, breach notification

• PCI-DSS: Firewall, stored data protection, encryption, user identification

• ISO 27001: Security policies, access control, cryptography, incident management

Educative Outputs

Every tool response includes structured guidance:

{
  "explanation": "What was done and why",
  "next_steps": "Guided next action with command suggestion",
  "learning_note": "Educational context about the concept",
  "diagram": "Mermaid diagram relevant to the output"
}

Complete Pipeline Flow

From any input to production -- fully automated, MCP-orchestrated, with artifacts and diagrams generated at every step. All artifacts are saved in .specs/NNN-feature/.

Enterprise Ready

Specky is built with enterprise adoption in mind.

Security Posture

• 2 runtime dependencies — minimal attack surface (@modelcontextprotocol/sdk, zod)

• Zero outbound network requests — all data stays local

• No eval() or dynamic code execution — template rendering is string replacement only

• Path traversal prevention: FileManager sanitizes all paths, blocks .. sequences

• Zod .strict() validation — every tool input is schema-validated; unknown fields rejected

• security-scan hook blocks commits containing hardcoded secrets (exit code 2)

• See SECURITY.md for full OWASP Top 10 coverage

• See docs/SYSTEM-DESIGN.md for complete security architecture

Security Best Practices

When using Specky, follow these practices to protect your data:

Data Sensitivity Guide

Key principle: Specky creates files only on your local filesystem. Nothing is sent to any cloud service unless you push to git or the AI client routes a payload to an external MCP server. You are always in control.

Compliance Validation

Built-in compliance checking validates your specifications against industry frameworks:

Audit Trail

Every pipeline phase produces a traceable artifact in .specs/NNN-feature/. The complete specification-to-code journey is documented in the SDD Journey document (docs/journey-{feature}.md) with phase timestamps, gate decisions, and traceability metrics.

Quality Gates

• Phase Validation — every tool validates it's being called in the correct pipeline phase

• Gate Enforcement — advancePhase() blocks if gate decision is BLOCK or CHANGES_NEEDED

• EARS Validator — programmatic requirement quality enforcement

• Cross-Artifact Analysis — automatic alignment checking between spec, design, and tasks

• Phase Enforcement — state machine blocks phase-skipping; required files gate advancement

• 507 unit tests — CI enforces thresholds on every push

Development

# Clone and setup
git clone https://github.com/paulasilvatech/specky.git
cd specky
npm install

# Build
npm run build

# Run tests (507 tests)
npm test

# Run tests with coverage report
npm run test:coverage

# Development mode (auto-reload on file changes)
npm run dev

# Verify MCP handshake (quick smoke test)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null

# Build and run with Docker locally
docker build -t specky-sdd:dev .
docker run -p 3200:3200 -v $(pwd):/workspace specky-sdd:dev
curl http://localhost:3200/health

Roadmap

v3.1 (current)

v3.2+ (planned)

Have a feature request? Open an issue.

Contributing

See CONTRIBUTING.md for architecture details and how to add tools, templates, or services.

Links

• CHANGELOG.md: Version history and release notes

• SECURITY.md: Vulnerability disclosure policy and OWASP Top 10 coverage

• CONTRIBUTING.md: How to add tools, templates, or services

• Spec-Kit: The SDD methodology foundation

• npm package: specky-sdd on npm

License

MIT. Created by Paula Silva | Americas Software GBB, Microsoft