KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

spec-driven-workflow

★ 87 Open GitHub ↗

Lightweight markdown-based workflow for collaborating with AI coding assistants using spec-driven development methodology

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
    <img src="./misc/sdd-workflow-hero.png" alt="Spec-Driven Development workflow from idea to verified delivery" width="900"/>
    <h1>🧭 Spec-Driven Development Workflow</h1>
    <h3><em>Build predictable software with a repeatable AI-guided workflow.</em></h3>
</div>

<p align="center">
    <strong>A skill-first spec-driven development workflow for collaborating with AI agents to deliver reliable outcomes.</strong>
</p>

> [!IMPORTANT]
> **SDD is now skill-first.** If you previously installed SDD as separate `/SDD-*` slash-command prompts, migrate to the recommended `sdd` skill so your agent can route through the right workflow phase from repository state. Start with the [migration guide](./MIGRATION.md), or update an existing skill install with `npx skills update sdd --yes`.

## Overview

This repository provides a **primary agent skill** plus **structured prompt files** that guide AI assistants through a complete software development workflow:

- **Define intent**: generate a reviewed spec with clear demo criteria
- **Plan**: break work into demoable tasks and subtasks, then run a planning audit gate
- **Execute**: implement with checkpoints and proof artifacts
- **Validate**: verify implementation against the spec with evidence

Think of the skill and the prompt files that power it as reusable playbooks that keep AI agents focused and consistent across long conversations.

## Table of Contents

- [TLDR / Quickstart](#tldr--quickstart)
- [Migrating from prompt-based installs](#migrating-from-prompt-based-installs)
- [Details for the 4-step workflow](#details-for-the-4-step-workflow)
- [Artifacts and directory layout](#artifacts-and-directory-layout)
- [Documentation](#documentation)
- [Context verification markers](#context-verification-markers)
- [Security best practices](#security-best-practices)
- [Contributing](#contributing)
- [References](#references)
- [License](#license)

## TLDR / Quickstart

### Installation options

#### Option A: Install as Agent Skill (Recommended)

Install `skill/` when your AI assistant supports skill folders or skill-native workflows. This is the primary recommended path because the single `sdd` skill can reassess repository state, load the right phase reference, and continue from persisted artifacts without making users remember four separate phase commands.

Install the SDD skill using the [`skills.sh`](https://skills.sh) CLI:

```bash
# List available skills in this repository without installing
npx skills add liatrio-labs/spec-driven-workflow --list

# Install the SDD skill
npx skills add liatrio-labs/spec-driven-workflow --skill sdd

# Install the SDD skill non-interactively
npx skills add liatrio-labs/spec-driven-workflow --skill sdd --yes

# Install to specific agents
npx skills add liatrio-labs/spec-driven-workflow --skill sdd -a cursor -a codex

# Install globally instead of project scope
npx skills add liatrio-labs/spec-driven-workflow --skill sdd --global

# Update an existing SDD skill install
npx skills update sdd --yes
```

The SDD skill is explicit-invocation only: users should intentionally invoke it through their agent harness, such as `/sdd` or `$sdd`. It is not designed to be dynamically loaded or automatically triggered by the agent. Once explicitly invoked, the skill router reassesses the workspace, loads the correct SDD phase reference, and continues from persisted artifacts in `docs/specs/`.

Compatibility notes:

- Agent support for skills and allowed tools varies by agent harness.
- Use `DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1` to opt out of telemetry when running the `skills.sh` CLI.

#### Option B: Install as Slash Commands

Use `prompts/` as slash commands when your assistant does not support skills or when your team specifically wants separate phase commands. Install these prompts as native `/slash-commands` in your AI assistant (Cursor, Windsurf, Claude Code, etc.) using the [slash-command-manager](https://github.com/liatrio-labs/slash-command-manager) utility:

**Prerequisite:** `uvx` comes from [uv](https://docs.astral.sh/uv/getting-started/installation/). Ensure it is installed first:

- (Mac & Linux): `brew install uv`
- (Windows): `winget install astral-sh.uv`

##### Install SDD w/ Bash (Mac)

```bash
uvx --from git+https://github.com/liatrio-labs/slash-command-manager \
  slash-man generate \
  --github-repo liatrio-labs/spec-driven-workflow \
  --github-branch main \
  --github-path prompts/
```

##### Install SDD w/ PowerShell (Windows)

```ps
uvx --from git+https://github.com/liatrio-labs/slash-command-manager `
  slash-man generate `
  --github-repo liatrio-labs/spec-driven-workflow `
  --github-branch main `
  --github-path prompts/
```

**What this command does:**

- `uvx` runs a Python tool without installing it globally (like `npx` for Python)
- Fetches the `slash-command-manager` tool from GitHub
- Auto-detects your installed AI assistants from the list of supported tools
- Downloads the prompt files for each supported tool from the `prompts/` directory
- Installs them as slash commands for each supported tool

**Result:** you can now type `/SDD-1-generate-spec` in your AI assistant to start the prompt-command workflow.

**Where to use the slash commands:** in AI chat UIs (e.g., Windsurf, Claude Code) type `/` in the chat input. Some AI assistants require being in "Agent" or "Code" mode for slash commands to appear.

#### Option C: Manual Copy-Paste (No Installation)

Copy the contents of a prompt file directly from `prompts/` and paste it into your AI chat. The AI will follow the structured instructions in the prompt.

## Migrating from prompt-based installs

If you previously installed SDD as separate `/SDD-*` slash-command prompts, migrate to the recommended `sdd` skill when your agent supports skills. Existing project artifacts in `docs/specs/` do not need to be converted; the skill reads the same artifact structure and routes to the right phase from repository state.

See [`MIGRATION.md`](./MIGRATION.md) for step-by-step migration, update, and cleanup instructions.

### Quick "try it" flow

For the recommended skill install, explicitly invoke the skill via your agent harness, usually `/sdd`. In Codex, use `$sdd`. You can supply a feature/idea/task along with the invocation, or invoke the skill without extra detail and let its internal router detect the appropriate SDD phase from persisted artifacts. Here are some example invocations:

- `/sdd review issue #123 and start creating a spec for it`
- `/sdd generate tasks for the latest spec`
- `/sdd run a validation for the latest spec`

Or just invoke the skill with `/sdd` and let the skill guide you through the appropriate phase based on the repo context.

For slash-command installs, invoke each step individually:

1. Run `/SDD-1-generate-spec` and describe the feature you want. If the AI determines material clarification is needed, answer the generated questions file before continuing.
2. Next, use `/SDD-2-generate-task-list-from-spec` pointing it at the generated spec; complete task generation, baseline planning commit, planning audit, and user-approved remediation if needed.
3. Then execute `/SDD-3-manage-tasks` to implement tasks one at a time (creating proof artifacts before commits) after the SDD-2 audit required gates pass.
4. Finally, apply `/SDD-4-validate-spec-implementation` to verify the implementation against the spec.

## Details for the 4-step workflow

Each phase is available through the recommended `sdd` skill router and, for slash-command installs, through an equivalent prompt file. The workflow produces specific artifacts in `docs/specs/`.

1. **Generate a spec** ([`prompts/SDD-1-generate-spec.md`](./prompts/SDD-1-generate-spec.md))
   - **What it does**: checks scope, researches current best practices for relevant technologies, determines whether clarification is needed, optionally creates a questions file for material ambiguities with recommended answers and justification notes, and writes a junior-friendly spec with demo criteria
   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md` and, when needed, `docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md`
   - **Why**: aligns humans + AI on what to build before any code changes

2. **Generate a task list** ([`prompts/SDD-2-generate-task-list-from-spec.md`](./prompts/SDD-2-generate-task-list-from-spec.md))
   - **What it does**: converts the spec into parent tasks (demoable units) + detailed subtasks, creates a baseline planning commit, runs a planning audit gate, and requires user-approved remediation before implementation handoff
   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` and `docs/specs/[NN]-spec-[feature-name]/[NN]-audit-[feature-name].md`
   - **Why**: catches planning defects early and improves downstream validation readiness

3. **Manage tasks (implementation loop)** ([`prompts/SDD-3-manage-tasks.md`](./prompts/SDD-3-manage-tasks.md))
   - **What it does**: guides execution with checkpoints, verification checklists, and proof artifacts created **before** each commit
   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/[NN]-task-[TT]-proofs.md`
   - **Why**: keeps work single-threaded, demoable, and evidence-driven

4. **Validate implementation** ([`prompts/SDD-4-validate-spec-implementation.md`](./prompts/SDD-4-validate-spec-implementation.md))
   - **What it does**: validates implementation vs spec using proof artifacts, applies validation gates, produces a coverage matrix
   - **Output**: validation report (markdown) showing verified/missing items
   - **Why**: confirms completeness before shipping

5. **SHIP IT** 🚢💨

## Highlights

- **Skill-first workflow:** Use the `sdd` skill to route from idea → spec → task list → implementation-ready backlog, with prompt files available for assistants that need slash/custom prompts.
- **Planning quality gate:** SDD-2 includes a mandatory audit with human-approved remediation before implementation starts.
- **Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind.
- **Flexible install paths:** Install the skill for skill-native agents first; use prompt files when slash/custom prompt support is the better fit.
- **Context verification:** Built-in emoji markers (SDD1️⃣-SDD4️⃣) detect when AI responses follow critical instructions, helping identify context rot issues early.

## Why Spec-Driven Development?

Spec-Driven Development (SDD) keeps AI collaborators and human developers aligned around a shared source of truth. This repository provides a lightweight, skill-first workflow that turns an idea into a reviewed specification, an actionable plan, and a disciplined execution loop. By centering on markdown artifacts instead of heavy platform tooling, the workflow travels with you—across projects, models, and collaboration environments.

## Guiding Principles

- **Clarify intent before delivery:** The spec prompt requires a clarification sufficiency check so material ambiguities are resolved before planning, while minor uncertainty can remain explicit in the spec.
- **Ground plans in current guidance:** The spec prompt combines repository pattern discovery with current external best-practice research for material technologies, then asks follow-up questions when those signals still leave meaningful choices open.
- **Ship demoable slices:** Every stage pushes toward thin, end-to-end increments with clear demo criteria and proof artifacts.
- **Make work transparent:** Tasks live in versioned markdown files so stakeholders can review, comment, and adjust scope anytime.
- **Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress.
- **Stay automation ready:** While SDD works with plain Markdown, the skill and prompts are structured for MCP, IDE agents, or other AI integrations.

## Artifacts and directory layout

Each SDD run writes Markdown outputs into `docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.), giving you a lightweight backlog that is easy to review, share, and implement.

- **Specs:** `docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md`
- **Questions files (when needed):** `docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md`
- **Task lists:** `docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md`
- **Audit reports:** `docs/specs/[NN]-spec-[feature-name]/[NN]-audit-[feature-name].md`
- **Proof artifacts:** `docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/[NN]-task-[TT]-proofs.md`
- **Validation reports:** `docs/specs/[NN]-spec-[feature-name]/[NN]-validation-[feature-name].md`

Example directory structure:

`[NN]-questions-[N]-[feature-name].md` is optional and appears only when the spec prompt determines a clarification round is required.

```bash
docs/specs
└── 01-spec-feature-name
    ├── 01-proofs
    │   ├── 01-task-01-proofs.md
    │   ├── 01-task-02-proofs.md
    │   ├── 01-task-03-proofs.md
    │   └── 01-task-04-proofs.md
    ├── 01-questions-1-feature-name.md
    ├── 01-audit-feature-name.md
    ├── 01-spec-feature-name.md
    ├── 01-tasks-feature-name.md
    └── 01-validation-feature-name.md
```

## Documentation

For comprehensive documentation, examples, and detailed guides, visit the **SDD Playbook**:

- **[SDD Playbook](https://liatrio-labs.github.io/spec-driven-workflow/)** — Complete overview and workflow guide
- **[Comparison](https://liatrio-labs.github.io/spec-driven-workflow/comparison.html)** — How SDD compares to other structured development tools
- **[Developer Experience](https://liatrio-labs.github.io/spec-driven-workflow/developer-experience.html)** — Real-world usage examples and patterns
- **[Common Questions](https://liatrio-labs.github.io/spec-driven-workflow/common-questions.html)** — FAQ and troubleshooting
- **[Video Overview](https://liatrio-labs.github.io/spec-driven-workflow/video-overview.html)** — Visual walkthrough of the workflow
- **[Reference Materials](https://liatrio-labs.github.io/spec-driven-workflow/reference-materials.html)** — Additional resources and examples

To preview the playbook locally with hot reload, run:

```bash
uvx livereload --port 8012 docs/
```

Then open `http://localhost:8012`.

### Getting help

- **Start here**: [Common Questions](https://liatrio-labs.github.io/spec-driven-workflow/common-questions.html)
- **Ask/Report**: open a GitHub Issue in this repo with details about your environment + prompt/tooling

## Context verification markers

Each prompt includes a context verification marker (SDD1️⃣ for spec generation, SDD2️⃣ for task breakdown, SDD3️⃣ for task management, SDD4️⃣ for validation) that appears at the start of AI responses. These markers help detect **context rot**—a phenomenon where AI performance degrades as input context length increases, even when tasks remain simple.

**Why this matters:** Context rot doesn't announce itself with errors. It creeps in silently, causing models to lose track of critical instructions. When you see the marker at the start of each response, it's an <strong>indicator</strong> that the AI is probably following the prompt's instructions. If the marker disappears, it's an immediate signal that context instructions may have been lost.

**What to expect:** You'll see responses like `SDD1️⃣ I'll help you generate a specification...` or `SDD3️⃣ Let me start implementing task 1.0...`. This is normal and indicates the verification system is working. For more details, see the [research documentation](docs/emoji-context-verification-research.md).

## Security Best Practices

### Protecting Sensitive Data in Proof Artifacts

Proof artifacts are committed to your repository and may be publicly visible. **Never commit real credentials or sensitive data.** Follow these guidelines:

- **Replace credentials with placeholders**: Use `[YOUR_API_KEY_HERE]`, `[REDACTED]`, or `example-key-123` instead of real API keys, tokens, or passwords
- **Use example values**: When demonstrating configuration, use dummy or example data instead of production values
- **Sanitize command output**: Review CLI output and logs for accidentally captured credentials before committing
- **Consider pre-commit hooks**: Tools like [gitleaks](https://github.com/gitleaks/gitleaks), [truffleHog](https://github.com/trufflesecurity/truffleHog), or [talisman](https://github.com/thoughtworks/talisman) can automatically scan for secrets before commits

The SDD skill and prompt files include built-in reminders about security, but ultimate responsibility lies with the developer to review artifacts before committing or pushing to remotes.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Please review [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

## References

| Reference | Description | Link |
| --- | --- | --- |
| AI Dev Tasks | Foundational example of an SDD workflow expressed entirely in Markdown. | [snarktank/ai-dev-tasks](https://github.com/snarktank/ai-dev-tasks) |
| Slash Command Manager | Utility for installing prompts as slash commands in AI assistants. | [liatrio-labs/slash-command-manager](https://github.com/liatrio-labs/slash-command-manager) |
| skills.sh | CLI for installing repository skills into skill-native AI assistant workflows. | [skills.sh](https://skills.sh) |
| MCP | Standard protocol for AI agent interoperability. | [modelcontextprotocol.io](https://modelcontextprotocol.io/docs/getting-started/intro) |

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

spec-driven-workflow

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README