	Section	Description
Start	What is Specky?	Overview and ecosystem
	What's Included	Agents, prompts, skills, hooks, and MCP tools
	Why Specifications Matter	Vibe coding vs deterministic development
	Getting Started	Complete educational guide
Use	Quick Start	Install via npm CLI
	Where Specifications Live	File structure and naming conventions
	Input Methods	6 ways to feed Specky
	Three Project Types	Greenfield, Brownfield, Modernization
	Use-Case Contracts	Lifecycle, workload, mode, capabilities, evidence, migration
	How to upgrade	Bump npm + refresh project assets (no `--target` needed)
	Staying up to date	Update notifications and opt-out
Pipeline	Pipeline and LGTM Gates	Feature-specific phase graphs and configured review gates
	All 58 Tools	Complete tool reference by category
	EARS Notation	The 6 requirement patterns
Enterprise	Compliance Frameworks	HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001
	Enterprise Ready	Security, audit trail, quality gates
Platform	The SDD Platform	Built on Spec-Kit, everything included
	Roadmap	v3.12.0 current, future capabilities planned

What is Specky?

Specky is a CLI toolkit for Spec-Driven Development — 13 specialized agents, 58 MCP tools, 22 prompts, 14 skills, and 16 automation hooks. Each feature selects an explicit lifecycle, workload, execution mode, and capability configuration; Specky persists the resolved phase graph and rejects missing identity, hidden defaults, unsupported capabilities, and ungrounded artifact evidence.

Powered by the Spec-Kit methodology. Install the specky CLI and it places agents, prompts, skills, hooks, and the MCP server registration into your project — for GitHub Copilot (VS Code), Claude Code, Cursor, or OpenCode.

What's Included

Specky is a complete AI development toolkit — not just an MCP server. The specky CLI installs everything your AI IDE needs into a single project:

Primitive	What it is	Specky includes
Agents	Specialized AI personas with defined roles, tools, and guardrails	13 agents — @specky-orchestrator (full pipeline), @specky-onboarding (wizard), @specky-spec-engineer, @specky-design-architect, @specky-task-planner, @specky-quality-reviewer, and 7 more
Prompts	Slash commands that activate the right agent for a task	22 prompts — `/specky-greenfield`, `/specky-specify`, `/specky-release`, `/specky-orchestrate`, etc.
Skills	Domain knowledge files loaded into agent context automatically	14 skills — SDD pipeline rules, phase playbooks, EARS patterns, implementation patterns, test criteria, release gate protocol
Hooks	Scripts that run before/after every tool call for validation	16 hooks — specky-artifact-validator, specky-branch-validator, specky-phase-gate, specky-lgtm-gate, specky-security-scan, etc.
MCP Server	The tool engine that validates, generates, and enforces	58 tools via Model Context Protocol (the runtime underneath)

Why not just an MCP server?

An MCP server gives you tools. The CLI toolkit gives you the experience:

Tools alone: You must provide exact feature identity, use-case selection, capability parameters, and evidence.
CLI toolkit: You invoke @specky-orchestrator; it loads the feature's signed contract, follows its persisted graph, delegates to lean agents that read rich skills, and applies configured gates.

The MCP engine is the runtime. The agents + hooks + skills are the product.

How to install

Specky ships as a single npm package with a unified specky CLI. Works on macOS, Linux, Windows, and WSL.

# 1. Install the CLI globally (once per machine)
npm install -g specky-sdd@latest

# 2. Bootstrap your project — choose your target harness:
cd your-project
specky install --target=copilot      # VS Code + GitHub Copilot (recommended)
specky install --target=claude       # Claude Code
specky install --target=cursor       # Cursor
specky install --target=opencode     # OpenCode
specky install --target=agent-skills # Skills-only shared .agents/skills bundle

Important: Prefer --target=.... The legacy --ide flag still works for copilot, claude, both, and auto, but it is deprecated in favor of APM-style targets. Copilot + Claude in the same workspace is supported (--target=both or all); Specky strips Claude hooks from .claude/settings.json so Copilot cannot cross-read them. Prefer a single target if you need Claude lifecycle hooks. See docs/INSTALL.md for details.

Or per-project (for teams — pins version in package.json, run via npx):

cd your-project
npm install --save-dev specky-sdd@latest
npx specky install --target=copilot

The CLI installs 13 agents, 22 prompts, 14 skills, 16 hooks, and target-local MCP registration pinned to the installed version. Canonical agent capabilities compile to the selected harness's native tools; they are not inferred from workflow prose. Use --permission-profile=scoped (default) for narrow Claude pre-authorization, or --permission-profile=prompt to leave every approval with the host. Specky does not pre-authorize arbitrary shell, rm, network access, or credentials. Add --integration=github only when GitHub MCP routing is required. Run specky doctor anytime to validate integrity and configuration.

Generated assets are platform-native. specky install --target=copilot writes GitHub Copilot agents/prompts with VS Code tool names such as search, agent, and specky/sdd_get_status, plus prompt agent: agent frontmatter. specky install --target=claude writes Claude Code agents/commands with Read, Glob, Grep, Task, and mcp__specky__sdd_get_status, with Copilot-only prompt metadata removed. Cursor and OpenCode receive their own native vocabulary. agent-skills is intentionally skills-only. See Target Capabilities for the full capability matrix, GitHub MCP opt-in, and host approval boundaries.

Specky also has an APM governance layer for enterprise package control. apm.yml declares the package primitives, targets, and MCP runtime; apm.lock.yaml pins primitive hashes; apm-policy.yml enforces MCP and tool-name policy. Maintainers and CI can run specky apm validate, specky apm policy, specky apm verify-lock, and specky apm sbom before publishing or installing. See Uso do APM pelo Specky for the detailed model, including why APM is not a runtime proxy and why users do not need to install the Microsoft APM CLI.

Full walkthroughs per OS, offline install, and CLI reference: docs/INSTALL.md · docs/CLI.md.

How to upgrade

When a new Specky version is out (banner from specky doctor / specky status, or GitHub Releases):

# Global CLI (most users)
npm install -g specky-sdd@latest
cd your-project
specky upgrade

# Per-project pin (teams)
npm install --save-dev specky-sdd@latest
npx specky upgrade

You do not need --target on upgrade. specky upgrade reads the harness you already installed from .specky/install.json and refreshes the same targets — agents, prompts, skills, hooks, and MCP registration (.mcp.json, .vscode/mcp.json, .cursor/mcp.json, or opencode.json). It preserves .specs/ (pipeline artifacts) and .specky/profile.json (onboarding answers).

Updating only the npm package is not enough: without specky upgrade, MCP pins can still point at the old server version.

Use --target only for a first install or when switching harness (e.g. Copilot → Cursor):

specky install --target=cursor          # new target set
specky install --force --target=copilot   # reinstall / repair one target

See also Staying up to date for update notifications and opt-out.

Why Specifications Matter in the AI Era

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#f8fafc","primaryBorderColor":"#9ca3af","primaryTextColor":"#111827","secondaryColor":"#f3f4f6","tertiaryColor":"#e5e7eb","lineColor":"#6b7280","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart LR
  A["Raw intent"] --> B["Vibe coding<br/>direct prompt to code"]
  B --> C["Guessing<br/>implicit requirements"]
  C --> D["Rework<br/>drift and missing acceptance criteria"]

  A --> E["Specky SDD<br/>validated specification first"]
  E --> F["EARS requirements<br/>measurable acceptance criteria"]
  F --> G["Deterministic delivery<br/>traceable design, tasks, tests, release"]

  classDef node fill:#f8fafc,stroke:#9ca3af,color:#111827,stroke-width:1px;
  classDef risk fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px;
  class A,E,F,G node;
  class B,C,D risk;

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 is avoidable rework: requirements, acceptance criteria, design decisions, tasks, tests, and release evidence cannot be traced to one reviewed contract.

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.

Key concepts you should know:

Concept	What it is	Why it matters
Markdown	The universal language that both humans and AI read fluently	All spec artifacts are `.md` files in your repo, versioned with Git
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
EARS Notation	A method for writing requirements that forces precision with 6 patterns	Eliminates vague statements like "the system should be fast"
Agents and Skills	Specialized AI roles that invoke Specky tools with domain expertise	13 agents + 14 skills orchestrate the full pipeline
CLI Toolkit	A complete AI development package: agents + prompts + skills + hooks + MCP server	Installed via npm: `npm install -g specky-sdd`

How Specky Enforces Determinism

Specky adds a deterministic engine between your intent and your code:

State Machine: signed per-feature phase graphs for full, rapid, and emergency execution modes.
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.

What Makes Specky Different

Capability	Specky
Complete CLI toolkit	13 agents, 22 prompts, 14 skills, 16 hooks + 58 MCP tools
Pipeline orchestrator	@specky-orchestrator follows the selected feature's signed phase graph
Onboarding wizard	@specky-onboarding detects context and guides setup
Explicit input contracts	Document, transcript, and Figma tools require enabled capabilities and complete parameters
EARS validation (programmatic, not AI guessing)	6 patterns enforced at schema level
Enforced pipeline (not suggestions)	Contract-specific phases, central analysis gate, optional configured LGTM blocking
Pre/post hooks on every phase	specky-artifact-validator, specky-branch-validator, specky-phase-gate, specky-lgtm-gate
Workload-specific diagrams	Explicit evidence validation or deterministic auto-generation from specification/design content
Infrastructure as Code	DESIGN.md-driven Terraform with exact resource templates and fail-fast preflight
Work item export	GitHub Issues, Azure Boards, Jira via MCP-to-MCP routing
5 compliance frameworks	HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 with explicit control-ID evidence
Cross-artifact traceability	Requirement to design to task to test to code
Explicit release policy	Branch prefix, base, draft, and checkpoint choices persisted per feature
Unified CLI distribution	`npm install -g specky-sdd && specky install --target=copilot` — one binary, multi-OS (macOS/Linux/Windows/WSL)
First-class harness targets	VS Code + Copilot, Claude Code, Cursor, OpenCode, plus shared `.agents/skills`
Zero outbound calls from the MCP server	Air-gap friendly; code never leaves your machine. The CLI's once-daily update check is opt-out
MIT open source	Fork it, extend it, audit it. No vendor lock, no seat pricing

Quick Start

Prerequisites

Node.js 20+: Download here (Node 20 LTS recommended)
An AI IDE or agent CLI: VS Code with Copilot, Claude Code, Cursor, or OpenCode

Install the Plugin

One-time CLI install:

npm install -g specky-sdd@latest

Bootstrap each project:

cd your-project
specky install

That's it. The CLI auto-detects supported harnesses or uses the explicit target and installs the 13 agents, 22 prompts, 14 skills, 16 hooks, and MCP server registration with least-privilege tool scope for the selected harness.

Other install modes:

# Per-project (teams — pins version in package.json)
cd your-project
npm install --save-dev specky-sdd@latest
npx specky install

# Zero-install (one command, no persistent CLI)
cd your-project
npx -y specky-sdd@latest install

Full per-OS walkthrough: docs/INSTALL.md · CLI reference: docs/CLI.md.

Verify

specky doctor          # validates integrity + configuration
specky status          # shows active features and pipeline phase

Then open your IDE and type:

@specky-onboarding

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

Try It Now

@specky-orchestrator run the pipeline for a todo API

The orchestrator resolves the selected feature contract and follows its full, rapid, or emergency phase graph. Specify, Design, and Tasks require lgtm: true only when workspace configuration enables LGTM enforcement.

Your situation	Guide
Building something new	Greenfield
Adding features to existing code	Brownfield
Upgrading a legacy system	Modernization

Tip: New to Spec-Driven Development? Specky already includes all the SDD methodology from Spec-Kit. Just install Specky and the pipeline guides you through every phase with educative outputs that explain the concepts as you work.

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            ← Required runtime workspace contract

Naming convention: NNN-feature-name, zero-padded number + kebab-case name. Each directory is independent; you can work on multiple features simultaneously.

Input Methods: 6 Ways to Start

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#f8fafc","primaryBorderColor":"#9ca3af","primaryTextColor":"#111827","secondaryColor":"#f3f4f6","tertiaryColor":"#e5e7eb","lineColor":"#6b7280","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart TB
  P["Natural language prompt"] --> I["Specky input layer"]
  T["Meeting transcript"] --> I
  D["Documents<br/>PDF, DOCX, PPTX, MD"] --> I
  F["Figma or FigJam"] --> I
  C["Existing codebase"] --> I
  R["Raw pasted text"] --> I
  I --> S["sdd_init + sdd_discover"]
  S --> A[".specs/NNN-feature<br/>research, requirements, design, tasks"]

  classDef input fill:#ffffff,stroke:#9ca3af,color:#111827,stroke-width:1px;
  classDef engine fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px;
  classDef output fill:#f8fafc,stroke:#374151,color:#111827,stroke-width:1px;
  class P,T,D,F,C,R input;
  class I,S engine;
  class A output;

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.

Honest note on binary formats: the built-in extractor fully handles md/txt and simple uncompressed files. Real-world (compressed) PDF/DOCX/PPTX need one of: the optional mammoth/pdfjs-dist packages, or the recommended MarkItDown MCP integration. Since 3.6, unsupported binaries fail with clear guidance instead of silently importing garbage.

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

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#f8fafc","primaryBorderColor":"#9ca3af","primaryTextColor":"#111827","secondaryColor":"#f3f4f6","tertiaryColor":"#e5e7eb","lineColor":"#6b7280","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart LR
  G["Greenfield<br/>new product idea"] --> D["Discover"]
  B["Brownfield<br/>existing codebase"] --> D
  M["Modernization<br/>legacy migration"] --> D
  D --> S["Specify"] --> A["Analyze"] --> I["Implement"] --> V["Verify"] --> R["Release"]

  classDef start fill:#ffffff,stroke:#9ca3af,color:#111827,stroke-width:1px;
  classDef phase fill:#f8fafc,stroke:#6b7280,color:#111827,stroke-width:1px;
  class G,B,M start;
  class D,S,A,I,V,R phase;

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:

Scope: What problem does this solve? What are the boundaries of v1?
Users: Who are the primary users? What are their skill levels?
Constraints: Language, framework, hosting, budget, timeline?
Integrations: What external systems, APIs, or services?
Performance: Expected load, concurrent users, response times?
Security: Authentication, authorization, compliance requirements?
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:

## 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, submit SOC2 control evidence, and validate the workload-required diagram set

The AI calls:

sdd_run_analysis → completeness audit, orphaned criteria detection
sdd_compliance_check → evaluates the persisted SOC2 pack using evidence keyed by control ID
sdd_generate_all_diagrams → validates explicit Mermaid payloads or uses mode: "auto" to derive the complete supported set from source evidence before an atomic write

Step 6: Generate infrastructure and tests

> Generate the persisted Azure Terraform resources, Docker environment, and executable Vitest bindings

The AI calls:

sdd_generate_iac → Terraform for the exact cloud/resources grounded in the relevant DESIGN.md sections; excluded or unsupported resources fail before files are written
sdd_generate_dockerfile → Dockerfile/compose from the persisted development stack
sdd_generate_tests → executable tests from fingerprinted requirement bindings

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 to understand the requirement patterns, or see All 58 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: Next: See compliance frameworks for regulatory validation, or MCP integration 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 for regulatory validation during modernization, or project configuration to customize Specky for your team.

Pipeline and LGTM Gates

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#f8fafc","primaryBorderColor":"#9ca3af","primaryTextColor":"#111827","secondaryColor":"#f3f4f6","tertiaryColor":"#e5e7eb","lineColor":"#6b7280","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart LR
  I["Init"] --> D["Discover"] --> S["Specify"] --> G1{"LGTM gate"}
  G1 -->|approved| C["Clarify"] --> A["Design"] --> G2{"LGTM gate"}
  G2 -->|approved| T["Tasks"] --> G3{"LGTM gate"}
  G3 -->|approved| N["Analyze"] --> P["Implement"] --> V["Verify"] --> R["Release"]
  G1 -->|changes requested| S
  G2 -->|changes requested| A
  G3 -->|changes requested| T
  V -->|drift detected| S

  classDef phase fill:#f8fafc,stroke:#6b7280,color:#111827,stroke-width:1px;
  classDef gate fill:#f3f4f6,stroke:#374151,color:#111827,stroke-width:1px;
  class I,D,S,C,A,T,N,P,V,R phase;
  class G1,G2,G3 gate;

This diagram is the full execution-mode graph. Rapid and emergency contracts persist smaller ordered graphs. The state machine blocks transitions outside the selected feature's graph.

LGTM gates: Specify, Design, and Tasks can require lgtm: true when .specky/config.yml enables LGTM enforcement. When disabled, review remains useful but is not a hidden blocking default.

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.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#f8fafc","primaryBorderColor":"#9ca3af","primaryTextColor":"#111827","secondaryColor":"#f3f4f6","tertiaryColor":"#e5e7eb","lineColor":"#6b7280","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart LR
  P0["0 Init"] --> P1["1 Discover"] --> P2["2 Specify"] --> P3["3 Clarify"] --> P4["4 Design"] --> P5["5 Tasks"] --> P6["6 Analyze"] --> P7["7 Implement"] --> P8["8 Verify"] --> P9["9 Release"]

  classDef phase fill:#ffffff,stroke:#9ca3af,color:#111827,stroke-width:1px;
  class P0,P1,P2,P3,P4,P5,P6,P7,P8,P9 phase;

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
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
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/. See Input Methods for how to feed data into the pipeline.

All 58 Tools

Input and Conversion (6)

Tool	Description
`sdd_import_document`	Convert PDF, DOCX, PPTX, TXT, MD to Markdown
`sdd_import_transcript`	Parse meeting transcripts (Teams, Zoom, Google Meet)
`sdd_auto_pipeline`	Any input to complete spec pipeline (all documents)
`sdd_batch_import`	Process folder of mixed documents
`sdd_batch_transcripts`	Scan folder of transcripts and run full auto-pipeline for each
`sdd_figma_to_spec`	Figma design to requirements specification

Pipeline Core (8)

Tool	Description
`sdd_init`	Initialize project with constitution and scope diagram
`sdd_discover`	Interactive disc

Specky

README

Table of Contents

What is Specky?

What's Included

Why not just an MCP server?

How to install

How to upgrade

Why Specifications Matter in the AI Era

The Problem: Vibe Coding

The Solution: Deterministic Development

How Specky Enforces Determinism

What Makes Specky Different

Quick Start

Prerequisites

Install the Plugin

Verify

Try It Now

Where Specifications Live

Input Methods: 6 Ways to Start

1. Natural Language Prompt (simplest)

2. Meeting Transcript (VTT / SRT / TXT / MD)

3. Existing Documents (PDF / DOCX / PPTX)

4. Figma Design (design-to-spec)

5. Codebase Scan (brownfield / modernization)

6. Raw Text (paste anything)

Three Project Types, One Pipeline

Greenfield Project: Start from Scratch

Step 1: Initialize and discover

Step 2: Write the specification

Step 3: Design the architecture

Step 4: Break into tasks

Step 5: Quality gates

Step 6: Generate infrastructure and tests

Step 7: Export and ship

Brownfield Project: Add Features to Existing Code

Step 1: Scan the codebase first

Step 2: Initialize with codebase context

Step 3: Import existing documentation

Step 4: Write spec with codebase awareness

Step 5: Check for drift

Step 6: Cross-feature analysis

Modernization Project: Assess and Upgrade Legacy Systems

Step 1: Scan and document the current state

Step 2: Import all existing documentation

Step 3: Import stakeholder meetings

Step 4: Create the modernization specification

Step 5: Compliance assessment

Step 6: Generate migration artifacts

Step 7: Generate onboarding for the team

Pipeline and LGTM Gates

All 58 Tools

Input and Conversion (6)

Pipeline Core (8)

Comments (0)