13 agents. 57 MCP tools. 10-phase pipeline. One plugin.

Agentic Spec-Driven Development

Website · Getting Started · npm · Security

Specky is a complete Spec-Driven Development plugin — 13 specialized agents, 57 MCP tools, 22 prompts, 8 skills, and 14 automation hooks — that enforces a deterministic 10-phase pipeline from any input (meeting transcripts, documents, Figma designs, or natural language prompts) through specifications, architecture, infrastructure as code, implementation, and deployment.

The plugin is powered by the specky-sdd MCP engine and the Spec-Kit methodology. Install Specky and you get everything: the agents orchestrate the pipeline, the tools enforce validation, the hooks guard every phase transition, and the skills provide domain knowledge.

A plugin is a complete AI development package — not just a tool server. It bundles everything your AI IDE needs into a single installable unit:

An MCP server gives you tools. A plugin gives you the experience:

• Tools alone: You call sdd_write_spec and hope you're in the right phase, with the right prerequisites, on the right branch.
• Plugin: You type @specky-orchestrator and the agent validates your phase, checks your branch, loads the right skill, calls the right tool, runs pre/post hooks, and pauses for LGTM before advancing.

The MCP engine is the runtime. The plugin is the product.

Specky is distributed via APM (Agent Package Manager) — Microsoft's open-source dependency manager for AI agents:

# Install APM (one-time) — pick one:
curl -sSL https://aka.ms/apm-unix | sh        # macOS / Linux
brew install microsoft/apm/apm                 # Homebrew
irm https://aka.ms/apm-windows | iex           # Windows PowerShell

# Then install Specky:
apm install paulasilvatech/specky

This installs all 13 agents, 22 prompts, 8 skills, 14 hooks, configures the MCP server, and generates a lock file (apm.lock.yaml) for version reproducibility. No configuration drift across your team. See APM installation docs for more options.

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.

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:

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.

• Node.js 18+: Download here
• An AI IDE: VS Code with Copilot, Claude Code, Cursor, or Windsurf

Install APM first, then:

apm install paulasilvatech/specky

Open Copilot Chat and type:

@specky-onboarding

The onboarding wizard detects your project context (greenfield/brownfield/modernization) and guides you through setup.

@specky-orchestrator run the pipeline for a todo API

The orchestrator coordinates all 10 phases: Init → Research → Specify → Design → Tasks → Implement → Verify → Review → Release, with LGTM gates at Specify, Design, and Tasks.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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

> 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.

> 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.

> 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.

> 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.

> 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

> 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

> 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 57 Tools for a complete reference.

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

> 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

> 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."

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.

> 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.

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.

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.

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

> 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.

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.

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.

> 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

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.

> 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

> 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.

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.

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 complete plugin that reimplements that methodology as 57 enforceable MCP tools with 13 agents, 22 prompts, 8 skills, and 14 hooks. It enforces how to do it.

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 is installed via apm install paulasilvatech/specky. See the Installation section for details.

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.

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()

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.

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

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"
}

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/.

Specky is built with enterprise adoption in mind.

• 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

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

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.

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

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.

• 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

# 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

Have a feature request? Open an issue.

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

• 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

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