devspec SpecLabs

ai cli developer-tools spec-driven-development workflow

Use this command to install devspec with WinGet:

winget install --id=SpecLabs.Devspec -e

devspec is a spec-driven development framework designed to manage project context, architecture, engineering rules, and work-item workflows for AI coding agents and IDE adapters. It enables teams using GitHub Copilot and other AI tools to maintain consistent workflows across projects and environments.

Key Features:

Installs and synchronizes foundation files including project context, tech stack, codebase structure, coding standards, and operational rules.
Manages work items from intake to review through structured flows for features, bugs, and security issues.
Provides recovery mechanisms from repository artifacts when chat history is unavailable.
Supports multiple AI tools including GitHub Copilot, Claude Code, Codex, Cursor, Gemini CLI, and Google Antigravity.

Audience & Benefit: Ideal for developers and engineering teams using AI coding agents. Devspec ensures that all team members and AI tools follow the same workflow and guidelines, improving collaboration and consistency across projects.

devspec

devspec is a compact, resumable spec-driven workflow for AI coding agents. Git-tracked devspec/ artifacts are the canonical project state, so planning, implementation, review, and recovery never depend on chat history.

Choose a setup route

Your situation	Use this guide
No installer, Python, package manager, or CLI	Manual copy from `main`
Python is available; one-off or persistent CLI use	Python and uvx
Windows package-manager installation	WinGet
macOS/Linux package-manager installation	Homebrew
Already installed the CLI; need init, upgrade, or profile changes	CLI lifecycle
A repository already uses devspec 0.2.x	Upgrade from devspec 0.2.x

Manual copying and CLI installation produce the same canonical devspec/ content and agent wrappers, once the manual route resets the project records listed in its guide. In either route, set the target repository's repository-state.md to new or existing. Choose one setup route; the CLI is optional.

CLI quick start

uvx devspec init --target . --profile all --repo-state existing
uvx devspec doctor --target . --profile all

Use --repo-state new for a repository with no source yet. The CLI quick start covers both routes and the first command to run.

init copies the canonical contracts, protocols, and templates plus the wrappers for the selected agent profile, generates devspec/foundation/repository-state.md from --repo-state, and seeds empty devspec/architecture/overview.md and artifact-queue.md. Those three files and devspec/constitution.md are project-owned: init and sync never overwrite them, even with --force.

Before a framework upgrade, inspect drift with devspec diff --target . and preview it with devspec sync --target . --profile all --dry-run.

Supported agent hosts

Agent host	Profile	Installed wrapper	Invoke a command
GitHub Copilot	`copilot`	`.github/prompts/` and `.github/agents/`	`/devspec.story`
OpenAI Codex	`codex`	`AGENTS.md`	Ask for `devspec.story`
Claude Code	`claude`	`.claude/skills/`	`/devspec-story`
Cursor	`cursor`	`.cursor/rules/devspec-workflow.mdc`	Ask for `devspec.story`
Gemini CLI	`gemini`	`.gemini/commands/devspec/`	`/devspec:story`
Google Antigravity	`antigravity`	`.agents/skills/`	The `devspec-story` skill

Each wrapper only points at its contract in devspec/contracts/, so every host runs the same workflow. The all profile installs every wrapper.

Choose a workflow route

Foundation route for new and existing repositories

Delivery route for quickfix and work items

Use the developer workflow guide for concrete quickfix, refinement, clarification, and change-request examples.

How to

Follow the scenario-based how-to guide to choose the right command, establish a baseline, deliver a story, work across repositories, or route a small fix safely. The beginner command examples give a first prompt for every command.

Two rules apply throughout. Confirm single-repository or multi-repository scope before every devspec.* command, unless current canonical evidence already records it. After starting a story, run the work-item commands or continue without repeating its ID: private per-worktree context resumes only the recorded next action.

Contributing and releases

Run the test suite with uv run python -m unittest discover -s tests. Release pipelines, one-time publishing setup, and the release checklist are in packaging/README.md.

License

devspec is released under the Apache License 2.0.