specky-sdd 2.0.0 → 2.2.1

package/README.md

@@ -1,10 +1,12 @@
 <div align="center">
   <h1>Specky</h1>
   <h3>The Complete Spec-Driven Development Platform</h3>
-  <p><strong>42 MCP tools. 10-phase pipeline. Works in any IDE.</strong></p>
+  <p><strong>47 MCP tools. 10-phase pipeline. Works in any IDE.</strong></p>
 
   <p>
     <a href="https://www.npmjs.com/package/specky-sdd"><img src="https://img.shields.io/npm/v/specky-sdd" alt="npm"/></a>
+    <a href="https://github.com/paulasilvatech/specky/actions/workflows/ci.yml"><img src="https://github.com/paulasilvatech/specky/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+    <a href="https://securityscorecards.dev/viewer/?uri=github.com/paulasilvatech/specky"><img src="https://api.securityscorecards.dev/projects/github.com/paulasilvatech/specky/badge" alt="OpenSSF Scorecard"/></a>
     <a href="https://github.com/paulasilvatech/specky"><img src="https://img.shields.io/github/stars/paulasilvatech/specky?style=social" alt="Stars"/></a>
     <a href="https://github.com/paulasilvatech/specky/blob/main/LICENSE"><img src="https://img.shields.io/github/license/paulasilvatech/specky" alt="License"/></a>
   </p>
@@ -12,31 +14,74 @@
 
 ---
 
+## Table of Contents
+
+- [What is Specky?](#what-is-specky) — Overview and ecosystem
+- [Why Specifications Matter](#why-specifications-matter-in-the-ai-era) — Vibe coding vs deterministic development, what is Markdown/MCP/EARS/Agents
+- [GETTING-STARTED.md](GETTING-STARTED.md) — Complete educational guide (1400 lines, assumes no prior knowledge)
+- [Quick Start](#quick-start) — Install via npm or Docker, connect to your IDE, and run your first command
+- [Where Specifications Live](#where-specifications-live) — File structure and naming conventions
+- [Input Methods](#input-methods--6-ways-to-start) — 6 ways to feed Specky (prompts, transcripts, documents, Figma, codebase scan, raw text)
+- [Three Project Types](#three-project-types--one-pipeline) — Greenfield, brownfield, and modernization workflows
+  - [Greenfield](#greenfield-project--start-from-scratch) — New project from scratch
+  - [Brownfield](#brownfield-project--add-features-to-existing-code) — Add features to existing code
+  - [Modernization](#modernization-project--assess-and-upgrade-legacy-systems) — Assess and upgrade legacy systems
+- [Pipeline and LGTM Gates](#pipeline-and-lgtm-gates) — 10-phase pipeline with human review gates
+- [All 47 Tools](#all-47-tools) — Complete tool reference by category
+- [The SDD Platform](#the-spec-driven-development-platform) — Built on Spec-Kit, everything included
+- [Configuration](#project-configuration) — `.specky/config.yml` options
+- [MCP Integration](#mcp-integration-architecture) — MCP-to-MCP routing to GitHub, Azure DevOps, Jira, Terraform, Figma
+- [EARS Notation](#ears-notation) — The 6 requirement patterns
+- [Compliance](#compliance-frameworks) — HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001
+- [Enterprise Ready](#enterprise-ready) — Security posture, audit trail, quality gates
+- [Development](#development) — Build from source, run tests, contribute
+
+---
+
 ## What is Specky?
 
-Specky is an open-source MCP (Model Context Protocol) server that transforms how software is built. It provides a complete, deterministic pipeline from any input -- meeting transcripts, documents, designs, or user prompts -- through specifications, architecture, infrastructure as code, implementation, and deployment.
+Specky is the **complete Spec-Driven Development (SDD) platform**, built on the foundation of the [Spec-Kit](https://github.com/paulasilvatech/spec-kit) methodology. It's an open-source MCP (Model Context Protocol) server that 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.
 
-Unlike template-based tools, Specky enforces every step programmatically: a state machine blocks phase-skipping, an EARS validator ensures testable requirements, cross-artifact analysis catches drift, and compliance engines validate against frameworks like HIPAA and SOC2.
+Specky **already includes everything from Spec-Kit** -- the EARS notation, the SDD templates, the pipeline phases, and the quality patterns -- and adds **programmatic enforcement** on top: a state machine that blocks phase-skipping, an EARS validator that ensures testable requirements, cross-artifact analysis that catches drift, and compliance engines that validate against frameworks like HIPAA and SOC2.
 
-**Specky works inside the tools you already use** -- VS Code with GitHub Copilot, Claude Code, Cursor, Windsurf, or any AI agent that supports MCP.
+**Install Specky and you're ready to go.** No separate installation of Spec-Kit required. It works inside any AI IDE that supports MCP — via `.github/agents/` for GitHub Copilot or `.claude/commands/` for Claude Code, and natively in Cursor, Windsurf, or any MCP-compatible client.
 
 ---
 
-## Why Specky?
+## Why Specifications Matter in the AI Era
+
+<p align="center">
+  <img src="media/why-specifications-matter.svg" alt="Why Specifications Matter — From Vibe Coding to Deterministic Development" width="100%"/>
+</p>
+
+### 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.
 
-### The Problem
+**Key concepts you should know:**
 
-AI coding assistants are fast but chaotic. They skip requirements, ignore architecture, and produce code that drifts from the original intent. Template-based approaches help but rely on the AI to follow instructions -- with no programmatic enforcement.
+- **Markdown** -- The universal language that both humans and AI read fluently. All spec artifacts are Markdown files that live in your repo, versioned with Git.
+- **MCP (Model Context Protocol)** -- An open standard by Anthropic that lets AI assistants call external tools. Think of it as USB for AI. Specky is an MCP server; any AI IDE can connect to it.
+- **EARS Notation** -- A method for writing requirements that forces precision. Six patterns (When/While/Where/If/The system shall) eliminate vague statements like "the system should be fast."
+- **Agents and Skills** -- Specialized AI roles (Spec Engineer, Design Architect, Task Planner) that invoke Specky tools with domain expertise. Defined in `.github/agents/` and `.claude/commands/`.
 
-### The Solution
+### 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 (Ubiquitous, Event-driven, State-driven, Optional, Unwanted, Complex). No vague statements pass.
+- **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](GETTING-STARTED.md).
+
 ### Differentiators
 
 <p align="center">
@@ -63,7 +108,7 @@ Specky adds a **deterministic engine** between your intent and your code:
 | Phantom task detection | Extension | No | No | **Yes** |
 | Complete auto-documentation | No | No | No | **Yes** |
 | Educative outputs | No | No | No | **Yes** |
-| 42 MCP tools | N/A | N/A | N/A | **Yes** |
+| 47 MCP tools | N/A | N/A | N/A | **Yes** |
 | Works in ANY IDE via MCP | Templates | IDE-locked | IDE-locked | **Yes** |
 
 </details>
@@ -72,19 +117,82 @@ Specky adds a **deterministic engine** between your intent and your code:
 
 ## Quick Start
 
-### Install
+### Prerequisites
+
+- **Node.js 18+** — [Download here](https://nodejs.org/)
+- **An AI IDE or client** — VS Code with Copilot, Claude Code, Claude Desktop, Cursor, or Windsurf
+
+### Option 1: npm (Recommended)
+
+No installation needed — `npx` downloads and runs Specky on demand:
 
 ```bash
-# npm (recommended)
 npx specky-sdd
+```
+
+Or install globally for faster startup:
 
-# Or install globally
+```bash
 npm install -g specky-sdd
+specky-sdd
+```
+
+### Option 2: Docker
+
+Run Specky as an HTTP server in a container — no Node.js required on the host:
+
+```bash
+# Pull and run (mounts your project into /workspace)
+docker run -p 3200:3200 -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest
+```
+
+Or use Docker Compose for a persistent setup:
+
+```bash
+# Create a workspace directory and start
+mkdir -p workspace
+docker compose up -d
+
+# Check health
+curl http://localhost:3200/health
+# → {"status":"ok","version":"2.2.0"}
+
+# View logs
+docker compose logs -f specky
+
+# Stop
+docker compose down
+```
+
+<details>
+<summary>Build from source with Docker</summary>
+
+```bash
+git clone https://github.com/paulasilvatech/specky.git
+cd specky
+
+# Build the image locally
+docker build -t specky-sdd:local .
+
+# Run it
+docker run -p 3200:3200 -v $(pwd):/workspace specky-sdd:local
+
+# Or with docker compose
+docker compose up -d --build
 ```
 
-### Configure in VS Code (GitHub Copilot)
+</details>
+
+> **stdio vs HTTP:** When run via `npx`, Specky uses stdio (direct pipe to the AI client). When run in Docker, it uses HTTP mode on port 3200. Both modes expose the same 47 MCP tools.
+
+### Connect to Your AI IDE
+
+Once Specky is running, connect it to your preferred AI tool:
 
-Create `.vscode/mcp.json` in your project:
+<details>
+<summary><strong>VS Code with GitHub Copilot</strong></summary>
+
+Create `.vscode/mcp.json` in your project root:
 
 ```json
 {
@@ -100,9 +208,14 @@ Create `.vscode/mcp.json` in your project:
 }
 ```
 
-Open Copilot Chat -- Specky's 42 tools are now available.
+Open Copilot Chat — Specky's 47 tools are now available. Type `@specky` to scope your prompts.
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-### Configure in Claude Code
+One command:
 
 ```bash
 claude mcp add specky -- npx -y specky-sdd
@@ -124,9 +237,12 @@ Or add to your MCP settings manually:
 }
 ```
 
-### Configure in Claude Desktop
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
-Add to `claude_desktop_config.json`:
+Add to your `claude_desktop_config.json`:
 
 | OS | Config File Location |
 |----|---------------------|
@@ -148,7 +264,10 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-### Configure in Cursor
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
 
 Add to Cursor's MCP settings (Settings > MCP Servers):
 
@@ -161,38 +280,505 @@ Add to Cursor's MCP settings (Settings > MCP Servers):
 }
 ```
 
-### Docker
+</details>
+
+<details>
+<summary><strong>Docker (HTTP mode) — for any MCP client</strong></summary>
+
+If your AI client supports HTTP-based MCP servers, point it to:
+
+```
+http://localhost:3200/mcp
+```
+
+Start the container first:
 
 ```bash
-docker run -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest
+docker compose up -d
+```
+
+</details>
+
+### 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 [Greenfield](#greenfield-project--start-from-scratch), [Brownfield](#brownfield-project--add-features-to-existing-code), or [Modernization](#modernization-project--assess-and-upgrade-legacy-systems) guide depending on your project type.
+
+> **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.
+
+---
+
+## 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.
+
 ---
 
-## The 10-Phase Pipeline
+## Input Methods — 6 Ways to Start
 
 <p align="center">
-  <img src="media/pipeline-10-phases.svg" alt="Specky 10-Phase Pipeline" width="100%"/>
+  <img src="media/input-methods.svg" alt="Specky 6 Input Methods" width="100%"/>
+</p>
+
+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:
+
+| Detected | Examples |
+|----------|---------|
+| Language | TypeScript, Python, Go, Rust, Java |
+| Framework | Next.js, Express, React, Django, FastAPI, Gin |
+| Package Manager | npm, pip, poetry, cargo, maven, gradle |
+| Runtime | Node.js, Python, Go, JVM |
+| Directory Tree | Full project structure with file counts |
+
+**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
+
+<p align="center">
+  <img src="media/project-workflows.svg" alt="Greenfield, Brownfield, and Modernization Workflows" width="100%"/>
+</p>
+
+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:
+
+```markdown
+## 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:** Learn about [EARS notation](#ears-notation) to understand the requirement patterns, or see [all 47 tools](#all-47-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:** See [compliance frameworks](#compliance-frameworks) for regulatory validation, or [MCP integration](#mcp-integration-architecture) 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:** See [compliance frameworks](#compliance-frameworks) for regulatory validation during modernization, or [project configuration](#project-configuration) to customize Specky for your team.
+
+---
+
+## Pipeline and LGTM Gates
+
+<p align="center">
+  <img src="media/pipeline-lgtm-gates.svg" alt="Pipeline with LGTM Quality Gates" width="100%"/>
 </p>
 
-Each phase is **mandatory**. The state machine blocks advancement until prerequisites are met.
+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.
+
+<p align="center">
+  <img src="media/pipeline-10-phases.svg" alt="Specky 10-Phase Pipeline" width="100%"/>
+</p>
 
 | Phase | What Happens | Required Output |
 |-------|-------------|----------------|
 | **Init** | Create project structure, constitution, scan codebase | CONSTITUTION.md |
 | **Discover** | Interactive discovery: 7 structured questions about scope, users, constraints | Discovery answers |
-| **Specify** | Write EARS requirements with acceptance criteria | SPECIFICATION.md |
+| **Specify** | Write [EARS requirements](#ears-notation) with acceptance criteria | SPECIFICATION.md |
 | **Clarify** | Resolve ambiguities, generate decision tree | Updated SPECIFICATION.md |
 | **Design** | Architecture, data model, API contracts, research unknowns | DESIGN.md, RESEARCH.md |
 | **Tasks** | Implementation breakdown by user story, dependency graph | TASKS.md |
-| **Analyze** | Cross-artifact analysis, quality checklist, compliance check | ANALYSIS.md, CHECKLIST.md, CROSS_ANALYSIS.md |
+| **Analyze** | Cross-artifact analysis, quality checklist, [compliance check](#compliance-frameworks) | ANALYSIS.md, CHECKLIST.md, CROSS_ANALYSIS.md |
 | **Implement** | Ordered execution with checkpoints per user story | Implementation progress |
 | **Verify** | Drift detection, phantom task detection | VERIFICATION.md |
 | **Release** | PR generation, work item export, documentation | Complete package |
 
+All 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.
+
 ---
 
-## All 42 Tools
+## All 47 Tools
 
 ### Input and Conversion (5)
 
@@ -281,6 +867,77 @@ Each phase is **mandatory**. The state machine blocks advancement until prerequi
 | `sdd_metrics` | Project metrics dashboard |
 | `sdd_amend` | Amend project constitution |
 
+### Testing (2) — NEW in v2.2.0
+
+| Tool | Description |
+|------|-------------|
+| `sdd_generate_tests` | Generate test stubs from acceptance criteria (vitest/jest/playwright/pytest/junit/xunit) |
+| `sdd_verify_tests` | Verify test results against requirements — reports traceability coverage |
+
+---
+
+## The Spec-Driven Development Platform
+
+Specky is a **complete, self-contained SDD platform**. It includes everything from the [Spec-Kit](https://github.com/paulasilvatech/spec-kit) methodology — the EARS notation, the pipeline phases, the quality patterns, the templates — and adds programmatic enforcement on top.
+
+**You do not need to install Spec-Kit separately.** Specky already has it built in.
+
+### What Spec-Kit Provides (included in Specky)
+
+- EARS notation for testable requirements (6 patterns)
+- 10-phase pipeline structure (Init → Release)
+- 22 Markdown templates for all spec artifacts
+- Quality gate patterns and traceability model
+- Spec-Driven Development methodology and workflow
+
+### What Specky Adds on Top
+
+- **47 MCP tools** — programmatic enforcement, not just templates
+- **State machine** — blocks phase-skipping, enforces prerequisites
+- **EARS validator** — regex-based requirement validation, flags vague terms
+- **6 input types** — transcripts, documents, Figma, codebase scan, raw text, prompts
+- **Compliance engines** — HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001
+- **Test generation** — 6 frameworks (vitest, jest, playwright, pytest, junit, xunit)
+- **MCP-to-MCP routing** — structured payloads for GitHub, Azure DevOps, Jira, Terraform, Figma, Docker
+- **Cross-artifact analysis** — automatic alignment checking with consistency scoring
+- **Educative outputs** — every tool explains what it did and what to do next
+
+### When to Use Spec-Kit Directly
+
+[Spec-Kit](https://github.com/paulasilvatech/spec-kit) is still useful as a **standalone learning tool** if you want to:
+- Learn SDD concepts before using the full platform
+- Work in environments where MCP servers aren't available
+- Use the prompt templates with any AI tool that doesn't support MCP
+
+But for production use, **Specky is all you need**:
+
+```json
+{
+  "servers": {
+    "specky": {
+      "command": "npx",
+      "args": ["-y", "specky-sdd"]
+    }
+  }
+}
+```
+
+---
+
+## Project Configuration
+
+Create `.specky/config.yml` in your project root to customize Specky:
+
+```yaml
+# .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
@@ -366,26 +1023,45 @@ Every tool response includes structured guidance:
   <img src="media/end-to-end-flow.svg" alt="Specky End-to-End Development Flow" width="100%"/>
 </p>
 
-From any input to production — fully automated, MCP-orchestrated, with artifacts and diagrams generated at every step.
+From 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).
 
 ---
 
-## Project Structure
+## Enterprise Ready
 
-```
-.specs/
-  001-feature-name/
-    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 decisions
-    TASKS.md              -- Implementation breakdown
-    ANALYSIS.md           -- Quality gate report
-    CHECKLIST.md          -- Mandatory quality checklist
-    CROSS_ANALYSIS.md     -- Spec-design-tasks alignment
-    COMPLIANCE.md         -- Compliance framework report
-    VERIFICATION.md       -- Phantom detection results
-```
+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
+- See [SECURITY.md](SECURITY.md) for full OWASP Top 10 coverage
+
+### Compliance Validation
+
+Built-in compliance checking validates your specifications against industry frameworks:
+
+| Framework | Controls | Use Case |
+|-----------|----------|----------|
+| HIPAA | 6 controls | Healthcare applications |
+| SOC 2 | 6 controls | SaaS and cloud services |
+| GDPR | 5 controls | EU data processing |
+| PCI-DSS | 6 controls | Payment card handling |
+| ISO 27001 | 6 controls | Enterprise security management |
+
+### Audit Trail
+
+Every pipeline phase produces a traceable artifact in `.specs/NNN-feature/`. The complete specification-to-code journey is documented and reproducible.
+
+### Quality Gates
+
+- **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
+- **211 unit tests** with 89% code coverage; CI enforces thresholds on every push
 
 ---
 
@@ -400,11 +1076,22 @@ npm install
 # Build
 npm run build
 
-# Development mode (auto-reload)
+# Run tests (211 tests, 89% coverage)
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Development mode (auto-reload on file changes)
 npm run dev
 
-# Verify MCP handshake
+# 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
 ```
 
 ---
@@ -415,6 +1102,16 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details and how to add t
 
 ---
 
+## Links
+
+- [CHANGELOG.md](CHANGELOG.md) — Version history and release notes
+- [SECURITY.md](SECURITY.md) — Vulnerability disclosure policy and OWASP Top 10 coverage
+- [CONTRIBUTING.md](CONTRIBUTING.md) — How to add tools, templates, or services
+- [Spec-Kit](https://github.com/paulasilvatech/spec-kit) — The learning companion for Spec-Driven Development
+- [npm package](https://www.npmjs.com/package/specky-sdd) — `specky-sdd` on npm
+
+---
+
 ## License
 
 MIT -- Created by [Paula Silva](https://github.com/paulasilvatech) | Americas Software GBB, Microsoft