{"id":47620820,"url":"https://github.com/paulasilvatech/specky","last_synced_at":"2026-04-01T22:03:18.760Z","repository":{"id":346021728,"uuid":"1187625576","full_name":"paulasilvatech/specky","owner":"paulasilvatech","description":"Specky — The open-source MCP server for Spec-Driven Development (SDD). The fun name, the serious engine.","archived":false,"fork":false,"pushed_at":"2026-03-22T04:01:13.000Z","size":441,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T10:32:53.603Z","etag":null,"topics":["ai-agent","claude","copilot","ears-notation","mcp","meeting-transcription","requirements-engineering","spec-driven-development","specification","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulasilvatech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T00:16:48.000Z","updated_at":"2026-03-22T04:01:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paulasilvatech/specky","commit_stats":null,"previous_names":["paulasilvatech/specky"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/paulasilvatech/specky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulasilvatech%2Fspecky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulasilvatech%2Fspecky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulasilvatech%2Fspecky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulasilvatech%2Fspecky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulasilvatech","download_url":"https://codeload.github.com/paulasilvatech/specky/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulasilvatech%2Fspecky/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","copilot","ears-notation","mcp","meeting-transcription","requirements-engineering","spec-driven-development","specification","typescript"],"created_at":"2026-04-01T22:03:14.429Z","updated_at":"2026-04-01T22:03:18.711Z","avatar_url":"https://github.com/paulasilvatech.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg src=\"media/specky-brand-logo.svg\" alt=\"Specky\" height=\"80\"\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cp\u003e\u003cstrong\u003e53 MCP tools. 10-phase pipeline. Works in any IDE.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003eAgentic Spec-Driven Development\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/tools-53_MCP-7c3aed?style=flat-square\" alt=\"53 Tools\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/phases-10_enforced-6d28d9?style=flat-square\" alt=\"10 Phases\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/diagrams-17_types-5b21b6?style=flat-square\" alt=\"17 Diagrams\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/compliance-6_frameworks-4c1d95?style=flat-square\" alt=\"6 Compliance\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-a78bfa?style=flat-square\" alt=\"MIT\"/\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/specky-sdd\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/specky-sdd?style=flat-square\u0026color=7c3aed\" alt=\"npm\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/paulasilvatech/specky/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/paulasilvatech/specky/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://securityscorecards.dev/viewer/?uri=github.com/paulasilvatech/specky\"\u003e\u003cimg src=\"https://api.securityscorecards.dev/projects/github.com/paulasilvatech/specky/badge\" alt=\"OpenSSF Scorecard\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/paulasilvatech/specky\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/paulasilvatech/specky?style=flat-square\u0026color=6d28d9\" alt=\"Stars\"/\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://paulasilvatech.github.io/specky/\"\u003eWebsite\u003c/a\u003e ·\n    \u003ca href=\"GETTING-STARTED.md\"\u003eGetting Started\u003c/a\u003e ·\n    \u003ca href=\"https://www.npmjs.com/package/specky-sdd\"\u003enpm\u003c/a\u003e ·\n    \u003ca href=\"SECURITY.md\"\u003eSecurity\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n## Table of Contents\n\n| | Section | Description |\n|---|---------|-------------|\n| **Start** | [What is Specky?](#what-is-specky) | Overview and ecosystem |\n| | [Why Specifications Matter](#why-specifications-matter-in-the-ai-era) | Vibe coding vs deterministic development |\n| | [Getting Started](GETTING-STARTED.md) | Complete educational guide |\n| **Use** | [Quick Start](#quick-start) | Install via npm or Docker, connect to your IDE |\n| | [Where Specifications Live](#where-specifications-live) | File structure and naming conventions |\n| | [Input Methods](#input-methods-6-ways-to-start) | 6 ways to feed Specky |\n| | [Three Project Types](#three-project-types-one-pipeline) | Greenfield, Brownfield, Modernization |\n| **Pipeline** | [Pipeline and LGTM Gates](#pipeline-and-lgtm-gates) | 10 phases with human review gates |\n| | [All 53 Tools](#all-53-tools) | Complete tool reference by category |\n| | [EARS Notation](#ears-notation) | The 6 requirement patterns |\n| **Enterprise** | [Compliance Frameworks](#compliance-frameworks) | HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 |\n| | [Enterprise Ready](#enterprise-ready) | Security, audit trail, quality gates |\n| **Platform** | [The SDD Platform](#the-spec-driven-development-platform) | Built on Spec-Kit, everything included |\n| | [Roadmap](#roadmap) | v3.0 current, v3.1+ planned |\n\n\n## What is Specky?\n\nSpecky is an open-source **MCP server** that turns the [Spec-Kit](https://github.com/paulasilvatech/spec-kit) SDD methodology into a **programmable enforcement engine** with 53 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.\n\n**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.\n\n**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](#the-spec-driven-development-platform).\n\n\n## Why Specifications Matter in the AI Era\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/why-specifications-matter.svg\" alt=\"Why Specifications Matter, From Vibe Coding to Deterministic Development\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n### The Problem: Vibe Coding\n\nAI 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.\n\nThe 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.\n\n### The Solution: Deterministic Development\n\n**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.\n\n**Key concepts you should know:**\n\n| Concept | What it is | Why it matters |\n|---------|-----------|----------------|\n| **Markdown** | The universal language that both humans and AI read fluently | All spec artifacts are `.md` files in your repo, versioned with Git |\n| **MCP** | Model Context Protocol — an open standard that lets AI assistants call external tools | Specky is an MCP server; any AI IDE can connect to it |\n| **EARS Notation** | A method for writing requirements that forces precision with 6 patterns | Eliminates vague statements like \"the system should be fast\" |\n| **Agents and Skills** | Specialized AI roles that invoke Specky tools with domain expertise | Defined in `.github/agents/` and `.claude/commands/` |\n\n### How Specky Enforces Determinism\n\nSpecky adds a **deterministic engine** between your intent and your code:\n\n- **State Machine**: 10 mandatory phases, no skipping. Init, Discover, Specify, Clarify, Design, Tasks, Analyze, Implement, Verify, Release.\n- **EARS Validator**: Every requirement validated against 6 patterns. No vague statements pass.\n- **Cross-Artifact Analysis**: Automatic alignment checking between spec, design, and tasks. Orphaned requirements are flagged instantly.\n- **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.\n\n\u003e **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](GETTING-STARTED.md).\n\n### What Makes Specky Different\n\n| Capability | Specky |\n|---|---|\n| Any input (PDF, DOCX, PPTX, transcript, Figma) to spec | 53 MCP tools handle all input formats |\n| EARS validation (programmatic, not AI guessing) | 5 patterns enforced at schema level |\n| Enforced pipeline (not suggestions) | 10 phases with actual gates that block advancement |\n| 17 diagram types generated automatically | C4 (4 levels), sequence, ER, activity, use case, DFD, deployment, network |\n| Infrastructure as Code | Terraform, Bicep, Dockerfile from DESIGN.md |\n| Work item export | GitHub Issues, Azure Boards, Jira via MCP-to-MCP routing |\n| 6 compliance frameworks | HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 built-in |\n| Cross-artifact traceability | Requirement to design to task to test to code |\n| Phantom task detection | Catches tasks marked done with no code evidence |\n| Property-based testing | fast-check (TypeScript) and Hypothesis (Python) |\n| Checkpoint/restore | Persistent snapshots of all spec artifacts |\n| 7 automation hooks | Tests, docs, security scan, spec sync, SRP, changelog, checkpoint |\n| Works in any MCP host | VS Code + Copilot, Claude Code, Cursor, Windsurf, or any MCP client |\n| Zero outbound network calls | Fully air-gapped, code never leaves your machine |\n| MIT open source | Fork it, extend it, audit it. No vendor lock, no seat pricing |\n\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 18+**: [Download here](https://nodejs.org/)\n- **An AI IDE**: VS Code with Copilot, Claude Code, Claude Desktop, Cursor, or Windsurf\n\n### Step 1: Choose Your Installation Scope\n\n| Scope | What it does | Best for |\n|-------|-------------|----------|\n| **Per workspace** (recommended) | Config file lives inside the repo, shared with the team via Git | Teams, open-source projects |\n| **Global (once)** | Installed on your machine, available in every repo automatically | Personal use, quick setup |\n\n### Step 2: Install\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003ePer Workspace: Per Workspace (recommended)\u003c/strong\u003e\u003c/summary\u003e\n\nNo global install needed. You add a config file to the repo and `npx` handles the rest.\n\n**For VS Code with GitHub Copilot** create `.vscode/mcp.json` in the repo root:\n\n```json\n{\n  \"servers\": {\n    \"specky\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specky-sdd\"],\n      \"env\": {\n        \"SDD_WORKSPACE\": \"${workspaceFolder}\"\n      }\n    }\n  }\n}\n```\n\n**For Claude Code** run this once inside the repo:\n\n```bash\nclaude mcp add specky -- npx -y specky-sdd\n```\n\n**For Cursor** add to MCP settings (Settings \u003e MCP Servers):\n\n```json\n{\n  \"specky\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"specky-sdd\"]\n  }\n}\n```\n\n\u003e **Tip:** Commit the config file to Git so every team member gets Specky automatically when they clone the repo.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGlobal: Global (once, all repos)\u003c/strong\u003e\u003c/summary\u003e\n\nInstall globally and Specky is available everywhere on your machine:\n\n```bash\nnpm install -g specky-sdd\n```\n\nThen configure your IDE to use the global install:\n\n**VS Code** (`.vscode/mcp.json`):\n```json\n{\n  \"servers\": {\n    \"specky\": {\n      \"command\": \"specky-sdd\",\n      \"env\": { \"SDD_WORKSPACE\": \"${workspaceFolder}\" }\n    }\n  }\n}\n```\n\n**Claude Code**:\n```bash\nclaude mcp add specky -- specky-sdd\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n| OS | Config location |\n|----|----------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n```json\n{\n  \"mcpServers\": {\n    \"specky\": {\n      \"command\": \"specky-sdd\",\n      \"env\": { \"SDD_WORKSPACE\": \"/path/to/your/project\" }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDocker: Docker (HTTP mode, no Node.js required)\u003c/strong\u003e\u003c/summary\u003e\n\nRun Specky as an HTTP server in a container:\n\n```bash\ndocker run -d --name specky -p 3200:3200 -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest\n```\n\nVerify it's running:\n\n```bash\ncurl http://localhost:3200/health\n```\n\nPoint any MCP client that supports HTTP to `http://localhost:3200/mcp`\n\nStop when done:\n\n```bash\ndocker stop specky \u0026\u0026 docker rm specky\n```\n\n\u003c/details\u003e\n\n### Step 3: Verify\n\nOpen your AI IDE and type:\n\n```\n\u003e What tools does Specky have?\n```\n\nThe AI should list the 53 SDD tools. If you see them, Specky is working.\n\n### Try It Now\n\nOnce connected, type this in your AI chat to see Specky in action:\n\n```\n\u003e Initialize a Specky project for a todo API and help me define the scope\n```\n\nSpecky creates the project structure and asks you 7 discovery questions. From here, follow the guide for your project type:\n\n| Your situation | Guide |\n|---------------|-------|\n| Building something new | [Greenfield](#greenfield-project-start-from-scratch) |\n| Adding features to existing code | [Brownfield](#brownfield-project-add-features-to-existing-code) |\n| Upgrading a legacy system | [Modernization](#modernization-project-assess-and-upgrade-legacy-systems) |\n\n\u003e **Tip:** **New to Spec-Driven Development?** Specky already includes all the SDD methodology from [Spec-Kit](https://github.com/paulasilvatech/spec-kit). Just install Specky and the pipeline guides you through every phase with [educative outputs](#educative-outputs) that explain the concepts as you work.\n\n\n## Where Specifications Live\n\nEvery feature gets its own numbered directory inside `.specs/`. This keeps specifications, design documents, and quality reports together as a self-contained package.\n\n```\nyour-project/\n├── src/                          ← Your application code\n├── .specs/                       ← All Specky specifications\n│   ├── 001-user-authentication/  ← Feature #1\n│   │   ├── CONSTITUTION.md       ← Project principles and governance\n│   │   ├── SPECIFICATION.md      ← EARS requirements with acceptance criteria\n│   │   ├── DESIGN.md             ← Architecture, data model, API contracts\n│   │   ├── RESEARCH.md           ← Resolved unknowns and technical decisions\n│   │   ├── TASKS.md              ← Implementation breakdown with dependencies\n│   │   ├── ANALYSIS.md           ← Quality gate report\n│   │   ├── CHECKLIST.md          ← Domain-specific quality checklist\n│   │   ├── CROSS_ANALYSIS.md     ← Spec-design-tasks alignment score\n│   │   ├── COMPLIANCE.md         ← Regulatory framework validation\n│   │   ├── VERIFICATION.md       ← Drift and phantom task detection\n│   │   └── .sdd-state.json       ← Pipeline state (current phase, history)\n│   ├── 002-payment-gateway/      ← Feature #2\n│   └── 003-notification-system/  ← Feature #3\n├── reports/                      ← Cross-feature analysis reports\n└── .specky/config.yml            ← Optional project-level configuration\n```\n\n**Naming convention:** `NNN-feature-name`, zero-padded number + kebab-case name. Each directory is independent; you can work on multiple features simultaneously.\n\n\n## Input Methods: 6 Ways to Start\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/input-methods.svg\" alt=\"Specky 6 Input Methods\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nSpecky accepts multiple input types. Choose the one that matches your starting point:\n\n### 1. Natural Language Prompt (simplest)\n\nType your idea directly into the AI chat. No files needed.\n\n```\n\u003e I need a feature for user authentication with email/password login,\n  password reset via email, and JWT session management\n```\n\nThe AI calls `sdd_init` + `sdd_discover` to structure your idea into a spec project.\n\n**Best for:** Quick prototyping, brainstorming, greenfield projects.\n\n### 2. Meeting Transcript (VTT / SRT / TXT / MD)\n\nImport a transcript from Teams, Zoom, or Google Meet. Specky extracts topics, decisions, action items, and requirements automatically.\n\n```\n\u003e Import the requirements meeting transcript and create a specification\n```\n\nThe AI calls `sdd_import_transcript` → extracts:\n- Participants and speakers\n- Topics discussed with summaries\n- Decisions made\n- Action items\n- Raw requirement statements\n- Constraints mentioned\n- Open questions\n\n**Supported formats:** `.vtt` (WebVTT), `.srt` (SubRip), `.txt`, `.md`\n\n**Pro tip:** Use `sdd_auto_pipeline` to go from transcript to complete spec in one step:\n\n```\n\u003e Run the auto pipeline from this meeting transcript: /path/to/meeting.vtt\n```\n\n**Got multiple transcripts?** Use batch processing:\n\n```\n\u003e Batch import all transcripts from the meetings/ folder\n```\n\nThe AI calls `sdd_batch_transcripts` → processes every `.vtt`, `.srt`, `.txt`, and `.md` file in the folder.\n\n### 3. Existing Documents (PDF / DOCX / PPTX)\n\nImport requirements documents, RFPs, architecture decks, or any existing documentation.\n\n```\n\u003e Import this requirements document and create a specification:\n  /path/to/requirements.pdf\n```\n\nThe AI calls `sdd_import_document` → converts to Markdown, extracts sections, and feeds into the spec pipeline.\n\n**Supported formats:** `.pdf`, `.docx`, `.pptx`, `.txt`, `.md`\n\n**Batch import from a folder:**\n\n```\n\u003e Import all documents from the docs/ folder into specs\n```\n\nThe AI calls `sdd_batch_import` → processes every supported file in the directory.\n\n\u003e **Tip:** For best results with PDF/DOCX, install the optional `mammoth` and `pdfjs-dist` packages for enhanced formatting, table extraction, and image handling.\n\n### 4. Figma Design (design-to-spec)\n\nConvert Figma designs into requirements specifications. Works with the Figma MCP server.\n\n```\n\u003e Convert this Figma design into a specification:\n  https://figma.com/design/abc123/my-app\n```\n\nThe AI calls `sdd_figma_to_spec` → extracts components, layouts, and interactions, then routes to the Figma MCP server for design context.\n\n**Best for:** Design-first workflows, UI-driven projects.\n\n### 5. Codebase Scan (brownfield / modernization)\n\nScan an existing codebase to detect tech stack, frameworks, structure, and patterns before writing specs.\n\n```\n\u003e Scan this codebase and tell me what we're working with\n```\n\nThe AI calls `sdd_scan_codebase` → detects:\n\n| Detected | Examples |\n|----------|---------|\n| Language | TypeScript, Python, Go, Rust, Java |\n| Framework | Next.js, Express, React, Django, FastAPI, Gin |\n| Package Manager | npm, pip, poetry, cargo, maven, gradle |\n| Runtime | Node.js, Python, Go, JVM |\n| Directory Tree | Full project structure with file counts |\n\n**Best for:** Understanding an existing project before adding features or modernizing.\n\n### 6. Raw Text (paste anything)\n\nNo file? Just paste the content directly. Every import tool accepts a `raw_text` parameter as an alternative to a file path.\n\n```\n\u003e Here's the raw requirements from the client email:\n\n  The system needs to handle 10,000 concurrent users...\n  Authentication must support SSO via Azure AD...\n  All data must be encrypted at rest and in transit...\n\n  Import this and create a specification.\n```\n\n\n## Three Project Types, One Pipeline\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/project-workflows.svg\" alt=\"Greenfield, Brownfield, and Modernization Workflows\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nSpecky adapts to any project type. The pipeline is the same; the **starting point** is what changes.\n\n\n## Greenfield Project: Start from Scratch\n\n**Scenario:** You're building a new application with no existing code.\n\n### Step 1: Initialize and discover\n\n```\n\u003e I'm building a task management API. Initialize a Specky project and help\n  me define the scope.\n```\n\nThe AI calls `sdd_init` → creates `.specs/001-task-management/CONSTITUTION.md`\nThen calls `sdd_discover` → asks you **7 structured questions**:\n\n1. **Scope**: What problem does this solve? What are the boundaries of v1?\n2. **Users**: Who are the primary users? What are their skill levels?\n3. **Constraints**: Language, framework, hosting, budget, timeline?\n4. **Integrations**: What external systems, APIs, or services?\n5. **Performance**: Expected load, concurrent users, response times?\n6. **Security**: Authentication, authorization, compliance requirements?\n7. **Deployment**: CI/CD, monitoring, rollback strategy?\n\nAnswer each question. Your answers feed directly into the specification.\n\n### Step 2: Write the specification\n\n```\n\u003e Write the specification based on my discovery answers\n```\n\nThe AI calls `sdd_write_spec` → creates `SPECIFICATION.md` with EARS requirements:\n\n```markdown\n## Requirements\n\nREQ-001 [Ubiquitous]: The system shall provide a REST API for task CRUD operations.\n\nREQ-002 [Event-driven]: When a user creates a task, the system shall assign\na unique identifier and return it in the response.\n\nREQ-003 [State-driven]: While a task is in \"in-progress\" state, the system\nshall prevent deletion without explicit force confirmation.\n\nREQ-004 [Unwanted]: If the API receives a malformed request body, then the\nsystem shall return a 400 status with a descriptive error message.\n```\n\n**The AI pauses here.** Review `.specs/001-task-management/SPECIFICATION.md` and reply **LGTM** when satisfied.\n\n### Step 3: Design the architecture\n\n```\n\u003e LGTM.proceed to design\n```\n\nThe AI calls `sdd_write_design` → creates `DESIGN.md` with:\n- System architecture diagram (Mermaid)\n- Data model / ER diagram\n- API contracts with endpoints, request/response schemas\n- Sequence diagrams for key flows\n- Technology decisions with rationale\n\nReview and reply **LGTM**.\n\n### Step 4: Break into tasks\n\n```\n\u003e LGTM.create the task breakdown\n```\n\nThe AI calls `sdd_write_tasks` → creates `TASKS.md` with implementation tasks mapped to acceptance criteria, dependencies, and estimated complexity.\n\n### Step 5: Quality gates\n\n```\n\u003e Run analysis, compliance check for SOC2, and generate all diagrams\n```\n\nThe AI calls:\n- `sdd_run_analysis` → completeness audit, orphaned criteria detection\n- `sdd_compliance_check` → SOC2 controls validation\n- `sdd_generate_all_diagrams` → architecture, sequence, ER, flow, dependency, traceability diagrams\n\n### Step 6: Generate infrastructure and tests\n\n```\n\u003e Generate Terraform for Azure, a Dockerfile, and test stubs for vitest\n```\n\nThe AI calls:\n- `sdd_generate_iac` → Terraform configuration\n- `sdd_generate_dockerfile` → Dockerfile + docker-compose\n- `sdd_generate_tests` → Test stubs with acceptance criteria mapped to test cases\n\n### Step 7: Export and ship\n\n```\n\u003e Export tasks to GitHub Issues and create a PR\n```\n\nThe AI calls `sdd_export_work_items` + `sdd_create_pr` → generates work item payloads and PR body with full spec traceability.\n\n\u003e **Next:** **Next:** Learn about [EARS notation](#ears-notation) to understand the requirement patterns, or see [All 53 Tools](#all-53-tools) for a complete reference.\n\n\n## Brownfield Project: Add Features to Existing Code\n\n**Scenario:** You have a running application and need to add a new feature with proper specifications.\n\n### Step 1: Scan the codebase first\n\n```\n\u003e Scan this codebase so Specky understands what we're working with\n```\n\nThe AI calls `sdd_scan_codebase` → detects tech stack, framework, directory structure. This context informs all subsequent tools.\n\n```\nDetected: TypeScript + Next.js + npm + Node.js\nFiles: 247 across 32 directories\n```\n\n### Step 2: Initialize with codebase context\n\n```\n\u003e Initialize a feature for adding real-time notifications to this Next.js app.\n  Use the codebase scan results as context.\n```\n\nThe AI calls `sdd_init` → creates `.specs/001-real-time-notifications/CONSTITUTION.md`\nThen calls `sdd_discover` with the codebase summary → the 7 discovery questions now include context about your existing tech stack:\n\n\u003e *\"What technical constraints exist? **Note: This project already uses TypeScript, Next.js, npm, Node.js.** Consider compatibility with the existing stack.\"*\n\n### Step 3: Import existing documentation\n\nIf you have existing PRDs, architecture docs, or meeting notes:\n\n```\n\u003e Import the PRD for notifications: /docs/notifications-prd.pdf\n```\n\nThe AI calls `sdd_import_document` → converts to Markdown and adds to the spec directory. The content is used as input when writing the specification.\n\n### Step 4: Write spec with codebase awareness\n\n```\n\u003e Write the specification for real-time notifications. Consider the existing\n  Next.js architecture and any patterns already in the codebase.\n```\n\nThe specification references existing components, APIs, and patterns from the codebase scan.\n\n### Step 5: Check for drift\n\nAfter implementation, verify specs match the code:\n\n```\n\u003e Check if the implementation matches the specification\n```\n\nThe AI calls `sdd_check_sync` → generates a drift report flagging any divergence between spec and code.\n\n### Step 6: Cross-feature analysis\n\nIf you have multiple features specified:\n\n```\n\u003e Run cross-analysis across all features to find conflicts\n```\n\nThe AI calls `sdd_cross_analyze` → checks for contradictions, shared dependencies, and consistency issues across `.specs/001-*`, `.specs/002-*`, etc.\n\n\u003e **Next:** **Next:** See [compliance frameworks](#compliance-frameworks) for regulatory validation, or [MCP integration](#mcp-integration-architecture) for routing to external tools.\n\n\n## Modernization Project: Assess and Upgrade Legacy Systems\n\n**Scenario:** You have a legacy system that needs assessment, documentation, and incremental modernization.\n\n### Step 1: Scan and document the current state\n\n```\n\u003e Scan this legacy codebase and help me understand what we have\n```\n\nThe AI calls `sdd_scan_codebase` → maps the technology stack, directory tree, and file counts.\n\n### Step 2: Import all existing documentation\n\nGather everything you have.architecture documents, runbooks, meeting notes about the system:\n\n```\n\u003e Batch import all documents from /docs/legacy-system/ into specs\n```\n\nThe AI calls `sdd_batch_import` → processes PDFs, DOCX, PPTX, and text files. Each becomes a Markdown reference in the spec directory.\n\n### Step 3: Import stakeholder meetings\n\nIf you have recorded meetings with stakeholders discussing the modernization:\n\n```\n\u003e Batch import all meeting transcripts from /recordings/\n```\n\nThe AI calls `sdd_batch_transcripts` → extracts decisions, requirements, constraints, and open questions from every transcript.\n\n### Step 4: Create the modernization specification\n\n```\n\u003e Write a specification for modernizing the authentication module.\n  Consider the legacy constraints from the imported documents and\n  meeting transcripts.\n```\n\nThe specification accounts for:\n- Current system behavior (from codebase scan)\n- Existing documentation (from imported docs)\n- Stakeholder decisions (from meeting transcripts)\n- Migration constraints and backward compatibility\n\n### Step 5: Compliance assessment\n\nLegacy systems often need compliance validation during modernization:\n\n```\n\u003e Run compliance checks against HIPAA and SOC2 for the modernized auth module\n```\n\nThe AI calls `sdd_compliance_check` → validates the specification against regulatory controls and flags gaps.\n\n### Step 6: Generate migration artifacts\n\n```\n\u003e Generate the implementation plan, Terraform for the new infrastructure,\n  and a runbook for the migration\n```\n\nThe AI calls:\n- `sdd_implement` → phased implementation plan with checkpoints\n- `sdd_generate_iac` → infrastructure configuration for the target environment\n- `sdd_generate_runbook` → operational runbook with rollback procedures\n\n### Step 7: Generate onboarding for the team\n\n```\n\u003e Generate an onboarding guide for developers joining the modernization project\n```\n\nThe AI calls `sdd_generate_onboarding` → creates a guide covering architecture decisions, codebase navigation, development workflow, and testing strategy.\n\n\u003e **Next:** **Next:** See [compliance frameworks](#compliance-frameworks) for regulatory validation during modernization, or [project configuration](#project-configuration) to customize Specky for your team.\n\n\n## Pipeline and LGTM Gates\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/pipeline-lgtm-gates.svg\" alt=\"Pipeline with LGTM Quality Gates\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nEvery 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.\n\n**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.\n\n**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.\n\n**Advancing phases:** If you need to manually advance:\n\n```\n\u003e Advance to the next phase\n```\n\nThe AI calls `sdd_advance_phase` → moves the pipeline forward if all prerequisites are met.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/pipeline-10-phases.svg\" alt=\"Specky 10-Phase Pipeline\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n| Phase | What Happens | Required Output |\n|-------|-------------|----------------|\n| **Init** | Create project structure, constitution, scan codebase | CONSTITUTION.md |\n| **Discover** | Interactive discovery: 7 structured questions about scope, users, constraints | Discovery answers |\n| **Specify** | Write [EARS requirements](#ears-notation) with acceptance criteria | SPECIFICATION.md |\n| **Clarify** | Resolve ambiguities, generate decision tree | Updated SPECIFICATION.md |\n| **Design** | Architecture, data model, API contracts, research unknowns | DESIGN.md, RESEARCH.md |\n| **Tasks** | Implementation breakdown by user story, dependency graph | TASKS.md |\n| **Analyze** | Cross-artifact analysis, quality checklist, [compliance check](#compliance-frameworks) | ANALYSIS.md, CHECKLIST.md, CROSS_ANALYSIS.md |\n| **Implement** | Ordered execution with checkpoints per user story | Implementation progress |\n| **Verify** | Drift detection, phantom task detection | VERIFICATION.md |\n| **Release** | PR generation, work item export, documentation | Complete package |\n\nAll artifacts are saved in [`.specs/NNN-feature/`](#where-specifications-live). See [Input Methods](#input-methods-6-ways-to-start) for how to feed data into the pipeline.\n\n\n## All 53 Tools\n\n### Input and Conversion (5)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_import_document` | Convert PDF, DOCX, PPTX, TXT, MD to Markdown |\n| `sdd_import_transcript` | Parse meeting transcripts (Teams, Zoom, Google Meet) |\n| `sdd_auto_pipeline` | Any input to complete spec pipeline (all documents) |\n| `sdd_batch_import` | Process folder of mixed documents |\n| `sdd_figma_to_spec` | Figma design to requirements specification |\n\n### Pipeline Core (8)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_init` | Initialize project with constitution and scope diagram |\n| `sdd_discover` | Interactive discovery with stakeholder mapping |\n| `sdd_write_spec` | Write EARS requirements with flow diagrams |\n| `sdd_clarify` | Resolve ambiguities with decision tree |\n| `sdd_write_design` | 12-section system design (C4 model) with sequence diagrams, ERD, API flow |\n| `sdd_write_tasks` | Task breakdown with dependency graph |\n| `sdd_run_analysis` | Quality gate analysis with coverage heatmap |\n| `sdd_advance_phase` | Move to next pipeline phase |\n\n### Quality and Validation (5)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_checklist` | Mandatory quality checklist (security, accessibility, etc.) |\n| `sdd_verify_tasks` | Detect phantom completions |\n| `sdd_compliance_check` | HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 validation |\n| `sdd_cross_analyze` | Spec-design-tasks alignment with consistency score |\n| `sdd_validate_ears` | Batch EARS requirement validation |\n\n### Diagrams and Visualization (4) -- 17 Diagram Types\n\n| Tool | Description |\n|------|-------------|\n| `sdd_generate_diagram` | Single Mermaid diagram (17 software engineering diagram types) |\n| `sdd_generate_all_diagrams` | All diagrams for a feature at once |\n| `sdd_generate_user_stories` | User stories with flow diagrams |\n| `sdd_figma_diagram` | FigJam-ready diagram via Figma MCP |\n\n### Infrastructure as Code (3)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_generate_iac` | Terraform/Bicep from architecture design |\n| `sdd_validate_iac` | Validation via Terraform MCP + Azure MCP |\n| `sdd_generate_dockerfile` | Dockerfile + docker-compose from tech stack |\n\n### Dev Environment (3)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_setup_local_env` | Docker-based local dev environment |\n| `sdd_setup_codespaces` | GitHub Codespaces configuration |\n| `sdd_generate_devcontainer` | .devcontainer/devcontainer.json generation |\n\n### Integration and Export (5)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_create_branch` | Git branch naming convention |\n| `sdd_export_work_items` | Tasks to GitHub Issues, Azure Boards, or Jira |\n| `sdd_create_pr` | PR payload with spec summary |\n| `sdd_implement` | Ordered implementation plan with checkpoints |\n| `sdd_research` | Resolve unknowns in RESEARCH.md |\n\n### Documentation (4)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_generate_docs` | Complete auto-documentation |\n| `sdd_generate_api_docs` | API documentation from design |\n| `sdd_generate_runbook` | Operational runbook |\n| `sdd_generate_onboarding` | Developer onboarding guide |\n\n### Utility (5)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_get_status` | Pipeline status with guided next action |\n| `sdd_get_template` | Get any template |\n| `sdd_scan_codebase` | Detect tech stack and structure |\n| `sdd_metrics` | Project metrics dashboard |\n| `sdd_amend` | Amend project constitution |\n\n### Testing (3)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_generate_tests` | Generate test stubs from acceptance criteria (vitest/jest/playwright/pytest/junit/xunit) |\n| `sdd_verify_tests` | Verify test results against requirements, report traceability coverage |\n| `sdd_generate_pbt` | Generate property-based tests using fast-check (TypeScript) or Hypothesis (Python). Extracts invariants, round-trips, idempotence, state transitions, and negative properties from EARS requirements |\n\n### Turnkey Specification (1)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_turnkey_spec` | Generate a complete EARS specification from a natural language description. Auto-extracts requirements, classifies all 5 EARS patterns, generates acceptance criteria, infers non-functional requirements, and identifies clarification questions |\n\n### Checkpointing (3)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_checkpoint` | Create a named snapshot of all spec artifacts and pipeline state |\n| `sdd_restore` | Restore spec artifacts from a previous checkpoint (auto-creates backup before restoring) |\n| `sdd_list_checkpoints` | List all available checkpoints for a feature with labels, dates, and phases |\n\n### Ecosystem (1)\n\n| Tool | Description |\n|------|-------------|\n| `sdd_check_ecosystem` | Report recommended MCP servers with install commands |\n\n\n## The Spec-Driven Development Platform\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/specky-speckit-integration.svg\" alt=\"How Spec-Kit and Specky Work Together in the GitHub + Microsoft Ecosystem\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n### How Spec-Kit and Specky Complement Each Other\n\n**[Spec-Kit](https://github.com/paulasilvatech/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.\n\n**Specky** is the MCP engine that reimplements that methodology as 53 enforceable tools with programmatic validation. It enforces **how** to do it.\n\n| | Spec-Kit (Methodology) | Specky (Engine) |\n|--|------------------------|-----------------|\n| **What it is** | Prompt templates + agent definitions | MCP server with 53 tools |\n| **How it works** | AI reads `.md` templates and follows instructions | AI calls tools that validate, enforce, and generate |\n| **Validation** | AI tries to follow the prompts | State machine, EARS regex, Zod schemas |\n| **Install** | Copy `.github/agents/` and `.claude/commands/` | `npx specky-sdd` (includes methodology built-in) |\n| **Works standalone** | Yes, in any AI IDE | Yes, includes all Spec-Kit patterns |\n| **Best for** | Learning SDD, lightweight adoption | Production enforcement, enterprise, compliance |\n\n### Together: The Complete SDD Layer\n\nWhen 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.\n\nTogether 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.\n\n```json\n{\n  \"servers\": {\n    \"specky\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specky-sdd\"]\n    }\n  }\n}\n```\n\n\n## Project Configuration\n\nCreate `.specky/config.yml` in your project root to customize Specky:\n\n```yaml\n# .specky/config.yml\ntemplates_path: ./my-templates       # Override built-in templates\ndefault_framework: vitest            # Default test framework\ncompliance_frameworks: [hipaa, soc2] # Frameworks to check\naudit_enabled: true                  # Enable audit trail\n```\n\nWhen `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.\n\n\n## MCP Integration Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/architecture-mcp-ecosystem.svg\" alt=\"Specky MCP Ecosystem Architecture\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nSpecky outputs structured JSON with routing instructions. Your AI client calls the appropriate external MCP server:\n\n```\nSpecky --\u003e sdd_export_work_items(platform: \"azure_boards\") --\u003e JSON payload\n  --\u003e AI Client --\u003e Azure DevOps MCP --\u003e create_work_item()\n\nSpecky --\u003e sdd_validate_iac(provider: \"terraform\") --\u003e validation payload\n  --\u003e AI Client --\u003e Terraform MCP --\u003e plan/validate\n\nSpecky --\u003e sdd_figma_to_spec(file_key: \"abc123\") --\u003e Figma request\n  --\u003e AI Client --\u003e Figma MCP --\u003e get_design_context()\n```\n\n### Supported External MCP Servers\n\n| MCP Server | Integration |\n|-----------|-------------|\n| **GitHub MCP** | Issues, PRs, Codespaces |\n| **Azure DevOps MCP** | Work Items, Boards |\n| **Jira MCP** | Issues, Projects |\n| **Terraform MCP** | Plan, Validate, Apply |\n| **Azure MCP** | Template validation |\n| **Figma MCP** | Design context, FigJam diagrams |\n| **Docker MCP** | Local dev environments |\n\n\n## EARS Notation\n\nEvery requirement in Specky follows EARS (Easy Approach to Requirements Syntax):\n\n| Pattern | Format | Example |\n|---------|--------|---------|\n| Ubiquitous | The system shall... | The system shall encrypt all data at rest |\n| Event-driven | When [event], the system shall... | When a user submits login, the system shall validate credentials |\n| State-driven | While [state], the system shall... | While offline, the system shall queue requests |\n| Optional | Where [condition], the system shall... | Where 2FA is enabled, the system shall require OTP |\n| Unwanted | If [condition], then the system shall... | If session expires, the system shall redirect to login |\n| Complex | While [state], when [event]... | While in maintenance, when request arrives, queue it |\n\nThe EARS validator programmatically checks every requirement against these 6 patterns. Vague terms like \"fast\", \"good\", \"easy\" are flagged automatically.\n\n\n## Compliance Frameworks\n\nBuilt-in compliance checking against:\n\n- **HIPAA**: Access control, audit, encryption, PHI protection\n- **SOC 2**: Logical access, monitoring, change management, incident response\n- **GDPR**: Lawful processing, right to erasure, data portability, breach notification\n- **PCI-DSS**: Firewall, stored data protection, encryption, user identification\n- **ISO 27001**: Security policies, access control, cryptography, incident management\n\n\n## Educative Outputs\n\nEvery tool response includes structured guidance:\n\n```json\n{\n  \"explanation\": \"What was done and why\",\n  \"next_steps\": \"Guided next action with command suggestion\",\n  \"learning_note\": \"Educational context about the concept\",\n  \"diagram\": \"Mermaid diagram relevant to the output\"\n}\n```\n\n\n## Complete Pipeline Flow\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/end-to-end-flow.svg\" alt=\"Specky Complete Pipeline Development Flow\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\nFrom any [input](#input-methods-6-ways-to-start) to production -- fully automated, [MCP-orchestrated](#mcp-integration-architecture), with artifacts and diagrams generated at every step. All artifacts are saved in [`.specs/NNN-feature/`](#where-specifications-live).\n\n\n## Enterprise Ready\n\nSpecky is built with enterprise adoption in mind.\n\n### Security Posture\n\n- **2 runtime dependencies** — minimal attack surface (`@modelcontextprotocol/sdk`, `zod`)\n- **Zero outbound network requests** — all data stays local\n- **No `eval()` or dynamic code execution** — template rendering is string replacement only\n- **Path traversal prevention**: FileManager sanitizes all paths, blocks `..` sequences\n- **Zod `.strict()` validation** — every tool input is schema-validated; unknown fields rejected\n- **security-scan hook** blocks commits containing hardcoded secrets (exit code 2)\n- See [SECURITY.md](SECURITY.md) for full OWASP Top 10 coverage\n- See [docs/SYSTEM-DESIGN.md](docs/SYSTEM-DESIGN.md) for complete security architecture\n\n### Security Best Practices\n\nWhen using Specky, follow these practices to protect your data:\n\n| Practice | Why | How |\n|----------|-----|-----|\n| **Use stdio mode for local development** | No network exposure | `npx specky-sdd` (default) |\n| **Never expose HTTP mode to public networks** | HTTP is unencrypted, no auth | If using `--http`, bind to localhost only. Use a reverse proxy (nginx, Caddy) with TLS and authentication for remote access |\n| **Protect the `.specs/` directory** | Contains your specification artifacts (architecture, API contracts, business logic) | Add `.specs/` to `.gitignore` if specs contain sensitive IP, or use a private repo |\n| **Protect checkpoints** | `.specs/{feature}/.checkpoints/` stores full artifact snapshots | Same as above — treat checkpoints like source code |\n| **Review auto-generated specs before committing** | Turnkey and auto-pipeline generate from natural language — may capture sensitive details | Review SPECIFICATION.md and DESIGN.md before `git add` |\n| **Keep the security-scan hook enabled** | Detects API keys, passwords, tokens in staged files | Comes pre-configured; don't disable `.claude/hooks/security-scan.sh` |\n| **Use environment variables for secrets** | Specky never stores credentials, but your specs might reference them | Write `$DATABASE_URL` in specs, never the actual connection string |\n| **Run `npm audit` regularly** | Catches dependency vulnerabilities | `npm audit` — CI runs this automatically on every PR |\n\n### Data Sensitivity Guide\n\n| What Specky creates | Contains | Sensitivity | Recommendation |\n|---------------------|----------|-------------|----------------|\n| `CONSTITUTION.md` | Project scope, principles | Low | Safe to commit |\n| `SPECIFICATION.md` | Requirements, acceptance criteria | Medium | Review before committing — may contain business logic details |\n| `DESIGN.md` | Architecture, API contracts, security model | **High** | May contain infrastructure details, auth flows, data schemas |\n| `TASKS.md` | Implementation plan, effort estimates | Low | Safe to commit |\n| `ANALYSIS.md` | Quality gate results, coverage | Low | Safe to commit |\n| `.sdd-state.json` | Pipeline phase timestamps | Low | Safe to commit |\n| `.checkpoints/*.json` | **Full copies of all artifacts** | **High** | Protect like source code — contains everything above |\n| `docs/journey-*.md` | Complete SDD audit trail with timestamps | Medium | Review before sharing externally |\n| Routing payloads | Branch names, PR bodies, work items | **Transient** (memory only) | Never persisted by Specky; forwarded to external MCPs by the AI client |\n\n\u003e **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.\n\n### Compliance Validation\n\nBuilt-in compliance checking validates your specifications against industry frameworks:\n\n| Framework | Controls | Use Case |\n|-----------|----------|----------|\n| HIPAA | 6 controls | Healthcare applications |\n| SOC 2 | 6 controls | SaaS and cloud services |\n| GDPR | 6 controls | EU data processing |\n| PCI-DSS | 6 controls | Payment card handling |\n| ISO 27001 | 6 controls | Enterprise security management |\n\n### Audit Trail\n\nEvery 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.\n\n### Quality Gates\n\n- **Phase Validation** — every tool validates it's being called in the correct pipeline phase\n- **Gate Enforcement** — `advancePhase()` blocks if gate decision is BLOCK or CHANGES_NEEDED\n- **EARS Validator** — programmatic requirement quality enforcement\n- **Cross-Artifact Analysis** — automatic alignment checking between spec, design, and tasks\n- **Phase Enforcement** — state machine blocks phase-skipping; required files gate advancement\n- **321 unit tests** — CI enforces thresholds on every push\n\n\n## Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/paulasilvatech/specky.git\ncd specky\nnpm install\n\n# Build\nnpm run build\n\n# Run tests (292 tests coverage)\nnpm test\n\n# Run tests with coverage report\nnpm run test:coverage\n\n# Development mode (auto-reload on file changes)\nnpm run dev\n\n# Verify MCP handshake (quick smoke test)\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | node dist/index.js 2\u003e/dev/null\n\n# Build and run with Docker locally\ndocker build -t specky-sdd:dev .\ndocker run -p 3200:3200 -v $(pwd):/workspace specky-sdd:dev\ncurl http://localhost:3200/health\n```\n\n\n## Roadmap\n\n### v3.0 (current)\n\n| Capability | Status |\n|------------|--------|\n| 53 MCP tools across 10 enforced pipeline phases | Stable |\n| Phase validation on every tool with gate enforcement | Stable |\n| 17 software engineering diagram types (C4, sequence, ER, DFD, deployment, network) | Stable |\n| 12-section system design template (C4 model, security, infrastructure) | Stable |\n| Enriched interactive responses on all tools (progress, handoff, education) | Stable |\n| Parallel documentation generation (5 types via Promise.all) | Stable |\n| Turnkey spec from natural language (`sdd_turnkey_spec`) | Stable |\n| Property-based testing with fast-check and Hypothesis (`sdd_generate_pbt`) | Stable |\n| Checkpoint/restore for spec artifacts | Stable |\n| 7 automation hooks (security-scan blocks on secrets) | Stable |\n| 12 Claude Code commands + 5 Copilot agents | Stable |\n| 6 compliance frameworks (HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001) | Stable |\n| 6 input types (transcript, PDF, DOCX, Figma, codebase, raw text) | Stable |\n| Test generation for 6 frameworks (vitest, jest, playwright, pytest, junit, xunit) | Stable |\n| MCP-to-MCP routing (GitHub, Azure DevOps, Jira, Terraform, Figma, Docker) | Stable |\n| 321 unit tests | Stable |\n\n### v3.1+ (planned)\n\n| Feature | Description |\n|---------|-------------|\n| HTTP authentication | Token-based auth for the HTTP transport |\n| Observability | OpenTelemetry metrics and structured logging |\n| Internationalization | Spec templates in PT-BR, ES, FR, DE, JA |\n| Automated shrinking | fast-check/Hypothesis shrinking feedback into spec refinement |\n| RBAC | Role-based access control for phase advancement |\n| Persistent audit log | Centralized audit trail beyond `.sdd-state.json` |\n| Multi-tenant | Isolated workspaces for multiple teams |\n| Analytics dashboard | Specification quality metrics over time |\n\nHave a feature request? [Open an issue](https://github.com/paulasilvatech/specky/issues).\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details and how to add tools, templates, or services.\n\n\n## Links\n\n- [CHANGELOG.md](CHANGELOG.md): Version history and release notes\n- [SECURITY.md](SECURITY.md): Vulnerability disclosure policy and OWASP Top 10 coverage\n- [CONTRIBUTING.md](CONTRIBUTING.md): How to add tools, templates, or services\n- [Spec-Kit](https://github.com/paulasilvatech/spec-kit): The SDD methodology foundation\n- [npm package](https://www.npmjs.com/package/specky-sdd): `specky-sdd` on npm\n\n\n## License\n\nMIT. Created by [Paula Silva](https://github.com/paulasilvatech) | Americas Software GBB, Microsoft\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulasilvatech%2Fspecky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulasilvatech%2Fspecky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulasilvatech%2Fspecky/lists"}