sdd

Spec-Driven Development toolkit for AI agents.

Install battle-tested SDD skills into Claude Code, Cursor, GitHub Copilot, Gemini CLI, Antigravity, and Kiro — in seconds.

imagenpm version imagenpm downloads imageCI imageLicense: MIT imageNode.js ≥22

npx @ghcordeiro/sdd

What is this?

sdd installs a curated set of AI agent skills for Spec-Driven Development — spec-driven planning, architecture documentation, ADR creation, C4 diagrams, code quality review, RFC writing, and more.

All skills are installed at once, as a single toolkit. No picking and choosing — just run, select your agent, and get to work.

Each skill is a self-contained SKILL.md file that gives your AI agent deep, specialized knowledge. Plain Markdown. No cloud dependency. No lock-in.

Quick Start

npx @ghcordeiro/sdd

The interactive CLI walks you through three steps:

──────────────────────────────────────────
 ◆ SDD
   Spec-Driven Development toolkit for AI agents
──────────────────────────────────────────

  step 1 of 3 · Select agents
  ━━━━━━━━━━━━━──────────────────────────

  Which AI agent(s) do you use?

  › ○  Claude Code
    ○  Cursor
    ○  GitHub Copilot
    ○  Gemini CLI
    ○  Antigravity
    ○  Kiro

  ↑↓ navigate  ·  space toggle  ·  a select all  ·  enter confirm

  step 2 of 3 · Install scope
  ━━━━━━━━━━━━━━━━━━━━━━━━━━─────────────

  Where should spec-driven be installed?

  › ◉  Global    available across all your projects
    ○  Local     this project only

  step 3 of 3 · Confirm
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Ready to install spec-driven

  Agent  Gemini CLI
  Scope  Global
         ~/.gemini/skills

  › Enter to install     c to cancel

  ✓ spec-driven installed
  → ~/.gemini/skills

Non-interactive (scripts & CI)

npx @ghcordeiro/sdd install \
  --agent claude-code \
  --skills spec-driven \
  --global

You can always inspect the full CLI help with:

npx @ghcordeiro/sdd --help

Supported Agents

Kiro Power (install from the repo link)

This repository is also a Kiro Power — no CLI needed:

1. Open the Powers panel in Kiro
2. Add Custom Power → Import power from GitHub
3. Paste https://github.com/ghcordeiro/sdd and click Install

The power manifest is plugin.json at the repo root; the skill lives in skills/spec-driven/, and mcp.json adds the Context7 MCP server.

Learning & Companion Tools

Cross-project learnings

spec-driven learns how you work and carries it across projects. It keeps a plain Markdown file at ~/.sdd/LEARNINGS.md with your preferences, stack and code patterns, mistakes to avoid, and an index of your projects.

• Read at the start of Specify, Plan, and when resuming work.
• Written at every phase gate, whenever you correct the agent, and when a decision reflects a general preference.
• Project-only memory stays in .specs/project/STATE.md.

The file needs no extra tooling, and it never stores secrets or credentials. Edit or delete entries any time.

Recommended companions

sdd detects these and shows how to install them. It never installs or configures them for you. The skill uses each one when it is available.

Skills Included

🧭 Built-in workflows (loaded on demand)

spec-driven is a small router: each workflow below is a separate file loaded only when its trigger fires. If your agent already has an equivalent skill (e.g. systematic-debugging, security-review, using-git-worktrees), the host skill is used instead and the sdd file is never loaded.

🏗️ Planning & Architecture

📋 Decision & Documentation

🔍 Code Quality

🌐 Web & Frontend

⚙️ Tooling & Automation

Repository Structure

sdd/
├── plugin.json               # Kiro Power manifest (Agent Plugins format)
├── mcp.json                  # Kiro Power MCP servers (Context7)
├── skills/
│   └── spec-driven/          # the skill — SKILL.md + embedded toolkit/
├── packages/
│   └── cli/                  # @ghcordeiro/sdd — CLI publicado no npm
│       ├── src/              # TypeScript source (Ink + Commander)
│       └── build.mjs         # esbuild bundler script
├── libs/
│   └── core/                 # shared logic (catalog, installer, agent definitions)
├── .github/workflows/
│   ├── ci.yml                # type-check on every push to main
│   └── publish.yml           # semantic-release on push to main (npm Trusted Publishing)
├── package.json              # npm workspaces root
└── nx.json

Contributing

Adding a new skill

1. Create a new directory under skills/<skill-name>/
2. Add a SKILL.md with YAML frontmatter (name, description, license)
3. Open a pull request — the skill is automatically included in the next release

Publishing a new version

# Preview release result locally (optional)
npm run release:dry-run

Releases are fully automated with semantic-release on every push to main. It automatically:

• analyzes Conventional Commits (feat, fix, BREAKING CHANGE)
• calculates the next version
• updates packages/cli/package.json + package-lock.json + plugin.json (Kiro Power)
• creates CHANGELOG.md
• creates git tag + GitHub release
• publishes @ghcordeiro/sdd to npm with provenance

Examples:

• fix: ... → patch release
• feat: ... → minor release
• feat!: ... or BREAKING CHANGE: → major release

npm authentication — Trusted Publishing (OIDC)

There is no npm token in this repo. publish.yml authenticates to npm with Trusted Publishing: GitHub Actions exchanges a short-lived OIDC token with the registry on each run.

Rules:

• Do not add NPM_TOKEN / NODE_AUTH_TOKEN, and do not set registry-url in actions/setup-node — both switch npm back to token auth.
• The trusted publisher is bound to the filename publish.yml. Renaming the workflow or the npm environment breaks publishing until the npm setting is updated.
• Publishing access can stay on "Require two-factor authentication and disallow bypass 2fa tokens" — trusted publishers keep working.

Recovering a release that tagged but did not publish

If semantic-release created the tag but npm publish failed, the next push will not retry it (the tag already exists). Publish the existing tag from Actions:

gh workflow run publish.yml -f tag=vX.Y.Z

This checks out the tag, publishes it to npm with provenance, and creates the GitHub release if missing.

Troubleshooting release

• npm ci fails with lockfile mismatch:
  • run npm install locally to sync package-lock.json
  • commit package-lock.json before tagging
• ENONPMTOKEN / EINVALIDNPMTOKEN / EOTP:
  • npm is not using OIDC — check the trusted publisher settings above and that no token or registry-url was added to the workflow
• provenance/repository mismatch (E422):
  • ensure packages/cli/package.json repository.url points to the same GitHub repo used by Actions
• publish workflow not triggered:
  • ensure commit was pushed to main
  • ensure commit follows Conventional Commits so semantic-release can determine a version bump

Inspiration & Credits

This project's spec-driven skill is inspired by prior work from the community and published references on Spec-Driven Development.

Original work

• tlc-spec-driven by Felipe Rodrigues — Tech Lead's Club
• Source: tech-leads-club/agent-skills
• License: CC-BY-4.0

SDD references

• Martin Fowler — Spec-Driven Development: 3 Tools
• DS Academy — Spec-Driven Development series (parts 1-5)
• Microsoft Learn — Spec-Driven Development with GitHub Spec Kit

Toolkit skill provenance

License

MIT — see LICENSE.

Individual skills may carry their own licenses — check each skill's directory for details.