Spec it before you ship it.
Install in 60 seconds. No signup. No new IDE.
The complete SDD CLI toolkit that
keeps your requirements, code, and tests in sync. 13 agents, 58 MCP tools, 22 prompts, 14 skills, 16
hooks,
signed per-feature contracts, five evidence-backed compliance packs, and opt-in enterprise
controls.
One install. Explicit behavior.
Created by Paula Silva · @paulasilvatech · @paulanunes85
Specky running inside VS Code · GitHub Copilot Agent Mode · EARS notation, enforced pipeline
specky command installs agents,
prompts, skills, hooks, and the MCP server
registration into your project as one governed, versioned workflow.One npm package configures the local MCP server, IDE files, automation hooks, and SDD guidance your team needs. One install, one version, one rollback path.
Specky replaces improvised AI sessions with a governed, versioned, and auditable development workflow. Requirements, design, tasks, implementation, verification, and release stay connected.
Codify approved commands and workflows. Security policies restrict what the AI agent can do, ensuring only approved APIs and tools are used.
Senior engineers codify project expertise into skills and hooks. New team members get the full context automatically — tribal knowledge lives in the repo, not in people's heads.
Built on the open Model Context Protocol standard. Connect to databases, Slack, Jira, GitHub, Azure DevOps — no vendor lock-in, real-time context from every source.
Versioned with project-scoped configuration. Test, update, and roll back
independently. specky doctor verifies every team member runs the expected setup.
Specialized AI personas — @specky-orchestrator coordinates the
full pipeline, @specky-onboarding guides setup, plus 11 more for every phase.
Install the unified specky CLI from npm, then bootstrap your
project for GitHub Copilot or Claude Code. It pins agents, prompts, skills, hooks, and MCP configuration
to the installed package version.
13 agents orchestrate the pipeline, 22 prompts cover common workflows, 14 skills carry domain knowledge, and 16 hooks guard transitions. One install.
HIPAA, SOC 2, GDPR, PCI DSS, and ISO 27001 use explicit evidence keyed by control ID.
Zero outbound calls from the runtime. Three dependencies. No eval(). Works fully offline and in air-gapped environments.
Push to GitHub, Terraform, Docker, Jira, Azure DevOps, Figma. Specky generates payloads, your client delivers.
Six patterns that guarantee every requirement is testable, traceable, and unambiguous.
Artifact validation, branch checks, phase gates, LGTM gates, security scan, spec sync, drift monitor. Pre and post on every phase.
One package gives you the CLI, MCP server, 13 agents, 22 prompts, 14 skills, and 16 hooks.
# Install the CLI globally once $ npm install -g specky-sdd@latest # Bootstrap this project for VS Code + GitHub Copilot $ specky install --target=copilot # Verify integrity and configuration $ specky doctor
Everything is auto-configured. Specky creates .vscode/mcp.json, installs
agents, prompts, skills, hooks, and pins the MCP server to the package version.
Target-correct capabilities. Use --permission-profile=prompt to keep every
action behind host confirmation. Add --integration=github only when agents should route
authenticated PR and Issue payloads through GitHub MCP. Capability matrix →
Open Copilot Chat → Agent mode → type @specky-onboarding,
@specky-orchestrator, @specky-sdd-init, @specky-implementer, or
use prompts
like /specky-onboarding.
In Copilot Chat (Agent mode), type:
@specky-sdd-init initialize spec for user authentication
Tip: Specky auto-detects your stack (TypeScript, Python, Java, Go…) and applies the right EARS patterns. No configuration needed for most projects. Full docs →
One package installs the MCP server, agents, prompts, skills, and hooks for Claude Code.
# Install the CLI globally once $ npm install -g specky-sdd@latest # Bootstrap this project for Claude Code $ specky install --target=claude # Verify integrity and configuration $ specky doctor
Everything is auto-configured. Specky sets up the MCP server, agents, skills, hooks, and
slash commands automatically. The default scoped profile derives narrow Claude allow rules;
use --permission-profile=prompt to require confirmation for every action.
Specky adds 22 prompts. Start with:
/specky-specify write a spec for user auth /specky-design design the auth architecture /specky-verify check traceability
22 prompts: start with /specky-greenfield, /specky-specify,
/specky-orchestrate, and /specky-release.
Install Cursor-native agents, commands, rules, hooks, skills, and MCP registration.
# Install the CLI globally once $ npm install -g specky-sdd@latest # Bootstrap this project for Cursor $ specky install --target=cursor # Verify the server and generated config $ specky doctor
Everything is project-scoped. Specky writes .cursor/mcp.json,
.cursor/rules/specky-sdd.mdc, native hooks, agents, commands, and shared skills.
Ask your AI assistant: "Use specky to write a spec for [feature]" or call tools directly from the MCP panel.
One command installs OpenCode-native agents, commands, shared skills, and MCP registration.
# Install the CLI globally once $ npm install -g specky-sdd@latest # Bootstrap this project for OpenCode $ specky install --target=opencode # Verify integrity and configuration $ specky doctor
Everything is auto-configured. Specky creates opencode.json,
.opencode/agents/, .opencode/commands/, and .agents/skills/.
Open OpenCode and ask it to use the Specky MCP server, or run specky doctor to
verify all generated assets.
Air-gapped mode: The MCP server (specky serve) makes zero outbound
network calls — stdio or localhost HTTP only. No telemetry, no cloud sync. Three runtime npm
dependencies (@modelcontextprotocol/sdk, zod, yaml). The CLI may
optionally check the npm registry once per day for update banners; disable that for a strict offline
posture (see step 3).
$ npm pack specky-sdd # produces: specky-sdd-3.12.0.tgz
$ npm install -g ./specky-sdd-3.12.0.tgz $ specky install --target=cursor # or copilot, claude, opencode
By default the CLI may perform one GET per day to registry.npmjs.org after
doctor/status — not telemetry, but not air-gapped. Turn it off:
# environment (session or shell profile) $ export SPECKY_NO_UPDATE_CHECK=1 # or persist in .specky/config.yml: # update_check: false
npx)Installed mcp.json files use npx -y specky-sdd@… serve, which can reach the
network if the package is not cached. On air-gapped hosts, use the global CLI directly:
{
"mcpServers": {
"specky": {
"command": "specky",
"args": ["serve"]
}
}
}
Stdio transport works identically offline. Run specky doctor to confirm asset integrity
(with SPECKY_NO_UPDATE_CHECK=1 set).
HIPAA, SOC 2, GDPR, PCI DSS, ISO 27001 validation runs locally against bundled rule sets — no external validation service required.
Enterprise profile features (identity-based RBAC, rate limiting, HMAC-signed audit trail, and fail-closed audit mode) are available as of v3.5.0. See Enterprise docs →
Why a CLI? The specky command pins the package version, installs the MCP server
registration, writes project-scoped agents/prompts/skills/hooks, and lets teams verify drift with
specky doctor.
--target on upgrade — Specky reuses the harness recorded in .specky/install.json.
# 1. Update the CLI on your machine $ npm install -g specky-sdd@latest # 2. Refresh agents, hooks, skills, and MCP pins in the project $ cd your-project $ specky upgrade
$ npm install --save-dev specky-sdd@latest $ npx specky upgrade
No --target on upgrade.
specky upgrade reads your previous install from .specky/install.json and refreshes
the same harness. It preserves .specs/ and re-pins MCP registration — updating npm alone leaves
the old server pinned. Use specky install --target=... only for a first install or when
switching IDE (e.g. Copilot → Cursor).
Read the use-case contract guide →
Create feature state, branch context, and canonical spec package
Fast modelScan codebase, detect stack, map existing patterns
Reasoning-focusedEARS requirements — 6 patterns, testable and traceable
BalancedResolve ambiguity before design or implementation starts
Reasoning-focusedArchitecture, components, interfaces, and diagrams
Reasoning-focusedSequenced task list with parallel markers and gates
BalancedCompute real quality gate, traceability, and cross-artifact drift
Reasoning-focusedCode generation guided by spec, tasks, and quality gates
BalancedTests, compliance checks, audit evidence, and release readiness
BalancedBranch-aware PR flow, blocking gates, changelog, and sign-off
Reasoning model13 agents + 22 prompts
22 prompts + hooks
58 tools via MCP
Native agents + MCP
Fork it, extend it, audit it. No vendor lock, no seat pricing.
Full, rapid, and emergency modes persist distinct ordered graphs.
No proprietary IDE. Use VS Code, Copilot, Claude Code, Cursor, or any MCP-compatible client.
Code never leaves your machine. Air-gapped environments fully supported.
Validate explicit Mermaid evidence or deterministically derive supported diagrams from SPECIFICATION.md and DESIGN.md.
Vitest, Jest, Playwright, Pytest, JUnit, xUnit. Plus property-based testing.
Terraform resources are grounded in relevant DESIGN.md sections; unsupported templates fail before files are written.
HIPAA, SOC 2, GDPR, PCI DSS, and ISO 27001 with explicit control evidence.
Opt-in enterprise defaults for identity-based RBAC, rate limiting, HMAC-signed audit trail, and fail-closed auditing.
Published GHCR image, Dockerfile, healthcheck, and HTTP transport on port 3200 for hosted or air-gapped deployments.
Run specky serve --http --profile=enterprise behind TLS with
bearer auth or named token tables.
Route structured payloads to GitHub, Azure DevOps, Jira, Terraform, Figma, Docker, or companion MCP servers your team builds.
linux/amd64 and linux/arm64, built from the hardened Dockerfile (multi-stage, non-root, healthcheck on /health).
Every image build produces a CycloneDX SBOM workflow artifact; Cosign signatures are added when signing secrets are configured.
Set SPECKY_PROFILE=enterprise to turn on identity-based
RBAC, rate limiting, and a HMAC-signed, fail-closed audit trail.
The container binds 0.0.0.0:3200 for port publishing; production deployments terminate TLS at a reverse proxy and require bearer-token auth.
# Public image, no login needed. Multi-arch: linux/amd64 + linux/arm64. $ docker pull ghcr.io/paulasilvatech/specky:3.12.0 # or :latest $ docker run --rm -p 3200:3200 ghcr.io/paulasilvatech/specky:3.12.0 $ curl -s http://localhost:3200/health # -> {"status":"ok","version":"3.12.0"}
# Enterprise profile: RBAC, rate limiting, HMAC-signed audit trail # Initialize a mounted workspace once; .specky/config.yml is mandatory. $ mkdir -p workspace $ (cd workspace && npx specky-sdd@3.12.0 install --target=agent-skills --yes) $ docker run --rm -p 127.0.0.1:3200:3200 \ -e SPECKY_PROFILE=enterprise \ -e SDD_HTTP_TOKENS_FILE=/run/secrets/tokens.yml \ -e SDD_AUDIT_HMAC_KEY_FILE=/run/secrets/audit.key \ -v "$PWD/workspace:/workspace" \ -v /etc/specky:/run/secrets:ro \ ghcr.io/paulasilvatech/specky:3.12.0
Never expose the port directly. The image binds 0.0.0.0:3200 inside the container so
-p works, but production deployments terminate TLS at a reverse proxy and require
SDD_HTTP_TOKEN or SDD_HTTP_TOKENS_FILE. A non-loopback bind without a token
prints a loud warning. Full enterprise deployment guide →
I am Paula Silva, Software Global Black Belt. My work sits between platform engineering, AI infrastructure, and the practical reality of helping teams adopt agentic development at enterprise scale.
The same problem kept showing up in that work: AI coding assistants are fast, but without structure they generate code based on vibes instead of validated requirements — code that works but does not match what anyone actually specified. Specky is the answer I wanted to hand teams: a CLI toolkit that enforces a state machine, EARS notation, and traceability between requirements, design, tests, and code, so specifications and implementation never drift apart.
It is 100% open source under the MIT license, designed to be installed, extended, and audited. The goal is not just another AI tool, it is turning spec-driven development into the default way teams ship AI-assisted software.