specky-sdd 3.2.1 → 3.2.2

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to Specky are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.2] - 2026-04-13
+
+### Documentation (npm republish)
+
+- **Plugin-first Quick Start**: README now leads with plugin installation (`copilot plugin install`), MCP-only as alternative
+- **`mcpServers` key**: All JSON config examples updated from `servers` to `mcpServers`
+- **Stale counts fixed**: Tool count (53/55/56 → 57), hook count (7 → 10), agent count (5 → 7), skill count (6) across README, SECURITY, CONTRIBUTING
+- **SDD Platform table**: Updated to 57 tools, plugin install command
+- **GETTING-STARTED.md**: Full English rewrite with plugin-first installation, use cases, model routing, hooks, FAQ
+- **CONTRIBUTING.md**: Added Plugin Structure section; version reference updated to v3.2.x
+- **No runtime changes** — MCP server code is identical to v3.2.1
+
+## [3.2.1] - 2026-04-13
+
+### Plugin Marketplace
+
+- **`marketplace.json`**: Added `.github/plugin/marketplace.json` — repo is now a valid GitHub Copilot plugin marketplace
+- **`plugin.json`**: Added `plugins/specky-sdd/.github/plugin/plugin.json` in Claude Code spec format (7 agents, 19 commands, 6 skills)
+- **`.mcp.json`**: Plugin ships its own MCP config with `mcpServers` key and `specky-sdd@latest`
+- **`.claude-plugin/`**: Added symlink for Claude Code marketplace compatibility
+- **Plugin README**: Full plugin documentation at `plugins/specky-sdd/README.md` with skills, agents, commands, MCP server, and installation instructions
+- **Plugin install**: Users can now install via `copilot plugin marketplace add paulasilvatech/specky && copilot plugin install specky-sdd@specky`
+- **Flat structure**: Restructured from versioned `specky-sdd-vscode-v1.2.1/.github/plugin/specky/` to flat `plugins/specky-sdd/`
+- **MCP key fix**: All JSON configs now use `mcpServers` key (previously `servers` in some files)
+- **Version sync**: All plugin files aligned to v3.2.1 (`config.yml`, `plugin.json`, `marketplace.json`)
+- **Cleanup**: Removed duplicate directories, empty `.github/agents/`, `.github/prompts/`, `.github/instructions/`, `.github/hooks/`
+
+### MCP Server Metadata
+
+- **Server title**: MCP panel now shows "Specky" with description instead of raw binary name
+- **Server icon**: SVG + PNG icons served from GitHub raw content, visible in VS Code MCP panel
+- **Website URL**: Links to [specky-site](https://paulasilvatech.github.io/specky-site/) from server metadata
+- **Instructions**: AI clients receive pipeline guidance during MCP handshake
+- **Template path fix**: Templates now resolve from `dist/templates/` (self-contained npm package)
+
+### Documentation
+
+- **MCP config examples**: Added `"type": "stdio"` to all VS Code, Claude Code, and Claude Desktop config examples
+- **Removed broken env vars**: Removed `SDD_WORKSPACE` / `${workspaceFolder}` that caused startup errors
+- **Tool count**: Updated 56 → 57 across all documentation
+- **EARS patterns**: Fixed 5 → 6 pattern count (includes Complex)
+- **Broken links**: Fixed references to private files (CLAUDE.md, SYSTEM-DESIGN.md, ears-notation.md)
+- **Site fixes**: Updated EARS count and footer links on [specky-site](https://paulasilvatech.github.io/specky-site/)
+
 ## [3.2.0] - 2026-04-12
 
 ### Enterprise Security Hardening

package/README.md

@@ -23,6 +23,7 @@
   <p>
     <a href="https://paulasilvatech.github.io/specky-site/">Website</a> ·
     <a href="GETTING-STARTED.md">Getting Started</a> ·
+    <a href="plugins/specky-sdd/">Plugin</a> ·
     <a href="https://www.npmjs.com/package/specky-sdd">npm</a> ·
     <a href="SECURITY.md">Security</a>
   </p>
@@ -36,8 +37,10 @@
 | **Start** | [What is Specky?](#what-is-specky) | Overview and ecosystem |
 | | [Why Specifications Matter](#why-specifications-matter-in-the-ai-era) | Vibe coding vs deterministic development |
 | | [Getting Started](GETTING-STARTED.md) | Complete educational guide |
-| **Use** | [Quick Start](#quick-start) | Install via npm or Docker, connect to your IDE |
-| | [Where Specifications Live](#where-specifications-live) | File structure and naming conventions |
+| **Install** | [Quick Start](#quick-start) | Install plugin or MCP server, connect to your IDE |
+| | [Plugin (recommended)](#install-as-plugin-recommended) | Enterprise-grade: agents, skills, hooks, MCP — all in one |
+| | [MCP Server Only](#install-mcp-server-only) | Lightweight: just the 57 MCP tools |
+| **Use** | [Where Specifications Live](#where-specifications-live) | File structure and naming conventions |
 | | [Input Methods](#input-methods-6-ways-to-start) | 6 ways to feed Specky |
 | | [Three Project Types](#three-project-types-one-pipeline) | Greenfield, Brownfield, Modernization |
 | **Pipeline** | [Pipeline and LGTM Gates](#pipeline-and-lgtm-gates) | 10 phases with human review gates |
@@ -55,7 +58,7 @@ Specky is an open-source **MCP server** that turns the [Spec-Kit](https://github
 
 **Spec-Kit** provides the methodology: EARS notation, gated pipeline phases, constitution model, quality patterns. **Specky** reimplements all of it as MCP tools and adds programmatic enforcement: a state machine that blocks phase-skipping, an EARS validator, cross-artifact analysis, compliance engines, test generation, and MCP-to-MCP routing.
 
-**Install Specky and you get both.** The Spec-Kit methodology is already built in. It works inside any AI IDE that supports MCP, via `.github/agents/` or `.claude/commands/`, and natively in Cursor, Windsurf, or any MCP-compatible client. See how they [complement each other](#the-spec-driven-development-platform).
+**Install the Specky plugin and you get everything.** The Spec-Kit methodology is built in. The plugin bundles 7 agents, 19 prompts, 6 skills, 10 automation hooks, and the MCP server — all configured automatically. It works inside VS Code with Copilot, Claude Code, Cursor, Windsurf, or any MCP-compatible client. See the [plugin documentation](plugins/specky-sdd/) or how Spec-Kit and Specky [complement each other](#the-spec-driven-development-platform).
 
 
 ## Why Specifications Matter in the AI Era
@@ -109,7 +112,7 @@ Specky adds a **deterministic engine** between your intent and your code:
 | Phantom task detection | Catches tasks marked done with no code evidence |
 | Property-based testing | fast-check (TypeScript) and Hypothesis (Python) |
 | Checkpoint/restore | Persistent snapshots of all spec artifacts |
-| 7 automation hooks | Tests, docs, security scan, spec sync, SRP, changelog, checkpoint |
+| 10 automation hooks (2 blocking) | Security scan, release gate, spec sync, checkpoint, quality, EARS, task trace, drift, cognitive debt, metrics |
 | Works in any MCP host | VS Code + Copilot, Claude Code, Cursor, Windsurf, or any MCP client |
 | Zero outbound network calls | Fully air-gapped, code never leaves your machine |
 | MIT open source | Fork it, extend it, audit it. No vendor lock, no seat pricing |
@@ -122,31 +125,73 @@ Specky adds a **deterministic engine** between your intent and your code:
 - **Node.js 18+**: [Download here](https://nodejs.org/)
 - **An AI IDE**: VS Code with Copilot, Claude Code, Claude Desktop, Cursor, or Windsurf
 
-### Step 1: Choose Your Installation Scope
+### Install as Plugin (recommended)
 
-| Scope | What it does | Best for |
-|-------|-------------|----------|
-| **Per workspace** (recommended) | Config file lives inside the repo, shared with the team via Git | Teams, open-source projects |
-| **Global (once)** | Installed on your machine, available in every repo automatically | Personal use, quick setup |
+The **Specky plugin** is the enterprise-grade installation method. It bundles everything your team needs: 7 agents, 19 prompts, 6 skills, 10 automation hooks, and the MCP server — configured automatically and version-controlled with your repo.
 
-### Step 2: Install
+| What you get | MCP Server Only | Plugin |
+|-------------|:-:|:-:|
+| 57 MCP tools | ✅ | ✅ |
+| 7 specialized agents | — | ✅ |
+| 19 reusable prompts | — | ✅ |
+| 6 domain skills (SKILL.md) | — | ✅ |
+| 10 automation hooks (2 blocking) | — | ✅ |
+| EARS notation reference | — | ✅ |
+| Model routing guidance | — | ✅ |
+| Pipeline config (config.yml) | — | ✅ |
+| `copilot plugin install` ready | — | ✅ |
 
-<details open>
-<summary><strong>Global (recommended): Install once, use everywhere</strong></summary>
+#### Via Copilot CLI
 
-Install globally so `specky-sdd` is always available — no re-download on every run:
+```bash
+copilot plugin marketplace add paulasilvatech/specky
+copilot plugin install specky-sdd@specky
+```
+
+#### Manual Installation
 
 ```bash
-npm install -g specky-sdd
+cd your-project/
+bash <(curl -sL https://raw.githubusercontent.com/paulasilvatech/specky/main/plugins/specky-sdd/install.sh)
 ```
 
-Then configure your IDE to use the global install:
+The installer creates:
+
+```
+your-project/
+├── .github/plugin/specky/          ← Full plugin (agents, skills, hooks, prompts)
+│   ├── agents/                     ← 7 specialized Copilot agents
+│   ├── prompts/                    ← 19 reusable prompts
+│   ├── skills/                     ← 6 domain skills
+│   ├── hooks/scripts/              ← 10 automation hooks
+│   ├── instructions/               ← Copilot instructions
+│   └── config.yml                  ← Pipeline configuration
+├── .vscode/
+│   ├── mcp.json                    ← MCP server configuration
+│   └── settings.json               ← Hook integration
+└── GETTING-STARTED.md
+```
+
+> **Tip:** Commit `.github/plugin/` and `.vscode/` to Git so every team member gets Specky automatically on clone.
+
+See the full [plugin documentation](plugins/specky-sdd/README.md) for details.
+
+### Install MCP Server Only
+
+If you only need the 57 MCP tools without agents, skills, and hooks, install the MCP server directly.
+
+<details>
+<summary><strong>Global (npm)</strong></summary>
+
+```bash
+npm install -g specky-sdd
+```
 
 **VS Code** (`.vscode/mcp.json`):
 ```json
 {
-  "servers": {
-    "specky": {
+  "mcpServers": {
+    "specky-sdd": {
       "type": "stdio",
       "command": "specky-sdd"
     }
@@ -156,21 +201,14 @@ Then configure your IDE to use the global install:
 
 **Claude Code**:
 ```bash
-claude mcp add specky -- specky-sdd
+claude mcp add specky-sdd -- specky-sdd
 ```
 
 **Claude Desktop** (`claude_desktop_config.json`):
-
-| OS | Config location |
-|----|----------------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-
 ```json
 {
   "mcpServers": {
-    "specky": {
+    "specky-sdd": {
       "command": "specky-sdd"
     }
   }
@@ -180,57 +218,37 @@ claude mcp add specky -- specky-sdd
 </details>
 
 <details>
-<summary><strong>Per Workspace (alternative): npx, no global install</strong></summary>
-
-Add a config file to the repo so teammates get Specky automatically on clone — no global install needed.
+<summary><strong>Per Workspace (npx)</strong></summary>
 
 **VS Code** (`.vscode/mcp.json`):
 ```json
 {
-  "servers": {
-    "specky": {
+  "mcpServers": {
+    "specky-sdd": {
       "type": "stdio",
-      "command": "specky-sdd"
+      "command": "npx",
+      "args": ["-y", "specky-sdd@latest"]
     }
   }
 }
 ```
 
-**Claude Code**:
-```bash
-claude mcp add specky -- specky-sdd
-```
-
 > Commit `.vscode/mcp.json` to Git so every team member gets Specky automatically.
 
 </details>
 
 <details>
-<summary><strong>Docker: Docker (HTTP mode, no Node.js required)</strong></summary>
-
-Run Specky as an HTTP server in a container:
+<summary><strong>Docker (HTTP mode, no Node.js required)</strong></summary>
 
 ```bash
 docker run -d --name specky -p 3200:3200 -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest
 ```
 
-Verify it's running:
-
-```bash
-curl http://localhost:3200/health
-```
-
 Point any MCP client that supports HTTP to `http://localhost:3200/mcp`
 
-Stop when done:
-
-```bash
-docker stop specky && docker rm specky
-```
-
 </details>
 
-### Step 3: Verify
+### Verify
 
 Open your AI IDE and type:
 
@@ -242,7 +260,7 @@ The AI should list the 57 SDD tools. If you see them, Specky is working.
 
 ### Try It Now
 
-Once connected, type this in your AI chat to see Specky in action:
+Once connected, type this in your AI chat:
 
 ```
 > Initialize a Specky project for a todo API and help me define the scope
@@ -853,14 +871,14 @@ All artifacts are saved in [`.specs/NNN-feature/`](#where-specifications-live).
 
 **[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.
 
-**Specky** is the MCP engine that reimplements that methodology as 53 enforceable tools with programmatic validation. It enforces **how** to do it.
+**Specky** is the MCP engine that reimplements that methodology as 57 enforceable tools with programmatic validation. It enforces **how** to do it.
 
 | | Spec-Kit (Methodology) | Specky (Engine) |
 |--|------------------------|-----------------|
-| **What it is** | Prompt templates + agent definitions | MCP server with 55 tools |
+| **What it is** | Prompt templates + agent definitions | MCP server with 57 tools |
 | **How it works** | AI reads `.md` templates and follows instructions | AI calls tools that validate, enforce, and generate |
 | **Validation** | AI tries to follow the prompts | State machine, EARS regex, Zod schemas |
-| **Install** | Copy `.github/agents/` and `.claude/commands/` | `npx specky-sdd` (includes methodology built-in) |
+| **Install** | Copy `.github/agents/` and `.claude/commands/` | `copilot plugin install specky-sdd@specky` or `npm install -g specky-sdd` |
 | **Works standalone** | Yes, in any AI IDE | Yes, includes all Spec-Kit patterns |
 | **Best for** | Learning SDD, lightweight adoption | Production enforcement, enterprise, compliance |
 
@@ -870,10 +888,19 @@ When you install Specky, you get the full Spec-Kit methodology reimplemented as
 
 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.
 
+The recommended way to adopt this stack is via the [Specky plugin](plugins/specky-sdd/), which bundles the MCP server, agents, skills, and hooks into a single installable package:
+
+```bash
+copilot plugin marketplace add paulasilvatech/specky
+copilot plugin install specky-sdd@specky
+```
+
+Or configure the MCP server directly:
+
 ```json
 {
-  "servers": {
-    "specky": {
+  "mcpServers": {
+    "specky-sdd": {
       "type": "stdio",
       "command": "specky-sdd"
     }
@@ -881,7 +908,7 @@ Together they form the **SDD layer** of the GitHub + Microsoft enterprise platfo
 }
 ```
 
-> **Note:** This example assumes `specky-sdd` is installed globally (`npm install -g specky-sdd`). See the [Quick Start](#quick-start) section for per-workspace and Docker alternatives.
+> **Note:** This example assumes `specky-sdd` is installed globally (`npm install -g specky-sdd`). See the [Quick Start](#quick-start) section for plugin installation, per-workspace, and Docker alternatives.
 
 ## Project Configuration
 
@@ -1086,7 +1113,7 @@ For contributors, see [CONTRIBUTING.md](CONTRIBUTING.md).
 | Test traceability: REQ-ID → test coverage mapping | Stable |
 | Intent drift detection with amendment suggestions | Stable |
 | 10 automation hooks (2 blocking) | Stable |
-| 12 Claude Code commands + 5 Copilot agents | Stable |
+| 7 Copilot agents + 19 prompts + 6 skills (via plugin) | Stable |
 | 6 compliance frameworks (HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001) | Stable |
 | 6 input types (transcript, PDF, DOCX, Figma, codebase, raw text) | Stable |
 | Test generation for 6 frameworks (vitest, jest, playwright, pytest, junit, xunit) | Stable |

package/SECURITY.md

@@ -26,7 +26,7 @@ If you discover a security vulnerability in Specky, please report it responsibly
 
 ### Input Validation
 
-All 56 MCP tool inputs are validated using [Zod](https://zod.dev/) schemas with `.strict()` mode. No unknown fields are accepted. This prevents injection of unexpected parameters through the MCP JSON-RPC interface.
+All 57 MCP tool inputs are validated using [Zod](https://zod.dev/) schemas with `.strict()` mode. No unknown fields are accepted. This prevents injection of unexpected parameters through the MCP JSON-RPC interface.
 
 ```
 AI Client → JSON-RPC → Zod .strict() validation → Service layer
@@ -193,15 +193,15 @@ Running `npx specky-sdd` without a pinned version downloads the latest package f
 | Approach | Risk reduction | Notes |
 |----------|---------------|-------|
 | `npm install -g specky-sdd` | **High** — fetches once, runs offline after | Recommended default |
-| `npm install -g specky-sdd@3.2.0` | **Higher** — version-pinned, no silent upgrades | Best for reproducible environments |
-| Docker (`ghcr.io/paulasilvatech/specky:3.2.0`) | **Highest** — immutable image by digest | Best for CI/CD and air-gapped |
+| `npm install -g specky-sdd@3.2.1` | **Higher** — version-pinned, no silent upgrades | Best for reproducible environments |
+| Docker (`ghcr.io/paulasilvatech/specky:3.2.1`) | **Highest** — immutable image by digest | Best for CI/CD and air-gapped |
 | `npx specky-sdd` (unversioned) | **Baseline** — re-downloads on each invocation | Avoid in production pipelines |
 
 **Workspace isolation pattern** (CI/CD):
 
 ```bash
 # Install into a local vendor directory — no global write permissions needed
-npm install specky-sdd@3.2.0 --prefix ./vendor --ignore-scripts
+npm install specky-sdd@3.2.1 --prefix ./vendor --ignore-scripts
 ./vendor/node_modules/.bin/specky-sdd
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specky-sdd",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Specky — 57 MCP tools for Spec-Driven Development. 10-phase pipeline, enterprise security (rate limiting, HMAC state integrity, RBAC, hash-chained audit), model routing guidance, context tiering, cognitive debt metrics, EARS notation, 17 diagram types.",
   "type": "module",
   "main": "dist/index.js",