Specky 3.12.0 - Evidence-Grounded Diagrams and Terraform

Copy-paste body for the GitHub Release v3.12.0.

Specky 3.12.0 adds deterministic, evidence-grounded diagram generation and strengthens Terraform generation from DESIGN.md. The release preserves explicit diagram payloads as the default while adding an automatic mode for supported Mermaid types. Unsupported infrastructure now fails before any Terraform files are written.

Highlights

Explicit or Automatic Diagrams

sdd_generate_diagram and sdd_generate_all_diagrams accept mode: "explicit" | "auto". Explicit mode remains the default and validates caller-supplied Mermaid plus source evidence. Auto mode derives C4 context, sequence, ER, and deployment diagrams from SPECIFICATION.md and DESIGN.md, including evidence references for the actors, requirements, exchanges, entities, components, and deployment nodes used in each result.

Atomic Diagram Sets

Automatic diagram-set generation synthesizes and validates every contracted diagram in memory before writing DIAGRAMS.md. If the contract includes an unsupported type or any generated diagram fails validation, the prior artifact is left unchanged.

DESIGN.md-Driven Terraform

Terraform resource discovery uses canonical module:service keys and only the relevant design sections. Clause-scoped negation recognizes exclusions such as without, avoid, and not use, preventing excluded services from becoming resources.

Fail-Fast Infrastructure Preflight

Every requested resource must have a concrete template for the selected cloud. Unsupported resource types now produce an actionable hard error instead of placeholder comments or incomplete Terraform.

Cross-Platform and Developer Quality

Feature directories use stable forward-slash identifiers in user-facing MCP messages on Windows. The specky compile command validates and reads each instruction primitive through one file descriptor, eliminating a CodeQL-reported filesystem race. The release Docker build includes the Cursor plugin metadata consumed by manifest validation and an ephemeral internal workspace contract for no-volume health checks; mounted workspaces still require the strict .specky/config.yml created by specky install. The release also adds Biome lint/format commands, broader unit coverage, and longer integration-test timeouts for subprocess-heavy suites under CPU contention.

Compatibility

Existing diagram calls remain compatible because mode defaults to explicit. Callers using explicit mode continue to provide mermaid_code and evidence_refs; callers using auto mode omit those fields and let Specky derive both from the feature artifacts.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade
specky doctor

Project-scoped MCP registrations are pinned, so run specky upgrade after updating the npm package to refresh agents, prompts, skills, hooks, and the MCP runtime reference.

Validation

The release candidate passes the TypeScript build, manifest and primitive audits, 1019 tests across 99 files, and coverage thresholds of 89% statements, 77% branches, 95% functions, and 90% lines. The publish workflow also performs clean-package installation checks and builds the multi-architecture GHCR image with a CycloneDX SBOM artifact.

References

• Specky documentation
• MCP API reference
• Use-case contracts
• Publishing Specky
• npm Trusted Publishing
• GitHub Actions OIDC

Specky 3.11.1 - Signed Per-Feature Contracts

Copy-paste body for the GitHub Release v3.11.1.

Specky 3.11.1 makes the use-case contract a signed, per-feature runtime boundary. MCP tools now resolve feature identity and contract state before their handlers execute, preventing hidden defaults, ambiguous feature selection, and ungrounded generated artifacts.

Highlights

Signed Use-Case Contracts

Each feature persists a signed v5 state file containing its explicit lifecycle, workload, execution mode, capabilities, resolved phase graph, contract fingerprint, and HMAC signature. Specky supports 54 named lifecycle, workload, and mode contracts.

Strict Execution Context

Feature-scoped tools require the selected feature and its valid signed state. Legacy root state is not used at runtime; migrate it with specky migrate-contracts --dry-run before applying the reviewed plan.

Evidence-First Outputs

Documentation, diagrams, research, and turnkey specification flows accept explicit caller evidence and contract configuration. They fail closed when required evidence is absent instead of generating placeholder or inferred content.

Safer Packaging and Cursor Plugin Writes

The build clears stale output before compilation, and the Cursor plugin writer includes the upstreamed race-condition and unsafe-type fixes from the latest main branch.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade
specky doctor

For a workspace with legacy root state, review the deterministic migration plan first:

specky migrate-contracts --spec-dir=.specs --dry-run \
  --lifecycle=greenfield --workload=api --execution-mode=full \
  --capabilities='[]' --capability-config='{}'

Apply only the exact reviewed plan hash as documented by the CLI. See Use-Case Contracts for supported contracts and migration mappings.

Validation

The release pipeline builds the package, validates manifests and primitives, generates the API reference, executes the test suite, inspects the npm tarball, and installs the packed artifact in clean workspaces. The published workflow also builds the multi-architecture GHCR image and creates a CycloneDX SBOM artifact.

References

• Specky documentation
• Use-Case Contracts
• Publishing Specky
• npm Trusted Publishing
• GitHub Actions OIDC

Specky 3.11.0 - Target-Correct Agent Capabilities

Copy-paste body for the GitHub Release v3.11.0.

Specky 3.11.0 makes agent permissions explicit, portable, and testable across GitHub Copilot, Claude Code, Cursor, and OpenCode.

Highlights

Canonical Capabilities

Agents now declare canonical capabilities: in the APM source. Installation compiles them to the target-native tool vocabulary, so workflows receive the tools they actually require rather than relying on prose or cross-target tokens.

The verifier can run the detected test command, and release workflows have explicit Git, release-gate, and GitHub MCP capabilities. The implementer remains scaffold-only and does not receive production-code edit access.

Scoped or Prompted Permissions

Use the default scoped mode for narrow Claude Code allow rules:

specky install --target=claude --permission-profile=scoped

Or retain host confirmation for every action:

specky install --target=claude --permission-profile=prompt

Scoped mode never grants arbitrary shell execution, destructive shell commands, broad network access, or stored credentials.

Optional GitHub MCP

GitHub operations are now explicit and opt-in:

specky install --target=copilot --integration=github

Specky generates branch, pull request, and issue payloads. The host creates external resources only after the authenticated GitHub MCP tool is invoked. specky doctor verifies registration but intentionally does not claim that it can verify host authentication or user approval.

Release Integrity

Release metadata is synchronized across package.json, APM, config.yml, and the plugin MCP runtime pin. The preflight and installation CI smoke tests now cover Copilot, Claude, Cursor, OpenCode, and the skills-only agent-skills bundle. The publish workflow requires the GitHub Release tag to match the package version and emits OCI version/source/revision labels for GHCR images.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

To enable GitHub MCP in an existing workspace, run a target-specific reinstall:

specky install --force --target=copilot --integration=github
specky doctor --verbose

Read Target Capabilities for the target matrix, security boundaries, and runtime approval model.

References

• VS Code Model Context Protocol servers
• Claude Code permissions
• GitHub MCP Server

Specky 3.10.2 makes the Specky logo appear correctly in VS Code MCP and Cursor Agent Plugins — stdio MCP servers must use file:// icons, and Cursor needs a plugin manifest for the Installed plugins list.

Highlights

VS Code / GitHub Copilot

The MCP server handshake now advertises site/specky-icon.png as a local file:// URI with sizes. VS Code ignores HTTPS icon URLs on stdio transports.

Cursor Agent Plugins

specky install --target=cursor (and specky upgrade) now writes:

• .cursor-plugin/plugin.json — plugin manifest with logo
• .cursor/assets/specky-icon.png — copied from the npm package

Repo plugin (Marketplace / Git)

Root .cursor-plugin/plugin.json and mcp.json support installing Specky as a Cursor plugin from the repository.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

Restart VS Code or Cursor after upgrade so the MCP server reconnects with the new icon metadata.

Full details: CHANGELOG.md

Specky 3.10.1 — Tasks Parser + Report Persistence

Copy-paste body for the GitHub Release v3.10.1.

Specky 3.10.1 fixes the TASKS.md table↔checkbox mismatch that caused verify/implement/export to report "No tasks found", and closes related P0 gaps around persisted quality reports and Analyze-phase remediation.

Highlights

Dual TASKS.md parser

Writers emit markdown tables; readers now accept both table rows and legacy - [ ] T-001: checkboxes via shared parseTasksFromMarkdown. Wired into verify, implement, export, git progress, and Gantt diagrams.

Honest quality reports

COMPLIANCE.md and VERIFICATION.md persist pre-rendered table rows — no more [TODO: placeholders for findings/results.

Analyze remediation

After a BLOCK or CHANGES_NEEDED gate, authors can rewrite SPEC/DESIGN/TASKS in Analyze and re-run analysis. Implement/release tools remain gated until APPROVE.

Generation quality

• User stories use EARS prose titles (not (event_driven))
• Spec functional vs non-functional split
• Design stubs derived from SPECIFICATION.md when optional fields are omitted

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

Full details: CHANGELOG.md

Specky 3.10.0 — Pipeline MCP + Harness Hardening

Copy-paste body for the GitHub Release v3.10.0.

Specky 3.10.0 hardens the MCP pipeline with server-enforced analysis gates, strict phase bookkeeping, and expanded harness doctor/install coverage across all five targets.

Highlights

Server-enforced analysis gates

Implement, verify, and release tools now require gate_decision: APPROVE once the pipeline reaches Analyze. The check runs centrally in tool-enforcement.ts via validateGateForTool — not only on sdd_advance_phase.

Phase bookkeeping fixes

• ensurePhasesThrough closes orphan phases when write-tools skip advance_phase
• invalidateGateDecision clears stale approvals after SPEC/DESIGN/TASKS rewrites
• Strict feature_number resolution (no silent fallback to features[0])
• Analyze phase completes only on APPROVE

Pipeline tool improvements

• discovery_answers persisted in SPECIFICATION.md
• Real EARS compliance scores; invalid EARS blocked without force: true
• sdd_clarify starts Clarify without auto-completing it
• Dynamic pipeline.require_lgtm config loading

Harness completeness

• Expanded Cursor instructions; new OpenCode instruction primitive
• VS Code MCP writes both servers and mcpServers
• Claude/Cursor MultiEdit in tool map
• Doctor: Copilot hooks manifest, Claude hooks-in-settings, agent-skills count, improved target inference

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

OpenCode users:

specky install --target=opencode
specky compile --target=opencode

Full details: CHANGELOG.md

Specky 3.9.0 — Cursor-native hooks, dedicated phase skills, and doctor parity

Copy-paste body for the GitHub Release v3.9.0.

Specky 3.9.0 brings the Cursor target to full functional parity with Claude and Copilot — native hook automation, a dedicated always-on rule, and six new phase companion skills — and levels up specky doctor with per-target install validation. It also fixes cross-target instruction leakage in the Copilot and compile paths.

Highlights

Cursor-native hook automation

specky install --target=cursor now installs a complete, honest hook stack instead of skipping hooks:

• .cursor/hooks.json — Cursor schema v1 manifest generated from the single .apm/hooks/sdd-hooks.json source.
• .cursor/hooks/specky-run.sh — stdin adapter that maps Cursor hook payloads to the Specky hook scripts (SDD_TOOL_NAME, prompt extraction), with graceful jq-optional fallback.
• .cursor/hooks/scripts/ — the same 16 hook scripts used by Claude and Copilot.

Blocking gates (artifact validation, phase gate, security scan, release gate) deny unsafe actions with failClosed: true; advisory gates (branch, pipeline guard, LGTM, drift, checkpoint) warn without blocking.

Six dedicated phase companion skills (14 total)

Each pipeline phase agent now loads a dedicated skill first, with specky-sdd-pipeline retained as the shared cross-phase overview:

• specky-sdd-init (Phase 0), specky-spec-engineer (Phase 2), specky-sdd-clarify (Phase 3), specky-design-architect (Phase 4), specky-task-planner (Phase 5), specky-quality-reviewer (Phase 6).

Dedicated, leak-free instruction rules

• Cursor compiles to .cursor/rules/specky-sdd.mdc with alwaysApply and a neutral title.
• Claude compiles to .claude/rules/specky-sdd.md with neutral naming — no Copilot title, @workspace, or .vscode references.
• Copilot keeps its reserved .github/instructions/copilot-instructions.instructions.md, with the orphaned Rule #7/#8 headings merged into the Key Rules list and the outdated @workspace /prompt-name invocation corrected to /prompt-name.

specky doctor install parity

doctor now runs a full per-target install audit — agent, prompt/command, skill, and hook-script counts, rule format, MCP registration, and a cross-target leakage scan:

Cross-target isolation fixes

• Copilot installs no longer copy the Cursor/Claude instruction primitives into .github/instructions/; only the Copilot instruction is installed and stale primitives are removed.
• specky compile is now target-aware — each target renders only its own instruction primitive (Copilot as the neutral fallback) instead of concatenating every primitive into each root context file.
• Claude installs no longer receive the Copilot-named rule or @workspace/applyTo leakage.

Unified EARS notation

The rule, phase agents, and the specky-sdd-pipeline skill now use the canonical six EARS patterns: Ubiquitous, Event-driven, State-driven, Optional, Unwanted, and Complex.

Validation

• npm run build passed.
• npm test passed.
• specky apm validate, specky apm policy, and specky apm verify-lock passed.
• Smoke installs for all five targets (cursor, copilot, claude, opencode, agent-skills) pass their specky doctor checks with no cross-target leakage.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

For project-local installs:

npm install --save-dev specky-sdd@latest
npx specky upgrade

Cursor users gain native hooks on upgrade; enable the specky MCP server in Cursor Settings → MCP, then run specky doctor to confirm the install.

Full details: CHANGELOG.md

Specky 3.8.0 — Wave 1 multi-harness APM targets

Copy-paste body for the GitHub Release v3.8.0.

Specky 3.8.0 expands the platform-native primitive compiler with the first wave of additional APM harness targets, introduces a canonical --target install selector, and ships a multi-feature phase-advancement fix.

Highlights

Wave 1 APM targets: Cursor, OpenCode, Agent Skills

The primitive compiler now emits target-native assets for three additional harnesses alongside the existing Copilot and Claude targets:

• cursor — installs Cursor rules and writes .cursor/mcp.json.
• opencode — installs OpenCode assets and writes opencode.json.
• agent-skills — installs the shared .agents/skills bundle in isolation (no harness-specific config).

Each target has a registered native compiler, install paths, MCP config writer, and regression coverage.

Canonical --target install selector

specky install --target=<targets> is now the canonical, APM-aligned way to choose a harness. The legacy --ide flag remains as a deprecated alias for backward compatibility.

specky install --target=copilot      # VS Code + GitHub Copilot
specky install --target=claude       # Claude Code
specky install --target=cursor       # Cursor
specky install --target=opencode     # OpenCode
specky install --target=agent-skills # Shared .agents/skills bundle

specky compile --target=<targets> compiles instruction primitives into root context files (.github/copilot-instructions.md, CLAUDE.md, or AGENTS.md).

Doctor and governance updates

specky doctor now validates installed targets[] metadata instead of assuming Copilot/Claude IDE scopes. The APM manifest and policy use canonical target names and add Cursor/OpenCode target isolation checks. Copilot-inclusive installs strip Claude hooks from .claude/settings.json to prevent Copilot hook cross-read blocks.

Multi-feature phase-advancement fix

Artifact validation during phase advancement now uses the requested feature number instead of always validating state.features[0], fixing incorrect gating in multi-feature workspaces.

specky- primitive namespacing

All APM primitives are now namespaced with a specky- prefix — agents, skills, and hook scripts (prompts already carried the prefix). This prevents collisions with primitives shipped by other packages installed in the same workspace. Agent mentions change accordingly (for example @spec-engineer becomes @specky-spec-engineer). The Copilot instruction primitive keeps its reserved .github/copilot-instructions.md filename so Copilot continues to auto-load it.

Validation

• npm run audit passed.
• npm run build passed.
• npm test passed.
• specky apm verify-lock passed.
• npm pack --dry-run includes the APM manifest, lockfile, and policy file.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

For project-local installs:

npm install --save-dev specky-sdd@latest
npx specky upgrade

Full details: CHANGELOG.md

Specky 3.7.3 — APM governance layer

Copy-paste body for the GitHub Release v3.7.3.

Specky now ships a first-class APM governance layer on top of the platform-native primitive compiler introduced in 3.7.2.

Highlights

APM package governance

The package now includes governance files alongside the canonical .apm primitive source:

• apm.yml declares the package name, version, primitive source paths, supported harness targets, and Specky MCP runtime.
• apm.lock.yaml pins SHA256 hashes for the packaged primitive and governance files.
• apm-policy.yml enforces MCP allowlists, allowed hook events, and per-harness tool-name isolation.

New specky apm commands

Maintainers and CI can validate the package before publishing or installing:

specky apm validate      # validate apm.yml against package.json and primitive paths
specky apm lock          # write apm.lock.yaml with SHA256 per primitive
specky apm verify-lock   # diff current primitives against apm.lock.yaml
specky apm policy        # enforce apm-policy.yml governance rules
specky apm audit         # run the primitive frontmatter/tool audit
specky apm sbom          # emit a CycloneDX SBOM for packaged primitives

Build and package checks

npm run build now checks apm.yml name/version parity with package.json before compiling. npm pack --dry-run includes the APM manifest, lockfile, policy file, and compiled specky apm command/modules.

Validation

• npm run build passed.
• specky apm validate passed.
• specky apm policy passed.
• specky apm verify-lock passed.
• specky apm sbom emitted CycloneDX with 65 primitive/governance components.
• npm test passed: 38 test files, 355 tests.

Upgrade

npm install -g specky-sdd@latest
cd your-project
specky upgrade

For project-local installs:

npm install --save-dev specky-sdd@latest
npx specky upgrade

Full details: CHANGELOG.md

Users of old versions now find out — without the server ever phoning home.
Until now, someone on 3.4.0 had no way to learn that 3.7.0 existed, and a
project whose .mcp.json pinned an old server stayed old even after
npm install -g specky-sdd@latest. 3.7.0 closes both gaps.

Highlights

🔔 Version-drift advisory (always on, zero network)

specky doctor, specky status, and the MCP server at startup compare the
workspace's installed assets (.specky/install.json) against the running
version and nudge:

[specky] Installed assets are v3.5.0 but this server is v3.7.0 — run `specky upgrade` to refresh.

Local file comparison only — no network, stderr only, never blocks startup.
This catches the most common case: the global CLI was updated but the project's
pinned server/assets were not.

📬 Once-daily update banner (CLI only, opt-out)

After install, doctor, status, upgrade, or --version, the CLI checks
the npm registry at most once per day (2s timeout, silent offline) and prints:

Update available: specky-sdd v3.6.0 → v3.7.0  →  npm install -g specky-sdd@latest && specky upgrade

Honesty rules, enforced in code:

• Never runs in specky serve — the MCP server keeps making zero
  outbound calls, as promised.
• Disabled automatically in CI (CI=true).
• Opt out anytime: SPECKY_NO_UPDATE_CHECK=1 or update_check: false in
  .specky/config.yml.
• No telemetry — nothing is sent beyond the single HTTP GET.

📚 "Staying up to date" docs

README now covers the full menu: the banner, the one-command upgrade (and why
specky upgrade matters — it re-pins .mcp.json), Renovate/Dependabot for
teams pinning per-project, and GitHub Watch → Custom → Releases for release
e-mails. SECURITY.md discloses the exact network behavior.

Why not silent auto-update?

Deliberate choice: a floating @latest server would run any compromised
release instantly on every machine. Specky pins the server version per project
(supply-chain safety) and notifies loudly + upgrades in one command instead
of updating silently.

Install / upgrade

npm install -g specky-sdd@latest   # 3.7.0
cd your-project && specky upgrade  # refreshes assets, re-pins the server

Full details: CHANGELOG.md