SpecKit for Projects

SpecKit for Projects is a lightweight CLI plus scaffold bundle for design-driven development in SI-style projects. It keeps the executable surface area small and moves most document generation into AI workflows backed by repository-managed prompts, skills, and templates.

SpecKit for Projects Official example

https://github.com/yatarousan0227/vibe-todo

Why This Exists

Many teams want design artifacts to be regenerable, reviewable, and consistent across features, but they do not want a large framework or a document generator that owns too much of the process.

SpecKit for Projects focuses on a narrower role:

initialize a repository with the required scaffold
install agent-facing prompts or skills for the AI tool you use
validate that the repository still has the files needed for the workflow

It does not try to replace the actual design work. The brief, clarify, common_design, specific_design, tasks, and implement steps are driven by the prompts and skills that sdd init installs.

Information Model

The workflow separates design truth into three layers:

project: repository-wide standards and shared constraints
common_design: shared API, data, module, and UI truth reused by multiple features
specific_design: feature-specific design derived from one brief

The relationship between those design artifacts looks like this:

flowchart TD
    A[project] --> B[common_design]
    A --> C[specific_design: feature A]
    B --> C
    A --> D[specific_design: feature B]
    B --> D
    C --> E[tasks.md]
    D --> F[tasks.md]

That split is the main guardrail. Shared truth lives once, and feature bundles reference it instead of copying it.

Current CLI Scope

The CLI currently exposes three commands:

sdd init
sdd check
sdd analyze

The rest of the workflow is executed through the installed agent prompts and skills:

sdd.brief
sdd.clarify
sdd.analyze
sdd.common-design
sdd.design
sdd.debug
sdd.tasks
sdd.implement
sdd.reflect

Responsibility split:

sdd check: validate scaffold, directory layout, agent command files, and runtime availability
sdd.clarify: tighten ambiguous requirements and shared design assumptions before design starts
sdd analyze: validate one or more generated specific_design bundles and report consistency issues
sdd.debug: fix a bug and synchronize impacted design artifacts and execution ledgers
sdd.reflect: reconcile design and task documents to the current working tree diff

Installation

SpecKit for Projects requires Python 3.12 or later. uv is the recommended workflow.

The distribution package name is speckit-for-projects. The CLI remains sdd, and the internal Python module path is speckit_for_projects.

The package name is reserved in project metadata, but this project is not yet published to a package index. For now, install and run it from a local checkout.

Run from source without installing globally:

uv sync --dev
uv run sdd --help

Install the local checkout as a CLI tool:

uv tool install --editable .
sdd --help

After the package is published to a package index, install by name:

uv tool install speckit-for-projects
sdd --help

If you want to validate the example Storybook bundles, Node.js and npm are also required.

Quick Start

Initialize the current repository for Codex:

sdd init --here --ai codex --ai-skills
sdd check --ai codex

Initialize a new directory:

sdd init my-project --ai claude

Initialize an API-only project:

sdd init --here --capabilities api

Initialize for a generic agent with a custom prompt directory:

sdd init --here --ai generic --ai-commands-dir .myagent/commands
sdd check --ai generic --ai-commands-dir .myagent/commands

After generating designs/specific_design/<design-id>/tasks.md, re-check the bundle:

sdd analyze <design-id>

What Gets Generated

sdd init prepares a repository with:

.specify/project/*.md for project-wide standards
.specify/project/scope.yaml for managed project capabilities
.specify/glossary.md
.specify/conventions/README.md
.specify/templates/commands/*.md for agent workflows
.specify/templates/artifacts/ for scaffolded deliverables
briefs/
designs/common_design/
designs/specific_design/

Capability-specific additions:

ui: designs/common_design/ui/, ui-fields.yaml, and ui-storybook/ scaffolds
api: designs/common_design/api/ and API shared-design scaffold
batch: batch-design.md scaffold

Control that with --capabilities <csv>. The current supported values are ui, api, and batch. When omitted, sdd init keeps the legacy full scaffold and behaves as if --capabilities ui,api,batch was used.

Optional with --project-design-system:

.specify/project/design-system.md
.specify/project/ui-storybook/

Typical outputs later created through the workflow:

briefs/<brief-id>.md
designs/common_design/data|module/*.md
designs/common_design/api/*.md when the project has api
designs/common_design/ui/*.md when the project has ui
designs/common_design/tasks.md
designs/specific_design/<design-id>/overview.md
designs/specific_design/<design-id>/common-design-refs.yaml
designs/specific_design/<design-id>/traceability.yaml
designs/specific_design/<design-id>/tasks.md

Standard Workflow

Run sdd init.
Run sdd check.
Fill .specify/project/*.md and .specify/glossary.md.
Generate one brief with sdd.brief.
If the brief is still ambiguous, run sdd.clarify before design starts.
Generate shared design only when multiple features depend on the same truth.
Generate one specific_design bundle from one brief.
Generate tasks.md for either common_design or one specific_design bundle.
Run sdd analyze <design-id> or sdd analyze --all.
Use sdd.implement for planned task execution.
Use sdd.debug for defect-driven fixes that also need design/task synchronization.
Use sdd.reflect after manual code edits when the current diff is the source of truth.
Review the resulting diff.

`sdd init` Behavior

sdd init writes managed scaffold files only once by default.

existing managed files are kept on re-run
existing agent command files are kept on re-run
existing skills are kept on re-run
--force overwrites all of the above

The managed scope is stored in .specify/project/scope.yaml. sdd check uses that file to decide which capability-specific scaffold paths are required.

If the target directory does not already contain .git, sdd init also tries to run git init unless --no-git is specified.

`sdd check` Behavior

sdd check validates:

the shared scaffold under .specify/
required directories under briefs/ and designs/
agent-specific command files when --ai is specified
required local CLI runtime availability as a warning for agents that need one

Exit codes:

0: no warnings or failures
1: warnings only
2: one or more failures

`sdd analyze` Behavior

sdd analyze validates generated bundle consistency under designs/specific_design/.

sdd analyze <design-id>: analyze one bundle by ID
sdd analyze designs/specific_design/<design-id>: analyze one bundle by path
sdd analyze --all: analyze every bundle under designs/specific_design/

It checks:

required files inside the bundle, based on .specify/project/scope.yaml
traceability.yaml structure and references
tasks.md requirement coverage
common-design-refs.yaml structure and resolvability
brief-to-bundle requirement and shared design alignment when the matching brief exists

Exit codes:

0: all analyzed bundles are valid
2: one or more analyzed bundles have issues, or the input is invalid

Repository Layout

.specify/
├── glossary.md
├── conventions/
├── project/
│   ├── tech-stack.md
│   ├── domain-map.md
│   ├── coding-rules.md
│   └── architecture-principles.md
└── templates/
    ├── commands/
    │   ├── analyze.md
    │   ├── brief.md
    │   ├── clarify.md
    │   ├── common-design.md
    │   ├── design.md
    │   ├── debug.md
    │   ├── tasks.md
    │   ├── implement.md
    │   └── reflect.md
    └── artifacts/
        ├── brief.md
        ├── common_design/
        └── design/
briefs/
designs/
├── common_design/
│   ├── api/
│   ├── data/
│   ├── module/
│   └── ui/
└── specific_design/
    └── 001-example/

This Repository's Own Structure

The package source of truth and the repository's working files are not the same thing.

src/speckit_for_projects/: CLI implementation and validation logic
src/speckit_for_projects/templates/: Jinja source templates used by sdd init
guides/: end-user documentation for operating the workflow
docs/: maintainer and implementation notes for this repository itself
examples/: sample outputs and project-standard examples
tests/: unit, integration, golden, and end-to-end coverage
.specify/: this repository's own initialized scaffold used for dogfooding
.codex/ and .myagent/: locally generated agent prompt outputs in this repository

Important detail: checked-in skills are not the source of truth. Skills are generated from the shared command templates under .specify/templates/commands/ or, if needed, directly from src/speckit_for_projects/templates/commands/*.j2.

Also note that some templates exist in src/speckit_for_projects/templates/ but are not currently installed by sdd init. In the current implementation that includes:

legacy specific-design templates such as api-design.md.j2, data-design.md.j2, and module-design.md.j2

Project-level design system templates are available through sdd init --project-design-system.

The legacy specific-design templates listed above exist in the source tree, but they are not part of the managed scaffold written by the current CLI.

Examples And Guides

Supported AI Agents

Current supported --ai values are:

agy
amp
auggie
bob
claude
codebuddy
codex
copilot
cursor-agent
gemini
generic
kilocode
kiro-cli
opencode
qodercli
qwen
roo
shai
vibe
windsurf

Alias:

kiro resolves to kiro-cli

Typical command output locations:

codex: .codex/prompts/
claude: .claude/commands/
gemini: .gemini/commands/
copilot: .github/agents/
cursor-agent: .cursor/commands/
kiro-cli: .kiro/prompts/
generic: the path passed to --ai-commands-dir

Skill output locations:

codex: .agents/skills/
most other named agents: <agent-folder>/skills/

Codex note:

.codex/prompts/*.md are saved prompts, not registered slash commands
--ai-skills adds Codex-discoverable skills under .agents/skills/

Skill implementation note:

there is no separate per-skill source tree in src/
generated SKILL.md files are wrapped from the shared command templates

Development

Recommended local checks:

uv run pytest
uv run ruff check .
uv run mypy src

Example Storybook bundles can be verified with:

cd examples/screen-centric/designs/specific_design/001-screened-application-portal/ui-storybook
npm install
npm run build-storybook

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github		.github
.specify		.specify
briefs		briefs
designs		designs
docs		docs
examples		examples
guides		guides
src/speckit_for_projects		src/speckit_for_projects
tests		tests
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SpecKit for Projects