Stop making agents guess.

Spec-driven development for AI coding agents. SpecD compiles the right specs into agent context, verifies plans against requirements before implementation, and helps prevent drift before code ships.

Context is delivered, not discovered. Compliance is structural, not optional. For more information, visit getspecd.dev.

Why SpecD?

AI coding agents often fail for repeatable reasons:

• They miss relevant requirements.
• They lose context across long tasks.
• They drift from specifications during implementation.

SpecD addresses this by combining:

• Compiled context for agents. The right specs and lifecycle instructions are assembled before the agent starts work.
• Structured verification and approval guardrails. Mandatory verification reduces drift during the lifecycle, while optional human approval checkpoints can gate progression at key transitions.
• Spec and code graph impact analysis. SpecD connects specs, source files, symbols, and dependencies so agents can reason about change impact.
• Deterministic where correctness matters. Merging, validation, status resolution, and delta application are computed by SpecD instead of delegated to the LLM.

Minimal workflow

npm install -g @specd/specd

Initialize a project (wizard guides you through plugin selection):

# CLI
specd project init

Run skill on your coding agent:

# Coding agent
/specd

Invokes the SpecD skill, inspects project state, and routes to the next workflow step (for example creating or continuing a change).

What is SpecD?

AI coding assistants work best when given clear, structured intent. Spec-Driven Development (SDD) addresses this by inserting a spec layer between human intent and AI-generated code: requirements are written, validated, and agreed upon before implementation begins.

SpecD is a ground-up redesign of that workflow, built for professional teams. It models specs, changes, schemas, and hooks as first-class domain concepts — independent of any particular AI tool or delivery mechanism. The same business logic is exposed through a CLI, an MCP server, and agent plugins, all consuming a single core library with no I/O dependencies.

Key differences from earlier SDD tools:

• Context compiled, not discovered. At every lifecycle step, SpecD computes which specs are relevant to the current change and delivers their content as a structured, ready-to-consume block. The agent does not decide what to read; SpecD resolves it.
• Code graph built in. SpecD indexes your codebase and specs into a queryable graph, enabling impact analysis (upstream/downstream reach), hotspot detection, and change-aware queries. Multi-language: TypeScript, Go, Python, PHP (more languages coming).
• Deterministic where correctness matters. Spec merging, validation, status resolution, and delta application are computed algorithmically — not delegated to the LLM.
• Customizable schema model. A default schema is included, while projects can define their own artifact workflow, section structure, and dependency order in schema.yaml. SpecD does not hardcode any particular convention.
• Composable packages. Use only what you need: the core library as an SDK, the CLI for terminal workflows, the MCP server for agent-native workflows, or the full stack.
• Lifecycle hooks. Shell commands and AI instructions are attached to state transitions (pre/post), enabling lint gates, test runs, notifications, and step-specific agent guidance without leaving the workflow.
• Structured verification and approval guardrails. Mandatory verification is built into the lifecycle, while optional human approval checkpoints can govern progression at critical transitions.
• Multi-workspace and coordinator repos. A project can declare multiple spec workspaces, each pointing to a different directory or repository. A single coordinator repo can govern specs across an entire microservice architecture without coupling service repos to each other.

Current status (April 2026)

SpecD is in active development and installable from npm.

• @specd/specd — convenience metapackage that installs the full SpecD stack
• @specd/core — business logic layer: change lifecycle, spec management, schema validation, delta application, context compilation, hooks, storage adapters
• @specd/cli — complete command surface: change, spec, project, schema, skills, graph, plugins, drafts, discarded, archive, config
• @specd/code-graph — multi-language indexing (TypeScript, Go, Python, PHP), impact analysis, hotspot detection, staleness detection
• @specd/skills — skill registry API with bundle resolution and multiple agent runtime support
• @specd/plugin-* — agent plugins (claude, copilot, codex, opencode, standard) implemented per spec
• @specd/plugin-manager — plugin loader, install/update/uninstall use cases
• @specd/schema-std — ships a real schema.yaml and template files
• @specd/mcp — in progress (stub)
• @specd/public-web — in progress (Docusaurus site with landing page and docs)

Install from npm:

npm install -g @specd/specd

Or run without global install:

npx @specd/cli --help

Core concepts

The change lifecycle progresses through well-defined states:

drafting → designing → ready → implementing ⇄ verifying → done → archivable

Optional approval checkpoints can require human sign-off between ready → implementing and done → archivable.

Context compilation

Most SDD tools give the agent a list of files and leave it to figure out which specs are relevant. SpecD takes a different approach: at every lifecycle step, specd context computes and delivers the full instruction block the agent needs.

The resolution works in five steps:

1. Project-level include patterns — which specs always apply to every change in this project.
2. Project-level exclude patterns — specs explicitly excluded from context.
3. Workspace-level include/exclude patterns — applied only for workspaces active in the current change.
4. dependsOn traversal — starting from the specs a change touches, SpecD follows declared dependencies transitively to pull in related specs automatically.
5. Assembly — for each resolved spec, SpecD injects structured metadata (rules, constraints, scenarios) when available, with a raw-content fallback when metadata is stale or absent.

The output is a single, ordered instruction block combining project context, schema instructions for the active artifact, spec content, and lifecycle hooks — ready to inject into the agent's context window. The agent doesn't search, doesn't guess, and doesn't miss a spec that wasn't mentioned by name.

Structured verification and approval guardrails

The most common failure mode in spec-driven development is not writing bad specs — it is that agents plan and implement without fully respecting them. An agent reads the specs, generates a design and task list, then produces code that diverges from the requirements. The gap surfaces during verification or review, after the work is done.

SpecD addresses this with mandatory verification built into the lifecycle, plus optional human approval guardrails around critical transitions:

designing → ready → [optional approval] → implementing ⇄ verifying → done → [optional approval] → archivable

Verification (mandatory): after implementation, the agent enters the verifying step, where a dedicated verification skill checks the implementation against the relevant specs and may send the change back for revision when drift or contradictions are detected.

Approval checkpoints (optional): projects may require a design approval gate before implementation (ready → implementing) to review scope, affected specs, and design decisions, and/or an implementation approval gate before archiving (done → archivable) to review correctness, catch omissions discovered late, reconsider flawed or incomplete approaches, or reopen the change when the implementation or spec changes need adjustment before specs and deltas are merged. These checkpoints are deterministic workflow gates controlled by project policy.

This separates verification from governance: verification is always part of the lifecycle, while approvals are an optional control layer.

This turns spec conformance review into a first-class lifecycle concern, while allowing teams to add human governance where needed.

Hooks

Hooks attach automated actions or AI guidance to lifecycle transitions. They are defined in the schema's workflow section and extended in specd.yaml via schemaOverrides.

• Pre hooks run before entering a step — failure blocks the transition.
• Post hooks run after entering a step — failure does not roll back the state.

Two hook types are supported:

workflow:
  - step: implementing
    hooks:
      pre:
        - id: run-lint
          run: pnpm lint
      post:
        - id: notify
          run: echo "Implementation started for {{change.name}}"

Hook run: commands support template variables ({{change.name}}, {{change.workspace}}, {{change.path}}, {{project.root}}). Schema-level hooks fire first, then project-level overrides, in declaration order.

Multi-workspace projects

A SpecD project can declare multiple workspaces, each with its own spec tree, storage path, and code root. Workspaces can point to directories inside the same repository or to external repositories entirely.

This enables a coordinator pattern: a single repo holds the specs for an entire system, while each service repo maintains its own codebase. Context compilation is workspace-aware — when a change touches specs in multiple workspaces, include/exclude patterns and dependsOn traversal are applied per-workspace, and only the active workspaces contribute to the compiled context.

Teams with microservice architectures can manage cross-cutting specs (authentication contracts, API schemas, shared conventions) in one place, without forcing every service repo to carry a full SpecD installation.

Packages

Getting started (CLI)

Use as a CLI

Install globally (npm):

npm install -g @specd/specd

Install globally (pnpm):

pnpm add -g @specd/specd

Initialize a project (wizard guides you through plugin selection):

specd project init

Then launch your agent and run the skill:

/specd

Develop on specd

Requirements

• Node.js >= 20
• pnpm >= 10

Install dependencies and run quality checks:

pnpm install
pnpm build
pnpm test
pnpm lint

Build and run the CLI from source:

pnpm --filter @specd/cli build
node packages/cli/dist/index.js --help

Preview the public website locally:

pnpm web:dev

This starts the Docusaurus app in apps/public-web and serves the site locally, typically at http://localhost:3000. Development mode intentionally skips the generated API reference so the dev server does not watch hundreds of generated Markdown files.

Useful routes to check:

• / — presentation landing page
• /docs — public guides and reference docs
• /api — generated API reference for @specd/core in production preview builds

To preview the production output instead of the dev server:

pnpm web:build
pnpm web:serve

Example command groups currently wired:

• specd change ...
• specd spec ...
• specd project ...
• specd config show
• specd schema show
• specd graph ...
• specd skills ...

project init can generate a local specd.yaml. A minimal config looks like:

schema: '@specd/schema-std'

workspaces:
  default:
    specs:
      adapter: fs
      fs:
        path: specs/

storage:
  changes:
    adapter: fs
    fs:
      path: specd/changes
  drafts:
    adapter: fs
    fs:
      path: specd/drafts
  discarded:
    adapter: fs
    fs:
      path: specd/discarded
  archive:
    adapter: fs
    fs:
      path: specd/archive

See the configuration reference for all available options.

Documentation

Start here:

Reference:

Development model

This repository follows a spec-driven workflow: each significant area of behavior is specified in specs/ before implementation begins.

License

MIT — see LICENSE.